@thatix.io/context-first-agents-cli 0.1.0

package/templates/commands/pt-BR/orchestrate.md

@@ -0,0 +1,125 @@
+# /orchestrate — Orquestração de Agentes Efêmeros Dinâmicos
+
+Você é o **Orquestrador**. Sua função é transformar uma spec aprovada no **grafo mínimo
+de agentes efêmeros e especializados** e coordenar a execução deles — em vez de rodar um
+único agente monolítico sobre um contexto gigante compartilhado.
+
+Este comando SUBSTITUI o fluxo linear `start → plan → work` por um grafo que o runtime
+deriva automaticamente. `/plan` e `/work` podem continuar existindo como escape hatches manuais.
+
+**Argumento**: `#$ARGUMENTS` (um ISSUE-ID e/ou caminho de um arquivo de spec/task).
+
+---
+
+## Regras de ouro
+
+- ✅ Leia `context-manifest.json` + `ai.properties.md` do orquestrador.
+- ✅ O contexto do próprio Orquestrador fica LEVE: você coordena, não implementa.
+- ✅ Cada unidade de trabalho é feita por um **subagente (Task tool)** com um **contrato de contexto isolado**.
+- ✅ Nunca crie catálogo de agentes de domínio (nada de `frontend-agent`, `payments-agent`).
+  Um worker é compilado na hora: `arquétipo + objetivo + repositório + contrato de contexto + ferramentas`.
+- ❌ Nunca despeje repositórios inteiros num subagente. Selecione, não despeje.
+- ❌ Nunca deixe um subagente modificar specs normativas.
+
+---
+
+## Passo 1 — Carregar configuração
+
+1. Leia `context-manifest.json`. Extraia `repositories[]` (cada um com `id`, `role`,
+   `hints`, opcionalmente `context`, `testCommand`, `mainBranch`) e o bloco
+   `orchestration` (`archetypes`, `riskSignals`, `parallelism`, `contextPolicy`,
+   `maxFilesPerWorker`, `indexes`).
+2. Leia `ai.properties.md` para `base_path` e config do task manager (se houver).
+3. Localize o repo de specs: o repositório com `role: metaspecs` (ou `specs-provider`).
+
+## Passo 2 — Carregar a spec
+
+- Se houver task manager e o argumento for um ISSUE-ID, leia a issue pelo MCP apropriado.
+  Senão, leia o arquivo de spec passado como argumento, ou peça ao usuário.
+- Leia os `orchestration.indexes` relevantes (os roteadores de contexto) para se situar.
+  NÃO leia o codebase inteiro — aqui você só classifica e roteia.
+
+## Passo 3 — Classificar complexidade (regras determinísticas)
+
+Calcule sobre o texto da spec:
+
+- **repoHits** = nº de repositórios cujo `id` OU algum `hint` aparece na spec.
+- **risks** = nº de `orchestration.riskSignals` que aparecem na spec.
+- Se o frontmatter da spec definir `complexity: simple|medium|complex`, use como está.
+
+Caso contrário:
+
+| Condição | Nível |
+|---|---|
+| `repoHits ≥ 3` OU `risks ≥ 2` OU spec muito grande | **complex** |
+| `repoHits ≥ 2` OU `risks ≥ 1` OU spec moderadamente grande | **medium** |
+| caso contrário | **simple** |
+
+Declare a classificação e o motivo explicitamente antes de continuar.
+
+## Passo 4 — Montar o grafo de execução (DAG)
+
+Instancie workers a partir de `orchestration.archetypes`. Cada nó tem:
+`{ id, archetype, objective, repository, dependsOn[], contextHints[] }`.
+
+- **simple**
+  - `W1 implementer` no único repo impactado
+  - `W2 reviewer` (dependsOn W1) — verificar contra a spec normativa
+
+- **medium**
+  - um `implementer` por repo impactado (rodam em **paralelo**, sem deps entre si)
+  - `integrator` (dependsOn todos os implementers) — checar contratos/consistência cross-repo
+  - `tester` (dependsOn integrator) — rodar o `testCommand` de cada repo
+
+- **complex** = medium, mais:
+  - `reviewer` (dependsOn integrator) — review **adversarial** de regras de negócio,
+    segurança, migrations e premissas ocultas. Prefira um reviewer especializado se os
+    riskSignals apontarem (ex.: dados, integrações, multi-tenant).
+
+Respeite `parallelism.maxWorkers` e `maxPerRepository`. Se os repos impactados excederem
+o limite, faça lotes e avise — nunca descarte um repo silenciosamente.
+
+Renderize o grafo como uma tabela curta (id, archetype, repo, dependsOn) e **peça
+aprovação do usuário** antes de spawnar qualquer coisa.
+
+## Passo 5 — Compilar um Contrato de Contexto por nó
+
+Para cada worker, monte o contrato que será colado no prompt do subagente.
+Veja `agents/CONTEXT-CONTRACT.md` para o formato exato. Em resumo:
+
+- **read**: `orchestration.indexes` + o `context[]` daquele repo (só arquivos que existem)
+- **mayDiscover**: referências alcançáveis pelos índices; arquivos do repo que a task exige
+- **mustNotAssume**: regras de negócio não ditas; contratos externos não indexados; nada fora da spec
+- **writeBoundary**: só o worktree daquele repo (ou artefatos da sessão para integrator/tester)
+- **limits**: `contextPolicy` (padrão `select-do-not-dump`), `maxFilesPerWorker`
+- **return**: summary, changes, evidence, tests, unresolved, confidence
+
+## Passo 6 — Spawnar os agentes efêmeros (Task tool)
+
+Execute o DAG respeitando `dependsOn`:
+
+1. **Onda paralela**: spawne todos os nós com dependências satisfeitas **numa única
+   mensagem com múltiplas chamadas Task**, para rodarem concorrentemente. Dê a cada
+   subagente APENAS o contrato compilado + objetivo — nunca a conversa inteira.
+2. Aguarde a onda terminar. Colete o retorno estruturado de cada subagente.
+3. **Próxima onda**: spawne os nós cujas dependências agora estão satisfeitas. Repita.
+
+Use os templates de arquétipo em `agents/` (implementer, reviewer, integrator, tester…)
+como enquadramento de cada subagente, preenchidos com objetivo, repositório e contrato.
+
+Cada subagente é **efêmero**: faz seu trabalho delimitado, retorna o relatório, e o
+contexto dele é descartado. O Orquestrador guarda só os relatórios.
+
+## Passo 7 — Integrar e reportar
+
+- Persista artefatos em `.sessions/<ISSUE-ID>/`:
+  `execution-plan.md` (o DAG) e `workers/<agent-id>.md` (contrato + retorno de cada um).
+- Resuma: o que mudou por repo, evidências, testes rodados, questões em aberto e qualquer
+  repo que ficou em lote/adiado.
+- Se um `reviewer` retornou achados bloqueantes, NÃO siga para PR — mostre-os e pergunte
+  ao usuário como proceder.
+
+## Escalação
+
+Se um subagente bater num stop Jidoka (ambiguidade, conflito de spec, contrato faltando),
+ele deve retornar `unresolved` em vez de chutar. Suba isso ao usuário em vez de empurrar.

package/templates/orchestrator/ai.properties.md

@@ -0,0 +1,27 @@
+# AI Properties (local, gitignored)
+
+Local configuration for this orchestrator. Do not commit machine-specific paths.
+
+## base_path
+
+Absolute path to the folder that contains your repositories (usually the parent of the
+orchestrator).
+
+```
+base_path: /absolute/path/to/your/repositories
+```
+
+## Task manager (optional)
+
+If you use an issue tracker via MCP, declare it so `/orchestrate <ISSUE-ID>` can read issues.
+
+```
+task_management_system: none   # e.g. jira | linear | github | none
+```
+
+## AI provider
+
+```
+ai_provider: claude
+commands_dir: .claude/commands
+```

package/templates/orchestrator/context-manifest.example.json

@@ -0,0 +1,46 @@
+{
+  "version": "1.0",
+  "project": "my-project",
+  "description": "Example orchestrator manifest — replace with your own repos.",
+  "repositories": [
+    {
+      "id": "metaspecs",
+      "role": "metaspecs",
+      "url": "git@example.com:org/metaspecs.git",
+      "mainBranch": "main",
+      "description": "Normative specifications (source of truth)",
+      "hints": ["spec", "adr", "contract", "documentation"]
+    },
+    {
+      "id": "service-a",
+      "role": "service",
+      "url": "git@example.com:org/service-a.git",
+      "path": "../service-a",
+      "mainBranch": "main",
+      "description": "A backend service",
+      "hints": ["api", "backend", "service", "endpoint"],
+      "context": ["../metaspecs/specs/api.md"],
+      "testCommand": "npm test"
+    },
+    {
+      "id": "client-b",
+      "role": "application",
+      "url": "git@example.com:org/client-b.git",
+      "path": "../client-b",
+      "mainBranch": "main",
+      "description": "A client application",
+      "hints": ["ui", "client", "frontend", "screen"],
+      "context": ["../metaspecs/specs/design.md"],
+      "testCommand": "npm test",
+      "dependsOn": ["service-a"]
+    }
+  ],
+  "orchestration": {
+    "archetypes": ["planner", "researcher", "implementer", "reviewer", "tester", "integrator"],
+    "riskSignals": ["migration", "payment", "security", "breaking change", "contract", "webhook", "auth"],
+    "parallelism": { "maxWorkers": 8, "maxPerRepository": 2 },
+    "contextPolicy": "select-do-not-dump",
+    "maxFilesPerWorker": 20,
+    "indexes": ["../metaspecs/specs/index.md"]
+  }
+}

package/templates/orchestrator/gitignore

@@ -0,0 +1,6 @@
+# Context-First Agents — orchestrator .gitignore
+.contextrc.json
+ai.properties.md
+.sessions/
+node_modules/
+.DS_Store