Mapa anatômico do Builder (atual orchestrator/) preparando o refactor para nomenclatura Harry/Harrison no Estágio 4. Documenta: fluxo de execução, hierarquia de agents, sistema cascade, APIs/schemas, e mapeamento atual → futuro.

🎯 Visão geral em 30 segundos

O Builder hoje é um orchestrator que recebe um README de projeto, decompõe em tasks, cascata modelos LLM por task_type, valida output e escreve arquivos com defesa em camadas. Tudo em orchestrator/ (TypeScript via tsx).

No Estágio 4 (próximo), Builder vira Harrison (chief of staff), com crew nomeada estilo Peaky Blinders.

🏗️ Fluxo do orchestrator (estado atual)

┌──────────────────────────────────────────────────────────────────┐
│  ENTRADA                                                          │
│  ─────────                                                        │
│  • README.md do projeto (ex: luiz-llm)                           │
│  • Stack definida (Next.js + Fastify + Supabase + Prisma)        │
│  • CLI flags (--resume, --max-tasks, BUILDER_USE_SPAWN=1)        │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  index.ts — LOOP PRINCIPAL                                        │
│  ────────────────────────                                         │
│  1. Carrega state.json (.builder/)                               │
│  2. Renderiza painel ASCII (epic/task/progress)                  │
│  3. Para cada task pending: chama task-engine.runTask()          │
│  4. Atualiza state.json após cada task                           │
│  5. Exit: 0 se done>0, 1 se falha total (Bug 36)                 │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  task-engine.ts — runTask()                                       │
│  ──────────────────────────                                       │
│  0. detectInstability() (Bug 42) — pause panel se 'critical'    │
│  1. context-builder monta contexto (3k tokens)                   │
│  2. SPEC + PLAN: cascade chama LLM (gera spec.md + plan.md)     │
│  3. output_files expandido (Bug 19 fix: 4 → N arquivos)         │
│  4. EXECUTE: cascade chama LLM (gera código)                    │
│  5. STEWARDSHIP: validateStructure() — checa qualidade          │
│     ↓ se issues:                                                  │
│     6. RETRY com modelo escalado (3 tentativas)                  │
│         ↓ se ainda falha:                                        │
│         7. needs_review ou blocked                               │
│  8. file-writer.ts grava arquivos (Bug 28: defesa 3 camadas)    │
│  9. Marca task completed                                          │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  SAÍDA                                                            │
│  ───────                                                          │
│  • Arquivos em apps/api/, apps/web/, packages/                   │
│  • docs/specs/{TASK_ID}-spec.md                                  │
│  • docs/plans/{TASK_ID}-plan.md                                  │
│  • state.json atualizado                                          │
│  • quota-status.json (Bug 42)                                    │
│  • build-*.log                                                    │
└──────────────────────────────────────────────────────────────────┘

👥 Hierarquia de Agents (estado atual → visão Harry)

Hoje — `AGENT_RULES` em `orchestrator/agents/index.ts`

Agents são prompts especializados (não classes). Cada um define regras para o LLM agir como aquele especialista. Existem 6+ agents ativos:

Agent atual	Função	Cascade preferida	→ Codinome Harry
`frontend`	Componentes React + shadcn/ui	gemini-flash → gpt5-mini → gpt5-cli → sonnet	Nova
`backend`	Fastify routes + services	gpt5-cli → sonnet → gpt5-mini → opus	Forge
`security`	OWASP, RBAC, RLS, audit log	opus → gpt5-thinking → sonnet → gpt5-cli	Sentinel
`testing`	Vitest unit + Playwright e2e	gemini-flash → gpt5-mini → gpt5-cli → sonnet	Echo
`storyboard`	Atomic Design, Storybook, design tokens	(compartilha frontend)	Nova (especialização)
`deploy`	Docker, GitHub Actions, CI/CD	gpt5-cli → sonnet → gpt5-mini → opus	Switch

Visão futura (Estágio 4) — Crew Harry completa

                  ┌─────────────────────────────┐
                  │    🎩 HARRISON              │
                  │    Chief of Staff (boss)    │
                  │    Coordena, decide, fala   │
                  │    com Bruno                │
                  └──────────────┬──────────────┘
                                 │
      ┌──────────────┬───────────┼───────────┬──────────────┐
      │              │           │           │              │
      ▼              ▼           ▼           ▼              ▼
┌─────────┐    ┌─────────┐  ┌─────────┐ ┌─────────┐  ┌─────────┐
│ ATLAS   │    │ FORGE   │  │  NOVA   │ │ LEDGER  │  │SENTINEL │
│Architect│    │Backend  │  │Frontend │ │Database │  │Security │
└─────────┘    └─────────┘  └─────────┘ └─────────┘  └─────────┘
      │              │           │           │              │
      └──────────────┴───────────┼───────────┴──────────────┘
                                 │
            ┌────────────┬───────┼───────┬────────────┐
            │            │       │       │            │
            ▼            ▼       ▼       ▼            ▼
       ┌────────┐  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
       │  ECHO  │  │ GRAVES │ │ QUILL  │ │ SWITCH │ │  ???   │
       │ QA/    │  │Auditor │ │ Docs   │ │ Deploy │ │Future  │
       │Testing │  │  novo  │ │        │ │ DevOps │ │Specialist│
       └────────┘  └────────┘ └────────┘ └────────┘ └────────┘

Mapeamento detalhado

Codinome	Especialidade	Substitui agent atual	Nasce novo?
Harrison	Chief of staff, coordena crew, fala com Bruno	(orchestrator core)	renomeação
Atlas	Arquitetura, ADRs, decisões técnicas	`architect`	renomeação
Forge	Backend services, APIs, business logic	`backend`	renomeação
Nova	Frontend, componentes, design system	`frontend` • `storyboard`	renomeação + merge
Ledger	Database schemas, migrations, queries	`database_schema`	renomeação
Sentinel	Security audit, OWASP, RBAC, RLS	`security`	renomeação
Echo	QA, unit/integration/e2e tests	`testing`	renomeação
Graves	Auditor de código gerado, code review final	(não existe hoje)	NOVO
Quill	Documentação técnica, READMEs, ADRs	(parte de architect)	extração
Switch	DevOps, deploy, CI/CD, infra	`deploy`	renomeação

⚡ Sistema Cascade — como Harrison decide o modelo

Cascade v3.2 atual (`orchestrator/llm-router.ts`)

Princípio: cost-first com 4 níveis garantidos por rota. Sobe na cascade quando modelo anterior falha (rate limit, erro, ou stewardship reject).

Categorias de criticidade

ALTA CRITICIDADE (12 rotas)
├─ task-generator, architect, spec-writer, planner
├─ security, auth, code_review, bug_fix
└─ frontend_setup, backend_setup, database_schema, devops
   Cascade atual (Bug 51, 17/04): opus-cli / gpt5-thinking-cli / gpt5-cli / sonnet-cli
   (gemini-pro REMOVIDO — 50 RPD free = inviável)

MÉDIA CRITICIDADE (9 rotas)
├─ frontend_page, frontend_component
├─ backend_api, backend_service
├─ database_query, testing_integration
└─ testing_e2e, refactor, documentation
   Cascade atual (Bug 51, 17/04): gemini-flash-cli → gpt5-mini-cli → gpt5-cli → sonnet-cli

BAIXA CRITICIDADE (5 rotas)
├─ ui_microchange, testing_unit
├─ dependency_update, config_tweak
└─ comment_fix
   Cascade atual: gemini-flash-cli → groq-llama-70b → gpt5-mini-cli → sonnet-cli