#!/bin/bash
# This script manages the authoring of Product Requirements Documents (PRDs).

set -e

# --- UTILITY FUNCTIONS ---

function to_kebab_case() {
    echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g'
}

function get_date() {
    date +%Y-%m-%d
}

function check_prd_directory() {
    if [ ! -d "docs/prds" ]; then
        echo "Error: docs/prds/ directory does not exist." >&2
        echo "Please create it first: mkdir -p docs/prds" >&2
        exit 1
    fi
}

function check_project_exists() {
    local project_name=$1
    local project_dir="docs/prds/$project_name"

    if [ ! -d "$project_dir" ]; then
        echo "Error: Project directory '$project_dir' does not exist." >&2
        echo "Run 'brief' command first to create the project." >&2
        exit 1
    fi
}

function check_file_exists() {
    local file_path=$1
    local description=$2

    if [ ! -f "$file_path" ]; then
        echo "Error: $description not found at '$file_path'." >&2
        return 1
    fi
    return 0
}

# --- STATUS COMMAND ---

function status() {
    local project_name=$1
    check_prd_directory

    echo "=== PRD Status Report ==="
    echo ""

    # If no project name provided, list all projects
    if [ -z "$project_name" ]; then
        local projects=(docs/prds/*/)
        if [ ${#projects[@]} -eq 0 ] || [ ! -d "${projects[0]}" ]; then
            echo "No PRD projects found in docs/prds/"
            echo ""
            echo "Recommendation: Run 'brief' command to start a new project"
            echo "Next command: bash scripts/prd-authoring.sh brief \"Project Name\""
            return
        fi

        echo "Found projects:"
        for project_dir in "${projects[@]}"; do
            if [ -d "$project_dir" ]; then
                local proj_name=$(basename "$project_dir")
                echo "  - $proj_name"
            fi
        done
        echo ""
        echo "Run 'status <project-name>' to check specific project status"
        return
    fi

    local project_dir="docs/prds/$project_name"
    if [ ! -d "$project_dir" ]; then
        echo "Project: $project_name (NOT FOUND)"
        echo ""
        echo "Recommendation: Run 'brief' command to create this project"
        echo "Next command: bash scripts/prd-authoring.sh brief \"$project_name\""
        return
    fi

    echo "Project: $project_name"
    echo ""

    # Check product brief
    local brief_status="✗"
    local brief_complete="✗"
    if [ -f "$project_dir/product-brief.md" ]; then
        brief_status="✓"
        # Check for required sections
        if grep -q "## Problem Statement" "$project_dir/product-brief.md" && \
           grep -q "## Target Users" "$project_dir/product-brief.md" && \
           grep -q "## Success Metrics" "$project_dir/product-brief.md"; then
            brief_complete="✓"
        fi
    fi

    # Check research
    local research_status="✗"
    local research_complete="✗"
    if [ -f "$project_dir/research.md" ]; then
        research_status="✓"
        # Check for required sections
        if grep -q "## Competitive Analysis" "$project_dir/research.md" && \
           grep -q "## Recommendations" "$project_dir/research.md"; then
            research_complete="✓"
        fi
    fi

    # Check PRD
    local prd_status="✗"
    local prd_complete="✗"
    if [ -f "$project_dir/prd.md" ]; then
        prd_status="✓"
        # Check for required sections
        if grep -q "## Objectives" "$project_dir/prd.md" && \
           grep -q "## Success Criteria" "$project_dir/prd.md" && \
           grep -q "## Functional Requirements" "$project_dir/prd.md"; then
            prd_complete="✓"
        fi
    fi

    # Check epics
    local epics_status="✗"
    if [ -f "$project_dir/epics.md" ]; then
        epics_status="✓"
    fi

    # Determine status and recommendation
    local status_phase="Inception"
    local recommendation=""
    local next_command=""

    if [ "$epics_status" = "✓" ]; then
        status_phase="Ready for Development"
        recommendation="PRD decomposed into epics. Ready for spec-authoring workflow."
        next_command="Transition to spec-authoring for each epic"
    elif [ "$prd_complete" = "✓" ]; then
        status_phase="PRD Complete"
        recommendation="Run 'decompose' command to break PRD into epics"
        next_command="bash scripts/prd-authoring.sh decompose $project_name"
    elif [ "$prd_status" = "✓" ]; then
        status_phase="PRD Draft"
        recommendation="Complete PRD sections, then run 'validate-prd' command"
        next_command="bash scripts/prd-authoring.sh validate-prd $project_name"
    elif [ "$research_complete" = "✓" ] || [ "$research_status" = "✓" ]; then
        status_phase="Research Phase"
        recommendation="Run 'create-prd' command to create PRD from brief and research"
        next_command="bash scripts/prd-authoring.sh create-prd $project_name"
    elif [ "$brief_complete" = "✓" ]; then
        status_phase="Brief Complete"
        recommendation="Run 'research' command to conduct market analysis"
        next_command="bash scripts/prd-authoring.sh research $project_name"
    elif [ "$brief_status" = "✓" ]; then
        status_phase="Brief Draft"
        recommendation="Complete product brief sections"
        next_command="Edit docs/prds/$project_name/product-brief.md"
    fi

    echo "Status: $status_phase"
    echo "- $brief_status Product brief exists (docs/prds/$project_name/product-brief.md)"
    if [ "$brief_status" = "✓" ]; then
        echo "  - Brief completeness: $brief_complete"
    fi
    echo "- $research_status Research document exists (docs/prds/$project_name/research.md)"
    if [ "$research_status" = "✓" ]; then
        echo "  - Research completeness: $research_complete"
    fi
    echo "- $prd_status PRD exists (docs/prds/$project_name/prd.md)"
    if [ "$prd_status" = "✓" ]; then
        echo "  - PRD completeness: $prd_complete"
    fi
    echo "- $epics_status Epic decomposition exists (docs/prds/$project_name/epics.md)"
    echo ""
    echo "Recommendation: $recommendation"
    echo "Next command: $next_command"
}

# --- BRIEF COMMAND ---

function brief() {
    local project_name=$1
    if [ -z "$project_name" ]; then
        echo "Error: Project name not provided for 'brief' command." >&2
        echo "Usage: $0 brief <project-name>" >&2
        exit 1
    fi

    check_prd_directory

    local dir_name=$(to_kebab_case "$project_name")
    local project_dir="docs/prds/$dir_name"
    local brief_file="$project_dir/product-brief.md"

    echo "Creating product brief: $project_name"

    if [ -d "$project_dir" ]; then
        echo "Warning: Project directory '$project_dir' already exists." >&2
        if [ -f "$brief_file" ]; then
            echo "Error: Product brief already exists at '$brief_file'." >&2
            exit 1
        fi
    fi

    mkdir -p "$project_dir"

    local today=$(get_date)

    local today=$(get_date)
    echo "Generating a draft product brief with Gemini..."

    local gemini_prompt="Generate a comprehensive and well-structured product brief for a new project called '${project_name}'.
The brief should be in markdown format and include the following sections:
- A YAML frontmatter with title, type (product-brief), status (draft), created, and updated fields.
- A main title: '# Product Brief: ${project_name}'
- ## Problem Statement: Articulate a specific, measurable, and customer-focused problem.
- ## Target Users: Define primary and secondary user personas.
- ## Proposed Solution: Give a high-level overview of the solution.
- ## Value Proposition: Detail user and business benefits.
- ## Success Metrics: Define specific, measurable, achievable, relevant, and time-bound (SMART) metrics for launch and long-term success.

Flesh out each section with plausible, high-quality example content appropriate for a project of this nature. The goal is to create a strong first draft that can be reviewed and refined."

    # Call Gemini and write the output to the file
    gemini -p "$gemini_prompt" > "$brief_file"

    # Ensure the frontmatter has the correct dates
    sed -i "s/created: .*/created: $today/" "$brief_file"
    sed -i "s/updated: .*/updated: $today/" "$brief_file"

    echo "Successfully created product brief at $brief_file"
    echo ""
    echo "Next steps:"
    echo "1. Edit $brief_file to populate all sections"
    echo "2. Run 'status $dir_name' to verify completion"
    echo "3. Run 'research $dir_name' to conduct market analysis"
}

# --- RESEARCH COMMAND ---

function research() {
    local project_name=$1
    if [ -z "$project_name" ]; then
        echo "Error: Project name not provided for 'research' command." >&2
        echo "Usage: $0 research <project-name>" >&2
        exit 1
    fi

    check_prd_directory
    check_project_exists "$project_name"

    local project_dir="docs/prds/$project_name"
    local research_file="$project_dir/research.md"

    # Check if brief exists
    if ! check_file_exists "$project_dir/product-brief.md" "Product brief"; then
        echo "Run 'brief' command first to create the product brief." >&2
        exit 1
    fi

    echo "Creating research document for: $project_name"

    if [ -f "$research_file" ]; then
        echo "Error: Research document already exists at '$research_file'." >&2
        exit 1
    fi

    local today=$(get_date)

    local today=$(get_date)
    local brief_file="$project_dir/product-brief.md"
    echo "Generating a draft research document with Gemini..."

    local gemini_prompt="Based on the following product brief, generate a comprehensive market research document for the project '${project_name}'.
The research document should be in markdown format and include:
- A YAML frontmatter with title, type (research), status (in-progress), created, and updated fields.
- A main title: '# Research: ${project_name}'
- ## Competitive Analysis: Identify 2-3 potential competitors and analyze their strengths, weaknesses, and market position.
- ## Market Insights: Discuss market size, trends, and any relevant regulations.
- ## User Feedback Analysis: Synthesize potential user pain points and desired features.
- ## Technical Considerations: Examine common technical approaches, architecture patterns, and risks.
- ## Recommendations: Provide actionable recommendations for priority features, technical approach, and go-to-market positioning.

Flesh out each section with plausible, high-quality example content that logically follows from the product brief. The goal is to create a strong first draft that can be reviewed and refined.

Here is the product brief for context:
@${brief_file}
"

    # Call Gemini and write the output to the file
    gemini -p "$gemini_prompt" > "$research_file"

    # Ensure the frontmatter has the correct dates
    sed -i "s/created: .*/created: $today/" "$research_file"
    sed -i "s/updated: .*/updated: $today/" "$research_file"

    echo "Successfully created research document at $research_file"
    echo ""
    echo "Next steps:"
    echo "1. Conduct competitive analysis and market research"
    echo "2. Edit $research_file to document findings"
    echo "3. Run 'status $project_name' to verify completion"
    echo "4. Run 'create-prd $project_name' to create PRD"
}

# --- CREATE-PRD COMMAND ---

function create-prd() {
    local project_name=$1
    if [ -z "$project_name" ]; then
        echo "Error: Project name not provided for 'create-prd' command." >&2
        echo "Usage: $0 create-prd <project-name>" >&2
        exit 1
    fi

    check_prd_directory
    check_project_exists "$project_name"

    local project_dir="docs/prds/$project_name"
    local prd_file="$project_dir/prd.md"

    # Check if brief exists
    if ! check_file_exists "$project_dir/product-brief.md" "Product brief"; then
        echo "Run 'brief' command first to create the product brief." >&2
        exit 1
    fi

    # Check if research exists (warning only, not required)
    if ! check_file_exists "$project_dir/research.md" "Research document"; then
        echo "Warning: Research document not found. PRD quality may be reduced." >&2
        echo "Consider running 'research $project_name' first." >&2
        read -p "Continue anyway? (y/n) " -n 1 -r
        echo
        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
            exit 1
        fi
    fi

    echo "Creating PRD for: $project_name"

    if [ -f "$prd_file" ]; then
        echo "Error: PRD already exists at '$prd_file'." >&2
        exit 1
    fi

    local today=$(get_date)

    local today=$(get_date)
    local brief_file="$project_dir/product-brief.md"
    local research_file="$project_dir/research.md"
    echo "Generating a draft PRD with Gemini..."

    local gemini_prompt="Based on the following product brief and research document, generate a comprehensive Product Requirements Document (PRD) for the project '${project_name}'.
The PRD should be in markdown format and include:
- A YAML frontmatter with title, type (prd), status (draft), created, and updated fields.
- A main title: '# Product Requirements Document: ${project_name}'
- ## Objectives: Define 2-3 primary, SMART objectives.
- ## Success Criteria: Detail both launch criteria and post-launch success metrics.
- ## Functional Requirements: List at least 3-5 detailed functional requirements (FRs) with descriptions, user stories, and acceptance criteria.
- ## Non-Functional Requirements: Detail requirements for Performance, Security, Reliability, and Usability.
- ## Constraints: List any known technical, business, or resource constraints.
- ## Assumptions: Document key assumptions being made.
- ## Out of Scope: Clearly define what will not be built.

Flesh out each section with plausible, high-quality example content that logically follows from the provided context. The requirements should be specific and testable, and the success criteria should be measurable. The goal is to create a strong first draft that can be reviewed and refined.

Here is the product brief for context:
@${brief_file}

Here is the research document for context:
@${research_file}
"

    # Call Gemini and write the output to the file
    gemini -p "$gemini_prompt" > "$prd_file"

    # Ensure the frontmatter has the correct dates
    sed -i "s/created: .*/created: $today/" "$prd_file"
    sed -i "s/updated: .*/updated: $today/" "$prd_file"

    echo "Successfully created PRD at $prd_file"
    echo ""
    echo "Next steps:"
    echo "1. Populate PRD sections with requirements and success criteria"
    echo "2. Ensure requirements are specific, measurable, and testable"
    echo "3. Run 'validate-prd $project_name' to check quality"
    echo "4. Run 'decompose $project_name' after PRD is complete"
}

# --- VALIDATE-PRD COMMAND ---

function validate-prd() {
    set +e  # Temporarily disable exit on error for this function
    local project_name=$1
    local mode=${2:-strict}

    if [ -z "$project_name" ]; then
        echo "Error: Project name not provided for 'validate-prd' command." >&2
        echo "Usage: $0 validate-prd <project-name> [--lenient]" >&2
        exit 1
    fi

    # Handle --lenient flag
    if [ "$mode" = "--lenient" ]; then
        mode="lenient"
    elif [ "$mode" != "strict" ] && [ "$mode" != "lenient" ]; then
        mode="strict"
    fi

    check_prd_directory
    check_project_exists "$project_name"

    local project_dir="docs/prds/$project_name"
    local prd_file="$project_dir/prd.md"

    if ! check_file_exists "$prd_file" "PRD"; then
        echo "Run 'create-prd' command first to create the PRD." >&2
        exit 1
    fi

    echo "=== PRD Validation Report ==="
    echo "Project: $project_name"
    echo "File: $prd_file"
    echo "Mode: $mode"
    echo ""

    local issues=0
    local warnings=0

    # Check YAML frontmatter
    if head -n 1 "$prd_file" | grep -q "^---$"; then
        echo "✓ YAML frontmatter present"
    else
        echo "✗ YAML frontmatter missing"
        ((issues++))
    fi

    # Check for required sections
    local required_sections=(
        "## Objectives"
        "## Success Criteria"
        "## Functional Requirements"
        "## Non-Functional Requirements"
        "## Constraints"
        "## Assumptions"
    )

    echo ""
    echo "Completeness Checks:"
    for section in "${required_sections[@]}"; do
        if grep -q "^$section" "$prd_file"; then
            echo "  ✓ $section section present"
        else
            if [ "$mode" = "strict" ]; then
                echo "  ✗ $section section missing"
                ((issues++))
            else
                echo "  ⚠ $section section missing (lenient mode)"
                ((warnings++))
            fi
        fi
    done

    # Check for vague language
    echo ""
    echo "Quality Checks:"

    local vague_terms=("should" "might" "probably" "maybe" "could" "reasonable" "fast" "slow" "good" "better" "best" "many" "few" "most" "some")
    local vague_found=0

    for term in "${vague_terms[@]}"; do
        local matches=$(grep -n -i "\b$term\b" "$prd_file" | grep -v "^#" | head -n 3)
        if [ -n "$matches" ]; then
            if [ $vague_found -eq 0 ]; then
                echo "  Vague language detected:"
                vague_found=1
            fi
            echo "$matches" | while read -r line; do
                local line_num=$(echo "$line" | cut -d: -f1)
                echo "    ⚠ Line $line_num: Contains '$term'"
                ((warnings++)) || true
            done
        fi
    done

    if [ $vague_found -eq 0 ]; then
        echo "  ✓ No vague language detected"
    fi

    # Check for measurable success criteria
    if grep -q "## Success Criteria" "$prd_file"; then
        local success_section=$(sed -n '/## Success Criteria/,/^## /p' "$prd_file")
        if echo "$success_section" | grep -qE '[0-9]+%|[0-9]+ (seconds|minutes|hours|users|transactions)'; then
            echo "  ✓ Success criteria include measurable targets"
        else
            echo "  ⚠ Success criteria may lack measurable targets"
            ((warnings++))
        fi
    fi

    # Check for acceptance criteria in requirements
    if grep -q "## Functional Requirements" "$prd_file"; then
        local fr_count=$(grep -c "^### FR[0-9]" "$prd_file" || true)
        fr_count=${fr_count:-0}
        local ac_count=$(sed -n '/## Functional Requirements/,/^## /p' "$prd_file" | grep -c "Acceptance Criteria:" || true)
        ac_count=${ac_count:-0}

        if [ "$fr_count" -gt 0 ] && [ "$ac_count" -ge "$fr_count" ]; then
            echo "  ✓ Functional requirements include acceptance criteria"
        else
            echo "  ⚠ Some functional requirements may lack acceptance criteria"
            ((warnings++))
        fi
    fi

    # Check for out of scope section
    if grep -q "## Out of Scope" "$prd_file"; then
        echo "  ✓ Out of scope section defines boundaries"
    else
        echo "  ⚠ Out of scope section missing (recommended)"
        ((warnings++))
    fi

    # LLM-based quality analysis
    echo ""
    echo "Advanced Quality Analysis (LLM):"

    LLM_VALIDATOR="$(dirname "${BASH_SOURCE[0]}")/validate_prd_llm.py"

    if [ -f "$LLM_VALIDATOR" ]; then
        LLM_ANALYSIS=$(python3 "$LLM_VALIDATOR" --prd-file "$prd_file" 2>&1)
        LLM_EXIT_CODE=$?

        if [ $LLM_EXIT_CODE -eq 0 ] && [ -n "$LLM_ANALYSIS" ]; then
            # Check if LLM found no issues
            if echo "$LLM_ANALYSIS" | grep -q "No quality issues found"; then
                echo "  ✓ LLM quality check passed"
                echo "  $LLM_ANALYSIS"
            else
                echo "  ⚠ LLM identified potential quality issues:"
                echo ""
                echo "$LLM_ANALYSIS" | sed 's/^/  /'
                echo ""
                ((warnings++))
            fi
        else
            echo "  ⚠ LLM quality analysis failed or unavailable"
            ((warnings++))
        fi
    else
        echo "  ⚠ LLM validator script not found at $LLM_VALIDATOR"
        ((warnings++))
    fi

    # Summary
    echo ""
    echo "=== Summary ==="
    echo "Issues: $issues"
    echo "Warnings: $warnings"
    echo ""

    if [ $issues -eq 0 ] && [ $warnings -eq 0 ]; then
        echo "Overall: EXCELLENT ✓"
        echo "PRD meets all quality standards."
    elif [ $issues -eq 0 ] && [ $warnings -le 3 ]; then
        echo "Overall: GOOD ✓"
        echo "PRD is solid with minor improvements recommended."
    elif [ $issues -eq 0 ]; then
        echo "Overall: ACCEPTABLE"
        echo "PRD is complete but could be improved."
    else
        echo "Overall: NEEDS WORK"
        echo "Address critical issues before proceeding."
        if [ "$mode" = "strict" ]; then
            echo ""
            echo "Tip: Use '--lenient' flag for draft validation"
        fi
    fi

    echo ""
    echo "Next steps:"
    if [ $issues -gt 0 ]; then
        echo "1. Address critical issues in $prd_file"
        echo "2. Re-run validation: bash scripts/prd-authoring.sh validate-prd $project_name"
    else
        echo "1. Run 'decompose $project_name' to break PRD into epics"
    fi
}

# --- DECOMPOSE COMMAND ---

function decompose() {
    local project_name=$1
    if [ -z "$project_name" ]; then
        echo "Error: Project name not provided for 'decompose' command." >&2
        echo "Usage: $0 decompose <project-name>" >&2
        exit 1
    fi

    check_prd_directory
    check_project_exists "$project_name"

    local project_dir="docs/prds/$project_name"
    local prd_file="$project_dir/prd.md"
    local epics_file="$project_dir/epics.md"

    if ! check_file_exists "$prd_file" "PRD"; then
        echo "Run 'create-prd' command first to create the PRD." >&2
        exit 1
    fi

    echo "Creating epic decomposition for: $project_name"

    if [ -f "$epics_file" ]; then
        echo "Error: Epics document already exists at '$epics_file'." >&2
        echo "Edit existing file or delete it to regenerate." >&2
        exit 1
    fi

    local today=$(get_date)

    cat > "$epics_file" << EOF
---
title: $project_name Epics
type: epic-breakdown
prd: docs/prds/$project_name/prd.md
status: draft
created: $today
updated: $today
---

# Epic Breakdown: $project_name

<!-- This document decomposes the PRD into independently deliverable epics -->
<!-- Purpose: Create a logical decomposition that enables parallel work and incremental delivery -->

## Epic Decomposition Guidelines

<!-- Follow these principles when defining epics: -->

**What makes a good epic?**
- **Independently deliverable**: Can be shipped and provide value on its own
- **Right-sized**: Completable in 2-4 sprints (4-8 weeks)
- **Clear scope**: Well-defined boundaries of what's included/excluded
- **Aligned with objectives**: Directly supports one or more PRD objectives
- **Testable**: Has clear success criteria from the PRD
- **Minimal dependencies**: Reduces blocking between teams/sprints

**Common decomposition strategies:**
- By user journey (onboarding epic, checkout epic, etc.)
- By functional area (authentication epic, payment epic, analytics epic)
- By technical layer (frontend epic, API epic, data migration epic)
- By user persona (admin tools epic, end-user features epic)

---

## Epic 1: [Epic Name]

<!-- Use a descriptive name that captures the essence of what's being built -->
<!-- Example: "User Authentication & Authorization" -->
<!-- Example: "One-Click Checkout Experience" -->

### Objective

<!-- What does this epic achieve? What value does it provide? -->
<!-- Connect to PRD objectives - which objective(s) does this epic support? -->
<!-- Example: "Enable users to securely save payment methods and checkout with a single click, reducing checkout time from 3 minutes to 30 seconds (supports Objective 1: Reduce cart abandonment)" -->

### Scope

<!-- What specific features and capabilities are included in this epic? -->
<!-- Be concrete and specific - these become the basis for user stories -->

**Core Features**:
- [Feature/capability 1]
  - Example: "User can save up to 5 payment methods to their account"
- [Feature/capability 2]
  - Example: "User can select saved payment method during checkout"
- [Feature/capability 3]
  - Example: "User can set a default payment method"

**Supporting Features**:
- [Feature/capability]
  - Example: "User can edit or delete saved payment methods"
- [Feature/capability]
  - Example: "System validates payment methods before saving"

### Requirements Coverage

<!-- Which specific PRD requirements does this epic address? -->
<!-- Reference PRD requirement numbers (FR1, FR2, NFR1, etc.) -->

**Functional Requirements**:
- FR1: [Requirement name from PRD]
  - Coverage: [Complete / Partial - specify what's included]
- FR3: [Requirement name from PRD]
  - Coverage: [Complete / Partial - specify what's included]

**Non-Functional Requirements**:
- NFR2: Security
  - Coverage: Payment data encryption, PCI compliance
- NFR3: Reliability
  - Coverage: Error handling for payment service failures

### Success Criteria

<!-- What must be true for this epic to be considered successful? -->
<!-- Pull from PRD success criteria and launch criteria -->
<!-- Make these specific and measurable -->

**Functional Success** (Must meet all):
- [ ] [Specific, testable criterion from PRD]
  - Example: "User can save payment method and use it on next checkout"
- [ ] [Specific, testable criterion from PRD]
  - Example: "Payment method data encrypted at rest and in transit"
- [ ] [Specific, testable criterion from PRD]
  - Example: "System handles invalid payment data gracefully with clear error messages"

**Quality Success** (Must meet all):
- [ ] [Performance/quality target from PRD]
  - Example: "Payment method save operation completes in <1 second"
- [ ] [Performance/quality target from PRD]
  - Example: "Zero stored plaintext payment data in database"

**Business Success** (Measured post-launch):
- [ ] [Business metric from PRD]
  - Example: "30% of users save payment method on first use"
- [ ] [Business metric from PRD]
  - Example: "Returning users using saved payment methods checkout 60% faster"

### User Stories (Optional)

<!-- Breaking epics into user stories helps clarify scope -->
<!-- Format: As a [user type], I want [capability], so that [benefit] -->

1. As a [user type], I want [capability], so that [benefit]
   - Example: "As a returning customer, I want to save my payment method, so that I don't have to re-enter it on every purchase"

2. As a [user type], I want [capability], so that [benefit]
   - Example: "As a user, I want to see only the last 4 digits of my saved card, so that my payment information stays private"

### Dependencies

<!-- What must exist before this epic can be completed? -->
<!-- Are there dependencies on other epics, teams, or external systems? -->

**Epic Dependencies**:
- [Other epic]: [What's needed from that epic]
  - Example: "Epic 2 (User Account Management): Requires user authentication to be complete"

**Technical Dependencies**:
- [System/service]: [What's needed]
  - Example: "Stripe API integration: Account must be set up and credentials configured"

**Team Dependencies**:
- [Team/person]: [What's needed]
  - Example: "Security team: Review and approval of encryption approach"

**If no dependencies**: "None - this is a foundational epic that other work can build on"

### Technical Approach (Optional)

<!-- High-level technical strategy for implementing this epic -->
<!-- This is optional but helpful for complex epics -->

- [Key architectural decision or approach]
  - Example: "Use Stripe's Token API to avoid storing raw payment data"
- [Key architectural decision or approach]
  - Example: "Implement encryption at application layer using AWS KMS"

### Estimated Effort

<!-- How long will this epic take to complete? -->
<!-- Consider: design, implementation, testing, documentation, deployment -->

**Estimate**: [Number of sprints]
- Example: "3 sprints (6 weeks)"

**Breakdown**:
- Design & Planning: [Duration]
  - Example: "1 sprint: UI design, API design, security review"
- Implementation: [Duration]
  - Example: "1.5 sprints: Frontend, backend, integration"
- Testing & Polish: [Duration]
  - Example: "0.5 sprints: Testing, bug fixes, documentation"

**Confidence Level**: [High / Medium / Low]
<!-- High: Clear requirements, familiar territory -->
<!-- Medium: Some unknowns, but manageable -->
<!-- Low: Significant unknowns, may need spike work -->

### Out of Scope

<!-- What is explicitly NOT included in this epic? -->
<!-- Clarity on exclusions prevents scope creep -->

- [Feature/capability explicitly excluded]
  - Example: "Support for cryptocurrency payments (deferred to Phase 2)"
- [Feature/capability explicitly excluded]
  - Example: "Payment method sharing between family accounts (not in PRD)"
- [Feature/capability explicitly excluded]
  - Example: "Integration with non-Stripe payment processors"

### Risks & Mitigations

<!-- What could go wrong? How will you address it? -->

**Risk 1**: [Description of risk]
- Likelihood: [High / Medium / Low]
- Impact: [High / Medium / Low]
- Mitigation: [How to reduce or handle the risk]
- Example: "Stripe API changes - Likelihood: Low, Impact: High, Mitigation: Use stable API version, monitor changelog"

**Risk 2**: [Description of risk]
- Likelihood:
- Impact:
- Mitigation:

### Acceptance Process

<!-- How will this epic be validated before closing? -->

1. [Validation step]
   - Example: "All functional and quality success criteria met"
2. [Validation step]
   - Example: "Product owner sign-off on user experience"
3. [Validation step]
   - Example: "Security review passed"
4. [Validation step]
   - Example: "Documentation complete and published"

---

## Epic 2: [Epic Name]

<!-- Repeat the structure above for each epic -->

### Objective

### Scope

**Core Features**:
-
-

**Supporting Features**:
-

### Requirements Coverage

**Functional Requirements**:
- FRX:
  - Coverage:

**Non-Functional Requirements**:
- NFRX:
  - Coverage:

### Success Criteria

**Functional Success**:
- [ ]

**Quality Success**:
- [ ]

**Business Success**:
- [ ]

### User Stories (Optional)

1. As a [user type], I want [capability], so that [benefit]

### Dependencies

**Epic Dependencies**:
-

**Technical Dependencies**:
-

**Team Dependencies**:
-

### Technical Approach (Optional)

-

### Estimated Effort

**Estimate**:

**Breakdown**:
- Design & Planning:
- Implementation:
- Testing & Polish:

**Confidence Level**:

### Out of Scope

-

### Risks & Mitigations

**Risk 1**:
- Likelihood:
- Impact:
- Mitigation:

### Acceptance Process

1.
2.

---

## Epic 3: [Epic Name]

<!-- Add as many epics as needed to cover all PRD requirements -->
<!-- Typical PRD decomposes into 3-7 epics -->
<!-- If you have >10 epics, consider whether they're properly sized -->

<!-- Repeat epic structure -->

---

## Epic Dependencies & Sequencing

<!-- This section visualizes how epics relate and the recommended order -->
<!-- Understanding dependencies helps with sprint planning and parallel work -->

### Dependency Diagram

\`\`\`
Epic 1: [Name] (Foundational - no dependencies)
  │
  ├─→ Epic 2: [Name] (Depends on Epic 1)
  │     │
  │     └─→ Epic 4: [Name] (Depends on Epic 2)
  │
  └─→ Epic 3: [Name] (Depends on Epic 1)

Epic 5: [Name] (Independent - can be done in parallel)
\`\`\`

### Recommended Sequence

<!-- Provide a concrete plan for tackling epics -->
<!-- Consider: dependencies, team capacity, business priorities, risk reduction -->

**Phase 1** (Sprints 1-3):
- Epic 1: [Name]
  - Rationale: [Why this comes first]
  - Example: "Must complete foundational authentication before other features can build on it"

**Phase 2** (Sprints 4-6):
- Epic 2: [Name] (Depends on Epic 1)
- Epic 3: [Name] (Depends on Epic 1) - Can run in parallel with Epic 2
  - Rationale: [Why these are next and can be parallel]

**Phase 3** (Sprints 7-9):
- Epic 4: [Name]
- Epic 5: [Name] - Can run in parallel with Epic 4
  - Rationale: [Why these come last]

**Critical Path**: Epic 1 → Epic 2 → Epic 4
<!-- The critical path determines minimum timeline -->

---

## Requirements Traceability Matrix

<!-- This ensures 100% coverage of PRD requirements across epics -->
<!-- Every requirement from the PRD must map to at least one epic -->

### Functional Requirements Coverage

| Requirement | Epic(s) | Coverage | Notes |
|-------------|---------|----------|-------|
| FR1: [Name] | Epic 1 | 100% | Fully covered |
| FR2: [Name] | Epic 1, Epic 2 | 100% | Split across two epics |
| FR3: [Name] | Epic 3 | 100% | |
| FR4: [Name] | Epic 2 | 50% | Partial: MVP only, full implementation in Phase 2 |

<!-- Add rows for all functional requirements from PRD -->

### Non-Functional Requirements Coverage

| Requirement | Epic(s) | Coverage | Notes |
|-------------|---------|----------|-------|
| NFR1: Performance | All Epics | 100% | Each epic includes performance testing |
| NFR2: Security | Epic 1, Epic 2 | 100% | Auth & data protection |
| NFR3: Reliability | All Epics | 100% | Error handling in each epic |
| NFR4: Usability | Epic 3, Epic 4 | 100% | |
| NFR5: Scalability | Epic 5 | 100% | Dedicated infrastructure epic |

<!-- Add rows for all non-functional requirements from PRD -->

### Coverage Summary

- **Total Functional Requirements**: [Count from PRD]
- **Requirements Fully Covered**: [Count]
- **Requirements Partially Covered**: [Count] - [Explain which and why]
- **Requirements Not Covered**: [Count] - [Explain which and why]
- **Overall Coverage**: [Percentage]

**Target**: 100% coverage of all "Must Have" requirements

---

## Sprint Planning Guidance

<!-- This section helps transition from epics to sprint execution -->

### Estimated Timeline

- **Total Epics**: [Count]
- **Estimated Duration**: [Total sprints needed]
  - Example: "5 epics, 12 sprints (24 weeks)"
- **Target Completion**: [Date based on sprint cadence]

### Team Capacity Assumptions

<!-- What assumptions about team capacity went into estimates? -->

- **Team Size**: [Number of engineers]
- **Sprint Length**: [Weeks per sprint]
- **Velocity**: [Story points or similar per sprint]
- **Availability**: [Any known constraints]
  - Example: "Assumes full team availability, accounts for holidays"

### Prerequisites for Sprint Planning

<!-- What needs to happen before we can start sprinting? -->

- [ ] All epics reviewed and approved by stakeholders
- [ ] Dependencies identified and coordinated
- [ ] Team capacity confirmed
- [ ] Technical approach validated for high-risk epics
- [ ] [Other prerequisites]

---

## Next Steps

<!-- Clear actions to move from epic breakdown to execution -->

### Immediate Actions

1. **Review with Stakeholders**
   - Schedule: [When]
   - Attendees: [Who needs to review]
   - Goal: [What you're seeking approval for]
   - Example: "Present epic breakdown to product leadership on [date] for approval"

2. **Refine Epic Boundaries**
   - Identify any overlaps or gaps between epics
   - Ensure each epic is independently deliverable
   - Validate effort estimates with engineering team

3. **Begin Spec Authoring**
   - Use SynthesisFlow spec-authoring skill to create detailed specs
   - Start with Epic 1 (foundational/highest priority)
   - Create one spec per epic or per major user story

4. **Coordinate Dependencies**
   - [Action for specific dependency]
   - Example: "Schedule kickoff with security team for Epic 1 review"
   - [Action for specific dependency]

### Transition to Execution

**Once epics are approved:**

1. Use **spec-authoring** skill to write detailed specifications for Epic 1
2. Use **sprint-planner** skill to decompose specs into GitHub issues
3. Begin Sprint 1 execution using **issue-executor** skill
4. After each epic completion, use **change-integrator** skill to update documentation

**Success Criteria for This Document**:
- [ ] All PRD requirements mapped to epics (100% coverage)
- [ ] Epic dependencies clearly identified and sequenced
- [ ] Effort estimates reviewed by engineering team
- [ ] Stakeholder approval obtained
- [ ] Ready to begin spec authoring for Epic 1

EOF

    echo "Successfully created epic decomposition at $epics_file"
    echo ""
    echo "Next steps:"
    echo "1. Review PRD requirements and group into logical epics"
    echo "2. Edit $epics_file to define each epic"
    echo "3. Map dependencies between epics"
    echo "4. Verify 100% requirements coverage"
    echo "5. Transition to spec-authoring workflow for each epic"
}

# --- GENERATE-SPEC COMMAND ---

function generate-spec() {
    local project_name=$1
    local epic_name=$2

    if [ -z "$project_name" ] || [ -z "$epic_name" ]; then
        echo "Error: Project name and epic name required for 'generate-spec' command." >&2
        echo "Usage: $0 generate-spec <project-name> <epic-name>" >&2
        exit 1
    fi

    check_prd_directory
    check_project_exists "$project_name"

    local project_dir="docs/prds/$project_name"
    local prd_file="$project_dir/prd.md"
    local epics_file="$project_dir/epics.md"

    # Validate PRD and epics exist
    if ! check_file_exists "$prd_file" "PRD"; then
        echo "Run 'create-prd' command first to create the PRD." >&2
        exit 1
    fi

    if ! check_file_exists "$epics_file" "Epic decomposition"; then
        echo "Run 'decompose' command first to create epic decomposition." >&2
        exit 1
    fi

    # Normalize epic name to kebab-case
    local epic_dir_name=$(to_kebab_case "$epic_name")
    local changes_dir="docs/changes/$epic_dir_name"

    echo "Generating spec proposal for epic: $epic_name"

    # Check if changes directory exists
    if [ ! -d "docs/changes" ]; then
        echo "Creating docs/changes directory..."
        mkdir -p "docs/changes"
    fi

    # Check if spec proposal already exists
    if [ -d "$changes_dir" ]; then
        echo "Error: Spec proposal directory '$changes_dir' already exists." >&2
        echo "Either use a different epic name or delete the existing directory." >&2
        exit 1
    fi

    # Create changes directory
    mkdir -p "$changes_dir"

    local today=$(get_date)

    # Extract epic information from epics.md
    # This is a simplified extraction - looks for the epic by searching for the epic name in headers
    local epic_found=0

    # Try to find the epic section in epics.md
    # We'll look for patterns like "## Epic N: <epic-name>" or just the epic name in headers
    if grep -qi "^## .*$epic_name" "$epics_file"; then
        epic_found=1
        echo "Found epic '$epic_name' in $epics_file"
    else
        echo "Warning: Could not find epic '$epic_name' in $epics_file" >&2
        echo "Generating generic spec proposal template. Please populate manually." >&2
    fi

    # Generate proposal.md
    cat > "$changes_dir/proposal.md" << EOF
---
title: $epic_name
type: spec-proposal
status: draft
prd: docs/prds/$project_name/prd.md
epic: $epic_name
created: $today
updated: $today
---

# Proposal: $epic_name

## Problem Statement

<!-- Extract from PRD and epic scope -->
<!-- What specific problem does this epic solve? -->
<!-- Reference the PRD objectives this epic supports -->

## Proposed Solution

<!-- High-level overview of what will be built -->
<!-- Based on the epic scope and requirements coverage -->

## Benefits

<!-- User benefits and business value -->
<!-- Connect to PRD success criteria -->

- **User Impact**: [How this improves user experience]
- **Business Value**: [How this supports business objectives]
- **Technical Impact**: [How this improves system architecture/quality]

## Success Criteria

<!-- Pull from epic success criteria in epics.md -->
<!-- Must be specific, measurable, and testable -->

**Functional Success**:
- [ ] [Criterion from epic]
- [ ] [Criterion from epic]

**Quality Success**:
- [ ] [Performance/quality target]
- [ ] [Security/reliability requirement]

**Business Success** (Measured post-launch):
- [ ] [Business metric target]

## Scope

**In Scope**:
<!-- Core features from epic scope -->
- [Feature/capability 1]
- [Feature/capability 2]
- [Feature/capability 3]

**Out of Scope**:
<!-- Explicitly excluded from this epic -->
- [Excluded feature/capability]
- [Deferred to future phase]

## Dependencies

<!-- From epic dependencies section -->

**Epic Dependencies**:
- [Other epic or requirement]

**Technical Dependencies**:
- [System/service/API requirement]

**Team Dependencies**:
- [Required reviews or approvals]

## Risks

<!-- From epic risks & mitigations section -->

**Risk 1**: [Description]
- Likelihood: [High/Medium/Low]
- Impact: [High/Medium/Low]
- Mitigation: [Strategy]

## Traceability

**PRD Reference**: docs/prds/$project_name/prd.md

**Requirements Coverage**:
<!-- List specific PRD requirements this epic addresses -->
- FR[N]: [Requirement name]
- NFR[N]: [Non-functional requirement]

**Success Metrics Mapping**:
<!-- Map to PRD success criteria -->
- [PRD metric]: [How this epic contributes]

EOF

    # Generate spec-delta.md
    cat > "$changes_dir/spec-delta.md" << EOF
---
title: $epic_name Specification
type: spec-delta
status: draft
prd: docs/prds/$project_name/prd.md
epic: $epic_name
created: $today
updated: $today
---

# Spec Delta: $epic_name

## Overview

<!-- High-level description of what this spec defines -->
<!-- Based on epic objective and scope -->

This specification defines the implementation requirements for the "$epic_name" epic from the $project_name PRD.

## Requirements

### Functional Requirements

<!-- Extract from PRD functional requirements that this epic covers -->
<!-- Each requirement from the epic's "Requirements Coverage" section should be detailed here -->

#### FR1: [Requirement Name]
- **Description**: [What this functionality does]
- **Inputs**: [What data or actions trigger this]
- **Outputs**: [What results or changes occur]
- **Business Rules**: [Constraints or special conditions]
- **Acceptance Criteria**:
  - [ ] [Specific, testable criterion]
  - [ ] [Specific, testable criterion]
  - [ ] [Specific, testable criterion]
- **Priority**: [Must Have / Should Have / Could Have]
- **PRD Reference**: FR[N] in docs/prds/$project_name/prd.md

#### FR2: [Requirement Name]
- **Description**:
- **Inputs**:
- **Outputs**:
- **Business Rules**:
- **Acceptance Criteria**:
  - [ ]
  - [ ]
- **Priority**:
- **PRD Reference**:

### Non-Functional Requirements

<!-- Extract from PRD non-functional requirements relevant to this epic -->

#### NFR1: Performance
- [Performance target from PRD]
- [Measurement method]
- **PRD Reference**: NFR[N] in docs/prds/$project_name/prd.md

#### NFR2: Security
- [Security requirement from PRD]
- [Compliance requirement]
- **PRD Reference**: NFR[N] in docs/prds/$project_name/prd.md

#### NFR3: Reliability
- [Reliability requirement from PRD]
- [Error handling requirement]
- **PRD Reference**: NFR[N] in docs/prds/$project_name/prd.md

#### NFR4: Usability
- [Usability requirement from PRD]
- [User experience requirement]
- **PRD Reference**: NFR[N] in docs/prds/$project_name/prd.md

## Design Decisions

<!-- Document key architectural and design choices -->

### DD1: [Decision Name]
**Decision**: [What was decided]

**Rationale**:
- [Reason for this approach]
- [How it supports epic objectives]

**Alternatives Considered**:
- [Alternative approach]: [Why rejected]

**Impact**: [Effect on system architecture or user experience]

### DD2: [Decision Name]
**Decision**:

**Rationale**:
-

**Alternatives Considered**:
-

**Impact**:

## Implementation Approach

<!-- High-level technical approach -->
<!-- Based on "Technical Approach" section from epic if present -->

### Architecture

[Describe component architecture, data flow, integration points]

### Components

**Component 1**: [Name/Purpose]
- Responsibilities: [What it does]
- Interfaces: [APIs or contracts]
- Dependencies: [What it depends on]

**Component 2**: [Name/Purpose]
- Responsibilities:
- Interfaces:
- Dependencies:

### Data Model

<!-- If applicable, describe data structures, database schema changes, API contracts -->

### Integration Points

<!-- External systems, APIs, services this integrates with -->

- [System/Service]: [Integration type and purpose]

## Testing Strategy

<!-- How this will be validated -->

### Unit Testing
- [What will be unit tested]
- Target coverage: [Percentage]

### Integration Testing
- [What integration scenarios to test]
- [Key workflows to validate]

### End-to-End Testing
- [User workflows to test]
- [Success criteria validation]

### Performance Testing
- [Performance benchmarks to validate]
- [Load testing approach]

## Migration Path

<!-- If applicable, how existing systems/data will be migrated -->

### For New Installations
[Approach for greenfield deployments]

### For Existing Systems
[Upgrade path, data migration, backward compatibility]

## Dependencies

<!-- Detailed dependency information -->

### Upstream Dependencies
<!-- What must exist before this can be implemented -->
- [Dependency]: [What's required and why]

### Downstream Impact
<!-- What will be affected by this implementation -->
- [Affected system/component]: [Nature of impact]

## Success Metrics

<!-- Specific metrics for this epic -->
<!-- Derived from epic success criteria and PRD metrics -->

### Launch Criteria
- [ ] [Specific launch requirement]
- [ ] [Specific launch requirement]

### Post-Launch Metrics
- **[Metric name]**: [Baseline] → [Target] within [timeframe]
- **[Metric name]**: [Baseline] → [Target] within [timeframe]

## Risks and Mitigations

<!-- From epic risks section -->

### Technical Risks
- **Risk**: [Description]
  - Likelihood: [High/Medium/Low]
  - Impact: [High/Medium/Low]
  - Mitigation: [Strategy]
  - Contingency: [Fallback plan]

### Schedule Risks
- **Risk**: [Description]
  - Mitigation: [Strategy]

## Traceability Matrix

<!-- Map spec requirements back to PRD -->

| Spec Requirement | PRD Requirement | Epic Section | Coverage |
|------------------|-----------------|--------------|----------|
| FR1 | FR[N] | [Section] | Complete |
| FR2 | FR[N] | [Section] | Partial |
| NFR1 | NFR[N] | [Section] | Complete |

**Coverage Summary**:
- Total PRD requirements in epic: [Count]
- Requirements addressed in spec: [Count]
- Coverage percentage: [Percentage]

EOF

    # Generate tasks.md
    cat > "$changes_dir/tasks.md" << EOF
---
title: $epic_name Tasks
type: task-breakdown
status: draft
prd: docs/prds/$project_name/prd.md
epic: $epic_name
created: $today
updated: $today
---

# Tasks: $epic_name

<!-- This task breakdown will be refined during sprint planning -->
<!-- Use epic "User Stories" section and requirements to identify tasks -->

## Overview

**Epic**: $epic_name
**PRD**: docs/prds/$project_name/prd.md
**Estimated Effort**: [From epic] sprints ([N] weeks)

## Task Breakdown

<!-- Break epic into implementable tasks -->
<!-- Each task should be completable in a few hours to a few days -->
<!-- Tasks should align with spec requirements -->

---

## Task 1: [Task Name]

<!-- Foundation or setup task -->

**Description**: [What needs to be done]

**Subtasks**:
- [ ] [Specific subtask]
- [ ] [Specific subtask]
- [ ] [Specific subtask]

**Acceptance Criteria**:
- [Specific, testable criterion]
- [Specific, testable criterion]

**Dependencies**:
- [What must be complete first]

**Estimated Effort**: [Hours or days]

**Related Requirements**: FR[N], NFR[N]

---

## Task 2: [Task Name]

<!-- Core implementation task -->

**Description**:

**Subtasks**:
- [ ]
- [ ]
- [ ]

**Acceptance Criteria**:
-
-

**Dependencies**:
- Task 1

**Estimated Effort**:

**Related Requirements**:

---

## Task 3: [Task Name]

<!-- Testing or integration task -->

**Description**:

**Subtasks**:
- [ ]
- [ ]

**Acceptance Criteria**:
-
-

**Dependencies**:
- Task 2

**Estimated Effort**:

**Related Requirements**:

---

## Task 4: [Task Name]

<!-- Documentation or polish task -->

**Description**:

**Subtasks**:
- [ ]
- [ ]

**Acceptance Criteria**:
-
-

**Dependencies**:
- Task 3

**Estimated Effort**:

**Related Requirements**:

---

## Summary

**Total Tasks**: [Count]
**Total Estimated Effort**: [Sum] hours/days
**Sprint Allocation**: [How tasks map to sprints]

### Task Dependencies

\`\`\`
Task 1 (Foundation)
  │
  ├─→ Task 2 (Core Implementation)
  │     │
  │     └─→ Task 3 (Integration)
  │
  └─→ Task 4 (Documentation) - Can run in parallel
\`\`\`

### Milestones

1. **Foundation Complete** (Task 1): [Description]
2. **Core Features** (Task 2): [Description]
3. **Integration Ready** (Task 3): [Description]
4. **Launch Ready** (Task 4): [Description]

## Next Steps

<!-- Actions to transition from tasks to execution -->

1. **Review and Refine**
   - Review task breakdown with team
   - Validate effort estimates
   - Identify any missing tasks

2. **Sprint Planning**
   - Use sprint-planner skill to create GitHub issues
   - Allocate tasks across sprint(s)
   - Assign team members

3. **Begin Execution**
   - Use issue-executor skill to start implementation
   - Track progress through GitHub issues
   - Update task status as work completes

## Traceability

**Epic**: $epic_name in docs/prds/$project_name/epics.md
**PRD**: docs/prds/$project_name/prd.md
**Spec**: docs/changes/$epic_dir_name/spec-delta.md

**Requirements Covered**:
<!-- List all PRD requirements addressed by these tasks -->
- FR[N]: [Requirement name] - Tasks [N, N, N]
- NFR[N]: [Requirement name] - Tasks [N, N]

EOF

    echo "Successfully generated spec proposal in $changes_dir"
    echo ""
    echo "Generated files:"
    echo "  - $changes_dir/proposal.md"
    echo "  - $changes_dir/spec-delta.md"
    echo "  - $changes_dir/tasks.md"
    echo ""
    echo "Next steps:"
    echo "1. Review and populate the generated files with epic details from $epics_file"
    echo "2. Extract requirements from the epic section in epics.md"
    echo "3. Link spec requirements back to PRD requirements"
    echo "4. Validate traceability from spec to PRD"
    echo "5. Open a Spec PR using spec-authoring workflow"
}

# --- MAIN ---

COMMAND=$1
shift || true

case "$COMMAND" in
    status)
        status "$@"
        ;;
    brief)
        brief "$@"
        ;;
    research)
        research "$@"
        ;;
    create-prd)
        create-prd "$@"
        ;;
    validate-prd)
        validate-prd "$@"
        ;;
    decompose)
        decompose "$@"
        ;;
    generate-spec)
        generate-spec "$@"
        ;;
    *)
        echo "Error: Unknown command '$COMMAND'" >&2
        echo "Usage: $0 {status|brief|research|create-prd|validate-prd|decompose|generate-spec} ..." >&2
        echo "" >&2
        echo "Commands:" >&2
        echo "  status [project-name]                      - Assess project readiness and show next steps" >&2
        echo "  brief <project-name>                       - Create product brief template" >&2
        echo "  research <project-name>                    - Create research template" >&2
        echo "  create-prd <project-name>                  - Create PRD template" >&2
        echo "  validate-prd <project-name> [--lenient]    - Validate PRD quality" >&2
        echo "  decompose <project-name>                   - Break PRD into epics" >&2
        echo "  generate-spec <project-name> <epic-name>   - Generate spec proposal from epic" >&2
        exit 1
        ;;
esac