# Architecture

## 6-Phase Pipeline Flow (0-5)

```mermaid
graph TD
    INPUT["🎯 Input<br/>(Issue # / Jira URL / free text)"]
    P0["Phase 0: Init<br/>Project detect, worktree, branch, identity"]
    P1["Phase 1: Plan<br/>Codebase scan (parallel Explore agents),<br/>task breakdown, architecture review, Plan Approval Gate"]
    P2["Phase 2: Dev<br/>TDD: RED → GREEN → REFACTOR<br/>Verify exit gate: build · lint · tests · secrets"]
    P3["Phase 3: Review<br/>Parallel + Fable triage, then the optional user test<br/>(3 reviewers per host: Claude Code Fable + Opus + Sonnet · Copilot GPT-5.4 + Opus + Sonnet)"]
    P4["Phase 4: Commit<br/>Git commit, PR creation"]
    P5["Phase 5: Report<br/>Jira · Wiki+Figma · Confluence · Log · Knowledge"]

    INPUT --> P0
    P0 --> P1
    P1 --> P2
    P2 -->|build + test logs| P3
    P3 -->|approved| P4
    P3 -->|fix needed| P2
    P4 --> P5

    style INPUT fill:#f9f,stroke:#333
    style P2 fill:#ffd,stroke:#333
    style P3 fill:#dff,stroke:#333
    style P5 fill:#a855f7,stroke:#333,color:#fff
```

## Operating Modes

```mermaid
graph LR
    subgraph Normal ["Normal (Full 6-phase)"]
        N0[Init] --> N1[Plan] --> N2[Dev] --> N3[Review] --> N4[Commit] --> N5[Report]
    end

    subgraph Autopilot ["Autopilot (skip confirmations, quality gates on)"]
        A0[Init] --> A1[Plan] --> A2[Dev] --> A3[Review] --> A4[Commit] --> A5[Report]
    end

    subgraph Unattended ["Continuous mode (MULTI_AGENT_UNATTENDED=1)"]
        U0[Init] --> U1[Plan] --> U2[Dev] --> U3[Review] --> U4[Commit<br/>PR request] --> UR[Runner verifies<br/>and opens a draft PR]
    end
```

## Review Architecture (Phase 3)

```mermaid
graph TD
    DIFF["Code Diff"]

    DIFF --> R1["Fable (Claude Code) / Opus (Copilot)<br/>Security + Architecture"]
    DIFF --> GPT["GPT-5.4<br/>Quality + Edge Cases<br/>(Copilot CLI only)"]
    DIFF --> SON["Sonnet<br/>Correctness + Style"]

    R1 --> TRIAGE["Fable Triage<br/>(Opus on Copilot CLI)"]
    GPT --> TRIAGE
    SON --> TRIAGE

    TRIAGE -->|PASS| P4["Phase 4: Commit"]
    TRIAGE -->|FIX_REQUIRED| P2["Phase 2: Dev (retry ≤3x)"]

    style TRIAGE fill:#ffd,stroke:#333
    style P3 fill:#fdd,stroke:#333
    style P5 fill:#dfd,stroke:#333
```

## Figma SubPhase Integration (Phase 2)

When a task is classified `component`, Phase 2 dispatches to the marketplace component plugin (`ai-<platform>-toolkit`) via the Skill tool. Component skills are not bundled in this repo; the subphases below describe the flow the plugin skill runs internally:

```mermaid
graph TD
    P2["Phase 2: Dev"]

    P2 -->|figmaConfigPath set| FIGMA
    P2 -->|default| TDD["Standard TDD<br/>RED → GREEN → REFACTOR"]

    subgraph FIGMA ["Figma Pipeline (17 SubPhases)"]
        direction TB
        S0["3.0 Init"] --> S1["3.1 Gather"]
        S1 --> S2A["3.2A TestingIDs"]
        S1 --> S2B["3.2B Localization"]
        S1 --> S2C["3.2C Accessibility"]
        S1 --> S2D["3.2D Analytics"]
        S2A --> S3["3.3 Token Mapping"]
        S2B --> S3
        S2C --> S3
        S2D --> S3
        S3 --> S4A["3.4A Config"]
        S4A --> S4B["3.4B View"]
        S4B --> S4C["3.4C Docs"]
        S4C --> S4D["3.4D Preview"]
        S4D --> S4E["3.4E Modifiers"]
        S4E --> S4F["3.4F Wiki"]
        S4F --> S5A["3.5A ViewInspector"]
        S5A --> S5B["3.5B Snapshot"]
        S5B --> S5C["3.5C Unit"]
        S5C --> S6["3.6 CodeConnect"]
    end

    style P3 fill:#ffd,stroke:#333
    style TDD fill:#dfd,stroke:#333
```

## Component Architecture

```mermaid
graph TB
    subgraph "CLI Layer"
        IDX[index.js<br/>Command router]
        INS[install.js<br/>Zero-dep installer]
    end

    subgraph "Pipeline Specs"
        CMD[commands/<br/>64 command files]
        AGT[agents/<br/>10 agent personas]
        RUL[rules/<br/>13 domain rules]
        PHS[multi-agent-refs/phases/<br/>phase specs + contracts]
        CMP[skills/shared/core/<br/>orchestration skills<br/>incl. compliance]
        EXT["skills/shared/external/<br/>151 curated skills<br/>(authoring source for the<br/>multi-agent-plugins marketplace)"]
    end

    subgraph "Quality Gates"
        SCH[schemas/<br/>JSON schemas + validated data]
        EVL[eval/triage/<br/>11 regression fixtures]
        SMK[scripts/smoke-*<br/>100+ smoke suites]
    end

    IDX --> INS
    INS -->|copies to ~/.claude/| CMD
    INS -->|copies to ~/.claude/| AGT
    INS -->|copies to ~/.claude/| RUL
    CMD --> PHS
    SCH --> EVL
    SCH --> SMK
```

## Data Flow

```
User Input → Phase 0 (Init)
                ↓
            agent-state.json (created)
                ↓
            Phase 1 (Plan: analysis + breakdown + approval gate)
                ↓
            Phase 2 (Dev) ←──────── retry loop (max 3x)
                ↓                        ↑
            Verify exit gate             │
            build · lint · tests · secrets
                ↓ .build.log + .test.log │
            Phase 3 (Review + user test) ┘ (if fix needed)
                ↓
            Phase 4 (Commit → push → PR)
                ↓
            Phase 5 REPORT (Jira → Wiki+Figma → Confluence → Log → Knowledge)
                ↓
            agent-log.md + agent-state.json (final)
```

## Unattended Autopilot (continuous mode)

```mermaid
graph TD
    TICK["launchd tick<br/>autopilot-runner.mjs"]
    ARM["Arm: cost ceiling · circuit breaker ·<br/>credential probe · parallel cap"]
    TAKE["Take the head of the queue<br/>(one run per repo)"]
    RUN["claude --bg child in a worktree<br/>MULTI_AGENT_UNATTENDED=1 · agent-guard fail-closed"]
    GATES["Gate ledger: symbol existence · open questions ·<br/>plan critique · spec consistency · evidence ·<br/>test strength · citations · review decision · plan coverage"]
    PARK{"Parked on maturity<br/>or open questions?"}
    RESEARCH["/multi-agent:research --autonomous<br/>research-gate.mjs decides"]
    REQ["Phase 4: commit + pr-request.json<br/>(no push from the session)"]
    PUB["autopilot-publish.mjs: re-run build + tests,<br/>re-check ledger, secrets, outbound gate"]
    PR["Push from a clean staging repo<br/>gh pr create --draft"]
    HUMAN["A person reviews and merges"]
    VF["verification-failed<br/>(verdict on disk)"]

    TICK --> ARM --> TAKE --> RUN
    RUN --> PARK
    PARK -->|yes| RESEARCH
    RESEARCH -->|proceed| RUN
    RESEARCH -->|gaps left| WAIT["Parked for a person"]
    PARK -->|no| GATES --> REQ --> PUB
    PUB -->|pass| PR --> HUMAN
    PUB -->|fail| VF
```

The session can build, test and commit inside its worktree; everything that
leaves the machine goes through the runner, after the runner checked it again
outside the session. With the variable unset none of this runs, and an attended
run behaves as before. Detail:
[`unattended-contract.md`](../pipeline/multi-agent-refs/unattended-contract.md),
[`unattended-security.md`](../pipeline/multi-agent-refs/features/unattended-security.md),
[`unattended-gates.md`](../pipeline/multi-agent-refs/features/unattended-gates.md),
[`autopilot-operations.md`](../pipeline/multi-agent-refs/features/autopilot-operations.md).

## Ecosystem Sync Targets

`/multi-agent:sync` walks **six** targets: Copilot CLI, Codex CLI, the pipeline
repo and the website, plus the two independently shipped repos
(`multi-agent-plugins`, `multi-agent-toolkit-mcp`):

```mermaid
graph TD
    CC["Claude Code<br/>(source of truth)"]
    COP["Copilot CLI<br/>(instructions + 64 sub-command skills)"]
    COD["Codex CLI<br/>(1 router skill + 64 refs)"]
    REPO["Pipeline Repo<br/>(npm package)"]
    WEB["Website"]
    PLUGREPO["multi-agent-plugins<br/>(6 plugins, own repo)"]
    DTK["multi-agent-toolkit-mcp<br/>(own repo, own release cadence)"]

    CC -->|copy + reformat| COP
    CC -->|transform via install.js --codex| COD
    CC -->|genericize| REPO
    CC -->|version + features| WEB
    REPO -->|build-stack-plugins.mjs| PLUGREPO
    DTK -.->|sync only detects + ships, never authors| CC

    REPO -->|npm publish| NPM["npm registry (public)"]
    WEB -->|auto-deploy| VERCEL["Vercel"]
    PLUGREPO -->|git push| MKT["Claude marketplace"]
    DTK -->|npm publish| NPM2["npm registry (public)"]
```

Full detail on how these three repos compose at install time and at run time -
including the Phase 2 → plugin dispatch contract and the Phase 3 → multi-agent-toolkit MCP
contract - lives in [`docs/ecosystem.md`](./ecosystem.md).