speckit-tasks

name	speckit-tasks
description	Generate an actionable, dependency-ordered set of Beads via 'br' CLI for the feature based on available design artifacts.
compatibility	Requires spec-kit project structure with .specify/ directory and Beads (br) CLI
metadata	{"author":"github-spec-kit","source":"templates/commands/tasks.md"}

User Input

$ARGUMENTS

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

Pre-Execution Checks

Check for extension hooks (before Bead generation):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.before_tasks 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

1. Setup: Run .specify/scripts/bash/check-prerequisites.sh --json from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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").

2. Load design documents: Read from FEATURE_DIR:

   • Required: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
   • Optional: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
   • Note: Not all projects have all documents. Generate beads based on what's available.

3. Execute Bead generation workflow:

   • Extract SPEC_ID from the FEATURE_DIR basename (e.g., if path is specs/003-user-auth, SPEC_ID is 003-user-auth)
   • Load plan.md and extract tech stack, libraries, project structure
   • Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
   • If data-model.md exists: Extract entities and map to user stories
   • If contracts/ exists: Map interface contracts to user stories
   • If research.md exists: Extract decisions for setup tasks
   • Determine Workflow Mode: Based on complexity and risk, classify the work as direct_task, spike, small_change, standard_feature, or high_risk_feature.
   • Identify Unknowns: Highlight any MEDIUM/HIGH risks that require a Spike bead (Phase 0) before execution.
   • Generate beads organized by user story (see Bead Generation Rules below)
   • Generate dependency graph showing user story completion order
   • Validate completeness (each user story has all needed beads, independently testable)

4. Create Beads (PHASE BY PHASE): To avoid exceeding context limits and to provide immediate value, you MUST ACTUALLY EXECUTE the br create commands ONE PHASE AT A TIME using your terminal/command tools, instead of just printing the scripts in the chat for the user to review.

   • Start by executing the commands to create beads for Phase 0 if there are risks/unknowns that require a Spike. Otherwise, start from Phase 1.
   • After successfully creating the beads for the current phase, STOP and ask the user: "I have created the beads for Phase X. Please review them using br list. Should I proceed to create the beads for Phase Y?"
   • Wait for the user's confirmation before creating the beads for the next phase.
   • Continue this interactive process until all phases are created.
   • Phases to follow sequentially:
     • Phase 1: Setup tasks (project initialization)
     • Phase 2: Foundational tasks (blocking prerequisites for all user stories)
     • Phase 3+: One phase per user story (in priority order from spec.md)
     • Final Phase: Polish & cross-cutting concerns
   • Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
   • All tasks must follow the strict Bead Command format (see Bead Generation Rules below).
   • Execute br dep add commands to establish dependencies if applicable.
   • Checklist Blocker Linkage: Query existing open beads (br list --status=open) to find any beads of type chore or checklist generated by speckit-checklist. If any exist, you MUST execute br dep add commands to make your Phase 1 or Phase 2 implementation beads depend on those checklist beads.

5. Report: After ALL phases have been created and confirmed, output a summary:

   • Total Bead count
   • Bead count per user story
   • Parallel opportunities identified
   • Independent test criteria for each story
   • Suggested MVP scope (typically just User Story 1)

6. Check for extension hooks: After Beads are generated, check if .specify/extensions.yml exists in the project root.

   • If it exists, read it and look for entries under the hooks.after_tasks 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

Context for task generation: $ARGUMENTS

The br CLI commands should be immediately executable - each bead must be specific enough that an LLM can complete it without additional context.

Bead Generation Rules

CRITICAL: You MUST use /effort max (or act with maximal effort) and elaborate extensively to create a comprehensive and granular set of beads with tasks, subtasks, and dependency structure overlaid. The whole thing must be totally self-contained and self-documenting.

Bead Planning & Sizing Rules

• Worker-Sized: Beads must represent validated current work, not speculative future planning. Each bead should represent a bounded execution pass.
• Workflow Mode: Explicitly determine the mode based on risk: direct_task (obvious), spike (assumption validation), small_change (low risk), standard_feature (ordered capability), high_risk_feature (broad blast radius).
• Handle Unknowns First: If there are MEDIUM/HIGH unknowns or assumptions, generate a spike bead or validation bead (Phase 0) before any execution beads to prove feasibility.
• Outcomes over Layers: Organize beads around end-to-end outcomes (stories) rather than horizontal architecture layers (e.g., prefer "User Auth Bead" over a generic "Database Bead").

Bead Content Requirements

For every bead generated, you MUST include a detailed description (e.g., using a --description or --body flag as supported by the tool, or via a multi-line string) that contains:

• Relevant background and context.
• Reasoning/justification and considerations.
• Goals and intentions, including thought process and how it serves the over-arching goals of the project.
• Exit State & Verification: Observable truth of what must be true after execution, and exactly how to test/verify it.
• Granular Tasks & Subtasks: Break down the bead into highly detailed, actionable subtasks.

Bead Command Format (REQUIRED)

You MUST NOT generate a markdown checklist like - [ ]. Instead, you MUST use the br tool repeatedly to output br create commands directly.

Every actionable item MUST strictly follow this command format. Notice how the command output is captured into a variable to allow for automated dependency linking:

BEAD_ID_NAME=$(br create --title="[P?] [Story?] [Mode: {MODE}] [Phase: {PHASE_NAME}] [Spec: {SPEC_ID}] Title" --type=task --priority=2 --description="
### Spec Reference
- **Spec ID**: {SPEC_ID} (Derived from the FEATURE_DIR basename)
- **Phase**: {PHASE_NAME}

### Background & Reasoning
[Detailed self-contained documentation, reasoning, considerations, and how it serves over-arching goals]

### Exit State & Verification
[Observable truth: What must be true after execution? How to verify/test it?]

### Granular Subtasks
- Subtask 1
- Subtask 2
") | grep -o 'br-[0-9]\+')

Format Components:

1. br create via variable: ALWAYS capture the bead ID into a shell variable (e.g., BEAD_SETUP_1=$(br create ... | grep -o 'br-[0-9]\+')) to enable automated dependency linking via br dep add.
2. [P] marker: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks).
3. [Story] label: REQUIRED for user story phase tasks only (e.g., [US1], [US2]).
4. [Mode: {MODE}] tag: REQUIRED. Explicitly classify the workflow mode (e.g., direct_task, spike, small_change).
5. [Phase: {PHASE_NAME}] tag: REQUIRED. Include the current phase (e.g., Phase 1, Phase 2, etc.) in the title.
6. [Spec: {SPEC_ID}] tag: REQUIRED. Extract the Spec ID from the FEATURE_DIR basename (e.g. 003-user-auth) and include it in the title.
7. Title: Clear action.
8. Priority: --priority=... (Default to 2 unless otherwise specified).
9. Detailed Description: Use a multi-line string to embed the Spec Reference, Background & Reasoning, Exit State & Verification, and Granular Subtasks as shown above.

Dependency Management (REQUIRED)

You MUST overlay a clear dependency structure. Establish the exact sequence and blocking relationships between beads by generating br dep add $DEPENDENT_BEAD $BLOCKING_BEAD commands using the variables you captured during creation.

Phase Structure

• Phase 0: Discovery & Spikes (ONLY if MEDIUM/HIGH unknowns exist to prove feasibility before execution)
• Phase 1: Setup (project initialization)
• Phase 2: Foundational (blocking prerequisites - MUST complete before user stories)
• Phase 3+: User Stories in priority order (P1, P2, P3...)
  • Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
  • Each phase should be a complete, independently testable increment
• Final Phase: Polish & Cross-Cutting Concerns

Ensure you group the br create and br dep add commands clearly under their respective phase headings.