spec steering workflow

Spec Steering Workflow

Use this skill when work is long, interruptible, multi-phase, or needs recovery in a new session.

Start or recommend a spec when any of these are true:

• The task is likely to take more than 20 minutes.
• The task has more than one deliverable.
• The task needs staged execution.
• The task is likely to be interrupted.
• The task needs research plus execution.
• The task must survive across sessions.
• The user asks for plan first, then execution.

This skill manages execution state with workspace files:

• specs/active//
• specs/archive//
• steering/

Default workflow:

1. Read steering/workflow.md and steering/preferences.md.
2. If resuming, read handoff.md, then tasks.md, then meta.json.
3. Work only on the current batch.
4. After each batch, or every 20-30 minutes, write a checkpoint.
5. Before stopping, update handoff.md and meta.json.

Valid checkpoint types are only:

• done
• blocked
• failed

Do not treat "working on it", "continue", or "in progress" as valid progress reports.

Use {baseDir}/scripts/specctl.py for these operations:

• init --title "" --kind
• checkpoint --type done|blocked|failed --batch --next ""
• status
• resume
• validate
• archive
• set-status --status ready|review|completed [--phase ] [--next ""]
• doctor

Read references only as needed:

• {baseDir}/references/workflow-rules.md for trigger and lifecycle rules
• {baseDir}/references/checkpoint-rules.md for checkpoint requirements
• {baseDir}/references/recovery-rules.md for resume order and stale-state rules
• {baseDir}/references/integration-rules.md for coexistence with other skills
• {baseDir}/references/template-contracts.md for file contracts and required fields

Use templates from {baseDir}/assets/templates/. Keep the skill lean: detailed rules belong in references/, file bodies belong in assets/templates/, and only execution state belongs in workspace specs/ and steering/.