SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsspeckit-specify-zh

speckit-specify-zh

Coding & development

View repository

Updated 10-15 15:17

About this skill

User input

$ARGUMENTS

Before continuing, youmustconsider the user input (if non-empty).

Outline

The text typed by the user after the trigger word in the trigger messageisthe function description. Assume that this function description is always available in this conversation, namely $ARGUMENTS. Unless the user provided an empty command, do not ask the user to repeat it.

Based on this function description, please perform the following actions:

  1. Copy assets/specify/ all files (including subdirectories) according to the original directory structure to the.specify directory under the repository root, skip existing files,must not overwrite existing files with the same name. The -n (--no-clobber) option of the cp command can prevent overwriting existing files. At this stage, your project folder contents should resemble the following:
仓库根目录
└── .specify
    ├── memory
    │  └── constitution.md
    ├── scripts
    │  ├──bash    
    │  │  ├── check-prerequisites.sh
    │  │  ├── common.sh
    │  │  ├── create-new-feature.sh
    │  │  ├── setup-plan.sh
    │  │  └── update-claude-md.sh
    │  ├──powershell    
    │  │  ├── check-prerequisites.ps1
    │  │  ├── common.ps1
    │  │  ├── create-new-feature.ps1
    │  │  ├── setup-plan.ps1
    │  │  └── update-claude-md.ps1    
    ├── specs
    │  └── 001-create-taskify
    │      └── spec.md
    └── templates
        ├── plan-template.md
        ├── spec-template.md
        └── tasks-template.md

  1. Generate a concise short name(2-4 words) for the branch:

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

  2. Check existing branches before creating a new branch：

    a. First fetch all remote branches to ensure you have the latest information:

    git fetch --all --prune

    b. Find the highest function number for the short name across all sources:

    • Remote branches:git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'
    • Local branches:git branch | grep -E '^[* ]*[0-9]+-<short-name>$'
    • Specification directory: check for directories matching specs/[0-9]+-<short-name> directories

    c. Determine the next available number:

    • Extract all numbers from all three sources
    • Find the maximum number N
    • Use N+1 for the new branch

    d. Run the script using the calculated number and short name create-new-feature.ps1 -Json "$ARGUMENTS"：

    • Pass --number N+1 and --short-name "your-short-name" as well as the function description
    • Bash example:create-new-feature.sh -Json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "添加用户认证"
    • PowerShell example:create-new-feature.ps1 -Json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "添加用户认证"

    Important：

    • Check all three sources (remote branches, local branches, specification directory) to find the highest number
    • Only match branches/directories with the exact short name pattern
    • If no existing branch/directory with this short name is found, start from number 1
    • This script can only be run once per function
    • JSON is provided as output in the terminal - always refer to it to get the actual content you are looking for
    • The JSON output will contain BRANCH_NAME and SPEC_FILE paths
    • For single quotes in arguments like "I'm Groot", use the escape syntax: for example 'I'''m Groot' (or if possible use double quotes: "I'm Groot")

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

  4. Follow this execution flow:

    1. Parse the user description from the input If empty: error "No feature description provided"
    2. Extract key concepts from the description Identify: actors, actions, data, constraints
    3. For unclear aspects:
      • Make informed guesses based on context and industry standards
      • Only mark [NEEDS CLARIFICATION: specific question] when:
        • The choice significantly impacts feature scope or user experience
        • There are multiple reasonable interpretations with different implications
        • There is no reasonable default
      • Limit: at most 3 [NEEDS CLARIFICATION] markers in total
      • Prioritize by impact: scope > security/privacy > user experience > technical details
    4. Fill in the User Scenarios & Testing section If there is 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 the Assumptions section)
    6. Define success criteria Create measurable, technology-agnostic outcomes Include both quantitative metrics (time, performance, count) and qualitative measures (user satisfaction, task completion) Each criterion must be verifiable without implementation details
    7. Identify key entities (if data is involved)
    8. Return: SUCCESS (spec is ready for planning)

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

  6. 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, referencing:assets/quality-checklist-template.md

    b. Run validation checks: Review the spec against each checklist item:

    • For each item, determine whether it passes or fails
    • Document specific issues found (quoting the 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 the checklist notes and warn the user

    • If [NEEDS CLARIFICATION] markers exist：

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

      2. Limitation check: If there are more than 3 markers, keep only the 3 most important by scope/safety/user experience impact, and make an educated guess for the rest

      3. For each question that needs clarification (up to 3), refer toassets/clarification-template.mdPresent the options to the user.

      4. Critical - table formatting: Ensure markdown tables are correctly formatted:

        • Use consistent spacing and pipe alignment
        • Each cell should have spaces around its content:| 内容 | instead of |内容|
        • The header separator must have at least 3 dashes:|--------|
        • Test whether the table renders correctly in markdown preview

      5. Number the questions in order (Q1, Q2, Q3 - at most 3 total)

      6. Present all questions together before waiting for a response

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

      8. Update the specification by replacing each [needs clarification] marker with the user's selected or provided answer

      9. Rerun validation after all clarifications are resolved

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

  7. Report completion, including the branch name, specification file path, checklist results, and readiness for the next phase (speckit-clarify or speckit-plan).

Note: The script creates and checks out a new branch and initializes the specification file before writing.

General guidelines

Quick guide

  • Focus on what the user needswhatandwhy
  • Avoid how to implement (no tech stack, APIs, code structure)
  • Write for business stakeholders, not developers
  • Do not create any checklist embedded in the specification. That will be a separate command

Section requirements

  • Required sections: every feature must complete them
  • Optional sections: include only when relevant to the feature
  • When a section does not apply, remove it entirely (do not leave "N/A")

For AI generation

When creating this specification from the user prompt:

  1. Make educated guesses: use context, industry standards, and common patterns to fill gaps
  2. Document assumptions: record reasonable defaults in the assumptions section
  3. Limit clarifications: at most 3 [needs clarification] markers - only for those that:
    • Key decisions that significantly affect feature scope or user experience
    • Situations with multiple reasonable interpretations and different meanings
    • Situations lacking any reasonable default
  4. Prioritize clarifications: scope > safety/privacy > user experience > technical details
  5. Think like a tester: every ambiguous requirement should fail the "testable and explicit" checklist item
  6. Common areas that need clarification(Only when no reasonable default exists):
    • Functional scope and boundaries (including/excluding specific use cases)
    • User types and permissions (if multiple conflicting interpretations are possible)
    • Security/compliance requirements (when legally/financially important)

Reasonable default examples(Do not ask about these):

  • Data retention: industry-standard practices in the domain
  • Performance goals: standard web/mobile application expectations, unless otherwise specified
  • Error handling: user-friendly messages and appropriate fallbacks
  • Authentication method: standard session-based or OAuth2 web application
  • Integration pattern: RESTful API, unless otherwise specified

Success criteria guidelines

Success criteria must:

  1. Measurable: include specific metrics (time, percentage, count, ratio)
  2. Technology-agnostic: do not mention frameworks, languages, databases, or tools
  3. User-centric: describe outcomes from the user/business perspective, not system internals
  4. Verifiable: testable/verifiable without knowing implementation details

Good examples：

  • "Users can complete checkout within 3 minutes"
  • "The system supports 10,000 concurrent users"
  • "95% of searches return results within 1 second"
  • "Task completion rate increases by 40%"

Bad examples(implementation-oriented):

  • "API response time is under 200 milliseconds" (too technical; use "users see results immediately")

  • "The database can handle 1000 TPS" (implementation detail; use user-facing metrics)

  • "React components render efficiently" (framework-specific)

  • "Redis cache hit rate is above 80%" (technology-specific)