# Multi-Agent Development Pipeline

This block is managed by `multi-agent-pipeline`. Edit anything outside it freely;
the installer replaces only the span up to the end marker.

The pipeline is an 8-phase development workflow (analysis, planning, TDD dev,
parallel review + triage, test, commit, report). It is invoked as `/multi-agent`
or `$multi-agent`, and the orchestrator spec lives at
`$HOME/.codex/skills/multi-agent/SKILL.md`.

## Host adaptation (Codex CLI)

| Concern          | On Codex                                                                                                                     |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Orchestrator     | one skill, `multi-agent` - it reads per-command specs on demand from `$HOME/.codex/multi-agent-refs/commands/<cmd>/SKILL.md` |
| Phase specs      | `$HOME/.codex/multi-agent-refs/phases/phase-N-*.md`, read only when that phase runs                                          |
| Personas         | `$HOME/.codex/agents/*.toml` (generated from the pipeline's persona set)                                                     |
| Progress display | the native `update_plan` tool, one plan step per phase, plus `phase-tracker.sh` state on disk                                |
| Shared state     | task logs and preferences stay under `$HOME/.claude/` - that path is the cross-host state root, not a Claude Code dependency |

## Sub-agent delegation is authorized for this pipeline

Codex does not spawn sub-agents unless instructions explicitly ask for it. The
pipeline's Phase 1 (parallel codebase scan) and Phase 4 (parallel review) depend
on real fan-out, so **delegation is authorized whenever a `/multi-agent` or
`$multi-agent` run is active**, under these rules:

1. **Always pass `fork_turns: "none"`** (or a positive integer) on a
   `spawn_agent` that sets `model` or `reasoning_effort`. A full-history fork
   inherits the parent model and **silently discards the override**, which would
   collapse the whole review panel onto one model with no error.
2. **At most 3 concurrent children.** There are 4 concurrency slots including the
   orchestrator, so a 3-reviewer panel is the ceiling; a 4th child queues rather
   than running in parallel.
3. Outside an active pipeline run, the default applies: do not delegate unless
   asked.

## The skills are on disk, not in the list

`$HOME/.codex/multi-agent-refs/skills/<name>/SKILL.md` holds every skill Claude Code
and Copilot CLI get: the pipeline's shared knowledge set plus the enabled stack
plugin's lifecycle skills (`create-screen`, `create-component`, `figma-validate`,
`figma-review`, `component`, `state`, `navigation`, `ios-coding-standard`, and the
rest). They are reference files rather than block entries, so they cost nothing until
read.

That means they will not be suggested to you. Look for one when the work calls for it:

```bash
ls "$HOME/.codex/multi-agent-refs/skills"                      # what exists
grep -rl "<topic>" "$HOME/.codex/multi-agent-refs/skills"/*/SKILL.md | head   # by content
head -4 "$HOME/.codex/multi-agent-refs/skills/<name>/SKILL.md"  # its description
```

Read the SKILL.md before implementing in its area, exactly as you would read a phase
spec. A component or screen task should reach `figma-validate` and `create-screen`; a
Swift review should reach `ios-coding-standard` and cite rule IDs from
`references/rules.yml`. Guessing a convention that one of these files states is the
failure this layout exists to prevent.

## Outside a pipeline run

The install leaves capability behind that a `$multi-agent` run is not required to
use. `$HOME/.codex/rules/outside-the-pipeline.md` carries it, and it applies to an
ordinary session:

- **Service credentials.** Tokens onboarded by setup resolve through
  `$HOME/.codex/lib/credential-store.sh get <key>`, keyed by
  `prefs.global.keychainMapping`. Read freely; route writes (Jira comments, issue
  edits, PRs) to the pipeline commands that carry the rules making them safe.
  A value must never reach argv, a log or a reply.
- **Stack skills.** Whatever is enabled for the repo is available now - ask each
  enabled toolkit's own `index` first rather than guessing from a skill name.
- **multi-agent-toolkit MCP.** Registered by the installer and preserved by
  uninstall; reach for it instead of guessing about a running app.

Detail: `$HOME/.codex/multi-agent-refs/outside-the-pipeline.md`.

## Skills-block budget

Codex assembles every discovered skill's name + description into one prompt block
and **silently drops entries when that block overflows**. The pipeline therefore
contributes exactly **one** skill (`multi-agent`) and keeps every sub-command
specs as reference files that cost nothing until read. Do not convert those specs
into peer skills: doing so evicts other skills, including ones from installed
plugins, with no error surfaced.