Skip to main content
Agent skill

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 started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/shep-kitimplement
# Save SKILL.md to ~/.claude/skills/shep-kitimplement/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.