| name | speckit-ralph-implement |
| description | Orchestrate task-by-task implementation (Ralph loop) until all tasks are complete. |
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Pre-Loop: Quality Gates Validation
Ralph uses two gates: an optional fast scoped gate (.specify/quality-gates-fast.sh) per iteration and the full gate (.specify/quality-gates.sh) once after the loop terminates.
Before configuring the loop, validate that quality gates are set up. Run the following checks using the Bash tool:
- Full gate file existence:
test -f .specify/quality-gates.sh && echo "EXISTS" || echo "MISSING"
- Full gate non-empty content:
grep -v '^\s*#' .specify/quality-gates.sh | grep -v '^\s*$' | head -1
- Fast gate file existence:
test -f .specify/quality-gates-fast.sh && echo "EXISTS" || echo "MISSING"
- Fast gate non-empty content (only if file exists):
grep -v '^\s*#' .specify/quality-gates-fast.sh | grep -v '^\s*$' | head -1
If the full gate file is MISSING or its grep produces no output, display this error and STOP:
ERROR: Quality gates file is missing or empty.
Expected: .specify/quality-gates.sh with executable commands
Found: File missing or contains only comments/whitespace
The full quality gates file is required for Ralph to validate task implementations.
Create or update .specify/quality-gates.sh with your project's quality gate
commands (e.g., npm test && npm run lint). The file must exit 0 for gates to pass.
Optionally, also create .specify/quality-gates-fast.sh with scoped commands
that check only changed files for faster per-iteration feedback.
If the fast gate file is missing, note this for the LOOP_CONFIG below — the full gate will be used per-iteration instead.
Pre-Loop: Task Counting
After resolving FEATURE_DIR (the orchestrator handles this), count tasks in FEATURE_DIR/tasks.md:
- Count incomplete tasks:
grep -c '^\s*- \[ \]' "<FEATURE_DIR>/tasks.md"
- Count completed tasks:
grep -c '^\s*- \[x\]' "<FEATURE_DIR>/tasks.md"
- If no incomplete tasks remain, exit early — nothing to implement
- Calculate dynamic max iterations:
incomplete_tasks + 10
Use the calculated value as MAX_ITERATIONS in the loop configuration below.
Loop Configuration
Set the following LOOP_CONFIG values for this execution:
- AGENT_NAME: ralph
- AGENT_DISPLAY_NAME: Ralph
- AGENT_FILE: .claude/agents/ralph.md
- SLASH_COMMAND_REF: /speckit-implement
- PROMISE_TAG: ALL_TASKS_COMPLETE
- PREREQ_FLAGS: --json --require-tasks --include-tasks
- REQUIRED_ARTIFACTS: spec.md, plan.md, tasks.md
- MAX_ITERATIONS: (use the value calculated in Task Counting above)
- EXTRA_PROMPT_SUFFIX: Quality gates: bash .specify/quality-gates-fast.sh (if the fast gate exists; otherwise use: bash .specify/quality-gates.sh)
- REPORT_MODE: tasks
Execute
Read and follow the instructions in .claude/agents/loop-orchestrator.md, using the LOOP_CONFIG values above. Pass $ARGUMENTS through for argument parsing.
Post-Loop: End-of-Loop Full Quality Gate
Run only when the loop exited via the success path (<promise>ALL_TASKS_COMPLETE</promise> observed). Skip this step on max-iterations, stuck, or failure exits.
Run via Bash tool:
bash .specify/quality-gates.sh
If it exits non-zero, treat the loop as incomplete: the fast gate missed a regression in files outside the per-iteration scope. Set the completion status to failure with reason "end-of-loop full quality gates failed", surface the failing output in the report, and suggest rerunning ralph or fixing the issue manually before re-running this command.
If it exits zero, proceed to tasks verification.
Post-Loop: Tasks Verification
After the loop orchestrator reports completion via the promise tag, also verify tasks.md directly — if no - [ ] lines remain and at least one - [x] exists, confirm completion. If incomplete tasks remain despite the promise tag, report the discrepancy.
Examples
/speckit-ralph-implement — Auto-detect spec dir from current branch, use default max iterations (incomplete_tasks + 10)
/speckit-ralph-implement specs/003-fix-pipeline-delegation — Run for specific spec dir
/speckit-ralph-implement 5 — Auto-detect spec dir, limit to 5 iterations
/speckit-ralph-implement specs/003-fix-pipeline-delegation 5 — Specific spec dir with 5 max iterations