jdi-cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,209 @@
+# JDI — Agents
+
+5 agents core (shipped) + 2 specialists per-project (gerados).
+
+## Core (em `core/agents/`)
+
+### `jdi-researcher` (Opus)
+
+**Funcao:** Discover do projeto antes do roadmap.
+
+**Spawned por:** `/jdi-new`
+
+**Filosofia:** 1 agent unico em vez de varios researchers paralelos. Mais barato, suficiente pra projetos pequenos/medios.
+
+**Inputs:**
+- Argumento livre: ideia do projeto
+- Read em diretorio atual
+
+**Outputs:**
+- `.jdi/PROJECT.md` (visao + stack + code-design LOCKED)
+- `.jdi/ROADMAP.md` (1 phase por feature MVP)
+- `.jdi/STATE.md`
+- `.jdi/DECISIONS.md` (com D-1)
+- `.gitattributes` (normaliza line endings)
+
+**Permissoes:** Read, Write, WebSearch (max 2 lookups via ctx7), AskUserQuestion.
+
+### `jdi-bootstrap` (Sonnet)
+
+**Funcao:** Wrapper que dispara `jdi-architect` em modo specialist pra gerar doer + reviewer per-project.
+
+**Spawned por:** `/jdi-bootstrap`
+
+**Inputs:**
+- Read em `.jdi/PROJECT.md`
+
+**Outputs:**
+- `.jdi/agents/jdi-doer-{slug}.md`
+- `.jdi/agents/jdi-reviewer-{slug}.md`
+- `.jdi/specialists.md` + `.jdi/reviewers.md` (routing)
+- `.jdi/registry.md` (R-1 audit trail)
+- `.jdi/STATE.md` atualizado (`specialists_ready: true`)
+
+**Permissoes:** Read, Write, Edit, Bash, AskUserQuestion, Agent (spawn architect).
+
+### `jdi-asker` (Sonnet)
+
+**Funcao:** Loop adaptativo de perguntas pra capturar decisoes locked.
+
+**Spawned por:** `/jdi-discuss <N>`
+
+**Inputs:**
+- `phase_number`
+- Read em PROJECT.md, ROADMAP.md, DECISIONS.md, ate 2 CONTEXT.md anteriores
+
+**Outputs:**
+- `.jdi/phases/{NN-slug}/CONTEXT.md`
+- `.jdi/DECISIONS.md` (append D-XX)
+- `.jdi/todos.md` (se scope creep)
+
+**Regras:**
+- Max 5 perguntas por sessao
+- Max 5 D-XX por sessao
+- Identifica gray areas especificas (nao categorias genericas)
+- Para quando user diz "chega" / "go" / 5 perguntas
+
+**Permissoes:** Read, Write, AskUserQuestion.
+
+### `jdi-planner` (Opus)
+
+**Funcao:** Decompoe phase em tasks com waves de paralelismo.
+
+**Spawned por:** `/jdi-plan <N>`
+
+**Inputs:**
+- `phase_number`
+- Read em PROJECT.md, ROADMAP.md, DECISIONS.md, CONTEXT.md, doer specialist
+- Read no codigo existente (mapeamento de files_modified)
+
+**Outputs:**
+- `.jdi/phases/{NN-slug}/PLAN.md`
+
+**Regras:**
+- Max 8 tasks por phase (split se passar)
+- Cada task tem: `files_modified`, `acceptance` mensuravel, `dependencies`, `test`
+- Wave grouping: paralelo dentro, sequencial entre
+- Files_modified disjoint dentro da mesma wave (overlap = sequencial automatico)
+- Self-check antes de salvar (checklist 5 itens)
+
+**Permissoes:** Read, Write, AskUserQuestion (so se ambiguo).
+
+### `jdi-architect` (Opus)
+
+**Funcao:** Meta-agent. 2 modos.
+
+**Modo `create` (spawned por `/jdi-create`):**
+- Cria agent ou skill GENERICO em `core/agents/` ou `core/skills/`
+- 8 perguntas pra classificar (agent / skill / composite)
+- Validacao com user (approve / edit / cancel)
+- Build + install pro runtime
+
+**Modo `specialist` (spawned por `/jdi-bootstrap`):**
+- Cria doer + reviewer PER-PROJECT em `.jdi/agents/`
+- 6 perguntas focadas (test framework, build/test commands, coverage min, lint, conventions)
+- Substitui placeholders nos templates `core/templates/{doer,reviewer}-specialist.md`
+- Mapeia bash<->PowerShell pros gates do reviewer
+
+**Inputs:**
+- Modo `create`: argumento livre opcional
+- Modo `specialist`: `.jdi/PROJECT.md` obrigatorio
+- Read em todos os files de routing
+
+**Outputs:**
+- Modo `create`: `core/agents/jdi-{nome}.md` ou `core/skills/{nome}/`
+- Modo `specialist`: `.jdi/agents/jdi-{doer,reviewer}-{slug}.md`
+- Em ambos: update de routing + audit em `.jdi/registry.md`
+
+**Permissoes:** Read, Write, Edit, Bash, AskUserQuestion.
+
+## Per-project (em `.jdi/agents/`)
+
+### `jdi-doer-{slug}` (Sonnet)
+
+**Funcao:** Executor que JA SABE stack/code-design/conventions do projeto.
+
+**Spawned por:** `/jdi-do <N>`
+
+**Filosofia:** 1 specialist focado que ja sabe a stack, em vez de executor + code-fixer + doc-writer separados.
+
+**Inputs:**
+- `phase_number`
+- Read em PROJECT.md, DECISIONS.md, CONTEXT.md, PLAN.md
+- Write nos paths em `files_modified` do PLAN
+
+**Outputs:**
+- Codigo modificado, commitado atomicamente
+- `.jdi/phases/{NN}/PLAN.md` atualizado (status das tasks)
+- `.jdi/phases/{NN}/SUMMARY.md` final
+
+**Regras:**
+- Sem `--no-verify` em commits (hooks rodam)
+- Sem skip de testes — task so completa se test passou
+- Atomic commit por task
+- Conventional Commits, scope = phase slug
+- Max 3 tentativas de correcao por task antes de marcar `blocked`
+
+**Permissoes:** Read, Write, Edit, Bash. Sem Web (deve ja saber stack).
+
+### `jdi-reviewer-{slug}` (Sonnet)
+
+**Funcao:** Roda gates de qualidade definidos pra stack.
+
+**Spawned por:** `/jdi-verify <N>`
+
+**Filosofia:** 1 reviewer focado por stack, em vez de code-reviewer + security-auditor + integration-checker + verifier separados.
+
+**Inputs:**
+- `phase_number`
+- Read em PROJECT.md, PLAN.md, SUMMARY.md, codigo modificado
+
+**Outputs:**
+- `.jdi/phases/{NN}/REVIEW.md` com veredicto
+
+**Gates:**
+1. Build
+2. Tests
+3. Coverage (>= threshold do PROJECT.md, default 80%)
+4. Lint/Format
+5. Security/Perf rules da stack (sem secrets, sem TODO sem issue, sem localStorage tokens, etc)
+6. Plan consistency (commits batem com files_modified)
+
+**Veredictos:**
+- APPROVED — todos PASS
+- APPROVED_WITH_WARNINGS — sem blockers, com warns
+- BLOCKED — gate 1-3 falhou OU gate 5 critical
+
+**Permissoes:** Read-only por design. Read + Bash (so pra rodar comandos de gate). **Sem Write, sem Edit.**
+
+## Resumo visual
+
+```
+core/agents/                  <- 5 agents shipped
+  jdi-researcher    Opus     pre-roadmap discovery
+  jdi-bootstrap     Sonnet   wrapper -> spawn architect specialist
+  jdi-asker         Sonnet   loop perguntas
+  jdi-planner       Opus     decompose phase
+  jdi-architect     Opus     meta (2 modos)
+
+.jdi/agents/                  <- per-project, gerados pelo /jdi-bootstrap
+  jdi-doer-{slug}    Sonnet   executor especialista
+  jdi-reviewer-{slug} Sonnet  reviewer especialista (read-only)
+```
+
+## Modelos por runtime
+
+Cada agent declara `runtime_overrides:` no frontmatter. Build script gera frontmatter especifico:
+
+| Runtime | Field | Exemplo (researcher) |
+|---|---|---|
+| Claude Code | `model:` | `opus` |
+| GitHub Copilot | `model:` | `gpt-5` |
+| Antigravity | `triggers:` | discovery automatica via prefixo `jdi-` |
+| OpenCode | `mode:`, `model:`, `temperature:`, `permission:` | `subagent`, `anthropic/claude-sonnet-4-20250514`, `0.2`, edit/bash/write rules |
+
+## Estendendo
+
+Pra criar agent novo no core: rode `/jdi-create` dentro do repo JDI. Architect modo create faz tudo.
+
+Pra criar specialists per-project diferentes (ex: multi-stack): atualmente `/jdi-bootstrap` cria 1 doer agregado. Multi-doer eh feature pendente — workaround: edita `.jdi/agents/` manual ou rode bootstrap multiplas vezes com slugs diferentes.

package/ARCHITECTURE.md

@@ -0,0 +1,210 @@
+# JDI — Architecture
+
+## Principios
+
+1. **Fresh context per agent** — cada spawn tem janela limpa. Anti context-rot
+2. **Thin orchestrator** — comando carrega contexto, spawn agente, roteia. Nada mais
+3. **File-based state** — `.jdi/` em md/json. Sem DB, sem servidor
+4. **Decisao locked = imutavel** — D-XX nunca volta
+5. **1 task = 1 commit atomico**
+6. **Plano e prompt** — PLAN.md ja eh o input do executor
+7. **Per-project specialists** — doer/reviewer customizados por projeto, nao genericos
+8. **Wave-based parallelism** — paralelo dentro da wave, sequencial entre waves
+9. **Security > Perf > Best Practices** — ordem fixa quando conflita
+
+## Estrutura em camadas
+
+```
+core/                    <- shipped, generators (lives in JDI repo)
+  agents/                <- 5 agents core
+    jdi-researcher.md
+    jdi-bootstrap.md
+    jdi-asker.md
+    jdi-planner.md
+    jdi-architect.md
+  commands/              <- 8 commands
+    jdi-new.md, jdi-bootstrap.md, jdi-discuss.md, jdi-plan.md,
+    jdi-do.md, jdi-verify.md, jdi-ship.md, jdi-create.md
+  templates/
+    agent.md, skill.md
+    doer-specialist.md       <- usado pelo architect modo specialist
+    reviewer-specialist.md   <- idem
+
+.jdi/                    <- per-project state (gerado por /jdi-new)
+  PROJECT.md, ROADMAP.md, DECISIONS.md, STATE.md
+  specialists.md, reviewers.md, registry.md
+  agents/                <- per-project specialists (gerado por /jdi-bootstrap)
+    jdi-doer-{slug}.md
+    jdi-reviewer-{slug}.md
+  phases/{NN-slug}/
+    CONTEXT.md, PLAN.md, SUMMARY.md, REVIEW.md
+```
+
+## Ciclo de vida
+
+```
+/jdi-new "<descricao>"   -> PROJECT.md + ROADMAP.md + STATE.md + DECISIONS.md
+/jdi-bootstrap           -> .jdi/agents/jdi-doer-{slug} + jdi-reviewer-{slug}
+/jdi-discuss N           -> phases/NN/CONTEXT.md
+/jdi-plan N              -> phases/NN/PLAN.md (tasks + waves)
+/jdi-do N                -> commits atomicos + phases/NN/SUMMARY.md
+/jdi-verify N            -> phases/NN/REVIEW.md (gates)
+/jdi-ship N              -> ROADMAP advance + tag (opcional) + STATE atualizado
+```
+
+Gates entre etapas:
+
+| De | Para | Gate |
+|---|---|---|
+| /jdi-new | /jdi-bootstrap | PROJECT.md + ROADMAP.md exist |
+| /jdi-bootstrap | /jdi-discuss | .jdi/agents/jdi-doer-* + jdi-reviewer-* exist |
+| /jdi-discuss | /jdi-plan | CONTEXT.md exist + decisoes locked claras |
+| /jdi-plan | /jdi-do | PLAN.md valido (tasks + acceptance + files_modified) |
+| /jdi-do | /jdi-verify | SUMMARY.md exist (todas tasks concluidas ou marcadas blocked) |
+| /jdi-verify | /jdi-ship | REVIEW.md verdict != BLOCKED |
+
+## Permissoes (least privilege)
+
+| Agente | Read | Write | Edit | Bash | Web |
+|---|:---:|:---:|:---:|:---:|:---:|
+| jdi-researcher | x | x | - | - | x |
+| jdi-bootstrap | x | x | x | x | - |
+| jdi-asker | x | x | - | - | - |
+| jdi-planner | x | x | - | - | - |
+| jdi-architect | x | x | x | x | - |
+| jdi-doer-{slug} | x | x | x | x | - |
+| jdi-reviewer-{slug} | x | - | - | x | - |
+
+Reviewer eh **read-only** por design. So roda gates, nao corrige.
+
+## Agents core x specialists per-project
+
+**Core (shipped, em `core/agents/`):**
+- `jdi-researcher` — discover do projeto, gera PROJECT.md + ROADMAP.md
+- `jdi-bootstrap` — wrapper que dispara architect modo specialist
+- `jdi-asker` — loop adaptativo de perguntas (CONTEXT.md)
+- `jdi-planner` — decompoe phase em tasks + waves
+- `jdi-architect` — meta. 2 modos: `create` (agents/skills no core/) ou `specialist` (doer/reviewer per-project)
+
+**Per-project (gerados, em `.jdi/agents/`):**
+- `jdi-doer-{slug}` — executor que JA SABE stack/conventions/code-design. Sem descoberta
+- `jdi-reviewer-{slug}` — gates customizados pra stack (build/test/coverage/lint/security)
+
+Specialist routing via `.jdi/specialists.md` e `.jdi/reviewers.md`.
+
+## Wave-based parallelism
+
+`/jdi-do N`:
+1. Le PLAN.md, agrupa tasks em waves (wave M = tasks que so dependem de wave M-1)
+2. Pra cada wave:
+   - Intra-wave overlap check (files_modified disjoint?)
+   - Se 2+ tasks paralelas E sem overlap E nao `--sequential`:
+     - Sequential dispatch — UM `Agent()` por message com `run_in_background: true`
+     - Aguarda wave inteira terminar antes da proxima
+   - Senao: executa sequencial, 1 doer por task
+3. Apos todas waves: doer escreve SUMMARY.md final
+
+Sequential dispatch evita race em `.git/config.lock` (problema bem documentado em git worktree).
+
+## Loop de perguntas (jdi-asker)
+
+Adaptativo. Regras:
+
+1. Le PROJECT.md, ROADMAP.md, DECISIONS.md
+2. Le ate 2 CONTEXT.md anteriores (max)
+3. Identifica 3-5 gray areas especificas da phase (nao categorias genericas)
+4. Pergunta uma por vez via AskUserQuestion
+5. Cada resposta vira D-XX em DECISIONS.md
+6. Para quando user diz "chega" / "go" / 5 perguntas atingidas
+7. Escreve CONTEXT.md com decisoes + canonical_refs
+
+## Loop de execucao (jdi-doer-{slug})
+
+Por task no PLAN.md:
+
+1. Le task (files_modified, acceptance, dependencies, test)
+2. Implementa codigo
+3. Roda test command (`{TEST_COMMAND}` definido no specialist)
+4. Se falha -> tenta corrigir 1 vez. Falha de novo -> marca `blocked`, segue
+5. Commit atomico: `feat({phase-slug}): {task summary}` (Conventional Commits)
+6. Append linha em SUMMARY.md
+7. Proxima task
+
+## Review pos-execucao (jdi-reviewer-{slug})
+
+`/jdi-verify N` dispara reviewer. 6 gates:
+1. Build
+2. Tests
+3. Coverage (>= threshold do PROJECT.md, default 80%)
+4. Lint/Format
+5. Security/Perf rules da stack
+6. Plan consistency (commits batem com files_modified)
+
+Veredicto: APPROVED / APPROVED_WITH_WARNINGS / BLOCKED. BLOCKED bloqueia /jdi-ship.
+
+## Read-depth scaling (token budget)
+
+Regra dura: **read-depth escala com distancia da phase atual**. Orchestrator e agentes nao leem corpo de phase qualquer — leem o necessario.
+
+| Distancia | Arquivo | Read permitido |
+|---|---|---|
+| `current_phase` | CONTEXT, PLAN, SUMMARY, REVIEW da phase | Corpo inteiro (ate budget de `config.json`) |
+| `current_phase - 1` | SUMMARY.md, REVIEW.md anterior | **Frontmatter + veredict apenas**. Nunca corpo. |
+| `<= current_phase - 2` | Phases antigas | **Nao ler.** Existencia via `ls`. Metadados via `head -10`. |
+
+**Excecoes documentadas:**
+- `/jdi-verify N` pode ler `PLAN.md` de phase `N-1` se task atual referencia `D-XX` daquela phase (rastreabilidade)
+- `/jdi-discuss N` (asker) le ate **2 CONTEXT.md anteriores** (regra ja vigente em `core/agents/jdi-asker.md`)
+- `jdi-researcher` le PROJECT/ROADMAP inteiros — sao curtos por design (PROJECT cap 80 linhas, ROADMAP eh sumario)
+
+**Por que:**
+- Phase 8 nao precisa de corpo de SUMMARY phase 1. Frontmatter ja contem `status` + `verdict`.
+- Context rot: pesquisa Anthropic/Chroma 2025 confirma — recall degrada com tokens, mesmo dentro do limite.
+- Cache hit aumenta: arquivos imutaveis (PROJECT, DECISIONS) viram prefix estavel.
+
+**Como aplicar (orchestrator):**
+- Antes de `Read` em arquivo de phase anterior: cheque distancia via STATE.md
+- Use `head -20` no lugar de `cat` quando so quer frontmatter
+- Phases archived (`.jdi/archive/`): tratar como phase `<= current - 2`. Nao ler corpo.
+- Pra arquivos grandes na phase atual, use `bin/lib/jdi-truncate.{sh,ps1}` antes de inline em prompt:
+  ```bash
+  bash bin/lib/jdi-truncate.sh .jdi/phases/01-x/PLAN.md 12000   # cap em chars
+  ```
+  Helper preserva frontmatter, headings, 1a linha de cada secao. Resto vira pointer.
+
+## Memoria
+
+| Arquivo | Lifespan | Conteudo |
+|---|---|---|
+| `PROJECT.md` | Vida do projeto | Visao, stack, code-design locked |
+| `ROADMAP.md` | Vida do projeto | Phases + status |
+| `DECISIONS.md` | Append-only | D-XX (decisoes locked) |
+| `STATE.md` | Sobrescreve | current_phase + next_step |
+| `specialists.md`, `reviewers.md` | Append-only | Routing per-project |
+| `registry.md` | Append-only | Audit trail dos specialists/agents criados |
+| `phases/{NN}/CONTEXT.md` | Vida da phase | Output do asker |
+| `phases/{NN}/PLAN.md` | Vida da phase | Output do planner |
+| `phases/{NN}/SUMMARY.md` | Vida da phase | Output do doer |
+| `phases/{NN}/REVIEW.md` | Vida da phase | Output do reviewer |
+
+Decisoes locked em DECISIONS.md, audit trail em registry.md.
+
+## Hooks
+
+`.githooks/pre-commit` e `post-commit` shipped como **no-op por padrao**. Doer/reviewer cobrem responsabilidades de docs/qualidade dentro do flow normal.
+
+User pode customizar `.githooks/` pra:
+- Lint rapido pre-commit
+- Notificacao Slack pos-commit
+- Etc.
+
+## Codigo nao spec-driven 100%
+
+JDI nao eh Spec-Driven Development puro. Spec ortodoxo exige spec antes de codigo, rastreabilidade ate teste, assinatura de stakeholders.
+
+JDI faz:
+- CONTEXT.md = spec lite. Decisao locked, nada mais
+- PLAN.md = task list com acceptance. Rastreabilidade via D-XX
+- Nada de stakeholder. So user
+
+Quando user precisa de spec formal -> usa ferramenta dedicada de governanca. JDI eh dev workflow, nao governanca.

package/COMMANDS.md

@@ -0,0 +1,241 @@
+# JDI — Commands
+
+9 comandos. 7 no loop principal + 1 ralph mode + 1 meta (`/jdi-create`).
+
+## Loop principal
+
+### `/jdi-new "<descricao>"`
+
+**Entry point.** Cria projeto JDI do zero.
+
+```
+/jdi-new "TODO app .NET 10 + React 19"
+```
+
+Faz:
+1. Validacao: `.jdi/` nao existe (ou `--reset`)
+2. Spawn `jdi-researcher`:
+   - 4 perguntas chave (visao, stack, code-design, MVP features)
+   - Research focado opcional via ctx7 (max 2 lookups)
+   - Gera `PROJECT.md` (visao + stack + code-design LOCKED)
+   - Gera `ROADMAP.md` (1 phase por feature do MVP)
+   - Gera `STATE.md` + `DECISIONS.md` (D-1: code design)
+   - Cria `.gitattributes` (normaliza CRLF)
+3. Commit inicial: `chore(jdi): initialize <project_name>`
+
+**Proximo:** `/jdi-bootstrap`
+
+### `/jdi-bootstrap`
+
+Cria specialists per-project (doer + reviewer).
+
+Faz:
+1. Le `.jdi/PROJECT.md`
+2. Spawn `jdi-architect` em modo `specialist`:
+   - 6 perguntas focadas (test framework, build/test commands, coverage min, lint, conventions)
+   - Gera `.jdi/agents/jdi-doer-{slug}.md` (de `core/templates/doer-specialist.md`)
+   - Gera `.jdi/agents/jdi-reviewer-{slug}.md` (de `core/templates/reviewer-specialist.md`)
+   - Atualiza `.jdi/specialists.md` + `.jdi/reviewers.md` + `.jdi/registry.md`
+3. Commit: `chore(jdi): bootstrap specialists for <project_name>`
+4. Atualiza STATE.md: `specialists_ready: true`
+
+**Proximo:** `/jdi-discuss 1`
+
+### `/jdi-discuss <N> [--auto]`
+
+Captura decisoes locked da phase.
+
+```
+/jdi-discuss 2
+/jdi-discuss 1 --auto    # asker decide tudo, sem perguntar
+```
+
+Faz:
+1. Validacao: phase existe em ROADMAP.md
+2. Spawn `jdi-asker`:
+   - Identifica 3-5 gray areas especificas da phase
+   - Pergunta uma por vez (max 5 D-XX por sessao)
+   - Captura cada resposta como D-XX em DECISIONS.md
+   - Scope creep -> `.jdi/todos.md`
+   - Escreve `.jdi/phases/{NN-slug}/CONTEXT.md`
+3. Commit: `docs({NN-slug}): capture phase context`
+
+**Proximo:** `/jdi-plan N`
+
+### `/jdi-plan <N> [--review]`
+
+Decompoe phase em tasks executaveis.
+
+```
+/jdi-plan 2
+/jdi-plan 2 --review     # mostra preview, pede approve
+```
+
+Faz:
+1. Validacao: CONTEXT.md existe
+2. Spawn `jdi-planner`:
+   - Le PROJECT.md + ROADMAP.md + DECISIONS.md + CONTEXT.md
+   - Decompoe em tasks (max 8) com `files_modified` + `acceptance` + `dependencies` + `test`
+   - Agrupa em waves (paralelo dentro, sequencial entre)
+   - Self-check (toda task tem files_modified? wave grouping respeita deps?)
+   - Escreve `.jdi/phases/{NN-slug}/PLAN.md`
+3. Commit: `docs({NN-slug}): generate plan ({M} tasks, {W} waves)`
+
+**Proximo:** `/jdi-do N`
+
+### `/jdi-do <N> [--sequential]`
+
+Executa tasks da phase via doer specialist do projeto.
+
+```
+/jdi-do 2
+/jdi-do 2 --sequential   # forca sequencial, mesmo se waves permitem paralelo
+```
+
+Faz:
+1. Validacao: PLAN.md existe + doer registrado em `.jdi/specialists.md`
+2. Resolve doer specialist (`jdi-doer-{slug}`)
+3. Le PLAN.md, identifica tasks pendentes, agrupa waves
+4. Pra cada wave:
+   - Intra-wave overlap check (files_modified disjoint?)
+   - Se paralelo: sequential dispatch (1 Agent por message com `run_in_background:true`)
+   - Se sequencial: 1 doer por task em sequencia
+5. Doer atualiza status no PLAN.md, commita atomico, escreve SUMMARY.md final
+6. Commit final do orchestrator: `chore(state): phase {N} executed`
+
+**Proximo:** `/jdi-verify N`
+
+### `/jdi-verify <N>`
+
+Roda gates de qualidade via reviewer specialist.
+
+Faz:
+1. Validacao: SUMMARY.md existe + reviewer registrado em `.jdi/reviewers.md`
+2. Resolve reviewer specialist (`jdi-reviewer-{slug}`)
+3. Spawn reviewer:
+   - Gate 1: Build
+   - Gate 2: Tests
+   - Gate 3: Coverage (>= threshold)
+   - Gate 4: Lint/Format
+   - Gate 5: Security/Perf rules da stack
+   - Gate 6: Plan consistency (commits batem com files_modified)
+4. Reviewer escreve `.jdi/phases/{NN-slug}/REVIEW.md` com veredicto:
+   - APPROVED — todos gates PASS
+   - APPROVED_WITH_WARNINGS — sem blockers, alguns warns
+   - BLOCKED — gate 1-3 falhou OU gate 5 critical
+5. Commit: `docs({NN-slug}): verify phase ({VERDICT})`
+
+**Proximo:** `/jdi-ship N` (se nao BLOCKED) — ou `/jdi-loop N` se quiser auto-fix loop
+
+### `/jdi-loop <N> [--max-iter=5] [--max-resets=3]`
+
+**Ralph loop mode.** Roda `/jdi-do` -> `/jdi-verify` em ciclo automatico ate veredicto APPROVED. Sem acao humana entre iter. Cap absoluto: 5 iter por round x 3 resets = 15 iter.
+
+```
+/jdi-loop 2
+/jdi-loop 2 --max-iter=3 --max-resets=2    # cap mais conservador
+```
+
+Faz:
+1. Validacao: PLAN.md + doer + reviewer registrados
+2. Inicializa `.jdi/phases/{NN-slug}/LOOP.md` (ou retoma se existe)
+3. Loop:
+   - Spawn doer (com last REVIEW.md findings + LOOP history como contexto)
+   - Spawn reviewer (read-only, escreve REVIEW.md)
+   - Hash dos blockers/warnings -> append em LOOP.md history
+   - Se veredicto APPROVED ou APPROVED_WITH_WARNINGS -> converged, exit
+   - Se finding hash igual ao iter anterior -> oscillation detected, AskUserQuestion
+   - Se iter >= max_iter -> AskUserQuestion (continuar/abortar/ajustar)
+4. Human gate options:
+   - `Continuar` -> reset counter, novo round (total_resets++)
+   - `Abortar` -> status=escalated, exit limpo
+   - `Ajustar plano` -> status=paused, exit, user edita PLAN/CONTEXT, re-roda /jdi-loop
+5. Hard cap: total_resets >= max_resets -> status=killed, kill switch absoluto
+6. Cada iter = doer commit atomico + reviewer commit (audit trail granular em git)
+
+**Generator/Judge separation:** doer escreve, reviewer le (read-only). Invariante Ralph.
+
+**Quando usar:**
+- Phase com tests automaticos confiaveis
+- Tasks mecanicas (refactor, test coverage, batch fixes)
+- Quer "fire and forget" com cap controlado
+
+**Quando NAO usar:**
+- Tasks que precisam decisao arquitetural humana
+- Phase com gates subjetivos
+- Specs vagas (vai oscilar)
+
+**Proximo:** `/jdi-ship N` (se converged) ou revisao humana (se killed/escalated/paused)
+
+### `/jdi-ship <N>`
+
+Finaliza phase, avanca pra proxima.
+
+Faz:
+1. Validacao: REVIEW.md existe + veredicto != BLOCKED
+2. Se WITH_WARNINGS: pergunta "ship mesmo assim?"
+3. Atualiza ROADMAP.md (phase {N}: status `done`, phase {N+1}: status `ready`)
+4. Atualiza STATE.md (current_phase: {N+1})
+5. Commit: `feat({NN-slug}): ship phase {N} ({VERDICT})`
+6. Tag opcional: `phase-{N}-{slug}` (se PROJECT.md tem `tag_phases: true`)
+
+**Proximo:** `/jdi-discuss <N+1>` (ou done)
+
+## Comando meta
+
+### `/jdi-create [descricao]`
+
+Cria novo agent ou skill GENERICO no `core/`. So roda dentro do repo JDI fonte.
+
+```
+/jdi-create "specialist pra Rust com cargo + clippy"
+/jdi-create "skill com convencoes EF Core 9"
+/jdi-create
+```
+
+Faz:
+1. Validacao: esta no repo JDI (`core/` existe)
+2. Spawn `jdi-architect` modo `create`:
+   - 8 perguntas (problema, trigger, input, output, reuso, decision-loop, custo, tools)
+   - Classificacao automatica (agent / skill / composite)
+   - Validacao com user (approve / edit / cancel)
+   - Geracao de files em `core/agents/` ou `core/skills/`
+   - Update de routing
+3. Build + install pro runtime ativo
+4. Commit + audit em `.jdi/registry.md`
+
+**NAO usado em projetos consumindo JDI.** So pra contributors estendendo o core.
+
+## Resumo visual
+
+```
+/jdi-new        --> .jdi/{PROJECT,ROADMAP,STATE,DECISIONS}.md + .gitattributes
+/jdi-bootstrap  --> .jdi/agents/{jdi-doer-{slug},jdi-reviewer-{slug}}.md + routing
+/jdi-discuss N  --> .jdi/phases/{NN}/CONTEXT.md
+/jdi-plan N     --> .jdi/phases/{NN}/PLAN.md
+/jdi-do N       --> commits atomicos + .jdi/phases/{NN}/SUMMARY.md
+/jdi-verify N   --> .jdi/phases/{NN}/REVIEW.md
+/jdi-loop N     --> ralph mode: do<->verify auto + .jdi/phases/{NN}/LOOP.md
+/jdi-ship N     --> ROADMAP advance + tag (opcional)
+
+/jdi-create     --> [internal] core/agents/* ou core/skills/* (so no repo JDI)
+```
+
+## Flags globais
+
+- `--auto` (em `/jdi-discuss`): asker decide tudo, sem pergunta
+- `--review` (em `/jdi-plan`): mostra preview do PLAN, pede approve
+- `--sequential` (em `/jdi-do`): forca execucao sequencial mesmo se waves permitem paralelo
+- `--max-iter=N` (em `/jdi-loop`): max iter por round antes de human gate (default 5)
+- `--max-resets=N` (em `/jdi-loop`): max rounds de reset antes do kill switch (default 3)
+- `--reset` (em `/jdi-new`): apaga `.jdi/` antes de iniciar (CUIDADO)
+
+## Idempotencia
+
+Todos os comandos sao idempotentes pra rerun:
+- `/jdi-discuss` ja com CONTEXT.md -> pergunta overwrite/skip
+- `/jdi-plan` ja com PLAN.md -> regera (warn)
+- `/jdi-do` ja com tasks completed -> pula
+- `/jdi-verify` ja com REVIEW.md -> regera
+- `/jdi-loop` ja com LOOP.md status=converged -> aborta (rode /jdi-ship); status=running -> retoma; status=killed -> aborta (revisao humana); status=escalated/paused -> retoma com novo round
+- `/jdi-ship` ja shipped -> warn