stack-plan

Interactive planner for stacked features: assigns issues to repos and confirms the unclear ones.

Planning is the one step of the stack lifecycle where a wrong answer is a rebuild rather than a bad paragraph — every later command inherits the issue order and repo assignment the plan writes. This skill makes that step interactive: the agent assigns what's obvious itself, but never silently guesses on the unclear or the non-code. Use it when starting an xiv stack feature, especially a multi-repo one, before running any build.

The human provides three things: a Linear source (a project, or a parent issue with sub-issues), the repos the feature may span as key=path pairs (one for single-repo), and a short feature slug.

How it works

1. Learn the repos. Read each repo's README / package.json / Cargo.toml — one line per repo on what the service is.

2. Fetch the issues via the Linear MCP tools (get_project, get_issue, list_issues, list_comments).

3. Classify each issue into one of three buckets (references/classification.md):

   • confident — the repo is clear (a service label, a 1:1 project/sub-team mapping, a service or path named in the title) → assigned automatically.
   • ambiguous — clearly code, clearly one repo, but the signal is split or weak → the human picks from 1–2 candidates.
   • not-repo-specific — not a code change in any registered repo ("set GCP secrets", "notify customers", "update the runbook") → recommended for EXCLUDE; the human confirms or assigns.

4. Order the issues globally, foundations first, respecting dependencies. Each repo's substack is just its issues in that global order.

5. Show one table, ask once. Every issue appears in a single compact table — confident rows checked, flagged rows carrying a recommendation — and the human corrects the flagged rows in one reply. No per-issue prompting.

6. Resolve and persist. Apply the corrections, write the plan file, and run:

   xiv stack plan --feature <slug> --repo <key>=<path> [--repo ...] --plan <file>

7. Hand off. The next steps are xiv stack init in each repo (if not done) and xiv stack build --all-repos --feature <slug> — typically supervised by xiv-operator.

The plan file

references/plan-file.md gives the exact JSON schema: an order array (the global build sequence, each item an issue assigned to a repo key), an excluded array (issues intentionally not built, each with a reason), and a source for provenance. Rules the schema enforces:

• Every issue from the Linear source lands in exactly one of order or excluded.
• Branch names are derived by the CLI, never set in the plan.
• Within a repo, each issue stacks on the previous issue of that same repo — the CLI computes bases, so interleaved repos are fine.
• Excluded issues are recorded in the stack map and shown by xiv stack status, but never built.

xiv stack plan --plan persists the file deterministically — no agent re-guessing at persist time. The judgment happens in the conversation; the CLI just records it.

Notable design decisions

• Non-code work defaults to excluded, never silently assigned. Infra tasks, process steps, and docs-outside-any-repo aren't buildable; sneaking one into the stack produces a nonsense PR. The recommendation is always surfaced for the human to confirm — they may still assign it (e.g. infra-as-code that genuinely lives in a registered infra repo).
• One table, one question. Batching all flagged rows into a single reply keeps a 20-issue feature from becoming 20 round-trips.
• Read-only on code. The skill's only writes are the plan file and the xiv stack plan invocation — no branches, no edits, no other stack commands.
• Tie-breakers are explicit: prefer the most foundational repo when a change spans layers; an issue that is really two changes in two repos gets flagged for splitting in Linear rather than inventing a second issue.