Command Template System

Relevant source files

• templates/commands/specify.md
• templates/commands/tasks.md

The Command Template System defines the structure and processing rules for command templates that drive the Spec-Driven Development workflow. These templates serve as the authoritative source for slash command behavior across all 16+ supported AI agents. This page documents the template file format, YAML frontmatter schema, placeholder system, and processing rules.

For information about how templates are converted to agent-specific formats, see Template Processing Pipeline. For documentation on cross-platform scripts referenced in templates, see Cross-Platform Script Architecture.

Template File Structure

Command templates are stored in the templates/commands/ directory. Each template is a Markdown file with a specific structure consisting of YAML frontmatter followed by instructional content.

File Location and Naming

Aspect	Convention
Directory	templates/commands/
File Format	Markdown (.md)
Naming Pattern	{command-name}.md (e.g., specify.md, tasks.md)
Command Mapping	Filename maps to /speckit.{command-name} slash command

Sources: templates/commands/specify.md1-262 templates/commands/tasks.md1-140

Overall Template Structure

Sources: templates/commands/specify.md1-14 templates/commands/tasks.md1-15

YAML Frontmatter Schema

The frontmatter is delimited by --- markers and contains metadata that controls command behavior and integration.

Frontmatter Fields

Field	Type	Required	Description
description	string	Yes	Human-readable command description shown in agent UIs
handoffs	list	No	Suggested next commands with pre-filled prompts
scripts	object	Yes	Script paths for bash (sh) and PowerShell (ps) variants

Scripts Object Structure

Key Points:

• sh key: Bash script path with arguments
• ps key: PowerShell script path with arguments
• Both paths are relative to repository root
• {ARGS} placeholder is substituted during processing

Sources: templates/commands/specify.md11-14 templates/commands/tasks.md12-14

Handoffs Configuration

Handoffs enable workflow continuity by suggesting the next logical command with contextual prompts.

Field Definitions:

Field	Type	Purpose
label	string	Button text shown in agent UI
agent	string	Target command (e.g., speckit.plan)
prompt	string	Pre-filled text for next command
send	boolean	If true, auto-submit the handoff (optional)

Sources: templates/commands/specify.md3-10 templates/commands/tasks.md3-11

Template Body Format

The template body contains structured Markdown sections that provide instructions to AI agents. These sections follow a consistent pattern across all command templates.

Standard Sections

User Input Section

This section displays the raw arguments passed to the command:

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

The `$ARGUMENTS` placeholder is substituted with the actual user input when the command is invoked.

Sources: <FileRef file-url="https://github.com/github/spec-kit/blob/9a1e3037/templates/commands/specify.md#L16-L22" min=16 max=22 file-path="templates/commands/specify.md">Hii</FileRef> <FileRef file-url="https://github.com/github/spec-kit/blob/9a1e3037/templates/commands/tasks.md#L17-L23" min=17 max=23 file-path="templates/commands/tasks.md">Hii</FileRef>

### Outline Section

The Outline section provides step-by-step instructions for command execution. It typically includes:

1. **Setup steps**: Script execution and environment validation
2. **Data loading**: Reading specification files and configuration
3. **Processing workflow**: Core command logic
4. **Output generation**: Writing results to files
5. **Reporting**: Summary of actions taken

Sources: <FileRef file-url="https://github.com/github/spec-kit/blob/9a1e3037/templates/commands/specify.md#L24-L198" min=24 max=198 file-path="templates/commands/specify.md">Hii</FileRef> <FileRef file-url="https://github.com/github/spec-kit/blob/9a1e3037/templates/commands/tasks.md#L25-L68" min=25 max=68 file-path="templates/commands/tasks.md">Hii</FileRef>

## Placeholder System

Templates use multiple placeholder types that are substituted during processing to create agent-specific command files.

### Placeholder Types and Substitution Rules

```mermaid
graph LR
    subgraph "Template Placeholders"
        ARGUMENTS["$ARGUMENTS"]
        SCRIPT["{SCRIPT}"]
        ARGS["{ARGS}"]
        FEATURE_DIR["{FEATURE_DIR}"]
    end
    
    subgraph "Markdown Format<br/>(Most Agents)"
        MD_ARGUMENTS["$ARGUMENTS"]
        MD_SCRIPT["Resolved script path"]
        MD_ARGS["$ARGUMENTS"]
    end
    
    subgraph "TOML Format<br/>(Gemini, Qwen)"
        TOML_ARGS["{{args}}"]
        TOML_SCRIPT["Resolved script path"]
    end
    
    ARGUMENTS --> MD_ARGUMENTS
    ARGUMENTS --> TOML_ARGS
    SCRIPT --> MD_SCRIPT
    SCRIPT --> TOML_SCRIPT
    ARGS --> MD_ARGS
    ARGS --> TOML_ARGS

Placeholder Reference Table

Placeholder	Purpose	Markdown Substitution	TOML Substitution
$ARGUMENTS	User's command arguments	$ARGUMENTS (preserved)	{{args}}
{SCRIPT}	Script path from frontmatter	Resolved sh or ps path	Resolved sh or ps path
{ARGS}	Inline argument reference	$ARGUMENTS	{{args}}
{FEATURE_DIR}	Current feature directory	Resolved from script output	Resolved from script output

Processing Rules:

1. Format-specific conversion: $ARGUMENTS becomes {{args}} for TOML-based agents
2. Script selection: {SCRIPT} resolves to sh path for bash-based agents, ps path for PowerShell-based agents
3. Path rewriting: Absolute paths adjusted based on agent directory conventions
4. Preserved placeholders: Some placeholders like $ARGUMENTS remain as-is for agent runtime substitution

Sources: templates/commands/specify.md12-72 templates/commands/tasks.md27

Command Template Structure Example

The specify.md Template

The specify.md template demonstrates the complete structure and placeholder usage:

Key Structural Elements:

1. Frontmatter (specify.md1-14):

   • Description for UI display
   • Two handoff options (plan, clarify)
   • Dual script paths for bash/PowerShell

2. User Input (specify.md16-22):

   • Displays $ARGUMENTS placeholder
   • Instructs agent to consider input

3. Outline (specify.md24-198):

   • 7-step workflow with sub-tasks
   • Local CLI commands (git, bash/PowerShell scripts)
   • Validation and quality checks
   • Output artifact specifications

4. Guidelines (specify.md200-262):

   • Quality standards
   • Section requirements
   • Success criteria rules

Sources: templates/commands/specify.md1-262

The tasks.md Template

The tasks.md template shows variation in structure for different command types:

Structural Differences:

1. Different prerequisite script (tasks.md12-14): Uses check-prerequisites.sh instead of feature creation
2. Multiple input sources (tasks.md29-32): Reads plan.md, spec.md, data-model.md, contracts/
3. Detailed formatting rules (tasks.md70-140): Extensive checklist format specification
4. Optional test generation (tasks.md74): Conditional task creation based on requirements

Sources: templates/commands/tasks.md1-140

Template Processing Workflow

Templates are processed during project initialization to generate agent-specific command files.

Processing Stages

Stage 1: Frontmatter Extraction

• Parse YAML between --- delimiters
• Validate required fields (description, scripts)
• Extract handoff configurations

Stage 2: Script Resolution

• Select sh or ps script path based on target agent
• Substitute {SCRIPT} placeholder with resolved path
• Preserve script arguments and flags

Stage 3: Placeholder Substitution

• Convert {ARGS} to $ARGUMENTS (Markdown) or {{args}} (TOML)
• Preserve $ARGUMENTS as runtime placeholder
• Resolve environment-specific placeholders

Stage 4: Path Rewriting

• Adjust templates/ references to .specify/ for packaged projects
• Convert relative paths based on agent directory structure
• Handle agent-specific command directories

Stage 5: Format Conversion

• For Markdown agents: Preserve body as-is with substitutions
• For TOML agents: Wrap in TOML structure with description and prompt fields
• Apply agent-specific formatting conventions

Sources: templates/commands/specify.md1-262 templates/commands/tasks.md1-140

Template Design Patterns

Multi-Stage Workflow Pattern

Commands like specify.md implement multi-stage workflows with validation gates:

Implementation:

• Step 6 in specify.md (specify.md104-196): Quality validation checklist
• Iterative refinement with max 3 attempts
• Clarification prompts for unresolved markers

Sources: templates/commands/specify.md104-196

Script-First Execution Pattern

Templates that interact with the filesystem follow a script-first pattern:

Key Characteristics:

• Always run script first to get environment state (specify.md60-72 tasks.md27)
• Parse JSON output for file paths and variables
• Use script output to guide subsequent operations
• Single script execution per command invocation

Sources: templates/commands/specify.md60-72 templates/commands/tasks.md27

Conditional Section Pattern

The tasks.md template demonstrates conditional content generation:

Implementation Approach:

• Document conditions in template guidelines (tasks.md74)
• Let agent decide based on available inputs (tasks.md29-32)
• Provide clear decision criteria (tasks.md110-140)

Sources: templates/commands/tasks.md29-140

Template Maintenance and Extension

Adding New Command Templates

To add a new command template:

1. Create template file: templates/commands/{command-name}.md
2. Define frontmatter:

3. Structure body: User Input → Outline → Guidelines
4. Use placeholders: $ARGUMENTS, {SCRIPT}, {ARGS}
5. Test with multiple agents: Verify Markdown and TOML rendering

Modifying Existing Templates

When modifying templates, consider:

1. Backward compatibility: Existing projects may have generated files
2. Multi-agent impact: Changes affect all 16+ supported agents
3. Placeholder consistency: Maintain standard placeholder patterns
4. Documentation synchronization: Update related guidelines sections

Template Validation Rules

Templates must satisfy these constraints:

Rule	Validation
Frontmatter required	Must have description and scripts fields
Dual scripts	Both sh and ps paths must be specified
User Input section	Must include $ARGUMENTS placeholder section
Outline section	Must provide step-by-step instructions
Script JSON output	Must parse JSON from script execution
Path resolution	All file paths must be resolvable

Sources: templates/commands/specify.md1-262 templates/commands/tasks.md1-140