spec-flow

description: Use when planning, executing, checkpointing, finishing, or inspecting lightweight spec-driven work. Runs one task at a time using .spec/ markdown files and the bundled specctl helper. NOT for broad product discovery beyond a short requirement interview. name: spec-flow

Spec flow

Lightweight spec loop for controlled task-by-task work.

Loop: plan one slice → execute one task → checkpoint or close → repeat.

specctl owns state. Do not edit task status or .spec/SESSION.yaml by hand.

Read first

• references/method.md for artifact shapes, planning rules, task quality, and mini-interview guidance.
• references/specctl-commands.md for CLI commands.

State model

• .spec/tasks/TASK-*.md — executable vertical slices. Required for work.
• .spec/epics/EPIC-*.md — optional group for multi-task plans.
• .spec/reqs/REQ-*.md — optional WHY/WHAT context for ambiguous work.
• .spec/SESSION.yaml — active task, step, base commit.
• .spec/PROGRESS.md — append-only activity log.

Task states: todo, in-progress, done.

Common flows

New project:

scripts/specctl init

Then plan the first executable slice. Do not build a full backlog unless the user asks.

Existing project:

1. Inspect current code and project instructions.
2. Create the smallest task that can be verified.
3. Link optional REQ/EPIC context only when it reduces ambiguity.

Stop and resume:

scripts/specctl checkpoint --message "<where to resume>"
scripts/specctl session handoff

Iterate:

scripts/specctl ready
scripts/specctl start TASK-<id>
# implement + verify
scripts/specctl done TASK-<id> --summary "..." --tests "..."

Modes

Orient

Use when the user asks for status, next task, resume, health, or what to do next.

scripts/specctl status
scripts/specctl ready
scripts/specctl session handoff
scripts/specctl validate

Report active session, next ready task, validation issues, and the smallest next action.

Plan

Use when the user has an idea, requirement, bug, or project gap and wants an executable plan.

1. Run scripts/specctl init.
2. Check status/session before changing files.
3. Ask 3-5 questions only if the slice is unclear.
4. Optionally scan the codebase for relevant files and patterns.
5. Draft the smallest useful artifact set:
   • one clear slice → one TASK-*
   • several slices → one EPIC-* plus tasks
   • unclear WHY/WHAT → one REQ-* first
6. Show the proposed plan and ask before writing.
7. Write with scripts/specctl new task <slug> when possible, then edit details.
8. Run scripts/specctl validate and scripts/specctl ready.

Do not write implementation code in plan files.

Execute

Use when the user wants to work, continue, or implement a task.

1. Run scripts/specctl status and scripts/specctl session show.
2. If a session exists, ask whether to resume, checkpoint, clear, or stop.
3. Select with scripts/specctl ready or verify the named task with scripts/specctl show TASK-<id>.
4. Start with scripts/specctl start TASK-<id>.
5. Make a short implementation plan; ask before editing.
6. Implement only the approved task.
7. Run project-appropriate checks from project instructions and changed files.
8. Show scoped diff or scripts/specctl session handoff before close.
9. Close with scripts/specctl done ... or checkpoint with scripts/specctl checkpoint.

Checkpoint or close

Use when the user stops, switches context, or finishes.

Checkpoint:

scripts/specctl checkpoint --message "<where to resume>"

Close:

scripts/specctl done TASK-<id> \
  --summary "<what changed>" \
  --tests "<checks passed or not run: reason>" \
  --files "<changed files or none>" \
  --commits "<sha or none>"

specctl done needs --summary and --tests unless the user explicitly approves --force.

Guardrails

• One task is the execution unit.
• Checkpoint before stopping or switching.
• Keep work inside the approved task.
• File follow-up tasks instead of expanding scope.
• Verification is adaptive; do not assume every project has make.
• User approval is required before writing plan files, editing code, forcing state, or clearing another session.

Output

## Spec flow

Mode: orient | plan | execute | checkpoint | close
Task: <TASK-id or none>
Status: <ready | in-progress | checkpointed | done | blocked>
Evidence: <commands/tests/checks or skipped reason>
Next: <one command or action>

Failure handling

• No .spec/: run or offer scripts/specctl init.
• Active session conflicts: show handoff and ask before switching.
• No ready tasks: show blockers; plan new work or finish blockers.
• Validation fails: fix the smallest artifact issue before work.
• Verification fails: fix within scope, checkpoint, or stop; do not mark done.