superspec:execute
A task-execution framework that uses subagents and strict phase protocols to maintain context and code quality.
Install
mkdir -p .claude/skills/superspec-execute && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/11780" && unzip -o skill.zip -d .claude/skills/superspec-execute && rm skill.zipInstalls to .claude/skills/superspec-execute
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when executing implementation plans in current session. Dispatches fresh subagent per task with two-stage review. Spec Reviewer validates against Specs, Quality Reviewer checks code quality.Key capabilities
- →Dispatch fresh subagents for each task in an implementation plan
- →Conduct a two-stage review process: Spec Compliance Review and Code Quality Review
- →Ensure every requirement has an implementation and every scenario has a test during Spec Compliance Review
- →Check for error handling, type safety, SOLID principles, and tests during Code Quality Review
- →Maintain persistent user-visible progress in `tasks.md` after each task completion
- →Enforce Test-Driven Development (TDD) for every task
How it works
The skill executes implementation plans by dispatching subagents for individual tasks, followed by a two-stage review process for spec compliance and code quality. It enforces TDD and maintains progress records.
Inputs & outputs
When to use superspec:execute
- →Executing multi-phase development plans
- →Maintaining context during large code changes
- →Automating code review and task completion
About this skill
Subagent-Driven Development
🔴 CRITICAL: Phase Protocol (Prevents Context Drift!)
Before starting ANY phase, you MUST read skills/phase-protocol/SKILL.md.
This protocol prevents you from forgetting tasks during long development sessions:
┌────────────────────────────────────────────────────────────────┐
│ PHASE PROTOCOL SUMMARY │
├────────────────────────────────────────────────────────────────┤
│ ENTRY (start of each phase): │
│ 1. Read phase-protocol skill (refresh context) │
│ 2. Read tasks.md (get task list) │
│ 3. CREATE TODO IMMEDIATELY ← Before reading other docs! │
│ 4. Gate: Verify TODO completeness │
│ 5. Read plan.md, design.md, specs/*.md │
│ 6. Gate: Output key understanding │
│ 7. Begin implementation │
├────────────────────────────────────────────────────────────────┤
│ EXIT (end of each phase): │
│ 1. Update tasks.md │
│ 2. Git commit │
│ 3. Re-read phase-protocol skill ← Loop back! │
│ 4. Create next phase TODO │
└────────────────────────────────────────────────────────────────┘
Why this works: TODO survives context compression. Exit Gate forces re-read.
⚠️ CRITICAL: Document Updates (Read This First!)
You MUST maintain TWO separate progress records:
| Tool | Purpose | When |
|---|---|---|
TodoWrite | Your internal tracking (ephemeral, lost after session) | At start of execution |
tasks.md file | Persistent user-visible progress (survives sessions) | After EACH task completion |
TodoWrite is NOT a substitute for updating tasks.md!
After EVERY task completion, you MUST:
- ✅ Mark task
[x]insuperspec/changes/[id]/tasks.md - ✅ Update Status counts at top of
tasks.md - ✅ Update Completion Tracking table at bottom of
tasks.md
Self-check: If you only used TodoWrite without editing tasks.md, you did NOT update progress correctly!
Overview
Execute plan by dispatching fresh subagent per task, with two-stage review:
- Spec Compliance Review - Does implementation match Specs?
- Code Quality Review - Is the code well-written?
Core principle: Fresh subagent per task + two-stage review = high quality, fast iteration
Announce at start: "I'm using subagent-driven development to execute the plan."
When to Use
Have implementation plan?
↓ yes
Tasks mostly independent?
↓ yes
Stay in this session?
↓ yes
→ Use subagent-development
Prerequisites
- Proposal exists:
superspec/changes/[id]/proposal.md - Design exists:
superspec/changes/[id]/design.md- Required - Specs exist:
superspec/changes/[id]/specs/**/*.md - Plan exists:
superspec/changes/[id]/plan.md - Tasks exist:
superspec/changes/[id]/tasks.md - Specs validated:
superspec validate [id] --strictpasses
The Process
┌────────────────────────────────────────────────────────────────────┐
│ Per Task Loop │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 1. Dispatch Implementer Subagent │ │
│ │ - Provide: Full task text + context + Spec reference │ │
│ │ - Follows TDD: RED → GREEN → REFACTOR │ │
│ │ - Self-reviews before handoff │ │
│ └──────────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 2. Dispatch Spec Reviewer Subagent │ │
│ │ - Reads: superspec/changes/[id]/specs/[cap]/spec.md │ │
│ │ - Reads: Actual implementation code │ │
│ │ - Checks: │ │
│ │ ✓ Every Requirement has implementation │ │
│ │ ✓ Every Scenario has test │ │
│ │ ✓ No missing features │ │
│ │ ✓ No extra features (not in Spec) │ │
│ └──────────────────────────┬──────────────────────────────────┘ │
│ │ │
│ [Spec Compliant?] │
│ / \ │
│ No Yes │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────┐ ┌─────────────────────────────────┐ │
│ │ Implementer fixes │ │ 3. Dispatch Quality Reviewer │ │
│ │ spec gaps │ │ - Checks: Error handling, │ │
│ └──────────┬───────────┘ │ type safety, SOLID, tests │ │
│ │ │ - Classifies: Critical / │ │
│ └─→ Re-review │ Important / Suggestion │ │
│ └──────────────┬──────────────────┘ │
│ │ │
│ [Quality Approved?] │
│ / \ │
│ No Yes │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────┐ ┌──────────────────┐ │
│ │ Implementer fixes │ │ Mark complete + │ │
│ │ quality issues │ │ UPDATE DOCS! │ │
│ └──────────┬───────────┘ └────────┬─────────┘ │
│ │ │ │
│ └─→ Re-review ▼ │
│ Update tasks.md │
│ Update plan.md │
│ │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 4. External AI Review (if review.enabled in project.yaml) │ │
│ │ - Check task type: [FRONTEND] or [BACKEND] │ │
│ │ - Frontend → Use review.frontend.provider (gemini/codex) │ │
│ │ - Backend → Use review.backend.provider (codex/gemini) │ │
│ │ - Read external-review skill for details │ │
│ │ - CRITICAL: Hallucination check before applying fixes! │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘
[All tasks complete]
↓
┌────────────────────────────────────────────────────────────────────┐
│ Dispatch Final Code Reviewer │
│ - Reviews entire implementation │
│ - Checks cross-task consistency │
│ - Validates all Specs fully implemented │
└────────────────────────────────────────────────────────────────────┘
↓
Use superspec:finish-branch
Step 1: Setup (Phase Entry Protocol)
🔴 FOLLOW THE PHASE ENTRY PROTOCOL FROM phase-protocol SKILL:
1. READ phase-protocol skill: skills/phase-protocol/SKILL.md
→ This refreshes your context and provides the full protocol
2. READ tasks.md: superspec/changes/[id]/tasks.md
→ Identify which phase you are starting
→ Get the task list for this phase
3. CREATE TODO IMMEDIATELY ← 🔴 BEFORE READING OTHER DOCS!
→ Use TodoWrite with Entry Gate + Tasks + Exit Gate structure
→ This is CRITICAL: TODO survives context compression
→ See phase-protocol skill for TODO template
4. GATE: Verify TODO completeness
→ Output the completeness checklist
→ Ensure Entry (8) + Tasks (N) + Exit (3) items exist
5. Read plan.md: superspec/changes/[id]/plan.md
→ Extract task details and context
→ Note Spec references for each task
6. Read design.md: superspec/changes/[id]/design.md
→ Understand technical decisions
7. Read specs: superspec/changes/[id]/specs/**/*.md
→ Understand requirements and scenarios
8. **Detect frontend tasks** (see below)
9. GATE: Output key understanding
→ Must output phase goal, tasks, spec refs, technical approach
→ See phase-protocol skill for template
10. BEGIN IMPLEMENTATION
→ Now proceed with Per Task Loop
Frontend Task Detection
For each task, determine if it's a frontend task by checking:
Keywords in task description:
- UI, interface, component, page, view, form, modal, dialog
- Frontend, front-end, client-side
- Button, input, dropdown, navigation, menu, header, footer
- Layout, grid, flex, responsive, mobile
- Style, styling, theme, dark mode, light mode
- Animation, transition, hover, interaction
File types involved:
.tsx,.jsx,.vue,.css,.scss,.html,.svelte
Capability/Spec names containing:
ui,
Content truncated.
When not to use it
- →When the implementation plan does not exist
- →When the design, specs, plan, or tasks files do not exist
- →When specs are not validated
Prerequisites
Limitations
- →Requires `superspec/changes/[id]/tasks.md` to exist
- →Requires `superspec validate [id] --strict` to pass
- →Implementer subagents must follow TDD: RED → GREEN → REFACTOR
How it compares
This skill automates a structured subagent-driven development process with mandatory two-stage reviews and TDD, providing a more rigorous and consistent approach than manual task execution.
Compared to similar skills
superspec:execute side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| superspec:execute (this skill) | 0 | 6mo | Review | Advanced |
| resolve-conflicts | 81 | 8mo | Review | Intermediate |
| claude-automation-recommender | 47 | 2mo | Review | Beginner |
| codex-skill | 12 | 5mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
resolve-conflicts
antinomyhq
Use this skill immediately when the user mentions merge conflicts that need to be resolved. Do not attempt to resolve conflicts directly - invoke this skill first. This skill specializes in providing a structured framework for merging imports, tests, lock files (regeneration), configuration files, and handling deleted-but-modified files with backup and analysis.
claude-automation-recommender
anthropics
Analyze a codebase and recommend Claude Code automations (hooks, subagents, skills, plugins, MCP servers). Use when user asks for automation recommendations, wants to optimize their Claude Code setup, mentions improving Claude Code workflows, asks how to first set up Claude Code for a project, or wants to know what Claude Code features they should use.
codex-skill
feiskyer
Use when user asks to leverage codex, gpt-5, or gpt-5.1 to implement something (usually implement a plan or feature designed by Claude). Provides non-interactive automation mode for hands-off task execution without approval prompts.
git-advanced-workflows
wshobson
Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use when managing complex Git histories, collaborating on feature branches, or troubleshooting repository issues.
subagent-driven-development
davila7
Use when executing implementation plans with independent tasks in the current session
validate-openapi-specs
epieczko
Validates and registers hook manifest files (YAML) in the Hook Registry for versioned hook management.