docs: add Topic Handoff Pattern guidelines

docs/quickstart.md

@@ -77,6 +77,40 @@ If you invoke the skill without a task description, the AI will ask you what you
 
 ---
 
+## Optional: Split Large or Unrelated Topics
+
+For one focused task, the three root files are enough. For several unrelated
+tasks in the same repository, use an isolated plan directory so each topic has
+its own `task_plan.md`, `findings.md`, and `progress.md`:
+
+```bash
+./scripts/init-session.sh backend-refactor
+./scripts/init-session.sh production-incident
+./scripts/set-active-plan.sh 2026-01-10-backend-refactor
+```
+
+For a long-running operational topic that shares the same root plan, keep
+`progress.md` concise and move durable details into a topic handoff file:
+
+```text
+progress.md
+  Runtime-wide timeline and short pointers
+
+handoffs/backend-refactor.md
+  Current state, commands, validation, risks, rollback, PR links
+```
+
+Use this pattern when a discussion spans multiple sessions, has many commands,
+or needs a clean resume point without scanning the full timeline. Add one short
+line to `progress.md` whenever the topic handoff changes, then put the details
+in the handoff file.
+
+For GitHub work, `progress.md` should usually record only the branch, commit,
+PR URL, validation summary, and handoff file. Put the longer PR context,
+remaining risks, and rollback notes in the topic handoff.
+
+---
+
 ## Step 4: Re-read Before Decisions
 
 **When:** Before making major decisions (automatic with hooks in Claude Code)

docs/workflow.md

@@ -189,6 +189,52 @@ When an error occurs:
 
 ---
 
+## Topic Handoff Pattern
+
+The three root files work best for one active task. When work splits into
+multiple unrelated topics, prefer isolated planning directories:
+
+```text
+.planning/
+  2026-01-10-backend-refactor/
+    task_plan.md
+    findings.md
+    progress.md
+  2026-01-10-production-incident/
+    task_plan.md
+    findings.md
+    progress.md
+```
+
+Use `scripts/init-session.sh <slug>` to create a scoped plan and
+`scripts/set-active-plan.sh <plan-id>` to switch the active plan. Hooks resolve
+the active plan from `$PLAN_ID`, `.planning/.active_plan`, the newest scoped
+plan, then the legacy root files.
+
+Some teams also keep durable topic handoffs alongside the root planning files:
+
+```text
+progress.md
+  Short runtime timeline, plus links to topic handoffs
+
+handoffs/<topic>.md
+  Detailed current state, commands, validation, risks, rollback, PR links
+```
+
+This is useful when a topic spans many sessions or many chat threads. Keep
+`progress.md` as the index and put details in the topic handoff. A good
+handoff section answers:
+
+| Question | Where to put it |
+|----------|-----------------|
+| What is running now? | `handoffs/<topic>.md` |
+| How do I check it? | `handoffs/<topic>.md` |
+| What changed today? | Short pointer in `progress.md` |
+| What branch, commit, or PR matters? | Pointer in `progress.md`, details in the handoff |
+| What risk remains? | `handoffs/<topic>.md` |
+
+---
+
 ## The 5-Question Reboot Test
 
 If you can answer these questions, your context management is solid: