feat(linear): auto-decompose issues into a dependency-aware sub-issue graph (plan + approval)

[isadeks]

Component

API or orchestration, Agent runtime, Scripts / CLI

Describe the feature

Auto-decomposition of Linear issues into a dependency-aware sub-issue graph, with optional plan-approval. When a sufficiently complex issue is labeled, ABCA judges whether to decompose, proposes a sub-issue breakdown with blockedBy edges, a worst-case cost ceiling, per-child S/M/L sizing, and critical-path length, then (per project config) either waits for approval or auto-runs — finally writing the sub-issues into Linear and handing the graph to the #247 orchestration executor.

This is the planner that #247 deliberately scoped out ("planner-worker out of scope for MVP"). It is stacked on #247 and reuses its executor wholesale.

Use case

• Label-once epics: a PM labels a single complex issue; ABCA decomposes it.
• Both worlds: a human-authored graph runs via feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 (Mode A); a plain issue gets decomposed here (Mode B). Both converge on the same executor.
• Spend safety: plan-approval + project caps bound the blast radius of N agent runs.

Proposed solution

• Label = decomposition intent (only acts on an undecomposed issue): bgagent:decompose (decompose + approve plan), bgagent:auto (decompose + auto-run). On a parent that already has sub-issues the suffix is a no-op → falls back to the feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 executor (Mode A). Plain bgagent = today's single task (or, on an existing graph, execute it via feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247).
• Caps by project config (LinearProjectMappingTable, admin-set): decompose_allowed, max_sub_issues (default 8), max_parent_budget_usd. Submitters pick a mode but cannot exceed caps.
• Complexity judge decides whether to decompose at all.
• Planner (LLM) proposes breakdown + dependency edges + S/M/L; cost estimate = Σ child max_budget_usd (ceiling) + critical-path length. No absolute-time estimate.
• Plan-approval gate on the parent issue (pre-execution; distinct from Cedar intra-task HITL).
• Write-back: create subIssues + blockedBy edges in Linear → feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 executor runs it.

Acceptance criteria

• Plain complex issue with bgagent:decompose → ABCA posts a proposed plan (sub-issues + edges + cost ceiling + S/M/L + critical-path) on the parent.
• Plan respects max_sub_issues / max_parent_budget_usd; over-cap plans are rejected or trimmed with a clear message.
• bgagent:auto skips approval; bgagent:decompose waits for approve/reject.
• On approval, sub-issues + blockedBy edges are written to Linear and the feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 executor takes over.
• Below-threshold issues fall back to today's single-task path unchanged.
• Docs: decomposition + label-mode guide; ROADMAP row; Starlight sync.

Depends on

• feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 (orchestration executor) — hard prerequisite (needs A1–A3).
• feat(notifications): Linear dispatcher in fanout consumer (cost/turns/duration) #243 (fan-out plane) — plan + rollup rendering.

Out of scope (this issue)

• Recursive decomposition (depth > 1).
• Auto-retry of failed children (follow-up).
• Auto-merge of the completed stack.