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

package/dist/templates/commands/pt-BR/quality/observe.md

@@ -0,0 +1,206 @@
+# Observabilidade de Decisões
+
+Este comando registra decisões importantes tomadas durante o desenvolvimento, criando um log auditável para explicabilidade e rastreabilidade.
+
+## 🎯 Objetivo
+
+Criar registro estruturado de decisões técnicas e de produto, garantindo:
+- **Explicabilidade**: Por que cada decisão foi tomada
+- **Rastreabilidade**: Quais fontes (PRD, metaspecs, ADRs) embasaram a decisão
+- **Auditoria**: Histórico completo de escolhas para revisão futura
+- **Aprendizado**: Documentação de trade-offs e alternativas consideradas
+
+**IMPORTANTE**: Este comando NÃO gera decisões novas. Ele apenas REGISTRA decisões que já foram tomadas no processo de desenvolvimento.
+
+## 📋 Configuração do Projeto
+
+**⚠️ IMPORTANTE: Sempre leia os arquivos de configuração do projeto ANTES de executar este comando!**
+
+### Arquivos Obrigatórios
+
+1. **`context-manifest.json`** (raiz do orchestrator)
+   - Lista de repositórios do projeto
+   - Roles de cada repositório (metaspecs, application, etc.)
+   - URLs e dependências entre repositórios
+
+2. **`ai.properties.md`** (raiz do orchestrator)
+   - Configurações do projeto (`project_name`, `base_path`)
+   - Sistema de gerenciamento de tarefas (`task_management_system`)
+   - Credenciais e configurações específicas
+
+### Como Ler
+
+```bash
+# 1. Ler context-manifest.json
+cat context-manifest.json
+
+# 2. Ler ai.properties.md
+cat ai.properties.md
+```
+
+### Informações Essenciais
+
+Após ler os arquivos, você terá:
+- ✅ Lista completa de repositórios do projeto
+- ✅ Localização do repositório de metaspecs
+- ✅ Base path para localizar repositórios
+- ✅ Sistema de task management configurado
+- ✅ Configurações específicas do projeto
+
+**🛑 NÃO prossiga sem ler estes arquivos!** Eles contêm informações críticas para a execução correta do comando.
+
+
+## 📋 Pré-requisitos
+
+- Executou pelo menos um dos comandos que geram decisões:
+  - `/spec` - gera PRD com decisões de produto
+  - `/plan` - gera plan.md com decisões técnicas
+  - `/work` - implementação gera decisões durante desenvolvimento
+
+## 🔍 Processo de Observação
+
+### 1. Identificar Decisões Relevantes
+
+Analise os arquivos da sessão (`./.sessions/<ISSUE-ID>/`) para identificar decisões:
+
+**Após `/spec`** - Decisões de Produto:
+- Leia `./.sessions/<ISSUE-ID>/prd.md`
+- Identifique decisões em:
+  - Escopo (o que entra/não entra na feature)
+  - Personas atendidas (quem é o público-alvo)
+  - Métricas de sucesso (como medir resultados)
+  - Requisitos não-funcionais (performance, acessibilidade)
+  - Restrições e trade-offs
+
+**Após `/plan`** - Decisões Técnicas:
+- Leia `./.sessions/<ISSUE-ID>/plan.md`
+- Identifique decisões em:
+  - Arquitetura de componentes/módulos
+  - Escolha de bibliotecas ou ferramentas
+  - Padrões de implementação
+  - Estrutura de dados
+  - Estratégia de testes
+
+**Durante `/work`** - Decisões de Implementação:
+- Leia `./.sessions/<ISSUE-ID>/work.md`
+- Identifique decisões em:
+  - Refatorações realizadas
+  - Mudanças de abordagem
+  - Otimizações aplicadas
+  - Tratamento de edge cases
+
+### 2. Documentar Cada Decisão
+
+Para cada decisão identificada, documente:
+
+```markdown
+## Decisão: [Título Claro]
+
+**Contexto**: [Por que precisamos decidir isso? Qual o problema ou necessidade?]
+
+**Opções Consideradas**:
+1. **Opção A**: [Descrição]
+   - Prós: [vantagens]
+   - Contras: [desvantagens]
+2. **Opção B**: [Descrição]
+   - Prós: [vantagens]
+   - Contras: [desvantagens]
+
+**Decisão**: [Opção escolhida]
+
+**Justificativa**: [Por que escolhemos esta opção? Quais critérios foram mais importantes?]
+
+**Fontes**:
+- [PRD seção X]
+- [Metaspec Y]
+- [ADR-00Z]
+
+**Trade-offs Aceitos**: [Quais desvantagens aceitamos conscientemente?]
+
+**Reversibilidade**: Fácil / Média / Difícil
+
+**Data**: [data da decisão]
+```
+
+### 3. Criar Log de Decisões
+
+Salve em `./.sessions/<ISSUE-ID>/decisions.md`:
+
+```markdown
+# Log de Decisões - [ISSUE-ID]
+
+## Resumo
+[Breve resumo das principais decisões tomadas nesta feature]
+
+## Decisões de Produto
+
+### [Decisão 1]
+[Conforme template acima]
+
+### [Decisão 2]
+[Conforme template acima]
+
+## Decisões Técnicas
+
+### [Decisão 3]
+[Conforme template acima]
+
+### [Decisão 4]
+[Conforme template acima]
+
+## Decisões de Implementação
+
+### [Decisão 5]
+[Conforme template acima]
+
+## Lições Aprendidas
+- [Lição 1]
+- [Lição 2]
+
+## Decisões Pendentes
+- [Decisão que ainda precisa ser tomada]
+```
+
+## 📊 Análise de Impacto
+
+Para decisões críticas, documente o impacto:
+
+```markdown
+## Análise de Impacto
+
+**Repositórios Afetados**: [lista]
+
+**Componentes Impactados**: [lista]
+
+**Dependências Criadas**: [lista]
+
+**Riscos Introduzidos**: [lista]
+
+**Mitigações Aplicadas**: [lista]
+```
+
+## 🔄 Revisão de Decisões
+
+Periodicamente, revise as decisões tomadas:
+- Ainda fazem sentido?
+- Os trade-offs se provaram corretos?
+- Há aprendizados para documentar?
+- Alguma decisão precisa ser revertida?
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Resultado
+
+Após executar este comando, você terá:
+- Log completo de decisões em `./.sessions/<ISSUE-ID>/decisions.md`
+- Rastreabilidade de cada escolha feita
+- Documentação para futuras referências
+- Base para ADRs (se decisões forem de arquitetura)

package/dist/templates/commands/pt-BR/warm-up.md

@@ -0,0 +1,59 @@
+# Aquecimento - Carregamento de Contexto
+
+Prepara o ambiente carregando o contexto otimizado do projeto.
+
+## 1. Carregar Configuração
+
+Leia os arquivos do orchestrator:
+- **`context-manifest.json`** - Repositórios e roles
+- **`ai.properties.md`** - base_path, task_management_system
+
+## 2. Carregar Contexto Compacto (OTIMIZADO)
+
+**IMPORTANTE**: Use carregamento PROGRESSIVO para economizar janela de contexto.
+
+### Obrigatório (warm-up)
+
+Localize metaspecs via `context-manifest.json` (role: "specs-provider"):
+
+```
+{base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md  (~100 linhas)
+```
+
+Este arquivo contém TODOS os essenciais:
+- Stack tecnológica
+- Hierarquia de contexto
+- 5 regras críticas
+- Padrões de código mínimos
+- Tabela de carregamento sob demanda
+
+### Sob Demanda (NÃO carregar durante warm-up)
+
+| Necessidade | Documento |
+|-------------|-----------|
+| Gerar código | `CLAUDE.meta.md` |
+| Arquitetura | `ARCHITECTURE.md` |
+| Feature específica | `features/{FEATURE}.md` |
+| Anti-patterns completos | `ANTI_PATTERNS.md` |
+
+## 3. Verificar Repositórios
+
+Para cada repositório no `context-manifest.json`:
+- Verificar existência em `{base_path}/{repo-id}/`
+- **NÃO** ler README.md agora (sob demanda)
+
+## 4. Verificar Sessão (se existir)
+
+```bash
+ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
+```
+
+## 5. Princípio Jidoka
+
+Se problemas detectados: **PARE**, documente, alerte o usuário.
+
+---
+
+**Argumentos**: #$ARGUMENTS
+
+**Status**: Contexto carregado. Aguardando próximo comando.

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@thatix.io/context-first-agents-cli",
-  "version": "0.1.0",
-  "publishConfig": { "access": "public" },
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Evolution of context-first-cli: manage the Context-First methodology across any project AND orchestrate dynamic, ephemeral AI agents from specs. All agent orchestration lives in .md command templates; the Node layer only scaffolds and manages.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +39,9 @@
   ],
   "author": "Thiago Abreu <thiagoabreu.dev>",
   "license": "MIT",
-  "engines": { "node": ">=18.0.0" },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
     "chalk": "^5.6.2",
     "commander": "^14.0.2",

package/templates/commands/en/engineer/plan.md

@@ -0,0 +1,301 @@
+# Technical Planning
+
+This command creates the detailed technical plan for the feature implementation.
+
+## 📋 Prerequisites
+
+- PRD created via `/spec`
+- Initial analysis done via `/start`
+- `context.md` and `architecture.md` files created and approved
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📍 IMPORTANT: Understand the Structure
+
+**Workspace**:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree (will be used in /work)
+├── repo-2/          # worktree (will be used in /work)
+├── context.md       # context (immutable - READ)
+├── architecture.md  # architecture (immutable - READ)
+└── plan.md          # plan (mutable - CREATE)
+```
+
+**Main repositories** (read-only):
+```
+{base_path}/repo-1/  # main repo (branch main/master)
+{base_path}/repo-2/  # main repo (branch main/master)
+```
+
+**GOLDEN RULE**:
+- ✅ Read `context.md` and `architecture.md` (immutable)
+- ✅ Create `plan.md` in `.sessions/<ISSUE-ID>/`
+- ✅ Read code from main repositories (read-only)
+- ❌ NEVER checkout main repositories
+- ❌ NEVER modify `context.md` or `architecture.md`
+
+## ⚠️ IMPORTANT: Immutable Files
+
+**This command must READ but NOT MODIFY:**
+- ✅ **READ** `.sessions/<ISSUE-ID>/context.md` (immutable)
+- ✅ **READ** `.sessions/<ISSUE-ID>/architecture.md` (immutable)
+- ✅ **CREATE** `.sessions/<ISSUE-ID>/plan.md` (mutable - will be updated during `/work`)
+- ❌ **DO NOT modify `context.md` or `architecture.md`**
+
+## 📚 Load MetaSpecs
+
+**Automatically locate MetaSpecs**:
+1. Read `context-manifest.json` from the orchestrator
+2. Find the repository with `"role": "metaspecs"`
+3. Read `ai.properties.md` to get the `base_path`
+4. The metaspecs are at: `{base_path}/{metaspecs-repo-id}/`
+5. Read the relevant `index.md` files to ensure compliance with:
+   - System architecture
+   - Design and code patterns
+   - Folder and file structure
+   - Naming conventions
+
+## 🎯 Goal
+
+Create a detailed technical plan that will guide the implementation, dividing the work into smaller, sequential units.
+
+## 📝 Plan Structure
+
+### 1. Technical Overview
+
+```markdown
+# Technical Plan - [Feature Title]
+
+## Summary
+[Brief technical description of what will be implemented]
+
+## Involved Repositories
+- **<repo-1>**: [Role in this feature]
+- **<repo-2>**: [Role in this feature]
+
+## Technical Approach
+[General implementation strategy]
+```
+
+### 2. Solution Architecture
+
+```markdown
+## Architecture
+
+### Component Diagram
+[Textual description or ASCII art of components and their relationships]
+
+### Data Flow
+1. [Step 1 of the flow]
+2. [Step 2 of the flow]
+3. [Step 3 of the flow]
+
+### Integrations
+- **<repo-1> → <repo-2>**: [How they communicate]
+- **System → External API**: [If any]
+```
+
+### 3. Technical Decisions
+
+```markdown
+## Technical Decisions
+
+### Decision 1: [Title]
+**Context**: [Why we need to decide this]
+**Considered options**:
+- Option A: [Pros and cons]
+- Option B: [Pros and cons]
+**Decision**: [Chosen option]
+**Justification**: [Why we chose this option]
+
+### Decision 2: [Title]
+[Same format as above]
+```
+
+### 4. Implementation Plan
+
+Divide the work into small, sequential units:
+
+```markdown
+## Implementation Plan
+
+### Phase 1: [Phase Name]
+**Goal**: [What will be achieved in this phase]
+**Repositories**: [affected repos]
+
+#### Task 1.1: [Description]
+- **Repo**: <repo-1>
+- **Files**: [files to create/modify]
+- **Description**: [What to do]
+- **Tests**: [Tests to implement]
+- **Estimate**: [estimated time]
+
+#### Task 1.2: [Description]
+- **Repo**: <repo-2>
+- **Files**: [files to create/modify]
+- **Description**: [What to do]
+- **Tests**: [Tests to implement]
+- **Estimate**: [estimated time]
+
+### Phase 2: [Phase Name]
+[Same format as above]
+
+### Phase 3: [Phase Name]
+[Same format as above]
+```
+
+### 5. File Structure
+
+For each repository, define the structure:
+
+```markdown
+## File Structure
+
+### <repo-1>
+```
+src/
+├── components/
+│   ├── NewComponent.tsx (CREATE)
+│   └── ExistingComponent.tsx (MODIFY)
+├── services/
+│   └── NewService.ts (CREATE)
+└── tests/
+    └── NewComponent.test.tsx (CREATE)
+```
+
+### <repo-2>
+```
+src/
+├── controllers/
+│   └── NewController.ts (CREATE)
+└── tests/
+    └── NewController.test.ts (CREATE)
+```
+```
+
+### 6. APIs and Contracts
+
+```markdown
+## APIs and Contracts
+
+### New Endpoints
+
+#### POST /api/resource
+**Request**:
+```json
+{
+  "field1": "string",
+  "field2": "number"
+}
+```
+
+**Response**:
+```json
+{
+  "id": "string",
+  "status": "string"
+}
+```
+
+### Modified Endpoints
+
+#### GET /api/resource/:id
+**Changes**: [What changes]
+**Breaking Change**: Yes / No
+```
+
+### 7. Testing Strategy
+
+```markdown
+## Testing Strategy
+
+### Unit Tests
+- **<repo-1>**: [Components/functions to test]
+- **<repo-2>**: [Components/functions to test]
+
+### Integration Tests
+- **Scenario 1**: [Description and involved repos]
+- **Scenario 2**: [Description and involved repos]
+
+### E2E Tests (if applicable)
+- **Flow 1**: [Description]
+- **Flow 2**: [Description]
+```
+
+### 8. Technical Risks
+
+```markdown
+## Technical Risks
+
+### Risk 1: [Description]
+- **Impact**: High / Medium / Low
+- **Probability**: High / Medium / Low
+- **Mitigation**: [How to mitigate]
+- **Plan B**: [Alternative if it occurs]
+
+### Risk 2: [Description]
+[Same format as above]
+```
+
+### 9. Implementation Checklist
+
+```markdown
+## Implementation Checklist
+
+### Phase 1
+- [ ] Task 1.1
+- [ ] Task 1.2
+- [ ] Phase 1 Tests
+
+### Phase 2
+- [ ] Task 2.1
+- [ ] Task 2.2
+- [ ] Phase 2 Tests
+
+### Phase 3
+- [ ] Task 3.1
+- [ ] Task 3.2
+- [ ] Phase 3 Tests
+
+### Finalization
+- [ ] Documentation updated
+- [ ] Code review
+- [ ] Integration tests
+- [ ] PR created
+```
+
+## 📄 Saving the Plan
+
+Save it in `./.sessions/<ISSUE-ID>/plan.md`
+
+## 🔍 Review
+
+Review the plan checking:
+- All tasks are clear and executable
+- Dependencies between tasks are identified
+- Estimates are realistic
+- Risks have been considered
+- Testing strategy is adequate
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+After plan approval:
+
+```bash
+/work
+```
+
+This command will start executing the first work unit of the plan.