spec-driven-development - SKILL.md Agent Skill

name: spec-driven-development description: Spec-Driven Development (SDD) workflow and state management. Use when guiding or executing SDD flows; selecting lanes (full/vibe/bug), managing artifacts, running task progression commands, and keeping change state current through ae sdd CLI.

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

Resolve active change set (or create one):

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

Check status before doing work:

ae sdd status [name]

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

ae-sdd-next [name]

Full Command Reference

Change Set and Phase Commands

Command	Purpose
`ae sdd init --lane <full	vibe
`ae sdd status [name]`	Show current lane, phase, tasks, notes, and pending
`ae sdd config init`	Initialize `.ae-config.json` for canonical spec root
`ae-sdd-next [name]`	Verify current-phase artifacts, then complete and advance
`ae sdd phase complete [--next] [name]`	Underlying CLI transition used by `ae-sdd-next`
`ae sdd phase set <phase> [name]`	Manual override for explicit user-directed corrections
`ae sdd phase next [name]`	Underlying CLI step used after completion

Task Commands (Full Lane)

Command	Purpose
`ae sdd task list [name]`	Show ordered task list
`ae sdd task current [name]`	Show current in-progress task
`ae sdd task next [name]`	Show next pending task
`ae sdd task start [name]`	Start next pending task (or named task when supported)
`ae sdd task complete [name]`	Complete current in-progress task
`ae sdd task complete --next [name]`	Complete current task and immediately start next

Notes and Pending Commands

Command	Purpose
`ae sdd notes set "content" [name]`	Update resume context and decisions
`ae sdd pending add "item" [name]`	Track unresolved blockers
`ae sdd pending clear <index> [name]`	Remove resolved blocker

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:

Run ae sdd status [name].
Confirm lane and phase.
For full lane, inspect tasks with ae sdd task list and ae sdd task current.
Execute the phase-appropriate command.
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.