[shiplog/plan] Make planned stacked decomposition a first-class Phase 1 output

[devallibus]

Context

shiplog currently plans work as a single issue with tiered tasks, then opens that issue into one branch and one worktree. Stacked PRs exist in the protocol, but only as a discovery-time escape hatch after implementation has already started.

That leaves a planning gap:

• Tier-1 and tier-2 items that are obviously separate prerequisites or separate review units stay as checklist items inside one issue.
• Phase 1 has no way to say "this item should become its own stacked child issue and PR from the outset."
• The plan and start command flow materializes one issue into one branch/worktree, so the default workflow stays linear even when the design already implies a stack or a parallel fan-out.
• This underuses the intended model where a stronger planner decomposes the work tightly and weaker agents execute bounded leaves in parallel.

Related issues already cover adjacent parts of the problem:

• #92 covers runtime orchestration, fan-out, auto-spawn, and worktree lifecycle once parallel work is being dispatched.
• #79 covers task-to-git mapping once a task or branch boundary has already been chosen.

This issue covers the missing earlier decision: how Phase 1 should represent planned dependency topology so stacked execution is a first-class output instead of a discovery-only fallback.

Design Summary

• Add a planning-time topology model that distinguishes:
  • issue-local task
  • planned stacked child issue/PR
  • deferred follow-up issue
• Add explicit dependency metadata so plans can express:
  • blocks / depends on
  • can run in parallel with
  • should merge before / after
• Make parent/child stack planning part of Phase 1 output when the dependency structure is already known.
• Keep the existing "one branch, one worktree, one agent" rule at the execution leaf level, but add an orchestrator layer above it for planned decomposition.
• Align the planning model with #92 so runtime fan-out and collection operate on an explicit planned topology, not an inferred one.

Approach

Extend the Phase 1 issue template and command flow so planning can emit either:

1. a single issue with only issue-local tasks, or
2. a parent issue plus explicitly planned child issues that are intended to become stacked branches and PRs.

The protocol should define when a task remains local versus when it should be promoted to a child issue:

• separate prerequisite
• materially independent review unit
• bounded file ownership for delegated execution
• parallelizable branch of work
• decision-heavy item that should not be buried inside a larger implementation issue

The output of that classification should then feed Phase 2 branch setup and the #92 orchestration work, while staying compatible with #79 task-to-git mapping inside each resulting issue.

Alternatives Considered

• Keep stacked PRs discovery-only. Rejected because it makes known topology appear late, after work has already been serialized into one branch.
• Fold this entirely into [shiplog/plan] Orchestrator protocol: fan-out dispatch, auto-spawn at phase boundaries, and worktree lifecycle #92. Rejected because #92 starts at runtime dispatch; this issue is about plan representation before dispatch exists.
• Fold this entirely into feat(#79): define task-to-git mapping — how issue tasks become commits and branches #79. Rejected because task-to-git mapping is downstream of the more important question: which planned items should become separate issues/branches at all.

Tasks

• T1: Define the planning-time topology model [tier-1]

  • What: Design the minimum set of planning outcomes and dependency fields needed to represent linear work, planned stacks, and parallelizable children without making Phase 1 noisy.
  • Files: skills/shiplog/SKILL.md, skills/shiplog/references/phase-templates.md, commands/shiplog/plan.md
  • Decision budget: full
  • Accept when: A planner can classify planned work as issue-local, stacked child, or follow-up issue without inference, and the dependency vocabulary is explicit.
  • Why tier-1: This is a protocol boundary decision that affects how every future plan is shaped.

• T2: Define promotion criteria from task to child stacked issue [tier-1]

  • What: Specify the rules for when a planned item should be promoted out of the parent issue into its own child issue and future stacked PR, including examples and anti-examples.
  • Files: skills/shiplog/SKILL.md, skills/shiplog/references/phase-templates.md, README.md
  • Decision budget: full
  • Accept when: The docs clearly distinguish "keep as task" from "promote to child issue" for prerequisites, parallel work, separate review units, and routine subtasks.
  • Why tier-1: Bad criteria here either explode every issue into noise or keep obviously separate work trapped inside one branch.

• T3: Update Phase 1 templates and command flow to emit planned stacks [tier-2]

  • What: Modify the Phase 1 template and /shiplog plan command so a planning run can create or propose a parent issue plus planned child issues with explicit cross-references.
  • Files: skills/shiplog/references/phase-templates.md, commands/shiplog/plan.md, skills/shiplog/SKILL.md
  • Allowed to change: Planning templates, issue-body structure, command guidance, and cross-reference wording.
  • Must not change: The existing discovery protocol for unplanned mid-work findings.
  • Stop and ask if: The implementation would require changing GitHub issue semantics or dropping the current single-issue path for simple work.
  • Verification: Read the final planning flow top to bottom and confirm it supports both single-issue plans and planned parent/child stacks.
  • Return artifact: Updated planning flow summary with one concrete example of a parent issue spawning two planned child issues.
  • Decision budget: narrow
  • Accept when: A tier-2 executor can follow the docs and produce a correct planned stack capture from a brainstorm.

• T4: Align planned stack topology with [shiplog/plan] Orchestrator protocol: fan-out dispatch, auto-spawn at phase boundaries, and worktree lifecycle #92 and feat(#79): define task-to-git mapping — how issue tasks become commits and branches #79 [tier-2]

  • What: Define the handoff points between planning-time topology (this issue), runtime orchestration and collection (#92), and task-level git traceability inside each issue (#79).
  • Files: skills/shiplog/SKILL.md, README.md
  • Allowed to change: Cross-references, integration map wording, and relationship notes between issues.
  • Must not change: The one-branch-one-worktree-one-agent execution rule at the leaf level.
  • Stop and ask if: Resolving the overlap would require collapsing the three issues into one large scope blob.
  • Verification: The final docs leave no ambiguity about which issue owns planning topology, runtime fan-out, and task-level artifact mapping.
  • Return artifact: Scope boundary summary for #92, #79, and this issue.
  • Decision budget: narrow
  • Accept when: The three threads are complementary instead of overlapping ambiguously.

• T5: Update README examples to show planned stacks as a first-class path [tier-3]

  • What: Add one example showing a brainstorm that produces a parent issue with planned child issues and stacked PR intent from the start.
  • Files: README.md
  • Allowed to change: README examples and explanatory text.
  • Must not change: Existing simple linear examples that are still valid for small work.
  • Stop and ask if: The docs update would require promising automation that shiplog does not actually provide yet.
  • Verification: The README now shows both linear and planned-stack paths without implying that every task becomes its own PR.
  • Return artifact: Diff summary.
  • Decision budget: none
  • Accept when: A reader can see that planned stacks are a supported outcome of planning, not only a mid-work discovery response.

Open Questions

• Should planned child issues be created during Phase 1 immediately, or should Phase 1 be allowed to record "intended child issues" that are materialized at Phase 2 start?
• Should the dependency vocabulary live in task bullets, artifact envelopes, or a separate "Execution Topology" section?
• Should a planned stacked child always imply a separate PR, or can some child issues still land as grouped commits if the stack collapses during execution?
• What is the minimum topology syntax that remains readable in GitHub issues without turning the issue body into YAML noise?

---

Authored-by: openai/gpt-5.4 (codex, effort: high)
Captain's log entry created by shiplog