---

Status: complete Last updated: 2026-04-30 Parent: Design - Architecture Overview Read before this: Design - Skill Pipeline, Concept - Progressive Disclosure

Coding Harness Agents

Current state

The agent population that produces deliverables. Three layers, in increasing complexity:

Skills are the top-level unit. A skill is invoked by the user (or a future scheduler), runs end-to-end, produces deliverables, and emits a Contract - Phase Outcome. Skills are stored as folders under .claude/skills/<skill-name>/ containing a SKILL.md, optional procedures, and reference files. They follow Concept - Progressive Disclosure — only metadata loads at startup; full content loads when the skill is invoked.

Subagents are spawned by skills to do focused work in isolated context. They have their own model selection, no inherited context from the skill that spawned them, and return a distilled answer rather than their full reasoning. Subagents are how skills keep their main context clean while doing heavy reading or generation.

Agent Teams are a lead agent coordinating multiple teammates that can message each other. Two skills use them today:

• /develop spawns one Test Writer + Implementer pair per work unit (plus an optional fix agent), each running with Ralph Wiggum persistence to keep iterating until verification passes.
• /code-validate spawns a parallel reviewer team (Dependency Verifier, Bug Hunter, Static Security Reviewer, Spec Checker) that work independently from a shared review scope and report back to the lead.

Coding harness agents write to issues only. They never write to the wiki. The Role - The Documentation Agent is a separate population.

Skills vs agents

Skills are static knowledge plus a procedure, read in the current session. Agents are dispatchable workers with isolated context, their own model, and independent execution. The same project can have a /code-validate skill that uses a Bug Hunter agent — the skill defines the procedure, the agent runs it.

Agent Teams + Ralph Wiggum

Agent Teams provide parallelism; Ralph Wiggum provides per-teammate persistence. Without Ralph, a teammate can prematurely declare "stuck" and stop. Without Agent Teams, work runs serially. The combination — parallel teammates that each refuse to stop until verified done — is what makes /develop reliable enough to run unattended.

Prerequisites: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in ~/.claude/settings.json, and the Ralph Wiggum plugin installed.

Sandbox requirement

/develop runs with --permission-mode=dontAsk. This is recommended only inside a sandbox (devcontainer or equivalent). The devcontainer must be Debian-based (e.g. bookworm) — Alpine is musl-based and Playwright browser binaries may not run reliably on it. /setup warns if Alpine is detected.

Rationale

The three-layer split exists because the layers solve different problems. Skills give you a procedure. Subagents give you context isolation. Agent Teams give you coordinated parallelism. Conflating them produces either skills that grow until they exhaust context, or subagent escalation chains that are hard to reason about.

Agent Teams turned out to be load-bearing in /develop rather than reserved for QA. The original assumption was that parallelism mattered most for QA debate (multiple reviewers cross-checking). In practice, the bigger win was running multiple work units of an SREQ in parallel — backend and frontend changes that don't depend on each other can both be in flight, halving wall-clock time for a typical feature. QA debate runs once at the end; development is the long pole.

Ralph Wiggum is the answer to "how do we keep an agent iterating without a human in the loop?" Without it, agents stop at the first plausible "good enough." With it, agents iterate until their stated completion criteria are objectively met. The cost is more model calls; the benefit is dramatically less hand-holding. The combination with --permission-mode=dontAsk means a feature can run from spawn to "ready for QA" without prompting once.

The "issues only, never wiki" rule comes from the Design - Wiki Layer reader-organised model. If /closeout could write to the wiki, every closeout would be tempted to summarise the feature there — and the wiki would degrade into per-feature changelogs. Forcing wiki writes through a separate agent population that thinks in component knowledge (not feature work) preserves the wiki's structure.

Open questions

None at this level. Specific skill compositions live in their SKILL.md files in the repo.