---

name: skill-implementer description: Execute general implementation tasks following a plan. Invoke for non-Lean implementation work. allowed-tools: Task, Bash, Edit, Read, Write

Original context (now loaded by subagent):

- .claude/context/core/formats/summary-format.md

- .claude/context/core/standards/code-patterns.md

Original tools (now used by subagent):

- Read, Write, Edit, Glob, Grep, Bash

---

Implementer Skill

Thin wrapper that delegates general implementation to general-implementation-agent subagent.

IMPORTANT: This skill implements the skill-internal postflight pattern. After the subagent returns, this skill handles all postflight operations (status update, artifact linking, git commit) before returning. This eliminates the "continue" prompt issue between skill return and orchestrator.

Context References

Reference (do not load eagerly):

• Path: .claude/context/core/formats/return-metadata-file.md - Metadata file schema
• Path: .claude/context/core/patterns/postflight-control.md - Marker file protocol
• Path: .claude/context/core/patterns/file-metadata-exchange.md - File I/O helpers
• Path: .claude/context/core/patterns/jq-escaping-workarounds.md - jq escaping patterns (Issue #1132)

Note: This skill is a thin wrapper with internal postflight. Context is loaded by the delegated agent.

Trigger Conditions

This skill activates when:

• Task language is "general", "meta", or "markdown"
• /implement command is invoked
• Plan exists and task is ready for implementation

---

Execution Flow

Stage 1: Input Validation

Validate required inputs:

• task_number - Must be provided and exist in state.json
• Task status must allow implementation (planned, implementing, partial)

# Lookup task
task_data=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num)' \
  specs/state.json)

# Validate exists
if [ -z "$task_data" ]; then
  return error "Task $task_number not found"
fi

# Extract fields
language=$(echo "$task_data" | jq -r '.language // "general"')
status=$(echo "$task_data" | jq -r '.status')
project_name=$(echo "$task_data" | jq -r '.project_name')
description=$(echo "$task_data" | jq -r '.description // ""')

# Validate status
if [ "$status" = "completed" ]; then
  return error "Task already completed"
fi

---

Stage 2: Preflight Status Update

Update task status to "implementing" BEFORE invoking subagent.

Update state.json:

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg status "implementing" \
   --arg sid "$session_id" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    status: $status,
    last_updated: $ts,
    session_id: $sid,
    started: $ts
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

Update TODO.md: Use Edit tool to change status marker from [PLANNED] to [IMPLEMENTING].

Update plan file (if exists): Use centralized helper to update the Status field:

# Call centralized helper script
.claude/scripts/update-plan-status.sh "$task_number" "$project_name" "IMPLEMENTING"

---

Stage 3: Create Postflight Marker

Create the marker file to prevent premature termination:

# Ensure task directory exists
mkdir -p "specs/${task_number}_${project_name}"

cat > "specs/${task_number}_${project_name}/.postflight-pending" << EOF
{
  "session_id": "${session_id}",
  "skill": "skill-implementer",
  "task_number": ${task_number},
  "operation": "implement",
  "reason": "Postflight pending: status update, artifact linking, git commit",
  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "stop_hook_active": false
}
EOF

---

Stage 4: Prepare Delegation Context

Prepare delegation context for the subagent:

{
  "session_id": "sess_{timestamp}_{random}",
  "delegation_depth": 1,
  "delegation_path": ["orchestrator", "implement", "skill-implementer"],
  "timeout": 7200,
  "task_context": {
    "task_number": N,
    "task_name": "{project_name}",
    "description": "{description}",
    "language": "{language}"
  },
  "plan_path": "specs/{NNN}_{SLUG}/plans/implementation-{NNN}.md",
  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json",
  "iteration": 1,
  "resume_phase": null,
  "handoff_path": null
}

Iteration Fields (used by Stage 6a auto-resume loop):

• iteration: Current loop iteration (1 for initial invocation, incremented on re-invocations)
• resume_phase: Phase number to resume from (null for initial, set from partial_progress.phases_completed + 1 on re-invocation)
• handoff_path: Path to handoff document for context exhaustion cases (null unless agent wrote handoff)

---

Stage 5: Invoke Subagent

CRITICAL: You MUST use the Task tool to spawn the subagent.

Required Tool Invocation:

Tool: Task (NOT Skill)
Parameters:
  - subagent_type: "general-implementation-agent"
  - prompt: [Include task_context, delegation_context, plan_path, metadata_file_path]
  - description: "Execute implementation for task {N}"

DO NOT use Skill(general-implementation-agent) - this will FAIL.

The subagent will:

• Load implementation context files
• Parse plan and find resume point
• Execute phases sequentially
• Create/modify files as needed
• Create implementation summary
• Write metadata to specs/{NNN}_{SLUG}/.return-meta.json
• Return a brief text summary (NOT JSON)

---

Stage 5a: Validate Subagent Return Format

IMPORTANT: Check if subagent accidentally returned JSON to console (v1 pattern) instead of writing to file (v2 pattern).

If the subagent's text return parses as valid JSON, log a warning:

# Check if subagent return looks like JSON (starts with { and is valid JSON)
subagent_return="$SUBAGENT_TEXT_RETURN"
if echo "$subagent_return" | grep -q '^{' && echo "$subagent_return" | jq empty 2>/dev/null; then
    echo "WARNING: Subagent returned JSON to console instead of writing metadata file."
    echo "This indicates the agent may have outdated instructions (v1 pattern instead of v2)."
    echo "The skill will continue by reading the metadata file, but this should be fixed."
fi

This validation:

• Does NOT fail the operation (continues to read metadata file)
• Logs a warning for debugging
• Indicates the subagent instructions need updating
• Allows graceful handling of mixed v1/v2 agents

---

Stage 6: Parse Subagent Return (Read Metadata File)

After subagent returns, read the metadata file:

metadata_file="specs/${task_number}_${project_name}/.return-meta.json"

if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then
    status=$(jq -r '.status' "$metadata_file")
    artifact_path=$(jq -r '.artifacts[0].path // ""' "$metadata_file")
    artifact_type=$(jq -r '.artifacts[0].type // ""' "$metadata_file")
    artifact_summary=$(jq -r '.artifacts[0].summary // ""' "$metadata_file")
    phases_completed=$(jq -r '.metadata.phases_completed // 0' "$metadata_file")
    phases_total=$(jq -r '.metadata.phases_total // 0' "$metadata_file")

    # Extract completion_data fields (if present)
    completion_summary=$(jq -r '.completion_data.completion_summary // ""' "$metadata_file")
    claudemd_suggestions=$(jq -r '.completion_data.claudemd_suggestions // ""' "$metadata_file")
    roadmap_items=$(jq -c '.completion_data.roadmap_items // []' "$metadata_file")
else
    echo "Error: Invalid or missing metadata file"
    status="failed"
fi

---

Stage 6a: Continuous Handoff Loop

If status is "partial" and requires_user_review is not true, automatically re-invoke the subagent with updated context. This enables multi-phase implementations to complete without manual intervention for recoverable partials.

Loop Guard File: Create .postflight-loop-guard to track iteration count across potential skill restarts:

# Create or read loop guard
loop_guard_file="specs/${task_number}_${project_name}/.postflight-loop-guard"
if [ -f "$loop_guard_file" ]; then
    iteration_count=$(cat "$loop_guard_file")
else
    iteration_count=0
fi
max_iterations=${MAX_ITERATIONS:-5}

# Enter loop (loop body starts here, checked each iteration)
while true; do
    iteration_count=$((iteration_count + 1))
    echo "$iteration_count" > "$loop_guard_file"

    # Already have status from Stage 6
    requires_review=$(jq -r '.requires_user_review // false' "$metadata_file")
    handoff_path=$(jq -r '.partial_progress.handoff_path // ""' "$metadata_file")

    # Stop condition: implemented (success)
    if [ "$status" == "implemented" ]; then
        break
    fi

    # Stop condition: hard failure
    if [ "$status" == "blocked" ] || [ "$status" == "failed" ]; then
        break
    fi

    # Stop condition: partial but requires user review
    if [ "$status" == "partial" ] && [ "$requires_review" == "true" ]; then
        echo "Partial completion requires user review - exiting loop"
        break
    fi

    # Stop condition: iteration limit reached
    if [ "$status" == "partial" ] && [ "$iteration_count" -ge "$max_iterations" ]; then
        echo "Max iterations ($max_iterations) reached - exiting loop"
        break
    fi

    # If partial and not blocked, re-invoke subagent
    if [ "$status" == "partial" ]; then
        echo "Iteration $iteration_count: Partial completion, auto-resuming..."

        # Commit iteration progress before re-invocation
        git add \
          "specs/${task_number}_${project_name}/summaries/" \
          "specs/${task_number}_${project_name}/plans/" \
          "specs/${task_number}_${project_name}/.return-meta.json"
        git commit -m "task ${task_number}: iteration ${iteration_count} partial progress

Session: ${session_id}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>" || true

        # Update delegation context with resume info
        resume_phase=$((phases_completed + 1))

        # Re-invoke subagent (same as Stage 5) with updated context
        # Delegation context now includes:
        #   - iteration: current loop iteration
        #   - resume_phase: phase to resume from
        #   - handoff_path: path to handoff document (if context exhaustion)

        # ... invoke Task tool with updated context ...
        # After subagent returns, re-read metadata (repeat Stage 6)

        if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then
            status=$(jq -r '.status' "$metadata_file")
            phases_completed=$(jq -r '.metadata.phases_completed // 0' "$metadata_file")
            phases_total=$(jq -r '.metadata.phases_total // 0' "$metadata_file")
            completion_summary=$(jq -r '.completion_data.completion_summary // ""' "$metadata_file")
            claudemd_suggestions=$(jq -r '.completion_data.claudemd_suggestions // ""' "$metadata_file")
            roadmap_items=$(jq -c '.completion_data.roadmap_items // []' "$metadata_file")
        else
            echo "Error: Invalid or missing metadata file after re-invocation"
            status="failed"
            break
        fi

        continue
    fi

    # Unknown status - exit loop
    break
done

Stop Conditions Summary:

Condition	Result	User Action Required
status == "implemented"	Proceed to postflight	None
status == "blocked"	Exit with blocker report	Yes - resolve blocker
status == "failed"	Exit with error	Yes - investigate failure
status == "partial" && requires_user_review == true	Exit with blocker	Yes - review required
status == "partial" && iteration >= max_iterations	Exit with limit warning	Optional - run again
status == "partial" && requires_user_review != true	Re-invoke subagent	None (automatic)

Iteration Context Passage:

Each re-invocation includes in delegation context:

• iteration: Current loop iteration number
• resume_phase: Next phase to execute (phases_completed + 1)
• handoff_path: Path to handoff document if available (for context exhaustion cases)
• session_id: Same session ID for commit continuity

---

Stage 7: Update Task Status (Postflight)

If status is "implemented":

Update state.json to "completed" and add completion_data fields:

# Step 1: Update status and timestamps
jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg status "completed" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    status: $status,
    last_updated: $ts,
    completed: $ts
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

# Step 2: Add completion_summary (always required for completed tasks)
if [ -n "$completion_summary" ]; then
    jq --arg summary "$completion_summary" \
      '(.active_projects[] | select(.project_number == '$task_number')).completion_summary = $summary' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json
fi

# Step 3: Add language-specific completion fields
# For meta tasks: add claudemd_suggestions
if [ "$language" = "meta" ] && [ -n "$claudemd_suggestions" ]; then
    jq --arg suggestions "$claudemd_suggestions" \
      '(.active_projects[] | select(.project_number == '$task_number')).claudemd_suggestions = $suggestions' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json
fi

# For non-meta tasks: add roadmap_items (if present and non-empty)
if [ "$language" != "meta" ] && [ "$roadmap_items" != "[]" ] && [ -n "$roadmap_items" ]; then
    jq --argjson items "$roadmap_items" \
      '(.active_projects[] | select(.project_number == '$task_number')).roadmap_items = $items' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json
fi

Update TODO.md: Change status marker from [IMPLEMENTING] to [COMPLETED].

Update plan file (if exists): Use centralized helper to update the Status field:

# Call centralized helper script
.claude/scripts/update-plan-status.sh "$task_number" "$project_name" "COMPLETED"

If status is "partial":

Keep status as "implementing" but update resume point:

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --argjson phase "$phases_completed" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    last_updated: $ts,
    resume_phase: ($phase + 1)
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

TODO.md stays as [IMPLEMENTING].

Update plan file (if exists): Use centralized helper to update the Status field:

# Call centralized helper script
.claude/scripts/update-plan-status.sh "$task_number" "$project_name" "PARTIAL"

On failed: Keep status as "implementing" for retry. Do not update plan file (leave as [IMPLEMENTING] for retry).

---

Stage 8: Link Artifacts

Add artifact to state.json with summary. Summary artifacts should be linked for both implemented and partial status, since incremental summaries contain Phase Entries for completed work.

IMPORTANT: Use two-step jq pattern to avoid Issue #1132 escaping bug. See jq-escaping-workarounds.md.

# Find summary artifact in metadata (regardless of status)
summary_artifact_path=$(jq -r '.artifacts[] | select(.type == "summary") | .path // ""' "$metadata_file" | head -1)
summary_artifact_summary=$(jq -r '.artifacts[] | select(.type == "summary") | .summary // ""' "$metadata_file" | head -1)

if [ -n "$summary_artifact_path" ]; then
    # Step 1: Filter out existing summary artifacts (use "| not" pattern to avoid != escaping - Issue #1132)
    jq '(.active_projects[] | select(.project_number == '$task_number')).artifacts =
        [(.active_projects[] | select(.project_number == '$task_number')).artifacts // [] | .[] | select(.type == "summary" | not)]' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

    # Step 2: Add new summary artifact
    jq --arg path "$summary_artifact_path" \
       --arg summary "$summary_artifact_summary" \
      '(.active_projects[] | select(.project_number == '$task_number')).artifacts += [{"path": $path, "type": "summary", "summary": $summary}]' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json
fi

# Also link implementation artifacts if present
if [ -n "$artifact_path" ] && [ "$artifact_type" != "summary" ]; then
    jq --arg path "$artifact_path" \
       --arg type "$artifact_type" \
       --arg summary "$artifact_summary" \
      '(.active_projects[] | select(.project_number == '$task_number')).artifacts += [{"path": $path, "type": $type, "summary": $summary}]' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json
fi

Update TODO.md (for both implemented AND partial): Add summary artifact link:

- **Summary**: [implementation-summary-{DATE}.md]({summary_artifact_path})

This enables visibility into partial progress through the summary file even when implementation is incomplete.

---

Stage 9: Git Commit

Commit changes with session ID using targeted staging (prevents race conditions with concurrent agents):

# Stage task-specific files (summaries, plans, metadata)
git add \
  "specs/${task_number}_${project_name}/summaries/" \
  "specs/${task_number}_${project_name}/plans/" \
  "specs/${task_number}_${project_name}/.return-meta.json" \
  "specs/TODO.md" \
  "specs/state.json"

# Stage implementation files based on language:
# - meta: .claude/
# - general: files specified in plan
# - markdown: docs/
git add "${implementation_files[@]}"

git commit -m "task ${task_number}: complete implementation

Session: ${session_id}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

Note: Use targeted staging, NOT git add -A. See .claude/context/core/standards/git-staging-scope.md.

---

Stage 10: Cleanup

Remove marker and metadata files:

rm -f "specs/${task_number}_${project_name}/.postflight-pending"
rm -f "specs/${task_number}_${project_name}/.postflight-loop-guard"
rm -f "specs/${task_number}_${project_name}/.return-meta.json"

---

Stage 11: Return Brief Summary

Return a brief text summary (NOT JSON). Example:

Implementation completed for task {N}:
- All {phases_total} phases executed successfully
- Key changes: {summary of changes}
- Created summary at specs/{NNN}_{SLUG}/summaries/implementation-summary-{DATE}.md
- Status updated to [COMPLETED]
- Changes committed

---

Error Handling

Input Validation Errors

Return immediately with error message if task not found or status invalid.

Metadata File Missing

If subagent didn't write metadata file:

1. Keep status as "implementing"
2. Do not cleanup postflight marker
3. Report error to user

Git Commit Failure

Non-blocking: Log failure but continue with success response.

Subagent Timeout

Return partial status if subagent times out (default 7200s). Keep status as "implementing" for resume.

---

Return Format

This skill returns a brief text summary (NOT JSON). The JSON metadata is written to the file and processed internally.

Example successful return:

Implementation completed for task 350:
- All 5 phases executed successfully
- Created new feature component with tests
- Created summary at specs/350_feature/summaries/implementation-summary-20260118.md
- Status updated to [COMPLETED]
- Changes committed with session sess_1736700000_abc123

Example partial return:

Implementation partially completed for task 350:
- Phases 1-3 of 5 executed
- Phase 4 failed: TypeScript compilation error
- Partial summary at specs/350_feature/summaries/implementation-summary-20260118.md
- Status remains [IMPLEMENTING] - run /implement 350 to resume