Audit

---
name: audit
description: Run a full codebase audit chain — architecture, security, toolkit integrity, then the docs pipeline by invoking the `docs` skill, then security again. Spawns four named agents consecutively, chained on task dependencies, and reports results.
disable-model-invocation: true
argument-hint: [optional focus area]
---

# Codebase Audit Chain

Run the full audit pipeline in consecutive order. Each agent audits the codebase and (where its role grants edit tools) implements fixes before the next one starts; report-only agents deliver findings for the user or a later agent to fix.

The documentation passes are **not this skill's to run**. A skill is the unit of work and orchestration is only sequencing: this chain **invokes the `docs` skill** for its documentation step and never re-spawns `docs-agent` or `docs-human` itself. The `docs` skill owns its own pipeline — a read-only architecture change report, then `docs-agent` fed by that report, then `docs-human` — so nothing about the doc passes is wired here.

## Chain Order

1. **harness-architect** — Audit and improve codebase structure (module patterns, file organization, naming, dependency rules, import paths)
2. **general-purpose** (pass 1) — Full security audit per the security-audit skill checklist
3. **general-purpose** (Toolkit integrity) — Validates manifests, placeholders, tests, and render/lock integrity (validate + test + render + doctor).
4. **`docs` skill** (invoked, not spawned) — Refresh the machine docs and the human docs. The skill runs its own three-step pipeline: a read-only architecture change report, then `docs-agent`, then `docs-human`, each step informed by the one before.
5. **general-purpose** (pass 2) — Re-audit the entire codebase including all changes made by earlier agents and by the docs pipeline. Ensure no new issues were introduced.

## Spawn-and-collect contract

Every orchestrator in this stack spawns and collects agents the same way — this chain, `autopilot`'s gate loops and audit gate, `standup`'s one-wave round-up. This section is that scaffold's **one home**: the others cite it by heading and state only what differs (a task chain here; per-round persistence in `autopilot`; no barriers in `standup`). An invoked skill's spawns belong to that skill — the `docs` skill's, for instance, are spawned, collected and torn down by the `docs` skill's own prose and are never part of the invoker's roster or teardown.

1. **Named spawn, name as address.** Every spawn carries `name:`. The name is the agent's address — `SendMessage(to:)` reaches it and `TaskStop(task_id:)` stops it — so the orchestrator holds nothing else to talk to or stop an agent it started.
2. **Collection.** Each agent reports back to the orchestrator with `SendMessage`. An agent whose toolset lacks `SendMessage`/`TaskUpdate` finishes silently — its returned tool result is its report — and the orchestrator verifies the work directly and does any task bookkeeping itself. The orchestrator never waits on a message or a task update from a silent specialist.
3. **Teardown is shutdown-then-stop.** At every exit — success, cap reached, a red round, an error — the orchestrator sends `shutdown_request` and then calls `TaskStop`, for each agent it actually spawned and only those. The request is the courtesy; the stop is the guarantee. A requested agent can go idle but stay alive, so the request alone never proves the agent is gone; the stop terminates it and is safe on an agent that has already exited. Wrap the run so an error still reaches the teardown — a leaked agent is never acceptable.
4. **Seat constraint.** The seat an orchestrator runs from decides what it may do (verified against the live harness, 2026-09-18). From a **named** agent's seat a named spawn is rejected — `Teammates cannot spawn other teammates — the team roster is flat` — so omit `name:` and address the agent by the `agentId` the spawn returns; `SendMessage` and `TaskStop` both accept it in place of a name. From an **unnamed** subagent's seat a named spawn is accepted and `SendMessage(to: <name>)` reaches it. From **any** spawned seat, teardown is impossible: `shutdown_request` messages and `TaskStop` are acts of the main session and are rejected from a spawned agent. An orchestrator running from a spawned seat therefore hands its agent names back to the session that spawned it — that session performs the teardown — rather than reporting a teardown it cannot perform.

## Execution Steps

The chain is **four named agents** plus one invoked skill, run one at a time and chained on task dependencies. There is no team to create or delete: the session has a **single implicit team**, and the `Agent` tool's `team_name` parameter is deprecated and ignored. An agent's `name:` is its address — `SendMessage(to: "<name>")` reaches it and `TaskStop(task_id: "<name>")` stops it. Spawning, collection, teardown and the seat constraint follow the [Spawn-and-collect contract](#spawn-and-collect-contract) above.

### 1. Create the Tasks, Then Chain Them

`TaskCreate` takes `subject` **and** `description` (both required); it has no `team_name` and no `addBlockedBy`. Dependencies are wired **afterwards**, with `TaskUpdate`:

```
task1 = TaskCreate(subject: "Architecture audit", description: "Audit and improve codebase structure")
task2 = TaskCreate(subject: "Security pass 1",    description: "Full security audit per the security-audit checklist")
task3 = TaskCreate(subject: "Toolkit integrity check", description: "Validates manifests, placeholders, tests, and render/lock integrity (validate + test + render + doctor).")
task4 = TaskCreate(subject: "Documentation",      description: "Invoke the docs skill — change report, machine docs, human docs")
task5 = TaskCreate(subject: "Security pass 2",    description: "Re-audit including all changes made by earlier agents")

# addBlockedBy is a TaskUpdate parameter, not a TaskCreate one — and the key is taskId, not id
TaskUpdate(taskId: task2.id, addBlockedBy: [task1.id])
TaskUpdate(taskId: task3.id, addBlockedBy: [task2.id])
TaskUpdate(taskId: task4.id, addBlockedBy: [task3.id])
TaskUpdate(taskId: task5.id, addBlockedBy: [task4.id])
```

### 2. Spawn Agents Sequentially

For each step, spawn the named agent, wait for completion, then proceed:

```
Agent(
  subagent_type: "harness-architect",
  name: "architecture-pass",
  prompt: <architecture prompt>
)
# After completion:
TaskUpdate(taskId: task1.id, status: "completed")
```

```
Agent(
  subagent_type: "general-purpose",
  name: "security-pass1",
  prompt: <security pass 1 prompt>
)
TaskUpdate(taskId: task2.id, status: "completed")
```

**Gate after pass 1:** present the security findings to the user. Do **not** auto-proceed if there are Critical or High findings — wait for the fixes (by the user or the architecture agent) or an explicit override before continuing the chain.

```
Agent(
  subagent_type: "general-purpose",
  name: "toolkit-integrity",
  prompt: <Toolkit integrity check prompt>
)
TaskUpdate(taskId: task3.id, status: "completed")
```

**Documentation (Task 4) — invoke, do not spawn.** Invoke the `docs` skill (`.claude/skills/docs/SKILL.md`) and run it to completion exactly as it documents itself: its step 1 is a **read-only** architecture change report, its step 2 hands that report to `docs-agent`, its step 3 runs `docs-human` after `docs-agent` completes. Pass the focus area along (see [Focus Area](#focus-area)). Do not spawn `docs-agent` or `docs-human` from this chain and do not thread anything between them — the `docs` skill owns that wiring. Its spawns are its own: they finish and return, and they are not part of this chain's named roster or its teardown. That the `docs` skill spawns `harness-architect` a second time is by design — pass 1 above *remediates* structure; the docs pipeline's pass only *reports* what changed so the doc writers are informed.

```
# After the docs skill completes:
TaskUpdate(taskId: task4.id, status: "completed")
```

```
Agent(
  subagent_type: "general-purpose",
  name: "security-final",
  prompt: <security pass 2 prompt>
)
TaskUpdate(taskId: task5.id, status: "completed")
```

### 3. Summary and Teardown

After all 5 complete, present the user a consolidated summary table of findings and fixes per step, then tear the named agents down:

```
# Politely ask each agent to wind down…
SendMessage(to: "architecture-pass", message: {type: "shutdown_request", reason: "Audit chain complete"})
SendMessage(to: "security-pass1",    message: {type: "shutdown_request", reason: "Audit chain complete"})
SendMessage(to: "toolkit-integrity", message: {type: "shutdown_request", reason: "Audit chain complete"})
SendMessage(to: "security-final",    message: {type: "shutdown_request", reason: "Audit chain complete"})

# …then confirm the kill.
TaskStop(task_id: "architecture-pass")
TaskStop(task_id: "security-pass1")
TaskStop(task_id: "toolkit-integrity")
TaskStop(task_id: "security-final")
```

**Teardown is shutdown-then-stop.** `shutdown_request` is the polite first step, and an agent that honours it terminates cleanly. It is **not** reliable on its own — a requested agent can go idle but stay alive, still emitting idle notifications. `TaskStop(task_id: "<agent-name>")` is what actually terminates it, and it is safe to call on an agent that has already exited. Never treat a sent `shutdown_request` as proof the agent is gone; always follow through. There is nothing else to tear down — with a single implicit team per session, no team object is created and none is deleted, and the `docs` skill's own spawns are not this chain's to stop.

## Agent Prompts

Each agent this chain spawns should:

- Read its corresponding skill in `.claude/skills/` for standards and checklists
- Read the full project source and root
- Implement fixes directly if its role grants edit tools; report-only agents deliver a severity-ranked findings report instead
- Verify the build passes after changes (`npm run typecheck`)
- Send a findings summary to the team lead: `SendMessage(to: "team-lead", message: <summary>, summary: "<5–10 word preview>")`
- Mark its task as completed: `TaskUpdate(taskId: <task_id>, status: "completed")`

If an agent's toolset lacks `SendMessage`/`TaskUpdate`, it finishes silently — verify its output directly and do the task bookkeeping yourself.

The docs pipeline's agents take their prompts from the `docs` skill, not from here.

### Architecture (Task 1)

Audit for: module pattern adherence, file structure conventions, naming (kebab-case files, PascalCase classes/components, camelCase functions), dependency rules (no circular deps), import paths (through index.ts), type exports in a types module, entry point kept lifecycle-only, index.ts as public API. Fix all issues.

### Security Pass 1 (Task 2)

Full audit per the general-purpose agent's own checklist — and `.claude/skills/security-audit/SKILL.md` where the project has that skill, as the source of truth for grep patterns and the severity rubric. Apply fixes if your role permits edits; otherwise deliver a severity-ranked findings report and do not modify code.

### Toolkit integrity (Task 3)

Run the toolkit's own checks in order and report violations:

1. `npm run validate` — manifests parse, frontmatter is complete, every placeholder is declared
2. `npm test` — installer suite passes
3. `node installer/cli.mjs render --allow-unreleased && node installer/cli.mjs doctor` — rendered output matches the lock (no hand-edits to generated `.claude/` files). The flag is required (#373): `render` refuses from a toolkit that is not at a release tag, and a branch checkout never is; plain `doctor` is not gated and needs nothing.
4. Spot-check changed stacks: every placeholder used in content is declared in that `stack.yaml`; `setup:` notes contain no placeholders

Fix what your role permits (source side only, then re-render); otherwise report each failure with the command output quoted.

### Security Pass 2 (Task 5)

Repeat the full security audit checklist. Focus especially on: new files created by earlier agents and by the docs pipeline, any content written to project root, ensuring no sensitive information was documented, all previous fixes still intact. Same fix-or-report behavior as pass 1.

## Focus Area

If `$ARGUMENTS` is provided, instruct all agents to pay special attention to that area while still performing their full audit, and pass the same focus to the `docs` skill when you invoke it. For example: `/audit data pipeline` focuses extra attention on the data-layer modules.

## Claude Workflow Variant

The same chain ships as two staged Claude workflow scripts — opt-in syrup, Claude target only: `.claude/workflows/audit-stage-1.js` (architecture → security pass 1) and `.claude/workflows/audit-stage-2.js` (Toolkit integrity → the `docs` skill, step by step → security pass 2). Install both with `wafflestack install files/.claude/workflows/audit-stage-1.js files/.claude/workflows/audit-stage-2.js`. Every phase runs a section of this skill or of the `docs` skill; the scripts hold sequencing only, so the prose here stays the source of truth for what a pass does.

**Sign-off happens between the two runs.** Stage 1 returns `{ stoppedAt, signOffRequired, architecture, security1 }` and sets `stoppedAt: "security-1"` when Critical/High findings remain — the gate after pass 1 above, as a hard stop. Present the findings; only after a human has reviewed them, run stage 2 with `args: { stage1: <stage-1 result>, signedOff: true }` (it refuses an un-signed-off stop). With no stop, run stage 2 with `args: { stage1: <stage-1 result> }`.

This prose chain is the permanent fallback: workflows are paid-plan, version-gated and can be switched off, so a poured script may be inert — whenever the `Workflow` tool is unavailable, run the chain above.

## Summary Format

After all steps complete, present:

```
## Audit Complete

| # | Step | Findings | Fixes Applied |
|---|------|----------|---------------|
| 1 | harness-architect | N issues | brief list |
| 2 | general-purpose (pass 1) | N issues | brief list |
| 3 | general-purpose (Toolkit integrity) | N issues | brief list or "clean" |
| 4 | `docs` skill (docs-agent, docs-human) | N files created/updated | file list |
| 5 | general-purpose (pass 2) | N issues | brief list or "clean" |

Build status: passing/failing
```