name: agent-implementation-skill description: Multi-model agent implementation workflow for software development. Orchestrates research, evaluation, design baseline, implementation, RCA, structured decomposition, constraint discovery, model selection, and agent-driven Stage 3 codemap exploration across external AI models (GPT, GLM, Claude). Use when implementing features through a structured multi-phase pipeline with worktrees, dynamic scheduling, and SQLite-backed agent coordination.

Development Workflow

Single entry point for the full development lifecycle. Read this file, determine what phase you're in or what the user needs, then read the relevant sub-file from this directory.

Paths

Everything lives in this skill folder. WORKFLOW_HOME is: !dirname "$(grep -rl '^name: agent-implementation-skill' ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | head -1)" 2>/dev/null

When dispatching scripts or agents, export WORKFLOW_HOME with the path above. Scripts also self-locate via dirname as a fallback when invoked directly.

$WORKFLOW_HOME/
  SKILL.md              # this file — entry point
  implement.md          # multi-model implementation pipeline
  research.md           # exploration → alignment → proposal
  rca.md                # root cause analysis
  evaluate.md           # proposal review
  baseline.md           # constraint extraction
  audit.md              # structured task decomposition
  constraints.md        # constraint discovery
  models.md             # model selection guide
  scripts/
    workflow.sh         # schedule driver ([wait]/[run]/[done]/[fail])
    db.sh               # SQLite-backed coordination database
    scan.sh             # Stage 3 coordinator: dispatches agents to explore codespace and build codemap, then per-section file identification
    section-loop.py     # strategic section-loop orchestrator: integration proposals, strategic implementation, cross-section communication, global coordination (Stages 4-5 of implement.md)
  tools/
    extract-docstring-py  # extract Python module docstrings
    extract-summary-md    # extract YAML frontmatter from markdown
    README.md             # tool interface spec (for Opus to write new tools)
  agents/
    orchestrator.md     # event-driven step dispatcher (model: claude-opus)
    monitor.md          # task-level pipeline monitor — detects cycles/stuck (model: glm)
    qa-monitor.md       # deep QA monitor — 26 rules, 5 categories, PAUSE authority (model: opus)
    agent-monitor.md    # per-agent loop detector — watches narration (model: glm)
    state-detector.md   # workspace state reporter (model: claude-opus)
    exception-handler.md # RCA on failed steps (model: claude-opus)
    microstrategy-writer.md # tactical per-file breakdown (model: gpt-5.3-codex-high)
    section-re-explorer.md  # re-explores sections with no related files (model: claude-opus)
    setup-excerpter.md      # extracts section excerpts from globals (model: claude-opus)
    bridge-agent.md         # resolves cross-section interface friction (model: gpt-5.3-codex-xhigh)
  templates/
    implement-proposal.md   # 10-step implementation schedule
    research-cycle.md       # 7-step research schedule
    rca-cycle.md            # 6-step RCA schedule

Workspaces live on native filesystem for performance, separate from project:

• Planspace: ~/.claude/workspaces/<task-slug>/ — schedule, state, log, artifacts, coordination database
• Codespace: project root or worktree — where source code lives

Clean up planspace when workflow is fully complete (rm -rf the workspace dir).

Phase Detection

Check these in order:

1. User explicitly requested an action → Read the matching file
2. Test failures need investigation → rca.md
3. Proposal exists, not yet evaluated → evaluate.md
4. Proposal evaluated, no baseline → baseline.md
5. Baseline exists, implementation needed → implement.md
6. No proposal exists → research.md
7. Something feels wrong about a change → constraints.md
8. Need to pick a model → models.md
9. Need structured task decomposition → audit.md

Files

| File | What It Does | |------|-------------| | research.md | Exploration → alignment → proposal → refinement | | evaluate.md | Proposal alignment review (Accept / Reject / Push Back) | | baseline.md | Atomize proposal into constraints / patterns / tradeoffs | | implement.md | Multi-model implementation with worktrees + dynamic scheduling | | rca.md | Root cause analysis + architectural fix for test failures | | audit.md | General structured task decomposition + delegation | | constraints.md | Surface implicit constraints, validate design principles | | models.md | Model selection guide for multi-model workflows |

Design Philosophy

These principles govern all pipeline behavior. Violations are alignment failures.

1. Alignment over audit — Check directional coherence between adjacent layers ("is it solving the right problem?"), never feature coverage against a checklist ("is it done?"). The system is never done.
2. Strategy over brute force — Strategy collapses many waves of problems in one go. Brute force leads to countless cycles. Fewer tokens, fewer cycles, same quality.
3. Scripts dispatch, agents decide — Scripts do mechanical coordination (dispatch, check, log). Agents do reasoning (explore, understand, decide). Strategic decisions (grouping, relatedness, signal interpretation) belong to agents, not scripts.
4. Heuristic exploration, not exhaustive scanning — Build a routing map (codemap), then use it for targeted investigation. Never catalog every file. The cost of occasionally routing wrong is far less than exhaustive scanning.
5. Problems, not features — We decompose problems all the way down, then solve tiny problems. Proposals describe strategies, not implementations. We never do feature coverage because we generate as we go.
6. Proposals must solve the same problems — Alternative proposals are valid only if they solve the original problems. An optimization or complexity argument is an excuse. Do not introduce constraints the user did not specify.

Terminology Contract

• "Audit" only ever means alignment against stated problems and constraints — never feature coverage against a checklist.
• "Alignment" is directional coherence between adjacent layers: does the work solve the problem it claims to solve?
• "Feature coverage" is explicitly banned as a verification method. Plans describe problems and strategies, not enumerable features.

The Full Lifecycle

Exploration → Alignment → Proposal → Review → Baseline → Implementation → Verification
  (research.md)           (evaluate.md) (baseline.md) (implement.md)    (rca.md)

Phases iterate: Review may loop back to Research. Implementation may trigger tangent research cycles. Verification may reveal architectural issues requiring RCA.

Artifact Flow

[Raw Idea]
    ↓
[Exploration Notes]              ← research.md Phase A
    ↓
[Alignment Document]             ← research.md Phase B
    ↓
[Proposal]                       ← research.md Phase C
    ↓
[Evaluation Report]              ← evaluate.md (iterate if REJECT/PUSH BACK)
    ↓
[Design Baseline]                ← baseline.md (constraints/, patterns/, TRADEOFFS.md)
    ↓
[Section Files → Integration Proposals → Strategic Implementation → Code]  ← implement.md
    ↓
[Tests → Debug → Constraint Check → Lint → Commit]   ← implement.md + rca.md

Workflow Orchestration

For multi-step workflows, use the orchestration system instead of running everything from memory.

Dispatch: All Agents via uv run agents

CRITICAL: All step dispatch goes through uv run agents via Bash. Never use Claude's Task tool to spawn sub-agents — it causes "sibling" errors and reliability issues. The agent runner automatically unsets CLAUDECODE so sibling Claude sessions can launch.

# Sequential dispatch — model directly with prompt file
uv run agents --model <model> --file <planspace>/artifacts/step-N-prompt.md \
  > <planspace>/artifacts/step-N-output.md 2>&1

# Agent file dispatch — agent instructions prepended to prompt
uv run agents --agent-file "$WORKFLOW_HOME/agents/exception-handler.md" \
  --file <planspace>/artifacts/exception-prompt.md

# Parallel dispatch with db.sh coordination
(uv run agents --model gpt-5.3-codex-high --file <prompt-A.md> && \
  bash "$WORKFLOW_HOME/scripts/db.sh" send <planspace>/run.db orchestrator "done:block-A") &
(uv run agents --model gpt-5.3-codex-high --file <prompt-B.md> && \
  bash "$WORKFLOW_HOME/scripts/db.sh" send <planspace>/run.db orchestrator "done:block-B") &
bash "$WORKFLOW_HOME/scripts/db.sh" recv <planspace>/run.db orchestrator
bash "$WORKFLOW_HOME/scripts/db.sh" recv <planspace>/run.db orchestrator

# Codemap exploration dispatch (Opus explores the codespace)
uv run agents --model claude-opus --project <codespace> \
  --file <planspace>/artifacts/scan-logs/codemap-prompt.md \
  > <planspace>/artifacts/codemap.md 2>&1

Schedule Templates

Pre-built schedules in $WORKFLOW_HOME/templates/. Each step specifies its model:

[wait] 1. step-name | model-name -- description (skill-section-reference)

• implement-proposal.md — full 10-step implementation pipeline
• research-cycle.md — research → evaluate → propose → refine
• rca-cycle.md — investigate → plan fix → apply → verify

Stage 3 Codemap Exploration

Stage 3 dispatches agents to explore and understand the codebase:

1. An Opus agent explores the codespace — reads files, follows its curiosity, builds understanding.
2. The agent writes <planspace>/artifacts/codemap.md capturing what it discovered.
3. Per-section Opus agents use the codemap to identify related files for each section.
4. Deep scan dispatches GLM agents to reason about specific file relevance in context.

Control and recovery:

• If codemap.md already exists, codemap exploration can be skipped.
• If a section already has ## Related Files, its exploration is skipped.
• Non-zero codemap exit stops Stage 3 before section exploration.

Model Roles

| Model | Used For | |-------|----------| | claude-opus | Section setup (excerpt extraction), alignment checks (shape/direction), decomposition, codemap exploration, per-section file identification | | gpt-5.3-codex-high | Integration proposals, strategic implementation, coordinated fixes, extraction, investigation | | gpt-5.3-codex-high2 | Constraint audit (same capability, different quota) | | gpt-5.3-codex-xhigh | Deep architectural synthesis, proposal drafting | | glm | Test running, verification, quick commands, deep file analysis, semantic impact analysis, sub-agent exploration during integration proposals |

Prompt Files

Step agents receive self-contained prompt files (they cannot read $WORKFLOW_HOME). The orchestrator builds each prompt from:

1. Skill section text — copied verbatim from the referenced skill file
2. Planspace path — so the agent can read/write state and artifacts
3. Codespace path — so the agent knows where source code lives
4. Context — relevant content from state.md
5. Output contract — what the agent should return on success/failure

Written to: <planspace>/artifacts/step-N-prompt.md

Workspace Structure

Each workflow gets a planspace at ~/.claude/workspaces/<task-slug>/:

• schedule.md — task queue with status markers (copied from template)
• state.md — current position + accumulated facts
• log.md — append-only execution log
• artifacts/ — prompt files, output files, working files for steps
  • artifacts/sections/ — section excerpts (proposal + alignment excerpts)
  • artifacts/proposals/ — integration proposals per section
  • artifacts/snapshots/ — post-completion file snapshots per section
  • artifacts/notes/ — cross-section consequence notes
  • artifacts/coordination/ — global coordinator state and fix prompts
  • artifacts/decisions/ — accumulated parent decisions per section (from pause/resume)
• run.db — coordination database (messages, events, agent registry)
• constraints/ — discovered constraints (promote later)
• tradeoffs/ — discovered tradeoffs (promote later)

Coordination System (db.sh)

SQLite-backed coordination for agent messaging. One run.db per pipeline run — messages are claimed (not consumed), history is preserved, and the database file is the complete audit trail.

# Initialize the coordination database (idempotent)
bash "$WORKFLOW_HOME/scripts/db.sh" init <planspace>/run.db

# Send a message to an agent
bash "$WORKFLOW_HOME/scripts/db.sh" send <planspace>/run.db <target> [--from <agent>] "message text"

# Block until a message arrives (agent sleeps, no busy-loop)
bash "$WORKFLOW_HOME/scripts/db.sh" recv <planspace>/run.db <name> [timeout_seconds]

# Check pending count (non-blocking)
bash "$WORKFLOW_HOME/scripts/db.sh" check <planspace>/run.db <name>

# Read all pending messages
bash "$WORKFLOW_HOME/scripts/db.sh" drain <planspace>/run.db <name>

# Agent lifecycle
bash "$WORKFLOW_HOME/scripts/db.sh" register <planspace>/run.db <name> [pid]
bash "$WORKFLOW_HOME/scripts/db.sh" unregister <planspace>/run.db <name>
bash "$WORKFLOW_HOME/scripts/db.sh" agents <planspace>/run.db
bash "$WORKFLOW_HOME/scripts/db.sh" cleanup <planspace>/run.db [name]

# Event logging and querying
bash "$WORKFLOW_HOME/scripts/db.sh" log <planspace>/run.db <kind> [tag] [body] [--agent <name>]
bash "$WORKFLOW_HOME/scripts/db.sh" tail <planspace>/run.db [kind] [--since <id>] [--limit <n>]
bash "$WORKFLOW_HOME/scripts/db.sh" query <planspace>/run.db <kind> [--tag <t>] [--agent <a>] [--since <id>] [--limit <n>]

Key patterns:

• Orchestrator blocks on recv waiting for parallel step results
• Step agents send done:<step>:<summary> or fail:<step>:<error> when finished
• Section-loop sends summary:setup:, summary:proposal:, summary:proposal-align:, summary:impl:, summary:impl-align:, status:coordination: messages; complete only on full success; fail:<num>:coordination_exhausted:<summary> on coordination timeout
• Mailbox is required for orchestrator/step coordination boundaries
• Codemap exploration is a single Opus agent that explores the codespace directly
• Agents needing user input send ask:<step>:<question>, then block on their own mailbox
• User or orchestrator can send abort to any agent to trigger graceful shutdown
• agents command shows who's registered and who's waiting — detect stuck agents

Cross-Cutting Tools

• audit.md — Structured decomposition + delegation for any large task
• constraints.md — Before implementation or when something feels wrong
• models.md — Which external model to use for any given task