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.