9thlevelsoftware/legion/spec-pipeline

Input:
  - .planning/ROADMAP.md — phase details (goal, requirements list, success criteria)
  - .planning/REQUIREMENTS.md — full requirement descriptions (if exists)
  - .planning/PROJECT.md — project constraints, architecture notes, value proposition
 
Output:
  Structured requirements summary with categorized items
 
Process:
 
Step 1: Read ROADMAP.md
  Find the Phase Details section for the target phase number.
  Extract:
  - phase_name: descriptive name
  - phase_goal: the Goal field
  - phase_requirements: list of requirement IDs
  - success_criteria: the Success Criteria list
  - dependencies: which prior phases this phase depends on
 
Step 2: Expand requirements
  If .planning/REQUIREMENTS.md exists:
    For each requirement ID in phase_requirements, extract the full description,
    acceptance criteria, and any notes from REQUIREMENTS.md.
  If REQUIREMENTS.md is absent (between milestones):
    Use ROADMAP.md requirement summaries. Note the limitation.
 
Step 3: Read project constraints
  From PROJECT.md, extract:
  - Architecture constraints (tech stack, patterns, conventions)
  - Non-functional requirements (performance, accessibility, compatibility)
  - User-facing constraints (target users, use cases)
 
Step 4: Categorize requirements
  Group all extracted requirements into:
 
  | Category | Description | Examples |
  |----------|-------------|---------|
  | Functional | What the system must do | "Spawn 2-3 agents with different philosophies" |
  | Non-functional | Quality attributes and constraints | "Per-plan task cap", "Progressive disclosure" |
  | Dependencies | What must exist before this phase | "Phase 29 output (frontmatter schema)" |
  | Deliverables | Concrete files/artifacts produced | "skills/spec-pipeline/SKILL.md" |
 
Step 5: Identify success criteria
  For each requirement, derive a testable success criterion:
  - What file exists?
  - What string is present?
  - What command returns success?
  - What user-facing behavior changes?
 
  If the ROADMAP.md success criteria are vague, sharpen them into
  machine-checkable statements (same standard as phase-decomposer
  Section 6 verification lines).
 
Output format:
 
  ## Requirements Summary — Phase {N}: {phase_name}
 
  **Goal:** {phase_goal}
  **Dependencies:** {prior phases}
 
  ### Functional Requirements
  | ID | Description | Acceptance Criteria |
  |----|-------------|-------------------|
  | {REQ-ID} | {description} | {testable criterion} |
 
  ### Non-Functional Requirements
  | Constraint | Source | Impact |
  |-----------|--------|--------|
  | {constraint} | {PROJECT.md / ROADMAP.md} | {how it affects implementation} |
 
  ### Deliverables
  | Artifact | Path | Purpose |
  |----------|------|---------|
  | {name} | {file path} | {what it provides} |

Input:
  - Section 1 output (structured requirements summary)
  - .planning/CODEBASE.md and .planning/codebase/ (if exists — codebase map context)
  - Existing skill/command files relevant to this phase
 
Output:
  Research brief with findings, open questions, and recommended approaches
 
Process:
 
Step 1: Identify knowledge gaps
  For each deliverable from Section 1:
  a. Does an existing file need modification? → Read it to understand current structure
  b. Does a new file follow an existing pattern? → Find and read the pattern source
  c. Does the requirement reference an unfamiliar concept? → Flag as research needed
  d. Does the requirement depend on external behavior? → Flag for verification
 
  Produce a gap list:
  | Gap | Type | Resolution Strategy |
  |-----|------|-------------------|
  | {what's unknown} | Pattern / Technical / Domain | {how to resolve} |
 
Step 2: Search existing codebase
  For each gap with resolution strategy "Pattern" or "Technical":
  a. Search for similar patterns in existing skill files
  b. Read relevant command files for workflow patterns
  c. Check prior phase outputs (.planning/phases/) for reusable approaches
  d. If .planning/CODEBASE.md exists, check its Conventions and Risk Areas sections
 
  Record findings:
  | Gap | Source File | Finding |
  |-----|-----------|---------|
  | {gap} | {file path} | {what was found} |
 
Step 3: Spawn research agents (conditional)
  Only when the phase involves unfamiliar technology, patterns outside
  the existing codebase, or complex domain knowledge:
 
  a. Spawn 1-2 read-only (Explore) agents with specific research questions
  b. Each agent receives:
     - The requirements summary from Section 1
     - Their specific research question(s)
     - Instructions to return structured findings
  c. Agent selection: prefer agents with domain expertise
     (e.g., engineering-senior-developer for architecture research,
      design-ux-researcher for UX domain research)
 
  For most Legion phases (skill/command/agent work), the orchestrator
  handles research directly. Skip agent spawning.
 
Step 4: Compile research brief
  Merge all findings into a structured brief:
 
  ## Research Brief — Phase {N}: {phase_name}
 
  ### Findings
  | Topic | Source | Summary |
  |-------|--------|---------|
  | {topic} | {file or agent} | {1-2 sentence finding} |
 
  ### Patterns to Follow
  - {pattern name}: {source file} — {how it applies}
 
  ### Open Questions
  - {question that could not be resolved by research}
  - {question that needs user decision}
  Each question must be classified as Blocking or Non-blocking.
  Blocking questions halt planning until resolved.
  Non-blocking questions must include the default chosen by the spec and the
  evidence that makes that default safe.
 
  ### Recommended Approaches
  For each major deliverable:
  - **{deliverable}**: {recommended approach based on research}
    Rationale: {why this approach, what evidence supports it}
    Decision coverage: {API/type contracts, file placement, data/control flow,
    compatibility constraints, failure modes, and acceptance checks resolved for
    this deliverable}

Input:
  - Section 1 output (requirements summary)
  - Section 2 output (research brief)
 
Output:
  Spec document at .planning/specs/{NN}-{phase-slug}-spec.md
 
Process:
 
Step 1: Create specs directory (if needed)
  mkdir -p .planning/specs/
 
Step 2: Draft spec document
  Write the spec to .planning/specs/{NN}-{phase-slug}-spec.md using
  the following structure:
 
  ---BEGIN SPEC TEMPLATE---
 
  # Spec: Phase {N} — {phase_name}
 
  ## Overview
  {1-paragraph summary of what will be built and why. Reference the phase
  goal and connect it to the broader milestone/project context.}
 
  ## Requirements
  | ID | Description | Priority | Acceptance Criteria |
  |----|-------------|----------|-------------------|
  | {REQ-ID} | {description} | {Must/Should/Could} | {testable criterion} |
 
  ## Architecture
  {How the deliverables fit together. Key design decisions with rationale.
  File relationships and data flow between artifacts. Reference patterns
  identified in Section 2 research.}
 
  ### Key Decisions
  | Decision | Choice | Rationale | Alternatives Considered |
  |----------|--------|-----------|----------------------|
  | {decision} | {what was chosen} | {why} | {what else was considered} |
 
  ## API and Type Contracts
  {For each public or internal interface created/changed: function signatures,
  exported types, request/response shapes, schema keys, command arguments,
  output formats, and backward-compatibility expectations. If no API/type
  contract changes exist, write `None -- no API or type contract changes`.}
 
  ## File Placement
  | Artifact | Path | Placement Rationale | Existing Pattern |
  |----------|------|---------------------|------------------|
  | {artifact} | {path} | {why this path is correct} | {source file/pattern followed} |
 
  ## Data and Control Flow
  {Ordered flow from input/source through transformation, persistence/output,
  errors, and verification. Include caller/callee relationships or artifact
  producer/consumer relationships.}
 
  ## Compatibility Constraints
  - {public API, persisted data, CLI, adapter, config, migration, platform, or
    backward-compatibility constraint}
 
  ## Failure Modes
  | Failure Mode | Expected Behavior | Verification |
  |--------------|-------------------|--------------|
  | {missing file / invalid input / unavailable dependency / conflict} | {behavior} | {check} |
 
  ## Acceptance Checks
  | Check | Command or Evidence | Required |
  |-------|---------------------|----------|
  | {acceptance check} | {command or deterministic evidence} | true/false |
 
  ## Deliverables
  {For each deliverable:}
 
  ### {Deliverable Name}
  - **Path:** {file path}
  - **Purpose:** {what it provides}
  - **Key Content:** {sections, structure, or API surface}
  - **Dependencies:** {what it needs from other deliverables or prior phases}
  - **Estimated Size:** {approximate line count or complexity}
 
  ## Open Questions
  {Unresolved items from research. Items needing user decision.
  Each question should note its impact: "Blocking" (must resolve before
  planning) or "Non-blocking" (the spec chooses a default that planning may use).}
 
  | # | Question | Impact | Default Chosen by Spec | Planning Effect |
  |---|----------|--------|------------------------|-----------------|
  | 1 | {question} | Blocking / Non-blocking | {only for Non-blocking; Blocking = none} | {halt planning or use default} |
 
  ## Complexity Assessment
  {Left empty — filled in by Section 5}
 
  ---END SPEC TEMPLATE---