{
"markdown": "# SpecAI\n\n> **π Languages:** [English](README.md) | [EspaΓ±ol](README.es.md)\n\n**A complete software development methodology for AI coding agents.** specai turns code agents into disciplined engineers through composable _skills_ that guide every development phase: from idea to merge.\n\nBased on [Superpowers](https://github.com/obra/superpowers) by [Jesse Vincent](https://blog.fsck.com), adapted for OpenCode Go with per-role model configuration. Senior anti-overengineering philosophy inspired by [Ponytail / Mimocode](https://github.com/pavnxet/Mimocode-ponytail) by [pavnxet](https://github.com/pavnxet).\n\n## Philosophy\n\nspecai is not a plugin or a tool: it's a **methodology**. It tells the agent _how_ to think, _when_ to ask, and _when_ to act. Its pillars:\n\n| Principle | Description |\n|-----------|-------------|\n| **Skills > Prompts** | Composable skills the agent invokes per task |\n| **Brainstorming first** | No code is ever written without an approved design including Edge Case Taxonomy and must-NOT constraints |\n| **Living documents** | The six feature artifacts stay synchronized with execution and verification evidence |\n| **Specialized agents** | Each task gets a fresh implementer session and bounded role-specific context |\n| **Verify before claiming** | Don't say \"it works\" until the command runs |\n| **Atomic commits** | Each task = one commit with passing build and tests |\n| **Senior First** | Every agent applies the decision ladder before writing code: YAGNI β stdlib β native β existing dep β simple β minimum |\n| **Dependency Validation** | Validate packages before planning and enforce human checkpoints before installation tasks |\n| **Iterate with user** | User tests β documented feedback β corrective tasks β re-enter execution without restarting |\n\n---\n\n## How we compare\n\n> **Honest positioning.** specai enters a market with strong, well-trodden alternatives. This page summarizes when each is the right tool. Detailed comparison: see [docs/COMPARISON.md](docs/COMPARISON.md).\n\n| When you want | Use |\n| --- | --- |\n| **Skill library with TDD enforcement and a vast ecosystem (249k β )** | [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent |\n| **Fluid spec-driven development with delta specs and versioned domain specs (59k β )** | [OpenSpec](https://github.com/Fission-AI/OpenSpec) by Fission AI |\n| **Official first-party GitHub SDD toolkit with constitution/specify/plan/tasks/implement (119k β )** | [GitHub Spec Kit](https://github.com/github/spec-kit) |\n| **Multi-domain agile modules with 12+ specialist agents and risk-based test strategy (50k β )** | [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) |\n| **MCP-based task management with multi-AI provider support (28k β )** | [Task Master AI](https://github.com/eyaltoledano/claude-task-master) |\n| **Rigid subagent execution with enforced anti-overengineering, tiered model selection, and a User-Acceptance Gate** | **specai** |\n\n### specai in one sentence\nA methodology-first framework that turns coding agents into disciplined engineers through **rigid per-task cycles**, **multi-role subagents with cheap-model routing**, and **living documents that survive the feature's lifetime**.\n\n### Where specai shines\n- **Cost efficiency.** Models are configurable per role; mechanical document and command work can use the cheapest viable model while implementation and judgment use stronger models. Context isolation, bounded handoffs, and incremental document updates prevent input-token multiplication.\n- **Anti-overengineering.** A 6-rung decision ladder (YAGNI β stdlib β native β existing dep β simple β minimum) enforced through `// td:` markers and `/specai-review` / `/specai-audit`. None of the 5 alternatives has YAGNI as an executable skill.\n- **User-Acceptance Gate.** Implementation does NOT equal plan complete. The user must explicitly accept before the flow proceeds to merge. OpenSpec enforces the same via `opsx:archive`; Superpowers, BMad, Spec Kit, and Task Master do not.\n- **Living documents per feature.** `prd.md` + `spec.md` + `designs.md` + `plan.md` + `tasks.md` + `verify.md` per spec, updated by `specai-documentation`. Superpowers plans, GSD context, OpenSpec change-folders are similar but rarely auto-update.\n- **i18n.** README in English and Spanish. Skill bodies in English with Spanish comments where relevant. None of the 5 alternatives ships multi-lingual docs.\n\n### Trade-offs & limitations\n- **Ceremony.** Rigid gates add overhead. `/specai-mini` exists for trivial work; for one-line edits, just edit directly.\n- **Setup.** The seven core subagents defined in `scripts/agent-roster.json` must be registered with the harness.\n\nFor a SpecAI flow, even a mechanical change uses the same acceptance-contract\nshape. A direct one-line edit outside a SpecAI plan is not represented as a\nfeature task; when it enters the flow, it gets exact task and verification\ncontracts just like a larger change.\n\n---\n\n## Complete Workflow\n\n```mermaid\ngraph TB\n S[Socratic Definition] --> G[grill-me]\n G --> W[write-prd]\n W --> A[PRD approval]\n A --> P[Writing Plans: six docs]\n P --> Q{Implement or backlog?}\n Q -->|implement| B[Feature branch]\n Q -->|backlog| BL[Backlog, no branch]\n B --> C[Fresh implementer per task]\n C --> R[Build/test β local review β commit β document]\n R --> D[Full Test Suite]\n D --> SC[Spec compliance: global invariants]\n SC --> V[Verifier]\n V --> UA[Gate UA: User Acceptance]\n UA --> F[Finishing Branch]\n F --> U[User Tests]\n U -->|issues found| I[Iteration]\n I --> C\n\n P --> P1[prd.md + spec.md + designs.md]\n P --> P2[plan.md + tasks.md + verify.md]\n C --> C1[Subagent-Driven]\n C --> C2[Executing Plans]\n I --> I1[Update _plan.md]\n I --> I2[Update _tasks.md]\n\n SL[Senior Ladder YAGNI β stdlib β native β dep β simple β min] -.->|filters| C\n SL -.->|filters| I\n\n style SL fill:#f9f,stroke:#333,stroke-dasharray: 5 5\n```\n\n### Senior Decision Ladder\n\nEvery subagent evaluates the best approach top-down, stopping at the first rung that holds:\n\n```mermaid\ngraph TD\n Q1{1. Does this need to exist?} -->|no| SKIP[Skip it. YAGNI.]\n Q1 -->|yes| Q2{2. Stdlib does it?}\n Q2 -->|yes| USE1[Use stdlib]\n Q2 -->|no| Q3{3. Native platform feature?}\n Q3 -->|yes| USE2[Use native]\n Q3 -->|no| Q4{4. Already-installed dependency?}\n Q4 -->|yes| USE3[Use existing dep]\n Q4 -->|no| Q5{5. Can it be simple and clean?}\n Q5 -->|yes| USE4[Most readable solution]\n Q5 -->|no| MIN[6. Minimum that works]\n```\n\nMark deliberate simplifications with `// td: , `.\n\n**Never simplify:** validation at trust boundaries, error handling preventing data loss, security, accessibility, anything explicitly requested.\n\n---\n\n### 0. β Socratic Definition β Before Anything Else\n\n> **Mandatory:** Before design or code, the `grill-me` skill drives a relentless one-question-at-a-time interview that maps the design tree. The `write-prd` skill turns the resolved tree into a formal PRD that the user must approve before any plan is written. The implementer must NOT make design decisions or assumptions.\n\n### 1. π§ Brainstorming β The Most Important Phase\n\n> **Iron rule:** NO code is written without an approved design.\n\nBrainstorming is the heart of specai. It uses a **Socratic pattern** in groups of 3 questions to refine ideas before touching code.\n\n#### The 3 Socratic Questions\n\n| Type | Purpose | Example |\n|------|---------|---------|\n| **Theoretical** | Extract general domain principles | _\"What makes a calendar view useful for managing notes?\"_ |\n| **Frame** | Define constraints and boundaries | _\"What UX principles apply (grouping, navigation, visual indicators)?\"_ |\n| **Application** | Make specific decisions concrete | _\"In your app, do you prefer monthly, weekly, or both views?\"_ |\n\n**Always in groups of 3**, never 1 by 1. Each question β€ 25 tokens. This cuts conversation turns by β .\n\n#### Brainstorming Checklist\n\n1. Explore project context (files, docs, recent commits)\n2. Offer visual companion (if topic requires it)\n3. Clarifying questions (Socratic pattern, groups of 3)\n4. Propose 2-3 approaches with trade-offs and recommendation\n5. Present design in sections (incremental approval)\n6. Write spec to `docs/specai//-designs.md` including **Edge Case Analysis** (boundaries, adjacency, empty, encoding, ordering, precision, idempotency, concurrency) and **System Constraints (Must-NOTs)**.\n7. Ambiguity scan\n8. Spec self-review\n9. User reviews the written spec\n10. Transition to writing-plans\n\n#### Anti-Pattern: \"This Is Too Simple\"\n\nEvery project goes through the socratic + grill-me + write-prd chain. A TODO list, a single-function utility, a config change β all of them. \"Simple\" projects are where unexamined assumptions cause the most wasted work.\n\n---\n\n### 2. π Writing Plans\n\nCreates the feature folder `docs/specai//` with all implementation documents:\n\n| File | Purpose |\n|------|---------|\n| `-prd.md` | Approved product requirements: problem, stories, decisions, constraints, edge cases, and out of scope |\n| `-spec.md` | Functional contract and delta against the affected project specification |\n| `-designs.md` | Populated from grill-me + write-prd artifacts, containing architecture & specs |\n| `-plan.md` | Implementation plan, goal, tech stack, and execution log |\n| `-tasks.md` | Atomic tasks of 2-5 minutes each (checklist format) |\n| `-verify.md` | Global acceptance criteria and final verification template |\n\nEach task specifies: exact target and location, current value, requested change,\nassertion, files to touch, commands with expected output, and tests to write.\nEach verification criterion specifies `Criterion type`, `Invariant`,\n`Verification seam`, and a `Given / When / Then` scenario.\n\nFull and Mini modes use the same six feature artifacts: `prd.md`, `spec.md`,\n`designs.md`, `plan.md`, `tasks.md`, and `verify.md`. Mini creates compact\nversions with shorter ceremony only; exact task instructions, global\n`Given / When / Then` criteria, criterion metadata, evidence, the corrective\nloop, branch timing, and Gate UA remain required.\n\n#### Dependency Validation Gate\n\nWhen the plan introduces any new external dependency, it undergoes a security and legitimacy check:\n1. The planner audits the package reputation (age, downloads, repository health) to detect typosquatting or low reputation.\n2. The package is listed under the `## Dependency & Package Validation` section in the plan.\n3. An explicit `checkpoint:human-verify` task is added in `-tasks.md` before the package installation command, ensuring the user approves it before execution.\n\n---\n\n### 3. βοΈ Subagent-Driven Development\n\nThe execution engine. Dispatches specialized agents with **minimal context**:\n\n```mermaid\ngraph TD\n C[Controller] --> I[implementer]\n C --> BF[build-fixer]\n C --> V[verifier]\n C --> D[documenter]\n C --> CM[specai-command]\n\n I -->|DONE| C\n BF -->|FIXED| C\n V -->|PASS/FAIL| C\n D -->|OK| C\n CM -->|output| C\n```\n\n#### Per-Task Cycle\n\n1. **Dispatch a fresh implementer session** with ONLY its task, relevant spec section, research facts, and scheduling metadata. Never inherit the parent conversation.\n2. Implementer reports: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.\n3. **Build and test verification** via `specai-command` (the implementer may self-verify).\n4. If it fails: dispatch **build-fixer** with the error and relevant code only.\n5. Dispatch **code-reviewer** before commit. It must return both a quality verdict and `Compliance verdict: PASS` for every criterion mapped to the task.\n6. Fix CRITICAL/IMPORTANT or compliance failures, rerun verification, and review again.\n7. **Commit** only after build/tests and both review verdicts pass.\n8. **Documenter** updates the living documents after task transitions, errors, commits, and verifier outcomes.\n9. After all tasks: full suite β `spec-compliance-reviewer` (including cross-task/global invariants) β `verifier`.\n10. Session metadata remains ephemeral; recovery is reconstructed from `*-tasks.md` and the `Execution Log` of `*-plan.md`. `TodoWrite` is only the session mirror.\n\nBefore implementing each task, record `TASK_STARTED` in the plan log with `timestamp`, `branch`, `git_hash`, `task_id`, and context. A new session restores every `in_progress` task; without active tasks it selects the first eligible `pending` task, and blocks on inconsistencies. Human approval and review checkpoints remain decision gates, not session persistence.\n\n#### Smart Caching\n\nIf a task only modifies tests and `src/` hasn't changed, the build is skipped (saves 30-50% tokens).\n\n---\n\n### 4. β Verification\n\nThe **verifier** compares the final result against the acceptance criteria in `_verify.md`:\n\n```\nGOAL_COMPLETE β Gate UA (user acceptance)\nPARTIAL/FAIL/UNVERIFIED β Generate exact corrective tasks β re-dispatch implementer β verify again\n```\n\n`_verify.md` is a goal contract, not just a test checklist. It maps every\ncriterion (`C1`, `C2`, ...) to task IDs, exact commands, expected output, and\nfresh evidence. The goal cannot pass while any task is open, any criterion is\npartial, or any corrective task remains unresolved.\n\nEvery criterion uses the same `Given / When / Then` scenario, including\nmechanical changes. The `Then` field must contain the exact observable literal\nor assertion; qualitative wording such as βlargerβ or βmore readableβ is not\naccepted.\n\nTasks prove local changes; criteria prove the complete goal. A criterion that\nspans screens, components, modules, or tasks must be typed `ARCHITECTURE` or\n`INTEGRATION`, state its complete `Invariant`, and name a `Verification seam`.\nThe verifier reads that seam and checks the relationship independently. For\nexample, βstatistics screens are equalβ means the two entrypoints resolve to\nthe same shared screen component, game-specific data enters through the\ndeclared adapter, and no duplicate layout exists. Completed subtasks alone are\nnot evidence for that invariant.\n\n---\n\n### 5. π Iteration β User Feedback Loop\n\nAfter verification passes and the user tests the implementation manually, if issues are found, the iteration loop documents feedback and re-enters the execution flow **without restarting** from grill-me.\n\n```\nUser tests β finds issues β specai-iteration β\n Update _plan.md (iteration log entry) +\n Update _tasks.md (corrective tasks) β\n Re-enter execution (implement β build β document β verify) β\n Full test suite β Verifier β Finishing\n```\n\n**Rules:**\n- Do NOT restart the full flow (socratic β grill-me β write-prd) for small corrections\n- Do NOT create a new feature directory β append corrective tasks to existing docs\n- Always run the full test suite after corrective tasks\n- Commit rules apply during iteration too\n- Exit only when the user confirms the implementation works as expected\n\n**Related skills:** `specai-iteration`, `specai-documentation`, `specai-subagent-driven-development`\n\n---\n\n### 6. π Finishing a Development Branch\n\nFour options presented to the user:\n\n| Option | Merge locally | Push & PR | Keep worktree | Delete branch |\n|--------|---------------|-----------|---------------|---------------|\n| 1. Merge locally | β | β | β | β |\n| 2. Push + PR | β | β | β | β |\n| 3. Keep as-is | β | β | β | β |\n| 4. Discard | β | β | β | β (force) |\n\n---\n\n## Senior Philosophy\n\nspecai applies a **senior decision ladder** before writing any code. Every subagent evaluates the best approach top-down, stopping at the first rung that holds:\n\n| Rung | Question | If yes |\n|------|----------|--------|\n| 1 | Does this need to exist? | Skip it (YAGNI) |\n| 2 | Stdlib does it? | Use stdlib |\n| 3 | Native platform feature covers it? | Use native (e.g., `` over flatpickr) |\n| 4 | Already-installed dependency solves it? | Use it, never add a new dep for what a few lines can do |\n| 5 | Can it be simple and clean? | Most readable solution (sometimes 3 clear lines > 1 cryptic line) |\n| 6 | Only then | The minimum code that works |\n\n### Intensity Levels\n\n| Level | Behavior |\n|-------|----------|\n| **off** | specai normal, no changes |\n| **lite** | Build what's asked + suggest lazier alternative in one line |\n| **medium** | Full ladder enforced, minimalism active (**default**) |\n| **ultra** | YAGNI extremist, question the task itself before implementing |\n\nChange with `/specai-mode lite|medium|ultra|off` or edit `~/.config/specai/config.json` (`seniorMode`).\n\n### Minimalism Rules\n\n- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes\n- No boilerplate, no scaffolding \"for later\" β later can scaffold for itself\n- Deletion over addition. Boring over clever\n- Fewest files possible. Shortest working diff wins\n- Mark deliberate simplifications with `// td: , `\n- Output: code first, then at most three short lines of explanation\n\n### Anti-Bloat Review\n\n| Command | What it does |\n|---------|--------------|\n| `/specai-review` | Review current diff for over-engineering (delete/stdlib/native/yagni/shrink). End with `net: -N lines possible.` |\n| `/specai-audit` | Audit entire repo for bloat, ranked by impact. End with `net: -N lines, -M deps possible.` |\n| `/specai-audit-plan` | Full-project audit (bloat + architecture) β interactive triage β specai-plan. |\n\n---\n\n## Commit Rules\n\nConfigurable via `commitMode` in `~/.config/specai/config.json` (default: `auto`).\n\n**When on a feature branch** (not `main`, `master`, `develop`, `dev`):\n\n| Mode | Behavior |\n|------|----------|\n| **auto** | Commit AUTOMATICALLY without asking. Announce and continue. |\n| **confirm** | STOP after each task and ask: \"Ready to commit? [Y/n]\" |\n| **manual** | Never commit automatically. Announce \"Changes ready.\" |\n\n**When NOT on a feature branch:**\n- STOP. Do NOT commit.\n- Direct commits on `main`, `master`, `develop`, or `dev` are forbidden.\n- The only valid continuation is to create the feature branch after the explicit implementation choice, or keep the work uncommitted while that choice is clarified.\n- Wait for the user's choice before proceeding.\n\n---\n\n## Complete Skills\n\n| Skill | Purpose | Type |\n|-------|---------|------|\n| **agent-models** | Configure AI model per subagent role | Flexible |\n| **anti-bloat** | Three sub-skills: review (diff), audit (repo-wide), debt (ledger of `// td:`) | Flexible |\n| **antigravity-bridge** | Use when Antigravity's plan mode conflicts with specai flow β guards against parallel plan creation | Rigid |\n| **backlog** | Reads `.specai/backlog.json` to show and select pending plans by number | Flexible |\n| **bootstrap** | Skill invocation rules and startup β how to find and use skills | Rigid |\n| **grill-me** | Socratic one-question-at-a-time interview that maps the design tree | Rigid |\n| **write-prd** | Generates the formal PRD from the resolved design tree | Rigid |\n| **checkpoints** | Documentary recovery and ephemeral session metadata; no persistent checkpoint | Flexible |\n| **code-review** | Automated code review with per-task `code-reviewer` and end-of-flow `spec-compliance-reviewer` | Rigid |\n| **command** | Command execution delegation β all commands go through `specai-command` | Rigid |\n| **dispatching-parallel-agents** | Concurrent independent failure investigation | Flexible |\n| **documentation** | Living documents synchronization β the six feature artifacts, README, and related docs | Rigid |\n| **domain-modeling** | Builds glossary (`CONTEXT.md`) and ADRs to establish shared project language | Rigid |\n| **executing-plans** | Batch execution with documentary recovery for long implementations | Flexible |\n| **finishing-a-development-branch** | Merge/PR/discard with cleanup | Rigid |\n| **iteration** | User feedback loop: document issues β corrective tasks β re-enter execution | Rigid |\n| **judgment-day** | Adversarial dual-blind pre-PR review β two judges, only confirmed issues fixed | Flexible |\n| **living-documents** | Keep specs, design, plan and tasks synchronized during implementation | Flexible |\n| **receiving-code-review** | Respond to feedback with technical rigor, not performative agreement | Flexible |\n| **requesting-code-review** | Pre-review checklist before requesting feedback | Flexible |\n| **senior-philosophy** | Anti-overengineering decision ladder (6 rungs), intensity levels, minimalism | Rigid |\n| **socratic-clarifier** | Resolve ambiguities in specs via hyper-concise socratic questions | Flexible |\n| **subagent-driven-development** | Execution with role-specialized agents, each with minimal context | Rigid |\n| **systematic-debugging** | 4 phases: root cause β pattern β hypothesis β fix | Rigid |\n| **test-driven-development** | RED-GREEN-REFACTOR cycle with triangulation | Rigid |\n| **using-git-worktrees** | Parallel workspace isolation via git worktrees | Flexible |\n| **verification-before-completion** | Never claim without running the command β evidence before assertions | Rigid |\n| **writing-plans** | Creates the six feature artifacts with atomic tasks of 2-5 min each | Rigid |\n| **writing-skills** | TDD applied to creating and verifying new skills | Rigid |\n\n---\n\n## Agents and Models\n\nspecai uses the **seven core subagents** defined in `scripts/agent-roster.json`, with configurable models per role:\n\n| Agent | Role | Default model |\n|-------|------|---------------|\n| `implementer` | Implements ONE atomic task with minimal context | `minimax/MiniMax-M3` |\n| `build-fixer` | Resolves compilation errors β minimal diff fix | Configured in roster/config |\n| `verifier` | Compares implementation against global acceptance criteria | Configured in roster/config |\n| `code-reviewer` | Reviews quality and task compliance before each commit | Configured in roster/config |\n| `spec-compliance-reviewer` | Reviews the full implementation, cross-task consistency, and global invariants | Configured in roster/config |\n| `specai-command` | Executes commands (build, test, git). No other agent runs commands directly | Configured in roster/config |\n| `specai-documentation` | Creates and updates all documentation. No other agent writes docs directly | Configured in roster/config |\n\n**Critical rules:**\n- No agent executes commands directly (except `implementer` verifying its own work) β everything delegates to `specai-command`\n- No agent writes documentation directly β everything delegates to `specai-documentation`\n- Each `implementer` receives ONLY its task: no plan, no other tasks, no execution log\n- **Two review levels**: the named `code-reviewer` checks quality and local task compliance before each commit; the named `spec-compliance-reviewer` checks the complete implementation and global invariants before the verifier.\n\n### Changing Models\n\n```bash\n# In conversation: use the specai-configure-model tool\n# In terminal:\nbash scripts/configure-agents.sh implementer \"anthropic/claude-sonnet-4-20250514\"\n# Interactive:\nbash scripts/configure-agents.sh --interactive\n```\n\n---\n\n## Installation\n\n### OpenCode (Recommended)\n\nAdd specai to the `plugin` array in your `opencode.json`:\n\n```json\n{\n \"plugin\": [\"specai@git+https://github.com/ArceApps/specai.git\"]\n}\n```\n\nThe plugin auto-registers:\n- **7 subagents** (`@implementer`, `@build-fixer`, `@code-reviewer`, `@verifier`, `@spec-compliance-reviewer`, `@specai-command`, `@specai-documentation`)\n- **13 slash commands** (`/specai-plan`, `/specai-mini`, `/specai-explore`, `/specai-verify`, `/specai-review`, `/specai-iterate`, `/specai-mode`, `/specai-audit`, `/specai-audit-plan`, `/specai-backlog`, `/specai-init`, `/specai-finish`, `/specai-config`)\n- **1 built-in tool** (`specai-configure-model`)\n- **All 39 skills** under `skills/`\n\n> **Why so many skills for so few commands?** The number of skills and the\n> number of slash commands are decoupled on purpose. Each skill is a\n> tightly-scoped procedure β the smallest unit of behavior a single\n> subagent can invoke with the exact context it needs. Skills are split\n> by responsibility (interview, design, plan, implement, review,\n> commit, document, verify, finish, iterateβ¦), not by command. A single\n> `/specai-plan` ends up loading several skills in sequence, but the\n> agent that runs any one step of it sees only the procedure that step\n> actually needs. Fewer, larger skills would force every subagent to\n> carry instructions for work it never does, which is the exact prompt-\n> rot we are trying to avoid. 13 slash commands stay a fixed,\n> memorable surface; the skill set is allowed to grow as the\n> methodology gains finer distinctions.\n\nAfter adding the plugin, run:\n\n```bash\nbash scripts/setup-agents.sh # Injects agents and commands into OpenCode config\n```\n\n### Antigravity / Codex / OpenCode / Hermes / Universal (Unified CLI)\n\nUse the unified `specai` CLI manager to link, install, update, diagnose, and configure across detected harnesses:\n\n```bash\n./specai link # Live development linking for detected harnesses (Antigravity, Codex, OpenCode, Hermes, Universal)\n./specai install # Public installation into detected harnesses\n./specai update # Update from remote and refresh detected harnesses\n./specai doctor # Diagnose health of all harnesses, skills, and subagents\n./specai config # Open interactive configuration TUI\n```\n\nEach harness has its own configuration (e.g., `.antigravity-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.droid-plugin/`). Antigravity discovers the seven native subagents under `.antigravity-plugin/agents/` and dispatches them with `invoke_subagent`. Hermes is the one exception β there is no `.hermes-plugin/` because Hermes discovers skills by reading individual `SKILL.md` files under `$HERMES_HOME/skills/`.\n\n- **Factory Droid**: Factory Droid automatically picks up project instructions from `AGENTS.md` and respects the specai workflow when the harness loads.\n- **GitHub Copilot CLI**: Leverages `additionalContext` in the `sessionStart` hook (detected via the `COPILOT_CLI` environment variable) to inject the full specai bootstrap at session start.\n- **Hermes (Nous Research)**: skills are symlinked into `~/.hermes/skills/` (one per skill). Run `hermes skills list | grep specai` to verify. Hermes does not consume `commands.json` or native subagent definitions; its scope is the skill projection.\n\n### Native subagent harness contract\n\nThe same seven-role roster is projected through each native harness:\n\n| Harness | Native dispatch | Required capability |\n|---------|-----------------|---------------------|\n| OpenCode | `delegate` | seven roles registered as `mode: subagent` |\n| Codex | `spawn_agent` β `wait_agent` β `close_agent` | `[features] multi_agent = true` |\n| Antigravity | `invoke_subagent` | seven Markdown agents with `subagent: true` |\n\nAll handoffs use the shared `scripts/agent-harness-contract.json`: 900-second\nmaximum runtime, 15-second polling and 30-second heartbeat. Run the read-only\ndiagnostic before dispatching:\n\n```bash\nbash scripts/specai-harness-doctor.sh --json\n```\n\nIf a native capability is missing, SpecAI blocks with an actionable diagnosis;\nit never silently executes the work inline.\n\n### Post-Clone Update\n\nAfter pulling new changes, refresh everything:\n\n```bash\n./specai update\n```\n\nThis updates from remote and refreshes all detected harnesses in one step.\n\n---\n\n## Usage\n\n### Slash Commands (inside OpenCode)\n\n| Command | What it does |\n|---------|-------------|\n| `/specai-plan` | Execute the full SpecAI flow (socratic β grill-me β write-prd β plan β per-task cycle β verifier β user-acceptance β finishing). |\n| `/specai-mini` | Execute Mini mode: socratic β compact six artifacts β implementation/backlog choice β branch only if implement β implement β verify. For small features and bug fixes. |\n| `/specai-explore` | Explore codebase interactively β no artifacts, no commitment. |\n| `/specai-verify` | Verify implementation against acceptance criteria. |\n| `/specai-review` | Review current diff for over-engineering (delete/stdlib/native/yagni/shrink). |\n| `/specai-iterate` | User feedback loop β document issues, add corrective tasks, re-enter execution. |\n| `/specai-mode` | Set senior philosophy intensity: `off`, `lite`, `medium`, or `ultra`. |\n| `/specai-audit` | Audit entire repo for bloat, ranked by impact. |\n| `/specai-audit-plan` | Full-project audit (bloat + architecture) β interactive triage β specai-plan. |\n| `/specai-backlog` | Show pending plans from `.specai/backlog.json`. Select by number to execute. |\n| `/specai-init` | Initialize `docs/specai/` directories, verify config, ensure agents are set up. |\n| `/specai-finish` | Finish an accepted development branch by choosing merge, PR, keep, or discard. |\n| `/specai-config` | Show or change agent models, language, and commit mode interactively. |\n\n### CLI Commands (`./specai `)\n\nRun without arguments for the **interactive TUI menu**, or with a command:\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `link` | `--link` | Live development linking for detected harnesses (Antigravity, Codex, OpenCode, Hermes, Universal) |\n| `install` | `--install`, `-i` | Public installation into detected harnesses |\n| `update` | `--update`, `-u` | Update from remote and refresh detected harnesses |\n| `doctor` | `--doctor` | Diagnose health of all harnesses, skills, and subagents |\n| `config` | `--config` | Open interactive configuration TUI |\n| `unlink` | `--unlink` | Unlink and clean SpecAI from detected harnesses |\n| `help` | `--help`, `-h` | Show usage help |\n\n**Example:**\n```bash\n./specai # Open interactive TUI menu\n./specai link # Link live development across detected harnesses\n./specai install # Install into detected harnesses\n./specai doctor # Run comprehensive health diagnostic\n./specai config # Configure models interactively\n```\n\n### Built-in Tool: `specai-configure-model`\n\nChange any subagent's model at runtime from inside a conversation:\n\n**Parameters:**\n- `agent`: one of the seven core agents in `scripts/agent-roster.json`\n- `model`: Full model ID (e.g., `minimax/MiniMax-M3`, `anthropic/claude-sonnet-4-20250514`)\n\nUpdates `~/.config/specai/config.json` and applies the change immediately.\n\n### Scripts (`bash scripts/