9thlevelsoftware/legion/phase-decomposer

Phase Decomposer

Engine for /legion:plan. Takes a ROADMAP.md phase entry and transforms it into decision-complete implementation contracts with per-plan agent recommendations. The full flow: analyze phase, resolve design decisions, decompose into independently verifiable plans, recommend agents, present for confirmation, generate plan files.

Section 1: Decomposition Principles

1. Per-plan task cap comes from settings — read settings.json key planning.max_tasks_per_plan (default: 3). This only limits how many tasks go inside one plan; it does not limit how many plans a phase may contain. If a phase needs more work than that per-plan task cap, split it into as many additional plans as dependency, ownership, verification, and traceability boundaries require.
2. Wave-structured execution — Wave 1 plans have no internal dependencies. Wave 2 plans depend on Wave 1 outputs. Parallel within waves, sequential between waves.
3. Per-plan agent assignment — different plans in the same phase may use different agents. A frontend plan gets a frontend agent; a testing plan gets a testing agent.
4. Self-contained plans — each plan must be executable with only its <context> and <execution_contract> references. An agent should never need to read a file not listed in the contract.
5. Concrete verification — every task has BOTH:

• > verification: inline lines after the task description — machine-checkable commands that can be extracted and run automatically by the wave-executor
• A <verify> block with the same commands in executable form

No "manually check" or "visually inspect" instructions. If you cannot script the check, the task is too vague.

1. Smallest independently verifiable plan — choose the smallest plan that can be executed and verified on its own. planning.max_tasks_per_plan is a per-plan task cap, not a phase plan-count cap or compression goal; do not combine work just to reduce plan count when it leaves the executor making design decisions.
2. No planned-work deferrals — every planned task must be written so execution ends in one of three states: completed, blocked with evidence, or escalated through the blocker escalation protocol. Do not tell executors to leave planned work for later, move it to a future phase, or mark it deferred unless the task itself is to create a user-approved follow-up artifact.
3. Decision-complete implementation contracts — every plan must name exact read targets, write targets, implementation sequence, required interfaces or content structure, edge/error cases, forbidden files, verification commands, and BLOCKED conditions. If a planner cannot decide an API, path, validation behavior, helper, or test location, planning is not done.

Section 1.5: Settings Input

Before decomposition, resolve the per-plan task cap from settings.json:

• Try Read settings.json
• If present, use planning.max_tasks_per_plan as the hard cap for tasks inside each plan
• If missing or invalid, default to 3
• This value never caps the total number of plans in a phase
• Carry this value as {max_tasks_per_plan} for all rules and templates below

Extended Thinking Mode

If settings.json models.planning_reasoning is true AND the active adapter's supports_extended_thinking is true:

• Use adapter.model_planning (e.g., opus) for the decomposition agent
• Extended thinking provides deeper analysis of:
• Requirement dependencies and implicit constraints
• Wave ordering rationale (why plan A must precede plan B)
• Agent selection justification (why this agent over alternatives)
• The decomposition output is identical in format; only the reasoning depth changes

If models.planning_reasoning is false: use adapter.model_execution as normal

Section 2: Phase Analysis

How to extract and analyze phase information before decomposition.

Step-by-Step Extraction

Step 1: Read .planning/ROADMAP.md
Step 2: Find the Phase Details section for the target phase number
Step 3: Extract the following fields:
  - phase_name: the descriptive name (e.g., "Plugin Foundation")
  - phase_goal: the Goal field
  - phase_requirements: the Requirements field (list of requirement IDs)
  - success_criteria: the Success Criteria list
  - estimated_plans: the Plans count
Step 4: Read .planning/REQUIREMENTS.md
Step 5: Cross-reference: for each requirement ID in phase_requirements,
        get the full requirement description from REQUIREMENTS.md
Step 6: Read .planning/PROJECT.md for broader project context
        (value proposition, target users, constraints, architecture notes)
Step 7: Read .planning/STATE.md for current progress and any completed
        phases that this phase builds on

What to Look For

Phase Slug Convention

Derive the phase directory slug from the phase name:

• Lowercase the name
• Replace spaces with hyphens
• Remove special characters
• Example: "Plugin Foundation" becomes plugin-foundation
• Full path: .planning/phases/{NN}-{slug}/ (e.g., .planning/phases/03-phase-planning/)

Marketing Domain Detection

After reading phase details, check if this is a marketing-focused phase:

1. Requirement check: Any MKT-* requirement IDs in the phase requirements?
2. Keyword check: Phase description contains marketing keywords?

Keywords: "campaign", "content calendar", "social media", "cross-channel", "marketing", "brand awareness", "audience", "engagement strategy", "content strategy", "channel strategy"

1. Agent signal: Does agent-registry recommend majority marketing-division agents?

If ANY signal is positive: → Flag phase as marketing-focused → Read marketing-workflows skill for domain-specific patterns → Use marketing wave pattern in Section 3 decomposition → Trigger campaign questioning (marketing-workflows Section 2.1) → Generate campaign document (marketing-workflows Section 2.2)

If no signals: → Standard decomposition (no impact)

Design Domain Detection

After reading phase details (and after marketing detection), check if this is a design-focused phase:

1. Requirement check: Any DSN-* requirement IDs in the phase requirements?
2. Keyword check: Phase description contains design keywords?

Keywords: "design system", "component library", "UX research", "usability testing", "accessibility audit", "brand guidelines", "design tokens", "wireframes", "prototypes", "user testing", "design review", "user persona", "user journey", "information architecture", "visual design"

1. Agent signal: Does agent-registry recommend majority design-division agents?

If ANY signal is positive: → Flag phase as design-focused → Read design-workflows skill for domain-specific patterns → Use design wave pattern in Section 3 decomposition → Trigger design brief questioning (design-workflows Section 2.1) → Generate design documents (design-workflows Section 2.2)

If no signals: → Standard decomposition (no impact)

Section 2.5: Competing Architecture Proposals

Before decomposing into plans, optionally generate competing architecture proposals. This ensures the planning approach isn't biased by a single perspective. Adapted from Feature-dev's 2-3 competing designs pattern.

When to Generate Proposals

Complexity check:
- If phase has ≤2 requirements AND only modifies existing markdown files → Skip (too simple)
- If phase has 3+ requirements AND involves architectural choices (new abstractions,
  new patterns, structural decisions) → Offer proposals
- If user explicitly requests → Always generate
- Default is skip — proposals are opt-in, not opt-out
- The orchestrator presents the option; user can always decline

Philosophy Archetypes

Define 3 labeled approaches that agents adopt:

Proposal Generation Process

Step 1: Read phase context
  Use the phase analysis output from Section 2: phase goal, requirements,
  success criteria, existing assets, and constraints.
 
Step 2: Spawn proposal agents
  Spawn 2-3 agents using the read-only Explore subagent type (same pattern
  as plan-critique Section 4). Each agent receives:
  - The full phase context from Step 1
  - Their assigned philosophy (Minimal, Clean, or Pragmatic)
  - Instructions to produce a structured proposal
 
  Agent selection:
  - Use agent-registry to match agents with architectural or strategic expertise
  - Preferred: engineering-senior-developer (Clean), engineering-rapid-prototyper (Minimal),
    product-sprint-prioritizer (Pragmatic)
  - For non-engineering phases: match to domain-appropriate agents with similar traits
  - Each agent operates in full personality (personality injection pattern from workflow-common)
 
  Prompt template for each agent:
  "You are analyzing Phase {N}: {phase_name} from the perspective of the
   {philosophy} philosophy. Given the requirements and context below,
   propose how you would structure the implementation.
 
   Your proposal must include:
   1. Approach summary (2-3 sentences)
   2. Key decisions and why (3-5 bullet points)
   3. Files you would modify/create (list)
   4. Estimated wave structure (how many waves, what in each)
   5. Trade-offs (what this approach gains and what it sacrifices)
   6. Risk assessment (1-2 main risks of this approach)"
 
Step 3: Collect and format proposals
  Wait for all agents to return. Format proposals side-by-side:
 
  ## Architecture Proposals — Phase {N}: {phase_name}
 
  ### Proposal A: Minimal ({agent_name})
  **Approach:** {summary}
  **Key decisions:**
  - {decision 1}
  - {decision 2}
  **Files:** {list}
  **Waves:** {wave structure}
  **Trade-offs:** {gains vs sacrifices}
  **Risk:** {main risk}
 
  ### Proposal B: Clean Architecture ({agent_name})
  {same structure}
 
  ### Proposal C: Pragmatic ({agent_name})
  {same structure}
 
  ### Comparison
  | Dimension | Minimal | Clean | Pragmatic |
  |-----------|---------|-------|-----------|
  | Files modified | {N} | {N} | {N} |
  | Estimated waves | {N} | {N} | {N} |
  | Risk level | {Low/Med/High} | {Low/Med/High} | {Low/Med/High} |
  | Best for | {scenario} | {scenario} | {scenario} |
 
Step 4: User selection
  Use AskUserQuestion:
 
  "Which architecture approach for Phase {N}?"
  Options:
  - "Proposal A: Minimal" — {1-line summary}
  - "Proposal B: Clean Architecture" — {1-line summary}
  - "Proposal C: Pragmatic" — {1-line summary}
  - "Hybrid" — "I want to combine elements from multiple proposals"
 
  If "Hybrid": ask user which elements from which proposals to combine,
  then synthesize a merged approach.
 
Step 5: Feed into decomposition
  The selected approach (or hybrid) becomes the architectural direction
  for Section 3 (Task Decomposition). Record the selection in the phase
  CONTEXT.md under "Key Design Decisions":
 
  "Architecture approach: {selected philosophy} — {rationale}"