@thatix.io/context-first-agents-cli 0.2.0 → 0.2.2

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.
Files changed (13) hide show
  1. package/dist/templates/commands/en/orchestrate.md +33 -0
  2. package/dist/templates/commands/en/warm-up.md +63 -39
  3. package/dist/templates/commands/es/orchestrate.md +33 -0
  4. package/dist/templates/commands/es/warm-up.md +63 -39
  5. package/dist/templates/commands/pt-BR/orchestrate.md +33 -0
  6. package/dist/templates/commands/pt-BR/warm-up.md +63 -39
  7. package/package.json +1 -1
  8. package/templates/commands/en/orchestrate.md +33 -0
  9. package/templates/commands/en/warm-up.md +63 -39
  10. package/templates/commands/es/orchestrate.md +33 -0
  11. package/templates/commands/es/warm-up.md +63 -39
  12. package/templates/commands/pt-BR/orchestrate.md +33 -0
  13. package/templates/commands/pt-BR/warm-up.md +63 -39
package/dist/templates/commands/en/orchestrate.md CHANGED
@@ -93,6 +93,39 @@ See `agents/CONTEXT-CONTRACT.md` for the exact shape. In short:
93
93
  - **limits**: `contextPolicy` (default `select-do-not-dump`), `maxFilesPerWorker`
94
94
  - **return**: summary, changes, evidence, tests, unresolved questions, confidence
95
95
 
96
+ ## Step 5b — Prepare the session worktrees (via git, not Node)
97
+
98
+ Before spawning any agent, create an **isolated git worktree per impacted repository**
99
+ (only the ones in the graph), so each implementer has a place to write without touching
100
+ the main repo. Use `base_path` (from `ai.properties.md`) and the `<ISSUE-ID>`.
101
+
102
+ For each impacted repository `<repo>`:
103
+
104
+ 1. If `.sessions/<ISSUE-ID>/<repo>/` already exists, **skip** (worktree ready).
105
+ 2. Check whether branch `feature/<ISSUE-ID>` already exists in the repo:
106
+ ```bash
107
+ git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
108
+ ```
109
+ 3. Create the worktree from the main repo:
110
+ - if the branch does **not** exist (create it in the worktree):
111
+ ```bash
112
+ git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
113
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
114
+ ```
115
+ - if the branch **already** exists (reuse it):
116
+ ```bash
117
+ git -C "{base_path}/<repo>" worktree add \
118
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
119
+ ```
120
+
121
+ Rules:
122
+ - **Never** `checkout` in the main repo (`{base_path}/<repo>`) — the worktree isolates everything.
123
+ - If `git worktree add` fails with "already exists", treat it as ready and continue.
124
+ - Only prepare worktrees for the **impacted** repos in the graph, not every repo in the manifest.
125
+ - Record in `execution-plan.md` which worktrees were created (path + branch).
126
+
127
+ After this, each agent's `writeBoundary` (`.sessions/<ISSUE-ID>/<repo>/`) actually exists.
128
+
96
129
  ## Step 6 — Spawn ephemeral agents (Task tool)
97
130
 
98
131
  Execute the DAG respecting `dependsOn`:
package/dist/templates/commands/en/warm-up.md CHANGED
@@ -1,59 +1,83 @@
1
- # Warm-up - Context Loading
1
+ # Warm-up — Context Loading (spec indexes for RAG)
2
2
 
3
- Prepares the environment by loading optimized project context.
3
+ Prepares the environment by loading the **spec indexes** into a navigable context map.
4
+ The goal is NOT to dump the specs into context, but to load the **indexes** so later
5
+ commands know **where to look** for each piece of information, on demand.
4
6
 
5
- ## 1. Load Configuration
7
+ **Arguments**: `#$ARGUMENTS`
6
8
 
7
- Read the orchestrator files:
8
- - **`context-manifest.json`** - Repositories and roles
9
- - **`ai.properties.md`** - base_path, task_management_system
9
+ ---
10
10
 
11
- ## 2. Load Compact Context (OPTIMIZED)
11
+ ## 1. Load configuration
12
12
 
13
- **IMPORTANT**: Use PROGRESSIVE loading to save context window.
13
+ Read from the orchestrator:
14
+ - **`context-manifest.json`** — `repositories[]` (id, role, hints), and the
15
+ `orchestration` block (especially `indexes`).
16
+ - **`ai.properties.md`** — `base_path`, `task_management_system`.
14
17
 
15
- ### Required (warm-up)
18
+ Locate the specs repo: the one with `role: "metaspecs"` (or `"specs-provider"`).
16
19
 
17
- Locate metaspecs via `context-manifest.json` (role: "specs-provider"):
20
+ ## 2. Discover the indexes (dynamic — requires no fixed file)
18
21
 
19
- ```
20
- {base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md (~100 lines)
21
- ```
22
+ Build the list of indexes to load, in this priority order, **skipping whatever doesn't exist**:
23
+
24
+ 1. Every path in the manifest's `orchestration.indexes` (if defined).
25
+ 2. If none are defined, or to complement, **discover** indexes in the specs repo:
26
+ - look for `index.md` / `INDEX.md` under `{base_path}/{metaspecs-id}/specs/` and
27
+ subfolders (e.g. `specs/index.md`, `specs/technical/index.md`,
28
+ `specs/business/index.md`, `specs/business/features/index.md`).
29
+ 3. Also include, **if they exist**, each repository's `context[]` files from the manifest.
30
+
31
+ > Degrade gracefully: if an expected index is missing, **just note it and continue**.
32
+ > Never fail the warm-up because a specific file is absent.
22
33
 
23
- This file contains ALL essentials:
24
- - Technology stack
25
- - Context hierarchy
26
- - 5 critical rules
27
- - Minimal code patterns
28
- - On-demand loading table
34
+ ## 3. Build the Context Map (the warm-up's output)
29
35
 
30
- ### On Demand (DO NOT load during warm-up)
36
+ Read ONLY the discovered indexes (not the documents they point to). From them, assemble
37
+ and present a **RAG map** — the project's "routing table":
31
38
 
32
- | Need | Document |
33
- |------|----------|
34
- | Generate code | `CLAUDE.meta.md` |
35
- | Architecture | `ARCHITECTURE.md` |
36
- | Specific feature | `features/{FEATURE}.md` |
37
- | Complete anti-patterns | `ANTI_PATTERNS.md` |
39
+ ```
40
+ ## Context Map (RAG)
41
+
42
+ ### Loaded indexes
43
+ - specs/index.md → navigation root
44
+ - specs/technical/index.md → architecture, API, ADRs, conventions
45
+ - specs/business/index.md → personas, journey, strategy
46
+ - ...(only the ones that exist)
47
+
48
+ ### Where to look, on demand
49
+ | Need | Consult (via index) |
50
+ |-------------------------------|--------------------------------------|
51
+ | Architecture / decisions | technical/index.md → ARCHITECTURE / ADRs |
52
+ | API contract | technical/index.md → API_SPECIFICATION |
53
+ | Business rules / feature | business/index.md → features/... |
54
+ | Code conventions | technical/index.md → code guide |
55
+
56
+ ### Repositories (from the manifest)
57
+ - <repo-id> [role] — hints: ...
58
+ ```
38
59
 
39
- ## 3. Verify Repositories
60
+ If an index references documents that don't exist on disk, mark them as
61
+ `(referenced, missing)` — that signals an incomplete spec, not a warm-up error.
40
62
 
41
- For each repository in `context-manifest.json`:
42
- - Verify existence at `{base_path}/{repo-id}/`
43
- - **DO NOT** read README.md now (on demand)
63
+ ## 4. Verify repositories and session
44
64
 
45
- ## 4. Verify Session (if exists)
65
+ - For each repo in the manifest, confirm it exists at `{base_path}/{repo-id}/`
66
+ (do not read README or code now — that's on demand).
67
+ - If an ISSUE-ID was passed, check `.sessions/<ISSUE-ID>/`.
46
68
 
47
- ```bash
48
- ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
49
- ```
69
+ ## 5. How later commands use this
50
70
 
51
- ## 5. Jidoka Principle
71
+ Commands like `/spec`, `/orchestrate` and the agents must NOT scan the repo blindly.
72
+ They should: consult the Context Map → open the relevant index → follow the link to the
73
+ specific document. The index is what optimizes RAG: load little, navigate precisely.
52
74
 
53
- If problems detected: **STOP**, document, alert the user.
75
+ ## 6. Jidoka principle
54
76
 
55
- ---
77
+ If you detect a structural problem (no index found, specs-provider missing):
78
+ **STOP**, describe what's missing, and suggest how to fix it (e.g. create `specs/index.md`
79
+ or fill `orchestration.indexes`). Do not invent context.
56
80
 
57
- **Arguments**: #$ARGUMENTS
81
+ ---
58
82
 
59
- **Status**: Context loaded. Awaiting next command.
83
+ **Status**: Indexes loaded and Context Map built. Awaiting the next command.
package/dist/templates/commands/es/orchestrate.md CHANGED
@@ -94,6 +94,39 @@ Ver `agents/CONTEXT-CONTRACT.md` para el formato exacto. En resumen:
94
94
  - **limits**: `contextPolicy` (por defecto `select-do-not-dump`), `maxFilesPerWorker`
95
95
  - **return**: summary, changes, evidence, tests, unresolved, confidence
96
96
 
97
+ ## Paso 5b — Preparar los worktrees de la sesión (vía git, no Node)
98
+
99
+ Antes de spawnear cualquier agente, crea un **git worktree aislado por repositorio
100
+ impactado** (sólo los del grafo), para que cada implementer tenga dónde escribir sin tocar
101
+ el repo principal. Usa `base_path` (de `ai.properties.md`) y el `<ISSUE-ID>`.
102
+
103
+ Para cada repositorio impactado `<repo>`:
104
+
105
+ 1. Si `.sessions/<ISSUE-ID>/<repo>/` ya existe, **sáltalo** (worktree listo).
106
+ 2. Chequea si la branch `feature/<ISSUE-ID>` ya existe en el repo:
107
+ ```bash
108
+ git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
109
+ ```
110
+ 3. Crea el worktree desde el repo principal:
111
+ - si la branch **no** existe (créala en el worktree):
112
+ ```bash
113
+ git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
114
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
115
+ ```
116
+ - si la branch **ya** existe (reutilízala):
117
+ ```bash
118
+ git -C "{base_path}/<repo>" worktree add \
119
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
120
+ ```
121
+
122
+ Reglas:
123
+ - **Nunca** hagas `checkout` en el repo principal (`{base_path}/<repo>`) — el worktree aísla todo.
124
+ - Si `git worktree add` falla con "already exists", trátalo como listo y continúa.
125
+ - Sólo prepara worktrees de los repos **impactados** del grafo, no de todos los del manifiesto.
126
+ - Registra en `execution-plan.md` qué worktrees se crearon (path + branch).
127
+
128
+ Tras esto, el `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de verdad.
129
+
97
130
  ## Paso 6 — Spawnear los agentes efímeros (Task tool)
98
131
 
99
132
  Ejecuta el DAG respetando `dependsOn`:
package/dist/templates/commands/es/warm-up.md CHANGED
@@ -1,59 +1,83 @@
1
- # Calentamiento - Carga de Contexto
1
+ # Calentamiento — Carga de Contexto (índices para RAG)
2
2
 
3
- Prepara el entorno cargando el contexto optimizado del proyecto.
3
+ Prepara el entorno cargando los **índices de las specs** en un mapa de contexto navegable.
4
+ El objetivo NO es volcar las specs en el contexto, sino cargar los **índices** para que los
5
+ comandos siguientes sepan **dónde buscar** cada información, bajo demanda.
4
6
 
5
- ## 1. Cargar Configuración
7
+ **Argumentos**: `#$ARGUMENTS`
6
8
 
7
- Lee los archivos del orquestador:
8
- - **`context-manifest.json`** - Repositorios y roles
9
- - **`ai.properties.md`** - base_path, task_management_system
9
+ ---
10
10
 
11
- ## 2. Cargar Contexto Compacto (OPTIMIZADO)
11
+ ## 1. Cargar configuración
12
12
 
13
- **IMPORTANTE**: Usa carga PROGRESIVA para economizar la ventana de contexto.
13
+ Lee del orquestador:
14
+ - **`context-manifest.json`** — `repositories[]` (id, role, hints), y el bloque
15
+ `orchestration` (especialmente `indexes`).
16
+ - **`ai.properties.md`** — `base_path`, `task_management_system`.
14
17
 
15
- ### Obligatorio (warm-up)
18
+ Localiza el repo de specs: el de `role: "metaspecs"` (o `"specs-provider"`).
16
19
 
17
- Localiza metaspecs vía `context-manifest.json` (role: "specs-provider"):
20
+ ## 2. Descubrir los índices (dinámico — no exige ningún archivo fijo)
18
21
 
19
- ```
20
- {base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md (~100 líneas)
21
- ```
22
+ Arma la lista de índices a cargar, en este orden de prioridad, **saltando lo que no exista**:
23
+
24
+ 1. Todas las rutas en `orchestration.indexes` del manifiesto (si están definidas).
25
+ 2. Si no hay ninguna, o para complementar, **descubre** los índices en el repo de specs:
26
+ - busca `index.md` / `INDEX.md` bajo `{base_path}/{metaspecs-id}/specs/` y subcarpetas
27
+ (ej.: `specs/index.md`, `specs/technical/index.md`, `specs/business/index.md`,
28
+ `specs/business/features/index.md`).
29
+ 3. Incluye también, **si existen**, los archivos de `context[]` de cada repositorio del manifiesto.
30
+
31
+ > Degrada con gracia: si un índice esperado no existe, **sólo regístralo y continúa**.
32
+ > Nunca falles el calentamiento por la ausencia de un archivo específico.
22
33
 
23
- Este archivo contiene TODOS los esenciales:
24
- - Stack tecnológico
25
- - Jerarquía de contexto
26
- - 5 reglas críticas
27
- - Patrones de código mínimos
28
- - Tabla de carga bajo demanda
34
+ ## 3. Construir el Mapa de Contexto (el producto del calentamiento)
29
35
 
30
- ### Bajo Demanda (NO cargar durante warm-up)
36
+ Lee SÓLO los índices descubiertos (no los documentos que apuntan). A partir de ellos,
37
+ arma y presenta un **mapa de RAG** — la "tabla de ruteo" del proyecto:
31
38
 
32
- | Necesidad | Documento |
33
- |-----------|-----------|
34
- | Generar código | `CLAUDE.meta.md` |
35
- | Arquitectura | `ARCHITECTURE.md` |
36
- | Feature específica | `features/{FEATURE}.md` |
37
- | Anti-patrones completos | `ANTI_PATTERNS.md` |
39
+ ```
40
+ ## Mapa de Contexto (RAG)
41
+
42
+ ### Índices cargados
43
+ - specs/index.md → raíz de navegación
44
+ - specs/technical/index.md → arquitectura, API, ADRs, convenciones
45
+ - specs/business/index.md → personas, journey, estrategia
46
+ - ...(sólo los que existen)
47
+
48
+ ### Dónde buscar bajo demanda
49
+ | Necesidad | Consultar (vía índice) |
50
+ |-------------------------------|--------------------------------------|
51
+ | Arquitectura / decisiones | technical/index.md → ARCHITECTURE / ADRs |
52
+ | Contrato de API | technical/index.md → API_SPECIFICATION |
53
+ | Reglas de negocio / feature | business/index.md → features/... |
54
+ | Convenciones de código | technical/index.md → guía de código |
55
+
56
+ ### Repositorios (del manifiesto)
57
+ - <repo-id> [role] — hints: ...
58
+ ```
38
59
 
39
- ## 3. Verificar Repositorios
60
+ Si un índice referencia documentos que no existen en disco, márcalos como
61
+ `(referenciado, ausente)` — eso indica una spec incompleta, no un error del calentamiento.
40
62
 
41
- Para cada repositorio en `context-manifest.json`:
42
- - Verificar existencia en `{base_path}/{repo-id}/`
43
- - **NO** leer README.md ahora (bajo demanda)
63
+ ## 4. Verificar repositorios y sesión
44
64
 
45
- ## 4. Verificar Sesión (si existe)
65
+ - Para cada repo del manifiesto, confirma que existe en `{base_path}/{repo-id}/`
66
+ (no leas README ni código ahora — eso es bajo demanda).
67
+ - Si se pasó un ISSUE-ID, verifica `.sessions/<ISSUE-ID>/`.
46
68
 
47
- ```bash
48
- ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
49
- ```
69
+ ## 5. Cómo los comandos siguientes usan esto
50
70
 
51
- ## 5. Principio Jidoka
71
+ Comandos como `/spec`, `/orchestrate` y los agentes NO deben escanear el repo a ciegas.
72
+ Deben: consultar el Mapa de Contexto → abrir el índice relevante → seguir el link al
73
+ documento específico. El índice es lo que optimiza el RAG: cargar poco, navegar con precisión.
52
74
 
53
- Si se detectan problemas: **PARA**, documenta, alerta al usuario.
75
+ ## 6. Principio Jidoka
54
76
 
55
- ---
77
+ Si detectas un problema estructural (ningún índice encontrado, specs-provider ausente):
78
+ **DETENTE**, describe qué falta y sugiere cómo corregirlo (ej.: crear `specs/index.md` o
79
+ completar `orchestration.indexes`). No inventes contexto.
56
80
 
57
- **Argumentos**: #$ARGUMENTS
81
+ ---
58
82
 
59
- **Estado**: Contexto cargado. Esperando próximo comando.
83
+ **Estado**: Índices cargados y Mapa de Contexto armado. Esperando el próximo comando.
package/dist/templates/commands/pt-BR/orchestrate.md CHANGED
@@ -94,6 +94,39 @@ Veja `agents/CONTEXT-CONTRACT.md` para o formato exato. Em resumo:
94
94
  - **limits**: `contextPolicy` (padrão `select-do-not-dump`), `maxFilesPerWorker`
95
95
  - **return**: summary, changes, evidence, tests, unresolved, confidence
96
96
 
97
+ ## Passo 5b — Preparar os worktrees da sessão (via git, não Node)
98
+
99
+ Antes de spawnar qualquer agente, crie um **git worktree isolado por repositório
100
+ impactado** (só os do grafo), para que cada implementer tenha onde escrever sem tocar no
101
+ repo principal. Use `base_path` (de `ai.properties.md`) e o `<ISSUE-ID>`.
102
+
103
+ Para cada repositório impactado `<repo>`:
104
+
105
+ 1. Se `.sessions/<ISSUE-ID>/<repo>/` já existir, **pule** (worktree já preparado).
106
+ 2. Descubra se a branch `feature/<ISSUE-ID>` já existe no repo:
107
+ ```bash
108
+ git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
109
+ ```
110
+ 3. Crie o worktree a partir do repo principal:
111
+ - se a branch **não** existe (cria a branch no worktree):
112
+ ```bash
113
+ git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
114
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
115
+ ```
116
+ - se a branch **já** existe (reaproveita):
117
+ ```bash
118
+ git -C "{base_path}/<repo>" worktree add \
119
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
120
+ ```
121
+
122
+ Regras:
123
+ - **Nunca** faça `checkout` no repo principal (`{base_path}/<repo>`) — o worktree isola tudo.
124
+ - Se `git worktree add` falhar por "already exists", trate como já preparado e siga.
125
+ - Só prepare worktrees dos repos **impactados** pelo grafo, não de todos do manifesto.
126
+ - Registre no `execution-plan.md` quais worktrees foram criados (path + branch).
127
+
128
+ Depois disso, o `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de fato.
129
+
97
130
  ## Passo 6 — Spawnar os agentes efêmeros (Task tool)
98
131
 
99
132
  Execute o DAG respeitando `dependsOn`:
package/dist/templates/commands/pt-BR/warm-up.md CHANGED
@@ -1,59 +1,83 @@
1
- # Aquecimento - Carregamento de Contexto
1
+ # Aquecimento — Carregamento de Contexto (índices para RAG)
2
2
 
3
- Prepara o ambiente carregando o contexto otimizado do projeto.
3
+ Prepara o ambiente carregando os **índices das specs** para um mapa de contexto navegável.
4
+ O objetivo NÃO é despejar as specs no contexto, e sim carregar os **índices** para que
5
+ comandos seguintes saibam **onde buscar** cada informação sob demanda.
4
6
 
5
- ## 1. Carregar Configuração
7
+ **Argumentos**: `#$ARGUMENTS`
6
8
 
7
- Leia os arquivos do orchestrator:
8
- - **`context-manifest.json`** - Repositórios e roles
9
- - **`ai.properties.md`** - base_path, task_management_system
9
+ ---
10
10
 
11
- ## 2. Carregar Contexto Compacto (OTIMIZADO)
11
+ ## 1. Carregar configuração
12
12
 
13
- **IMPORTANTE**: Use carregamento PROGRESSIVO para economizar janela de contexto.
13
+ Leia do orchestrator:
14
+ - **`context-manifest.json`** — `repositories[]` (id, role, hints), e o bloco
15
+ `orchestration` (especialmente `indexes`).
16
+ - **`ai.properties.md`** — `base_path`, `task_management_system`.
14
17
 
15
- ### Obrigatório (warm-up)
18
+ Localize o repositório de specs: o de `role: "metaspecs"` (ou `"specs-provider"`).
16
19
 
17
- Localize metaspecs via `context-manifest.json` (role: "specs-provider"):
20
+ ## 2. Descobrir os índices (dinâmico — não exige nenhum arquivo fixo)
18
21
 
19
- ```
20
- {base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md (~100 linhas)
21
- ```
22
+ Monte a lista de índices a carregar, nesta ordem de prioridade, **pulando o que não existir**:
23
+
24
+ 1. Todos os caminhos em `orchestration.indexes` do manifest (se definidos).
25
+ 2. Se nenhum foi definido, ou para complementar, **descubra** os índices no repo de specs:
26
+ - procure por `index.md` / `INDEX.md` em `{base_path}/{metaspecs-id}/specs/` e subpastas
27
+ (ex.: `specs/index.md`, `specs/technical/index.md`, `specs/business/index.md`,
28
+ `specs/business/features/index.md`).
29
+ 3. Inclua também, **se existirem**, os arquivos de `context[]` de cada repositório do manifest.
30
+
31
+ > Degrade graciosamente: se um índice esperado não existir, **apenas registre e continue**.
32
+ > Nunca falhe o warm-up por falta de um arquivo específico.
22
33
 
23
- Este arquivo contém TODOS os essenciais:
24
- - Stack tecnológica
25
- - Hierarquia de contexto
26
- - 5 regras críticas
27
- - Padrões de código mínimos
28
- - Tabela de carregamento sob demanda
34
+ ## 3. Construir o Mapa de Contexto (o produto do warm-up)
29
35
 
30
- ### Sob Demanda (NÃO carregar durante warm-up)
36
+ Leia SOMENTE os índices descobertos (não os documentos que eles apontam). A partir deles,
37
+ monte e apresente um **mapa de RAG** — a "tabela de roteamento" do projeto:
31
38
 
32
- | Necessidade | Documento |
33
- |-------------|-----------|
34
- | Gerar código | `CLAUDE.meta.md` |
35
- | Arquitetura | `ARCHITECTURE.md` |
36
- | Feature específica | `features/{FEATURE}.md` |
37
- | Anti-patterns completos | `ANTI_PATTERNS.md` |
39
+ ```
40
+ ## Mapa de Contexto (RAG)
41
+
42
+ ### Índices carregados
43
+ - specs/index.md → raiz da navegação
44
+ - specs/technical/index.md → arquitetura, API, ADRs, convenções
45
+ - specs/business/index.md → personas, jornada, estratégia
46
+ - ...(apenas os que existem)
47
+
48
+ ### Onde buscar sob demanda
49
+ | Necessidade | Consultar (via índice) |
50
+ |---------------------------------|-------------------------------------|
51
+ | Arquitetura / decisões | technical/index.md → ARCHITECTURE / ADRs |
52
+ | Contrato de API | technical/index.md → API_SPECIFICATION |
53
+ | Regras de negócio / feature | business/index.md → features/... |
54
+ | Convenções de código | technical/index.md → guia de código |
55
+
56
+ ### Repositórios (do manifest)
57
+ - <repo-id> [role] — hints: ...
58
+ ```
38
59
 
39
- ## 3. Verificar Repositórios
60
+ Se um índice referenciar documentos que não existem em disco, marque como
61
+ `(referenciado, ausente)` — isso é sinal de spec incompleta, não um erro do warm-up.
40
62
 
41
- Para cada repositório no `context-manifest.json`:
42
- - Verificar existência em `{base_path}/{repo-id}/`
43
- - **NÃO** ler README.md agora (sob demanda)
63
+ ## 4. Verificar repositórios e sessão
44
64
 
45
- ## 4. Verificar Sessão (se existir)
65
+ - Para cada repo do manifest, confirme existência em `{base_path}/{repo-id}/`
66
+ (não leia README nem código agora — isso é sob demanda).
67
+ - Se um ISSUE-ID foi passado, verifique `.sessions/<ISSUE-ID>/`.
46
68
 
47
- ```bash
48
- ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
49
- ```
69
+ ## 5. Como comandos seguintes usam isto
50
70
 
51
- ## 5. Princípio Jidoka
71
+ Comandos como `/spec`, `/orchestrate` e os agentes NÃO devem varrer o repo às cegas.
72
+ Eles devem: consultar o Mapa de Contexto → abrir o índice relevante → seguir o link para
73
+ o documento específico. É o índice que otimiza o RAG: carrega-se pouco, e navega-se com precisão.
52
74
 
53
- Se problemas detectados: **PARE**, documente, alerte o usuário.
75
+ ## 6. Princípio Jidoka
54
76
 
55
- ---
77
+ Se detectar um problema estrutural (nenhum índice encontrado, specs-provider ausente):
78
+ **PARE**, descreva o que falta e sugira ao usuário como corrigir (ex.: criar
79
+ `specs/index.md` ou preencher `orchestration.indexes`). Não invente contexto.
56
80
 
57
- **Argumentos**: #$ARGUMENTS
81
+ ---
58
82
 
59
- **Status**: Contexto carregado. Aguardando próximo comando.
83
+ **Status**: Índices carregados e Mapa de Contexto montado. Aguardando o próximo comando.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thatix.io/context-first-agents-cli",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
package/templates/commands/en/orchestrate.md CHANGED
@@ -93,6 +93,39 @@ See `agents/CONTEXT-CONTRACT.md` for the exact shape. In short:
93
93
  - **limits**: `contextPolicy` (default `select-do-not-dump`), `maxFilesPerWorker`
94
94
  - **return**: summary, changes, evidence, tests, unresolved questions, confidence
95
95
 
96
+ ## Step 5b — Prepare the session worktrees (via git, not Node)
97
+
98
+ Before spawning any agent, create an **isolated git worktree per impacted repository**
99
+ (only the ones in the graph), so each implementer has a place to write without touching
100
+ the main repo. Use `base_path` (from `ai.properties.md`) and the `<ISSUE-ID>`.
101
+
102
+ For each impacted repository `<repo>`:
103
+
104
+ 1. If `.sessions/<ISSUE-ID>/<repo>/` already exists, **skip** (worktree ready).
105
+ 2. Check whether branch `feature/<ISSUE-ID>` already exists in the repo:
106
+ ```bash
107
+ git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
108
+ ```
109
+ 3. Create the worktree from the main repo:
110
+ - if the branch does **not** exist (create it in the worktree):
111
+ ```bash
112
+ git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
113
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
114
+ ```
115
+ - if the branch **already** exists (reuse it):
116
+ ```bash
117
+ git -C "{base_path}/<repo>" worktree add \
118
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
119
+ ```
120
+
121
+ Rules:
122
+ - **Never** `checkout` in the main repo (`{base_path}/<repo>`) — the worktree isolates everything.
123
+ - If `git worktree add` fails with "already exists", treat it as ready and continue.
124
+ - Only prepare worktrees for the **impacted** repos in the graph, not every repo in the manifest.
125
+ - Record in `execution-plan.md` which worktrees were created (path + branch).
126
+
127
+ After this, each agent's `writeBoundary` (`.sessions/<ISSUE-ID>/<repo>/`) actually exists.
128
+
96
129
  ## Step 6 — Spawn ephemeral agents (Task tool)
97
130
 
98
131
  Execute the DAG respecting `dependsOn`:
package/templates/commands/en/warm-up.md CHANGED
@@ -1,59 +1,83 @@
1
- # Warm-up - Context Loading
1
+ # Warm-up — Context Loading (spec indexes for RAG)
2
2
 
3
- Prepares the environment by loading optimized project context.
3
+ Prepares the environment by loading the **spec indexes** into a navigable context map.
4
+ The goal is NOT to dump the specs into context, but to load the **indexes** so later
5
+ commands know **where to look** for each piece of information, on demand.
4
6
 
5
- ## 1. Load Configuration
7
+ **Arguments**: `#$ARGUMENTS`
6
8
 
7
- Read the orchestrator files:
8
- - **`context-manifest.json`** - Repositories and roles
9
- - **`ai.properties.md`** - base_path, task_management_system
9
+ ---
10
10
 
11
- ## 2. Load Compact Context (OPTIMIZED)
11
+ ## 1. Load configuration
12
12
 
13
- **IMPORTANT**: Use PROGRESSIVE loading to save context window.
13
+ Read from the orchestrator:
14
+ - **`context-manifest.json`** — `repositories[]` (id, role, hints), and the
15
+ `orchestration` block (especially `indexes`).
16
+ - **`ai.properties.md`** — `base_path`, `task_management_system`.
14
17
 
15
- ### Required (warm-up)
18
+ Locate the specs repo: the one with `role: "metaspecs"` (or `"specs-provider"`).
16
19
 
17
- Locate metaspecs via `context-manifest.json` (role: "specs-provider"):
20
+ ## 2. Discover the indexes (dynamic — requires no fixed file)
18
21
 
19
- ```
20
- {base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md (~100 lines)
21
- ```
22
+ Build the list of indexes to load, in this priority order, **skipping whatever doesn't exist**:
23
+
24
+ 1. Every path in the manifest's `orchestration.indexes` (if defined).
25
+ 2. If none are defined, or to complement, **discover** indexes in the specs repo:
26
+ - look for `index.md` / `INDEX.md` under `{base_path}/{metaspecs-id}/specs/` and
27
+ subfolders (e.g. `specs/index.md`, `specs/technical/index.md`,
28
+ `specs/business/index.md`, `specs/business/features/index.md`).
29
+ 3. Also include, **if they exist**, each repository's `context[]` files from the manifest.
30
+
31
+ > Degrade gracefully: if an expected index is missing, **just note it and continue**.
32
+ > Never fail the warm-up because a specific file is absent.
22
33
 
23
- This file contains ALL essentials:
24
- - Technology stack
25
- - Context hierarchy
26
- - 5 critical rules
27
- - Minimal code patterns
28
- - On-demand loading table
34
+ ## 3. Build the Context Map (the warm-up's output)
29
35
 
30
- ### On Demand (DO NOT load during warm-up)
36
+ Read ONLY the discovered indexes (not the documents they point to). From them, assemble
37
+ and present a **RAG map** — the project's "routing table":
31
38
 
32
- | Need | Document |
33
- |------|----------|
34
- | Generate code | `CLAUDE.meta.md` |
35
- | Architecture | `ARCHITECTURE.md` |
36
- | Specific feature | `features/{FEATURE}.md` |
37
- | Complete anti-patterns | `ANTI_PATTERNS.md` |
39
+ ```
40
+ ## Context Map (RAG)
41
+
42
+ ### Loaded indexes
43
+ - specs/index.md → navigation root
44
+ - specs/technical/index.md → architecture, API, ADRs, conventions
45
+ - specs/business/index.md → personas, journey, strategy
46
+ - ...(only the ones that exist)
47
+
48
+ ### Where to look, on demand
49
+ | Need | Consult (via index) |
50
+ |-------------------------------|--------------------------------------|
51
+ | Architecture / decisions | technical/index.md → ARCHITECTURE / ADRs |
52
+ | API contract | technical/index.md → API_SPECIFICATION |
53
+ | Business rules / feature | business/index.md → features/... |
54
+ | Code conventions | technical/index.md → code guide |
55
+
56
+ ### Repositories (from the manifest)
57
+ - <repo-id> [role] — hints: ...
58
+ ```
38
59
 
39
- ## 3. Verify Repositories
60
+ If an index references documents that don't exist on disk, mark them as
61
+ `(referenced, missing)` — that signals an incomplete spec, not a warm-up error.
40
62
 
41
- For each repository in `context-manifest.json`:
42
- - Verify existence at `{base_path}/{repo-id}/`
43
- - **DO NOT** read README.md now (on demand)
63
+ ## 4. Verify repositories and session
44
64
 
45
- ## 4. Verify Session (if exists)
65
+ - For each repo in the manifest, confirm it exists at `{base_path}/{repo-id}/`
66
+ (do not read README or code now — that's on demand).
67
+ - If an ISSUE-ID was passed, check `.sessions/<ISSUE-ID>/`.
46
68
 
47
- ```bash
48
- ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
49
- ```
69
+ ## 5. How later commands use this
50
70
 
51
- ## 5. Jidoka Principle
71
+ Commands like `/spec`, `/orchestrate` and the agents must NOT scan the repo blindly.
72
+ They should: consult the Context Map → open the relevant index → follow the link to the
73
+ specific document. The index is what optimizes RAG: load little, navigate precisely.
52
74
 
53
- If problems detected: **STOP**, document, alert the user.
75
+ ## 6. Jidoka principle
54
76
 
55
- ---
77
+ If you detect a structural problem (no index found, specs-provider missing):
78
+ **STOP**, describe what's missing, and suggest how to fix it (e.g. create `specs/index.md`
79
+ or fill `orchestration.indexes`). Do not invent context.
56
80
 
57
- **Arguments**: #$ARGUMENTS
81
+ ---
58
82
 
59
- **Status**: Context loaded. Awaiting next command.
83
+ **Status**: Indexes loaded and Context Map built. Awaiting the next command.
package/templates/commands/es/orchestrate.md CHANGED
@@ -94,6 +94,39 @@ Ver `agents/CONTEXT-CONTRACT.md` para el formato exacto. En resumen:
94
94
  - **limits**: `contextPolicy` (por defecto `select-do-not-dump`), `maxFilesPerWorker`
95
95
  - **return**: summary, changes, evidence, tests, unresolved, confidence
96
96
 
97
+ ## Paso 5b — Preparar los worktrees de la sesión (vía git, no Node)
98
+
99
+ Antes de spawnear cualquier agente, crea un **git worktree aislado por repositorio
100
+ impactado** (sólo los del grafo), para que cada implementer tenga dónde escribir sin tocar
101
+ el repo principal. Usa `base_path` (de `ai.properties.md`) y el `<ISSUE-ID>`.
102
+
103
+ Para cada repositorio impactado `<repo>`:
104
+
105
+ 1. Si `.sessions/<ISSUE-ID>/<repo>/` ya existe, **sáltalo** (worktree listo).
106
+ 2. Chequea si la branch `feature/<ISSUE-ID>` ya existe en el repo:
107
+ ```bash
108
+ git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
109
+ ```
110
+ 3. Crea el worktree desde el repo principal:
111
+ - si la branch **no** existe (créala en el worktree):
112
+ ```bash
113
+ git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
114
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
115
+ ```
116
+ - si la branch **ya** existe (reutilízala):
117
+ ```bash
118
+ git -C "{base_path}/<repo>" worktree add \
119
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
120
+ ```
121
+
122
+ Reglas:
123
+ - **Nunca** hagas `checkout` en el repo principal (`{base_path}/<repo>`) — el worktree aísla todo.
124
+ - Si `git worktree add` falla con "already exists", trátalo como listo y continúa.
125
+ - Sólo prepara worktrees de los repos **impactados** del grafo, no de todos los del manifiesto.
126
+ - Registra en `execution-plan.md` qué worktrees se crearon (path + branch).
127
+
128
+ Tras esto, el `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de verdad.
129
+
97
130
  ## Paso 6 — Spawnear los agentes efímeros (Task tool)
98
131
 
99
132
  Ejecuta el DAG respetando `dependsOn`:
package/templates/commands/es/warm-up.md CHANGED
@@ -1,59 +1,83 @@
1
- # Calentamiento - Carga de Contexto
1
+ # Calentamiento — Carga de Contexto (índices para RAG)
2
2
 
3
- Prepara el entorno cargando el contexto optimizado del proyecto.
3
+ Prepara el entorno cargando los **índices de las specs** en un mapa de contexto navegable.
4
+ El objetivo NO es volcar las specs en el contexto, sino cargar los **índices** para que los
5
+ comandos siguientes sepan **dónde buscar** cada información, bajo demanda.
4
6
 
5
- ## 1. Cargar Configuración
7
+ **Argumentos**: `#$ARGUMENTS`
6
8
 
7
- Lee los archivos del orquestador:
8
- - **`context-manifest.json`** - Repositorios y roles
9
- - **`ai.properties.md`** - base_path, task_management_system
9
+ ---
10
10
 
11
- ## 2. Cargar Contexto Compacto (OPTIMIZADO)
11
+ ## 1. Cargar configuración
12
12
 
13
- **IMPORTANTE**: Usa carga PROGRESIVA para economizar la ventana de contexto.
13
+ Lee del orquestador:
14
+ - **`context-manifest.json`** — `repositories[]` (id, role, hints), y el bloque
15
+ `orchestration` (especialmente `indexes`).
16
+ - **`ai.properties.md`** — `base_path`, `task_management_system`.
14
17
 
15
- ### Obligatorio (warm-up)
18
+ Localiza el repo de specs: el de `role: "metaspecs"` (o `"specs-provider"`).
16
19
 
17
- Localiza metaspecs vía `context-manifest.json` (role: "specs-provider"):
20
+ ## 2. Descubrir los índices (dinámico — no exige ningún archivo fijo)
18
21
 
19
- ```
20
- {base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md (~100 líneas)
21
- ```
22
+ Arma la lista de índices a cargar, en este orden de prioridad, **saltando lo que no exista**:
23
+
24
+ 1. Todas las rutas en `orchestration.indexes` del manifiesto (si están definidas).
25
+ 2. Si no hay ninguna, o para complementar, **descubre** los índices en el repo de specs:
26
+ - busca `index.md` / `INDEX.md` bajo `{base_path}/{metaspecs-id}/specs/` y subcarpetas
27
+ (ej.: `specs/index.md`, `specs/technical/index.md`, `specs/business/index.md`,
28
+ `specs/business/features/index.md`).
29
+ 3. Incluye también, **si existen**, los archivos de `context[]` de cada repositorio del manifiesto.
30
+
31
+ > Degrada con gracia: si un índice esperado no existe, **sólo regístralo y continúa**.
32
+ > Nunca falles el calentamiento por la ausencia de un archivo específico.
22
33
 
23
- Este archivo contiene TODOS los esenciales:
24
- - Stack tecnológico
25
- - Jerarquía de contexto
26
- - 5 reglas críticas
27
- - Patrones de código mínimos
28
- - Tabla de carga bajo demanda
34
+ ## 3. Construir el Mapa de Contexto (el producto del calentamiento)
29
35
 
30
- ### Bajo Demanda (NO cargar durante warm-up)
36
+ Lee SÓLO los índices descubiertos (no los documentos que apuntan). A partir de ellos,
37
+ arma y presenta un **mapa de RAG** — la "tabla de ruteo" del proyecto:
31
38
 
32
- | Necesidad | Documento |
33
- |-----------|-----------|
34
- | Generar código | `CLAUDE.meta.md` |
35
- | Arquitectura | `ARCHITECTURE.md` |
36
- | Feature específica | `features/{FEATURE}.md` |
37
- | Anti-patrones completos | `ANTI_PATTERNS.md` |
39
+ ```
40
+ ## Mapa de Contexto (RAG)
41
+
42
+ ### Índices cargados
43
+ - specs/index.md → raíz de navegación
44
+ - specs/technical/index.md → arquitectura, API, ADRs, convenciones
45
+ - specs/business/index.md → personas, journey, estrategia
46
+ - ...(sólo los que existen)
47
+
48
+ ### Dónde buscar bajo demanda
49
+ | Necesidad | Consultar (vía índice) |
50
+ |-------------------------------|--------------------------------------|
51
+ | Arquitectura / decisiones | technical/index.md → ARCHITECTURE / ADRs |
52
+ | Contrato de API | technical/index.md → API_SPECIFICATION |
53
+ | Reglas de negocio / feature | business/index.md → features/... |
54
+ | Convenciones de código | technical/index.md → guía de código |
55
+
56
+ ### Repositorios (del manifiesto)
57
+ - <repo-id> [role] — hints: ...
58
+ ```
38
59
 
39
- ## 3. Verificar Repositorios
60
+ Si un índice referencia documentos que no existen en disco, márcalos como
61
+ `(referenciado, ausente)` — eso indica una spec incompleta, no un error del calentamiento.
40
62
 
41
- Para cada repositorio en `context-manifest.json`:
42
- - Verificar existencia en `{base_path}/{repo-id}/`
43
- - **NO** leer README.md ahora (bajo demanda)
63
+ ## 4. Verificar repositorios y sesión
44
64
 
45
- ## 4. Verificar Sesión (si existe)
65
+ - Para cada repo del manifiesto, confirma que existe en `{base_path}/{repo-id}/`
66
+ (no leas README ni código ahora — eso es bajo demanda).
67
+ - Si se pasó un ISSUE-ID, verifica `.sessions/<ISSUE-ID>/`.
46
68
 
47
- ```bash
48
- ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
49
- ```
69
+ ## 5. Cómo los comandos siguientes usan esto
50
70
 
51
- ## 5. Principio Jidoka
71
+ Comandos como `/spec`, `/orchestrate` y los agentes NO deben escanear el repo a ciegas.
72
+ Deben: consultar el Mapa de Contexto → abrir el índice relevante → seguir el link al
73
+ documento específico. El índice es lo que optimiza el RAG: cargar poco, navegar con precisión.
52
74
 
53
- Si se detectan problemas: **PARA**, documenta, alerta al usuario.
75
+ ## 6. Principio Jidoka
54
76
 
55
- ---
77
+ Si detectas un problema estructural (ningún índice encontrado, specs-provider ausente):
78
+ **DETENTE**, describe qué falta y sugiere cómo corregirlo (ej.: crear `specs/index.md` o
79
+ completar `orchestration.indexes`). No inventes contexto.
56
80
 
57
- **Argumentos**: #$ARGUMENTS
81
+ ---
58
82
 
59
- **Estado**: Contexto cargado. Esperando próximo comando.
83
+ **Estado**: Índices cargados y Mapa de Contexto armado. Esperando el próximo comando.
package/templates/commands/pt-BR/orchestrate.md CHANGED
@@ -94,6 +94,39 @@ Veja `agents/CONTEXT-CONTRACT.md` para o formato exato. Em resumo:
94
94
  - **limits**: `contextPolicy` (padrão `select-do-not-dump`), `maxFilesPerWorker`
95
95
  - **return**: summary, changes, evidence, tests, unresolved, confidence
96
96
 
97
+ ## Passo 5b — Preparar os worktrees da sessão (via git, não Node)
98
+
99
+ Antes de spawnar qualquer agente, crie um **git worktree isolado por repositório
100
+ impactado** (só os do grafo), para que cada implementer tenha onde escrever sem tocar no
101
+ repo principal. Use `base_path` (de `ai.properties.md`) e o `<ISSUE-ID>`.
102
+
103
+ Para cada repositório impactado `<repo>`:
104
+
105
+ 1. Se `.sessions/<ISSUE-ID>/<repo>/` já existir, **pule** (worktree já preparado).
106
+ 2. Descubra se a branch `feature/<ISSUE-ID>` já existe no repo:
107
+ ```bash
108
+ git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
109
+ ```
110
+ 3. Crie o worktree a partir do repo principal:
111
+ - se a branch **não** existe (cria a branch no worktree):
112
+ ```bash
113
+ git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
114
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
115
+ ```
116
+ - se a branch **já** existe (reaproveita):
117
+ ```bash
118
+ git -C "{base_path}/<repo>" worktree add \
119
+ "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
120
+ ```
121
+
122
+ Regras:
123
+ - **Nunca** faça `checkout` no repo principal (`{base_path}/<repo>`) — o worktree isola tudo.
124
+ - Se `git worktree add` falhar por "already exists", trate como já preparado e siga.
125
+ - Só prepare worktrees dos repos **impactados** pelo grafo, não de todos do manifesto.
126
+ - Registre no `execution-plan.md` quais worktrees foram criados (path + branch).
127
+
128
+ Depois disso, o `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de fato.
129
+
97
130
  ## Passo 6 — Spawnar os agentes efêmeros (Task tool)
98
131
 
99
132
  Execute o DAG respeitando `dependsOn`:
package/templates/commands/pt-BR/warm-up.md CHANGED
@@ -1,59 +1,83 @@
1
- # Aquecimento - Carregamento de Contexto
1
+ # Aquecimento — Carregamento de Contexto (índices para RAG)
2
2
 
3
- Prepara o ambiente carregando o contexto otimizado do projeto.
3
+ Prepara o ambiente carregando os **índices das specs** para um mapa de contexto navegável.
4
+ O objetivo NÃO é despejar as specs no contexto, e sim carregar os **índices** para que
5
+ comandos seguintes saibam **onde buscar** cada informação sob demanda.
4
6
 
5
- ## 1. Carregar Configuração
7
+ **Argumentos**: `#$ARGUMENTS`
6
8
 
7
- Leia os arquivos do orchestrator:
8
- - **`context-manifest.json`** - Repositórios e roles
9
- - **`ai.properties.md`** - base_path, task_management_system
9
+ ---
10
10
 
11
- ## 2. Carregar Contexto Compacto (OTIMIZADO)
11
+ ## 1. Carregar configuração
12
12
 
13
- **IMPORTANTE**: Use carregamento PROGRESSIVO para economizar janela de contexto.
13
+ Leia do orchestrator:
14
+ - **`context-manifest.json`** — `repositories[]` (id, role, hints), e o bloco
15
+ `orchestration` (especialmente `indexes`).
16
+ - **`ai.properties.md`** — `base_path`, `task_management_system`.
14
17
 
15
- ### Obrigatório (warm-up)
18
+ Localize o repositório de specs: o de `role: "metaspecs"` (ou `"specs-provider"`).
16
19
 
17
- Localize metaspecs via `context-manifest.json` (role: "specs-provider"):
20
+ ## 2. Descobrir os índices (dinâmico — não exige nenhum arquivo fixo)
18
21
 
19
- ```
20
- {base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md (~100 linhas)
21
- ```
22
+ Monte a lista de índices a carregar, nesta ordem de prioridade, **pulando o que não existir**:
23
+
24
+ 1. Todos os caminhos em `orchestration.indexes` do manifest (se definidos).
25
+ 2. Se nenhum foi definido, ou para complementar, **descubra** os índices no repo de specs:
26
+ - procure por `index.md` / `INDEX.md` em `{base_path}/{metaspecs-id}/specs/` e subpastas
27
+ (ex.: `specs/index.md`, `specs/technical/index.md`, `specs/business/index.md`,
28
+ `specs/business/features/index.md`).
29
+ 3. Inclua também, **se existirem**, os arquivos de `context[]` de cada repositório do manifest.
30
+
31
+ > Degrade graciosamente: se um índice esperado não existir, **apenas registre e continue**.
32
+ > Nunca falhe o warm-up por falta de um arquivo específico.
22
33
 
23
- Este arquivo contém TODOS os essenciais:
24
- - Stack tecnológica
25
- - Hierarquia de contexto
26
- - 5 regras críticas
27
- - Padrões de código mínimos
28
- - Tabela de carregamento sob demanda
34
+ ## 3. Construir o Mapa de Contexto (o produto do warm-up)
29
35
 
30
- ### Sob Demanda (NÃO carregar durante warm-up)
36
+ Leia SOMENTE os índices descobertos (não os documentos que eles apontam). A partir deles,
37
+ monte e apresente um **mapa de RAG** — a "tabela de roteamento" do projeto:
31
38
 
32
- | Necessidade | Documento |
33
- |-------------|-----------|
34
- | Gerar código | `CLAUDE.meta.md` |
35
- | Arquitetura | `ARCHITECTURE.md` |
36
- | Feature específica | `features/{FEATURE}.md` |
37
- | Anti-patterns completos | `ANTI_PATTERNS.md` |
39
+ ```
40
+ ## Mapa de Contexto (RAG)
41
+
42
+ ### Índices carregados
43
+ - specs/index.md → raiz da navegação
44
+ - specs/technical/index.md → arquitetura, API, ADRs, convenções
45
+ - specs/business/index.md → personas, jornada, estratégia
46
+ - ...(apenas os que existem)
47
+
48
+ ### Onde buscar sob demanda
49
+ | Necessidade | Consultar (via índice) |
50
+ |---------------------------------|-------------------------------------|
51
+ | Arquitetura / decisões | technical/index.md → ARCHITECTURE / ADRs |
52
+ | Contrato de API | technical/index.md → API_SPECIFICATION |
53
+ | Regras de negócio / feature | business/index.md → features/... |
54
+ | Convenções de código | technical/index.md → guia de código |
55
+
56
+ ### Repositórios (do manifest)
57
+ - <repo-id> [role] — hints: ...
58
+ ```
38
59
 
39
- ## 3. Verificar Repositórios
60
+ Se um índice referenciar documentos que não existem em disco, marque como
61
+ `(referenciado, ausente)` — isso é sinal de spec incompleta, não um erro do warm-up.
40
62
 
41
- Para cada repositório no `context-manifest.json`:
42
- - Verificar existência em `{base_path}/{repo-id}/`
43
- - **NÃO** ler README.md agora (sob demanda)
63
+ ## 4. Verificar repositórios e sessão
44
64
 
45
- ## 4. Verificar Sessão (se existir)
65
+ - Para cada repo do manifest, confirme existência em `{base_path}/{repo-id}/`
66
+ (não leia README nem código agora — isso é sob demanda).
67
+ - Se um ISSUE-ID foi passado, verifique `.sessions/<ISSUE-ID>/`.
46
68
 
47
- ```bash
48
- ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
49
- ```
69
+ ## 5. Como comandos seguintes usam isto
50
70
 
51
- ## 5. Princípio Jidoka
71
+ Comandos como `/spec`, `/orchestrate` e os agentes NÃO devem varrer o repo às cegas.
72
+ Eles devem: consultar o Mapa de Contexto → abrir o índice relevante → seguir o link para
73
+ o documento específico. É o índice que otimiza o RAG: carrega-se pouco, e navega-se com precisão.
52
74
 
53
- Se problemas detectados: **PARE**, documente, alerte o usuário.
75
+ ## 6. Princípio Jidoka
54
76
 
55
- ---
77
+ Se detectar um problema estrutural (nenhum índice encontrado, specs-provider ausente):
78
+ **PARE**, descreva o que falta e sugira ao usuário como corrigir (ex.: criar
79
+ `specs/index.md` ou preencher `orchestration.indexes`). Não invente contexto.
56
80
 
57
- **Argumentos**: #$ARGUMENTS
81
+ ---
58
82
 
59
- **Status**: Contexto carregado. Aguardando próximo comando.
83
+ **Status**: Índices carregados e Mapa de Contexto montado. Aguardando o próximo comando.