Agent Skills: Spec flow

Spec flow

Lightweight loop for controlled work, one task at a time: plan one slice, execute one task, checkpoint or close, repeat.

scripts/specctl (written specctl below) owns state. Do not edit task status or .spec/SESSION.yaml by hand. references/specctl-commands.md lists every command. references/method.md covers task quality, templates, the planning output, and the mini-interview.

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.

Modes

Orient

For status, the next task, resume, or health: run specctl status, ready, session handoff, and validate. Report the active session, the next ready task, validation issues, and the smallest next action.

Plan

For an idea, requirement, bug, or project gap that needs an executable plan. Done when the smallest useful artifact set exists and passes specctl validate, and its first task appears in specctl ready (a REQ-only plan has no ready task yet). Create tasks and requirements with specctl new task|req, then fill in the details; write an EPIC-* file by hand. Pick the smallest set:

• one clear slice: one TASK-*
• several slices: one EPIC-* plus tasks
• unclear WHY or WHAT: one REQ-* first

Run specctl init when .spec/ is missing, and check status and session before changing files. In an existing project, read the code and project instructions first, and link REQ or EPIC context only when it reduces ambiguity. Ask questions only when the slice is unclear. Show the proposed plan before writing it unless the user already authorized that scope. Build a full backlog only on request, and keep implementation code out of plan files.

Execute

For work, continue, or implement. Done when the relevant build/test/lint checks pass on what you changed, or you name each check that did not run and why. Before closing, confirm the acceptance criteria and show the scoped diff or specctl session handoff; if the task cannot finish, checkpoint it instead.

• Check specctl status and specctl session show first. Resume a matching session when the user asks to continue; ask before replacing a conflicting one.
• Pick the task from specctl ready or verify the named one with specctl show, then specctl start TASK-<id>.
• Share a short implementation plan unless that scope is already approved. Implement only this task; file follow-up tasks instead of widening scope.
• Take checks from the project instructions and the changed files; not every project has make.

Checkpoint or close

Checkpoint before stopping or switching context:

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

Close a finished task:

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

--summary and --tests are required unless the user approves --force. They record your evidence; specctl does not run or certify checks. Name the commands and results, including skip reasons such as --tests "not run: docs-only task".

Authorization

Approval covers the agreed plan and implementation scope; do not ask again at each mechanical step. Ask when scope changes, before using --force, or before clearing a conflicting 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 specctl init.
• No ready tasks: show blockers; plan new work or finish the blockers.
• Validation fails: fix the smallest artifact issue before work.
• Verification fails: fix within scope, checkpoint, or stop; do not mark done.