---
name: plan-capture
metadata:
  version: "0.24.9"
description: '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.'
---

# 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: spawn ONE background subagent (Agent tool with
   `run_in_background`) whose prompt is: run the ticket-sync skill flow for
   the newly created items, then the wiki-publish flow for the new plan doc
   (its key is `plan/<slug>`), and report counts. 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 two 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.