specpulse 1.4.1__py3-none-any.whl → 1.4.2__py3-none-any.whl

specpulse/resources/commands/gemini/sp-spec.toml

@@ -1,52 +1,97 @@
-description = "Create or manage feature specifications with versioning"
+description = "Create or manage feature specifications using AI-optimized templates"
 prompt = """
-Handle the /sp-spec command with arguments: {{args}}
-
-First, detect current feature context:
-- Read memory/context.md for current feature metadata
-- Use git branch name if available (e.g., 001-user-authentication)
-- Fall back to most recently created feature directory
-- If no context found, ask user to specify feature or run /sp-pulse first
-
-Parse the arguments to determine the action:
-- If starts with "create": Generate new specification
-- If starts with "update": Modify existing specification  
-- If starts with "validate": Check specification completeness
-- If no action specified: Default to "create" with full arguments as description
-
-## For /sp-spec create [description] or /sp-spec [description]:
-1. Read template from @{templates/spec.md}
-2. Parse the description to identify:
-   - Functional requirements (Must/Should/Could have)
-   - User stories and acceptance criteria
-   - Technical requirements
-3. Mark any uncertainties with [NEEDS CLARIFICATION: detail]
-4. Find current feature directory from detected context
-5. Check existing spec files and create next version (spec-001.md, spec-002.md, etc.)
-6. Write specification to specs/XXX-feature/spec-XXX.md
-7. Run validation:
-   - !{bash scripts/sp-pulse-spec.sh "XXX-feature"}
-
-## For /sp-spec update:
-1. Show list of existing spec files in current feature directory
-2. Ask user which spec file to update
-3. Read selected specification file
-4. Ask user for clarifications or changes
-5. Update content while preserving structure
-6. Remove resolved [NEEDS CLARIFICATION] markers
-
-## For /sp-spec validate:
-1. Show list of existing spec files in current feature directory
-2. Ask user which spec file to validate
-3. Run validation:
-   - !{bash scripts/sp-pulse-spec.sh "XXX-feature"}
-4. Check all required sections are filled
-5. Count [NEEDS CLARIFICATION] markers
-6. Verify acceptance criteria are testable
-7. Report validation results
+## CRITICAL FILE EDIT RESTRICTIONS
+**NEVER EDIT:** templates/, scripts/, commands/, .claude/, .gemini/
+**ONLY EDIT:** specs/, plans/, tasks/, memory/
+Templates are COPIED to specs/ folder, then edited there
+
+## Command: /sp-spec {{args}}
+
+Create, update, or validate feature specifications using SpecPulse methodology.
+
+Actions: create, update, validate, clarify (defaults to create)
+
+### Implementation Steps:
+
+1. **Detect current feature context**:
+   - Read memory/context.md for current feature metadata
+   - Use git branch name if available (e.g., 001-user-authentication)
+   - Fall back to most recently created feature directory
+   - If no context found, ask user to specify feature or run /sp-pulse first
+
+2. **Parse arguments** to determine action:
+   - If starts with 'create': Generate new specification
+   - If starts with 'update': Modify existing specification
+   - If starts with 'validate': Check specification completeness
+   - If starts with 'clarify': Address [NEEDS CLARIFICATION] markers
+   - Default to 'create' with full arguments as description
+
+3. **Run specification script**:
+   - !{bash scripts/sp-pulse-spec.sh "{{args}}"}
+
+4. **For 'create' action**:
+   - Read template from @{templates/spec.md}
+   - Parse description to identify:
+     * Functional requirements (Must/Should/Could/Won't have)
+     * User stories with testable acceptance criteria
+     * Non-functional requirements (performance, security, scalability)
+     * Technical constraints and dependencies
+   - Fill template with AI-generated content
+   - Mark unclear items with [NEEDS CLARIFICATION]
+   - Create numbered spec file (spec-001.md, spec-002.md, etc.)
+   - Save to specs/XXX-feature/spec-XXX.md
+
+5. **Generate comprehensive specification**:
+   - Executive Summary
+   - Problem Statement
+   - Proposed Solution
+   - Functional Requirements (FR-001, FR-002, etc.)
+   - Non-Functional Requirements (performance, security, scalability)
+   - User Stories with acceptance criteria
+   - Technical Constraints
+   - Dependencies
+   - Risks and Mitigations
+   - Success Criteria
+   - Open Questions marked with [NEEDS CLARIFICATION]
+
+6. **For 'update' action**:
+   - Show list of existing spec files
+   - Ask user which spec file to update
+   - Read selected specification
+   - Ask for clarifications or changes
+   - Update content while preserving structure
+   - Remove resolved [NEEDS CLARIFICATION] markers
+
+7. **For 'validate' action**:
+   - Show list of existing spec files
+   - Run validation script
+   - Check all required sections are filled
+   - Count [NEEDS CLARIFICATION] markers
+   - Verify acceptance criteria are testable
+   - Report validation results
+
+8. **Update context and validate**:
+   - Update memory/context.md with specification status
+   - Check SDD compliance (Principle 1: Specification First)
+   - Validate all sections are filled
+   - Report any missing or incomplete sections
+
+### Example AI-Generated Content:
+For "User authentication with OAuth2":
+- FR-001: System SHALL support OAuth2 authentication with Google/GitHub
+- FR-002: System SHALL issue JWT tokens valid for 24 hours
+- NFR-001: Authentication response time < 200ms
+- User Story: As a user, I want to login with Google so that I don't need to remember another password
+
+### SDD Compliance Checklist:
+- [ ] Every requirement is testable (Principle 1)
+- [ ] User stories have clear acceptance criteria (Principle 1)
+- [ ] Dependencies are identified (Principle 4)
+- [ ] Success metrics defined (Principle 6)
 
 Examples:
 - /sp-spec user authentication with OAuth2 and email/password
 - /sp-spec update
 - /sp-spec validate
+- /sp-spec clarify
 """

specpulse/resources/scripts/sp-pulse-decompose.ps1

@@ -0,0 +1,74 @@
+# SpecPulse Decomposition Orchestrator - PowerShell Version
+# Validates decomposition request and returns status for AI processing
+
+param(
+    [Parameter(Mandatory=$false, Position=0)]
+    [string]$SpecId,
+
+    [Parameter(Mandatory=$false, Position=1)]
+    [string]$Action = "validate"
+)
+
+# Configuration
+$ScriptDir = Split-Path -Parent $PSCommandPath
+$ProjectRoot = Split-Path -Parent $ScriptDir
+
+# Colors for output
+$Green = "Green"
+$Yellow = "Yellow"
+
+Write-Host "[SpecPulse Decompose]" -ForegroundColor $Green -NoNewline
+Write-Host " Processing spec: $($SpecId ?? 'current')"
+
+# Find specification
+if ([string]::IsNullOrEmpty($SpecId)) {
+    $specDirs = Get-ChildItem -Path "$ProjectRoot\specs" -Directory -ErrorAction SilentlyContinue |
+                Sort-Object Name -Descending |
+                Select-Object -First 1
+    $SpecDir = if ($specDirs) { $specDirs.FullName } else { $null }
+} else {
+    $specDirs = Get-ChildItem -Path "$ProjectRoot\specs" -Directory -Filter "${SpecId}*" -ErrorAction SilentlyContinue |
+                Select-Object -First 1
+    $SpecDir = if ($specDirs) { $specDirs.FullName } else { $null }
+}
+
+if (-not $SpecDir -or -not (Test-Path $SpecDir)) {
+    Write-Host "ERROR: No specification found" -ForegroundColor Red
+    Write-Host "SUGGESTION: Run /sp-spec create first"
+    exit 1
+}
+
+# Check complexity (simple heuristic)
+$specFiles = Get-ChildItem -Path $SpecDir -Filter "spec-*.md" -ErrorAction SilentlyContinue |
+             Sort-Object Name |
+             Select-Object -Last 1
+
+if ($specFiles) {
+    $SpecFile = $specFiles.FullName
+    $LineCount = (Get-Content $SpecFile | Measure-Object -Line).Lines
+
+    Write-Output "SPEC_FILE=$SpecFile"
+    Write-Output "COMPLEXITY=$LineCount lines"
+
+    if ($LineCount -gt 100) {
+        Write-Output "RECOMMENDATION=Decomposition advised (complex spec)"
+    } else {
+        Write-Output "RECOMMENDATION=Single service may suffice"
+    }
+}
+
+# Check for existing decomposition
+$DecompositionPath = Join-Path $SpecDir "decomposition"
+if (Test-Path $DecompositionPath) {
+    Write-Output "STATUS=Decomposition exists"
+    Write-Output "PATH=$DecompositionPath"
+} else {
+    Write-Output "STATUS=Ready for decomposition"
+    Write-Output "PATH=$SpecDir"
+}
+
+# Return template paths for AI
+Write-Output "TEMPLATES_DIR=templates/decomposition"
+Write-Output "MEMORY_FILE=memory/context.md"
+
+exit 0

specpulse/resources/scripts/sp-pulse-execute.ps1

@@ -0,0 +1,177 @@
+# Execute tasks continuously from task list - PowerShell Version
+
+param(
+    [Parameter(Mandatory=$false, Position=0)]
+    [string]$Command = "next",
+
+    [Parameter(Mandatory=$false, Position=1)]
+    [string]$FeatureDir
+)
+
+# Configuration
+$ScriptName = Split-Path -Leaf $PSCommandPath
+$ScriptDir = Split-Path -Parent $PSCommandPath
+$ProjectRoot = Split-Path -Parent $ScriptDir
+
+# Logging function
+function Log-Message {
+    param([string]$Message)
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    Write-Host "[$timestamp] ${ScriptName}: $Message" -ForegroundColor Cyan
+}
+
+# Error handling function
+function Exit-WithError {
+    param([string]$Message)
+    Write-Host "ERROR: $Message" -ForegroundColor Red
+    exit 1
+}
+
+# Find active feature if not provided
+if ([string]::IsNullOrEmpty($FeatureDir)) {
+    $ContextFile = Join-Path $ProjectRoot "memory\context.md"
+    if (Test-Path $ContextFile) {
+        # Extract active feature from context
+        $contextContent = Get-Content $ContextFile -Raw
+        if ($contextContent -match "Active Feature:\s*(.+)") {
+            $FeatureName = $matches[1].Trim()
+        }
+        if ($contextContent -match "Feature ID:\s*(.+)") {
+            $FeatureId = $matches[1].Trim()
+        }
+
+        if ($FeatureId -and $FeatureName) {
+            # Convert to branch name format
+            $BranchSafeName = $FeatureName.ToLower() -replace '[^a-z0-9-]', '-' -replace '--+', '-' -replace '^-|-$', ''
+            $FeatureDir = "$FeatureId-$BranchSafeName"
+            Log-Message "Using active feature: $FeatureDir"
+        } else {
+            Exit-WithError "No active feature found in context file"
+        }
+    } else {
+        Exit-WithError "No feature directory provided and no context file found"
+    }
+}
+
+$TaskDir = Join-Path $ProjectRoot "tasks\$FeatureDir"
+
+# Ensure tasks directory exists
+if (-not (Test-Path $TaskDir)) {
+    Exit-WithError "Tasks directory not found: $TaskDir"
+}
+
+# Find latest task file
+$taskFiles = Get-ChildItem -Path $TaskDir -Filter "*.md" -ErrorAction SilentlyContinue |
+             Sort-Object LastWriteTime -Descending |
+             Select-Object -First 1
+
+if (-not $taskFiles) {
+    Exit-WithError "No task files found in $TaskDir"
+}
+
+$TaskFile = $taskFiles.FullName
+Log-Message "Analyzing task file: $TaskFile"
+
+# Read task content
+$taskContent = Get-Content $TaskFile -Raw
+
+# Detect if decomposed (service-specific tasks)
+$IsDecomposed = $false
+if ($taskContent -match "AUTH-T[0-9]|USER-T[0-9]|INT-T[0-9]") {
+    $IsDecomposed = $true
+    Log-Message "Detected decomposed architecture with service-specific tasks"
+}
+
+# Count task status using regex
+$taskPattern = '^- \[.\] (T[0-9]{3}|[A-Z]+-T[0-9]{3})'
+$allTasks = [regex]::Matches($taskContent, $taskPattern, [System.Text.RegularExpressions.RegexOptions]::Multiline)
+$TotalTasks = $allTasks.Count
+
+$CompletedTasks = ([regex]::Matches($taskContent, '^- \[x\] (T[0-9]{3}|[A-Z]+-T[0-9]{3})', [System.Text.RegularExpressions.RegexOptions]::Multiline)).Count
+$PendingTasks = ([regex]::Matches($taskContent, '^- \[ \] (T[0-9]{3}|[A-Z]+-T[0-9]{3})', [System.Text.RegularExpressions.RegexOptions]::Multiline)).Count
+$InProgressTasks = ([regex]::Matches($taskContent, '^- \[>\] (T[0-9]{3}|[A-Z]+-T[0-9]{3})', [System.Text.RegularExpressions.RegexOptions]::Multiline)).Count
+$BlockedTasks = ([regex]::Matches($taskContent, '^- \[!\] (T[0-9]{3}|[A-Z]+-T[0-9]{3})', [System.Text.RegularExpressions.RegexOptions]::Multiline)).Count
+
+# Find next task to execute
+$NextTask = ""
+$TaskDetails = ""
+
+switch ($Command) {
+    { $_ -in "next", "continue" } {
+        # Find first in-progress task
+        $inProgressMatch = [regex]::Match($taskContent, '^- \[>\] ((T[0-9]{3}|[A-Z]+-T[0-9]{3}): .+)$', [System.Text.RegularExpressions.RegexOptions]::Multiline)
+        if ($inProgressMatch.Success) {
+            $NextTask = $inProgressMatch.Groups[1].Value
+            $TaskDetails = "RESUMING IN-PROGRESS TASK"
+        } else {
+            # Find first pending task
+            $pendingMatch = [regex]::Match($taskContent, '^- \[ \] ((T[0-9]{3}|[A-Z]+-T[0-9]{3}): .+)$', [System.Text.RegularExpressions.RegexOptions]::Multiline)
+            if ($pendingMatch.Success) {
+                $NextTask = $pendingMatch.Groups[1].Value
+                $TaskDetails = "STARTING NEW TASK"
+            }
+        }
+    }
+    "all" {
+        if ($PendingTasks -gt 0 -or $InProgressTasks -gt 0) {
+            $NextTask = "ALL_REMAINING"
+            $TaskDetails = "EXECUTE ALL TASKS WITHOUT STOPPING"
+        }
+    }
+    default {
+        # Specific task requested
+        $specificMatch = [regex]::Match($taskContent, "^- \[.\] (($Command): .+)$", [System.Text.RegularExpressions.RegexOptions]::Multiline)
+        if ($specificMatch.Success) {
+            $NextTask = $specificMatch.Groups[1].Value
+            $TaskDetails = "EXECUTE SPECIFIC TASK"
+        }
+    }
+}
+
+# Calculate progress
+if ($TotalTasks -gt 0) {
+    $Progress = [math]::Round(($CompletedTasks / $TotalTasks) * 100)
+} else {
+    $Progress = 0
+}
+
+# Output status
+Write-Output "TASK_FILE=$TaskFile"
+Write-Output "TOTAL_TASKS=$TotalTasks"
+Write-Output "COMPLETED_TASKS=$CompletedTasks"
+Write-Output "PENDING_TASKS=$PendingTasks"
+Write-Output "IN_PROGRESS_TASKS=$InProgressTasks"
+Write-Output "BLOCKED_TASKS=$BlockedTasks"
+Write-Output "PROGRESS=$Progress%"
+
+if ($IsDecomposed) {
+    Write-Output "ARCHITECTURE=Microservices"
+} else {
+    Write-Output "ARCHITECTURE=Monolithic"
+}
+
+if ($NextTask) {
+    Write-Output "NEXT_TASK=$NextTask"
+    Write-Output "ACTION=$TaskDetails"
+    if ($Command -eq "all") {
+        Write-Output "MODE=CONTINUOUS"
+        Write-Output "INSTRUCTION=Execute all tasks without stopping, no explanations between tasks"
+    } else {
+        Write-Output "MODE=SINGLE"
+        Write-Output "INSTRUCTION=Execute this task and report results"
+    }
+} else {
+    if ($CompletedTasks -eq $TotalTasks -and $TotalTasks -gt 0) {
+        Write-Output "STATUS=ALL_COMPLETE"
+        Write-Output "MESSAGE=Congratulations! All tasks have been completed!"
+    } elseif ($BlockedTasks -gt 0) {
+        Write-Output "STATUS=BLOCKED"
+        Write-Output "MESSAGE=All remaining tasks are blocked. Resolve blockers first."
+    } else {
+        Write-Output "STATUS=NO_TASKS"
+        Write-Output "MESSAGE=No tasks available to execute"
+    }
+}
+
+Log-Message "Task analysis complete"
+exit 0

specpulse/resources/scripts/sp-pulse-init.ps1

@@ -61,23 +61,48 @@ try {
     Exit-WithError "Failed to create directories: $_"
 }
 
-# Create initial files from templates
+# Validate templates exist but don't copy them directly
 $TemplateDir = Join-Path $ProjectRoot "templates"
 
-$specTemplate = Join-Path $TemplateDir "spec.md"
-$planTemplate = Join-Path $TemplateDir "plan.md"
-$taskTemplate = Join-Path $TemplateDir "task.md"
-
-if (-not (Test-Path $specTemplate)) {
-    Exit-WithError "Template not found: $specTemplate"
+# Validate all required templates exist
+@("spec.md", "plan.md", "task.md") | ForEach-Object {
+    $templatePath = Join-Path $TemplateDir $_
+    if (-not (Test-Path $templatePath)) {
+        Exit-WithError "Template not found: $templatePath. Please run 'specpulse init' to initialize templates."
+    }
 }
 
+# Create marker files that indicate AI should use templates to generate content
+# These are placeholder files that will be replaced by AI-generated content
 try {
-    Copy-Item -Path $specTemplate -Destination "$SpecsDir\spec-$FeatureId.md" -Force
-    Copy-Item -Path $planTemplate -Destination "$PlansDir\plan-$FeatureId.md" -Force
-    Copy-Item -Path $taskTemplate -Destination "$TasksDir\task-$FeatureId.md" -Force
+    $specContent = @"
+# Specification for $FeatureName
+
+<!-- TO BE GENERATED FROM TEMPLATE: $TemplateDir\spec.md -->
+<!-- FEATURE: $FeatureName -->
+<!-- ID: $FeatureId -->
+"@
+    Set-Content -Path "$SpecsDir\spec-001.md" -Value $specContent
+
+    $planContent = @"
+# Implementation Plan for $FeatureName
+
+<!-- TO BE GENERATED FROM TEMPLATE: $TemplateDir\plan.md -->
+<!-- FEATURE: $FeatureName -->
+<!-- ID: $FeatureId -->
+"@
+    Set-Content -Path "$PlansDir\plan-001.md" -Value $planContent
+
+    $taskContent = @"
+# Task Breakdown for $FeatureName
+
+<!-- TO BE GENERATED FROM TEMPLATE: $TemplateDir\task.md -->
+<!-- FEATURE: $FeatureName -->
+<!-- ID: $FeatureId -->
+"@
+    Set-Content -Path "$TasksDir\task-001.md" -Value $taskContent
 } catch {
-    Exit-WithError "Failed to copy templates: $_"
+    Exit-WithError "Failed to create marker files: $_"
 }
 
 # Update context

specpulse/resources/scripts/sp-pulse-init.sh

@@ -55,16 +55,37 @@ mkdir -p "$SPECS_DIR" || error_exit "Failed to create specs directory: $SPECS_DI
 mkdir -p "$PLANS_DIR" || error_exit "Failed to create plans directory: $PLANS_DIR"
 mkdir -p "$TASKS_DIR" || error_exit "Failed to create tasks directory: $TASKS_DIR"
 
-# Create initial files from templates
+# Validate templates exist but don't copy them directly
 TEMPLATE_DIR="$PROJECT_ROOT/templates"
 
-if [ ! -f "$TEMPLATE_DIR/spec.md" ]; then
-    error_exit "Template not found: $TEMPLATE_DIR/spec.md"
-fi
-
-cp "$TEMPLATE_DIR/spec.md" "$SPECS_DIR/spec-${FEATURE_ID}.md" || error_exit "Failed to copy spec template"
-cp "$TEMPLATE_DIR/plan.md" "$PLANS_DIR/plan-${FEATURE_ID}.md" || error_exit "Failed to copy plan template"
-cp "$TEMPLATE_DIR/task.md" "$TASKS_DIR/task-${FEATURE_ID}.md" || error_exit "Failed to copy task template"
+# Validate all required templates exist
+for template in spec.md plan.md task.md; do
+    if [ ! -f "$TEMPLATE_DIR/$template" ]; then
+        error_exit "Template not found: $TEMPLATE_DIR/$template. Please run 'specpulse init' to initialize templates."
+    fi
+done
+
+# Create marker files that indicate AI should use templates to generate content
+# These are placeholder files that will be replaced by AI-generated content
+echo "# Specification for $FEATURE_NAME" > "$SPECS_DIR/spec-001.md"
+echo "# Implementation Plan for $FEATURE_NAME" > "$PLANS_DIR/plan-001.md"
+echo "# Task Breakdown for $FEATURE_NAME" > "$TASKS_DIR/task-001.md"
+
+# Add markers indicating these files need AI processing
+echo "" >> "$SPECS_DIR/spec-001.md"
+echo "<!-- TO BE GENERATED FROM TEMPLATE: $TEMPLATE_DIR/spec.md -->" >> "$SPECS_DIR/spec-001.md"
+echo "<!-- FEATURE: $FEATURE_NAME -->" >> "$SPECS_DIR/spec-001.md"
+echo "<!-- ID: $FEATURE_ID -->" >> "$SPECS_DIR/spec-001.md"
+
+echo "" >> "$PLANS_DIR/plan-001.md"
+echo "<!-- TO BE GENERATED FROM TEMPLATE: $TEMPLATE_DIR/plan.md -->" >> "$PLANS_DIR/plan-001.md"
+echo "<!-- FEATURE: $FEATURE_NAME -->" >> "$PLANS_DIR/plan-001.md"
+echo "<!-- ID: $FEATURE_ID -->" >> "$PLANS_DIR/plan-001.md"
+
+echo "" >> "$TASKS_DIR/task-001.md"
+echo "<!-- TO BE GENERATED FROM TEMPLATE: $TEMPLATE_DIR/task.md -->" >> "$TASKS_DIR/task-001.md"
+echo "<!-- FEATURE: $FEATURE_NAME -->" >> "$TASKS_DIR/task-001.md"
+echo "<!-- ID: $FEATURE_ID -->" >> "$TASKS_DIR/task-001.md"
 
 # Update context
 CONTEXT_FILE="$PROJECT_ROOT/memory/context.md"

specpulse/resources/scripts/sp-pulse-plan.sh

@@ -41,8 +41,13 @@ PLAN_DIR="$PROJECT_ROOT/plans/${FEATURE_DIR}"
 SPEC_DIR="$PROJECT_ROOT/specs/${FEATURE_DIR}"
 TEMPLATE_FILE="$PROJECT_ROOT/templates/plan.md"
 
+# Validate template file exists before proceeding
+if [ ! -f "$TEMPLATE_FILE" ]; then
+    error_exit "Template not found: $TEMPLATE_FILE. Please ensure templates are properly initialized."
+fi
+
 # Ensure plans directory exists
-mkdir -p "$PLAN_DIR"
+mkdir -p "$PLAN_DIR" || error_exit "Failed to create plans directory: $PLAN_DIR"
 
 # Find latest spec file
 if [ -d "$SPEC_DIR" ]; then
@@ -56,8 +61,13 @@ fi
 
 # Find next available plan number or create new one
 if [ -d "$PLAN_DIR" ]; then
-    existing_plans=$(find "$PLAN_DIR" -name "plan-*.md" | wc -l)
-    plan_number=$((existing_plans + 1))
+    # Get the highest plan number and increment it
+    highest_plan=$(find "$PLAN_DIR" -name "plan-*.md" -exec basename {} .md \; | sed 's/plan-//' | sort -n | tail -1)
+    if [ -n "$highest_plan" ]; then
+        plan_number=$((highest_plan + 1))
+    else
+        plan_number=1
+    fi
 else
     plan_number=1
 fi
@@ -68,25 +78,40 @@ if [ ! -f "$TEMPLATE_FILE" ]; then
     error_exit "Template not found: $TEMPLATE_FILE"
 fi
 
-# Create plan
-log "Creating implementation plan from template: $PLAN_FILE"
-cp "$TEMPLATE_FILE" "$PLAN_FILE" || error_exit "Failed to copy plan template"
+# Create plan marker for AI generation
+log "Creating implementation plan marker: $PLAN_FILE"
+echo "# Implementation Plan - $FEATURE_DIR" > "$PLAN_FILE"
+echo "" >> "$PLAN_FILE"
+echo "<!-- AI: Please generate plan using template: $TEMPLATE_FILE -->" >> "$PLAN_FILE"
+echo "<!-- SPEC_FILE: $SPEC_FILE -->" >> "$PLAN_FILE"
+echo "<!-- FEATURE_DIR: $FEATURE_DIR -->" >> "$PLAN_FILE"
+echo "<!-- FEATURE_ID: $FEATURE_ID -->" >> "$PLAN_FILE"
+echo "" >> "$PLAN_FILE"
+echo "## Awaiting AI Generation" >> "$PLAN_FILE"
+echo "This plan needs to be generated from the template based on specification: $SPEC_FILE" >> "$PLAN_FILE"
 
 # Validate plan structure
 log "Validating implementation plan..."
 
-# Check for required sections
-REQUIRED_SECTIONS=("## Implementation Plan:" "## Specification Reference" "## Phase -1: Pre-Implementation Gates" "## Implementation Phases")
-MISSING_SECTIONS=()
-
-for section in "${REQUIRED_SECTIONS[@]}"; do
-    if ! grep -q "$section" "$PLAN_FILE"; then
-        MISSING_SECTIONS+=("$section")
+# Check if file needs AI generation
+if grep -q "Awaiting AI Generation" "$PLAN_FILE"; then
+    log "WARNING: Plan needs to be generated by AI from template"
+    MISSING_SECTIONS=("ALL - Awaiting AI Generation")
+    GATE_STATUS="PENDING"
+else
+    # Check for required sections only if file has been generated
+    REQUIRED_SECTIONS=("## Implementation Plan:" "## Specification Reference" "## Phase -1: Pre-Implementation Gates" "## Implementation Phases")
+    MISSING_SECTIONS=()
+
+    for section in "${REQUIRED_SECTIONS[@]}"; do
+        if ! grep -q "$section" "$PLAN_FILE"; then
+            MISSING_SECTIONS+=("$section")
+        fi
+    done
+
+    if [ ${#MISSING_SECTIONS[@]} -gt 0 ]; then
+        log "WARNING: Missing required sections: ${MISSING_SECTIONS[*]}"
     fi
-done
-
-if [ ${#MISSING_SECTIONS[@]} -gt 0 ]; then
-    log "WARNING: Missing required sections: ${MISSING_SECTIONS[*]}"
 fi
 
 # Check SDD Gates