jarvis-ai-framework 1.0.0

package/rules/engineering/eng.downstream-flow-rules.md

@@ -0,0 +1,297 @@
+---
+trigger: always_on
+env_file: "@/ENV.md"
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: all | SQUAD: all
+
+# Regras de Fluxo Downstream — Responsáveis e Critérios
+
+> Referência obrigatória ao mover cards no board (Jira, GitLab, Linear ou equivalente).
+> Consultar antes de orientar o usuário sobre transição de status.
+
+---
+
+> Fonte de cargos: `taxonomy.md`. Este arquivo define o fluxo. Autonomia: o profissional que assumiu o card conduz ponta-a-ponta.
+
+## Princípio de autonomia
+
+Quem assumiu o card é o **owner** e pode avançar **todas** as transições abaixo.
+TECH LEAD, PM e pares **revisam e apoiam** — não precisam clicar para o trabalho continuar.
+
+Papéis no fluxo (ainda existem; não são cadeado):
+
+| Papel no Fluxo | Positions | Papel |
+|---|---|---|
+| **Owner** | quem pegou o card: DEV, TECH LEAD ou PM | Conduz ponta-a-ponta |
+| **DEV** | `JUNIOR`, `PLENO`, `SENIOR`, `SPECIALIST` | Entrega técnica |
+| **TECH LEAD** | `TECH LEAD` | Apoia priorização, review e deploy quando pedido |
+| **PM** | `PM`, `TPM`, `GPM` | Apoia aceite de produto quando pedido |
+| **QA** | `QA-ENGINEER` | Executa testes em apoio; não bloqueia o owner |
+| **N2** | Tech Analyst / suporte | Validação operacional se o time tiver esse papel |
+
+## Diagrama do Fluxo
+
+```mermaid
+graph TD
+    A[A fazer] -->|Owner puxa| B[Pronto para desenvolvimento]
+    B -->|Owner assume| C[Em progresso]
+    C -->|Owner abre MR| D[Review de código]
+    D -->|Owner após merge/review| E[Pronto para QA]
+    E -->|Owner inicia testes| F[Em QA]
+    F -->|Owner se negativo +flag| B
+    F -->|Owner se positivo| G[Pronto para produto]
+    G -->|Owner ou PM se ajuste +flag| B
+    G -->|Owner ou PM se OK| H[Pronto para deploy]
+    H -->|Owner inicia deploy| I[Em rollout]
+    I -->|Owner quando estável| J[Validação]
+    J -->|Owner/PM/N2 se problema| B
+    J -->|Owner/PM/N2 se OK| K[Pronto/Cancelado]
+    A -.->|Owner/TL/PM cancelam| K
+```
+
+---
+
+## Matriz de Transições (Quem move o quê)
+
+Default: **Owner do card**. TL/PM podem mover também (apoio), nunca como bloqueio.
+
+| De | Para | Quem move | Quando mover |
+|---|---|---|---|
+| **A fazer** | Pronto para desenvolvimento | **Owner** (DEV, TL ou PM) | Quando o card estiver claro o bastante para puxar |
+| **Pronto para desenvolvimento** | Em progresso | **Owner** | Quando assumir e começar |
+| **Em progresso** | Review de código | **Owner** | Quando abrir MR pronto para revisão |
+| **Review de código** | Pronto para QA | **Owner** | Após merge ou review (qualquer revisor; TL não é obrigatório) |
+| **Pronto para QA** | Em QA | **Owner** | Quando iniciar testes |
+| **Em QA** | Pronto para produto | **Owner** | Resultado positivo |
+| **Em QA** | Pronto para desenvolvimento | **Owner** | Resultado negativo — flag + comentário |
+| **Pronto para produto** | Pronto para deploy | **Owner ou PM** | Aceite (owner pode auto-aceitar se PM não estiver no fluxo) |
+| **Pronto para produto** | Pronto para desenvolvimento | **Owner ou PM** | Ajustes — flag + comentário |
+| **Pronto para deploy** | Em rollout | **Owner** | Quando iniciar deploy |
+| **Em rollout** | Validação | **Owner** | Deploy estável |
+| **Validação** | Pronto/Cancelado | **Owner, PM ou N2** | Validação ok |
+| **Validação** | Pronto para desenvolvimento | **Owner, PM ou N2** | Problema — comentário |
+| **Qualquer etapa** | Pronto/Cancelado | **Owner, TL ou PM** | Cancelar com motivo |
+
+---
+
+## Responsabilidades no Fluxo
+
+### Owner (DEV, TECH LEAD ou PM — quem assumiu)
+- Puxa, implementa, abre MR, faz merge, valida, aceita e faz deploy do **próprio** card.
+- Pede review/ajuda quando quiser — não é obrigatório esperar.
+
+### TECH LEAD
+- Apoia priorização, review e deploy **quando pedido**.
+- Pode mover qualquer card (destravar, cancelar, cobrir férias).
+- Não é gate: o DEV não espera o TL para avançar.
+
+### DEV
+- Dono da entrega ponta-a-ponta dos cards que assumiu.
+- Pode escrever spec de produto, tech spec e subtarefas.
+
+### QA
+- Executa testes e reporta bugs em apoio ao owner.
+- Não bloqueia o owner de avançar depois de registrar o resultado.
+
+### PM / TPM / GPM
+- Pode escrever spec, priorizar e aceitar.
+- Pode assumir um card e conduzi-lo (incluindo handoff técnico).
+- Aceite de produto é desejável, não cadeado: owner avança se PM não estiver no fluxo.
+
+### N2
+- Validação operacional pós-deploy **se o time tiver esse papel**.
+- Owner pode encerrar o card se não houver N2.
+
+---
+
+## Detalhamento dos Estágios
+
+### 1) A fazer — Owner: quem for puxar
+
+**Objetivo:** fila saudável e "puxável".
+
+**Pronto para entrar:**
+- Contexto mínimo existe (objetivo, escopo, restrições, critérios de aceite).
+- Dependências mapeadas (ou explicitamente "nenhuma").
+
+**Saídas:** *Pronto para desenvolvimento* quando o profissional puxar (DEV, TL ou PM).
+
+**Responsabilidades:**
+- Owner (ou TL/PM se estiver refinando o backlog) deixa o card puxável.
+- Não esperar o TL para puxar um card já claro.
+
+---
+
+### 2) Pronto para desenvolvimento — Owner: DEV
+
+**Objetivo:** sinalizar que pode ser iniciado imediatamente.
+
+**Pronto para entrar:**
+- Critérios de aceite claros.
+- Definição de "feito" acordada (testes, logs, métricas, migração, feature flag, etc.).
+
+**Saídas:** *Em progresso* quando alguém pegar.
+
+**Responsabilidades do DEV:**
+- Assumir a entrega ponta-a-ponta do card (inclui QA/ajustes até pronto).
+
+> O owner move para "Em progresso" ao assumir. Se o card ficar parado, qualquer DEV/TL/PM pode puxá-lo.
+
+---
+
+### 3) Em progresso — Owner: DEV
+
+**Objetivo:** implementação ativa.
+
+**Pronto para entrar:** card já assumido, branch/MR iniciados.
+
+**Saídas:** *Review de código* quando houver MR pronto.
+
+**Responsabilidades do DEV:**
+- Comunicar riscos cedo (bloqueios, escopo estourando, dependências).
+- Garantir checklist básico (lint/test/build, migrações, logs/telemetria quando aplicável).
+
+---
+
+### 4) Review de código — Owner: DEV
+
+**Objetivo:** MR em revisão até merge.
+
+**Pronto para entrar:**
+- MR aberto, descrevendo mudança, riscos, como testar, rollback/flag quando aplicável.
+- Link do ticket no MR.
+
+**Saídas:** *Pronto para QA* após merge ou review.
+
+**Responsabilidades do owner (autor do MR):**
+- Pedir review quando fizer sentido; responder comentários; manter MR pequeno.
+- Se review travar, o owner desbloqueia (pede ajuda ao TL/par — não fica parado esperando).
+
+**Quem move para próxima etapa:** o owner (após merge ou revisão).
+
+---
+
+### 5) Pronto para QA — Owner: DEV
+
+**Objetivo:** pacote pronto para validação (ambiente e instruções).
+
+**Pronto para entrar:**
+- Mudança disponível em ambiente de teste (ou release candidate preparado).
+- Passo-a-passo de validação e critérios de aceite listados.
+
+**Saídas:** *Em QA* quando DEV iniciar os testes e validação.
+
+**Responsabilidades do DEV:**
+- Garantir que existe build/ambiente e dados/seed (se necessário).
+- Garantir instruções de teste.
+- Mover para *Em QA* quando iniciar a validação.
+
+---
+
+### 6) Em QA — Owner: DEV
+
+**Objetivo:** validar e corrigir até ficar ok.
+
+**Pronto para entrar:** DEV executando testes ou validação em andamento.
+
+**Saídas:**
+- Volta para *Pronto para desenvolvimento* (se resultado negativo) — DEV adiciona flag e comentário.
+- Vai para *Pronto para produto* quando resultado positivo.
+
+**Responsabilidades do DEV:**
+- Executar testes e validação (pode contar com apoio do QA).
+- Se encontrar bugs/problemas, voltar para *Pronto para desenvolvimento* com flag e comentário claro.
+- Manter ciclo curto (fix → reteste).
+- Não jogar o card para outra pessoa só para mudar status — o owner avança.
+
+> Se QA atuar, manter Owner: DEV (accountability de entrega) e definir "Executor: QA". Isso evita o limbo "QA é o dono então dev não corre".
+
+---
+
+### 7) Pronto para produto — Owner: quem entregou (PM apoia)
+
+**Objetivo:** validação funcional/negócio.
+
+**Pronto para entrar:**
+- Validação técnica ok.
+- Evidências quando fizer sentido.
+
+**Saídas:** *Pronto para deploy* quando aprovado (pelo PM **ou** pelo owner se PM não estiver no fluxo).
+
+**Responsabilidades:**
+- PM valida comportamento quando estiver no fluxo.
+- Owner pode auto-aceitar em times pequenos / se o aceite de produto não for um papel separado.
+- Ajustes: volta para *Pronto para desenvolvimento* com flag e comentário.
+
+---
+
+### 8) Pronto para deploy — Owner: quem vai publicar
+
+**Objetivo:** deploy consciente (rollback/flag quando necessário).
+
+**Pronto para entrar:**
+- Aceite feito (PM ou owner).
+- Plano de deploy/rollback/flag quando o risco pedir.
+
+**Saídas:** *Em rollout* quando iniciar deploy.
+
+**Responsabilidades do owner:**
+- Executar ou coordenar o deploy do próprio card.
+- Pedir apoio ao TL em janela de risco — não é obrigatório.
+
+---
+
+### 9) Em rollout — Owner: quem publicou
+
+**Objetivo:** rollout em execução e monitorado.
+
+**Pronto para entrar:** deploy iniciado.
+
+**Saídas:** *Validação* quando a mudança estiver ativa e estável.
+
+**Responsabilidades do owner:**
+- Monitorar métricas/logs/alertas; rollback se necessário.
+- Comunicar status. Pedir ajuda ao TL em incidente.
+
+---
+
+### 10) Validação — Owner: quem publicou (PM/N2 apoiam)
+
+**Objetivo:** validação operacional e de suporte (pós-deploy).
+
+**Pronto para entrar:** feature ativa, checklist de validação disponível.
+
+**Saídas:** *Pronto/Cancelado* quando validado (ou encerrado).
+
+**Responsabilidades do N2:**
+- Confirmar que a feature está funcionando no "mundo real".
+- Se encontrar problema: voltar para *Pronto para desenvolvimento* com comentário objetivo do que falhou.
+- Se validação OK: mover para *Pronto/Cancelado*.
+
+---
+
+### 11) Pronto/Cancelado — Owner: quem fechou o card
+
+**Objetivo:** fechamento formal.
+
+**Pronto para entrar:**
+- Validado com sucesso **ou**
+- Cancelado com motivo registrado.
+
+**Responsabilidades:**
+- Owner, TL ou PM registram motivo de cancelamento ou evidência de entrega.
+- Qualquer um deles pode cancelar com motivo (prioridade/escopo).
+
+---
+
+## RACI
+
+| Papel | Ação no fluxo |
+|---|---|
+| **Owner (DEV, TL ou PM)** | Conduz o card ponta-a-ponta. Move todas as transições do próprio trabalho. |
+| **TECH LEAD** | Apoia. Pode mover qualquer card para destravar — não é gate. |
+| **DEV** | Entrega técnica completa, inclusive spec/PR/deploy dos cards que assumiu. |
+| **QA** | Testa e reporta. Não bloqueia o owner. |
+| **PM / TPM / GPM** | Spec, priorização e aceite. Pode assumir e conduzir um card. |
+| **N2** | Validação operacional se existir no time. |

package/rules/engineering/eng.integrations-rules.md

@@ -0,0 +1,73 @@
+---
+trigger: always_on
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: all | SQUAD: all
+
+# Integrações — vendors via ENV
+
+O Jarvis não assume Jira, GitLab ou Slack. Leia `$IDE/ENV.md` e despache pelo adapter.
+
+## Variáveis
+
+| Variável | Vendors | Adapter |
+|----------|---------|---------|
+| `TASK_MANAGER` | jira, linear, github, asana | `bin/lib/tasks/comment.js` |
+| `VERSION_CONTROL` | gitlab, github, bitbucket | `bin/lib/vcs/` |
+| `MESSAGE_COMUNICATOR` | slack, discord, teams | runtime `communicator/` |
+
+`{TASK_MANAGER_KEY}` = id da tarefa. Com board, é o id do card. Sem board, é o número de controle do usuário.
+
+## Freelance (TASK_MANAGER vazio)
+
+`TASK_MANAGER` vazio, ausente ou ainda com a lista `[jira, linear, github, asana]` = **sem board** (freelance).
+
+1. **Perguntar** o `TASK_MANAGER_KEY` se não veio em `$ARGUMENTS`. Não inventar. Não exigir padrão `XXX-000`.
+2. Prompt:
+
+```
+Não há TASK_MANAGER no ENV — modo freelance.
+Qual o seu número de controle para esta tarefa?
+(ex: F-042, CLIENTE-agosto, 2026-08-13)
+```
+
+3. Usar a resposta (lowercase) como pasta `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/` e no prefixo da branch.
+4. **Não** chamar `/eng-task-comment`, **não** mover card, **não** buscar issue no board.
+
+Com board definido, se o key não veio nos argumentos, perguntar o id do card naquele vendor (ex: Jira `TASK-123`).
+
+## Comentário no card
+
+Só se `TASK_MANAGER` estiver preenchido com um vendor. Freelance → pular.
+
+```
+/eng-task-comment {TASK_MANAGER_KEY} {mensagem}
+```
+
+## MR / PR
+
+```
+node bin/lib/vcs/create-merge.js --source BRANCH --target BRANCH --title "..." --body-file path
+```
+
+Vendor pelo hostname de `git remote get-url origin` (ou `VERSION_CONTROL`).
+
+## Alertas (runtime)
+
+`MESSAGE_COMUNICATOR=slack` → Socket Mode (três tokens).
+`discord` → Bot token + channel ID em `ALERTS_CHANNEL`.
+`teams` → Incoming Webhook em `MESSAGE_COMUNICATOR_BOT_TOKEN`.
+
+## URL do card
+
+| TASK_MANAGER | Padrão |
+|--------------|--------|
+| jira | `{TASK_MANAGER_URL_BASE}/browse/{TASK_MANAGER_KEY}` |
+| linear | `{TASK_MANAGER_URL_BASE}/issue/{TASK_MANAGER_KEY}` |
+| github | `{TASK_MANAGER_URL_BASE}/issues/{TASK_MANAGER_KEY}` |
+| asana | `{TASK_MANAGER_URL_BASE}/0/0/{TASK_MANAGER_KEY}` |
+
+## Proibido
+
+- Hardcodar `gitlab.com`, `/browse/` ou Slack Bolt fora dos adapters.
+- Pedir token no chat.

package/rules/engineering/eng.plan-rules.md

@@ -0,0 +1,333 @@
+---
+trigger: always_on
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: ENGINEERING | SQUAD: all
+
+# Regras do Workflow Plan (Planejamento de Execução)
+
+## Propósito
+
+O workflow `plan` tem como objetivo **criar um plano de execução detalhado e faseado** que permita implementar a feature de forma incremental e retomável.
+
+---
+
+## ⛔ Gate 0: Pré-requisitos Obrigatórios
+
+> Esta regra é executada **antes de qualquer ação**. Se qualquer condição falhar, o workflow para imediatamente.
+
+### Regra 0.1 — TASK_MANAGER_KEY obrigatório
+
+Ler `TASK_MANAGER` do ENV.md. Ver `eng.integrations-rules.md` (freelance vs board).
+
+Se `$ARGUMENTS` não trouxer o key: **perguntar e aguardar**. Não inventar. Não exigir `XXX-000`.
+
+- Freelance (`TASK_MANAGER` vazio): *Qual o seu número de controle para esta tarefa?*
+- Com board: *Qual o id do card no {TASK_MANAGER}?*
+
+Sem resposta → **PARAR**. Com resposta → seguir (pasta/branch em lowercase).
+
+### Regra 0.2 — Proibido executar em branch protegida
+
+Verificar branch atual:
+
+```bash
+git branch --show-current
+```
+
+Se for `main`, `master`, `develop`, `staging` ou `homolog`:
+
+```
+🚫 BLOQUEADO: Você está em uma branch protegida ({BRANCH_ATUAL}).
+
+Este workflow só pode ser executado em uma branch de feature.
+Execute /eng.start {TASK_MANAGER_KEY} primeiro para criar a branch correta.
+
+Branch esperada: {TASK_MANAGER_KEY}-{titulo-kebab-case}
+```
+
+**→ PARAR. Não executar nenhuma fase.**
+
+### Regra 0.3 — Branch deve corresponder ao TASK_MANAGER_KEY
+
+Se a branch atual **não contém** o `{TASK_MANAGER_KEY}` no nome:
+
+```
+⚠️ ATENÇÃO: A branch atual ({BRANCH_ATUAL}) não corresponde à tarefa {TASK_MANAGER_KEY}.
+
+  Branch atual:  {BRANCH_ATUAL}
+  Esperado:      branch contendo {TASK_MANAGER_KEY}
+
+Confirmar que está na branch certa? (s/n)
+```
+
+**→ Aguardar confirmação explícita antes de prosseguir.**
+
+---
+
+## ⚠️ REGRA CRÍTICA: SOMENTE PLANEJAMENTO
+
+> **Este workflow é EXCLUSIVAMENTE para criar o `plan.md`.**
+> 
+> **NÃO é permitido:**
+> - ❌ Escrever código
+> - ❌ Criar arquivos de código (.ts, .js, .py, etc.)
+> - ❌ Modificar arquivos existentes do projeto
+> - ❌ Executar comandos de build/test
+> - ❌ Fazer commits ou criar branches
+> - ❌ Iniciar implementação
+>
+> **O ÚNICO artefato permitido é o arquivo `plan.md`.**
+
+Se o usuário pedir para começar a implementação, responda:
+
+```
+⏸️ O workflow `plan` é apenas para planejamento.
+
+Para implementar o código, use o workflow `work`:
+→ eng.work {TASK_MANAGER_KEY}
+```
+
+---
+
+## Princípios Fundamentais
+
+### 1. Localização do Arquivo
+
+O arquivo `plan.md` deve ser criado em:
+
+```
+$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/plan.md
+```
+
+Onde `{TASK_MANAGER_KEY}` é o ID do card em **lowercase** (ex: `TASK-123` → `task-123`).
+
+### 2. Pré-requisito
+
+Antes de criar o `plan.md`, o arquivo `architecture.md` **DEVE existir** na mesma pasta da sessão. Se não existir, execute o workflow `start` primeiro.
+
+---
+
+## Estrutura do Plano
+
+### Fases
+
+O plano deve ser dividido em **fases incrementais**, onde cada fase:
+
+- Pode ser executada por um desenvolvedor em **1 hora** (máximo)
+- Entrega valor testável
+- Não quebra o sistema durante a implementação
+- Permite retomar o trabalho se a sessão for interrompida
+
+### Tarefas dentro das Fases
+
+Cada fase contém tarefas que:
+
+- São específicas e acionáveis
+- Possuem critério de conclusão claro
+- Indicam dependências (sequencial ou paralelo)
+- Incluem detalhes de implementação
+
+---
+
+## Status das Fases e Tarefas
+
+### Indicadores de Status
+
+| Status | Emoji | Uso |
+|--------|-------|-----|
+| Completada | ✅ | Fase/tarefa finalizada e testada |
+| Em Progresso | ⏰ | Fase/tarefa sendo executada agora |
+| Não Iniciada | ⏳ | Fase/tarefa ainda não começada |
+| Bloqueada | 🚫 | Fase/tarefa com impedimento |
+
+### Regras de Status
+
+1. **Apenas UMA fase** pode estar `Em Progresso ⏰` por vez
+2. **Apenas UMA tarefa** pode estar `Em Progresso ⏰` dentro de uma fase
+3. Marcar como `Completada ✅` somente após verificação
+4. Usar `Bloqueada 🚫` quando houver dependência externa
+
+---
+
+## Fluxo de Criação do Plano
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│  1. LER ARCHITECTURE.MD                                     │
+│        ↓                                                    │
+│  2. ANALISAR ESCOPO → Entender requisitos e restrições      │
+│        ↓                                                    │
+│  3. PESQUISAR → Buscar arquivos relevantes no código        │
+│        ↓                                                    │
+│  4. DIVIDIR EM FASES → Incrementos de ~1 hora               │
+│        ↓                                                    │
+│  5. DETALHAR TAREFAS → Específicas e acionáveis             │
+│        ↓                                                    │
+│  6. IDENTIFICAR DEPENDÊNCIAS → Sequencial vs paralelo       │
+│        ↓                                                    │
+│  7. CRIAR PLAN.MD → Usando o template                       │
+│        ↓                                                    │
+│  8. VALIDAR COM HUMANO → Confirmar antes de prosseguir      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Comportamento Esperado
+
+### Fase 1: Análise do Architecture.md
+
+1. **Ler** o arquivo `architecture.md` da sessão
+2. **Extrair**:
+   - Objetivo da feature
+   - Requisitos funcionais e não-funcionais
+   - Decisões arquiteturais
+   - Restrições técnicas
+   - Dependências externas
+
+### Fase 2: Pesquisa no Codebase
+
+1. **Identificar** arquivos existentes que serão modificados
+2. **Buscar** padrões similares já implementados
+3. **Analisar** estrutura atual do projeto
+4. **Documentar** descobertas relevantes
+
+### Fase 3: Divisão em Fases
+
+1. **Agrupar** trabalho em incrementos lógicos
+2. **Garantir** que cada fase:
+   - Seja independentemente testável
+   - Não quebre funcionalidades existentes
+   - Possa ser commitada separadamente
+3. **Ordenar** por dependências técnicas
+
+### Fase 4: Detalhamento de Tarefas
+
+Para cada tarefa, incluir:
+
+- **O que fazer**: Descrição clara da ação
+- **Onde fazer**: Arquivo(s) envolvido(s)
+- **Como fazer**: Abordagem técnica
+- **Como testar**: Verificação de conclusão
+
+### Fase 5: Validação
+
+1. **Apresentar** o plano ao humano
+2. **Discutir** ajustes necessários
+3. **Atualizar** `architecture.md` se houver mudanças arquiteturais
+
+---
+
+## Template do Plan.md
+
+O arquivo deve seguir o template em `$IDE/templates/engineering/plan-template.md`.
+
+---
+
+## Regras de Atualização
+
+### Durante a Execução (workflow `work`)
+
+1. **Atualizar status** conforme progresso
+2. **Adicionar comentários** sobre mudanças de direção
+3. **Documentar** aprendizados importantes
+4. **Registrar** bloqueios e resoluções
+
+### Seção de Comentários
+
+Cada fase pode ter uma seção `### Comentários:` para:
+
+- Mudanças de direção necessárias
+- Aprendizados durante a implementação
+- Decisões tomadas em conjunto
+- Problemas encontrados e soluções
+
+---
+
+## Regras de Qualidade
+
+### ⛔ NUNCA FAÇA
+
+- ❌ Criar `plan.md` sem ler `architecture.md`
+- ❌ Fases que levam mais de 1 hora
+- ❌ Tarefas vagas como "implementar feature"
+- ❌ Ignorar dependências entre tarefas
+- ❌ Pular a validação com o humano
+- ❌ Escrever em outro idioma que não pt-BR
+
+### ✅ SEMPRE FAÇA
+
+- ✅ Basear o plano no `architecture.md`
+- ✅ Dividir em fases de ~1 hora
+- ✅ Detalhar cada tarefa com contexto
+- ✅ Indicar dependências (sequencial/paralelo)
+- ✅ Usar os emojis de status corretamente
+- ✅ Validar o plano com o humano antes de prosseguir
+- ✅ Escrever tudo em português (pt-BR)
+
+---
+
+## Erros Comuns a Evitar
+
+### ❌ Anti-padrões
+
+1. **Fases muito grandes**
+   - ❌ "Implementar todo o backend"
+   - ✅ "Criar endpoint de autenticação"
+
+2. **Tarefas vagas**
+   - ❌ "Fazer os testes"
+   - ✅ "Criar teste unitário para validação de token em `auth.service.spec.ts`"
+
+3. **Sem ordem de execução**
+   - ❌ Lista solta de tarefas
+   - ✅ Fases numeradas com dependências claras
+
+4. **Sem critério de conclusão**
+   - ❌ "Melhorar código"
+   - ✅ "Refatorar `UserService` para usar injeção de dependência - verificar com teste unitário"
+
+---
+
+## Checklist de Conclusão
+
+Antes de considerar o plano completo:
+
+- [ ] `architecture.md` foi lido e compreendido
+- [ ] Pesquisa no codebase foi realizada
+- [ ] Plano dividido em fases de ~1 hora
+- [ ] Cada fase tem tarefas específicas
+- [ ] Tarefas indicam o que, onde e como
+- [ ] Dependências estão claras (sequencial/paralelo)
+- [ ] Status iniciais definidos (todos ⏳)
+- [ ] Conteúdo em português (pt-BR)
+- [ ] Validado com o humano
+- [ ] `plan.md` criado em `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`
+
+---
+
+## Integração com Outros Workflows
+
+### Entrada (de onde vem)
+
+```
+eng.start → architecture.md → eng.plan
+```
+
+### Saída (para onde vai)
+
+```
+eng.plan → plan.md → eng.work → código
+```
+
+### Relacionamento
+
+| Workflow | Relação |
+|----------|---------|
+| `start` | Cria o `architecture.md` que é entrada do `plan` |
+| `plan` | Cria o `plan.md` com fases de execução |
+| `work` | Executa o `plan.md` e atualiza status |
+| `pr` | Finaliza após todas as fases completadas |