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              # concern-based problem decomposition
  constraints.md        # constraint discovery
  models.md             # model selection guide
  scripts/
    workflow.sh         # schedule state markers ([wait]/[run]/[done]/[fail]) — internal, not the entry point
    db.sh               # SQLite-backed coordination database
  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)
  <system>/agents/      # agent definitions distributed across system modules (scan/, proposal/, implementation/, verification/, testing/, etc.)
  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 — where source code lives

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

Your Role

BEFORE DOING ANYTHING ELSE: Determine your role in the pipeline, then read the corresponding agent definition file. Agent definitions are distributed under system-owned directories (e.g., $WORKFLOW_HOME/<system>/agents/<name>.md); the task router resolves agent files by name. Do not proceed until you have read it.

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 concern-based problem decomposition → audit.md

Files

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. Accuracy over shortcuts — zero tolerance for fabrication and bypasses —

We accept zero tolerance for invented understanding, bypassed safeguards, or pipeline shortcuts that skip required grounding. Agents must follow the full pipeline faithfully: explore before proposing, propose before implementing, align before proceeding. Operational execution still uses proportional guardrails: the ROAL loop scales effort to actual risk and keeps residual risk below the configured threshold rather than pretending all execution can be made literally risk-free. "This is simple enough to skip a step" is never valid reasoning. When in doubt, follow the pipeline.

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.

Running the Implementation Pipeline

All implementation work goes through the canonical pipeline runner:

python -m pipeline <planspace> <codespace> --spec <spec-path> [--slug <slug>] [--qa-mode]

The runner provides minimal bootstrap: planspace initialization (paths, parameters.json, run-metadata.json, run.db), then hands off to the adaptive orchestration system. It does NOT own stages, schedule, governance, or directory scaffolding -- those are determined by the system's own decision-making (ROAL, coordination, signal processing).

Do NOT dispatch agents directly via the agents binary or write prompts manually. All dispatch must go through the pipeline's adaptive orchestration system.

Never use any sub-agent spawning or delegation mechanism outside this repo's dispatch and task-submission system — external spawning causes "sibling" errors and reliability issues.

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 — external research → evaluate → propose → refine (human-facing)
• rca-cycle.md — investigate → plan fix → apply → verify

Note: In-runtime section research (blocking_research_questions) is handled automatically through queued research_plan tasks within the section loop, not through this external schedule template.

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, reuse it only if the codespace

fingerprint is unchanged or the verifier confirms validity; otherwise rebuild.

• If a section already has ## Related Files, validate the list against

the current codemap/section content; skip only if unchanged.

• Non-zero codemap exit stops Stage 3 before section exploration.

Model Roles

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 typed artifacts and run.db-backed context sidecars
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)
• artifacts/ — prompt files, typed JSON artifacts, context sidecars, 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)
• artifacts/parameters.json — runtime parameters (e.g., {"qa_mode": true} to enable QA dispatch interception)
• artifacts/qa-intercepts/ — QA interceptor prompts, outputs, and rationale files (created when qa_mode is enabled)
• 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 — Concern-based problem decomposition + alignment tracing
• constraints.md — Before implementation or when something feels wrong
• models.md — Which external model to use for any given task

Internal Dispatch Reference (Script Use Only)

WARNING: These are internal implementation details used by the pipeline runner and section dispatcher. The orchestrating session must NOT invoke agents directly. Direct invocation bypasses QA interception, coordination tracking, and pipeline discipline.

# Sequential dispatch — model directly with prompt file
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
agents --agent-file "$WORKFLOW_HOME/proposal/agents/alignment-judge.md" \
  --file <planspace>/artifacts/alignment-prompt.md

# Parallel dispatch with db.sh coordination
(agents --model gpt-high --file <prompt-A.md> && \
  bash "$WORKFLOW_HOME/scripts/db.sh" send <planspace>/run.db orchestrator "done:block-A") &
(agents --model gpt-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)
agents --model claude-opus --project <codespace> \
  --file <planspace>/artifacts/scan-logs/codemap-prompt.md \
  > <planspace>/artifacts/codemap.md 2>&1

Note: The examples above show script-level dispatch — the pipeline runner launching step agents internally. Nested strategic work within step agents (e.g., exploration during integration proposals) uses task submission: agents write structured task-request files, and the dispatcher resolves agent file + model. See implement.md Stage 4-5 for task submission details.