Implement

---
name: implement
description: 'Execute a single beads issue with full lifecycle. Triggers: "implement", "work on task", "fix bug", "start feature", "pick up next issue".'
dependencies:
  - beads     # optional - for issue tracking via bd CLI
  - standards # loads language-specific standards
---

# Implement Skill

> **Quick Ref:** Execute single issue end-to-end. Output: code changes + commit + closed issue.

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

Execute a single issue from start to finish.

**CLI dependencies:** bd (issue tracking), ao (ratchet gates). Both optional — see `skills/shared/SKILL.md` for fallback table. If bd is unavailable, use the issue description directly and track progress via TaskList instead of beads.

## Execution Steps

Given `/implement <issue-id-or-description>`:

### Step 0: Check Issue State (Resume Logic)

Before starting implementation, check if resuming:

1. **Check if issue is in_progress:**
```bash
bd show <issue-id> --json 2>/dev/null | jq -r '.status'
```

2. **If status = in_progress AND assigned to you:**
   - Look for checkpoint in issue notes: `bd show <id> --json | jq -r '.notes'`
   - Resume from last checkpoint step
   - Announce: "Resuming issue from Step N"

3. **If status = in_progress AND assigned to another agent:**
   - Report: "Issue claimed by <agent> - use `bd update <id> --assignee self --force` to override"
   - Do NOT proceed without explicit override

4. **Store checkpoints after each major step:**
```bash
bd update <issue-id> --append-notes "CHECKPOINT: Step N completed at $(date -Iseconds)" 2>/dev/null
```

### Step 0a: Check Ratchet Status (RPI Workflow)

**Before implementation, verify prior workflow gates passed:**

```bash
# Check if ao CLI is available
if command -v ao &>/dev/null; then
  # Check if research and plan phases completed
  RATCHET_STATUS=$(ao ratchet status --json 2>/dev/null || echo '{}')
  RESEARCH_DONE=$(echo "$RATCHET_STATUS" | jq -r '.research.completed // false')
  PLAN_DONE=$(echo "$RATCHET_STATUS" | jq -r '.plan.completed // false')

  if [ "$RESEARCH_DONE" = "true" ] && [ "$PLAN_DONE" = "true" ]; then
    echo "Ratchet: Prior gates passed (research + plan complete)"
  elif [ "$RESEARCH_DONE" = "false" ] || [ "$PLAN_DONE" = "false" ]; then
    echo "WARNING: Prior gates not complete. Run /research and /plan first."
    echo "  Research: $RESEARCH_DONE"
    echo "  Plan: $PLAN_DONE"
    echo ""
    echo "Override with: ao ratchet skip <gate> --reason 'manual override'"
  fi

  # Get current spec path for reference
  SPEC_PATH=$(ao ratchet spec 2>/dev/null || echo "")
  if [ -n "$SPEC_PATH" ]; then
    echo "Ratchet: Current spec at $SPEC_PATH"
  fi
else
  echo "Ratchet: ao CLI not available - skipping gate check"
fi
```

**Fallback:** If ao is not available, proceed without ratchet checks. The skill continues normally.

### Step 1: Get Issue Details

**If beads issue ID provided** (e.g., `gt-123`):
```bash
bd show <issue-id> 2>/dev/null
```

**If plain description provided:** Use that as the task description.

**If no argument:** Check for ready work:
```bash
bd ready 2>/dev/null | head -3
```

### Step 2: Claim the Issue

```bash
bd update <issue-id> --status in_progress 2>/dev/null
```

### Step 3: Gather Context

**USE THE TASK TOOL** to explore relevant code:

```
Tool: Task
Parameters:
  subagent_type: "Explore"
  description: "Gather context for: <issue title>"
  prompt: |
    Find code relevant to: <issue description>

    1. Search for related files (Glob)
    2. Search for relevant keywords (Grep)
    3. Read key files to understand current implementation
    4. Identify where changes need to be made

    Return:
    - Files to modify (paths)
    - Current implementation summary
    - Suggested approach
    - Any risks or concerns
```

### Step 4: Implement the Change

Based on the context gathered:

1. **Edit existing files** using the Edit tool (preferred)
2. **Write new files** only if necessary using the Write tool
3. **Follow existing patterns** in the codebase
4. **Keep changes minimal** - don't over-engineer

### Step 5: Verify the Change

**Success Criteria (all must pass):**
- [ ] All existing tests pass (no new failures introduced)
- [ ] New code compiles/parses without errors
- [ ] No new linter warnings (if linter available)
- [ ] Change achieves the stated goal

Check for test files and run them:
```bash
# Find tests
ls *test* tests/ test/ __tests__/ 2>/dev/null | head -5

# Run tests (adapt to project type)
# Python: pytest
# Go: go test ./...
# Node: npm test
# Rust: cargo test
```

**If tests exist:** All tests must pass. Any failure = verification failed.

**If no tests exist:** Manual verification required:
- [ ] Syntax check passes (file compiles/parses)
- [ ] Imports resolve correctly
- [ ] Can reproduce expected behavior manually
- [ ] Edge cases identified during implementation are handled

**If verification fails:** Do NOT proceed to Step 5a. Fix the issue first.

### Step 5a: Verification Gate (MANDATORY)

**THE IRON LAW:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Before reporting success, you MUST:

1. **IDENTIFY** - What command proves this claim works?
2. **RUN** - Execute the FULL command (fresh, not cached output)
3. **READ** - Check full output AND exit code
4. **VERIFY** - Does output actually confirm the claim?
5. **ONLY THEN** - Make the completion claim

**Forbidden phrases without fresh verification evidence:**
- "should work", "probably fixed", "seems to be working"
- "Great!", "Perfect!", "Done!" (without output proof)
- "I just ran it" (must run it AGAIN, fresh)

#### Rationalization Table

| Excuse | Reality |
|--------|---------|
| "Too simple to verify" | Simple code breaks. Verification takes 10 seconds. |
| "I just ran it" | Run it AGAIN. Fresh output only. |
| "Tests passed earlier" | Run them NOW. State changes. |
| "It's obvious it works" | Nothing is obvious. Evidence or silence. |
| "The edit looks correct" | Looking != working. Run the code. |

**Store checkpoint:**
```bash
bd update <issue-id> --append-notes "CHECKPOINT: Step 5a verification passed at $(date -Iseconds)" 2>/dev/null
```

### Step 6: Commit the Change

If the change is complete and verified:
```bash
git add <modified-files>
git commit -m "<descriptive message>

Implements: <issue-id>"
```

### Step 7: Close the Issue

```bash
bd update <issue-id> --status closed 2>/dev/null
```

### Step 7a: Record Implementation in Ratchet Chain

**After successful issue closure, record in ratchet:**

```bash
# Check if ao CLI is available
if command -v ao &>/dev/null; then
  # Get the commit hash as output artifact
  COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "")
  CHANGED_FILES=$(git diff --name-only HEAD~1 2>/dev/null | tr '\n' ',' | sed 's/,$//')

  if [ -n "$COMMIT_HASH" ]; then
    # Record successful implementation
    ao ratchet record implement \
      --output "$COMMIT_HASH" \
      --files "$CHANGED_FILES" \
      --issue "<issue-id>" \
      2>&1 | tee -a .agents/ratchet.log

    if [ $? -eq 0 ]; then
      echo "Ratchet: Implementation recorded (commit: ${COMMIT_HASH:0:8})"
    else
      echo "Ratchet: Failed to record - chain.jsonl may need repair"
    fi
  else
    echo "Ratchet: No commit found - skipping record"
  fi
else
  echo "Ratchet: ao CLI not available - implementation NOT recorded"
  echo "  Run manually: ao ratchet record implement --output <commit>"
fi
```

**On failure/blocker:** Record the blocker in ratchet:

```bash
if command -v ao &>/dev/null; then
  ao ratchet record implement \
    --status blocked \
    --reason "<blocker description>" \
    2>/dev/null
fi
```

**Fallback:** If ao is not available, the issue is still closed via bd but won't be tracked in the ratchet chain. The skill continues normally.

### Step 8: Report to User

Tell the user:
1. What was changed (files modified)
2. How it was verified (with actual command output)
3. Issue status (closed)
4. Any follow-up needed
5. **Ratchet status** (implementation recorded or skipped)

**Output completion marker:**
```
<promise>DONE</promise>
```

If blocked or incomplete:
```
<promise>BLOCKED</promise>
Reason: <why blocked>
```

```
<promise>PARTIAL</promise>
Remaining: <what's left>
```

## Key Rules

- **Explore first** - understand before changing
- **Edit, don't rewrite** - prefer Edit tool over Write tool
- **Follow patterns** - match existing code style
- **Verify changes** - run tests or sanity checks
- **Commit with context** - reference the issue ID
- **Close the issue** - update status when done

## Without Beads

If bd CLI not available:
1. Skip the claim/close status updates
2. Use the description as the task
3. Still commit with descriptive message
4. Report completion to user

---

## Distributed Mode: Agent Mail Coordination

> **When:** Agent Mail MCP tools are available (distributed mode or multi-agent coordination)

Distributed mode enhances /implement with real-time coordination via MCP Agent Mail. This enables:
- Progress reporting to orchestrators (Mayor/Delphi)
- Help requests instead of blocking on user input
- Receiving guidance mid-execution
- Coordination with parallel workers (file reservations)

### Mode Detection

Detect the operational mode at skill start:

```bash
# Check for Agent Mail availability
AGENT_MAIL_AVAILABLE=false

# Method 1: Check if running inside a distributed worker context
if [ -n "$OLYMPUS_DEMIGOD_ID" ]; then
    AGENT_MAIL_AVAILABLE=true
fi

# Method 2: Check for explicit flag
# /implement <issue-id> --mode=distributed --thread-id <id>
# /implement <issue-id> --agent-mail --thread-id <id>  # Back-compat alias
```

**Mode Semantics:**
| Mode | Condition | Behavior |
|------|-----------|----------|
| `local` | No Agent Mail | Current behavior (all steps above) |
| `distributed` | Agent Mail available | Enhanced coordination (steps below) |

### Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--mode=local` | Force local mode | Default |
| `--mode=distributed` | Enable Agent Mail coordination | - |
| `--agent-mail` | Enable Agent Mail coordination (back-compat alias) | `false` |
| `--thread-id` | Thread ID for message grouping (usually bead-id) | `<issue-id>` |
| `--demigod-id` | Agent identity for message sender | `demigod-<issue-id>` |
| `--orchestrator` | Who to send status messages to | `<orchestrator-agent-name>` |

### Distributed Mode Execution Steps

When `--mode=distributed` (or `--agent-mail`) is enabled OR `$OLYMPUS_DEMIGOD_ID` is set:

#### Step 0: Initialize Agent Mail Session

```bash
# If not already registered (Demigod handles this), register self
# This is typically done by a worker wrapper (e.g., tmux session), but implement can work standalone
if [ -z "$OLYMPUS_DEMIGOD_ID" ]; then
    # Standalone distributed mode - need to register
    DEMIGOD_ID="${DEMIGOD_ID:-demigod-$(date +%s)}"
else
    DEMIGOD_ID="$OLYMPUS_DEMIGOD_ID"
fi
```

**MCP Tool Call (if standalone):**
```
Tool: mcp__mcp-agent-mail__register_agent
Parameters:
  project_key: "<project-key>"
  program: "implement-skill"
  model: "<model>"
  task_description: "Implementing <issue-id>"
```

#### Step 1: Send ACCEPTED Message

After claiming the issue (Step 2 in base flow), notify the orchestrator:

**MCP Tool Call:**
```
Tool: mcp__mcp-agent-mail__send_message
Parameters:
  project_key: "<project-key>"
  sender_name: "<demigod-id>"
  to: "<orchestrator>"
  subject: "BEAD_ACCEPTED"
  body_md: |
    Accepted bead: <issue-id>
    Title: <issue-title>
    Starting implementation at: <timestamp>
  thread_id: "<issue-id>"
  ack_required: false
```

#### Step 2: Check Inbox Before Major Steps

Before Steps 3, 4, 5 in base flow, check for incoming messages:

**MCP Tool Call:**
```
Tool: mcp__mcp-agent-mail__fetch_inbox
Parameters:
  project_key: "olympus"
  agent_name: "<demigod-id>"
```

**Handle incoming messages:**
| Message Type | Action |
|--------------|--------|
| `GUIDANCE` | Incorporate guidance into approach |
| `NUDGE` | Respond with progress update |
| `TERMINATE` | Exit gracefully (checkpoint work) |

#### Step 3: Send PROGRESS Messages Periodically

After each major step, send progress update:

**Timing:**
- After context gathering (Step 3)
- During implementation (Step 4) - every ~5 minutes of work
- After verification (Step 5)

**MCP Tool Call:**
```
Tool: mcp__mcp-agent-mail__send_message
Parameters:
  project_key: "olympus"
  sender_name: "<demigod-id>"
  to: "<orchestrator>"
  subject: "PROGRESS"
  body_md: |
    Bead: <issue-id>
    Step: <current-step>
    Status: <what's happening>
    Context usage: <approximate %>
    Files touched: <list>
  thread_id: "<issue-id>"
  ack_required: false
```

#### Step 4: Send HELP_REQUEST When Stuck

**Replace user prompts with Agent Mail help requests:**

Instead of:
```
"I'm stuck on X. Should I proceed with Y or Z?"
```

Do this:
```
Tool: mcp__mcp-agent-mail__send_message
Parameters:
  project_key: "olympus"
  sender_name: "<demigod-id>"
  to: "chiron@olympus"  # Help goes to Chiron (coach)
  subject: "HELP_REQUEST"
  body_md: |
    Bead: <issue-id>
    Issue Type: STUCK | SPEC_UNCLEAR | BLOCKED | TECHNICAL

    ## Problem
    <describe the issue>

    ## What I Tried
    <approaches attempted>

    ## Files Touched
    - path/to/file.py
    - path/to/other.py

    ## Question
    <specific question needing answer>
  thread_id: "<issue-id>"
  ack_required: true
```

**Then wait for HELP_RESPONSE:**
```
# Poll inbox for response (max 2 minutes per help-response timeout)
for i in {1..24}; do
    # Check inbox
    # If HELP_RESPONSE found, continue with guidance
    # If timeout exceeded, proceed with best judgment or fail gracefully
    sleep 5
done
```

#### Step 5: Report Completion via Agent Mail

After Step 7 (closing the issue), send completion message:

**On Success:**
```
Tool: mcp__mcp-agent-mail__send_message
Parameters:
  project_key: "olympus"
  sender_name: "<demigod-id>"
  to: "<orchestrator>"
  subject: "OFFERING_READY"
  body_md: |
    Bead: <issue-id>
    Status: DONE

    ## Changes
    - Commit: <commit-sha>
    - Files: <changed-files>

    ## Self-Validation
    - Tests: PASS/FAIL
    - Lint: PASS/FAIL
    - Build: PASS/FAIL

    ## Summary
    <brief description of what was implemented>
  thread_id: "<issue-id>"
  ack_required: true
```

**On Failure:**
```
Tool: mcp__mcp-agent-mail__send_message
Parameters:
  project_key: "olympus"
  sender_name: "<demigod-id>"
  to: "<orchestrator>"
  subject: "FAILED"
  body_md: |
    Bead: <issue-id>
    Status: FAILED

    ## Failure
    Type: TESTS_FAIL | BUILD_FAIL | SPEC_IMPOSSIBLE | ERROR
    Reason: <description>
    Internal Attempts: <count>

    ## Partial Progress
    - Commit: <partial-commit-sha if any>
    - Files: <files-modified>

    ## Recommendation
    <what needs to happen to unblock>
  thread_id: "<issue-id>"
  ack_required: false
```

### Distributed Mode File Reservations

When running in distributed mode with parallel workers, claim files before editing:

**Before Step 4 (implementation):**
```
Tool: mcp__mcp-agent-mail__file_reservation_paths
Parameters:
  project_key: "olympus"
  agent_name: "<demigod-id>"
  paths:
    - "path/to/file1.py"
    - "path/to/file2.py"
  exclusive: false  # Advisory, not blocking
```

**After Step 7 (completion):**
```
Tool: mcp__mcp-agent-mail__release_file_reservations
Parameters:
  project_key: "olympus"
  agent_name: "<demigod-id>"
```

### Distributed Mode Context Checkpoint

If context usage is high (>80%), send checkpoint before exiting:

```
Tool: mcp__mcp-agent-mail__send_message
Parameters:
  project_key: "olympus"
  sender_name: "<demigod-id>"
  to: "<orchestrator>"
  subject: "CHECKPOINT"
  body_md: |
    Bead: <issue-id>
    Reason: CONTEXT_HIGH

    ## Progress
    - Commit: <partial-commit-sha>
    - Description: <what's done, what remains>
    - Context usage: <pct>%

    ## Next Steps for Successor
    <guidance for replacement demigod>
  thread_id: "<issue-id>"
  ack_required: false
```

### Distributed Mode Key Rules

- **Always check inbox** - Messages may contain critical guidance
- **Send progress regularly** - Orchestrator needs visibility
- **Use HELP_REQUEST** - Don't block on user, ask Chiron
- **Reserve files** - Prevents conflicts with parallel workers
- **Checkpoint on context high** - Preserve progress for successor
- **Acknowledge important messages** - Confirms receipt to sender

### Distributed vs Local Mode Summary

| Behavior | Local | Distributed |
|----------|---------|---------|
| Progress reporting | None | PROGRESS messages |
| When stuck | Ask user / proceed | HELP_REQUEST to Chiron |
| Completion | bd update only | OFFERING_READY + bd update |
| Failure | Report to user | FAILED message + report |
| File conflicts | Race conditions | Advisory reservations |
| Guidance | None | Check inbox for GUIDANCE |

### Integration with Distributed Workers

When `/implement` is run inside a distributed worker (e.g., a tmux session):
1. Environment variables may already be set (`$OLYMPUS_DEMIGOD_ID`, etc.)
2. Agent registration already done
3. File reservations already claimed
4. Just focus on implementation + progress + completion messages

When /implement is called standalone with `--agent-mail`:
1. Must register self
2. Must claim own files
3. Full distributed mode behavior

---

## References

- **Agent Mail Protocol:** See `skills/shared/agent-mail-protocol.md` for message format specifications
- **Parser (Go):** `cli/internal/agentmail/` - shared parser for all message types