gh-martybonacci-specswarm/commands/specify.md

description

description
Create or update the feature specification from a natural language feature description.

User Input

$ARGUMENTS

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

Outline

The text the user typed after /speckit.specify in the triggering message is the feature description. Assume you always have it available in this conversation even if {ARGS} appears literally below. Do not ask the user to repeat it unless they provided an empty command.

Given that feature description, do this:

1. Create New Feature Structure (replaces script execution):

   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)
   ensure_features_dir "$REPO_ROOT"
   

   b. Determine Next Feature Number:

   # Get next feature number using helper
   FEATURE_NUM=$(get_next_feature_number "$REPO_ROOT")
   

   c. Create Feature Slug from Description:

   # Convert description to kebab-case
   # Example: "User Authentication System" → "user-authentication-system"
   SLUG=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//')
   

   d. Capture Parent Branch and Create Feature Branch (if git available):

   BRANCH_NAME="${FEATURE_NUM}-${SLUG}"
   
   if git rev-parse --git-dir >/dev/null 2>&1; then
     # Capture current branch as parent BEFORE switching
     PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
   
     echo ""
     echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
     echo "Branch Setup"
     echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
     echo "  Parent branch: $PARENT_BRANCH (current branch)"
     echo "  Feature branch: $BRANCH_NAME (will be created)"
     echo ""
     echo "ℹ️  The feature branch will be created from $PARENT_BRANCH."
     echo "   When complete, it will merge back to $PARENT_BRANCH."
     echo ""
     read -p "Is this correct? (y/n): " branch_confirm
   
     if [ "$branch_confirm" != "y" ]; then
       echo ""
       echo "❌ Branch setup cancelled"
       echo ""
       echo "Please checkout the correct parent branch first, then run:"
       echo "  /specswarm:specify \"$FEATURE_DESCRIPTION\""
       exit 0
     fi
     echo ""
   
     # Create and switch to new feature branch
     git checkout -b "$BRANCH_NAME"
   else
     # Non-git: use environment variable
     export SPECIFY_FEATURE="$BRANCH_NAME"
     PARENT_BRANCH="unknown"
   fi
   

   e. Create Feature Directory Structure:

   FEATURE_DIR="${FEATURES_DIR}/${FEATURE_NUM}-${SLUG}"
   mkdir -p "${FEATURE_DIR}/checklists"
   mkdir -p "${FEATURE_DIR}/contracts"
   

   f. Set Path Variables (use these for remainder of command):

   SPEC_FILE="${FEATURE_DIR}/spec.md"
   CHECKLISTS_DIR="${FEATURE_DIR}/checklists"
   

2. Load spec template to understand required sections:

   • Try to read templates/spec-template.md if it exists
   • If template missing, use this embedded minimal template:

   # Feature: [Feature Name]
   
   ## Overview
   [Brief description of the feature and its purpose]
   
   ## User Scenarios
   [Key user flows and scenarios]
   
   ## Functional Requirements
   [What the system must do]
   
   ## Success Criteria
   [Measurable outcomes that define success]
   
   ## Key Entities
   [Important data entities involved]
   
   ## Assumptions
   [Documented assumptions and reasonable defaults]
   

3. Parse the user's feature description from $ARGUMENTS and validate:

   • If empty: ERROR "No feature description provided"
   • Extract key concepts: actors, actions, data, constraints

4. Framework & Dependency Compatibility Check (for upgrade/migration features):

   If the feature description mentions dependency upgrades (PHP, Laravel, Node, framework versions, etc.), perform compatibility validation:

   a. Detect Upgrade Context:

   # Check if feature involves upgrades
   INVOLVES_UPGRADE=$(echo "$ARGUMENTS" | grep -iE '(upgrade|migrat|updat).*(php|laravel|node|framework|version|[0-9]\.[0-9])')
   

   b. Read Project Dependencies (if upgrade detected):

   if [ -n "$INVOLVES_UPGRADE" ] && [ -f "${REPO_ROOT}/composer.json" ]; then
     # Extract PHP requirement
     PHP_CURRENT=$(grep -Po '(?<="php":\s")[^"]+' "${REPO_ROOT}/composer.json" 2>/dev/null)
   
     # Extract Laravel/framework version
     FRAMEWORK=$(grep -Po '(?<="laravel/framework":\s")[^"]+' "${REPO_ROOT}/composer.json" 2>/dev/null)
   fi
   

   c. Cross-Reference Compatibility Matrices:

   When upgrade targets are identified in the feature description, check known compatibility constraints:

   Laravel Compatibility Matrix:

   • Laravel 5.8: PHP 7.2 - 7.4 ONLY
   • Laravel 6.x: PHP 7.2 - 8.0
   • Laravel 7.x: PHP 7.2 - 8.0
   • Laravel 8.x: PHP 7.3 - 8.1
   • Laravel 9.x: PHP 8.0 - 8.2
   • Laravel 10.x: PHP 8.1 - 8.3
   • Laravel 11.x: PHP 8.2 - 8.3

   Key Detection Rules:

   • If feature mentions "PHP 8.x upgrade" AND Laravel 5.8 detected → BLOCKER
   • If feature mentions "PHP 8.x upgrade" AND Laravel 6-7 detected → WARNING (check target PHP version)
   • If feature mentions framework upgrade dependencies → Include in spec

   d. Add Blockers Section to Spec (if incompatibilities found):

   If compatibility issues detected, add this section AFTER "Overview" and BEFORE "User Scenarios":

   ## ⚠️ CRITICAL BLOCKERS & DEPENDENCIES
   
   ### [Framework] Version Incompatibility
   
   **Issue**: [Current framework version] officially supports [compatible versions] only.
   
   **Current State**:
   - Framework: [Detected version from composer.json]
   - Target: [Upgrade target from feature description]
   - Compatibility: ❌ NOT COMPATIBLE
   
   **Resolution Options**:
   
   1. **Recommended**: Upgrade framework first
      - Path: [Current] → [Intermediate versions] → [Target compatible version]
      - Benefit: Official support, maintained compatibility
      - Timeline: [Estimated complexity]
   
   2. **Community Patches**: Use unofficial compatibility patches
      - Benefit: Faster, smaller scope
      - Risk: Unsupported, may break in production
      - Recommendation: NOT recommended for production
   
   3. **Stay on Compatible Version**: Delay target upgrade
      - Keep: [Current compatible version]
      - Timeline: [Until when it's supported]
      - Benefit: Stable, supported
   
   4. **Accept Risk**: Proceed with unsupported configuration
      - Risk: High - potential breaking changes
      - Required: Extensive testing, acceptance of maintenance burden
      - Recommendation: Only if timeline critical and resources available
   
   **Recommended Path**: [Most appropriate option with reasoning]
   
   **Impact on This Feature**: This blocker must be resolved before beginning implementation. Consider creating separate features for:
   - Feature XXX: [Framework] upgrade to [compatible version]
   - Feature YYY: [Dependency] upgrade (this feature, dependent on XXX)
   

   e. Document Assumptions About Compatibility:

   Even if no blockers found, add relevant assumptions to the Assumptions section:

   • "Framework version [X] is compatible with [upgrade target]"
   • "Standard upgrade path follows: [path]"
   • "Breaking changes from [source docs URL] have been reviewed"

5. Follow this execution flow:

   1. For unclear aspects:
      • Make informed guesses based on context and industry standards
      • Only mark with [NEEDS CLARIFICATION: specific question] if:
        • The choice significantly impacts feature scope or user experience
        • Multiple reasonable interpretations exist with different implications
        • No reasonable default exists
      • LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total
      • Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
   2. Fill User Scenarios & Testing section If no clear user flow: ERROR "Cannot determine user scenarios"
   3. Generate Functional Requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
   4. Define Success Criteria Create measurable, technology-agnostic outcomes Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) Each criterion must be verifiable without implementation details
   5. Identify Key Entities (if data involved)
   6. Return: SUCCESS (spec ready for planning)

6. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.

   IMPORTANT: Include YAML Frontmatter:

   The spec.md file MUST start with YAML frontmatter containing metadata:

   ---
   parent_branch: ${PARENT_BRANCH}
   feature_number: ${FEATURE_NUM}
   status: In Progress
   created_at: $(date -Iseconds)
   ---
   

   This metadata enables the /specswarm:complete command to merge back to the correct parent branch.

7. Specification Quality Validation: After writing the initial spec, validate it against quality criteria:

   a. Create Spec Quality Checklist: Generate a checklist file at FEATURE_DIR/checklists/requirements.md using the checklist template structure with these validation items:

   # Specification Quality Checklist: [FEATURE NAME]
   
   **Purpose**: Validate specification completeness and quality before proceeding to planning
   **Created**: [DATE]
   **Feature**: [Link to spec.md]
   
   ## Content Quality
   
   - [ ] No implementation details (languages, frameworks, APIs)
   - [ ] Focused on user value and business needs
   - [ ] Written for non-technical stakeholders
   - [ ] All mandatory sections completed
   
   ## Requirement Completeness
   
   - [ ] No [NEEDS CLARIFICATION] markers remain
   - [ ] Requirements are testable and unambiguous
   - [ ] Success criteria are measurable
   - [ ] Success criteria are technology-agnostic (no implementation details)
   - [ ] All acceptance scenarios are defined
   - [ ] Edge cases are identified
   - [ ] Scope is clearly bounded
   - [ ] Dependencies and assumptions identified
   
   ## Feature Readiness
   
   - [ ] All functional requirements have clear acceptance criteria
   - [ ] User scenarios cover primary flows
   - [ ] Feature meets measurable outcomes defined in Success Criteria
   - [ ] No implementation details leak into specification
   
   ## Notes
   
   - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
   

   b. Run Validation Check: Review the spec against each checklist item:

   • For each item, determine if it passes or fails
   • Document specific issues found (quote relevant spec sections)

   c. Handle Validation Results:

   • If all items pass: Mark checklist complete and proceed to step 6

   • If items fail (excluding [NEEDS CLARIFICATION]):

     1. List the failing items and specific issues
     2. Update the spec to address each issue
     3. Re-run validation until all items pass (max 3 iterations)
     4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user

   • If [NEEDS CLARIFICATION] markers remain:

     1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec

     2. LIMIT CHECK: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest

     3. For each clarification needed (max 3), present options to user in this format:

        ## Question [N]: [Topic]
        
        **Context**: [Quote relevant spec section]
        
        **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
        
        **Suggested Answers**:
        
        | Option | Answer | Implications |
        |--------|--------|--------------|
        | A      | [First suggested answer] | [What this means for the feature] |
        | B      | [Second suggested answer] | [What this means for the feature] |
        | C      | [Third suggested answer] | [What this means for the feature] |
        | Custom | Provide your own answer | [Explain how to provide custom input] |
        
        **Your choice**: _[Wait for user response]_
        

     4. CRITICAL - Table Formatting: Ensure markdown tables are properly formatted:

        • Use consistent spacing with pipes aligned
        • Each cell should have spaces around content: | Content | not |Content|
        • Header separator must have at least 3 dashes: |--------|
        • Test that the table renders correctly in markdown preview

     5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)

     6. Present all questions together before waiting for responses

     7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")

     8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer

     9. Re-run validation after all clarifications are resolved

   d. Update Checklist: After each validation iteration, update the checklist file with current pass/fail status

8. Report completion with:

   • Branch name (if git repo)
   • Feature directory path
   • Spec file path
   • Checklist results
   • Readiness for next phase (/clarify or /plan)

NOTE: This command creates the feature branch (if git), initializes the feature directory structure, and creates the initial spec.md file.

General Guidelines

Quick Guidelines

• Focus on WHAT users need and WHY.
• Avoid HOW to implement (no tech stack, APIs, code structure).
• Written for business stakeholders, not developers.
• DO NOT create any checklists that are embedded in the spec. That will be a separate command.

Section Requirements

• Mandatory sections: Must be completed for every feature
• Optional sections: Include only when relevant to the feature
• When a section doesn't apply, remove it entirely (don't leave as "N/A")

For AI Generation

When creating this spec from a user prompt:

1. Make informed guesses: Use context, industry standards, and common patterns to fill gaps
2. Document assumptions: Record reasonable defaults in the Assumptions section
3. Limit clarifications: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
   • Significantly impact feature scope or user experience
   • Have multiple reasonable interpretations with different implications
   • Lack any reasonable default
4. Prioritize clarifications: scope > security/privacy > user experience > technical details
5. Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
6. Common areas needing clarification (only if no reasonable default exists):
   • Feature scope and boundaries (include/exclude specific use cases)
   • User types and permissions (if multiple conflicting interpretations possible)
   • Security/compliance requirements (when legally/financially significant)

Examples of reasonable defaults (don't ask about these):

• Data retention: Industry-standard practices for the domain
• Performance targets: Standard web/mobile app expectations unless specified
• Error handling: User-friendly messages with appropriate fallbacks
• Authentication method: Standard session-based or OAuth2 for web apps
• Integration patterns: RESTful APIs unless specified otherwise

Success Criteria Guidelines

Success criteria must be:

1. Measurable: Include specific metrics (time, percentage, count, rate)
2. Technology-agnostic: No mention of frameworks, languages, databases, or tools
3. User-focused: Describe outcomes from user/business perspective, not system internals
4. Verifiable: Can be tested/validated without knowing implementation details

Good examples:

• "Users can complete checkout in under 3 minutes"
• "System supports 10,000 concurrent users"
• "95% of searches return results in under 1 second"
• "Task completion rate improves by 40%"

Bad examples (implementation-focused):

• "API response time is under 200ms" (too technical, use "Users see results instantly")
• "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
• "React components render efficiently" (framework-specific)
• "Redis cache hit rate above 80%" (technology-specific)