context-first-cli 2.3.2 → 2.3.4

package/README.md

@@ -17,6 +17,7 @@ Orchestrate multi-repository workflows, create isolated feature workspaces, and
 - [Installation](#installation)
 - [Commands](#commands)
 - [Workflow Guide](#workflow-guide)
+  - [AI Commands Workflow](#ai-commands-workflow)
 - [Docker Support](#docker-support)
 - [Architecture](#architecture)
 - [Examples](#examples)
@@ -174,6 +175,106 @@ npx context-first-cli@latest <command>
 
 ## Workflow Guide
 
+### AI Commands Workflow
+
+Context-First CLI includes **markdown-based AI commands** that guide AI assistants through a structured development workflow. These commands are installed in your orchestrator and can be invoked in AI assistants like Claude, Cursor, or Windsurf.
+
+#### Complete Workflow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        CONTEXT-FIRST WORKFLOW                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌──────────┐                                                               │
+│  │ warm-up  │  Load project context, metaspecs, and configuration          │
+│  └────┬─────┘                                                               │
+│       │                                                                     │
+│       ▼                                                                     │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      PRODUCT DISCOVERY                               │   │
+│  │                                                                       │   │
+│  │  ┌─────────┐    ┌────────┐    ┌──────┐    ┌───────┐                 │   │
+│  │  │ collect │ -> │ refine │ -> │ spec │ -> │ check │                 │   │
+│  │  └─────────┘    └────────┘    └──────┘    └───────┘                 │   │
+│  │   Gather         Refine &      Create      Validate                  │   │
+│  │   requirements   prioritize    specs       alignment                 │   │
+│  │                                                                       │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│       │                                                                     │
+│       ▼                                                                     │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      ENGINEERING                                     │   │
+│  │                                                                       │   │
+│  │  ┌───────┐    ┌──────┐    ┌──────┐    ┌────────┐    ┌────┐         │   │
+│  │  │ start │ -> │ plan │ -> │ work │ -> │ pre-pr │ -> │ pr │         │   │
+│  │  └───────┘    └──────┘    └──────┘    └────────┘    └────┘         │   │
+│  │   Create       Plan        Implement   Review &      Create         │   │
+│  │   workspace    approach    feature     validate      PR             │   │
+│  │                                                                       │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Command Reference
+
+| Phase | Command | Description |
+|-------|---------|-------------|
+| **Context** | `/warm-up` | Load project context, metaspecs, and configuration files |
+| **Products** | `/products/collect` | Gather requirements from stakeholders and documentation |
+| | `/products/refine` | Refine and prioritize collected requirements |
+| | `/products/spec` | Create detailed technical specifications |
+| | `/products/check` | Validate alignment between specs and implementation |
+| **Engineer** | `/engineer/start` | Create workspace, branches, and initial context |
+| | `/engineer/plan` | Create implementation plan with architecture decisions |
+| | `/engineer/work` | Implement the feature following the plan |
+| | `/engineer/pre-pr` | Run validations, tests, and pre-PR checklist |
+| | `/engineer/pr` | Create Pull Request with proper documentation |
+| **Quality** | `/quality/observe` | Monitor and analyze code quality |
+| | `/quality/metrics` | Collect and report quality metrics |
+
+#### Using the Commands
+
+1. **Start your session** with `/warm-up` to load the project context
+2. **For new features**, follow the product discovery flow: `collect` → `refine` → `spec` → `check`
+3. **For implementation**, follow the engineering flow: `start` → `plan` → `work` → `pre-pr` → `pr`
+
+**Example session:**
+
+```bash
+# In your AI assistant (Claude, Cursor, etc.)
+
+/warm-up
+# AI loads project context and metaspecs
+
+/engineer/start FIN-123
+# AI creates workspace and initial documentation
+
+/engineer/plan
+# AI creates implementation plan
+
+/engineer/work
+# AI implements the feature
+
+/engineer/pre-pr
+# AI runs tests and validations
+
+/engineer/pr
+# AI creates the Pull Request
+```
+
+#### Available Languages
+
+Commands are available in:
+- 🇺🇸 **English** (`en`)
+- 🇪🇸 **Español** (`es`)
+- 🇧🇷 **Português** (`pt-BR`)
+
+Select your language when running `create:orchestrator` or `update:commands`.
+
+---
+
 ### Initial Setup (Once Per Project)
 
 #### Step 1: Create Orchestrator
@@ -301,12 +402,13 @@ $ npx context-first-cli@latest feature add-repo FIN-123
 # Open in editor
 code .
 
-# Use AI commands (if configured)
-/start    # Create context.md and architecture.md
-/plan     # Create plan.md
-/work     # Implement feature
-/pre-pr   # Review before PR
-/pr       # Create pull request
+# Use AI commands (in your AI assistant)
+/warm-up              # Load project context
+/engineer/start       # Create context.md and architecture.md
+/engineer/plan        # Create implementation plan
+/engineer/work        # Implement feature
+/engineer/pre-pr      # Review and validate before PR
+/engineer/pr          # Create pull request
 ```
 
 #### Stop Services

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-first-cli",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "A generic CLI to manage the Context-First development methodology across any project.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -1,301 +0,0 @@
-# Planejamento Técnico
-
-Este comando cria o plano técnico detalhado para implementação da feature.
-
-## 📋 Pré-requisitos
-
-- PRD criado via `/spec`
-- Análise inicial feita via `/start`
-- Arquivos `context.md` e `architecture.md` criados e aprovados
-
-## Configuração
-
-Leia `context-manifest.json` e `ai.properties.md` do orchestrator para obter repositórios, base_path e task_management_system.
-
-## 📍 IMPORTANTE: Entenda a Estrutura
-
-**Workspace**:
-```
-<orchestrator>/.sessions/<ISSUE-ID>/
-├── repo-1/          # worktree (será usado no /work)
-├── repo-2/          # worktree (será usado no /work)
-├── context.md       # contexto (imutável - LER)
-├── architecture.md  # arquitetura (imutável - LER)
-└── plan.md          # plano (mutável - CRIAR)
-```
-
-**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 `context.md` e `architecture.md` (imutáveis)
-- ✅ Crie `plan.md` em `.sessions/<ISSUE-ID>/`
-- ✅ Leia código dos repositórios principais (read-only)
-- ❌ NUNCA faça checkout nos repositórios principais
-- ❌ NUNCA modifique `context.md` ou `architecture.md`
-
-## ⚠️ 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)
-- ✅ **CRIAR** `.sessions/<ISSUE-ID>/plan.md` (mutável - será atualizado durante `/work`)
-- ❌ **NÃO modificar `context.md` ou `architecture.md`**
-
-## 📚 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 para garantir conformidade com:
-   - Arquitetura do sistema
-   - Padrões de design e código
-   - Estrutura de pastas e arquivos
-   - Convenções de nomenclatura
-
-## 🎯 Objetivo
-
-Criar um plano técnico detalhado que guiará a implementação, dividindo o trabalho em unidades menores e sequenciais.
-
-## 📝 Estrutura do Plano
-
-### 1. Visão Geral Técnica
-
-```markdown
-# Plano Técnico - [Título da Feature]
-
-## Resumo
-[Breve descrição técnica do que será implementado]
-
-## Repositórios Envolvidos
-- **<repo-1>**: [Papel nesta feature]
-- **<repo-2>**: [Papel nesta feature]
-
-## Abordagem Técnica
-[Estratégia geral de implementação]
-```
-
-### 2. Arquitetura da Solução
-
-```markdown
-## Arquitetura
-
-### Diagrama de Componentes
-[Descrição textual ou ASCII art dos componentes e suas relações]
-
-### Fluxo de Dados
-1. [Passo 1 do fluxo]
-2. [Passo 2 do fluxo]
-3. [Passo 3 do fluxo]
-
-### Integrações
-- **<repo-1> → <repo-2>**: [Como se comunicam]
-- **Sistema → API Externa**: [Se houver]
-```
-
-### 3. Decisões Técnicas
-
-```markdown
-## 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]
-
-### Decisão 2: [Título]
-[Mesmo formato acima]
-```
-
-### 4. Plano de Implementação
-
-Divida o trabalho em unidades pequenas e sequenciais:
-
-```markdown
-## Plano de Implementação
-
-### Fase 1: [Nome da Fase]
-**Objetivo**: [O que será alcançado nesta fase]
-**Repositórios**: [repos afetados]
-
-#### Tarefa 1.1: [Descrição]
-- **Repo**: <repo-1>
-- **Arquivos**: [arquivos a criar/modificar]
-- **Descrição**: [O que fazer]
-- **Testes**: [Testes a implementar]
-- **Estimativa**: [tempo estimado]
-
-#### Tarefa 1.2: [Descrição]
-- **Repo**: <repo-2>
-- **Arquivos**: [arquivos a criar/modificar]
-- **Descrição**: [O que fazer]
-- **Testes**: [Testes a implementar]
-- **Estimativa**: [tempo estimado]
-
-### Fase 2: [Nome da Fase]
-[Mesmo formato acima]
-
-### Fase 3: [Nome da Fase]
-[Mesmo formato acima]
-```
-
-### 5. Estrutura de Arquivos
-
-Para cada repositório, defina a estrutura:
-
-```markdown
-## Estrutura de Arquivos
-
-### <repo-1>
-```
-src/
-├── components/
-│   ├── NewComponent.tsx (CRIAR)
-│   └── ExistingComponent.tsx (MODIFICAR)
-├── services/
-│   └── NewService.ts (CRIAR)
-└── tests/
-    └── NewComponent.test.tsx (CRIAR)
-```
-
-### <repo-2>
-```
-src/
-├── controllers/
-│   └── NewController.ts (CRIAR)
-└── tests/
-    └── NewController.test.ts (CRIAR)
-```
-```
-
-### 6. APIs e Contratos
-
-```markdown
-## APIs e Contratos
-
-### Endpoints Novos
-
-#### POST /api/resource
-**Request**:
-```json
-{
-  "field1": "string",
-  "field2": "number"
-}
-```
-
-**Response**:
-```json
-{
-  "id": "string",
-  "status": "string"
-}
-```
-
-### Endpoints Modificados
-
-#### GET /api/resource/:id
-**Mudanças**: [O que muda]
-**Breaking Change**: Sim / Não
-```
-
-### 7. Estratégia de Testes
-
-```markdown
-## Estratégia de Testes
-
-### Testes Unitários
-- **<repo-1>**: [Componentes/funções a testar]
-- **<repo-2>**: [Componentes/funções a testar]
-
-### Testes de Integração
-- **Cenário 1**: [Descrição e repos envolvidos]
-- **Cenário 2**: [Descrição e repos envolvidos]
-
-### Testes E2E (se aplicável)
-- **Fluxo 1**: [Descrição]
-- **Fluxo 2**: [Descrição]
-```
-
-### 8. Riscos Técnicos
-
-```markdown
-## Riscos Técnicos
-
-### Risco 1: [Descrição]
-- **Impacto**: Alto / Médio / Baixo
-- **Probabilidade**: Alta / Média / Baixa
-- **Mitigação**: [Como mitigar]
-- **Plano B**: [Alternativa se ocorrer]
-
-### Risco 2: [Descrição]
-[Mesmo formato acima]
-```
-
-### 9. Checklist de Implementação
-
-```markdown
-## Checklist de Implementação
-
-### Fase 1
-- [ ] Tarefa 1.1
-- [ ] Tarefa 1.2
-- [ ] Testes da Fase 1
-
-### Fase 2
-- [ ] Tarefa 2.1
-- [ ] Tarefa 2.2
-- [ ] Testes da Fase 2
-
-### Fase 3
-- [ ] Tarefa 3.1
-- [ ] Tarefa 3.2
-- [ ] Testes da Fase 3
-
-### Finalização
-- [ ] Documentação atualizada
-- [ ] Code review
-- [ ] Testes de integração
-- [ ] PR criado
-```
-
-## 📄 Salvamento do Plano
-
-Salve em `./.sessions/<ISSUE-ID>/plan.md`
-
-## 🔍 Revisão
-
-Revise o plano verificando:
-- Todas as tarefas estão claras e executáveis
-- Dependências entre tarefas estão identificadas
-- Estimativas são realistas
-- Riscos foram considerados
-- Estratégia de testes é adequada
-
----
-
-**Argumentos fornecidos**:
-
-```
-#$ARGUMENTS
-```
-
----
-
-## 🎯 Próximo Passo
-
-Após aprovação do plano:
-
-```bash
-/work
-```
-
-Este comando iniciará a execução da primeira unidade de trabalho do plano.

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

@@ -1,194 +0,0 @@
-# Criação de Pull Request
-
-Este comando cria Pull Requests para todos os repositórios modificados no workspace.
-
-## 📋 Pré-requisitos
-
-Antes de criar PRs, certifique-se de que:
-- Executou `/pre-pr` e todas as validações passaram
-- Todos os commits foram feitos
-- Todos os testes estão passando
-- A documentação está atualizada
-
-## Configuração
-
-Leia `context-manifest.json` e `ai.properties.md` do orchestrator para obter repositórios, base_path e task_management_system.
-
-## 🛑 CRÍTICO: ONDE TRABALHAR
-
-**⚠️ ATENÇÃO: Se precisar fazer ajustes de última hora, TODO CÓDIGO DEVE SER CRIADO DENTRO DO WORKTREE!**
-
-**✅ CORRETO** - Trabalhar dentro do worktree:
-```
-<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/src/file.ts  ✅
-<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/README.md  ✅
-<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/CHANGELOG.md  ✅
-```
-
-**❌ ERRADO** - NUNCA criar código fora do worktree:
-```
-<orchestrator>/.sessions/file.ts  ❌
-<orchestrator>/.sessions/<ISSUE-ID>/file.ts  ❌
-{base_path}/<repo-name>/file.ts  ❌ (repositório principal!)
-```
-
-**REGRA ABSOLUTA**:
-- 🛑 **Qualquer ajuste de código** (docs, changelog, fixes) **DEVE estar em** `<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/`
-- 🛑 **NUNCA modifique** o repositório principal em `{base_path}/<repo-name>/`
-- ✅ **Trabalhe APENAS** dentro do worktree do repositório específico
-
-## 🎯 Processo de Criação de PRs
-
-### 1. Identificar Repositórios Modificados
-
-Para cada repositório no workspace, verifique:
-```bash
-cd <repositório>
-git status
-git log origin/main..HEAD  # Ver commits não pushados
-```
-
-### 2. Push das Branches
-
-Para cada repositório modificado:
-```bash
-cd <repositório>
-git push origin <branch-name>
-```
-
-### 3. Criar Pull Requests
-
-Para cada repositório, crie um PR usando o GitHub CLI ou interface web:
-
-**Usando GitHub CLI**:
-```bash
-cd <repositório>
-gh pr create --title "[ISSUE-ID] Título da Feature" \
-  --body "$(cat ../.sessions/<ISSUE-ID>/pr-description.md)" \
-  --base main
-```
-
-**Template de Descrição do PR**:
-
-```markdown
-## 🎯 Objetivo
-
-[Breve descrição do que esta PR faz]
-
-## 📝 Mudanças
-
-### Repositório: <nome-do-repo>
-
-- [Mudança 1]
-- [Mudança 2]
-- [Mudança 3]
-
-## 🔗 Relacionamentos
-
-- **Issue**: <ISSUE-ID>
-- **PRs Relacionados**: 
-  - <repo-1>#<PR-number>
-  - <repo-2>#<PR-number>
-
-## ✅ Checklist
-
-- [ ] Código implementado e testado
-- [ ] Testes unitários adicionados/atualizados
-- [ ] Testes de integração passando
-- [ ] Documentação atualizada
-- [ ] Sem breaking changes (ou documentados)
-- [ ] Revisado por pares (após criação do PR)
-
-## 🧪 Como Testar
-
-1. [Passo 1]
-2. [Passo 2]
-3. [Resultado esperado]
-
-## 📸 Screenshots/Demos
-
-[Se aplicável, adicione screenshots ou links para demos]
-
-## 🔍 Notas para Revisores
-
-- [Ponto de atenção 1]
-- [Ponto de atenção 2]
-```
-
-### 4. Vincular PRs
-
-Se houver múltiplos PRs (um por repositório):
-- Adicione links cruzados entre os PRs
-- Documente a ordem de merge recomendada
-- Indique dependências entre PRs
-
-### 5. Atualizar Issue no Task Manager
-
-Se task manager estiver configurado:
-- Mova a issue para "Em Revisão" ou "PR Aberto"
-- Adicione links dos PRs na issue
-- Adicione comentário com resumo das mudanças
-
-### 6. Documentação da Sessão
-
-Atualize `./.sessions/<ISSUE-ID>/pr.md`:
-
-```markdown
-# [Título da Feature] - Pull Requests
-
-## PRs Criados
-
-### <repo-1>
-- **Link**: <URL do PR>
-- **Status**: Aberto
-- **Commits**: X commits
-
-### <repo-2>
-- **Link**: <URL do PR>
-- **Status**: Aberto
-- **Commits**: Y commits
-
-## Ordem de Merge Recomendada
-
-1. <repo-1> - [Justificativa]
-2. <repo-2> - [Justificativa]
-
-## Notas para Merge
-
-- [Nota importante 1]
-- [Nota importante 2]
-```
-
-## 🔍 Checklist Final
-
-Antes de solicitar revisão:
-- [ ] Todos os PRs criados
-- [ ] Descrições completas e claras
-- [ ] PRs vinculados entre si
-- [ ] Issue atualizada no task manager
-- [ ] Testes passando em CI/CD
-- [ ] Documentação da sessão completa
-
-## 📢 Comunicação
-
-Notifique o time sobre os PRs:
-- Mencione revisores relevantes
-- Destaque mudanças críticas ou breaking changes
-- Indique urgência se aplicável
-
----
-
-**Argumentos fornecidos**:
-
-```
-#$ARGUMENTS
-```
-
----
-
-## 🎯 Próximos Passos
-
-1. Aguardar revisão dos PRs
-2. Responder comentários e fazer ajustes
-3. Após aprovação, fazer merge na ordem recomendada
-4. Executar `context-cli feature:end <ISSUE-ID>` para limpar o workspace