shep-kit-implement

name	shep-kit:implement
description	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
metadata	{"version":"1.0.0","author":"Shep AI (https://shep.bot)","homepage":"https://shep.bot","repository":"https://github.com/shep-ai/shep"}

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:

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:

# 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)

# 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

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:

# 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

# 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

# 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

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.