Shep Kit:Implement
Validate specs and autonomously execute implementation tasks with status tracking. Use after /shep-kit:plan when ready to start implementation. Part of the Shep autonomous SDLC platform — https://shep.bot
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Shep Kit:Implement when an AI agent needs a reusable SKILL.md workflow for this job: Validate specs and autonomously execute implementation tasks with status tracking. Use after /shep-kit:plan when ready to start implementation. Part of the Shep autonomous SDLC platform — https://shep.bot
When not to use it
Skip Shep Kit:Implement when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/shep-kitimplement # Save SKILL.md to ~/.claude/skills/shep-kitimplement/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/shep-kitimplement/SKILL.md. For a shared project, commit the folder at .claude/skills/shep-kitimplement/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Shep Kit:Implement skill for this task: User says "implement", "start implementation", "execute tasks". Confirm any required inputs or files before making changes.
What supports this recommendation?
83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 92/100
- Practical detail
- 92/100
- Source evidence
- 62/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Autonomous Implementation Executor
## When to Use
Use this skill after `/shep-kit:plan` has created `plan.yaml` and `tasks.yaml`, and you're ready to start implementation.
**Triggers:**
- User says "implement", "start implementation", "execute tasks" - User runs `/shep-kit:implement` explicitly - After completing planning phase and ready to write code
**Don't use if:**
- Planning is not complete (`plan.yaml` or `tasks.yaml` missing) - Specs have open questions that need resolution - Architecture decisions are not finalized
## What This Skill Does
1. **Pre-Implementation Validation** - Comprehensive quality gates 2. **Autonomous Task Execution** - Executes all tasks from `tasks.yaml` sequentially 3. **Real-Time Status Tracking** - Updates `feature.yaml` throughout execution 4. **Smart Error Handling** - Retry with debugging (max 3 attempts per task) 5. **Session Resumption** - Automatically continues from last task on re-run
## Prerequisites
**Required YAML source files in spec directory:**
- `spec.yaml` - Complete feature specification - `research.yaml` - Technical decisions documented - `plan.yaml` - Implementation strategy - `tasks.yaml` - Task breakdown with acceptance criteria - `feature.yaml` - Status tracking file (created by `:new-feature`)
## Workflow
### Phase 1: Validation Gate
**Run comprehensive validation BEFORE starting implementation:**
```bash pnpm spec:validate <feature-id> ```
This script validates all 3 categories (completeness, architecture, consistency) against the YAML source files. See `validation/*.md` for the detailed rules it implements.
#### 1.1 Basic Completeness Check
- [ ] Required YAML files exist (`spec.yaml`, `research.yaml`, `plan.yaml`, `tasks.yaml`, `feature.yaml`) - [ ] All required keys present in each YAML file - [ ] Open questions resolved (`openQuestions[].resolved: true` in YAML) - [ ] Tasks have clear acceptance criteria (`tasks.yaml` tasks[].acceptanceCriteria) - [ ] Success criteria defined in `spec.yaml`
**Validation rules:** `validation/completeness.md`
#### 1.2 Architecture & Conventions Check
- [ ] Clean Architecture principles documented in `plan.yaml` content - [ ] **TypeSpec contracts defined** for new domain entities - [ ] **TDD phases explicitly outlined** (RED-GREEN-REFACTOR cycles) in `plan.yaml` - [ ] **Test coverage targets specified** - [ ] Repository pattern used for data access (if applicable)
**Validation rules:** `validation/architecture.md`
#### 1.3 Cross-Document Consistency Check
- [ ] Task count in `tasks.yaml` tasks[] matches `plan.yaml` phases[].taskIds - [ ] Acceptance criteria align with spec success criteria - [ ] Research decisions referenced in plan - [ ] No contradictions between spec/plan/research YAML files - [ ] Dependencies between tasks are valid (`tasks.yaml` tasks[].dependencies)
**Validation rules:** `validation/consistency.md`
#### 1.4 Auto-Fix (if needed)
**Apply ONLY safe structural fixes:**
- Add missing optional YAML keys with defaults - Add missing `tasks.yaml` from template if only `plan.yaml` exists
**Show summary of auto-fixes and require user approval before proceeding.**
#### 1.5 Blocking Issues
**If `pnpm spec:validate` finds blocking issues, STOP and report:**
- Unresolved open questions in YAML - Missing critical YAML keys (acceptance criteria, TDD phases) - Architecture violations - Cross-document contradictions
**Display validation report (see `examples/validation-report.md`) and exit.**
### Phase 2: Session Resumption Check
**Read `feature.yaml` to determine state:**
```yaml # Check current state current_phase = feature.yaml:status.phase current_task = feature.yaml:status.currentTask progress = feature.yaml:status.progress ```
**Display status summary:**
``` Feature {ID}: {Name} Progress: {completed}/{total} tasks ({percentage}%) Current: {currentTask} Last updated: {lastUpdated} ```
**Validate current state:**
1. If `currentTask` is not null, verify work is complete: - Check files exist for previous task - Run tests for completed work - Verify build passes 2. If validation passes → continue with `currentTask` or next task 3. If validation fails → re-attempt `currentTask`
**Auto-resume immediately (no user prompt).**
### Phase 3: Autonomous Task Execution
**Execute tasks from `tasks.yaml` in sequence:**
#### For each task:
**3.1 Update Status (Start)**
```yaml # Update feature.yaml status: currentTask: 'task-N' lastUpdated: '<timestamp>' lastUpdatedBy: 'shep-kit:implement' ```
**3.2 Read Task Definition**
- Load task from `tasks.yaml` (structured YAML data) - Read: `tasks[N].description`, `tasks[N].acceptanceCriteria`, `tasks[N].tddPhases`, `tasks[N].dependencies`
**3.3 Execute TDD Cycle**
**CRITICAL: Follow TDD discipline EXACTLY as defined in plan:**
1. **RED Phase:**
- Write failing tests FIRST (as specified in plan) - Ensure tests fail (expected behavior) - Commit failing tests
2. **GREEN Phase:**
- Write minimal implementation to pass tests - Run tests until green - Do NOT add extra features
3. **REFACTOR Phase:** - Improve code quality - Keep tests green throughout - Extract helpers, improve naming, reduce duplication
**3.4 Run Verification**
```bash pnpm test # All tests must pass pnpm build # Build must succeed pnpm typecheck # No TypeScript errors pnpm lint # No lint errors ```
**3.5 Handle Result**
**If verification PASSES:**
```yaml # Update feature.yaml status: progress: completed: { N+1 } percentage: { calculated } currentTask: 'task-{N+1}' lastUpdated: '<timestamp>' ```
Continue to next task.
**If verification FAILS:** → Enter Error Handling (Phase 4)
### Phase 4: Error Handling (Retry with Debug Cycle)
**When task fails:**
**4.1 Capture Error**
```yaml # Update feature.yaml errors: current: taskId: 'task-N' attempt: 1 error: '<concise description>' details: '<full error message/stack trace>' timestamp: '<timestamp>' resolved: false ```
**4.2 Run Systematic Debugging**
1. Analyze error root cause 2. Identify fix strategy 3. Apply fix 4. Re-run verification
**4.3 Check Retry Count**
- If fixed → clear `errors.current`, add to `errors.history`, continue - If still failing AND attempt < 3 → increment attempt, retry from 4.2 - If still failing AND attempt >= 3 → STOP execution
**4.4 Stop After 3 Failed Attempts**
```yaml # Update feature.yaml status: phase: 'blocked'
tasks: failed: ['task-N']
errors: current: taskId: 'task-N' attempt: 3 error: '<description>' details: '<full details>' timestamp: '<timestamp>' resolved: false ```
**Display error report to user:**
``` ❌ Implementation blocked on task-N after 3 retry attempts
Error: <concise description>
Details: <full error message>
Manual intervention required.
To resume: Fix the issue and re-run /shep-kit:implement ```
### Phase 5: Completion
**When all tasks complete successfully:**
**5.1 Update feature.yaml**
```yaml status: phase: 'ready-for-review' progress: completed: { total } percentage: 100 currentTask: null
checkpoints: - phase: 'implementation-complete' completedAt: '<timestamp>' completedBy: 'shep-kit:implement' ```
**5.2 Display completion summary:**
``` ✅ Feature {ID}: Implementation complete!
Summary: - {total} tasks completed - All tests passing - Build successful - Ready for code review
Next steps: 1. Review all changes 2. Run `/shep-kit:commit-pr` to create pull request ```
## Important Rules
### TDD Discipline
**NEVER skip RED-GREEN-REFACTOR cycle:**
- RED: Tests ALWAYS come first - GREEN: Implement minimal code to pass - REFACTOR: Improve while keeping tests green
**If plan doesn't specify TDD phases, STOP and ask user to update plan.**
### Task Execution Order
**Execute tasks STRICTLY in order from `tasks.yaml`:**
- Respect task dependencies (`tasks[].dependencies`) - Do not skip tasks - Do not reorder tasks
### Status Tracking
**Update `feature.yaml` after EVERY state change:**
- Starting new task - Completing task - Recording error - Resolving error
**See `docs/development/feature-yaml-protocol.md` for update patterns.**
### Error Boundaries
**Maximum 3 automatic retry attempts per task:**
- Prevents infinite loops - Allows self-correction for common issues - Requires human intervention for persistent problems
### Autonomous Execution
**No user prompts during execution (except for auto-fix approval):**
- Show status summaries - Display progress updates - Continue automatically - Only stop on blocking errors
## Reference Documentation
- **Feature YAML Protocol:** `docs/development/feature-yaml-protocol.md` - **Validation Rules:** `validation/*.md` in this skill directory - **Spec-Driven Workflow:** `docs/development/spec-driven-workflow.md` - **TDD Guide:** `docs/development/tdd-guide.md`
## Examples
See `examples/validation-report.md` for example validation output and error handling scenarios.
---
**Remember:** This skill bridges planning and implementation. Validation ensures quality gates are met before any code is written. Autonomous execution with bounded retries maximizes velocity while maintaining safety.
Intended uses
- User says "implement", "start implementation", "execute tasks"
- User runs /shep-kit:implement explicitly
- After completing planning phase and ready to write code
- Planning is not complete (plan.yaml or tasks.yaml missing)
- Specs have open questions that need resolution
- Architecture decisions are not finalized
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.