Spec Driven Development

Spec-Driven Development

Use this skill as the source of truth for running SDD with ae sdd commands. Load it before proposal, bug, or vibe work so change-set resolution and command flow are consistent.

Core Rules

• Use CLI commands for state progression whenever possible.
• Never advance phases automatically from any workflow command.
• Phase advancement is user-driven via ae-sdd-next only.
• If the user approves work, suggest ae-sdd-next instead of running phase progression commands.
• Do not use custom init scaffolding; initialize with ae sdd init.
• Keep one task in_progress at a time in full lane.
• Keep notes and pending current so work can resume in a new chat.

Lane Selection

• full: New capabilities, non-trivial behavior changes, architecture work.
• vibe: Exploration and prototyping that should still be tracked.
• bug: Defect fixes against intended or specified behavior.

If a bug request is actually a behavior change, switch to full.

Command Quick Start

1. Resolve active change set (or create one):

ae sdd init <name> --lane <full|vibe|bug>

1. Check status before doing work:

ae sdd status [name]

1. Move to the right phase only through ae-sdd-next:

ae-sdd-next [name]

Full Command Reference

Change Set and Phase Commands

Task Commands (Full Lane)

Notes and Pending Commands

Phase Flows

Full lane:

proposal -> specs -> discovery -> tasks -> plan -> implement -> reconcile -> finish

Vibe lane:

context -> plan -> implement -> [reconcile -> finish]

Bug lane:

triage -> plan -> implement -> [reconcile -> finish]

For vibe and bug lanes, reconcile and finish are optional unless specs must be updated.

Implement-Phase Rules (Full Lane)

• Start implementation tasks with ae sdd task start.
• Keep task order in tasks.toml; order is execution priority.
• Complete work using ae sdd task complete or ae sdd task complete --next.
• ae sdd phase next from implement is guarded:
  • blocked if any task is currently in_progress
  • loops back to plan when tasks remain incomplete
  • advances beyond implement only when all tasks are complete

Phase Transition Guardrails

• Never auto-transition phases inside ae-sdd-proposal, ae-sdd-specs, ae-sdd-tasks, ae-sdd-plan, ae-sdd-implement, ae-sdd-reconcile, ae-sdd-vibe, ae-sdd-bug, or other workflow commands.
• Only ae-sdd-next performs phase progression during normal workflow.
• ae-sdd-next must verify phase artifacts before running ae sdd phase complete --next.
• If artifacts are missing, stop and instruct the user how to produce them.
• ae sdd phase set <phase> is reserved for explicit user-directed corrections.

Artifact Expectations

• changes/<name>/state.toml: lane, phase, notes, pending
• changes/<name>/tasks.toml: ordered tasks and status (full lane)
• changes/<name>/proposal.md: proposal (full lane)
• changes/<name>/context.md: exploratory context (vibe/bug as needed)
• changes/<name>/specs/**/*.md: specs
• changes/<name>/plans/*.md: implementation plans

Session Playbook

At the start of any SDD command session:

1. Run ae sdd status [name].
2. Confirm lane and phase.
3. For full lane, inspect tasks with ae sdd task list and ae sdd task current.
4. Execute the phase-appropriate command.
5. Update notes and pending items before ending session.

Quality Gates

• Use one active change set per thread of work.
• Do not manually invent state structure in state.toml.
• Keep pending list strictly unresolved items.
• Keep notes concise and resume-oriented.
• In full lane, do not leave multiple tasks in_progress.