PHP Workx Clai Implement

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.

Requires: bd CLI (beads) for issue tracking. Falls back to plain descriptions if unavailable.

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:

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 - use bd update <id> --assignee self --force to override"
   • Do NOT proceed without explicit override

4. Store checkpoints after each major step:

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:

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

bd show <issue-id> 2>/dev/null

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

If no argument: Check for ready work:

bd ready 2>/dev/null | head -3

Step 2: Claim the Issue

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:

# 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

Store checkpoint:

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:

git add <modified-files>
git commit -m "<descriptive message>

Implements: <issue-id>"

Step 7: Close the Issue

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

Step 7a: Record Implementation in Ratchet Chain

After successful issue closure, record in ratchet:

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

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

Level 2 Mode: Agent Mail Coordination

When: Agent Mail MCP tools are available (Level 2 Olympus or multi-agent coordination)

Level 2 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)

Level Detection

Detect the operational level at skill start:

# Check for Agent Mail availability
AGENT_MAIL_AVAILABLE=false

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

# Method 2: Check for explicit flag
# /implement <issue-id> --agent-mail --thread-id <id>

Level Semantics:

New Parameters

Level 2 Execution Steps

When --agent-mail is enabled OR $OLYMPUS_DEMIGOD_ID is set:

L2 Step 0: Initialize Agent Mail Session

# If not already registered (Demigod handles this), register self
# This is typically done by /demigod, but implement can work standalone
if [ -z "$OLYMPUS_DEMIGOD_ID" ]; then
    # Standalone Level 2 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: "olympus"
  program: "implement-skill"
  model: "claude-opus-4-5-20250101"
  task_description: "Implementing <issue-id>"

L2 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: "olympus"
  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

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

L2 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

L2 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

L2 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

Level 2 File Reservations

When running in Level 2 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>"

Level 2 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

Level 2 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

Level 2 vs Level 1 Summary

Integration with /demigod

When /implement is called from /demigod skill:

1. Environment variables are pre-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 Level 2 behavior

Converted and distributed by TomeVault — claim your Tome and manage your conversions.