English | 中文

Spec-driven development workflow for AI coding assistants. Your agent thinks before it codes.

AI coding agents are fast but sloppy. They skip requirements, ignore edge cases, and write code before understanding the problem. SpecPowers fixes this by enforcing a structured workflow:

exploring → proposing → specifying → designing → planning → spec-driven-development → archiving

Every line of code traces back to a spec. Nothing is built without one.

You: "Add dark mode to the app"

AI:  [exploring]  "System-auto-detect, manual toggle, or both?"
You: "Both"

AI:  [proposing]  → proposal.md    ✓ intent, scope, non-goals
AI:  [specifying] → spec.md        ✓ 2 requirements, 4 scenarios (GIVEN/WHEN/THEN)
AI:  [designing]  → design.md      ✓ CSS Variables, 3 files
AI:  [planning]   → tasks.md       ✓ 3 TDD tasks mapped to specs

You: "Step-by-Step"

AI:  ✅ Task 1 — RED → GREEN → Code Review: APPROVED → ⏸️ you commit
AI:  ✅ Task 2 — done → ⏸️ you commit
AI:  ✅ Task 3 — done
     🎉 All tasks complete. Say "Archive" to merge specs.

The agent never runs git. You review and commit after each task. If you resume a change from an existing tasks.md, choose Step-by-Step or Fast before execution begins or resumes.

For complex requests, exploring may research existing implementations or delegate bounded research, but that stays inside exploring rather than becoming a separate workflow phase.

flowchart TD
    Start([User Request]) --> Exploring[exploring<br/>Socratic dialogue]
    Exploring --> Proposing[proposing<br/>proposal.md]
    Proposing --> Specifying[specifying<br/>spec.md · GIVEN/WHEN/THEN]
    Specifying --> Designing[designing<br/>design.md]
    Designing --> Planning[planning<br/>tasks.md · TDD tasks]
    Planning --> Execution[spec-driven-development<br/>execution modes]
    Execution --> Choice{Execution Mode}
    Choice -->|Step-by-Step| Step[1 task → review → pause]
    Choice -->|Fast| Fast[all tasks → unified review]
    Step -.->|commit then continue| Step
    Step --> Done
    Fast --> Done
    Done{Done} --> Archiving[archiving<br/>merge delta specs]

Requires Node.js for language rule auto-install and selective install.

For Codex local-plugin installs, bootstrap the managed skills payload once from the cloned repo before first use:

node scripts/install.js --platform codex --profile developer

When the agent activates the using-skills skill at session start, it scans your project files and auto-installs matching language rules — e.g., .ts files trigger rules-typescript, .py triggers rules-python. No manual setup needed for language rules.

If it's the first session after install (no prior install state), the agent also runs the developer profile setup automatically.

Start a new session and say "I want to build X". The agent should begin with exploring — asking questions, not writing code.

Auto-detected from your project files. rules-common loads first, then language-specific rules layer on top.

TypeScript · Python · Go · Rust · Java · Kotlin · C++ · Swift · PHP · Perl · C# · Dart

Pre-built agent templates: planner (read-only analysis), security-reviewer (deep-dive specialists for unified review), tdd-guide (TDD coaching).

• Rules Layer — rules-common and rules-* are standards and constraints used while writing, modifying, and reviewing code. They shape decisions and review criteria; they are not separate workflow entrypoints.
• Workflow Layer — user-facing entrypoints such as requesting-code-review, receiving-code-review, and dispatching-parallel-agents. For review, requesting-code-review is the single surfaced review entrypoint.
• Role Layer — internal helper roles such as security-reviewer, planner, and tdd-guide. These are internal helper roles used behind workflow skills rather than parallel user-facing workflows.

flowchart TD
  using["using-skills"]
  rules["rules-common + rules-* (always-on rules)"]
  workflow["exploring → proposing → specifying → designing → planning → spec-driven-development → archiving"]
  task["task-internal hooks: TDD + two-stage review"]
  milestone["milestone gate: verification-loop"]
  completion["completion gate: verification-before-completion"]
  review["manual review flow: requesting-code-review"]
  roles["role-layer helpers: security-reviewer / planner / tdd-guide"]

  using --> rules
  using --> workflow
  rules -. constrain .-> workflow
  workflow --> task
  task -. every 3-4 tasks / before larger handoff .-> milestone
  milestone -. evidence for readiness .-> completion
  review --> roles
  review -. final claim still gated by .-> completion

Read it as one main workflow with attached hooks:

• using-skills decides which workflow skill to activate first.
• rules-common and rules-* stay active as standards around the workflow, not as extra phases.
• spec-driven-development contains task-internal hooks such as TDD and two-stage review.
• verification-loop is a milestone gate, not a peer stage in the main workflow.
• verification-before-completion is the final claim gate before saying work is complete or ready.
• requesting-code-review is a separate manual review flow that can call role-layer helpers without creating extra top-level workflows.

• Specs before code — define behavior, then implement
• TDD is mandatory — every task starts with a failing test
• Evidence over claims — prove it works before moving on
• Research is embedded, not a phase — investigate existing solutions inside decision-making stages instead of adding workflow branches
• You control git — the agent never commits; you review everything
• Role isolation — the AI plays a constrained role at each stage (interviewer, architect, developer…)
• Brownfield-first — built for existing codebases, works great for greenfield too

For fine-grained control (most users don't need this):

node scripts/install.js --platform claude-code --profile developer
node scripts/install.js --platform kiro-ide --add rules-typescript
node scripts/install.js --platform cursor --profile full --exclude rules-rust

Profiles: core (minimal) · developer (recommended) · security · full (everything).

Module lifecycle commands (list, doctor, repair, uninstall) are in the selective-install skill.

Issues and PRs welcome. If you're adding a new skill, use the writing-skills meta-skill — it enforces the skill template structure.

Built on ideas from OpenSpec and Superpowers

MIT