spec-flow · diff

git:20260716.29b4d22 to git:20260908.c37b890

5 added, 5 removed. Audit A to A.

---

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. NOT for generic implementation planning that does not read

or write `.spec/` files.

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:

```bash

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:

```bash

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

scripts/specctl session handoff

```

Iterate:

```bash

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.

```bash

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.

+ 6. Show the proposed plan; obtain approval if the user has not already authorized that scope.

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.

+ 2. Resume an existing matching session when the user asks to continue. Ask before replacing a conflicting session.

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.

+ 5. Make a short implementation plan; obtain approval if that implementation scope is not already approved.

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:

```bash

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

```

Close:

```bash

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`.

+ `specctl done` needs `--summary` and `--tests` unless the user explicitly approves `--force`. These fields record the caller's evidence; the helper does not execute or certify checks. Name commands and results honestly, including skip reasons, and satisfy project gates before closing.

## 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.

+ - Authorization persists for the agreed plan and implementation scope; do not repeat approval at each mechanical step. Ask when scope changes or before forcing state or clearing a conflicting session.

## Output

```markdown

## 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.