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

package/dist/templates/commands/pt-BR/engineer/start.md

@@ -0,0 +1,319 @@
+# Início do Desenvolvimento
+
+Este comando inicia o desenvolvimento de uma funcionalidade no workspace atual.
+
+## 📍 IMPORTANTE: Entenda a Estrutura
+
+**Workspace** (onde você trabalhará):
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree com branch feature/<ISSUE-ID>
+├── repo-2/          # worktree com branch feature/<ISSUE-ID>
+├── context.md       # contexto (imutável - criado por este comando)
+├── architecture.md  # arquitetura (imutável - criado por este comando)
+└── plan.md          # plano (mutável - criado por /plan)
+```
+
+**Repositórios principais** (apenas leitura):
+```
+{base_path}/repo-1/  # repo principal (branch main/master)
+{base_path}/repo-2/  # repo principal (branch main/master)
+```
+
+**REGRA DE OURO**:
+- ✅ Leia metaspecs e código dos repositórios principais (read-only)
+- ✅ Crie `context.md` e `architecture.md` em `.sessions/<ISSUE-ID>/`
+- ❌ NUNCA faça checkout nos repositórios principais
+- ❌ NUNCA modifique código neste comando (use `/work` depois)
+
+## 📋 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.
+
+
+## 📚 Carregar MetaSpecs
+
+**Localizar MetaSpecs automaticamente**:
+1. Leia `context-manifest.json` do orchestrator
+2. Encontre o repositório com `"role": "metaspecs"`
+3. Leia `ai.properties.md` para obter o `base_path`
+4. O metaspecs está em: `{base_path}/{metaspecs-repo-id}/`
+5. Leia os arquivos `index.md` relevantes:
+   - Contexto de negócio
+   - Stack, arquitetura e padrões técnicos
+   - Convenções do projeto
+   - ADRs (Architecture Decision Records)
+
+## 🎯 Contexto do Projeto
+
+Antes de iniciar, carregue o contexto consultando:
+- `context-manifest.json` - Estrutura de repositórios
+- MetaSpecs (localizado acima) - Arquitetura e padrões
+- `diretório do workspace` - Informações do workspace atual
+
+## ⚙️ Configuração Inicial
+
+1. **Verificar Workspace**:
+   - Confirme que está no workspace correto (verifique `diretório do workspace`)
+   - Liste os repositórios disponíveis no workspace
+
+2. **Verificar Branches**:
+   - Para cada repositório no workspace, verifique a branch atual
+   - Confirme que todas as branches estão sincronizadas
+
+3. **Carregar Especificação**:
+   - **Se task manager configurado**: Leia a issue usando o MCP apropriado
+   - **Senão**: Peça ao usuário o arquivo de especificação ou descrição da feature
+
+4. **Atualizar Status** (se task manager configurado):
+   - Mova a issue para "Em Progresso"
+
+## 📋 Análise e Entendimento
+
+Analise a especificação e construa entendimento completo respondendo:
+
+### Negócio
+- **Por que** isso está sendo construído?
+- **Quem** se beneficia?
+- **Qual** métrica queremos impactar?
+
+### Funcional
+- **Qual resultado esperado**? (comportamento do usuário, output do sistema)
+- **Quais componentes** serão criados/modificados em cada repositório?
+- **Quais integrações** entre repositórios são necessárias?
+
+### Técnico
+- **Stack aprovada**? Verificar contra especificações técnicas
+- **Padrões arquiteturais**? Verificar ADRs (se disponíveis)
+- **Dependências novas**? Justificar e documentar
+- **Como testar**? (conforme padrões do projeto)
+
+### Validação contra Metaspecs
+
+Se metaspecs estiverem disponíveis, validar:
+- Alinhado com estratégia e roadmap?
+- Usa stack tecnológica aprovada?
+- Respeita Architecture Decision Records?
+- Segue regras de negócio documentadas?
+
+## 🤔 Perguntas de Esclarecimento
+
+Após análise inicial, formule **3-5 clarificações mais importantes**:
+
+**Exemplos de perguntas relevantes**:
+- Qual repositório deve conter a lógica principal?
+- Como os repositórios devem se comunicar?
+- Há dependências entre as mudanças nos diferentes repos?
+- Qual a ordem de implementação recomendada?
+- Há impacto em APIs ou contratos entre serviços?
+
+## 💾 Criação do Context.md
+
+**IMPORTANTE**: Este arquivo é **IMUTÁVEL** após aprovação. Não deve ser modificado por comandos subsequentes.
+
+Crie arquivo `./.sessions/<ISSUE-ID>/context.md` com:
+
+```markdown
+# Context: [Nome da Feature]
+
+## Por Que
+[Valor de negócio, persona atendida, métrica impactada]
+
+## O Que
+[Funcionalidades principais, comportamento esperado]
+
+## Como
+[Abordagem técnica, componentes, repositórios afetados]
+
+## Validação contra Metaspecs
+- [x] Alinhado com estratégia de produto
+- [x] Atende persona correta
+- [x] Métrica impactada documentada
+- [x] Usa stack aprovada
+- [x] Respeita ADRs
+- [x] Sem conflitos com limitações conhecidas
+
+## Dependências
+[Bibliotecas, APIs, componentes existentes]
+
+## Restrições
+[Limitações técnicas, performance targets, budget]
+
+## Testes
+[E2E críticos, unit tests necessários, cobertura esperada]
+```
+
+**Após criar `context.md`, peça revisão e aprovação do usuário antes de prosseguir.**
+
+---
+
+## 🏗️ Criação do Architecture.md
+
+**IMPORTANTE**: Este arquivo é **IMUTÁVEL** após aprovação. Não deve ser modificado por comandos subsequentes.
+
+### Princípios Arquiteturais (OBRIGATÓRIO)
+
+**ANTES de criar a arquitetura, você DEVE:**
+
+1. **Ler ADRs (Architecture Decision Records)**:
+   - Liste ADRs em metaspecs
+   - Leia TODOS os ADRs relevantes para a feature
+   - Identifique restrições e padrões obrigatórios
+
+2. **Consultar padrões arquiteturais**:
+   - Leia guias de estrutura do projeto em metaspecs
+   - Leia padrões de código em metaspecs
+   - Identifique padrões existentes no código (use Glob/Grep para encontrar exemplos similares)
+
+3. **Validar compliance com ADRs**:
+   - Para cada ADR relevante, verifique se a solução proposta respeita as decisões
+   - Documente compliance no architecture.md
+   - Se houver violação, justifique ou proponha correção
+
+4. **Analisar código existente**:
+   - Use Glob/Grep para encontrar componentes/módulos similares
+   - Entenda padrões e estruturas existentes
+   - Alinhe nova implementação com padrões do projeto
+
+### Estrutura do Documento de Arquitetura
+
+Crie arquivo `./.sessions/<ISSUE-ID>/architecture.md` com:
+
+```markdown
+# Architecture: [Nome da Feature]
+
+## Visão Geral
+[Visão de alto nível do sistema antes e depois da mudança]
+
+## Componentes Afetados
+[Lista de componentes e suas relações, dependências]
+
+### Diagrama de Componentes
+[Descrição textual ou diagrama Mermaid dos componentes]
+
+### Fluxo de Dados
+1. [Passo 1 do fluxo]
+2. [Passo 2 do fluxo]
+3. [Passo 3 do fluxo]
+
+## Estrutura de Diretórios Proposta
+[Baseada em padrões do projeto]
+
+```
+repo-1/
+├── src/
+│   ├── components/
+│   │   └── NewComponent.tsx (CRIAR)
+│   └── services/
+│       └── NewService.ts (CRIAR)
+```
+
+## Padrões e Melhores Práticas
+[Padrões que serão mantidos ou introduzidos]
+
+## Validação de ADRs
+[Lista de ADRs consultados e compliance]
+
+- [x] ADR-001: [Nome] - Compliant
+- [x] ADR-002: [Nome] - Compliant
+
+## Dependências Externas
+[Bibliotecas que serão usadas ou adicionadas]
+
+## Decisões Técnicas
+
+### Decisão 1: [Título]
+**Contexto**: [Por que precisamos decidir isso]
+**Opções consideradas**:
+- Opção A: [Prós e contras]
+- Opção B: [Prós e contras]
+**Decisão**: [Opção escolhida]
+**Justificativa**: [Por que escolhemos esta opção]
+
+## Restrições e Suposições
+[Limitações técnicas e premissas]
+
+## Trade-offs
+[Alternativas consideradas e por que não foram escolhidas]
+
+## Consequências
+**Positivas**:
+- [Benefício 1]
+- [Benefício 2]
+
+**Negativas**:
+- [Custo/limitação 1]
+- [Custo/limitação 2]
+
+## Arquivos Principais
+[Lista dos principais arquivos a serem editados/criados]
+
+- `repo-1/src/components/NewComponent.tsx` (CRIAR)
+- `repo-1/src/services/NewService.ts` (CRIAR)
+- `repo-2/src/controllers/NewController.ts` (CRIAR)
+```
+
+**Após criar `architecture.md`, peça revisão e aprovação do usuário antes de prosseguir.**
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Passo
+
+**Após aprovação do usuário dos arquivos `context.md` e `architecture.md`**:
+
+```bash
+/plan
+```
+
+Este comando criará o planejamento técnico detalhado da implementação.
+
+---
+
+## ⚠️ IMPORTANTE: Arquivos Imutáveis
+
+**`context.md` e `architecture.md` são IMUTÁVEIS após aprovação.**
+
+- ✅ Podem ser LIDOS por comandos subsequentes (`/plan`, `/work`)
+- ❌ NÃO devem ser MODIFICADOS por nenhum comando
+- ❌ Se houver necessidade de mudança, discuta com o usuário e crie novos arquivos ou atualize a issue no task manager

package/dist/templates/commands/pt-BR/engineer/work.md

@@ -0,0 +1,290 @@
+# Execução do Trabalho
+
+Este comando executa uma unidade de trabalho no workspace atual, implementando parte do plano técnico.
+
+## 📋 Pré-requisitos
+
+Antes de executar, certifique-se de que:
+- Executou `/start` e `/plan` para ter o planejamento técnico
+- Está no workspace correto: `<orchestrator>/.sessions/<ISSUE-ID>/`
+- Tem os arquivos `.sessions/<ISSUE-ID>/` disponíveis:
+  - `context.md` (imutável)
+  - `architecture.md` (imutável)
+  - `plan.md` (mutável)
+
+## 📋 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.
+
+
+## 📍 IMPORTANTE: Entenda a Estrutura
+
+**Workspace** (onde você trabalha):
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree com branch feature/<ISSUE-ID>
+├── repo-2/          # worktree com branch feature/<ISSUE-ID>
+├── context.md       # contexto (imutável)
+├── architecture.md  # arquitetura (imutável)
+└── plan.md          # plano (mutável)
+```
+
+**Repositórios principais** (NÃO tocar):
+```
+{base_path}/repo-1/  # repo principal (branch main/master)
+{base_path}/repo-2/  # repo principal (branch main/master)
+```
+
+**REGRA DE OURO**:
+- ✅ Trabalhe APENAS dentro de `<orchestrator>/.sessions/<ISSUE-ID>/`
+- ✅ Faça commits nos worktrees dentro do workspace
+- ❌ NUNCA faça checkout nos repositórios principais
+- ❌ NUNCA navegue para `{base_path}/{repo-id}/`
+
+## 🛑 CRÍTICO: ONDE CRIAR CÓDIGO
+
+**⚠️ ATENÇÃO: TODO CÓDIGO DEVE SER CRIADO DENTRO DO WORKTREE DO REPOSITÓRIO!**
+
+**✅ CORRETO** - Criar código dentro do worktree:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/src/file.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/tests/test.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/package.json  ✅
+```
+
+**❌ ERRADO** - NUNCA criar código diretamente em .sessions:
+```
+<orchestrator>/.sessions/src/file.ts  ❌
+<orchestrator>/.sessions/<ISSUE-ID>/src/file.ts  ❌
+<orchestrator>/.sessions/<ISSUE-ID>/file.ts  ❌
+```
+
+**REGRA ABSOLUTA**:
+- 🛑 **TODO arquivo de código** (`.ts`, `.js`, `.py`, `.java`, etc.) **DEVE estar dentro de** `<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/`
+- 🛑 **NUNCA crie código** diretamente em `<orchestrator>/.sessions/` ou `<orchestrator>/.sessions/<ISSUE-ID>/`
+- ✅ **Único lugar válido**: Dentro do worktree do repositório específico
+
+## ⚠️ IMPORTANTE: Arquivos Imutáveis
+
+**Este comando deve LER mas NÃO MODIFICAR:**
+- ✅ **LER** `.sessions/<ISSUE-ID>/context.md` (imutável)
+- ✅ **LER** `.sessions/<ISSUE-ID>/architecture.md` (imutável)
+- ✅ **ATUALIZAR** `.sessions/<ISSUE-ID>/plan.md` (marcar progresso)
+- ✅ **IMPLEMENTAR** código **DENTRO DO WORKTREE**: `.sessions/<ISSUE-ID>/<repo-name>/`
+- ✅ **FAZER COMMITS** nos worktrees: `.sessions/<ISSUE-ID>/<repo-name>/`
+- ❌ **NÃO modificar `context.md` ou `architecture.md`**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais (fora do workspace)**
+- 🛑 **NUNCA criar código em `.sessions/` ou `.sessions/<ISSUE-ID>/` diretamente**
+
+## 📚 Carregar MetaSpecs
+
+**Localizar MetaSpecs automaticamente**:
+1. Leia `context-manifest.json` do orchestrator
+2. Encontre o repositório com `"role": "metaspecs"`
+3. Leia `ai.properties.md` para obter o `base_path`
+4. O metaspecs está em: `{base_path}/{metaspecs-repo-id}/`
+5. Leia os arquivos `index.md` relevantes durante a implementação para:
+   - Seguir padrões de código
+   - Respeitar arquitetura definida
+   - Usar convenções corretas
+
+## 🎯 Objetivo
+
+Implementar uma unidade de trabalho específica do plano, que pode envolver:
+- Criar novos arquivos/componentes
+- Modificar arquivos existentes
+- Adicionar testes
+- Atualizar documentação
+
+## 📝 Processo de Trabalho
+
+**⚠️ IMPORTANTE: CONTROLE DE PROGRESSO**
+
+Este comando executa o trabalho em **fases incrementais**. Após completar cada **FASE PRINCIPAL** (ex: Fase 1 → Fase 2):
+
+1. 🛑 **PARE** a execução
+2. 📊 **APRESENTE** um resumo do que foi feito
+3. ❓ **PERGUNTE** ao desenvolvedor se ele quer:
+   - Revisar o código implementado
+   - Fazer ajustes antes de continuar
+   - Prosseguir para a próxima fase
+
+**IMPORTANTE**:
+- ✅ **PAUSE** entre fases principais (Fase 1 → Fase 2 → Fase 3)
+- ❌ **NÃO pause** entre subfases (Fase 1.1 → Fase 1.2 → Fase 1.3)
+
+**NÃO implemente tudo de uma vez**. Trabalhe fase principal por fase principal, aguardando confirmação do desenvolvedor.
+
+---
+
+### 1. Identificar Unidade de Trabalho
+
+Com base no plano técnico (`./.sessions/<ISSUE-ID>/plan.md`), identifique:
+- Qual tarefa específica será implementada agora
+- Em qual(is) repositório(s) do workspace
+- Quais arquivos serão criados/modificados
+- Dependências com outras tarefas
+
+### 2. Implementação
+
+
+
+**IMPORTANTE**: Trabalhe APENAS dentro do workspace em `.sessions/<ISSUE-ID>/`
+
+Para cada repositório no workspace:
+
+```bash
+# Navegue para o worktree dentro do workspace
+cd <orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/
+
+# Verifique que está na branch correta
+git branch  # deve mostrar * feature/<ISSUE-ID>
+
+# Implemente o código aqui
+```
+
+Execute a implementação seguindo:
+- **Padrões do projeto**: Consulte guias de estilo e arquitetura
+- **Stack aprovada**: Use apenas tecnologias documentadas nas metaspecs
+- **Testes**: Implemente testes conforme padrões do projeto
+- **Documentação**: Atualize comentários e docs quando necessário
+
+
+
+### 3. Validação Local
+
+Antes de commitar:
+- Execute testes unitários/integração
+- Verifique linting e formatação
+- Confirme que não quebrou funcionalidades existentes
+
+
+
+### 4. Commit
+
+Para cada repositório modificado **dentro do workspace**:
+
+```bash
+# Navegue para o worktree dentro do workspace
+cd <orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/
+
+# Adicione as mudanças
+git add .
+
+# Commit
+git commit -m "tipo: descrição concisa
+
+- Detalhe 1
+- Detalhe 2
+
+Refs: <ISSUE-ID>"
+```
+
+**Tipos de commit**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+**⚠️ PAUSA OBRIGATÓRIA**: Após completar TODA a fase principal (identificação + implementação + validação + commit + atualização do plan.md), **PARE** e mostre ao desenvolvedor:
+- Resumo completo da fase
+- Arquivos criados/modificados
+- Commits realizados
+- Pergunte se ele quer revisar ou prosseguir para a próxima fase
+
+### 5. Atualização do Plan.md
+
+**A CADA tarefa completada**, atualize `./.sessions/<ISSUE-ID>/plan.md`:
+
+```markdown
+#### 1.1 - [Nome da Tarefa] [Completada ✅]
+- [Detalhe 1]
+- [Detalhe 2]
+- [Detalhe 3]
+
+**Arquivos**:
+- `path/to/file1.ts` ✅
+- `path/to/file2.vue` ✅
+
+**Testes**:
+- Unit test: [Descrição] ✅
+- Integration test: [Descrição] ✅
+
+**Comentários**:
+- Decisão: [Explicação de decisão técnica importante]
+- Aprendizado: [Algo aprendido durante implementação]
+```
+
+**Marque status das tarefas**:
+- `[Não Iniciada ⏳]` - Tarefa ainda não começou
+- `[Em Progresso ⏰]` - Tarefa sendo trabalhada agora
+- `[Completada ✅]` - Tarefa finalizada e validada
+
+## 🔍 Checklist de Qualidade
+
+Antes de considerar a unidade completa:
+- [ ] Código implementado e testado
+- [ ] Testes passando
+- [ ] Linting/formatação OK
+- [ ] Documentação atualizada (se necessário)
+- [ ] Commit realizado em todos os repos afetados
+- [ ] `plan.md` atualizado com progresso e comentários
+
+## ⚠️ Princípio Jidoka
+
+Se encontrar problemas durante a implementação:
+1. 🛑 **PARE** a implementação
+2. 📝 **DOCUMENTE** o problema encontrado
+3. 💬 **ALERTE** o usuário e discuta soluções
+4. 🔄 **AJUSTE** o plano se necessário
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximos Passos
+
+- **Continuar implementação**: Execute `/work` novamente para próxima unidade
+- **Finalizar feature**: Quando tudo estiver implementado, execute `/pre-pr`
+
+## 💡 Dicas
+
+- Trabalhe em unidades pequenas e incrementais
+- Commit frequentemente (atomic commits)
+- Documente decisões importantes na sessão
+- Mantenha os repositórios sincronizados entre si