@thatix.io/context-first-agents-cli 0.1.1 → 0.2.1

package/templates/commands/en/quality/metrics.md

@@ -0,0 +1,266 @@
+# Quality Metrics
+
+This command collects and analyzes quality metrics of the code and the development process.
+
+## 🎯 Objective
+
+Measure and document the quality of the implementation through objective metrics:
+- Test coverage
+- Code complexity
+- Technical debt
+- Performance
+- Compliance with standards
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📋 Prerequisites
+
+- Implementation completed (after `/work`)
+- Tests implemented
+- Build working
+
+## 📊 Metrics to Collect
+
+### 1. Test Coverage
+
+For each modified repository:
+
+```bash
+cd <repository>
+
+# Run tests with coverage (examples by stack):
+# Node.js: npm run test:coverage / jest --coverage
+# Python: pytest --cov=src tests/
+# Java: mvn jacoco:report / gradle jacocoTestReport
+# Go: go test -cover ./...
+# Ruby: rspec --coverage
+# Rust: cargo tarpaulin
+# PHP: ./vendor/bin/phpunit --coverage-html coverage/
+# C#: dotnet test /p:CollectCoverage=true
+
+# Capture results
+```
+
+Document:
+```markdown
+## Test Coverage
+
+### <repo-1>
+- **Total Coverage**: X%
+- **Statements**: X%
+- **Branches**: X%
+- **Functions**: X%
+- **Lines**: X%
+- **Uncovered Files**: [list]
+
+### <repo-2>
+[Same format]
+```
+
+### 2. Code Complexity
+
+Analyze the cyclomatic complexity of modified files:
+
+```markdown
+## Code Complexity
+
+### Files with High Complexity
+- **file1.ts**: Complexity 15 (recommended: < 10)
+- **file2.ts**: Complexity 12
+
+### Recommendations
+- [Refactoring suggestion 1]
+- [Refactoring suggestion 2]
+```
+
+### 3. Code Quality
+
+```bash
+# Run linting (examples by stack):
+# Node.js: npm run lint / eslint .
+# Python: flake8 . / pylint src/
+# Java: mvn checkstyle:check
+# Go: golangci-lint run
+# Ruby: rubocop
+# Rust: cargo clippy
+
+# Check formatting (examples by stack):
+# Node.js: prettier --check .
+# Python: black --check .
+# Java: mvn formatter:validate
+# Go: gofmt -l .
+# Ruby: rubocop --format-only
+# Rust: cargo fmt --check
+
+# Static analysis (examples by stack):
+# Node.js: npm run analyze (if configured)
+# Python: mypy src/ / bandit -r src/
+# Java: mvn pmd:check / spotbugs:check
+# Go: go vet ./...
+# Ruby: brakeman (for Rails)
+# Rust: cargo audit
+```
+
+Document:
+```markdown
+## Code Quality
+
+### Linting
+- **Errors**: 0
+- **Warnings**: X
+- **Justified Warnings**: [list with justifications]
+
+### Formatting
+- **Status**: ✅ Compliant / ⚠️ Adjustments needed
+
+### Static Analysis
+- **Critical Issues**: 0
+- **Medium Issues**: X
+- **Low Issues**: Y
+```
+
+### 4. Performance
+
+If applicable, measure performance:
+
+```markdown
+## Performance
+
+### Benchmarks
+- **Operation X**: Yms (baseline: Zms)
+- **Operation Y**: Yms (baseline: Zms)
+
+### Applied Optimizations
+- [Optimization 1 and impact]
+- [Optimization 2 and impact]
+
+### Identified Bottlenecks
+- [Bottleneck 1 and mitigation plan]
+```
+
+### 5. Size and Impact
+
+```markdown
+## Size and Impact
+
+### Lines of Code
+- **Added**: +X lines
+- **Removed**: -Y lines
+- **Modified**: Z lines
+
+### Files
+- **New**: X files
+- **Modified**: Y files
+- **Removed**: Z files
+
+### Dependencies
+- **New dependencies**: [list]
+- **Bundle size**: +X KB
+```
+
+### 6. Technical Debt
+
+Identify technical debt introduced or resolved:
+
+```markdown
+## Technical Debt
+
+### Debt Introduced
+- **Item 1**: [Description and justification]
+  - Severity: High / Medium / Low
+  - Resolution plan: [when and how to resolve]
+
+### Debt Resolved
+- **Item 1**: [What was resolved]
+  - Impact: [improvement achieved]
+```
+
+## 📄 Metrics Report
+
+Create `./.sessions/<ISSUE-ID>/metrics.md`:
+
+```markdown
+# Metrics Report - [ISSUE-ID]
+
+**Date**: [date/time]
+**Repositories**: [list]
+
+## Executive Summary
+
+- **Test Coverage**: X% (goal: Y%)
+- **Code Quality**: ✅ / ⚠️ / ❌
+- **Performance**: ✅ / ⚠️ / ❌
+- **Technical Debt**: Low / Medium / High
+
+## Detailed Metrics
+
+[Include all sections above]
+
+## Comparison with Baseline
+
+| Metric | Before | After | Variation |
+|--------|--------|-------|-----------|
+| Coverage | X% | Y% | +Z% |
+| Average Complexity | X | Y | +Z |
+| Bundle Size | X KB | Y KB | +Z KB |
+
+## Recommended Actions
+
+1. [Action 1 - high priority]
+2. [Action 2 - medium priority]
+3. [Action 3 - low priority]
+
+## Approval for Merge
+
+- [ ] Test coverage >= goal
+- [ ] No critical quality issues
+- [ ] Performance within requirements
+- [ ] Technical debt documented and approved
+```
+
+## 🎯 Quality Goals
+
+If the project has goals defined in metaspecs, validate:
+
+```markdown
+## Validation against Goals
+
+### Project Goals
+- **Minimum coverage**: 80%
+- **Maximum complexity**: 10
+- **Performance**: < 100ms
+
+### Status
+- Coverage: ✅ 85% (goal: 80%)
+- Complexity: ⚠️ 12 (goal: 10) - Justified
+- Performance: ✅ 85ms (goal: 100ms)
+```
+
+## 🚨 Alerts
+
+If any metric is out of acceptable range:
+1. 🛑 **DOCUMENT** the issue
+2. 💬 **ALERT** the user
+3. 🔧 **PROPOSE** corrective actions
+4. ⏸️ **CONSIDER** blocking the merge until resolution
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Outcome
+
+After running this command, you will have:
+- Complete metrics report
+- Comparison with baseline and goals
+- Identification of quality issues
+- Recommendations for actions
+- Objective basis for merge approval

package/templates/commands/en/quality/observe.md

@@ -0,0 +1,172 @@
+# Decision Observability
+
+This command records important decisions made during development, creating an auditable log for explainability and traceability.
+
+## 🎯 Objective
+
+Create a structured record of technical and product decisions, ensuring:
+- **Explainability**: Why each decision was made
+- **Traceability**: Which sources (PRD, metaspecs, ADRs) supported the decision
+- **Audit**: Complete history of choices for future review
+- **Learning**: Documentation of trade-offs and alternatives considered
+
+**IMPORTANT**: This command DOES NOT generate new decisions. It only RECORDS decisions that have already been made during the development process.
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📋 Prerequisites
+
+- Have executed at least one of the commands that generate decisions:
+  - `/spec` - generates PRD with product decisions
+  - `/plan` - generates plan.md with technical decisions
+  - `/work` - implementation generates decisions during development
+
+## 🔍 Observation Process
+
+### 1. Identify Relevant Decisions
+
+Analyze the session files (`./.sessions/<ISSUE-ID>/`) to identify decisions:
+
+**After `/spec`** - Product Decisions:
+- Read `./.sessions/<ISSUE-ID>/prd.md`
+- Identify decisions in:
+  - Scope (what is included/excluded in the feature)
+  - Personas served (who is the target audience)
+  - Success metrics (how to measure results)
+  - Non-functional requirements (performance, accessibility)
+  - Constraints and trade-offs
+
+**After `/plan`** - Technical Decisions:
+- Read `./.sessions/<ISSUE-ID>/plan.md`
+- Identify decisions in:
+  - Component/module architecture
+  - Choice of libraries or tools
+  - Implementation patterns
+  - Data structure
+  - Testing strategy
+
+**During `/work`** - Implementation Decisions:
+- Read `./.sessions/<ISSUE-ID>/work.md`
+- Identify decisions in:
+  - Refactorings performed
+  - Approach changes
+  - Applied optimizations
+  - Edge case handling
+
+### 2. Document Each Decision
+
+For each identified decision, document:
+
+```markdown
+## Decision: [Clear Title]
+
+**Context**: [Why do we need to decide this? What is the problem or need?]
+
+**Options Considered**:
+1. **Option A**: [Description]
+   - Pros: [advantages]
+   - Cons: [disadvantages]
+2. **Option B**: [Description]
+   - Pros: [advantages]
+   - Cons: [disadvantages]
+
+**Decision**: [Chosen option]
+
+**Justification**: [Why did we choose this option? Which criteria were most important?]
+
+**Sources**:
+- [PRD section X]
+- [Metaspec Y]
+- [ADR-00Z]
+
+**Accepted Trade-offs**: [Which disadvantages did we consciously accept?]
+
+**Reversibility**: Easy / Medium / Hard
+
+**Date**: [decision date]
+```
+
+### 3. Create Decision Log
+
+Save in `./.sessions/<ISSUE-ID>/decisions.md`:
+
+```markdown
+# Decision Log - [ISSUE-ID]
+
+## Summary
+[Brief summary of the main decisions made in this feature]
+
+## Product Decisions
+
+### [Decision 1]
+[As per template above]
+
+### [Decision 2]
+[As per template above]
+
+## Technical Decisions
+
+### [Decision 3]
+[As per template above]
+
+### [Decision 4]
+[As per template above]
+
+## Implementation Decisions
+
+### [Decision 5]
+[As per template above]
+
+## Lessons Learned
+- [Lesson 1]
+- [Lesson 2]
+
+## Pending Decisions
+- [Decision that still needs to be made]
+```
+
+## 📊 Impact Analysis
+
+For critical decisions, document the impact:
+
+```markdown
+## Impact Analysis
+
+**Affected Repositories**: [list]
+
+**Impacted Components**: [list]
+
+**Created Dependencies**: [list]
+
+**Introduced Risks**: [list]
+
+**Applied Mitigations**: [list]
+```
+
+## 🔄 Decision Review
+
+Periodically review the decisions made:
+- Do they still make sense?
+- Have the trade-offs proven correct?
+- Are there learnings to document?
+- Does any decision need to be reversed?
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Outcome
+
+After running this command, you will have:
+- Complete decision log in `./.sessions/<ISSUE-ID>/decisions.md`
+- Traceability of every choice made
+- Documentation for future reference
+- Basis for ADRs (if decisions are architectural)

package/templates/commands/en/warm-up.md

@@ -0,0 +1,83 @@
+# Warm-up — Context Loading (spec indexes for RAG)
+
+Prepares the environment by loading the **spec indexes** into a navigable context map.
+The goal is NOT to dump the specs into context, but to load the **indexes** so later
+commands know **where to look** for each piece of information, on demand.
+
+**Arguments**: `#$ARGUMENTS`
+
+---
+
+## 1. Load configuration
+
+Read from the orchestrator:
+- **`context-manifest.json`** — `repositories[]` (id, role, hints), and the
+  `orchestration` block (especially `indexes`).
+- **`ai.properties.md`** — `base_path`, `task_management_system`.
+
+Locate the specs repo: the one with `role: "metaspecs"` (or `"specs-provider"`).
+
+## 2. Discover the indexes (dynamic — requires no fixed file)
+
+Build the list of indexes to load, in this priority order, **skipping whatever doesn't exist**:
+
+1. Every path in the manifest's `orchestration.indexes` (if defined).
+2. If none are defined, or to complement, **discover** indexes in the specs repo:
+   - look for `index.md` / `INDEX.md` under `{base_path}/{metaspecs-id}/specs/` and
+     subfolders (e.g. `specs/index.md`, `specs/technical/index.md`,
+     `specs/business/index.md`, `specs/business/features/index.md`).
+3. Also include, **if they exist**, each repository's `context[]` files from the manifest.
+
+> Degrade gracefully: if an expected index is missing, **just note it and continue**.
+> Never fail the warm-up because a specific file is absent.
+
+## 3. Build the Context Map (the warm-up's output)
+
+Read ONLY the discovered indexes (not the documents they point to). From them, assemble
+and present a **RAG map** — the project's "routing table":
+
+```
+## Context Map (RAG)
+
+### Loaded indexes
+- specs/index.md            → navigation root
+- specs/technical/index.md  → architecture, API, ADRs, conventions
+- specs/business/index.md   → personas, journey, strategy
+- ...(only the ones that exist)
+
+### Where to look, on demand
+| Need                          | Consult (via index)                  |
+|-------------------------------|--------------------------------------|
+| Architecture / decisions      | technical/index.md → ARCHITECTURE / ADRs |
+| API contract                  | technical/index.md → API_SPECIFICATION   |
+| Business rules / feature      | business/index.md → features/...     |
+| Code conventions              | technical/index.md → code guide      |
+
+### Repositories (from the manifest)
+- <repo-id> [role] — hints: ...
+```
+
+If an index references documents that don't exist on disk, mark them as
+`(referenced, missing)` — that signals an incomplete spec, not a warm-up error.
+
+## 4. Verify repositories and session
+
+- For each repo in the manifest, confirm it exists at `{base_path}/{repo-id}/`
+  (do not read README or code now — that's on demand).
+- If an ISSUE-ID was passed, check `.sessions/<ISSUE-ID>/`.
+
+## 5. How later commands use this
+
+Commands like `/spec`, `/orchestrate` and the agents must NOT scan the repo blindly.
+They should: consult the Context Map → open the relevant index → follow the link to the
+specific document. The index is what optimizes RAG: load little, navigate precisely.
+
+## 6. Jidoka principle
+
+If you detect a structural problem (no index found, specs-provider missing):
+**STOP**, describe what's missing, and suggest how to fix it (e.g. create `specs/index.md`
+or fill `orchestration.indexes`). Do not invent context.
+
+---
+
+**Status**: Indexes loaded and Context Map built. Awaiting the next command.

package/templates/commands/es/agents/CONTEXT-CONTRACT.md

@@ -0,0 +1,63 @@
+# Contrato de Contexto (forma)
+
+Todo agente efímero se spawnea con un contrato. Este es exactamente el objeto que el
+Orquestador compila por nodo y pega en el prompt del subagente. Es lo que mantiene el
+contexto de cada agente **pequeño, acotado y auditable** — el núcleo de la arquitectura.
+
+```json
+{
+  "agentId": "agent-w001",
+  "archetype": "implementer",
+  "objective": "<objetivo específico y acotado de este worker>",
+  "repository": "<repo-id o null para workers de sesión>",
+  "read": [
+    { "type": "index", "path": "../metaspecs/specs/index.md", "reason": "router de contexto" },
+    { "type": "hint",  "path": "../metaspecs/specs/technical/API_SPECIFICATION.md", "reason": "hint del repo" }
+  ],
+  "mayDiscover": [
+    "referencias alcanzables desde los índices de arriba",
+    "archivos de este repositorio necesarios para el objetivo"
+  ],
+  "mustNotAssume": [
+    "reglas de negocio no dichas",
+    "contratos externos no indexados",
+    "requisitos ausentes en la spec aprobada"
+  ],
+  "writeBoundary": ["worktree asignado del <repo-id>"],
+  "limits": { "policy": "select-do-not-dump", "maxFiles": 20 },
+  "return": ["summary", "changes", "evidence", "tests", "unresolved", "confidence"]
+}
+```
+
+## Reglas que el Orquestador debe garantizar al compilar un contrato
+
+- `read` incluye TODOS los `orchestration.indexes` más el `context[]` del repo — pero sólo
+  rutas que realmente existen en disco. Descarta el resto silenciosamente.
+- Workers de sesión (integrator, tester, reviewer) tienen `repository: null` y
+  `writeBoundary: ["sólo artefactos de la sesión"]`.
+- Nunca expandas `read` a "el repo entero". El descubrimiento está permitido
+  (`mayDiscover`), pero parte de los índices, no de un volcado ciego de directorio.
+- El contrato es el ÚNICO contexto de proyecto que recibe un subagente además del objetivo.
+  No pegues la conversación entera en los subagentes.
+
+## La forma de retorno que todo agente debe producir
+
+```markdown
+### summary
+<un párrafo: qué se hizo>
+
+### changes
+<archivos creados/modificados, por repo>
+
+### evidence
+<comandos corridos, salidas, links>
+
+### tests
+<tests agregados/corridos y su resultado>
+
+### unresolved
+<preguntas, conflictos de spec, stops Jidoka — o "ninguno">
+
+### confidence
+<low | medium | high> + una línea de por qué
+```

package/templates/commands/es/agents/implementer.md

@@ -0,0 +1,27 @@
+# Arquetipo: implementer
+
+Eres un **implementer efímero** para exactamente un repositorio. Serás descartado al
+retornar. La experiencia de dominio viene de tu contrato de contexto, no de una persona.
+
+## Recibes
+- `objective`: el objetivo acotado.
+- `repository`: el id del repo y la ruta del worktree.
+- Un **contrato de contexto** (alcance de lectura, writeBoundary, mustNotAssume, limits, return).
+
+## Haz
+1. Lee SÓLO lo que el `read` del contrato permite; descubre más allá SÓLO desde esos
+   índices/archivos del repo (`mayDiscover`). Respeta `limits.maxFiles`.
+2. Implementa el objetivo dentro de tu `writeBoundary` (el worktree de tu repo). Sigue los
+   patrones que encuentres en el repo y en las specs normativas. No introduzcas stack no
+   documentada en las specs sin señalarlo en `unresolved`.
+3. Agrega/ajusta tests según las convenciones del repo.
+4. Commit atómico dentro del worktree (`feat|fix|refactor|test|docs|chore: … Refs: <ISSUE-ID>`).
+
+## Nunca
+- Leer o modificar otros repositorios.
+- Modificar specs normativas.
+- Asumir algo en `mustNotAssume` — si lo necesitas, detente y ponlo en `unresolved`.
+
+## Retorno (exactamente esta forma)
+summary / changes / evidence / tests / unresolved / confidence
+(ver CONTEXT-CONTRACT.md)

package/templates/commands/es/agents/integrator.md

@@ -0,0 +1,24 @@
+# Arquetipo: integrator
+
+Eres un **integrator efímero**. Corres después de los implementers por repo y verificas
+que sus cambios encajen. Eres de sesión: `repository: null`,
+`writeBoundary: sólo artefactos de la sesión`.
+
+## Recibes
+- Los retornos de todos los implementers (resúmenes y changes por repo).
+- Las secciones de la spec que describen contratos cross-repo (APIs, eventos, tipos, design tokens).
+- Un **contrato de contexto**.
+
+## Haz
+1. Reconstruye el contrato entre los repos que cambiaron (ej.: endpoint del backend ↔
+   consumidor en el frontend, productor ↔ consumidor de un evento, componente compartido ↔
+   sus usos).
+2. Verifica que ambos lados concuerden: nombres/tipos de campos, status codes, forma de
+   error, versiones, nulabilidad, unidades. Señala cada divergencia con precisión (qué lado,
+   qué campo).
+3. Verifica dependencias de orden/deploy (¿un repo debe salir antes que otro?).
+4. NO reimplementes — si hallas divergencia, describe la corrección exacta y de quién es el repo.
+
+## Retorno
+summary / changes(=hallazgos de integración) / evidence / tests(=checks de integración a correr) /
+unresolved / confidence. Marca **CONSISTENT** o **MISMATCH**.

package/templates/commands/es/agents/reviewer.md

@@ -0,0 +1,31 @@
+# Arquetipo: reviewer
+
+Eres un **reviewer efímero**. Tu trabajo es encontrar lo que está mal, no elogiar.
+En tareas `complex` eres **adversarial**: asume que hay un defecto hasta probar lo contrario.
+
+## Recibes
+- `objective`: qué revisar y contra qué spec.
+- Los retornos de los implementers (summary/changes) y las secciones relevantes de la spec.
+- Un **contrato de contexto** limitando el alcance de lectura.
+
+## Foco (pesa por los riskSignals de la tarea)
+- Corrección vs. la **spec normativa** — no vs. tus suposiciones.
+- Reglas de negocio, casos borde e integridad de datos.
+- Seguridad, authz/authn, secretos, inyección, exposición de PII.
+- Migraciones: reversibilidad, backfill, downtime, orden.
+- Contratos cross-repo: ¿el cambio honra la API/interfaz que ambos lados esperan?
+- Premisas ocultas del implementer que no están en la spec.
+
+## Método
+1. Lee los archivos cambiados y las secciones de la spec que los gobiernan.
+2. Para cada hallazgo: indica archivo/línea, por qué está mal y la corrección concreta.
+3. Clasifica cada hallazgo: `blocking` | `should-fix` | `nit`.
+4. Intenta refutar tus propios hallazgos antes de reportar — descarta los que no sostengas.
+
+## Nunca
+- Aprobar por cortesía. Si está correcto, dilo brevemente y sigue.
+- Modificar código (tú revisas; los implementers corrigen).
+
+## Retorno
+summary / changes(=lista de hallazgos) / evidence / tests(=qué testearías) / unresolved / confidence
+Marca claramente **PASS** o **BLOCKED** (cualquier hallazgo blocking ⇒ BLOCKED).

package/templates/commands/es/agents/tester.md

@@ -0,0 +1,22 @@
+# Arquetipo: tester
+
+Eres un **tester efímero**. Validas criterios de aceptación y riesgo de regresión usando
+los comandos del propio proyecto. De sesión: `repository: null`.
+
+## Recibes
+- Los criterios de aceptación del objetivo (de la spec).
+- La lista de repos impactados y el `testCommand` de cada uno (del manifiesto).
+- Un **contrato de contexto**.
+
+## Haz
+1. Para cada repo impactado, corre el `testCommand` dentro del worktree. Si no hay, usa el
+   enfoque de test documentado en el proyecto y di qué asumiste.
+2. Mapea cada criterio de aceptación a un check concreto (test existente, test nuevo o
+   evidencia manual). Anota cualquier criterio que no pudiste verificar.
+3. Reporta fallas con el comando exacto, la salida y el archivo/área implicada.
+4. NO corrijas código — reporta para que un implementer corrija.
+
+## Retorno
+summary / changes(=ninguno, o tests nuevos) / evidence(=comandos + salidas) /
+tests(=pass/fail por repo + cobertura de criterios) / unresolved / confidence.
+Marca **GREEN** (todo pasa, criterios cubiertos) o **RED** (fallas / criterios sin cubrir).