/plan

<!-- ATTRIBUTION CHAIN: 1. Original: GitHub spec-kit (https://github.com/github/spec-kit) Copyright (c) GitHub, Inc. | MIT License 2. Adapted: SpecKit plugin by Marty Bonacci (2025) 3. Forked: SpecSwarm plugin with tech stack management by Marty Bonacci & Claude Code (2025) -->

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

1. Discover Feature Context:

   a. Find Repository Root and Initialize Features Directory:

   REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
   
   # Source features location helper
   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
   source "$PLUGIN_DIR/lib/features-location.sh"
   
   # Initialize features directory (handles migration if needed)
   get_features_dir "$REPO_ROOT"
   

   b. Get Current Feature:

   BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
   FEATURE_NUM=$(echo "$BRANCH" | grep -oE '^[0-9]{3}')
   
   # Fallback for non-git
   if [ -z "$FEATURE_NUM" ]; then
     FEATURE_NUM=$(list_features "$REPO_ROOT" | grep -oE '^[0-9]{3}' | sort -nr | head -1)
   fi
   

   c. Locate Feature Directory:

   find_feature_dir "$FEATURE_NUM" "$REPO_ROOT"
   # FEATURE_DIR is now set by find_feature_dir
   

   d. Set Path Variables:

   FEATURE_SPEC="${FEATURE_DIR}/spec.md"
   IMPL_PLAN="${FEATURE_DIR}/plan.md"
   RESEARCH_FILE="${FEATURE_DIR}/research.md"
   DATA_MODEL_FILE="${FEATURE_DIR}/data-model.md"
   CONTRACTS_DIR="${FEATURE_DIR}/contracts"
   

   e. Validate Prerequisites:

   • Check that spec.md exists
   • If missing: ERROR "No specification found. Run /specify first."

2. Load context:

   • Read FEATURE_SPEC (spec.md)
   • Read .specswarm/constitution.md if it exists
   • Check for .specswarm/tech-stack.md
   • Load plan template from templates/plan-template.md or use embedded template

<!-- ========== TECH STACK MANAGEMENT (SpecSwarm Enhancement) ========== --> <!-- Added by Marty Bonacci & Claude Code (2025) -->

2a. Tech Stack File Initialization (first-time setup):

Check if tech stack file exists:

if [ ! -f "${REPO_ROOT}.specswarm/tech-stack.md" ]; then
  FIRST_FEATURE=true
else
  FIRST_FEATURE=false
fi

If FIRST_FEATURE=true (no tech-stack.md exists):

1. Detect project technologies (scan existing files):

   # Check for package managers and extract dependencies
   if [ -f "${REPO_ROOT}/package.json" ]; then
     # Node.js/TypeScript project
     LANGUAGE=$(grep -q "typescript" "${REPO_ROOT}/package.json" && echo "TypeScript" || echo "JavaScript")
     RUNTIME="Node.js"
     # Extract frameworks and libraries from dependencies
   elif [ -f "${REPO_ROOT}/composer.json" ]; then
     # PHP project
     LANGUAGE="PHP"
   elif [ -f "${REPO_ROOT}/requirements.txt" ] || [ -f "${REPO_ROOT}/pyproject.toml" ]; then
     # Python project
     LANGUAGE="Python"
   elif [ -f "${REPO_ROOT}/go.mod" ]; then
     # Go project
     LANGUAGE="Go"
   elif [ -f "${REPO_ROOT}/Gemfile" ]; then
     # Ruby project
     LANGUAGE="Ruby"
   fi
   

2. Generate tech-stack.md using template:

   • Use /templates/tech-stack-template.md if exists
   • Otherwise use embedded template with detected technologies
   • Populate Core Technologies section from detection
   • Populate Standard Libraries from package files
   • Leave Prohibited Technologies section with TODO marker and common examples

3. Present to user for confirmation:

   🎯 TECH STACK FILE CREATED
   
   This is your FIRST feature using SpecSwarm. I've created `.specswarm/tech-stack.md`
   based on your project files and plan.md Technical Context.
   
   **Detected Stack:**
   - Language: {detected_language}
   - Framework: {detected_framework}
   - Database: {detected_database}
   - Key Libraries: {detected_libraries}
   
   **Action Required:**
   1. Review `.specswarm/tech-stack.md`
   2. Add any PROHIBITED technologies (important for drift prevention!)
   3. Confirm accuracy of detected stack
   
   ⚠️ This file will be used to validate ALL future features.
   
   **Options:**
   - Type "continue" to accept and proceed with planning
   - Type "edit" to pause while you refine tech-stack.md
   - Provide corrections: "Language should be JavaScript, not TypeScript"
   

4. Wait for user response:

   • If "continue": Proceed to section 2b (Tech Stack Validation)
   • If "edit": PAUSE with message "Run /specswarm:plan again when ready"
   • If corrections provided: Update tech-stack.md, show updated version, ask for confirmation again

5. Add reminder to constitution (if constitution exists):

   • Append note to constitution.md suggesting Principle 5 formalization
   • Message: "💡 Consider running /specswarm:constitution to formalize tech stack enforcement as Principle 5"

If FIRST_FEATURE=false (tech-stack.md already exists):

• Skip initialization entirely
• Proceed directly to section 2b (Tech Stack Validation)

If auto-detection fails (no package files found):

• Prompt user for manual input:

  🎯 TECH STACK FILE NEEDED
  
  Cannot auto-detect technologies. Please provide:
  1. Programming language and version (e.g., "TypeScript 5.x")
  2. Main framework (e.g., "React Router v7")
  3. Database (e.g., "PostgreSQL 17")
  4. 3-5 key libraries
  
  Example: "TypeScript 5, React Router v7, PostgreSQL 17, Drizzle ORM, Zod"
  

• Wait for response, generate tech-stack.md from input

2b. Tech Stack Validation (runs for all features after first):

If tech-stack.md does NOT exist:

• Skip validation (handled by section 2a above)

If tech-stack.md exists:

1. Extract technologies from plan.md Technical Context:

   • Parse all mentioned libraries, frameworks, tools from Technical Context section
   • Create list: NEW_TECHNOLOGIES[] (technologies mentioned in current plan)
   • Read and parse: APPROVED_STACK[] (from tech-stack.md approved sections)
   • Read and parse: PROHIBITED_STACK[] (from tech-stack.md prohibited section)

2. Classify each NEW technology:

   for TECH in "${NEW_TECHNOLOGIES[@]}"; do
     # Check 1: Is it PROHIBITED?
     if grep -qi "❌.*${TECH}" "${REPO_ROOT}.specswarm/tech-stack.md"; then
       TECH_STATUS[$TECH]="PROHIBITED"
       CONFLICTS_WITH[$TECH]=$(grep "❌.*${TECH}" "${REPO_ROOT}.specswarm/tech-stack.md" | sed 's/.*use \(.*\) instead.*/\1/')
       continue
     fi
   
     # Check 2: Is it already APPROVED?
     if grep -qi "${TECH}" "${REPO_ROOT}.specswarm/tech-stack.md" | grep -v "❌"; then
       TECH_STATUS[$TECH]="APPROVED"
       continue
     fi
   
     # Check 3: Does it CONFLICT with existing tech?
     # Extract PURPOSE tag from tech-stack.md for conflict detection
     TECH_PURPOSE=$(get_library_purpose "${TECH}")
   
     if [ -n "$TECH_PURPOSE" ]; then
       EXISTING_WITH_PURPOSE=$(grep -i "PURPOSE:${TECH_PURPOSE}" "${REPO_ROOT}.specswarm/tech-stack.md" | grep -v "❌" | head -1)
       if [ -n "$EXISTING_WITH_PURPOSE" ]; then
         TECH_STATUS[$TECH]="CONFLICT"
         CONFLICTS_WITH[$TECH]="${EXISTING_WITH_PURPOSE}"
         continue
       fi
     fi
   
     # Check 4: No conflict = AUTO_ADD candidate
     TECH_STATUS[$TECH]="AUTO_ADD"
   done
   

3. Generate Tech Stack Compliance Report in plan.md:

   Create a new section in the plan.md file:

   ## Tech Stack Compliance Report
   <!-- Auto-generated by SpecSwarm tech stack validation -->
   
   ### ✅ Approved Technologies (already in stack)
   {list of technologies with APPROVED status}
   
   ### ➕ New Technologies (auto-added)
   {list of technologies with AUTO_ADD status}
   For each:
   - **{Technology Name}**
     - Purpose: {detected_purpose}
     - No conflicts detected
     - Added to: {section_name}
     - Version updated: {old_version} → {new_version}
   
   ### ⚠️ Conflicting Technologies (require approval)
   {list of technologies with CONFLICT status}
   For each:
   - **{Technology Name}**
     - Purpose: {detected_purpose}
     - ❌ CONFLICT: Project uses `{existing_tech}` ({purpose})
     - **Action Required**: Choose one:
   
       | Option | Choice | Implications |
       |--------|--------|--------------|
       | A | Use {existing_tech} (keep existing) | Remove {new_tech} from plan, update Technical Context |
       | B | Replace {existing_tech} with {new_tech} | Update tech-stack.md (MAJOR version), refactor existing code |
       | C | Use both (justify overlap) | Document why both needed in research.md, add note to tech-stack.md |
   
     **Your choice**: _[Wait for user response]_
   
   ### ❌ Prohibited Technologies (cannot use)
   {list of technologies with PROHIBITED status}
   For each:
   - **{Technology Name}**
     - ❌ PROHIBITED in tech-stack.md
     - Reason: "{reason from tech-stack.md}"
     - **Must use**: {approved_alternative}
     - **Cannot proceed** until plan.md updated
   

4. Handle Each Status:

   APPROVED → Continue silently (no action needed)

   AUTO_ADD →

   # For each AUTO_ADD technology:
   1. Determine appropriate section (Data Layer, UI Layer, Utilities, etc.)
   2. Add entry to tech-stack.md:
      - {Technology} v{version} ({purpose}) <!-- Auto-added: Feature {FEATURE_NUM}, {DATE} -->
   3. Bump tech-stack.md MINOR version:
      OLD_VERSION=$(grep "^\*\*Version\*\*:" "${REPO_ROOT}.specswarm/tech-stack.md" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
      MAJOR=$(echo $OLD_VERSION | cut -d. -f1)
      MINOR=$(echo $OLD_VERSION | cut -d. -f2)
      PATCH=$(echo $OLD_VERSION | cut -d. -f3)
      NEW_MINOR=$((MINOR + 1))
      NEW_VERSION="${MAJOR}.${NEW_MINOR}.0"
      sed -i "s/\*\*Version\*\*: ${OLD_VERSION}/\*\*Version\*\*: ${NEW_VERSION}/" "${REPO_ROOT}.specswarm/tech-stack.md"
   4. Update version history section
   5. Notify user in compliance report
   6. Continue with plan generation
   

   CONFLICT →

   1. STOP planning process
   2. Show conflict details with options table (see report format above)
   3. WAIT for user response (A, B, or C)
   4. Based on choice:
      Option A (keep existing):
        - Remove conflicting tech from plan.md Technical Context
        - Continue with plan generation
      Option B (replace):
        - Remove existing tech from tech-stack.md
        - Add new tech to tech-stack.md
        - Bump MAJOR version (breaking change)
        - Add to research.md: justification for replacement
        - Continue with plan generation
      Option C (use both):
        - Require research.md justification section
        - Add new tech to tech-stack.md with overlap note
        - Bump MINOR version
        - Continue with plan generation
   5. Document decision in plan.md under "Tech Stack Compliance"
   

   PROHIBITED →

   1. ERROR: Cannot proceed with planning
   2. Show prohibited tech details and approved alternative
   3. Show amendment process:
   

   To use prohibited technology:

   1. Document compelling business justification in research.md
   2. Update .specswarm/constitution.md (requires constitutional amendment)
   3. Remove from Prohibited section in tech-stack.md
   4. Add to Approved section with justification comment
   5. Bump tech-stack.md MAJOR version (breaking constitutional change)
   6. Re-run /specswarm:plan

   4. HALT planning until issue resolved
   

5. Update tech-stack.md file (for AUTO_ADD technologies):

   • Automatically write changes to tech-stack.md
   • Update version and version history
   • Add auto-generated comment with feature number and date

<!-- ========== END TECH STACK MANAGEMENT ========== -->

3. Execute plan workflow: Follow the structure in IMPL_PLAN template to:

   • Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
   • Fill Constitution Check section from constitution
   • Evaluate gates (ERROR if violations unjustified)
   • Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
   • Phase 1: Generate data-model.md, contracts/, quickstart.md
   • Phase 1: Update agent context by running the agent script
   • Re-evaluate Constitution Check post-design

4. Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.

Phases

Phase 0: Outline & Research

1. Extract unknowns from Technical Context above:

   • For each NEEDS CLARIFICATION → research task
   • For each dependency → best practices task
   • For each integration → patterns task

2. Generate and dispatch research agents:

   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   

3. Consolidate findings in research.md using format:

   • Decision: [what was chosen]
   • Rationale: [why chosen]
   • Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved

Phase 1: Design & Contracts

Prerequisites: research.md complete

1. Extract entities from feature spec → data-model.md:

   • Entity name, fields, relationships
   • Validation rules from requirements
   • State transitions if applicable

2. Generate API contracts from functional requirements:

   • For each user action → endpoint
   • Use standard REST/GraphQL patterns
   • Output OpenAPI/GraphQL schema to /contracts/

3. Agent context update (optional):

   a. Detect Agent Type:

   # Check which agent context files exist
   if [ -d "${REPO_ROOT}/.claude" ]; then
     AGENT="claude"
     CONTEXT_FILE=".claude/context.md"
   elif [ -f "${REPO_ROOT}/.cursorrules" ]; then
     AGENT="cursor"
     CONTEXT_FILE=".cursorrules"
   elif [ -f "${REPO_ROOT}/.github/copilot-instructions.md" ]; then
     AGENT="copilot"
     CONTEXT_FILE=".github/copilot-instructions.md"
   else
     # No agent context file found - skip this step
     AGENT="none"
   fi
   

   b. Extract Tech Stack from plan.md:

   • Language (e.g., Python, TypeScript, Go)
   • Framework (e.g., React, FastAPI, Express)
   • Database (e.g., PostgreSQL, MongoDB)
   • Key libraries and tools

   c. Update Agent Context File (Enhanced by SpecSwarm):

   <!-- Tech stack enforcement added by Marty Bonacci & Claude Code (2025) -->
   • Read existing CONTEXT_FILE (if exists)
   • Read .specswarm/tech-stack.md if exists (SpecSwarm enhancement)
   • Look for markers like <!-- AUTO-GENERATED-START --> and <!-- AUTO-GENERATED-END -->
   • Replace content between markers with enhanced format:
   • If no markers exist, append new section
   • Preserve all manual edits outside markers
   • Enhanced format (includes CRITICAL CONSTRAINTS from tech-stack.md):

   <!-- AUTO-GENERATED-START -->
   ## Tech Stack (from plan.md)
   - **Language**: {language}
   - **Framework**: {framework}
   - **Database**: {database}
   - **Key Libraries**: {libraries}
   
   ## CRITICAL CONSTRAINTS (from tech-stack.md)
   ⚠️ **BEFORE suggesting ANY library, framework, or pattern:**
   1. Read `.specswarm/tech-stack.md`
   2. Verify your suggestion is APPROVED
   3. If PROHIBITED, suggest approved alternative
   4. If UNAPPROVED, warn user and require justification
   
   **Prohibited Technologies** (NEVER suggest these):
   {list of ❌ technologies from tech-stack.md with approved alternatives}
   Example format:
   - ❌ Axios → Use: fetch API
   - ❌ Class components → Use: Functional components
   - ❌ Redux → Use: React Router loaders/actions
   
   **Violation = Constitution violation** (see `.specswarm/constitution.md` Principle 5)
   
   **Auto-Addition:** Non-conflicting new libraries will be auto-added during `/specswarm:plan`
   <!-- AUTO-GENERATED-END -->
   

Output: data-model.md, /contracts/*, quickstart.md, (optional) agent context file

Key rules

• Use absolute paths
• ERROR on gate failures or unresolved clarifications