# Plan Capture

> Capture an approved plan as tracked work items. Use when exiting plan mode, when the user approves a plan, or says "capture this plan". Writes docs/plans/<date>-<slug>.md and appends the plan's tasks to .work/todo.jsonl via bin/worklog.

- Skill: `spillwavesolutions/plan-capture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add spillwavesolutions/plan-capture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spillwavesolutions/plan-capture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: spillwavesolutions (https://skillmd.com/u/spillwavesolutions)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/spillwavesolutions/plan-capture

---


# Plan capture

1. Write the approved plan as markdown. It MUST contain a `## Tasks` section:

       ## Tasks

       - [ ] (P1) Task title
         One to three plain sentences under the checkbox become the task's
         ticket body — written for a junior dev or a PM (spec §13.4):
         what and why, no ULIDs.
         - [ ] Subtask of the task above

   Priority token `(P0)`–`(P3)` optional, default P2. **Every task gets a
   description line** — a marker-only ticket body is a policy violation
   (§13.4). Plan-level prose (the *why*) goes in other sections and is
   preserved verbatim in the plan doc.

   Captured items are `kind:feature` by design — a plan's tasks deliver
   planned value. If a captured task is really a defect, retag it after
   capture: `bin/worklog update <ulid> --kind bug`.

2. Save it to a temp file and run:

       bin/worklog plan-capture --slug <kebab-slug> --title "<plan title>" \
           --body "<epic description a junior dev/PM can read>" --file <tempfile>

3. Run `bin/worklog roadmap-render`, then `bin/worklog ia-index` (refreshes
   sidecars, inventory, rendered Home/Sidebar/indexes, and the publish
   manifest so the new plan is navigable), then commit `docs/plans/`,
   `docs/roadmap.md`, `docs/.index/`, and `.work/todo.jsonl` together.

4. Publish in the background — but only what `bin/worklog triggers plan-capture`
   lists. Spawn ONE background subagent (Agent tool with `run_in_background`)
   whose prompt is: run those actions (ticket-sync skill flow for the newly
   created items; wiki-publish for the new plan doc, key `plan/<slug>`), and
   report counts. An empty list means skip publishing. Continue implementing
   immediately — do NOT wait for the subagent; fold its result in when the
   notification arrives. If background agents are unavailable in the harness,
   run the listed publishes inline after the first implementation commit
   instead — visibility may lag but never blocks. Whichever way it runs, the
   publishing step ends by re-running `bin/worklog ia-index` and committing
   `docs/.index/`: publishing writes each page's live wiki location back into
   the ledger, which leaves the generated inventory stale, and the IA gates
   are hard — the next commit fails otherwise. One pass converges, because a
   wiki location is not part of the render hash.

Never append to `.work/*.jsonl` directly (invariant 15.4). Never overwrite an
existing plan (invariant 15.8) — a changed design gets a NEW plan that
supersedes the old one.