Implement an OpenSpec change iteratively until all tasks complete
Implements OpenSpec changes iteratively by executing tasks from tasks.md until all marked complete.
/plugin marketplace add GantisStorm/essentials-claude-code/plugin install essentials@essentials-claude-code<change-id> [--step|--auto] [--max-iterations N]Implement an approved OpenSpec change iteratively, keeping tasks.md in sync until all tasks are complete.
IMPORTANT: Keep edits minimal and focused on the requested change. Update tasks.md after each task completion. Use the plan_reference for full implementation details if needed. The loop will not end until ALL tasks are marked [x].
This command is an alternative to the 5-stage Beads workflow. Use it when you want the iterative loop benefits without Beads:
| Workflow | When to Use |
|---|---|
/implement-loop | Plans from /plan-creator, /bug-plan-creator, /code-quality-plan-creator |
/spec-loop | OpenSpec changes (proposal.md + tasks.md) |
/beads-loop | Large specs converted to self-contained Beads |
The command accepts the following arguments:
<change-id> - The OpenSpec change to implement--step (default) or --auto - Controls pause behavior--max-iterations N - Maximum number of iterationsRun the setup script:
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-spec-loop.sh" $ARGUMENTS
You are now in spec loop mode. Your task is to implement the OpenSpec change completely.
openspec/AGENTS.md if you need additional OpenSpec conventions or clarifications.Read these files from the change directory:
proposal.md - The approved change proposaldesign.md - Technical design (if present)tasks.md - The task checklist to completeUse TodoWrite to create a todo for each task in tasks.md:
Example todo structure:
1. [pending] Implement user authentication endpoint
2. [pending] Add validation middleware
3. [pending] Create unit tests
4. [pending] Update API documentation
For each task:
tasks.md to mark the task [x]IMPORTANT: After completing each task, update tasks.md:
# Before
- [ ] Implement user authentication endpoint
# After
- [x] Implement user authentication endpoint
Before the loop ends:
tasks.md is marked [x]proposal.md are satisfiedWhen you try to exit:
tasks.md for uncompleted tasks[x] → loop ends, implementation completeWhen all tasks are complete, you may archive the change:
openspec archive <change-id>
Step mode pauses after each task for human control. This prevents context compaction and quality degradation on large specs.
After completing each task, you MUST:
tasks.md to get current statusBefore pausing, output execution status:
===============================================================
TASK COMPLETED: <task-name>
===============================================================
Progress: N/M tasks complete
EXECUTION ORDER (remaining):
Next → Task 3: Add validation middleware
Then → Task 4: Create unit tests
Then → Task 5: Run integration tests
===============================================================
Then use AskUserQuestion:
The options MUST include:
Example with 2 remaining tasks:
Use AskUserQuestion with:
- question: "Task complete. Next: Add validation middleware. Continue?"
- header: "Next step"
- options:
- label: "Continue (Recommended)"
description: "Proceed to: Add validation middleware"
- label: "Stop"
description: "End the spec loop here"
- label: "Create unit tests"
description: "Skip to: Create unit tests"
Based on the response:
Auto mode (--auto flag): Skips pauses but still follows task order from tasks.md.
If context is compacted and you lose track:
Quick Recovery:
openspec show <change-id> for summarytasks.md to see what's done and what's nextDeep Recovery (using back-references):
The OpenSpec change has a chain of back-references:
proposal.md → plan_reference (source plan)
design.md → Reference Implementation (FULL code)
tasks.md → Exit Criteria (EXACT commands)
specs/*.md → Requirements with scenarios
grep "Source Plan" openspec/changes/<id>/proposal.mdReference Commands:
Use these when you need additional context:
# Quick context
openspec show <id> --json --deltas-only
# Find plan reference
grep "Source Plan" openspec/changes/<id>/proposal.md
# Read full implementation code
cat openspec/changes/<id>/design.md | grep -A 100 "Reference Implementation"
# Read exit criteria
cat openspec/changes/<id>/tasks.md | grep -A 20 "Exit Criteria"
| Scenario | Action |
|---|---|
| Context compacted mid-implementation | Use Quick Recovery or Deep Recovery steps above |
| Task verification fails | Keep task as in_progress, debug and fix before marking complete |
| Missing proposal.md or tasks.md | Run openspec show <change-id> to verify change exists |
| Uncompleted tasks remain at exit | Loop automatically continues until all tasks marked [x] |
# Implement a specific OpenSpec change with step mode (default)
/spec-loop AUTH-001
# Implement with auto mode (no pauses)
/spec-loop AUTH-001 --auto
# Implement with iteration limit
/spec-loop AUTH-001 --max-iterations 10
# Implement with step mode explicitly
/spec-loop AUTH-001 --step