# Architecture

## 8-Phase Pipeline Flow (0-7)

```mermaid
graph TD
    INPUT["🎯 Input<br/>(Issue # / Jira URL / free text)"]
    P0["Phase 0: Init<br/>Project detect, worktree, branch, identity"]
    P1["Phase 1: Analysis<br/>Codebase scan (parallel Explore agents)"]
    P2["Phase 2: Planning<br/>Task breakdown, architecture review"]
    P3["Phase 3: Dev<br/>TDD: RED → GREEN → REFACTOR"]
    P4["Phase 4: Review<br/>Parallel + Fable triage<br/>(Claude: 2-model · Copilot: 3-model)"]
    P5["Phase 5: Test<br/>Optional manual testing"]
    P6["Phase 6: Commit<br/>Git commit, PR creation"]
    P7["Phase 7: Report<br/>Jira · Wiki+Figma · Confluence · Log · Knowledge"]

    INPUT --> P0
    P0 --> P1
    P1 --> P2
    P2 --> P3
    P3 --> P4
    P4 -->|approved| P5
    P4 -->|fix needed| P3
    P5 --> P6
    P6 --> P7

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

## Operating Modes

```mermaid
graph LR
    subgraph Normal ["Normal (Full 8-phase)"]
        N0[Init] --> N1[Analysis] --> N2[Planning] --> N3[Dev] --> N4[Review] --> N5[Test] --> N6[Commit] --> N7[Report]
    end

    subgraph Dev ["Short depth (picker, Opus)"]
        D0[Init] --> D3[Dev<br/>Opus] --> D4[Review] --> D5[Test] --> D6[Commit] --> D7[Report]
    end

    subgraph Autopilot ["Autopilot (skip confirmations)"]
        A0[Init] --> A1[Analysis] --> A2[Planning] --> A3[Dev] --> A4[Review] --> A6[Commit] --> A7[Report]
    end
```

## Review Architecture (Phase 4)

```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| P5["Phase 5: Test"]
    TRIAGE -->|FIX_REQUIRED| P3["Phase 3: 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 3)

When a task is classified `component`, Phase 3 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
    P3["Phase 3: Dev"]

    P3 -->|figmaConfigPath set| FIGMA
    P3 -->|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/>53 command files]
        AGT[agents/<br/>8 agent personas]
        RUL[rules/<br/>12 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/>19 JSON schemas]
        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-2 (Analysis + Planning)
                ↓
            Phase 3 (Dev) ←──── retry loop (max 3x)
                ↓                    ↑
            Phase 4 (Review) ────────┘ (if fix needed)
                ↓
            Phase 5-6 (Test + Commit)
                ↓
            Phase 7 REPORT (Jira → Wiki+Figma → Confluence → Log → Knowledge)
                ↓
            agent-log.md + agent-state.json (final)
```

## Ecosystem Sync Targets

`/multi-agent:sync` actually walks **five** targets, not the three shown in earlier
revisions of this diagram - Codex CLI and the two independently-shipped repos
(`multi-agent-plugins`, `multi-agent-toolkit-mcp`) are real sync targets too:

```mermaid
graph TD
    CC["Claude Code<br/>(source of truth)"]
    COP["Copilot CLI<br/>(instructions + 51 skills)"]
    COD["Codex CLI<br/>(1 router skill + 53 refs)"]
    REPO["Pipeline Repo<br/>(npm package)"]
    WEB["Website"]
    PLUGREPO["multi-agent-plugins<br/>(5 stack 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 3 → plugin dispatch contract and the Phase 5 → multi-agent-toolkit MCP
contract - lives in [`docs/ecosystem.md`](./ecosystem.md).