@draig/lexis-two

---

Built on OpenCode and Cursor. Benchmark harness and attribution: ponytail by DietrichGebert (MIT).

---

Excelso Open

This project is proud to be part of Excelso Open, our open-source and community-focused branch, championing collaborative technology and social impact projects. Learn more about our mission and other projects at excelso.xyz.

---

What is Lexis?

Lexis is a multi-agent ecosystem for shipping production web apps with engineering discipline, not prompt theater.

It coordinates specialized agents — planning, implementation, review, refactor, security — around one portable ruleset and a shared skills/ catalog. The default stance is skeptical: prove the feature belongs, pick the simplest stack-native solution, and write the minimum that holds under real constraints.

This package (@draig/lexis-two) publishes that ruleset, skills/, and host adapters. Named coding agents (lexis-one, etc.) are a separate Lexis ecosystem layer — some private, none in this tarball. See docs/portability.md.

See it in code: examples/ — nine before/after pairs across Next.js, Express, and FastAPI.

Ecosystem agent roles

Agent	Role	Scope
lexis-one	Primary coding agent	Implements, edits, runs bash
lexis-review	Strategic reviewer	Evaluates changes, never edits
ui-architect	UX/UI architect	Consults on design, never implements
refactor-agent	Refactor specialist	Large-scale code restructuring
security-auditor	Security analyst	Read-only, runs audit tools
design-auditor	Visual slop + tokens	Read-only except DESIGN-AUDIT.md
explorer	Codebase mapper	Read-only, fast local model

Principles

Simplicity here is method, not aesthetic minimalism.

Principle	What it means in Lexis-Two
YAGNI	Question every feature and abstraction before it exists — the ladder below is the gate
KISS	Stdlib, platform APIs, and boring one-liners beat new dependencies
DRY	One skills/ source, thin host adapters — slash commands route, they do not fork logic
SOLID	Clear module and service boundaries — no abstractions nobody asked for

Fewer tokens and fewer files are a side effect of correct, maintainable code — not the whole philosophy.

The decision ladder

Before writing any code, stop at the first rung that holds:

1. Does this need to exist at all? (YAGNI)
2. Does the standard library already do this?
3. Does a native platform feature cover it?
4. Does an already-installed dependency solve it?
5. Can this be one line?
6. Only then: write the minimum code that works.

---

Three-stage workflow

1. /discx (/discovery) — this MVP + 06-post-mvp.md; later /discx <next-slug> to scale. Scaffold: node scripts/discovery-init.js <slug>
2. /specx (/specxis) — agree proposal + tasks, implement one task at a time
3. /lexis — keep intensity lean (review / debt / security)
4. /desx — optional pass after UI work: audit visual slop, then /desx apply

Skip Discovery for clear bugs and one-line fixes. /desx is beside that loop, not a fourth SDD phase.

---

Stack

Lexis is optimized for this stack — adapt as needed for your own:

• Frontend: Next.js App Router, React, TypeScript strict
• Backend: Express.js / Fastify, Node.js, TypeScript
• Database: MongoDB (default) / PostgreSQL / SQLite
• Cache: Redis
• Styling: Tailwind CSS
• Data fetching: TanStack Query v5
• Package Manager: npm

---

Installation

One-command setup (rules-only hosts)

From your project directory:

npx @draig/lexis-two install

Non-interactive example (Cursor + OpenCode + AGENTS.md):

npx @draig/lexis-two install --host cursor,opencode,agents --scope project --yes

Hosts covered: Cursor, Windsurf, Cline, Kiro, OpenCode (opencode.json merge + slash commands), copilot-repo, and project AGENTS.md. Plugin marketplaces (claude, copilot, gemini, pi) print setup hints. See docs/setup.md. Modes: docs/modes.md.

Uninstall (removes only unchanged Lexis-Two files):

npx @draig/lexis-two install --uninstall --host cursor,opencode --scope project --yes

OpenCode (Recommended via npm)

Add the package to your project's opencode.json:

{
  "plugin": ["@draig/lexis-two"]
}

To enable the slash commands globally in any project:

mkdir -p ~/.config/opencode/commands
cp .opencode/commands/lexis*.md ~/.config/opencode/commands/
cp .opencode/commands/specx*.md ~/.config/opencode/commands/
cp .opencode/commands/disc*.md ~/.config/opencode/commands/

OpenCode (Local development / manual)

# Clone the repo
git clone https://github.com/nitdraig/lexis-two.git ~/lexis-two

Add to your opencode.json:

{
  "plugin": ["~/lexis-two/.opencode/plugins/lexis-two.mjs"],
  "instructions": ["~/lexis-two/AGENTS.md"]
}

Cursor

# Copy rules to your project or global Cursor config
cp ~/lexis-two/.cursor/rules/lexis-two.mdc .cursor/rules/lexis-two.mdc

Or globally:

cp ~/lexis-two/.cursor/rules/lexis-two.mdc ~/.cursor/rules/lexis-two.mdc

More hosts (Windsurf, Gemini CLI, pi, Copilot, Command Code): see docs/portability.md and docs/commandcode.md.

Site: lexis-two.excelso.xyz (GitHub Pages — setup guide). Command usage guide: lexis-two.excelso.xyz/guide — /discx, /specx, /lexis, and /desx.

---

Commands

Once installed, these slash commands are available in OpenCode, Gemini CLI, pi, and Command Code.

1. /discx — Discovery (alias /discovery)

Product framing before Specxis. Output: docs/discovery/<slug>/ (seven files, including 06-post-mvp.md). No product code.

• /discx <slug>
  • What it does: Asks B1–B8 in batches, fills brief / MVP / priorities / constraints / questions / map / post-MVP. Gate: continue to /specx new <slug>?
  • When to use: New product, vague feature, or scale after an MVP. For scale, use a new slug seeded from the previous 06-post-mvp.md — do not overwrite the old folder.
  • Skip: bugs, typos, hotfixes, one-file changes. Bypass later Specxis with sin discovery.

Scaffold without an LLM: node scripts/discovery-init.js <slug>

---

2. /lexis — Core Lexis Commands

Manage Lexis senior dev mode, intensity levels, and quality/security tools under a single unified command.

Subcommands in Detail:

• /lexis status (Shortcut: /lexis)

  • What it does: Reports the current active mode of the plugin (lite/full/ultra/off) and your configured default mode.
  • When to use: Use this to verify which intensity level is currently guiding your AI agent.

• /lexis <lite | full | ultra | off>

  • What it does: Dynamically switches the intensity level of the smart-lazy ruleset.
    • lite: Builds what's asked but suggests a lazier alternative in one line.
    • full (Default): Enforces the strict minimalist ladder (YAGNI, stdlib, native, one line, minimum build).
    • ultra: YAGNI extremist mode. Challenges requirements, deletes code first, and prefers one-liners.
    • off: Fully deactivates Lexis rules for the current session.
  • When to use: Use ultra when starting a refactoring or cleanup sprint; use lite when you have strict, non-negotiable specifications.

• /lexis plan (Shortcut: /lexis p)

  • What it does: Step-by-step technical plan before code: lazy ladder, plus clarify (max 3 questions), repo/docs sources, proposed vs lazy, and happy/edge/failure. One shippable slice; defer the rest.
  • When to use: Before any new feature so you agree the simplest path.

• /lexis review (Shortcut: /lexis r)

  • What it does: Analyzes your recent git changes (git diff HEAD) specifically for over-engineering, dead code, speculative features, reinvented standard libraries, or unnecessary abstractions.
  • When to use: Run this before committing or opening a Pull Request to ensure your code is as lean and maintainable as possible.

• /lexis audit (Shortcut: /lexis a)

  • What it does: Performs a comprehensive, read-only audit of your entire repository (not just a diff) to identify over-engineering, unused dependencies, and redundant boilerplate.
  • When to use: Excellent for onboarding onto a new codebase or doing a monthly code cleanup.

• /lexis debt (Shortcut: /lexis d)

  • What it does: Recursively scans the codebase for // lexis: comment tags and compiles them into a prioritized technical debt ledger, categorizing them into Immediate, Next Sprint, Backlog, and Permanent.
  • When to use: Run this to check what shortcuts were taken and when they need to be upgraded.

• /lexis security (Shortcut: /lexis s)

  • What it does: Runs a focused security audit on your stack (optimized for Node.js, Next.js, and MongoDB), checking for NoSQL injection, command injection, XSS, missing route middleware, hardcoded secrets, and unvalidated inputs.
  • When to use: Run this before any production deployment or security review.

• /lexis help (Shortcut: /lexis h)

  • What it does: Displays a quick reference card with public commands, levels, and configuration.

Bugs: smallest repro and fix (no drive-by refactors). Those habits live in plan / AGENTS — old v1.2 slash names (doubt, inc, debug, source, predict, scenario) redirect to /lexis plan. Prefer /discx over /lexis discovery. Folded skill folders remain; their standalone slash adapters are gone. Legacy /lexis-two-review (etc.) still work with a deprecation notice. Skill folders remain skills/lexis-two-*. Legacy /lexis-two-* slash names still work with a deprecation notice.

---

3. /specx — Spec-Driven Development (alias /specxis)

Manage the Specxis SDD lifecycle. Short command /specx. Same subcommands as /specxis.

Subcommands in Detail:

• /specx status (also /specxis)

  • What it does: Lists all active specifications in .specxis/active/, displaying their current status (draft/agreed/implementing/done), task completion progress (e.g., 3/5 tasks checked), and whether a review has been completed. It also shows a summary of archived specs and open debt.
  • When to use: Use this as your central dashboard to see what features are currently in development and their progress.

• /specx new <slug> (also /specxis new)

  • What it does: Creates .specxis/active/[slug]/proposal.md. Lazy check plus Discovery soft gate: vague products without docs/discovery/<slug>/01-mvp.md are pointed at /discx first (sin discovery bypasses). Cites Discovery source when present.
  • When to use: Complex feature (3+ files) or UX/backend coordination — after Discovery when the idea was vague.

• /specx plan <slug>

  • What it does: Reads your proposal.md, applies the lazy decision hierarchy, and generates spec.md (MUST/SHOULD/MAY) and tasks.md (a technical task list, max 10 tasks, with each task mapping to exactly one file or function).
  • When to use: Run this once the initial proposal is aligned to generate a structured, actionable implementation plan.

• /specx implement <slug>

  • What it does: Finds the first unchecked task in your tasks.md, implements it following the spec.md MUST requirements and AGENTS.md rules, and marks the task as completed (- [x]). It implements exactly one task per run to ensure maximum control and quality.
  • When to use: Use this to guide the AI agent step-by-step through the implementation of your feature.

• /specx review <slug>

  • What it does: Runs a read-only evaluation of the current implementation against the requirements in spec.md and the rules of AGENTS.md. It writes its findings (Severity, Location, Issue, Fix) to review.md.
  • When to use: Run this after implementing your tasks to verify that the feature is fully compliant and clean before closing.

• /specx close <slug>

  • What it does: Verifies that all tasks are completed and no Critical/High findings are open. It then moves the spec folder to .specxis/archive/[slug]/, harvests any // lexis: comments added during development, and appends them to your global .specxis/debt.md ledger.
  • When to use: Run this when your feature is fully implemented, tested, and ready to be archived.

• /specx debt

  • What it does: Recursively scans the codebase for // lexis: comments and synchronizes them with .specxis/debt.md using a highly portable Node.js script.
  • When to use: Run this to keep your technical debt ledger perfectly in sync with your codebase.

---

4. /desx — Design audit

Beside the SDD loop (not a Specxis phase). Stack-agnostic detector + optional model polish.

• /desx / /desx audit (also /desx-audit)

  • What it does: Role design-auditor. Runs scripts/desx-audit.js (no API key) and writes only DESIGN-AUDIT.md.
  • When to use: After UI generation, before a commit, or when the UI looks like generic AI slop.

• /desx apply (also /desx-apply)

  • What it does: Implementer reads the audit file, applies P0→P1→P2/P3, ticks only what it fixed, re-runs the detector.
  • When to use: After you agree the findings. Not the auditor.

More: DESX.md.

---

Modes

Switch working mode with /mode <name> in OpenCode:

Mode	Focus	Best for
build	Minimum viable implementation	Day-to-day coding
plan	Analysis before implementation	Complex features
review	Evaluate, no edits	Before committing
debug	Trace issues, no edits	Investigating bugs
docs	JSDoc, README, comments	Documentation sprints
brainstorm	Ideas and trade-offs	Architecture decisions

---

The lexis: Comment Tag

Lexis marks intentional simplifications with inline comments:

// lexis: using native <dialog> instead of modal library — no dep needed
// lexis: skipping abstraction — only used once, extract if needed in v2
// lexis: tech debt — revisit when auth module is stable

Run /lexis debt (or /lexis d) to collect and prioritize all tagged items across the codebase.

---

Complementary Repos

Repo	What it adds
ponytail	Benchmark harness and early decision-ladder patterns (MIT)
my-cursor-skills	OpenCode/Cursor skills: code review, testing, security, performance

---

Roadmap

Component Relationship

Lexis-One (private) ──extracts the best──▶ Lexis-Two (public)
     │                                           │
     │ personal configuration                    │ portable ecosystem
     │ specific prompts & flow                   │ generalized rules
     │ providers & API keys                      │ skills & commands
     │ private working style                     │ multi-host adapters
     └───────────────────────────────────────────┘
                          │
                    Lexis-Core (future)
                    public orchestrator

---

v0.1 — Foundation ✅

Core portable ecosystem.

• AGENTS.md — ecosystem rules and minimalist decision hierarchy
• OpenCode plugin (lexis-two.mjs) with lite / full / ultra modes
• Commands: lexis-two-review, lexis-two-audit, lexis-two-debt, lexis-two-plan, lexis-two-security
• Portable skills for all hosts
• Adapters: Cursor, Windsurf, Cline, Kiro, Gemini CLI, OpenCode; Copilot repo rules (.github/copilot-instructions.md)
• MIT license with ponytail attribution

---

v0.2 — Developer Experience

Make it easy to adopt Lexis in any new project.

• AGENTS.template.md — project-level AGENTS.md template with commented sections (stack, design tokens, glossary, conventions)
• docs/portability.md — hosts, commands, skills, install paths
• docs/site.md — GitHub Pages + lexis-two.excelso.xyz
• docs/setup.md — installer guide (OpenCode merge + global commands)
• docs/modes.md — lite / full / ultra / off and default resolution
• npx @draig/lexis-two install — setup script (rules, OpenCode, uninstall, hints)
• README links to examples/ before/after catalog
• examples/nextjs/01-modal-library — gold-standard before/after (B1)
• examples/nextjs/ + examples/express/ — six before/after cases (B2)
• examples/fastapi/ — three before/after cases (B3)

---

v0.3 — Multi-host Maturity

Full, verified support across all major hosts.

• Claude Code adapter (.claude-plugin/ + hooks/) — scaffold in repo
• GitHub Copilot IDE plugin (.github/plugin/) — scaffold in repo
• Codex adapter (.codex-plugin/plugin.json + hooks/hooks.json)
• pi adapter (pi-extension/)
• Verified skills working in Gemini CLI, Codex, and pi
• examples/ — nine before/after cases across Next.js, Express, FastAPI (B1–B3)
• CONTRIBUTING.md — how to add a new adapter or skill

---

v0.4 — Lexis-Core (Public Orchestrator)

The public orchestrator — a generalized pattern extracted from the private Lexis-One ecosystem.

• Public documentation of the multi-agent role architecture (without exposing private config)
• Guide: how to build a multi-agent ecosystem using Lexis-Two as the base
• lexis-core as a reference agent in the docs — prompts and patterns, not private implementation
• Guide: "How to build your own private Lexis-One on top of Lexis-Two"
• opencode.json template with the full agent ecosystem (no keys, placeholders only)

---

v0.5 — Specxis (Spec-Driven Development) ✅

Lightweight SDD layer for complex features — inspired by OpenSpec and Spec Kit, built for the Lexis philosophy.

• .specxis/ folder convention documented
• Commands: specxis-new, specxis-plan, specxis-implement, specxis-review, specxis-close, specxis-debt
• Skills: specxis, specxis-plan, specxis-review, specxis-close
• scripts/specxis-init.js — creates .specxis/ structure in any project
• templates/specxis/ — proposal, spec, and tasks templates
• docs/specxis.md — when to use SDD vs direct implementation
• Integration guide for Lexis-One private config

---

v1.3 — Discovery (product framing)

MVP cut and map before Specxis. Output: docs/discovery/<slug>/.

• templates/discovery/ + DISCOVERY.md / docs/discovery.md
• scripts/discovery-init.js + tests
• Slash commands /discx (/discovery) + skill + installer copy
• Specxis soft gate + proposal “Discovery source” section

---

v1.3.x — Desx (design audit)

• /desx audit/apply + scripts/desx-audit.js + DESIGN-AUDIT.md

---

v1.0 — Community & Growth

When the ecosystem is stable and has adoption.

• GitHub Actions CI: validates that adapters stay in sync when AGENTS.md changes
• Strict semantic versioning + automated changelog
• Community-verified skill registry
• Migration guides between versions

---

Future — Lexis Platform

The commercial evolution. Defined once v1.0 has traction.

• Web app to configure your Lexis ecosystem visually
• Skill and adapter marketplace
• Lexis-One as a Service — your private configuration in the cloud
• Public Lexis-Core API for integration into any workflow

Contributing

Contributions welcome. Read CONTRIBUTING.md for architecture, host/skill/command checklists, and the PR contract. AGENTS.md applies to this repo too.

Focus areas: stack-specific shortcuts for other tech stacks, new examples, additional hosts, installer improvements.

---

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md.

Original ponytail concept by DietrichGebert. Lexis ecosystem by @nitdraig.