SKILL.md
---
name: plan
description: One file that holds the whole job, so any helper can pick it up cold and know what's done, what's open, and what to do next.
---
# Plan
You keep plans for me. A plan is for work too big for one sitting: it spans several sessions, several helpers (people or agents), or both. You produce and maintain a manifest for it. The manifest is the single source of truth. Not memory notes, not chat summaries, not side documents. The manifest.
## Core principles
**Readable top-down by a helper with zero context.** The manifest must be simpler than anyone reading it. A helper with no prior context reads the plan top to bottom and knows exactly what happened, what's open, and what to do. If understanding the outcome requires cross-referencing other documents, the plan is broken.
**Self-contained.** Each item carries its own sub-plan inline: brief, decisions, forks, findings, notes. No separate brief files. The plan folder holds output artifacts (specs, schemas, reports). The plan's *narrative* lives in the manifest.
**Scope-boxed hand-offs.** A helper reads the item they're working on, not the whole plan. The item's sub-plan has everything they need. Handing off work is a pointer to an item plus its acceptance criteria, not a retelling of the plan.
**Adaptive.** Plans change mid-run. When reality forces a fork, record it inline in the item where it happened: what changed, why, which later items are affected. The plan absorbs its own changes.
## Where plans live
```
<plans-dir>/<plan-name>/
00-<plan-name>-manifest.md
00-run-state.md
01-site-audit.md
03-contact-form-spec.md
07-launch-runbook.md
```
- Each plan gets its own folder, named with a short lowercase hyphenated slug.
- The manifest is always `00-<plan-name>-manifest.md`.
- The run-state is always `00-run-state.md` (see below).
- Output artifacts are numbered by the item that produced them: `{item-number}-{descriptive-name}.md`. Gaps are expected; not every item produces a file.
- **No side briefs.** Hand-off briefs, decision records and fork stories live inline in the item's sub-plan. The folder holds output artifacts only.
- Artifacts stay in the plan folder until the plan closes. At close, file them to their permanent homes.
If I haven't told you where `<plans-dir>` is, ask once, then use it every time.
## The run-state
The manifest says what the work is and where each item stands. The run-state says what happened while running it. Keep them apart: the manifest is rewritten as status changes; the run-state only grows.
```markdown
# <plan-name> — run state
NEXT-CHECK: {date and time, with timezone, of the next status report — or "none" when idle}
## Log
- {YYYY-MM-DD HH:MM} {What happened: what was started, handed off, verified, corrected, or decided, and by whom. Quote the decision-maker's words where they rule.}
```
- **Append-only, newest last.** Never edit a past line. If a line turns out wrong, a new line says so.
- **Timestamps come from a clock,** read before you write the line. Never from memory or estimate.
- **NEXT-CHECK is updated every time you report.** If the time passes with no report, the run has gone silent and that is the first thing to fix.
- **Approved but not yet applied belongs here,** not in the manifest. The run-state is built to be superseded; the manifest states what is in force.
- **Verify before you log a completion.** Check the artifact on disk (file, commit, count) rather than relaying what a helper said it did.
## Commands
- `/plan new {slug}` — Create a new manifest from a source document or briefing.
- `/plan show {slug}` — Show current state: summary table plus blocked items.
- `/plan update {slug}` — Update items: mark complete, add notes, change status, reassign.
- `/plan review {slug}` — Full status review with dependency analysis and critical path.
- `/plan extract {slug}` — Turn a complete or near-complete manifest into a reusable runbook.
- `/plan list` — List all active manifests.
With no subcommand: `show` if a manifest exists, `new` if I'm describing work.
## Phase 1: Plan (`/plan new`)
### Input
Accept any of:
- A source document (spec, brief, proposal)
- A spoken or typed briefing from me
- An existing checklist or outline
### Breaking the work down
1. **Atomic items.** Each item can be finished in one working session by one helper. If it can't, split it.
2. **Dependencies explicit.** If item 12 needs item 8, say so. Use item numbers.
3. **Acceptance criteria.** Every item has a one-line definition of done. Not "add rate limiting" but "rate limiting at 10 requests/second, burst 20, returns 429, checked with a real request."
4. **Owner assignment.** Default owner is `orchestrator` (whoever is coordinating the plan hands it off). I can assign directly. Valid owners: any named person or agent on the work, `me`, `orchestrator`, or `sub-agent`.
5. **Sequencing.** Items are numbered. Groups are labeled. Dependencies make the execution graph.
6. **Each item carries an inline sub-plan.** See Item sub-plans below.
### On creation
1. Write the manifest and an empty run-state to the plan folder.
2. Show me the summary table for review.
3. Wait for my approval before anyone starts work.
## Manifest format
Structured markdown with YAML frontmatter.
```yaml
---
project: website-launch
source: <path-to-source-document>
created: 2026-04-01T09:50:00-05:00
created_by: orchestrator
status: active # draft | active | complete | archived
items_total: 12
items_done: 0
items_blocked: 0
---
```
Right after the frontmatter, a summary table generated from the items below it:
```markdown
| # | Item | Owner | Status | Depends | Done |
|---|------|-------|--------|---------|------|
| 1 | HTTPS certificate | orchestrator | ✅ done | — | 2026-03-31 |
| 2 | Security headers | orchestrator | ✅ done | 1 | 2026-03-31 |
| 3 | Contact form sends to inbox | sub-agent | 🔶 blocked | 2 | — |
| 4 | Mail account credentials | me | ⬜ pending | — | — |
```
Status symbols:
- `⬜ pending` — not started
- `🔵 active` — in progress by its owner
- `✅ done` — complete, acceptance criteria met
- `🔶 blocked` — can't proceed; reason and blocker required
- `⏭ deferred` — postponed on purpose; reason required
- `🪦 tombstoned` — removed from scope; never deleted or renumbered; reason required
Groups are labels for readability, not hierarchy. Dependencies cross groups freely.
Dependency notation: `—` none · `3` needs item 3 · `3, 7` needs items 3 and 7 · `3*` soft (can start in parallel, needs item 3 before it finishes).
## Item sub-plans
Every item carries its own sub-plan inline. It is the complete record of what was planned, what changed, and what happened. A helper reading only that item's block has everything needed.
**Every status change gets a stamped note:** `[YYYY-MM-DD HH:MM who] {status symbol} what was done or why the status changed`. No status change without one.
A simple item that lands in one pass needs only the header fields and Notes:
```markdown
## Item 1: HTTPS certificate
- **Group:** Infrastructure
- **Owner:** orchestrator
- **Status:** ✅ done
- **Depends:** —
- **Acceptance:** Certificate installed, site serves on HTTPS, HTTP redirects to HTTPS, auto-renewal on
- **Notes:**
- [2026-03-31 20:15 orchestrator] ✅ Already live. Spec assumed a different web server; spec updated to the as-built setup.
```
A full item grows these sections during the run. All are optional at creation:
```markdown
## Item 3: Contact form sends to inbox
- **Group:** Code — Forms
- **Owner:** sub-agent
- **Status:** ✅ done
- **Depends:** 2
- **Acceptance:** Form submission arrives in the shared inbox within a minute; spam field rejects bots; checked with three real submissions
### Brief
What the helper needs to know, and only for THIS item.
Point at sources rather than copying them: "Read §2.1 of `03-contact-form-spec.md`."
A pointer plus the difference, not a restatement.
### Decisions
Decisions made during the run. Each stamped, each final.
- [2026-04-08 09:16 me] File uploads out of scope. Item 9 tombstoned.
### Forks
Where reality left the plan: what changed, why, and what it does to later items.
- [2026-04-08 14:10 orchestrator] Brief assumed the site stores sessions in cookies; it uses a database. Adapted the form handler to read the session from the database. No downstream impact.
### Findings
Things found during the run that don't block this item but matter later.
- [2026-04-08 10:14 sub-agent] Upload folder permissions too open. Deferred to Item 11.
### Notes
- [2026-04-08 14:20 orchestrator] 🔵 Handed off. Scope: this item's Brief plus §2.1 of the spec.
- [2026-04-08 14:37 sub-agent] ✅ Complete. Commit `db02b8d`. 3/3 test submissions received.
- [2026-04-08 14:38 orchestrator] ✅ Checked against acceptance. Counts match. Findings non-blocking.
```
Blocked and tombstoned items say why, in the header and in a stamped note:
```markdown
## Item 4: Mail account credentials
- **Group:** Accounts
- **Owner:** me
- **Status:** 🔶 blocked
- **Depends:** —
- **Blocked by:** Needs the account holder present to set up two-factor
- **Acceptance:** Form's sending account exists, credentials stored in the secrets manager, not in the repo
### Notes
- [2026-03-31 22:00 orchestrator] 🔶 Blocked: needs me present for two-factor setup.
```
### Sub-plan rules
1. **The brief is a scope box, not a document.** Point to what the helper needs to read. Don't restate it.
2. **Decisions are stamped and final.** Don't edit one. If it changes, append a superseding decision.
3. **Forks track the change and its blast radius.** What changed, why, which later items are affected. If none, say so.
4. **Findings point forward.** They don't block the current item. They inform later items or post-plan cleanup.
5. **Notes accumulate, never delete.** The note trail is the audit trail.
6. **The sub-plan replaces side briefs.** Don't create separate hand-off files. The Brief section is the hand-off.
## When the plan has to change
1. **Record the fork in the item where it was found.** Use its Forks section.
2. **Update affected later items right away.** Add to their sub-plans: `[Fork from Item N] — what this changes here.`
3. **Update the summary table in the same edit** if items are added, tombstoned or re-scoped.
4. **Never delete or renumber items.** Tombstone with 🪦 and a reason. Stable numbering keeps the record honest.
5. **Reconcile the counters on every edit.** The frontmatter counts are a cache. The per-item `- **Status:**` lines are the truth: count each symbol and check the sum equals `items_total`.
## Phase 2: Check (`/plan update`)
Anyone working an item updates the manifest directly:
- Status: `pending` → `active` → `done` / `blocked` / `deferred`
- A stamped note with time, who, and what
### Update rules
1. **Current state is overwritten; history is append-only.** Status changes replace the old status. Notes accumulate.
2. **Blocked needs a reason and a blocker.** "Blocked" with no explanation isn't valid.
3. **Done needs a completion note.** Even one line: what was done, where the output lives.
4. **Only the orchestrator changes dependencies or acceptance criteria.** Everyone else updates status and notes.
### Status reports
Always show:
- Counts: ✅ done / 🔶 blocked / 🔵 active / ⬜ pending / ⏭ deferred
- Critical path: what's blocking the most later items
- Next actionable: items whose dependencies are all met
## Phase 3: Extract (`/plan extract`)
When a plan is complete or nearly so, turn the annotated manifest into a reusable runbook:
1. **Sequence from what actually happened.** The order the work really ran in, not the original numbering.
2. **Notes become procedures.** Completion notes expand into step-by-step instructions.
3. **Blocked items become known issues,** with the fix if one was found.
4. **Write it to the plan folder:** `<plan-name>/<plan-name>-runbook.md`.
5. **If the work will repeat,** add an automation skeleton (a YAML or script outline of the steps) beside it, and file it wherever your repeatable procedures live when the plan closes.
Before writing the runbook, check:
- Every done item has a completion note
- Every blocked item has a resolution or is marked as a known issue
- No item is marked done while one of its dependencies isn't
- The sequence you derived matches the dependency graph
## Rules for build work
For any item that touches code, infrastructure or live services.
### Version control is mandatory
- Anything under active development has a repository with a committed baseline before any change.
- Every change is committed with a message that names the plan item: `[plan-name #3] what changed`.
- No work on live systems without a commit to roll back to.
- If the repository doesn't exist yet, creating it and committing the baseline is the first item.
### The plan is the record
- Items are checked off only when complete, with date, time, who, and a one-line note of what was actually done.
- Updating the plan is part of the work, not something that happens later.
- If the work drifts from the design, record it as "as-built." That's normal; real work turns up better ideas. The as-built must meet or beat the original acceptance criteria, or it gets reworked.
- If new work shows up that isn't in the plan, add an item before doing it.
### No testing theatre
- Tests exist to find out whether the thing works. A failing test is information, not a problem.
- "Tested" means through the real path the live system uses. Calling one service directly, crafted inputs, or isolated checks don't count as testing the whole path.
- If the tooling to test the real path doesn't exist yet, building it is the actual blocker.
- Design tests to give real diagnostics. Designing around a bad reading is worse than a clean failure.
### Staging and live
- Build and check changes locally or on a staging copy first.
- Deploy to live only after review, with a plan item reference.
- If live breaks: roll back to the last good commit, fix locally, redeploy.
- No patching live systems while debugging. If you're debugging on live, you're already off-trail.
### Who does what
- **Mechanical work** (rewrites, migrations, file moves, config changes, scripted checks — anything with unambiguous acceptance criteria) goes to your fastest, cheapest capable helper, with clear and generous instructions that point at the item.
- **Judgment work** (security review, architecture, verification that means evaluating rather than executing) goes to your strongest reasoner. Its time is expensive; don't spend it producing output no one will read.
- **The test:** if I won't read the output and the acceptance criteria are mechanical, it's mechanical work. If I need to review it, or it weighs several concerns at once, it's judgment work.
### Helpers and sub-agents
- Don't hand infrastructure or build-and-deploy work to sub-agents until that path has been verified end to end.
- Sub-agent work is reviewed by the orchestrator before its status flips to done. I see code before it reaches live systems.
- A hand-off is a pointer: "Do Item N. Read its Brief and Acceptance. Report back in its Notes." Not a retelling of the plan.
- A helper's report of completion is checked against the item's acceptance criteria, and against the artifact itself, before status changes to done.
### Session discipline
- When a debugging session goes off-trail: stop. Commit what's known. Update the plan. Start a clean session.
- Not "one more thing." Stop.
- Never reset or compress context mid-debug. Commit state to the plan and to version control first.
- If you can't describe what you just changed and why in one line per change, you've lost the trail.
## Constraints
1. **One manifest per project.** No splitting across files. If a project is too big for one manifest, it's several projects.
2. **Output artifacts live in the plan folder until close.** Narrative (briefs, decisions, forks) lives inline in the manifest.
3. **Dense and scannable.** Status fields, timestamps, names. Sub-plans carry enough narrative to stand alone, and "enough" means what a zero-context helper needs, not a wall of prose.
4. **I approve the plan before work begins.** No one starts from an unapproved manifest.
5. **Scope-boxed reads.** A helper on Item N reads Item N's sub-plan. Not the whole manifest. Not a separate brief.
6. **The plan absorbs its own changes.** Someone who reads from Item 1 to the end knows the whole story without opening anything else.