Spec Kit — Prompts (Verbatim Excerpts)
This file quotes verbatim the most important prompt files from templates/commands/. All files were fetched from raw.githubusercontent.com/github/spec-kit/main/templates/commands/.
Prompt 1 — /speckit.specify (templates/commands/specify.md) — First ~120 lines
This is the most architecturally significant prompt. It demonstrates: frontmatter handoffs, pre/post extension hook checking, automated feature directory naming, spec quality validation, and a hard limit of 3 [NEEDS CLARIFICATION] markers.
---
description: Create or update the feature specification from a natural language feature description.
handoffs:
- label: Build Technical Plan
agent: speckit.plan
prompt: Create a plan for the spec. I am building with...
- label: Clarify Spec Requirements
agent: speckit.clarify
prompt: Clarify specification requirements
send: true
---
## User Input
```text
$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: [...]
Outline
...
- Generate a concise short name (2-4 words) for the feature:
- 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.)
...
Create the spec feature directory:
Specs live under the default specs/ directory unless the user explicitly provides SPECIFY_FEATURE_DIRECTORY.
Resolution order for SPECIFY_FEATURE_DIRECTORY:
- If the user explicitly provided
SPECIFY_FEATURE_DIRECTORY (e.g., via environment variable, argument, or configuration), use it as-is
- Otherwise, auto-generate it under
specs/:
- Check
.specify/init-options.json for branch_numbering
- If
"timestamp": prefix is YYYYMMDD-HHMMSS (current timestamp)
- If
"sequential" or absent: prefix is NNN (next available 3-digit number after scanning existing directories in specs/)
- Construct the directory name:
<prefix>-<short-name> (e.g., 003-user-auth or 20260319-143022-user-auth)
- Set
SPECIFY_FEATURE_DIRECTORY to specs/<directory-name>
...
- Follow this execution flow:
- Parse user description from arguments
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
...
Specification Quality Validation: After writing the initial spec, validate it against quality criteria:
a. Create Spec Quality Checklist: Generate a checklist file at SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md ...
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 8
- 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:
...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
**Technique highlights:**
- Frontmatter `handoffs` define which agents the user can chain to next (rendered as buttons in supporting UIs).
- Extension hooks are checked at both start and end of every command — the hook system is woven into every prompt.
- Hard constraint: maximum 3 clarification markers forces the LLM to make informed guesses rather than asking endlessly.
- Iterative self-validation loop: the LLM re-runs quality checks up to 3 times before surfacing issues to the user.
---
## Prompt 2 — `/speckit.clarify` (`templates/commands/clarify.md`) — First ~80 lines
This prompt demonstrates a sophisticated interactive clarification loop with a taxonomy-driven ambiguity scan, sequential one-question-at-a-time UX, and mandatory spec file updates after each accepted answer.
```markdown
---
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
handoffs:
- label: Build Technical Plan
agent: speckit.plan
prompt: Create a plan for the spec. I am building with...
scripts:
sh: scripts/bash/check-prerequisites.sh --json --paths-only
ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
---
...
2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
Functional Scope & Behavior:
- Core user goals & success criteria
- Explicit out-of-scope declarations
- User roles / personas differentiation
Domain & Data Model:
- Entities, attributes, relationships
- Identity & uniqueness rules
- Lifecycle/state transitions
- Data volume / scale assumptions
Interaction & UX Flow:
- Critical user journeys / sequences
- Error/empty/loading states
- Accessibility or localization notes
Non-Functional Quality Attributes:
- Performance (latency, throughput targets)
- Scalability (horizontal/vertical, limits)
- Reliability & availability (uptime, recovery expectations)
- Observability (logging, metrics, tracing signals)
- Security & privacy (authN/Z, data protection, threat assumptions)
- Compliance / regulatory constraints (if any)
...
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
- Maximum of 5 total questions across the whole session.
- Each question must be answerable with EITHER:
- A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
- A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
4. Sequential questioning loop (interactive):
- Present EXACTLY ONE question at a time.
- For multiple‑choice questions:
- **Analyze all options** and determine the **most suitable option** based on:
- Best practices for the project type
- Common patterns in similar implementations
- Risk reduction (security, performance, maintainability)
- Alignment with any explicit project goals or constraints visible in the spec
- Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
- Format as: `**Recommended:** Option [X] - <reasoning>`
- Then render all options as a Markdown table: ...
- After the user answers:
- If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
5. Integration after EACH accepted answer (incremental update approach):
- ...For the first integrated answer in this session:
- Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
- Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
- Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
- Then immediately apply the clarification to the most appropriate section(s): [...]
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
Technique highlights:
- Taxonomy-driven scan forces the LLM to audit 10 distinct categories before deciding what to ask.
- The "recommend first" pattern surfaces a best-practice suggestion before showing options, reducing the decision burden on users.
- Incremental file writes after every accepted answer prevent context loss and ensure partial progress is never lost.
- The "yes"/"recommended"/"suggested" shortcut is an explicit UX pattern to reduce user friction.
Prompt 3 — /speckit.checklist (templates/commands/checklist.md) — Core Concept Section
This prompt introduces the "unit tests for English" framing — the most philosophically distinctive piece of Spec Kit's approach to requirements quality.
## Checklist Purpose: "Unit Tests for English"
**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
**NOT for verification/testing**:
- ❌ NOT "Verify the button clicks correctly"
- ❌ NOT "Test error handling works"
- ❌ NOT "Confirm the API returns 200"
- ❌ NOT checking if code/implementation matches the spec
**FOR requirements quality validation**:
- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
...
**🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
- ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
- ❌ References to code execution, user actions, system behavior
- ❌ "Displays correctly", "works properly", "functions as expected"
- ❌ "Click", "navigate", "render", "load", "execute"
- ❌ Test cases, test plans, QA procedures
- ❌ Implementation details (frameworks, APIs, algorithms)
**✅ REQUIRED PATTERNS** - These test requirements quality:
- ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
- ✅ "Is [vague term] quantified/clarified with specific criteria?"
- ✅ "Are requirements consistent between [section A] and [section B]?"
- ✅ "Can [requirement] be objectively measured/verified?"
- ✅ "Are [edge cases/scenarios] addressed in requirements?"
- ✅ "Does the spec define [missing aspect]?"
Technique highlights:
- The "unit tests for English" metaphor is a precise, memorable constraint that prevents the most common failure mode (writing verification steps instead of requirement quality checks).
- Prohibited patterns include specific banned verbs ("Verify", "Test", "Confirm", "Click", "navigate", "render") — this is a hard constraint list, not guidance.
- The quality dimensions taxonomy (Completeness, Clarity, Consistency, Measurability, Coverage, Edge Case Coverage, NFRs, Dependencies, Ambiguities & Conflicts) mirrors the clarify command's ambiguity scan.
Prompt 4 — /speckit.analyze (templates/commands/analyze.md) — Operating Constraints + Detection Passes
## Operating Constraints
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `__SPECKIT_COMMAND_ANALYZE__`.
...
### 4. Detection Passes (Token-Efficient Analysis)
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
#### A. Duplication Detection
- Identify near-duplicate requirements
- Mark lower-quality phrasing for consolidation
#### B. Ambiguity Detection
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
#### C. Underspecification
- Requirements with verbs but missing object or measurable outcome
- User stories missing acceptance criteria alignment
- Tasks referencing files or components not defined in spec/plan
#### D. Constitution Alignment
- Any requirement or plan element conflicting with a MUST principle
- Missing mandated sections or quality gates from constitution
#### E. Coverage Gaps
- Requirements with zero associated tasks
- Tasks with no mapped requirement/story
- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
#### F. Inconsistency
- Terminology drift (same concept named differently across files)
- Data entities referenced in plan but absent in spec (or vice versa)
- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
### 5. Severity Assignment
- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
Technique highlights:
- Hard read-only constraint prevents autonomous spec mutation — the agent is explicitly prohibited from editing during analysis.
- Constitution violations are automatically CRITICAL with no escape hatch; this enforces governance at the prompt level.
- Token-efficient analysis: 50-finding cap prevents unbounded output in large codebases.
## Task Generation Rules
**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
### Checklist Format (REQUIRED)
Every task MUST strictly follow this format:
```text
- [ ] [TaskID] [P?] [Story?] Description with file path
Format Components:
- Checkbox: ALWAYS start with
- [ ] (markdown checkbox)
- Task ID: Sequential number (T001, T002, T003...) in execution order
- [P] marker: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
- [Story] label: REQUIRED for user story phase tasks only
- Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
- Setup phase: NO story label
- Foundational phase: NO story label
- User Story phases: MUST have story label
- Polish phase: NO story label
- Description: Clear action with exact file path
Examples:
- ✅ CORRECT:
- [ ] T001 Create project structure per implementation plan
- ✅ CORRECT:
- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
- ✅ CORRECT:
- [ ] T012 [P] [US1] Create User model in src/models/user.py
- ✅ CORRECT:
- [ ] T014 [US1] Implement UserService in src/services/user_service.py
- ❌ WRONG:
- [ ] Create User model (missing ID and Story label)
- ❌ WRONG:
T001 [US1] Create model (missing checkbox)
- ❌ WRONG:
- [ ] [US1] Create User model (missing Task ID)
- ❌ WRONG:
- [ ] T001 [US1] Create model (missing file path)
**Technique highlights:**
- Machine-readable task format (T-prefixed IDs, `[P]` parallelism markers, `[USn]` story labels) enables the `/speckit.implement` command to parse and execute tasks deterministically.
- The explicit right/wrong examples with parenthetical explanations enforce the format more reliably than prose descriptions.
- `[P]` marker enables the implement command to execute independent tasks in parallel without requiring a separate dependency graph.