alibaba/speckit.specify

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

Given that feature description, do this:

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

2. Check for existing specs before creating new one:

   a. First, find all existing specs:

   • Specs directories: Check for directories matching specs/[0-9]+-<short-name>

   b. Find the highest feature number and determine the next available number:

   • Extract all numbers of existing specs and find the highest number N
   • Use N+1 for the new branch number or 001 for the first spec
   • adding prefix-zeros if N+1 has less than three numbers, e.g., 001, 025, 146

   c. Create GitHub Feature Issue:

   • Create an feature issue on the GitHub
   • This issue name is: [<N+1>-<short-name>] <description>, e.g., [001-add-frontend] add frontend for biagent
   • The issue body is:

     # Feature
     
     [Use 3-5 sentences to describe this feature.]
     
     # Process
     
     - [ ] Specify
     - [ ] Plan
     - [ ] Task
     - [ ] Implement
     

   d. Initialize the spec:

   • Checkout to a new branch <N+1>-<short-name>.
   • Create a new spec directory specs/<N+1>-<short-name>.
   • Copy the template templates/spec-template.md to the feature directory as specs/<N+1>-<short-name>/spec.md and understand required sections.

   IMPORTANT:

   • Check all three sources (remote branches, local branches, specs directories) to find the highest number
   • Only match branches/directories with the exact short-name pattern
   • You must only ever run this script once per feature

3. Follow this execution flow:

   1. Parse user description from Input If empty: ERROR "No feature description provided"
   2. Extract key concepts from description Identify: actors, actions, data, constraints
   3. 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
   4. Fill User Scenarios & Testing section If no clear user flow: ERROR "Cannot determine user scenarios"
   5. Generate Functional Requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
   6. 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
   7. Identify Key Entities (if data involved)
   8. Return: SUCCESS (spec ready for planning)

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

5. Spec Review. The generated spec file requires human review. Ask users whether they want to review the spec in the workspace or on the GitHub. We provide the following steps to push the spec to the GitHub. Ask for permission to execute and wait for response.

   1. Commit generated files and push this spec branch to the remote.
   2. Create another new issue on the GitHub. This issue has the label Spec. The title is [<N+1>-<short-name>][Spec] <description>, e.g., [001-add-frontend][Spec] add spec for the frontend. The body is about this spec.
   3. Make this spec issue as the sub-issue of the feature issue. The command is:

   gh api graphql -f query='mutation { addSubIssue(input: {issueId: "xxx", subIssueId: "xxx"}) { issue { id title } subIssue { id title } } }'
   

   4. Create a Pull Request that merge the current spec branch to main. The first line of the body should be "fix #[spec-issue-number]" to link to the spec issue.
   5. Update the feature issue that add the spec issue id in the body, e.g., - [ ] Specify: #10.
   6. List all contributors and ask users to choose the reviewers. Note the PR author (i.e., me) cannot be reviewers.

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

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

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)