Autonomous Implementation Executor

When to Use

Use this skill after /shep-kit:plan has created plan.md and tasks.md, 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.md or tasks.md missing)
•Specs have open questions that need resolution
•Architecture decisions are not finalized

What This Skill Does

•Pre-Implementation Validation - Comprehensive quality gates
•Autonomous Task Execution - Executes all tasks from tasks.md sequentially
•Real-Time Status Tracking - Updates feature.yaml throughout execution
•Smart Error Handling - Retry with debugging (max 3 attempts per task)
•Session Resumption - Automatically continues from last task on re-run

Prerequisites

Required files in spec directory:

•spec.md - Complete feature specification
•research.md - Technical decisions documented
•plan.md - Implementation strategy
•tasks.md - 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:

1.1 Basic Completeness Check

• Required files exist (spec.md, plan.md, tasks.md, feature.yaml)
• All required sections present in each file
• Open questions resolved (no [ ] checkboxes with content)
• Tasks have clear acceptance criteria
• Success criteria defined in spec.md

Validation script: validation/completeness.md

1.2 Architecture & Conventions Check

•
Clean Architecture principles documented
- • Domain layer has no external dependencies
- • Application layer only depends on domain
- • Infrastructure implements application ports/interfaces
• TypeSpec contracts defined for new domain entities
• TDD phases explicitly outlined (RED-GREEN-REFACTOR cycles)
• Test coverage targets specified
• Repository pattern used for data access (if applicable)
• Use cases follow single responsibility principle

Validation script: validation/architecture.md

1.3 Cross-Document Consistency Check

• Task count in tasks.md matches plan phases
• Acceptance criteria align with spec success criteria
• Research decisions referenced in plan
• No contradictions between spec/plan/research
• Dependencies between tasks are clear

Validation script: validation/consistency.md

1.4 Auto-Fix (if needed)

Apply ONLY safe structural fixes:

•Add missing section headers (e.g., ## Open Questions)
•Close empty checkbox lines: [ ] → [x] Resolved: <timestamp>
•Add missing tasks.md template if only plan.md exists
•Fix heading level inconsistencies

Show summary of auto-fixes and require user approval before proceeding.

1.5 Blocking Issues

If validation finds blocking issues, STOP and report:

•Open questions with content that need decisions
•Missing critical sections (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:

code

Feature {ID}: {Name}
Progress: {completed}/{total} tasks ({percentage}%)
Current: {currentTask}
Last updated: {lastUpdated}

Validate current state:

•
If currentTask is not null, verify work is complete:
- •Check files exist for previous task
- •Run tests for completed work
- •Verify build passes
•If validation passes → continue with currentTask or next task
•If validation fails → re-attempt currentTask

Auto-resume immediately (no user prompt).

Phase 3: Autonomous Task Execution

Execute tasks from tasks.md 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.md
•Parse: description, acceptance criteria, TDD phases, dependencies

3.3 Execute TDD Cycle

CRITICAL: Follow TDD discipline EXACTLY as defined in plan:

•
RED Phase:
- •Write failing tests FIRST (as specified in plan)
- •Ensure tests fail (expected behavior)
- •Commit failing tests
•
GREEN Phase:
- •Write minimal implementation to pass tests
- •Run tests until green
- •Do NOT add extra features
•
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

•Analyze error root cause
•Identify fix strategy
•Apply fix
•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:

code

❌ 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:

code

✅ 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.md:

•Respect task 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.