harness

What this skill does

# Harness — Agent Team & Skill Architect

A meta-skill that builds a harness for a domain or project: it defines each agent's role and generates the skills those agents use.

**Core principles:**
1. Generate agent definitions (`.claude/agents/`) and skills (`.claude/skills/`).
2. **Agent teams are the default execution mode.**
3. **Register a harness pointer in CLAUDE.md** — record only the trigger rule (pointer) so the orchestrator skill fires in new sessions. No change log in CLAUDE.md; the evolution log lives in the harness README.
4. **A harness is a living system, not a fixed artifact** — after every run, fold in feedback and keep agents, skills, and CLAUDE.md current.

## Workflow

### Phase 0: Status Audit

When the harness skill triggers, first establish what already exists.

1. Read `project/.claude/agents/`, `project/.claude/skills/`, and `project/CLAUDE.md`.
2. Branch on what you find:
   - **New build**: agent/skill directories absent or empty → run Phase 1 onward in full.
   - **Extend existing**: a harness exists and the user wants to add agents/skills → run only the phases the matrix below selects.
   - **Operate/maintain**: the user wants to audit, fix, or sync an existing harness → jump to the Phase 7-5 operate/maintain workflow.

   **Phase selection matrix (extending an existing harness):**
   | Change type | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 | Phase 6 |
   |----------|---------|---------|---------|---------|---------|---------|
   | Add agent | skip (reuse Phase 0 result) | placement only | required | if a dedicated skill is needed | edit orchestrator | required |
   | Add/edit skill | skip | skip | skip | required | if wiring changes | required |
   | Architecture change | skip | required | affected agents only | affected skills only | required | required |
3. Cross-check the existing agent/skill inventory against the README change log to detect drift.
4. Summarize the audit to the user and confirm the execution plan.

### Phase 1: Domain Analysis
1. Identify the domain/project from the request.
2. Identify the core task types (generation, validation, editing, analysis, etc.).
3. Using the Phase 0 audit, analyze conflicts/overlaps with existing agents and skills.
4. Explore the project codebase — tech stack, data models, key modules.
5. **Detect user proficiency** — read contextual cues (terminology used, depth of questions) to gauge technical level, then calibrate your communication tone. Don't use terms like "assertion" or "JSON schema" unexplained with users who show little coding experience.

### Phase 2: Team Architecture Design

#### 2-1. Choose the execution mode

**Agent teams are the top-priority default.** Whenever two or more agents collaborate, evaluate an agent team first. Teammates self-coordinate via direct messaging (SendMessage) and a shared task list (TaskCreate); sharing findings, debating conflicts, and covering each other's gaps raises output quality.

| Mode | When to use | Mechanism |
|------|----------|------|
| **Agent team** (default) | 2+ agents collaborating, real-time coordination/feedback, cross-referenced intermediate outputs | `TeamCreate` + `SendMessage` + `TaskCreate`, self-coordinating |
| **Subagent** (alternative) | Single-agent task, returning only a result to main is enough, team-comms overhead would be excessive | `Agent` tool called directly, parallel via `run_in_background` |
| **Hybrid** | Phases differ in character — e.g. parallel collection (sub) → consensus synthesis (team) | mix team/sub per phase |

**Decision order:**
1. First check whether an agent team works — for 2+ agents it's the default.
2. Pick subagents only when team communication is structurally unnecessary (result handoff only) and the team overhead outweighs its benefit.
3. If phases differ markedly, consider hybrid — name each phase's mode in the orchestrator.

> For the full comparison and per-pattern decision tree, see "Execution modes" in `references/agent-design-patterns.md`.

#### 2-2. Choose the architecture pattern

1. Decompose the work into areas of expertise.
2. Decide the team structure (patterns in `references/agent-design-patterns.md`):
   - **Pipeline**: sequential, dependent tasks
   - **Fan-out/Fan-in**: parallel, independent tasks
   - **Expert Pool**: context-dependent selective dispatch
   - **Producer-Reviewer**: generate, then quality-review
   - **Supervisor**: a central agent holds state and distributes work dynamically
   - **Hierarchical Delegation**: a higher agent delegates recursively to lower ones

#### 2-3. Agent separation criteria

Judge on four axes: expertise, parallelism, context, reusability. See "Agent separation criteria" in `references/agent-design-patterns.md`.

### Phase 3: Generate Agent Definitions

**Every agent must be defined as a file at `project/.claude/agents/{name}.md`.** Putting a role directly in an Agent tool's prompt without a definition file is prohibited, because:
- A file-based definition can be reused in later sessions.
- An explicit team communication protocol is what guarantees collaboration quality.
- The harness's core value is separating the agent (who) from the skill (how).

Create a definition file even when using a built-in type (`general-purpose`, `Explore`, `Plan`). Pass the built-in type via the Agent tool's `subagent_type` parameter; the definition file carries the role, principles, and protocol.

**Model:** every agent uses `model: "opus"`. Always pass `model: "opus"` on Agent calls. Harness quality is bound to agent reasoning, and opus gives the best quality.

**Team reconfiguration:** only one team can be active per session, but you may disband and form new teams between phases. When a Pipeline needs a different mix of specialists per phase, save the previous team's output to file, clear the team, and create a new one.

Define each agent in `project/.claude/agents/{name}.md`. Required sections: core role, working principles, input/output protocol, error handling, collaboration. In agent-team mode, add a `## Team Communication Protocol` section naming message senders/receivers and the scope of task requests.

> For the definition template and full example files, see "Agent definition structure" in `references/agent-design-patterns.md` plus `references/team-examples.md`.

**When including a QA agent:**
- Use the `general-purpose` type (`Explore` is read-only and can't run verification scripts).
- The point of QA is not "does it exist" but **cross-boundary comparison** — read the API response and the frontend hook together and compare their shapes.
- Run QA incrementally, right after each module completes — not once at the end.
- See `references/qa-agent-guide.md`.

### Phase 4: Generate Skills

Generate each agent's skills at `project/.claude/skills/{name}/SKILL.md`. See `references/skill-writing-guide.md` for the authoring guide.

#### 4-1. Skill structure

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown body
└── Bundled resources (optional)
    ├── scripts/    - executable code for repetitive/deterministic work
    ├── references/ - reference docs loaded on demand
    └── assets/     - files used in output (templates, images, etc.)
```

#### 4-2. Writing the description — trigger assertively

The description is a skill's only trigger mechanism. Claude tends to judge triggers conservatively, so write the description **assertively ("pushy")**.

**Bad:** `"A skill that processes PDF documents"`
**Good:** `"Read PDFs and perform every PDF operation — text/table extraction, merge, split, rotate, watermark, encrypt, OCR. Use this skill whenever a .pdf file is mentioned or a PDF deliverable is requested."`

Key: state both what the skill does and the concrete trigger situations, written so it's distinguishable from similar cases that should *not* trigger it.

#### 4-3. Body principles

| Principle | What it means |
|------|------|
| **Explain why** | Instead of coercive ALWAY