Speckit Specify Agent Skill

User Input

$ARGUMENTS

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

Pre-Execution Checks

Check for extension hooks (before specification):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.before_specify key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
• If the hook has no condition field, or it is null/empty, treat the hook as executable
• If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• For each executable hook, output the following based on its optional flag:
• Optional hook (optional: true):

    ## Extension Hooks

    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}

    Prompt: {prompt}
    To execute: `/{command}`

• Mandatory hook (optional: false):

    ## Extension Hooks

    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}

    Wait for the result of the hook command before proceeding to the Outline.

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

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 $ARGUMENTS appears literally below. Do not ask the user to repeat it unless they provided an empty command.

Given that feature description, do this:

• Generate a concise short name (2-4 words) for the branch:
• Analyze the feature description and extract the most meaningful keywords
• Create a 2-4 word short name that captures the essence of the feature
• Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
• Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
• Keep it concise but descriptive enough to understand the feature at a glance
• Examples:
• "I want to add user authentication" → "user-auth"
• "Implement OAuth2 integration for the API" → "oauth2-api-integration"
• "Create a dashboard for analytics" → "analytics-dashboard"
• "Fix payment processing timeout bug" → "fix-payment-timeout"

• Create the feature branch by running the script with --short-name (and --json). In sequential mode, do NOT pass --number — the script auto-detects the next available number. In timestamp mode, the script generates a YYYYMMDD-HHMMSS prefix automatically:

Branch numbering mode: Before running the script, check if .specify/init-options.json exists and read the branch_numbering value.

• If "timestamp", add --timestamp (Bash) or -Timestamp (PowerShell) to the script invocation
• If "sequential" or absent, do not add any extra flag (default behavior)

• Bash example: .specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --short-name "user-auth" "Add user authentication"
• Bash (timestamp): .specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --timestamp --short-name "user-auth" "Add user authentication"
• PowerShell example: .specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -ShortName "user-auth" "Add user authentication"
• PowerShell (timestamp): .specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -Timestamp -ShortName "user-auth" "Add user authentication"

IMPORTANT:

• Do NOT pass --number — the script determines the correct next number automatically
• Always include the JSON flag (--json for Bash, -Json for PowerShell) so the output can be parsed reliably
• You must only ever run this script once per feature
• The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
• The JSON output will contain BRANCH_NAME and SPEC_FILE paths
• For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")

• Load .specify/templates/spec-template.md to understand required sections.

• Follow this execution flow:

• Parse user description from Input

If empty: ERROR "No feature description provided"

• Extract key concepts from description

Identify: actors, actions, data, constraints

• 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
• Fill User Scenarios & Testing section

If no clear user flow: ERROR "Cannot determine user scenarios"

• Generate Functional Requirements

Each requirement must be testable

Use reasonable defaults for unspecified details (document assumptions in Assumptions section)

• 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

• Identify Key Entities (if data involved)
• Return: SUCCESS (spec ready for planning)

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

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

• If items fail (excluding [NEEDS CLARIFICATION]):
• List the failing items and specific issues
• Update the spec to address each issue
• Re-run validation until all items pass (max 3 iterations)
• If still failing after 3 iterations, document remaining issues in checklist notes and warn user

• If [NEEDS CLARIFICATION] markers remain:
• Extract all [NEEDS CLARIFICATION: ...] markers from the spec
• 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
• 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]_

• 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
• Number questions sequentially (Q1, Q2, Q3 - max 3 total)
• Present all questions together before waiting for responses
• Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
• Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
• Re-run validation after all clarifications are resolved

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

• Report completion with branch name, spec file path, checklist results, and readiness for the next phase (/speckit.clarify or /speckit.plan).

• Check for extension hooks: After reporting completion, check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.after_specify key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
• If the hook has no condition field, or it is null/empty, treat the hook as executable
• If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• For each executable hook, output the following based on its optional flag:
• Optional hook (optional: true):

       ## Extension Hooks

       **Optional Hook**: {extension}
       Command: `/{command}`
       Description: {description}

       Prompt: {prompt}
       To execute: `/{command}`

• Mandatory hook (optional: false):

       ## Extension Hooks

       **Automatic Hook**: {extension}
       Executing: `/{command}`
       EXECUTE_COMMAND: {command}

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

NOTE: The script creates and checks out the new branch and initializes the spec file before writing.

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:

• Make informed guesses: Use context, industry standards, and common patterns to fill gaps
• Document assumptions: Record reasonable defaults in the Assumptions section
• 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
• Prioritize clarifications: scope > security/privacy > user experience > technical details
• Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
• 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: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)

Success Criteria Guidelines

Success criteria must be:

• Measurable: Include specific metrics (time, percentage, count, rate)
• Technology-agnostic: No mention of frameworks, languages, databases, or tools
• User-focused: Describe outcomes from user/business perspective, not system internals
• 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)