gh-martybonacci-specswarm/commands/plan.md at master

Files

Zhongwei Li 7e16d8a2a1 Initial commit

2025-11-30 08:39:24 +08:00

16 KiB

Raw Permalink Blame History

description

description
Execute the implementation planning workflow using the plan template to generate design artifacts.

User Input

$ARGUMENTS

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

Outline

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."

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

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):

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

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

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"

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
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:

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)

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

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

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:

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

4. HALT planning until issue resolved

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

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
Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.

Phases

Phase 0: Outline & Research

Extract unknowns from Technical Context above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task

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}"

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

Extract entities from feature spec → data-model.md:
- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
Generate API contracts from functional requirements:
- For each user action → endpoint
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to /contracts/

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):

Read existing CONTEXT_FILE (if exists)
Read .specswarm/tech-stack.md if exists (SpecSwarm enhancement)
Look for markers like  and 
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

16 KiB Raw Permalink Blame History Unescape Escape