oxe-cc 1.11.0 → 1.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +106 -0
- package/README.md +736 -681
- package/bin/lib/oxe-event-bus.cjs +118 -0
- package/bin/lib/oxe-memory-kernel.cjs +188 -0
- package/bin/lib/oxe-project-health.cjs +75 -0
- package/bin/lib/oxe-skill-loader.cjs +131 -0
- package/bin/oxe-cc.js +202 -40
- package/docs/INTEGRATION.md +152 -0
- package/docs/oxe-artifact-map.html +1172 -0
- package/lib/sdk/index.cjs +2 -0
- package/lib/sdk/index.d.ts +185 -159
- package/oxe/schemas/swarm-run.schema.json +130 -0
- package/oxe/workflows/agent-mode.md +150 -0
- package/oxe/workflows/conduct.md +149 -0
- package/oxe/workflows/distill.md +164 -0
- package/oxe/workflows/help.md +1 -0
- package/oxe/workflows/memory.md +163 -0
- package/oxe/workflows/oxe.md +2 -1
- package/oxe/workflows/references/workflow-runtime-contracts.json +1113 -960
- package/oxe/workflows/route.md +7 -5
- package/oxe/workflows/swarm/board.md +119 -0
- package/oxe/workflows/swarm/scout.md +170 -0
- package/oxe/workflows/swarm-mode.md +280 -0
- package/package.json +2 -2
- package/packages/runtime/package.json +1 -1
- package/vscode-extension/package.json +1 -1
package/oxe/workflows/route.md
CHANGED
|
@@ -13,15 +13,17 @@ Este passo é **meta**: só orientação. A execução real pertence ao workflow
|
|
|
13
13
|
</context>
|
|
14
14
|
|
|
15
15
|
<process>
|
|
16
|
-
1.
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
16
|
+
1. Verificar se o input é um **objetivo de implementação** (cria, implementa, adiciona, corrige, constrói, desenvolve, migra — verbos de ação sobre o código):
|
|
17
|
+
- **Sim** → destino direto: `oxe/workflows/conduct.md` (Conductor decide Agent Mode vs Swarm Mode). Não consultar tabela.
|
|
18
|
+
2. Caso contrário, ler a secção **Router** em `oxe/workflows/help.md` (ou `.oxe/workflows/help.md` no projeto).
|
|
19
|
+
3. Classificar a intenção do utilizador e escolher **uma** linha da tabela.
|
|
20
|
+
4. Se a classificação não for claramente dominante, ainda devolver um único destino, mas explicitar a confiança da escolha e a lacuna que poderia mudar o roteamento.
|
|
21
|
+
5. Responder apenas:
|
|
20
22
|
- **Comando:** …
|
|
21
23
|
- **Workflow:** `oxe/workflows/<nome>.md`
|
|
22
24
|
- **Por quê:** (uma frase)
|
|
23
25
|
- **Confiança:** alta | média | baixa (só quando houver ambiguidade real)
|
|
24
|
-
|
|
26
|
+
6. Não criar ficheiros em `.oxe/` salvo o utilizador pedir explícito registo; se o utilizador pedir rastreio: acrescentar uma linha em **`.oxe/STATE.md`** (ex.: `last_route: /oxe-scan — YYYY-MM-DD`).
|
|
25
27
|
</process>
|
|
26
28
|
|
|
27
29
|
<success_criteria>
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# OXE — Workflow: swarm/board (Board Manager)
|
|
2
|
+
|
|
3
|
+
<objective>
|
|
4
|
+
Gerenciar o BOARD.md e BOARD.json do Swarm Run — a visão em tempo real do estado de cada tarefa,
|
|
5
|
+
agente, bloqueio e wave. Consultado por qualquer agente do swarm para saber o que está acontecendo
|
|
6
|
+
e atualizado após cada mudança de estado.
|
|
7
|
+
</objective>
|
|
8
|
+
|
|
9
|
+
<context>
|
|
10
|
+
- Usado internamente por `swarm-mode.md` após cada fase.
|
|
11
|
+
- Pode ser invocado diretamente pelo usuário via `/oxe-dashboard` para visualizar o swarm ativo.
|
|
12
|
+
- Não modifica arquivos de código. Apenas lê `.oxe/swarm/` e atualiza artefatos de board.
|
|
13
|
+
</context>
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Estrutura do BOARD.md
|
|
18
|
+
|
|
19
|
+
```markdown
|
|
20
|
+
# Swarm Board — <run_id>
|
|
21
|
+
|
|
22
|
+
**Objetivo:** <texto>
|
|
23
|
+
**Status:** running | paused | completed | failed
|
|
24
|
+
**Iniciado:** <timestamp> | **Atualizado:** <timestamp>
|
|
25
|
+
**Wave atual:** <N> de <total>
|
|
26
|
+
|
|
27
|
+
## Progresso
|
|
28
|
+
|
|
29
|
+
| ID | Tarefa | Agente | Wave | Status | Verificação | Revisão |
|
|
30
|
+
|----|--------|--------|------|--------|-------------|---------|
|
|
31
|
+
| T1 | Criar service de importação | builder-backend | 1 | ✅ done | passed | aprovado |
|
|
32
|
+
| T2 | Criar componente de upload | builder-frontend | 1 | 🔄 running | — | — |
|
|
33
|
+
| T3 | Criar migration | builder-storage | 1 | ⏳ pending | — | — |
|
|
34
|
+
| T4 | Testes de integração | builder-backend | 2 | ⏳ pending | — | — |
|
|
35
|
+
|
|
36
|
+
## Bloqueios ativos
|
|
37
|
+
|
|
38
|
+
| Task | Agente | Razão | Desde |
|
|
39
|
+
|------|--------|-------|-------|
|
|
40
|
+
| — | — | — | — |
|
|
41
|
+
|
|
42
|
+
## Quality Gates
|
|
43
|
+
|
|
44
|
+
| Gate | Condição | Status |
|
|
45
|
+
|------|----------|--------|
|
|
46
|
+
| G1 | Cobertura ≥ 80% | ⏳ pendente |
|
|
47
|
+
| G2 | Arquivo de alto risco revisado | ⏳ pendente |
|
|
48
|
+
|
|
49
|
+
## Log de eventos (últimos 5)
|
|
50
|
+
|
|
51
|
+
| Timestamp | Evento |
|
|
52
|
+
|-----------|--------|
|
|
53
|
+
| ... | Scout concluído: 12 arquivos mapeados |
|
|
54
|
+
| ... | Builder-backend iniciou T1 |
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Estrutura do BOARD.json
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"run_id": "...",
|
|
64
|
+
"updated_at": "ISO8601",
|
|
65
|
+
"status": "running",
|
|
66
|
+
"current_wave": 1,
|
|
67
|
+
"total_waves": 2,
|
|
68
|
+
"tasks": [
|
|
69
|
+
{
|
|
70
|
+
"id": "T1",
|
|
71
|
+
"title": "...",
|
|
72
|
+
"agent": "builder-backend",
|
|
73
|
+
"wave": 1,
|
|
74
|
+
"status": "done | running | pending | blocked | failed",
|
|
75
|
+
"verification": "passed | failed | null",
|
|
76
|
+
"review": "approved | rejected | null",
|
|
77
|
+
"files_changed": [],
|
|
78
|
+
"started_at": "ISO8601",
|
|
79
|
+
"completed_at": null
|
|
80
|
+
}
|
|
81
|
+
],
|
|
82
|
+
"blockers": [],
|
|
83
|
+
"quality_gates": [
|
|
84
|
+
{"id": "G1", "condition": "coverage >= 80%", "status": "pending | passed | failed"}
|
|
85
|
+
],
|
|
86
|
+
"agents": {
|
|
87
|
+
"scout": "done",
|
|
88
|
+
"builders": {"builder-backend": "running", "builder-frontend": "pending"},
|
|
89
|
+
"reviewer": "pending",
|
|
90
|
+
"verifier": "pending"
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Operações disponíveis
|
|
98
|
+
|
|
99
|
+
### update_task_status(task_id, status, extra)
|
|
100
|
+
Atualiza status de uma tarefa em BOARD.json e regenera tabela em BOARD.md.
|
|
101
|
+
|
|
102
|
+
### add_blocker(task_id, agent, reason)
|
|
103
|
+
Adiciona à seção "Bloqueios ativos" em BOARD.md e ao array `blockers` em BOARD.json.
|
|
104
|
+
|
|
105
|
+
### resolve_blocker(task_id)
|
|
106
|
+
Remove da seção de bloqueios. Registra resolução no log.
|
|
107
|
+
|
|
108
|
+
### update_gate(gate_id, status)
|
|
109
|
+
Atualiza status do gate em ambos os artefatos.
|
|
110
|
+
|
|
111
|
+
### append_log(event_text)
|
|
112
|
+
Adiciona linha ao log de eventos (mantém últimos 10).
|
|
113
|
+
|
|
114
|
+
<success_criteria>
|
|
115
|
+
- [ ] BOARD.md renderiza tabela legível a qualquer momento do swarm.
|
|
116
|
+
- [ ] BOARD.json é fonte de verdade para todos os agentes lerem estado das tasks.
|
|
117
|
+
- [ ] Bloqueios visíveis imediatamente após registro.
|
|
118
|
+
- [ ] Quality gates rastreados com status atual.
|
|
119
|
+
</success_criteria>
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# OXE — Workflow: swarm/scout (Scout Agent)
|
|
2
|
+
|
|
3
|
+
<objective>
|
|
4
|
+
Executar reconhecimento do codebase antes que qualquer Builder toque um arquivo.
|
|
5
|
+
Produz o mapa completo de arquivos relevantes, padrões, riscos e candidatos a testes —
|
|
6
|
+
informação que permite ao Coordinator fazer decomposição e File Ownership sem surpresas.
|
|
7
|
+
</objective>
|
|
8
|
+
|
|
9
|
+
<context>
|
|
10
|
+
- Invocado por `swarm-mode.md` Fase 2.
|
|
11
|
+
- Aplicar `oxe/workflows/references/reasoning-discovery.md`: explorar antes de concluir; separar fatos, inferências e lacunas.
|
|
12
|
+
- Persona: `researcher.md` (exploração) + instinto de `executor.md` (write set mínimo — Scout não modifica código).
|
|
13
|
+
- Nunca modifica arquivos do projeto. Apenas lê e produz artefatos em `.oxe/swarm/scout/`.
|
|
14
|
+
- Parâmetros de entrada: `objective`, `intent_tags`, `run_id`.
|
|
15
|
+
</context>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Fase 1 — Mapeamento de Módulos
|
|
20
|
+
|
|
21
|
+
Com base nos `intent_tags`, identificar os módulos do projeto relevantes ao objetivo:
|
|
22
|
+
|
|
23
|
+
1. Usar Glob para localizar diretórios e arquivos por padrão (ex.: `src/**/*.ts`, `app/**/*.tsx`)
|
|
24
|
+
2. Para cada módulo relevante:
|
|
25
|
+
- Nome do módulo
|
|
26
|
+
- Caminho raiz
|
|
27
|
+
- Responsabilidade (inferida de exports, README local, comentários de topo de arquivo)
|
|
28
|
+
- Tamanho (estimativa de linhas, arquivos)
|
|
29
|
+
- Dependências internas (quais outros módulos ele importa)
|
|
30
|
+
|
|
31
|
+
Gravar `.oxe/swarm/scout/CODEBASE-MAP.md`:
|
|
32
|
+
```markdown
|
|
33
|
+
# Codebase Map — <run_id>
|
|
34
|
+
|
|
35
|
+
**Objetivo:** <texto>
|
|
36
|
+
**Domínios relevantes:** <intent_tags>
|
|
37
|
+
|
|
38
|
+
## Módulos identificados
|
|
39
|
+
|
|
40
|
+
| Módulo | Caminho | Responsabilidade | Arquivos | Dependências |
|
|
41
|
+
|--------|---------|-----------------|----------|--------------|
|
|
42
|
+
| auth | src/auth/ | Autenticação JWT | 8 | db, config |
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Fase 2 — Padrões de Código
|
|
48
|
+
|
|
49
|
+
Identificar as convenções em uso nos módulos relevantes:
|
|
50
|
+
|
|
51
|
+
- Naming conventions (camelCase? snake_case? PascalCase para classes?)
|
|
52
|
+
- Estrutura de arquivos (barrel exports? index.ts por pasta?)
|
|
53
|
+
- Padrão de imports (absolute paths? aliases? relative?)
|
|
54
|
+
- Padrão de testes (Jest? Vitest? Localização dos testes? `__tests__/` ou `.spec.ts` colocado?)
|
|
55
|
+
- Padrão de erros (throw? Result type? Either? callbacks?)
|
|
56
|
+
- Padrão de tipos (interfaces separadas? types inline? schemas Zod?)
|
|
57
|
+
|
|
58
|
+
Gravar `.oxe/swarm/scout/PATTERNS.md`:
|
|
59
|
+
```markdown
|
|
60
|
+
# Padrões Detectados — <run_id>
|
|
61
|
+
|
|
62
|
+
## Naming
|
|
63
|
+
- ...
|
|
64
|
+
|
|
65
|
+
## Estrutura de arquivos
|
|
66
|
+
- ...
|
|
67
|
+
|
|
68
|
+
## Testes
|
|
69
|
+
- ...
|
|
70
|
+
|
|
71
|
+
## Tipos
|
|
72
|
+
- ...
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Fase 3 — Mapa de Riscos
|
|
78
|
+
|
|
79
|
+
Para cada arquivo candidato a modificação:
|
|
80
|
+
|
|
81
|
+
| Critério | Risk Level |
|
|
82
|
+
|----------|-----------|
|
|
83
|
+
| Importado por 5+ outros módulos | high |
|
|
84
|
+
| Contém lógica de auth / pagamento / dados sensíveis | high |
|
|
85
|
+
| Arquivo de configuração global (env, db config) | high |
|
|
86
|
+
| Módulo com cobertura de testes < 50% | med |
|
|
87
|
+
| Arquivo tocado nos últimos 7 dias (git log) | med |
|
|
88
|
+
| Arquivo isolado com testes adequados | low |
|
|
89
|
+
|
|
90
|
+
Gravar `.oxe/swarm/scout/RISK-MAP.md`:
|
|
91
|
+
```markdown
|
|
92
|
+
# Risk Map — <run_id>
|
|
93
|
+
|
|
94
|
+
| Arquivo | Risk Level | Motivo | Agente sugerido |
|
|
95
|
+
|---------|-----------|--------|----------------|
|
|
96
|
+
| src/auth/jwt.ts | high | auth crítica + 12 importadores | builder-backend |
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Fase 4 — File Candidates
|
|
102
|
+
|
|
103
|
+
Para cada arquivo que provavelmente precisa ser criado ou modificado para satisfazer o objetivo:
|
|
104
|
+
|
|
105
|
+
Gravar `.oxe/swarm/scout/FILE-CANDIDATES.json`:
|
|
106
|
+
```json
|
|
107
|
+
[
|
|
108
|
+
{
|
|
109
|
+
"file": "src/import/import.service.ts",
|
|
110
|
+
"action": "create | modify",
|
|
111
|
+
"domain": "backend",
|
|
112
|
+
"risk_level": "low",
|
|
113
|
+
"suggested_agent": "builder-backend",
|
|
114
|
+
"rationale": "novo service de importação"
|
|
115
|
+
}
|
|
116
|
+
]
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Fase 5 — Test Candidates
|
|
122
|
+
|
|
123
|
+
Para cada arquivo de código candidato, identificar o arquivo de teste correspondente:
|
|
124
|
+
|
|
125
|
+
Gravar `.oxe/swarm/scout/TEST-CANDIDATES.json`:
|
|
126
|
+
```json
|
|
127
|
+
[
|
|
128
|
+
{
|
|
129
|
+
"code_file": "src/import/import.service.ts",
|
|
130
|
+
"test_file": "src/import/import.service.spec.ts",
|
|
131
|
+
"exists": false,
|
|
132
|
+
"existing_coverage_pct": null,
|
|
133
|
+
"test_strategy": "unit | integration | e2e"
|
|
134
|
+
}
|
|
135
|
+
]
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Fase 6 — Handoff para Coordinator
|
|
141
|
+
|
|
142
|
+
Emitir mensagem em `.oxe/swarm/MESSAGES.ndjson`:
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"ts": "ISO8601",
|
|
146
|
+
"from": "scout",
|
|
147
|
+
"to": "coordinator",
|
|
148
|
+
"type": "handoff_summary",
|
|
149
|
+
"run_id": "...",
|
|
150
|
+
"payload": {
|
|
151
|
+
"modules_mapped": N,
|
|
152
|
+
"files_candidates": M,
|
|
153
|
+
"high_risk_files": K,
|
|
154
|
+
"patterns_detected": ["..."],
|
|
155
|
+
"ready_for_task_graph": true
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Atualizar `.oxe/swarm/SWARM-RUN.json` → `agents.scout.status = "done"`.
|
|
161
|
+
|
|
162
|
+
<success_criteria>
|
|
163
|
+
- [ ] CODEBASE-MAP.md com todos os módulos relevantes ao objetivo.
|
|
164
|
+
- [ ] PATTERNS.md com pelo menos naming, estrutura e testes.
|
|
165
|
+
- [ ] RISK-MAP.md com risk_level para cada arquivo candidato.
|
|
166
|
+
- [ ] FILE-CANDIDATES.json com ação (create/modify) e agente sugerido.
|
|
167
|
+
- [ ] TEST-CANDIDATES.json com estratégia por arquivo.
|
|
168
|
+
- [ ] Nenhum arquivo do projeto foi modificado.
|
|
169
|
+
- [ ] Mensagem de handoff emitida para coordinator.
|
|
170
|
+
</success_criteria>
|
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
# OXE — Workflow: swarm-mode (Swarm Mode)
|
|
2
|
+
|
|
3
|
+
<objective>
|
|
4
|
+
Orquestração multi-agente para objetivos complexos (3+ domínios, 8+ arquivos ou feature completa).
|
|
5
|
+
Coordena 5 papéis em sequência controlada: Scout → Coordinator (Task Graph + File Ownership) → Builder(s) em paralelo → Reviewer → Verifier/Integrator.
|
|
6
|
+
Ao final, aciona aprendizado: padrões → CANDIDATES.ndjson → LESSONS.md.
|
|
7
|
+
</objective>
|
|
8
|
+
|
|
9
|
+
<context>
|
|
10
|
+
- Invocado por `conduct.md` quando `intent_score = complexo`.
|
|
11
|
+
- Reaproveitamento obrigatório:
|
|
12
|
+
- `packages/runtime/src/scheduler/multi-agent-coordinator.ts` — coordenação parallel/cooperative
|
|
13
|
+
- `oxe/schemas/plan-agents.schema.json` v3 — blueprint de agentes
|
|
14
|
+
- `oxe/workflows/references/plan-agent-chat-protocol.md` — mensagens inter-agente
|
|
15
|
+
- `packages/runtime/src/compiler/graph-compiler.ts` — ExecutionGraph
|
|
16
|
+
- Artefatos em `.oxe/swarm/` (run-scoped: `.oxe/swarm/<run_id>/` quando múltiplos runs ativos).
|
|
17
|
+
- Aplicar `oxe/workflows/references/reasoning-planning.md` na fase de decomposição.
|
|
18
|
+
- Aplicar `oxe/workflows/references/reasoning-execution.md` em cada Builder.
|
|
19
|
+
- Aplicar `oxe/workflows/references/reasoning-review.md` no Reviewer.
|
|
20
|
+
</context>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Fase 1 — Inicialização do Swarm
|
|
25
|
+
|
|
26
|
+
Gerar `run_id` único: `swarm-<YYYYMMDD>-<seq>`
|
|
27
|
+
|
|
28
|
+
Criar `.oxe/swarm/SWARM-RUN.json`:
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"run_id": "swarm-YYYYMMDD-001",
|
|
33
|
+
"started_at": "ISO8601",
|
|
34
|
+
"status": "running",
|
|
35
|
+
"objective": "<objetivo do usuário>",
|
|
36
|
+
"intent_tags": [],
|
|
37
|
+
"memory_applied": false,
|
|
38
|
+
"agents": {
|
|
39
|
+
"scout": {"status": "pending"},
|
|
40
|
+
"coordinator": {"status": "pending"},
|
|
41
|
+
"builders": [],
|
|
42
|
+
"reviewer": {"status": "pending"},
|
|
43
|
+
"verifier": {"status": "pending"}
|
|
44
|
+
},
|
|
45
|
+
"task_graph": null,
|
|
46
|
+
"file_ownership": null,
|
|
47
|
+
"waves": [],
|
|
48
|
+
"quality_gates": []
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Criar `.oxe/swarm/BOARD.md` (tabela inicial):
|
|
53
|
+
|
|
54
|
+
```markdown
|
|
55
|
+
# Swarm Board — <run_id>
|
|
56
|
+
|
|
57
|
+
**Objetivo:** <texto>
|
|
58
|
+
**Status:** running
|
|
59
|
+
**Iniciado:** <timestamp>
|
|
60
|
+
|
|
61
|
+
| ID | Tarefa | Agente | Status | Arquivos |
|
|
62
|
+
|----|--------|--------|--------|----------|
|
|
63
|
+
| — | — | Scout | em andamento | — |
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Fase 2 — Scout
|
|
69
|
+
|
|
70
|
+
Invocar `oxe/workflows/swarm/scout.md` com o objetivo e intent_tags.
|
|
71
|
+
|
|
72
|
+
O Scout produz (em `.oxe/swarm/scout/`):
|
|
73
|
+
- `CODEBASE-MAP.md` — visão geral dos módulos relevantes ao objetivo
|
|
74
|
+
- `PATTERNS.md` — padrões de código existentes (naming, estrutura, convenções)
|
|
75
|
+
- `RISK-MAP.md` — arquivos críticos, arquivos compartilhados, riscos de regressão
|
|
76
|
+
- `FILE-CANDIDATES.json` — `[{file, domain, risk_level: low|med|high, suggested_agent}]`
|
|
77
|
+
- `TEST-CANDIDATES.json` — `[{test_file, covers, existing_coverage_pct}]`
|
|
78
|
+
|
|
79
|
+
Ao completar, atualizar `SWARM-RUN.json` → `agents.scout.status = "done"`.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Fase 3 — Coordinator: Task Graph + File Ownership
|
|
84
|
+
|
|
85
|
+
O Coordinator (Conductor) usa os artefatos do Scout para:
|
|
86
|
+
|
|
87
|
+
### 3.1 Decomposição em tarefas
|
|
88
|
+
|
|
89
|
+
Decompor o objetivo em tarefas Tn seguindo os princípios de `oxe/personas/planner.md`:
|
|
90
|
+
- Cada tarefa: domínio claro, mutation_scope explícito, critério de aceite verificável
|
|
91
|
+
- Agrupar em ondas: tarefas sem dependência → mesma onda
|
|
92
|
+
|
|
93
|
+
### 3.2 Atribuição de Builders
|
|
94
|
+
|
|
95
|
+
Para cada domínio detectado, criar um Builder com:
|
|
96
|
+
- `id`: `builder-<domínio>` (ex.: `builder-backend`, `builder-frontend`)
|
|
97
|
+
- `persona`: persona mais adequada ao domínio (via mapeamento de conduct.md Fase 3)
|
|
98
|
+
- `taskIds`: tarefas atribuídas
|
|
99
|
+
- `model_hint`: fast | balanced | powerful
|
|
100
|
+
|
|
101
|
+
### 3.3 File Ownership
|
|
102
|
+
|
|
103
|
+
Criar `.oxe/swarm/FILE-OWNERSHIP.json`:
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"run_id": "...",
|
|
108
|
+
"created_at": "ISO8601",
|
|
109
|
+
"locks": [
|
|
110
|
+
{
|
|
111
|
+
"file": "src/api/import.ts",
|
|
112
|
+
"owner_agent": "builder-backend",
|
|
113
|
+
"status": "locked",
|
|
114
|
+
"locked_at": "ISO8601"
|
|
115
|
+
}
|
|
116
|
+
],
|
|
117
|
+
"free": []
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Regra de conflito:** se dois Builders têm o mesmo arquivo em seu write_set → serializar em waves sequenciais (não paralelas). Registrar decisão em `.oxe/swarm/DECISIONS.md`.
|
|
122
|
+
|
|
123
|
+
### 3.4 Atualizar artefatos
|
|
124
|
+
|
|
125
|
+
Gravar `.oxe/swarm/TASK-GRAPH.json`:
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"run_id": "...",
|
|
129
|
+
"tasks": [
|
|
130
|
+
{"id": "T1", "title": "...", "domain": "...", "agent": "builder-backend", "wave": 1, "depends_on": [], "mutation_scope": [], "verify": "..."}
|
|
131
|
+
],
|
|
132
|
+
"waves": [[["T1", "T2"]], [["T3"]]]
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Gravar `plan-agents.json` conforme schema v3 em `oxe/schemas/plan-agents.schema.json`.
|
|
137
|
+
|
|
138
|
+
Atualizar `BOARD.md` com todas as tarefas.
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## Fase 4 — Builders (execução em ondas)
|
|
143
|
+
|
|
144
|
+
Para cada onda, executar os Builders em paralelo (sem conflito de arquivo validado na Fase 3):
|
|
145
|
+
|
|
146
|
+
Cada Builder opera com o protocolo de `oxe/personas/executor.md`:
|
|
147
|
+
1. Ler tarefa(s) atribuída(s) + contexto de memória (inject de `conduct.md` Fase 2)
|
|
148
|
+
2. Discovery mínimo (confirmar arquivos, padrões)
|
|
149
|
+
3. Implementar com write set declarado no `FILE-OWNERSHIP.json`
|
|
150
|
+
4. Verificar (critério de aceite da tarefa)
|
|
151
|
+
5. Registrar resultado em `.oxe/swarm/BOARD.json`:
|
|
152
|
+
```json
|
|
153
|
+
{"task_id": "T1", "agent": "builder-backend", "status": "done", "files_changed": [], "verification": "passed"}
|
|
154
|
+
```
|
|
155
|
+
6. Emitir mensagem de handoff em `.oxe/swarm/MESSAGES.ndjson` para o próximo agente
|
|
156
|
+
|
|
157
|
+
Se verificação falhar:
|
|
158
|
+
- Registrar em `.oxe/swarm/BLOCKERS.ndjson`: `{"task_id": "...", "agent": "...", "reason": "...", "ts": "..."}`
|
|
159
|
+
- Atualizar BOARD.md com status `blocked`
|
|
160
|
+
- Coordinator decide: retry | replan local | escalar para usuário
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Fase 5 — Reviewer
|
|
165
|
+
|
|
166
|
+
Após cada onda de Builders, invocar `oxe/personas/verifier.md` como Reviewer:
|
|
167
|
+
|
|
168
|
+
Para cada tarefa concluída:
|
|
169
|
+
1. Ler arquivos modificados pelo Builder
|
|
170
|
+
2. Verificar: padrões seguidos? Critério de aceite satisfeito? Sem side effects não declarados?
|
|
171
|
+
3. Gravar `.oxe/swarm/reviews/<task_id>-REVIEW.md`:
|
|
172
|
+
```markdown
|
|
173
|
+
## Review — T1
|
|
174
|
+
**Status:** aprovado | reprovado
|
|
175
|
+
**Checklist:** [lista]
|
|
176
|
+
**Observações:** [texto ou —]
|
|
177
|
+
```
|
|
178
|
+
4. Se reprovado: Builder refaz → nova revisão (máx 2 tentativas por tarefa antes de escalar)
|
|
179
|
+
|
|
180
|
+
Atualizar BOARD.md.
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Fase 6 — Quality Gates
|
|
185
|
+
|
|
186
|
+
Antes de passar para o Verifier, avaliar gates automáticos baseados em `risk_score`:
|
|
187
|
+
|
|
188
|
+
| Condição | Gate |
|
|
189
|
+
|----------|------|
|
|
190
|
+
| Algum arquivo com `risk_level: high` foi modificado | Gate humano obrigatório |
|
|
191
|
+
| Cobertura de testes abaixo do threshold do projeto | Gate automático: bloquear até cobrir |
|
|
192
|
+
| Alguma tarefa falhou revisão 2x | Gate humano obrigatório |
|
|
193
|
+
| Nenhuma condição acima | Gate automático: aprovado |
|
|
194
|
+
|
|
195
|
+
Gravar `.oxe/swarm/QUALITY-GATES.md`:
|
|
196
|
+
```markdown
|
|
197
|
+
## Quality Gates — <run_id>
|
|
198
|
+
|
|
199
|
+
| Gate | Condição | Status | Resolução |
|
|
200
|
+
|------|----------|--------|-----------|
|
|
201
|
+
| G1 | Arquivo de alto risco modificado | pendente | — |
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Fase 7 — Verifier/Integrator
|
|
207
|
+
|
|
208
|
+
Invocar `oxe/personas/verifier.md` como Verifier final:
|
|
209
|
+
|
|
210
|
+
1. Integrar todas as mudanças (merge de worktrees se modo git_worktree)
|
|
211
|
+
2. Executar suite de testes completa
|
|
212
|
+
3. Verificar critérios de aceite do objetivo original (não só das tarefas individuais)
|
|
213
|
+
4. Gravar `.oxe/swarm/FINAL-INTEGRATION.md`:
|
|
214
|
+
```markdown
|
|
215
|
+
## Integração Final — <run_id>
|
|
216
|
+
|
|
217
|
+
**Objetivo:** <texto>
|
|
218
|
+
**Status:** integrado | falhou
|
|
219
|
+
**Testes:** N passando / M falhando
|
|
220
|
+
**Critérios de aceite:** [checklist com resultado]
|
|
221
|
+
**Evidências:** [lista de arquivos de evidência]
|
|
222
|
+
```
|
|
223
|
+
5. Atualizar `.oxe/VERIFY.md` com resultado da integração
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Fase 8 — Learning
|
|
228
|
+
|
|
229
|
+
Ao completar (sucesso ou falha parcial), acionar `oxe/workflows/distill.md`:
|
|
230
|
+
|
|
231
|
+
- Entrada: `SWARM-RUN.json` + `FINAL-INTEGRATION.md` + `BLOCKERS.ndjson` + reviews
|
|
232
|
+
- Saída: `.oxe/learning/CANDIDATES.ndjson` + atualização de `.oxe/global/LESSONS.md`
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Fase 9 — Eventos e Fechamento
|
|
237
|
+
|
|
238
|
+
Emitir para `.oxe/OXE-EVENTS.ndjson`:
|
|
239
|
+
```json
|
|
240
|
+
{"type": "RunStarted", "payload": {"mode": "swarm", "run_id": "...", "objective": "..."}}
|
|
241
|
+
{"type": "WorkItemCompleted", "payload": {"task_id": "T1", "agent": "..."}}
|
|
242
|
+
...
|
|
243
|
+
{"type": "RunCompleted", "payload": {"run_id": "...", "status": "completed|partial|failed"}}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Atualizar `SWARM-RUN.json` → `status = completed | partial | failed`.
|
|
247
|
+
Atualizar `BOARD.md` com resumo final.
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## Saída para o usuário
|
|
252
|
+
|
|
253
|
+
```
|
|
254
|
+
Swarm Mode — concluído
|
|
255
|
+
Objetivo: <texto resumido>
|
|
256
|
+
Agentes: Scout + N Builders + Reviewer + Verifier
|
|
257
|
+
Tasks: X concluídas / Y falharam
|
|
258
|
+
Integração: passou | falhou
|
|
259
|
+
Quality Gates: N aprovados / M pendentes
|
|
260
|
+
|
|
261
|
+
Arquivos principais alterados:
|
|
262
|
+
- <lista>
|
|
263
|
+
|
|
264
|
+
Learning: N lições registradas / M skill candidatas
|
|
265
|
+
|
|
266
|
+
Próximo passo: <recomendação>
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
<success_criteria>
|
|
270
|
+
- [ ] SWARM-RUN.json criado e atualizado em todas as fases.
|
|
271
|
+
- [ ] Scout produz todos os 5 artefatos em `.oxe/swarm/scout/`.
|
|
272
|
+
- [ ] FILE-OWNERSHIP.json sem conflitos entre Builders paralelos.
|
|
273
|
+
- [ ] BOARD.md atualizado em tempo real por fase.
|
|
274
|
+
- [ ] Cada tarefa tem review em `.oxe/swarm/reviews/`.
|
|
275
|
+
- [ ] QUALITY-GATES.md avaliado antes da integração.
|
|
276
|
+
- [ ] FINAL-INTEGRATION.md gerado pelo Verifier.
|
|
277
|
+
- [ ] VERIFY.md atualizado.
|
|
278
|
+
- [ ] Learning acionado (distill.md invocado).
|
|
279
|
+
- [ ] OXE-EVENTS.ndjson atualizado.
|
|
280
|
+
</success_criteria>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "oxe-cc",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.14.0",
|
|
4
4
|
"description": "OXE — spec-driven workflows in .oxe/ with runtime enterprise, evidence-first verification and multi-runtime integrations (npx)",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "",
|
|
@@ -68,7 +68,7 @@
|
|
|
68
68
|
"sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",
|
|
69
69
|
"release:doctor": "node scripts/release-doctor.cjs",
|
|
70
70
|
"release:manifest": "node scripts/release-doctor.cjs --write-manifest",
|
|
71
|
-
"test:root": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs tests/oxe-plugins.test.cjs",
|
|
71
|
+
"test:root": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs tests/oxe-plugins.test.cjs tests/oxe-status-summary.test.cjs tests/oxe-integration-contracts.test.cjs",
|
|
72
72
|
"test:runtime": "cd packages/runtime && npm test",
|
|
73
73
|
"test:runtime-smoke": "node scripts/runtime-smoke-matrix.cjs",
|
|
74
74
|
"test:runtime-real": "node scripts/runtime-real-suite.cjs",
|