SpecAI

🌐 Languages: English | Español

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.

Based on Superpowers by Jesse Vincent, adapted for OpenCode Go with per-role model configuration. Senior anti-overengineering philosophy inspired by Ponytail / Mimocode by pavnxet.

specai 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:

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.

A 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.

• 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.
• 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.
• 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.
• 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.
• i18n. README in English and Spanish. Skill bodies in English with Spanish comments where relevant. None of the 5 alternatives ships multi-lingual docs.

• Ceremony. Rigid gates add overhead. /specai-mini exists for trivial work; for one-line edits, just edit directly.
• Setup. The seven core subagents defined in scripts/agent-roster.json must be registered with the harness.

For a SpecAI flow, even a mechanical change uses the same acceptance-contract shape. A direct one-line edit outside a SpecAI plan is not represented as a feature task; when it enters the flow, it gets exact task and verification contracts just like a larger change.

graph TB
    S[Socratic Definition] --> G[grill-me]
    G --> W[write-prd]
    W --> A[PRD approval]
    A --> P[Writing Plans: six docs]
    P --> Q{Implement or backlog?}
    Q -->|implement| B[Feature branch]
    Q -->|backlog| BL[Backlog, no branch]
    B --> C[Fresh implementer per task]
    C --> R[Build/test → local review → commit → document]
    R --> D[Full Test Suite]
    D --> SC[Spec compliance: global invariants]
    SC --> V[Verifier]
    V --> UA[Gate UA: User Acceptance]
    UA --> F[Finishing Branch]
    F --> U[User Tests]
    U -->|issues found| I[Iteration]
    I --> C

    P --> P1[prd.md + spec.md + designs.md]
    P --> P2[plan.md + tasks.md + verify.md]
    C --> C1[Subagent-Driven]
    C --> C2[Executing Plans]
    I --> I1[Update _plan.md]
    I --> I2[Update _tasks.md]

    SL[Senior Ladder<br/>YAGNI → stdlib → native → dep → simple → min] -.->|filters| C
    SL -.->|filters| I

    style SL fill:#f9f,stroke:#333,stroke-dasharray: 5 5

Every subagent evaluates the best approach top-down, stopping at the first rung that holds:

graph TD
    Q1{1. Does this need<br/>to exist?} -->|no| SKIP[Skip it. YAGNI.]
    Q1 -->|yes| Q2{2. Stdlib does it?}
    Q2 -->|yes| USE1[Use stdlib]
    Q2 -->|no| Q3{3. Native platform<br/>feature?}
    Q3 -->|yes| USE2[Use native]
    Q3 -->|no| Q4{4. Already-installed<br/>dependency?}
    Q4 -->|yes| USE3[Use existing dep]
    Q4 -->|no| Q5{5. Can it be simple<br/>and clean?}
    Q5 -->|yes| USE4[Most readable solution]
    Q5 -->|no| MIN[6. Minimum that works]

Mark deliberate simplifications with // td: <ceiling>, <upgrade path>.

Never simplify: validation at trust boundaries, error handling preventing data loss, security, accessibility, anything explicitly requested.

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.

Iron rule: NO code is written without an approved design.

Brainstorming is the heart of specai. It uses a Socratic pattern in groups of 3 questions to refine ideas before touching code.

Always in groups of 3, never 1 by 1. Each question ≤ 25 tokens. This cuts conversation turns by ⅔.

1. Explore project context (files, docs, recent commits)
2. Offer visual companion (if topic requires it)
3. Clarifying questions (Socratic pattern, groups of 3)
4. Propose 2-3 approaches with trade-offs and recommendation
5. Present design in sections (incremental approval)
6. Write spec to docs/specai/<spec-name>/<spec-name>-designs.md including Edge Case Analysis (boundaries, adjacency, empty, encoding, ordering, precision, idempotency, concurrency) and System Constraints (Must-NOTs).
7. Ambiguity scan
8. Spec self-review
9. User reviews the written spec
10. Transition to writing-plans

Every 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.

Creates the feature folder docs/specai/<spec-name>/ with all implementation documents:

Each task specifies: exact target and location, current value, requested change, assertion, files to touch, commands with expected output, and tests to write. Each verification criterion specifies Criterion type, Invariant, Verification seam, and a Given / When / Then scenario.

Full and Mini modes use the same six feature artifacts: prd.md, spec.md, designs.md, plan.md, tasks.md, and verify.md. Mini creates compact versions with shorter ceremony only; exact task instructions, global Given / When / Then criteria, criterion metadata, evidence, the corrective loop, branch timing, and Gate UA remain required.

When the plan introduces any new external dependency, it undergoes a security and legitimacy check:

1. The planner audits the package reputation (age, downloads, repository health) to detect typosquatting or low reputation.
2. The package is listed under the ## Dependency & Package Validation section in the plan.
3. An explicit checkpoint:human-verify task is added in <spec-name>-tasks.md before the package installation command, ensuring the user approves it before execution.

The execution engine. Dispatches specialized agents with minimal context:

graph TD
    C[Controller] --> I[implementer]
    C --> BF[build-fixer]
    C --> V[verifier]
    C --> D[documenter]
    C --> CM[specai-command]

    I -->|DONE| C
    BF -->|FIXED| C
    V -->|PASS/FAIL| C
    D -->|OK| C
    CM -->|output| C

1. Dispatch a fresh implementer session with ONLY its task, relevant spec section, research facts, and scheduling metadata. Never inherit the parent conversation.
2. Implementer reports: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED.
3. Build and test verification via specai-command (the implementer may self-verify).
4. If it fails: dispatch build-fixer with the error and relevant code only.
5. Dispatch code-reviewer before commit. It must return both a quality verdict and Compliance verdict: PASS for every criterion mapped to the task.
6. Fix CRITICAL/IMPORTANT or compliance failures, rerun verification, and review again.
7. Commit only after build/tests and both review verdicts pass.
8. Documenter updates the living documents after task transitions, errors, commits, and verifier outcomes.
9. After all tasks: full suite → spec-compliance-reviewer (including cross-task/global invariants) → verifier.
10. Session metadata remains ephemeral; recovery is reconstructed from *-tasks.md and the Execution Log of *-plan.md. TodoWrite is only the session mirror.

Before 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.

If a task only modifies tests and src/ hasn't changed, the build is skipped (saves 30-50% tokens).

The verifier compares the final result against the acceptance criteria in _verify.md:

GOAL_COMPLETE → Gate UA (user acceptance)
PARTIAL/FAIL/UNVERIFIED → Generate exact corrective tasks → re-dispatch implementer → verify again

_verify.md is a goal contract, not just a test checklist. It maps every criterion (C1, C2, ...) to task IDs, exact commands, expected output, and fresh evidence. The goal cannot pass while any task is open, any criterion is partial, or any corrective task remains unresolved.

Every criterion uses the same Given / When / Then scenario, including mechanical changes. The Then field must contain the exact observable literal or assertion; qualitative wording such as “larger” or “more readable” is not accepted.

Tasks prove local changes; criteria prove the complete goal. A criterion that spans screens, components, modules, or tasks must be typed ARCHITECTURE or INTEGRATION, state its complete Invariant, and name a Verification seam. The verifier reads that seam and checks the relationship independently. For example, “statistics screens are equal” means the two entrypoints resolve to the same shared screen component, game-specific data enters through the declared adapter, and no duplicate layout exists. Completed subtasks alone are not evidence for that invariant.

After 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.

User tests → finds issues → specai-iteration →
  Update _plan.md (iteration log entry) +
  Update _tasks.md (corrective tasks) →
  Re-enter execution (implement → build → document → verify) →
  Full test suite → Verifier → Finishing

Rules:

• Do NOT restart the full flow (socratic → grill-me → write-prd) for small corrections
• Do NOT create a new feature directory — append corrective tasks to existing docs
• Always run the full test suite after corrective tasks
• Commit rules apply during iteration too
• Exit only when the user confirms the implementation works as expected

Related skills: specai-iteration, specai-documentation, specai-subagent-driven-development

Four options presented to the user:

specai applies a senior decision ladder before writing any code. Every subagent evaluates the best approach top-down, stopping at the first rung that holds:

Change with /specai-mode lite|medium|ultra|off or edit ~/.config/specai/config.json (seniorMode).

• No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes
• No boilerplate, no scaffolding "for later" — later can scaffold for itself
• Deletion over addition. Boring over clever
• Fewest files possible. Shortest working diff wins
• Mark deliberate simplifications with // td: <ceiling>, <upgrade path>
• Output: code first, then at most three short lines of explanation

Configurable via commitMode in ~/.config/specai/config.json (default: auto).

When on a feature branch (not main, master, develop, dev):

When NOT on a feature branch:

• STOP. Do NOT commit.
• Direct commits on main, master, develop, or dev are forbidden.
• 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.
• Wait for the user's choice before proceeding.

specai uses the seven core subagents defined in scripts/agent-roster.json, with configurable models per role:

Critical rules:

• No agent executes commands directly (except implementer verifying its own work) — everything delegates to specai-command
• No agent writes documentation directly — everything delegates to specai-documentation
• Each implementer receives ONLY its task: no plan, no other tasks, no execution log
• 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.

# In conversation: use the specai-configure-model tool
# In terminal:
bash scripts/configure-agents.sh implementer "anthropic/claude-sonnet-4-20250514"
# Interactive:
bash scripts/configure-agents.sh --interactive

Add specai to the plugin array in your opencode.json:

{
  "plugin": ["specai@git+https://github.com/ArceApps/specai.git"]
}

The plugin auto-registers:

• 7 subagents (@implementer, @build-fixer, @code-reviewer, @verifier, @spec-compliance-reviewer, @specai-command, @specai-documentation)
• 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)
• 1 built-in tool (specai-configure-model)
• All 39 skills under skills/

Why so many skills for so few commands? The number of skills and the number of slash commands are decoupled on purpose. Each skill is a tightly-scoped procedure — the smallest unit of behavior a single subagent can invoke with the exact context it needs. Skills are split by responsibility (interview, design, plan, implement, review, commit, document, verify, finish, iterate…), not by command. A single /specai-plan ends up loading several skills in sequence, but the agent that runs any one step of it sees only the procedure that step actually needs. Fewer, larger skills would force every subagent to carry instructions for work it never does, which is the exact prompt- rot we are trying to avoid. 13 slash commands stay a fixed, memorable surface; the skill set is allowed to grow as the methodology gains finer distinctions.

After adding the plugin, run:

bash scripts/setup-agents.sh          # Injects agents and commands into OpenCode config

Use the unified specai CLI manager to link, install, update, diagnose, and configure across detected harnesses:

./specai link           # Live development linking for detected harnesses (Antigravity, Codex, OpenCode, Hermes, Universal)
./specai install        # Public installation into detected harnesses
./specai update         # Update from remote and refresh detected harnesses
./specai doctor         # Diagnose health of all harnesses, skills, and subagents
./specai config         # Open interactive configuration TUI

Each 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/.

• Factory Droid: Factory Droid automatically picks up project instructions from AGENTS.md and respects the specai workflow when the harness loads.
• 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.
• Hermes (Nous Research): skills are symlinked into ~/.hermes/skills/<name> (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.

The same seven-role roster is projected through each native harness:

All handoffs use the shared scripts/agent-harness-contract.json: 900-second maximum runtime, 15-second polling and 30-second heartbeat. Run the read-only diagnostic before dispatching:

bash scripts/specai-harness-doctor.sh --json

If a native capability is missing, SpecAI blocks with an actionable diagnosis; it never silently executes the work inline.

After pulling new changes, refresh everything:

./specai update

This updates from remote and refreshes all detected harnesses in one step.

Run without arguments for the interactive TUI menu, or with a command:

Example:

./specai                    # Open interactive TUI menu
./specai link               # Link live development across detected harnesses
./specai install            # Install into detected harnesses
./specai doctor             # Run comprehensive health diagnostic
./specai config             # Configure models interactively

Change any subagent's model at runtime from inside a conversation:

Parameters:

• agent: one of the seven core agents in scripts/agent-roster.json
• model: Full model ID (e.g., minimax/MiniMax-M3, anthropic/claude-sonnet-4-20250514)

Updates ~/.config/specai/config.json and applies the change immediately.

configure-agents.sh subcommands:

During implementation, the six feature documents stay synchronized by the specai-documentation agent:

Never pass all six files to an agent at once — only the bounded section it needs.

To avoid wasting tokens on large file reads for small updates:

1. Controller prepares the event, exact target path, relevant section, and requested change
2. Documenter receives the bounded handoff and reads/writes only the named documentation section
3. Controller records the returned status — it never applies a second documentation edit

This keeps living documents updated without burning tokens on context.

After EVERY completed task:

• _tasks.md — tick completed steps
• _plan.md — append execution log entry

After EVERY commit:

• _plan.md — append commit log entry
• _tasks.md — ensure all completed steps are ticked

When errors occur:

• _plan.md — append error log entry with: what happened, root cause, fix applied, lessons learned
• _tasks.md — add corrective tasks if needed

During iteration (user feedback):

• _plan.md — append iteration log entry
• _tasks.md — add corrective tasks under ## Iteration Tasks

These are living logbooks — they must always reflect reality.

When using TDD inside subagent-driven development, each implementer reports:

The verifier checks this table against the acceptance criteria.

graph TD
    start[User gives instruction] --> skill{Does any skill apply?}
    skill -->|Yes, even 1%| invoke[Invoke Skill tool]
    skill -->|Definitely not| respond[Respond]
    invoke --> checklist{Has checklist?}
    checklist -->|Yes| todos[Create TodoWrite]
    checklist -->|No| follow[Follow skill exactly]
    todos --> follow
    follow --> respond

Red Flags (thoughts that mean STOP and check):

MIT — see LICENSE.

• Superpowers by Jesse Vincent and Prime Radiant — the original skills-based methodology for AI coding agents that inspired specai's composable skill architecture
• Ponytail / Mimocode by pavnxet — the senior anti-overengineering philosophy (decision ladder, minimalism, YAGNI) that inspires specai-senior-philosophy and specai-anti-bloat
• specai by ArceApps