context-first-cli 1.5.9 → 1.6.1

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

@@ -6,6 +6,40 @@ Este comando cria o plano técnico detalhado para implementação da feature.
 
 - PRD criado via `/spec`
 - Análise inicial feita via `/start`
+- Arquivos `context.md` e `architecture.md` criados e aprovados
+
+## 📍 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
 

package/dist/templates/commands/engineer/start.md

@@ -2,6 +2,30 @@
 
 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)
+
 ## 📚 Carregar MetaSpecs
 
 **Localizar MetaSpecs automaticamente**:
@@ -13,6 +37,7 @@ Este comando inicia o desenvolvimento de uma funcionalidade no workspace atual.
    - Contexto de negócio
    - Stack, arquitetura e padrões técnicos
    - Convenções do projeto
+   - ADRs (Architecture Decision Records)
 
 ## 🎯 Contexto do Projeto
 
@@ -77,34 +102,154 @@ Após análise inicial, formule **3-5 clarificações mais importantes**:
 - Qual a ordem de implementação recomendada?
 - Há impacto em APIs ou contratos entre serviços?
 
-## 📝 Documentação da Sessão
+## 💾 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>/start.md` com:
+Crie arquivo `./.sessions/<ISSUE-ID>/context.md` com:
 
 ```markdown
-# [Título da Feature] - Início
+# Context: [Nome da Feature]
+
+## Por Que
+[Valor de negócio, persona atendida, métrica impactada]
+
+## O Que
+[Funcionalidades principais, comportamento esperado]
 
-## Entendimento
-[Resumo do que será construído e por quê]
+## Como
+[Abordagem técnica, componentes, repositórios afetados]
 
-## Repositórios Afetados
-- **repo-1**: [O que será feito]
-- **repo-2**: [O que será feito]
+## 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
 
-## Perguntas Pendentes
-1. [Pergunta 1]
-2. [Pergunta 2]
+## Dependências
+[Bibliotecas, APIs, componentes existentes]
 
-## Validações Realizadas
-- [x] Alinhado com estratégia
-- [x] Stack aprovada
-- [ ] Pendente: [algo a validar]
+## Restrições
+[Limitações técnicas, performance targets, budget]
 
-## Próximos Passos
-1. Aguardar respostas das perguntas
-2. Executar `/plan` para planejamento técnico detalhado
+## 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**:
@@ -117,10 +262,20 @@ Crie arquivo `./.sessions/<ISSUE-ID>/start.md` com:
 
 ## 🎯 Próximo Passo
 
-Após esclarecimentos e aprovação:
+**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/engineer/work.md

@@ -6,8 +6,46 @@ Este comando executa uma unidade de trabalho no workspace atual, implementando p
 
 Antes de executar, certifique-se de que:
 - Executou `/start` e `/plan` para ter o planejamento técnico
-- Está no workspace correto (verifique `diretório do workspace`)
-- Tem o arquivo `./.sessions/<ISSUE-ID>/plan.md` disponível
+- 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)
+
+## 📍 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}/`
+
+## ⚠️ 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 nos repositórios do workspace
+- ✅ **FAZER COMMITS** nos repositórios do workspace
+- ❌ **NÃO modificar `context.md` ou `architecture.md`**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais (fora do workspace)**
 
 ## 📚 Carregar MetaSpecs
 
@@ -41,6 +79,20 @@ Com base no plano técnico (`./.sessions/<ISSUE-ID>/plan.md`), identifique:
 
 ### 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
@@ -56,11 +108,16 @@ Antes de commitar:
 
 ### 4. Commit
 
-Para cada repositório modificado:
+Para cada repositório modificado **dentro do workspace**:
 
 ```bash
-cd <repositório>
+# 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

package/dist/templates/commands/products/check.md

@@ -2,6 +2,16 @@
 
 Este comando valida requisitos, decisões ou implementações contra as metaspecs do projeto.
 
+## ⚠️ IMPORTANTE: Modo de Operação
+
+**Este comando é para VALIDAÇÃO:**
+- ✅ Validar contra metaspecs
+- ✅ **LER** arquivos dos repositórios (read-only)
+- ✅ Gerar relatório de validação
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO modificar código**
+- ❌ **NÃO modificar `context.md` ou `architecture.md`**
+
 ## 🎯 Objetivo
 
 Garantir alinhamento com:

package/dist/templates/commands/products/collect.md

@@ -8,8 +8,11 @@ Você é um especialista em produto responsável por coletar e documentar novas
 - ✅ Coletar e entender requisitos
 - ✅ Criar issue no task manager via MCP
 - ✅ Fazer perguntas de esclarecimento
+- ✅ **LER** arquivos dos repositórios principais (read-only)
 - ❌ **NÃO implementar código**
 - ❌ **NÃO fazer edits em arquivos de código**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO fazer commits**
 
 **Próximo passo**: `/refine [ISSUE-ID]` para refinar os requisitos coletados.
 

package/dist/templates/commands/products/refine.md

@@ -4,7 +4,14 @@ Este comando refina uma issue coletada, transformando-a em requisitos claros e v
 
 ## ⚠️ IMPORTANTE: Este Comando NÃO Implementa Código
 
-Este comando é para refinamento de requisitos, não implementação.
+**Este comando é APENAS para refinamento de requisitos:**
+- ✅ Refinar e validar requisitos
+- ✅ Atualizar issue no task manager via MCP
+- ✅ **LER** arquivos dos repositórios principais (read-only)
+- ❌ **NÃO implementar código**
+- ❌ **NÃO fazer edits em arquivos de código**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO fazer commits**
 
 **Próximo passo**: `/spec [ISSUE-ID]` para criar a especificação completa (PRD).
 

package/dist/templates/commands/products/spec.md

@@ -4,7 +4,14 @@ Este comando cria a especificação completa (Product Requirements Document) da
 
 ## ⚠️ IMPORTANTE: Este Comando NÃO Implementa Código
 
-Este comando é para documentação de requisitos, não implementação.
+**Este comando é APENAS para documentação de requisitos:**
+- ✅ Criar PRD (Product Requirements Document)
+- ✅ Atualizar issue no task manager via MCP
+- ✅ **LER** arquivos dos repositórios principais (read-only)
+- ❌ **NÃO implementar código**
+- ❌ **NÃO fazer edits em arquivos de código**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO fazer commits**
 
 **Próximo passo**: `/start` para iniciar o desenvolvimento.
 

package/package.json

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

package/templates/commands/engineer/plan.md

@@ -6,6 +6,40 @@ Este comando cria o plano técnico detalhado para implementação da feature.
 
 - PRD criado via `/spec`
 - Análise inicial feita via `/start`
+- Arquivos `context.md` e `architecture.md` criados e aprovados
+
+## 📍 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
 

package/templates/commands/engineer/start.md

@@ -2,6 +2,30 @@
 
 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)
+
 ## 📚 Carregar MetaSpecs
 
 **Localizar MetaSpecs automaticamente**:
@@ -13,6 +37,7 @@ Este comando inicia o desenvolvimento de uma funcionalidade no workspace atual.
    - Contexto de negócio
    - Stack, arquitetura e padrões técnicos
    - Convenções do projeto
+   - ADRs (Architecture Decision Records)
 
 ## 🎯 Contexto do Projeto
 
@@ -77,34 +102,154 @@ Após análise inicial, formule **3-5 clarificações mais importantes**:
 - Qual a ordem de implementação recomendada?
 - Há impacto em APIs ou contratos entre serviços?
 
-## 📝 Documentação da Sessão
+## 💾 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>/start.md` com:
+Crie arquivo `./.sessions/<ISSUE-ID>/context.md` com:
 
 ```markdown
-# [Título da Feature] - Início
+# Context: [Nome da Feature]
+
+## Por Que
+[Valor de negócio, persona atendida, métrica impactada]
+
+## O Que
+[Funcionalidades principais, comportamento esperado]
 
-## Entendimento
-[Resumo do que será construído e por quê]
+## Como
+[Abordagem técnica, componentes, repositórios afetados]
 
-## Repositórios Afetados
-- **repo-1**: [O que será feito]
-- **repo-2**: [O que será feito]
+## 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
 
-## Perguntas Pendentes
-1. [Pergunta 1]
-2. [Pergunta 2]
+## Dependências
+[Bibliotecas, APIs, componentes existentes]
 
-## Validações Realizadas
-- [x] Alinhado com estratégia
-- [x] Stack aprovada
-- [ ] Pendente: [algo a validar]
+## Restrições
+[Limitações técnicas, performance targets, budget]
 
-## Próximos Passos
-1. Aguardar respostas das perguntas
-2. Executar `/plan` para planejamento técnico detalhado
+## 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**:
@@ -117,10 +262,20 @@ Crie arquivo `./.sessions/<ISSUE-ID>/start.md` com:
 
 ## 🎯 Próximo Passo
 
-Após esclarecimentos e aprovação:
+**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/templates/commands/engineer/work.md

@@ -6,8 +6,46 @@ Este comando executa uma unidade de trabalho no workspace atual, implementando p
 
 Antes de executar, certifique-se de que:
 - Executou `/start` e `/plan` para ter o planejamento técnico
-- Está no workspace correto (verifique `diretório do workspace`)
-- Tem o arquivo `./.sessions/<ISSUE-ID>/plan.md` disponível
+- 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)
+
+## 📍 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}/`
+
+## ⚠️ 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 nos repositórios do workspace
+- ✅ **FAZER COMMITS** nos repositórios do workspace
+- ❌ **NÃO modificar `context.md` ou `architecture.md`**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais (fora do workspace)**
 
 ## 📚 Carregar MetaSpecs
 
@@ -41,6 +79,20 @@ Com base no plano técnico (`./.sessions/<ISSUE-ID>/plan.md`), identifique:
 
 ### 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
@@ -56,11 +108,16 @@ Antes de commitar:
 
 ### 4. Commit
 
-Para cada repositório modificado:
+Para cada repositório modificado **dentro do workspace**:
 
 ```bash
-cd <repositório>
+# 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

package/templates/commands/products/check.md

@@ -2,6 +2,16 @@
 
 Este comando valida requisitos, decisões ou implementações contra as metaspecs do projeto.
 
+## ⚠️ IMPORTANTE: Modo de Operação
+
+**Este comando é para VALIDAÇÃO:**
+- ✅ Validar contra metaspecs
+- ✅ **LER** arquivos dos repositórios (read-only)
+- ✅ Gerar relatório de validação
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO modificar código**
+- ❌ **NÃO modificar `context.md` ou `architecture.md`**
+
 ## 🎯 Objetivo
 
 Garantir alinhamento com:

package/templates/commands/products/collect.md

@@ -8,8 +8,11 @@ Você é um especialista em produto responsável por coletar e documentar novas
 - ✅ Coletar e entender requisitos
 - ✅ Criar issue no task manager via MCP
 - ✅ Fazer perguntas de esclarecimento
+- ✅ **LER** arquivos dos repositórios principais (read-only)
 - ❌ **NÃO implementar código**
 - ❌ **NÃO fazer edits em arquivos de código**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO fazer commits**
 
 **Próximo passo**: `/refine [ISSUE-ID]` para refinar os requisitos coletados.
 

package/templates/commands/products/refine.md

@@ -4,7 +4,14 @@ Este comando refina uma issue coletada, transformando-a em requisitos claros e v
 
 ## ⚠️ IMPORTANTE: Este Comando NÃO Implementa Código
 
-Este comando é para refinamento de requisitos, não implementação.
+**Este comando é APENAS para refinamento de requisitos:**
+- ✅ Refinar e validar requisitos
+- ✅ Atualizar issue no task manager via MCP
+- ✅ **LER** arquivos dos repositórios principais (read-only)
+- ❌ **NÃO implementar código**
+- ❌ **NÃO fazer edits em arquivos de código**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO fazer commits**
 
 **Próximo passo**: `/spec [ISSUE-ID]` para criar a especificação completa (PRD).
 

package/templates/commands/products/spec.md

@@ -4,7 +4,14 @@ Este comando cria a especificação completa (Product Requirements Document) da
 
 ## ⚠️ IMPORTANTE: Este Comando NÃO Implementa Código
 
-Este comando é para documentação de requisitos, não implementação.
+**Este comando é APENAS para documentação de requisitos:**
+- ✅ Criar PRD (Product Requirements Document)
+- ✅ Atualizar issue no task manager via MCP
+- ✅ **LER** arquivos dos repositórios principais (read-only)
+- ❌ **NÃO implementar código**
+- ❌ **NÃO fazer edits em arquivos de código**
+- ❌ **NÃO fazer checkout de branches nos repositórios principais**
+- ❌ **NÃO fazer commits**
 
 **Próximo passo**: `/start` para iniciar o desenvolvimento.