ai-plan

name	ai-plan
description	Turns an approved spec into a numbered task list where every task names one file, one check that fails, and how to undo it. When the spec adds anything deployable, the plan must carry a CI/CD task and an observability task; they are not optional. Trigger for "break this down", "what tasks do we need", "let's start implementing", "the scope changed, re-plan". Not for exploring the problem — use /ai-spec. Not for writing the code — say go once this is approved. Not for judging what was built — use /ai-review.
license	Apache-2.0
compatibility	needs git; an approved spec under specs/
disable-model-invocation	true

Turn the spec into tasks

What it produces

specs/NNN-slug/plan.md, beside the spec it implements.

Steps

1. Read the spec, and only the specs it names — the one it supersedes, the ones it depends on. Nothing else. A hundred specs cost the index plus the ones you were told about.
2. Write tasks small enough that each one is a commit, each one numbered and each one opening with an empty box: 1. [ ] **Title** —. For every task, four things: file (the one it touches), check (the command that fails today and passes after), rollback (how to undo it), done when (in one sentence, testable). Never write [x]. The box is filled by ai-eng spec show <id> --task <n> --tick, which runs the check and seals what it measured; an empty box means no command has run over these bytes yet, which is not the same as "not done".
3. A check is a command, never a judgement. "Looks right" is not a check. If a task's check reads "the agent decides X", say in one line why a script cannot do it — and if you cannot say why, write the script instead. That is rule 12, and it applies here first because here is where the cost is decided.
4. If the spec adds anything that gets a URL, two tasks are mandatory and named:
   • a CI/CD task: build, lint, test and security analysis on every push, deploy from the default branch, zero manual steps;
   • an observability task covering the eight signals the spec lists, each passing with a command. Without them the plan is not finished, whatever else is in it.
5. Order the tasks so that the first failing check appears as early as possible. A plan whose first six tasks cannot fail is a plan that finds out too late.
6. Say what you are not doing, and why. The deliberate omissions are the part reviewers most often need and least often get.

Done when

• Every task has a file, a check, a rollback and a "done when".
• The deployable tasks exist if the spec is deployable, and are absent if it is not.
• The person has approved it, recorded as an ADR at the spec and plan digests. That record is the gate: no code before it.

What this is not

Not an estimate, not a schedule, and not a place to redesign. If planning uncovers that the spec is wrong, stop and go back to /ai-spec. Re-planning around a wrong spec is the most expensive mistake available here.

• "A check that reads 'the agent decides X' is honest for this task" — a check is a command, never a judgement: if you cannot say why a script cannot decide it, write the script instead.