The check-prerequisites script is a unified utility used to identify the active feature directory and catalog available design documents. It is a critical component of the Spec-Driven Development (SDD) workflow, specifically serving as the discovery mechanism for commands like /speckit.tasks and /speckit.implement.
The script ensures that the AI agent has complete visibility into the project's planning artifacts (like spec.md, plan.md, and data-model.md) before generating tasks or starting implementation. It supports both text-based status reporting for users and JSON output for machine consumption by AI agents.
Sources: scripts/bash/check-prerequisites.sh3-19 scripts/powershell/check-prerequisites.ps13-15
The check-prerequisites script provides a single source of truth for:
plan.md) exist before a workflow phase begins.Sources: scripts/bash/check-prerequisites.sh5-6 scripts/bash/check-prerequisites.sh140-158
The script is typically invoked from the repository root. It is available in both Bash (for Unix/macOS/Linux) and PowerShell (for Windows).
Bash:
PowerShell:
| Parameter (Bash) | Parameter (PS) | Description |
|---|---|---|
--json | -Json | Output results in JSON format for AI agent parsing. |
--require-tasks | -RequireTasks | Forces a check for tasks.md. Used during the implementation phase. |
--include-tasks | -IncludeTasks | Includes tasks.md in the AVAILABLE_DOCS list if it exists. |
--paths-only | -PathsOnly | Skips file validation and only outputs resolved path variables. |
--help, -h | -Help, -h | Displays usage information and examples. |
Sources: scripts/bash/check-prerequisites.sh10-15 scripts/powershell/check-prerequisites.ps110-15
The script relies on common.sh (or common.ps1) to resolve paths. It uses the get_feature_paths function (Bash) or Get-FeaturePathsEnv (PowerShell) to populate variables based on the current Git branch or environment. This process is resilient to branch names; if feature.json exists, it can pin the feature directory even on non-standard branches. In --paths-only mode, the script passes --no-persist to get_feature_paths to avoid side effects like writing to feature.json.
Diagram: Natural Language to Code Entity Space (Path Resolution)
Sources: scripts/bash/check-prerequisites.sh81-90 scripts/powershell/check-prerequisites.ps159-66 tests/test_check_prerequisites_paths_only.py80-82
The script performs sequential checks to build the AVAILABLE_DOCS list and validate environment readiness.
Diagram: Execution Flow and Validation Logic
Sources: scripts/bash/check-prerequisites.sh120-158 scripts/powershell/check-prerequisites.ps190-131
--json)Used by AI agents to programmatically determine which files to read for context.
Note: If --paths-only is combined with --json, the output includes detailed path variables like REPO_ROOT, FEATURE_SPEC, and IMPL_PLAN.
Sources: scripts/bash/check-prerequisites.sh94-108 scripts/bash/check-prerequisites.sh160-180
Used for human-readable status checks in the terminal.
The status of files is reported via helper functions like check_file (Bash) or Test-FileExists (PowerShell).
Sources: scripts/bash/check-prerequisites.sh182-195 scripts/powershell/check-prerequisites.ps1140-153
The script enforces a strict hierarchy of documentation:
FEATURE_DIR and plan.md must always exist for the script to succeed (unless --paths-only is used). scripts/bash/check-prerequisites.sh121-131 scripts/powershell/check-prerequisites.ps191-103tasks.md is required only if the --require-tasks flag is passed. scripts/bash/check-prerequisites.sh134-138 scripts/powershell/check-prerequisites.ps1106-111research.md, data-model.md, quickstart.md, and the contracts/ directory (ensuring it contains files). scripts/bash/check-prerequisites.sh141-157 scripts/powershell/check-prerequisites.ps1114-130jqThe Bash implementation includes a fallback mechanism to generate JSON using printf and a json_escape utility if the jq command-line tool is not installed.
Sources: scripts/bash/check-prerequisites.sh105-108 scripts/bash/check-prerequisites.sh172-180
The PowerShell version (check-prerequisites.ps1) mirrors the Bash logic exactly, using Test-Path for validation and ConvertTo-Json for output.
Sources: scripts/powershell/check-prerequisites.ps157 scripts/powershell/check-prerequisites.ps1133-138
While check-prerequisites validates the environment, setup-plan.sh is responsible for initializing the plan.md file using resolve_template to find the appropriate plan-template from the project's configuration.
Diagram: Natural Language to Code Entity Space (Plan Setup & Prerequisites)
Sources: scripts/bash/setup-plan.sh31-48 scripts/bash/setup-plan.sh66-73
Refresh this wiki