superspecs

Workflow

SuperSpecs runs every feature through the same lifecycle: Plan → Execute → Verify → Ship, preceded by a one-time Setup phase. Each phase has a clear goal, a fixed set of skills, and a hard exit gate before the next phase can start.

01

Phase 0 — Setup

Goal: Ground every future session with a permanent stack profile.

Run once per project, and revisit when the stack changes. Define the project's tech stack through a guided questionnaire. Get concrete recommendations for specialist skills to install, ecosystem libraries per domain, and a production-readiness checklist tailored to the stack. Saves a permanent profile to the wiki that every future session can reference.

/superspecs:techstack → wiki/techstack.md (stack + recommended skills)

02

Phase 1 — Plan

Goal: Produce a spec that fits a fresh 200k-token context window.

Before any code exists, intent is captured as testable, machine-readable requirements. The 200k window constraint is deliberate: any executor (subagent, fresh session, different agent) must be able to pick up the spec and work from it without needing prior chat history. If a spec is too large to fit, it is decomposed into smaller specs.

  • /superspecs:design-import — optional, run before discuss when a DesignOS export exists
  • /superspecs:discuss → DISCUSS.md (decisions, constraints, non-goals)
  • /superspecs:spec → spec.md (SHALL requirements + GIVEN/WHEN/THEN scenarios), tasks.md, status.md
  • /superspecs:grill → GRILL.md (verdict: READY or NEEDS REVISION)

A spec that hasn't passed /superspecs:grill does not proceed to execution.

03

Phase 2 — Execute

Goal: Implement the spec in parallel using isolated subagents, with TDD enforced inside every task.

  • /superspecs:pick-spec — validates spec completeness
  • /superspecs:branch — git branch or worktree, one per spec
  • /superspecs:subagent — fresh subagent per task; TDD per task; wave dispatch with human checkpoints
  • /superspecs:code-review — spec compliance then code quality; critical findings block progress

Each subagent receives the spec, its task, and nothing else — no shared state, no reliance on context from other agents. TDD is not a separate step after subagent development: every subagent task follows RED → GREEN → REFACTOR before it is considered done.

The per-task cycle:

  1. Write a failing test — confirm it fails for the right reason (RED)
  2. Write minimal code — confirm it passes (GREEN)
  3. Refactor — clean up while tests stay green (REFACTOR)
  4. Run the full suite — no regressions
  5. Commit
  6. Code review — spec compliance first, then code quality
04

Phase 3 — Verify

Goal: Confirm the implementation matches the spec and the knowledge is preserved.

/superspecs:verify runs two sequential stages in one command:

  • Stage 1 — Check Tests: Full test suite, coverage check, every spec scenario verified by a test. No passing with skipped or pending tests.
  • Stage 2 — Wiki Import: Compile the implemented feature into the project wiki — architecture decisions, patterns, trade-offs, gotchas. Runs only if Stage 1 passes.
05

Phase 4 — Ship

Goal: Merge and close the loop.

/superspecs:ship creates the PR, writes a changelog entry, archives the phase directory, and marks the spec complete. After ship, the cycle resets: /superspecs:pick-spec for the next item.