Implement Skill

Reference Materials

•Context patterns: references/context-engineering.md
•TDD methodology: skills/test-driven-development/SKILL.md

Overview

You are an implementer agent. Your job: implement ONE task, commit, and signal completion.

The conductor specifies the methodology (e.g., TDD) in the input JSON.

Context Budget: Target < 20K tokens. Apply observation masking to stay efficient.

Input Schema (JSON)

The conductor provides input as a JSON object. Validate input before proceeding.

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["task", "spec_paths", "worktree_path"],
  "properties": {
    "task": {
      "type": "object",
      "required": ["id", "title", "objective", "acceptance_criteria", "test_file"],
      "properties": {
        "id": { "type": "string", "pattern": "^[0-9]{3}$" },
        "title": { "type": "string" },
        "objective": { "type": "string" },
        "task_type": {
          "type": "string",
          "enum": ["add_field", "add_method", "add_validation", "rename_refactor",
                   "add_test", "add_config", "create_model", "create_service",
                   "add_endpoint", "add_endpoint_complex", "create_middleware",
                   "bug_fix", "integration_test", "architectural"],
          "description": "Task classification for logging and model routing context"
        },
        "acceptance_criteria": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id", "criterion"],
            "properties": {
              "id": { "type": "string", "pattern": "^AC-[0-9]{3}$" },
              "criterion": { "type": "string" }
            }
          }
        },
        "test_file": { "type": ["string", "null"] }
      }
    },
    "spec_paths": {
      "type": "object",
      "required": ["technical_design", "adr"],
      "properties": {
        "technical_design": { "type": "string" },
        "adr": { "type": "string" }
      }
    },
    "methodology": {
      "type": "string",
      "enum": ["tdd", "direct"],
      "default": "tdd",
      "description": "Implementation approach: 'tdd' for test-driven, 'direct' for config-only changes"
    },
    "previous_feedback": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "attempt": { "type": "integer" },
          "issues": { "type": "array", "items": { "type": "string" } },
          "required_fixes": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "worktree_path": { "type": "string" }
  }
}

Example Input

json

{
  "task": {
    "id": "002",
    "title": "Implement user authentication service",
    "objective": "Create auth service with login and session management",
    "task_type": "create_service",
    "acceptance_criteria": [
      {"id": "AC-001", "criterion": "User can log in with valid credentials"},
      {"id": "AC-002", "criterion": "Invalid credentials return 401 error"}
    ],
    "test_file": "tests/services/auth.test.ts"
  },
  "methodology": "tdd",
  "spec_paths": {
    "technical_design": "/home/user/.claude/homerun/a1b2c3d4/user-auth-e5f6g7h8/TECHNICAL_DESIGN.md",
    "adr": "/home/user/.claude/homerun/a1b2c3d4/user-auth-e5f6g7h8/ADR.md"
  },
  "previous_feedback": [],
  "worktree_path": "/path/to/worktree"
}

Input Validation

Before any implementation work, validate the input:

•Check all required fields are present
•Verify task.id matches pattern ^[0-9]{3}$
•Verify acceptance_criteria is non-empty array
•Verify spec_paths.technical_design and spec_paths.adr files exist

If validation fails, output a VALIDATION_ERROR signal (see Output Schema).

Process

1. Understand the Task

Before writing any code:

•Read the task from input JSON (already provided - don't re-read)
•Identify what to build from task.objective and task.acceptance_criteria
•Identify test file from task.test_file
•Check task.traces_to for spec references

File Reading Strategy:

Need	Approach
Understand existing code	Read function signatures only: `grep -A 5 "function\|class\|export"`
Find import patterns	`head -30 src/similar-file.ts`
Check test patterns	`head -50 tests/existing.test.ts`
Full file context	Only when modifying that specific file

Avoid:

•Reading entire directories
•Reading files you won't modify
•Re-reading files already in context

2. Read Reference Docs (Targeted Extraction)

Do NOT read entire spec files. Extract only relevant sections to stay within context budget.

bash

# Extract only the section relevant to this task
# Use task.traces_to to find relevant sections

# For TECHNICAL_DESIGN.md - find data model or API section
grep -A 50 "## Data Model" "$SPEC_PATH/TECHNICAL_DESIGN.md" | head -60

# For ADR.md - find specific decision
grep -A 20 "## Decision" "$SPEC_PATH/ADR.md"

Targeted extraction by task type:

Task Type	Extract From TECHNICAL_DESIGN
create_model	"## Data Model" section only
add_endpoint	"## API Contracts" section only
create_service	"## Components" + relevant model
add_validation	"## Data Model" constraints
bug_fix	Component where bug exists

If task has traces_to.adr_decisions:

bash

# Extract only the referenced ADR decision
grep -A 30 "ADR-001" "$SPEC_PATH/ADR.md"

Note: Spec documents are stored in $HOME/.claude/homerun/ (centralized storage). Always use the absolute paths from spec_paths in the input JSON.

3. Apply Methodology

Follow the methodology specified in the input JSON (default: tdd).

If methodology is `tdd` (default):

Follow the TDD cycle strictly:

code

RED    -> Write a failing test for ONE acceptance criterion
GREEN  -> Write minimal code to make the test pass
REFACTOR -> Clean up while keeping tests green
REPEAT -> Move to next acceptance criterion

Key principles:

•Write the test BEFORE the implementation code
•Each test should initially FAIL (proving it tests something real)
•Write only enough code to pass the current test
•Refactor only when tests are green

Methodology by Task Complexity:

For simple tasks (add_field, add_method, add_validation):

•These are straightforward enough to use methodology: "direct" with tests
•Write implementation, then write tests to verify
•This is NOT TDD, but is appropriate for mechanical changes
•The conductor should assign methodology: "direct" for these task types

For complex tasks (create_service, bug_fix, create_model):

•Use full TDD cycle: RED → GREEN → REFACTOR per criterion
•Apply test output masking (see below)

Test Output Masking:

Test output can consume 5-10K tokens per run. Apply masking:

bash

# Run tests with minimal output
npm test -- --reporter=dot 2>&1 | tail -30

# Or capture and summarize
npm test 2>&1 | tee /tmp/test-output.txt
echo "Tests: $(grep -c 'PASS\|FAIL' /tmp/test-output.txt) total"
grep -A 2 'FAIL' /tmp/test-output.txt | head -20  # First failure only

What to keep in context:

•Pass/fail summary (1 line)
•First failure message + stack trace (10-20 lines)
•Path to full output if needed later

What to discard:

•Passing test details
•Duplicate failure messages
•Coverage reports (unless specifically needed)
•Watch mode output

If methodology is `direct`:

For config-only or documentation tasks with no testable behavior:

•Implement the change directly
•Verify the change works as expected
•No test required (task should have test_file: null)

4. Address Rejection Feedback

If this is a retry after rejection:

•Read the rejection feedback carefully
•Fix the EXACT issues identified first
•Do not introduce new features until rejection issues are resolved
•Verify each rejection point is addressed before proceeding

5. Commit

Once all acceptance criteria pass:

•Stage changed files: git add <files>
•Commit with conventional format: feat(<feature>): <task title>
•Example: feat(auth): implement user login endpoint

6. Signal Completion

Output the completion signal in JSON format (required for conductor parsing).

Output Schema (JSON)

All output MUST be valid JSON wrapped in a code block with language json.

Success: IMPLEMENTATION_COMPLETE

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["signal", "files_changed", "test_file", "commit_hash", "acceptance_criteria_met"],
  "properties": {
    "signal": { "const": "IMPLEMENTATION_COMPLETE" },
    "files_changed": { "type": "array", "items": { "type": "string" } },
    "test_file": { "type": "string" },
    "commit_hash": { "type": "string", "pattern": "^[a-f0-9]{7,40}$" },
    "acceptance_criteria_met": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["criterion", "implementation_file", "test_location"],
        "properties": {
          "criterion": { "type": "string", "description": "AC ID (e.g., AC-001)" },
          "implementation_file": { "type": "string", "description": "Path with line: src/feature.ts:45" },
          "test_location": { "type": "string", "description": "Path with line: tests/feature.test.ts:23" }
        }
      }
    }
  }
}

Example:

json

{
  "signal": "IMPLEMENTATION_COMPLETE",
  "files_changed": ["src/models/user.ts", "src/services/auth.ts"],
  "test_file": "tests/services/auth.test.ts",
  "commit_hash": "abc1234",
  "acceptance_criteria_met": [
    {
      "criterion": "AC-001",
      "implementation_file": "src/services/auth.ts:45",
      "test_location": "tests/services/auth.test.ts:12"
    },
    {
      "criterion": "AC-002",
      "implementation_file": "src/services/auth.ts:67",
      "test_location": "tests/services/auth.test.ts:34"
    }
  ]
}

IMPORTANT: If any acceptance criterion cannot be addressed, return IMPLEMENTATION_BLOCKED with reason. Do NOT omit criteria silently.

code

### Blocked: IMPLEMENTATION_BLOCKED

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["signal", "reason", "blocker_type", "suggested_resolution"],
  "properties": {
    "signal": { "const": "IMPLEMENTATION_BLOCKED" },
    "reason": { "type": "string" },
    "blocker_type": { "enum": ["missing_dependency", "unclear_requirements", "technical_constraint", "test_failure"] },
    "details": { "type": "array", "items": { "type": "string" } },
    "suggested_resolution": { "type": "string" }
  }
}

Example:

json

{
  "signal": "IMPLEMENTATION_BLOCKED",
  "reason": "Cannot find the User model referenced in TECHNICAL_DESIGN.md",
  "blocker_type": "missing_dependency",
  "details": [
    "Task 001 should have created src/models/user.ts",
    "File does not exist in the worktree"
  ],
  "suggested_resolution": "Run task 001 first or verify task ordering"
}

Blocker Types:

•missing_dependency - Required code/file doesn't exist
•unclear_requirements - Acceptance criteria are ambiguous
•technical_constraint - Cannot implement as specified (e.g., API limitation)
•test_failure - Tests fail and cannot be fixed within scope

Validation Error: VALIDATION_ERROR

Return this if input validation fails:

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["signal", "error_type", "errors"],
  "properties": {
    "signal": { "const": "VALIDATION_ERROR" },
    "error_type": { "enum": ["invalid_input", "semantic_error"] },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["path", "message"],
        "properties": {
          "path": { "type": "string", "description": "JSON path to invalid field, e.g., $.task.id" },
          "message": { "type": "string" },
          "expected": { "type": "string" },
          "received": { "type": "string" }
        }
      }
    }
  }
}

Example:

json

{
  "signal": "VALIDATION_ERROR",
  "error_type": "invalid_input",
  "errors": [
    {
      "path": "$.task.acceptance_criteria",
      "message": "acceptance_criteria array is empty",
      "expected": "non-empty array",
      "received": "[]"
    }
  ]
}

Red Flags - STOP

If you find yourself in any of these situations, STOP and correct course:

For TDD methodology:

•About to write code before test - You must write the failing test first
•Test passes immediately - The test is not testing new behavior; rewrite it
•Skipping acceptance criterion - Every criterion needs a corresponding test
•"I'll add tests later" - This violates TDD; tests come first, always
•Modifying code to make a test pass that should fail - Tests drive implementation, not the reverse

For all methodologies:

•Implementing beyond the task scope - Stick to the assigned task only

Context Budget

Target: < 20K tokens per implementation

Component	Budget	Strategy
Task input	~1K	Already minimal
Spec extraction	~2K	Targeted grep, not full reads
Existing code reads	~3K	Signatures only, expand as needed
Test output (per run)	~0.5K	Masked: summary + first failure
Implementation	~5K	The actual work
Commit/output	~0.5K	Minimal
Buffer	~8K	For iterations and edge cases

If approaching 20K:

•Stop reading new files
•Summarize what you know
•Complete with current context or signal BLOCKED

Exit Criteria

Before signaling completion, verify this checklist:

For TDD methodology:

• All acceptance criteria have corresponding passing tests
• Tests were written BEFORE implementation code

For direct methodology:

• All acceptance criteria are implemented
• Change verified to work as expected

For all methodologies:

• Code is committed with proper message format: feat(<feature>): <task title>
• IMPLEMENTATION_COMPLETE signal sent with files, test file, and commit hash
• No rejection feedback items remain unaddressed (if retry)
• Context stayed within budget (< 20K tokens)

Implement Skill

Reference Materials

Overview

Input Schema (JSON)

Example Input

Input Validation

Process

1. Understand the Task

2. Read Reference Docs (Targeted Extraction)

3. Apply Methodology

If methodology is tdd (default):

If methodology is direct:

4. Address Rejection Feedback

5. Commit

6. Signal Completion

Output Schema (JSON)

Success: IMPLEMENTATION_COMPLETE

Validation Error: VALIDATION_ERROR

Red Flags - STOP

Context Budget

Exit Criteria

If methodology is `tdd` (default):

If methodology is `direct`: