# Multi-Agent Pipeline Contract

> Canonical reference for AWKit's multi-agent pipeline: roles, gate mapping,
> artifact contract, reviewer rules, and escalation policy.
> Supersedes the role-map brainstorm in Antigravity brain (2026-07).
> Origin: `docs/specs/BRIEF.md` (Consolidate & Instrument).

---

## 1. Roles — role → runner only

Model names are **never** hardcoded in docs or prompts. The active model for a
runner is resolved at runtime via `awkit model` (`scripts/model-manager.js`),
which also tracks login status and quotas.

| Role | Runner | Responsibilities |
|------|--------|------------------|
| **Architect / Planner** | Claude Code | Requirement analysis, architecture, impact analysis (GitNexus), PRD/specs |
| **UI Designer / Asset Maker** | Codex CLI | GUI assets, spritesheets, HTML demo mockups |
| **Executor** | Qwen Coder | Implementation code, unit tests, local lint fixes |
| **Primary Code Reviewer** | Codex CLI | Logic, concurrency, security review → `codex-reports/` |
| **Architecture-Conformance Reviewer** | Claude Code | Verify implementation matches the approved design only |
| **Conductor** | agy (Antigravity CLI) | Flow orchestration, session restore, NeuralMemory sync, git automation, fallback pool |

**Reviewer independence:** the Planner (Claude) must not be the primary
reviewer of code implementing its own plan — Codex (different model family)
reviews first; Claude only checks architecture conformance.

**Codex write boundary** (consistent with `codex-conductor` skill): Codex may
**create new asset files** (`assets/ui/`, reports in `codex-reports/`) but must
**never edit source code**.

## 2. Pipeline phases ↔ 8-Gate mapping

Phases are **conditional on triage** — not every task runs every phase.

| Pipeline phase | Gate(s) | Runner | Runs when |
|----------------|---------|--------|-----------|
| Plan | Gate 0–2 (constitution, clarify, spec, architecture) | Claude Code | MODERATE / COMPLEX |
| UI & Assets | Gate 2.5 (visual design) | Codex CLI | Task has UI surface |
| Code | Gate 4 (execution) | Qwen Coder | Always |
| Review & QA | Gate 5 (verification + code review) | Codex (primary), Claude (conformance) | MODERATE / COMPLEX; TRIVIAL = lint + tests only |
| Commit & Sync | Auto-commit rule | agy / awkit | Always (build green) |

TRIVIAL tasks bypass straight to Code + Commit (per orchestrator triage).

## 3. Artifact contract — who writes what, where

Each phase has exactly **one writer** per artifact path. Agents must respond
with content in stdout; the invoking script is the single writer to disk
(two writers on one path is how a 247-line spec got overwritten by a chat
message — never again).

| Phase | Artifact | Location | Format |
|-------|----------|----------|--------|
| Plan | PRD | `docs/PRD.md` | Markdown |
| Plan | Feature spec | `docs/specs/<feature>_spec.md` | Markdown |
| UI | Demo preview | `assets/ui/demo_preview.html` | HTML |
| UI | GUI assets | `assets/ui/` | PNG / spritesheet + manifest |
| Code | Source changes | project source tree | per repo conventions |
| Escalation | Consult report | `docs/specs/escalation/<feature>_consult_round<N>.md` | Markdown + JSON summary |
| Escalation | Round state | `tmp/escalation_state.json` | JSON (gitignored) |
| Review | Review report | `codex-reports/` | Markdown |
| Any | Temp/scratch files | `tmp/` | gitignored, never committed |

**Never committed:** `tmp/`, `scripts/temp_*`, `temp_*.txt`, executor input
dumps, failure reports. Enforced by `.gitignore`.

## 4. Escalation policy (Executor → Architect)

Implemented in `scripts/escalate-helper.js` + `scripts/multi-model-pipeline.js`.

- **Trigger (deterministic):** exactly `MAX_EXECUTOR_ATTEMPTS = 2` failed
  executor attempts. Attempt count is the only trigger; wall-clock is a
  **safety timeout** (10 min per attempt), never a trigger. The old
  "3 minutes without progress" heuristic is retired (unmeasurable).
- **Classification before escalation:** `classifyError()` splits failures into
  - `code` (compile/test/logic) → eligible for consult;
  - `infra` (auth, quota, network, permissions, missing binary) → **no
    consult**; report to the user immediately. No model fixes a bad credential.
- **Consult cap:** `MAX_CONSULT_ROUNDS = 2` per feature, tracked in
  `tmp/escalation_state.json`. Reaching the cap hard-stops the pipeline for
  human intervention — prevents Executor↔Architect ping-pong loops.
- **Context package per consult:** original prompt, current error, current git
  diff, feature spec, **and the full history of prior rounds** (errors + diffs
  already tried) so the consultant never re-proposes a failed fix.
- **State reset:** a successful Code phase clears the feature's escalation
  state (`clearEscalationState`).

## 5. Fallback matrix (runner-level, model-agnostic)

| Failing runner | Fallback | Notes |
|----------------|----------|-------|
| Claude Code (Plan/Consult) | agy with best available high-reasoning model from `agy models` | preference order encoded in `escalate-helper.js` |
| Codex CLI (UI) | agy + HTML extraction | |
| Qwen Coder (Code) | agy flash-tier model | only when `--no-fallback` is not set |
| agy (Conductor) | Claude Code assumes Conductor duties for the session | backlog: formalize |

Fallback selection queries live runner state (`awkit model`); docs never pin
model IDs.

## 6. Telemetry (Phase 2 — implemented)

Implemented in `scripts/pipeline-telemetry.js`, wired into the pipeline and
escalation helper, surfaced via `awkit model stats`.

- **Event log:** append-only JSONL at `tmp/pipeline_telemetry.jsonl` (gitignored,
  local operational data). Writes are best-effort — telemetry never breaks the
  pipeline.
- **Events recorded:**
  - Code phase: `attempt` (per executor try, with duration + token estimate),
    `success`, `failure` (with `errorType`).
  - Escalation: `consult` (round, runner, duration, tokens), `infra-skip`,
    `cap-reached`.
- **KPIs (`awkit model stats`):** three distinct rates so a capped task isn't
  mistaken for "nothing happened":
  - **Task failure rate** — tasks whose executor gave up (≥1 code failure).
  - **Escalation-triggered rate** — tasks that engaged the escalation machinery
    at all (consult OR cap OR infra-block).
  - **Consult rate** — tasks that reached a LIVE model consult. A capped task
    triggers escalation but never consults, so this is intentionally lower.

  Plus: consult rounds used, infra-skip count, cap-reached count, avg retries
  per code task, and per-phase events/failures/tokens/wall-time.
- **Token counts are estimates** (chars/4) — the underlying CLIs don't expose
  exact usage. Labeled as such in the output; never presented as billed usage.

**Purpose:** verify routing assumptions (e.g. the cost-optimized route's claimed
savings) with evidence — a high consult rate means Qwen consult costs may be
eating the savings. This is the data foundation for future Adaptive Routing.

**Regression test:** `scripts/test-pipeline.js` (`npm run test:pipeline`) covers
classification, consult-report validation, telemetry aggregation, and a
fault-injected end-to-end `awkit pipeline code` run (fake qwen → no model quota,
no repo mutation, config restored byte-exact).

## 7. Consult report format

The Architect consult report is Markdown ending with a JSON summary block
matching `schemas/consult-report.schema.json` (`root_cause` string +
`files_to_modify` string array; optional `precise_diff`). Validated by
`validateConsultReport()` in `escalate-helper.js` — a malformed summary logs a
warning but never discards the human-readable report.