jarvis-ai-framework 1.0.2 → 1.1.0

package/AGENTS.md

@@ -21,7 +21,7 @@ prompts/
 │   ├── MCPs.md                   # Integracoes MCP
 │   ├── LEGACY_PROJECTS.md        # Guia para projetos legados
 │   │
-│   ├── agents/                   # 17 ativos + 5 arquivados
+│   ├── agents/                   # 18 ativos + 5 arquivados
 │   │   ├── engineering/          # Agentes de engenharia (14 ativos: 7 main + 6 QA + 1 Data)
 │   │   │   ├── eng.agent.md
 │   │   │   ├── eng.cybersecurity.agent.md  # Cybersecurity e AppSec (SENTINEL)
@@ -33,8 +33,9 @@ prompts/
 │   │   │   ├── data/             # 1 agente de Data
 │   │   │   │   └── eng.data-engineer.agent.md
 │   │   │   └── qa/               # 6 agentes de QA
-│   │   ├── product/              # Agentes de produto (1 ativo)
-│   │   │   └── prod.pm-checker.md
+│   │   ├── product/              # Agentes de produto (2 ativos)
+│   │   │   ├── prod.pm-checker.md
+│   │   │   └── prod.discovery-interviewer.md
 │   │   └── archive/              # Agentes arquivados (uso especializado)
 │   │       ├── architecture-design/   # 2 agentes
 │   │       ├── implementation/        # 2 agentes
@@ -44,7 +45,7 @@ prompts/
 │   │   ├── engineering/          # 25 workflows de engenharia
 │   │   │   ├── data/             # 2 workflows de dados (data.new-pipeline, data.contract)
 │   │   │   └── frontend/         # 3 workflows de frontend (component, review, perf-audit)
-│   │   └── product/              # 6 workflows de produto
+│   │   └── product/              # 7 workflows de produto
 │   │
 │   ├── skills/                   # 50 skills
 │   │   ├── claude-plugin-creator/
@@ -85,7 +86,8 @@ prompts/
 │   │   ├── churn-audit/           # Análise de churn SaaS por squad com relatório narrativo via Slack
 │   │
 │   ├── templates/                # Templates de documentos
-│   │   └── engineering/          # ARD, RFC, Tech Spec
+│   │   ├── engineering/          # ARD, RFC, Tech Spec
+│   │   └── product/              # PRD, FRD, épico, issue, breakdown, discovery
 │   │
 │   ├── rules/                    # Regras especificas (filtradas por perfil no init-jarvis)
 │   │   ├── rtk-rules.md          # RTK Token Killer (opt-in: RTK_ENABLED=true)
@@ -261,7 +263,7 @@ Cada pasta pode ter seu proprio AGENTS.md com instrucoes especificas:
 ```bash
 /eng.start "feature"     # Investigacao e arquitetura (somente planejamento)
 /eng.plan "feature"      # Plano de execucao faseado (somente planejamento)
-/eng.work "feature"      # Implementacao e testes (sem commits/PR)
+/eng.work "feature"      # Implementacao e testes (commit por fase, sem push/PR)
 /eng.pre-pr              # Validacao pre-PR
 /eng.pr                  # Cria branch, commit e PR
 ```
@@ -347,7 +349,7 @@ Quando um agente atua em tema com skill correspondente, o skill e a fonte de ver
 | Fase | Comando | Restricao |
 |------|---------|-----------|
 | Planejamento | `eng.start`, `eng.plan` | Somente analise, sem codigo |
-| Implementacao | `eng.work` | Codigo e testes, sem commits |
+| Implementacao | `eng.work` | Codigo e testes, commit por fase, sem push nem PR |
 | Entrega | `eng.pr` | Branch, commit e PR |
 
 ---
@@ -378,6 +380,7 @@ Quando um agente atua em tema com skill correspondente, o skill e a fonte de ver
 
 ### Produto (Ativo)
 - `prod.pm-checker.md` - Validacao de requisitos
+- `prod.discovery-interviewer.md` - Entrevistador de discovery: investiga uma ideia sem chutar e gera um rascunho estruturado
 
 ### Arquivados
 Disponiveis em `$IDE/agents/archive/` organizados por categoria.

package/README.md

@@ -221,7 +221,9 @@ Precisa de ajuda?
 
 - **Documentacao completa (proposta e conceitos)** — [`docs/visao-geral.md`](docs/visao-geral.md)
 - **Estrutura do repo (cada pasta/arquivo)** — [`docs/estrutura/`](docs/estrutura/README.md)
+- **Lista rapida de comandos (`eng.*` e `prod.*`)** — [`docs/comandos.md`](docs/comandos.md)
 - **Produto / PM / PO (comandos e exemplos)** — [`docs/produto/`](docs/produto/README.md)
+- **Engenharia (um guia por comando `eng.*`)** — [`docs/engenharia/`](docs/engenharia/README.md)
 - **Indice de docs/** — [`docs/README.md`](docs/README.md)
 - **Instrucoes para agentes / mapa de skills** — `AGENTS.md`
 - **Issues/Feedback** — skill `report-issue`

package/agents/AGENTS.md

@@ -29,8 +29,9 @@ agents/
 │       ├── eng.qa.quality-champion-task-agent.md
 │       ├── eng.qa.cypress-specialist.md
 │       └── eng.qa.quality-strategist.md
-├── product/               # Agentes ativos de produto (1 agent)
-│   └── prod.pm-checker.md
+├── product/               # Agentes ativos de produto (2 agents)
+│   ├── prod.pm-checker.md
+│   └── prod.discovery-interviewer.md
 └── archive/              # Biblioteca de agentes arquivados (9 agents)
     ├── architecture-design/  # 2 agents
     ├── implementation/       # 2 agents
@@ -174,7 +175,7 @@ ENABLE_CDD=true
 
 ### Ativos (em uso regular)
 - `engineering/` - Agentes de engenharia (12 agents: 5 main + 6 QA + 1 Data)
-- `product/` - Agentes de produto (1 agent)
+- `product/` - Agentes de produto (2 agents)
 
 ### Arquivados (biblioteca de referência)
 - `archive/` - Agentes genéricos organizados por área funcional (11 agents)

package/agents/README.md

@@ -24,16 +24,17 @@ agents/
 │   │   └── eng.data-engineer.agent.md
 │   └── qa/                       # QA específico de engenharia (6 agents)
 ├── product/                      # 🎯 Agentes do domínio de Produto (ATIVOS)
-│   └── prod.pm-checker.md        # Product Manager checker
+│   ├── prod.pm-checker.md        # Product Manager checker
+│   └── prod.discovery-interviewer.md  # Entrevistador de discovery
 └── archive/                      # 📦 Biblioteca de agentes arquivados
     └── product/                  # Product WIP (5)
 ```
 
 **📊 Total:**
-- **16 agents ativos** (prontos para uso)
+- **17 agents ativos** (prontos para uso)
   - Engineering main: 8 (6 main + 1 data + subpasta qa)
   - QA: 6
-  - Product: 1
+  - Product: 2
 - **5 agents arquivados** (uso especializado quando necessário)
 
 ---
@@ -73,13 +74,14 @@ Agentes específicos para fluxos e regras do domínio de Engenharia.
 
 ---
 
-## 🎯 2. Produto (1 agente)
+## 🎯 2. Produto (2 agentes)
 
 **Pasta**: `product/`
 
 Agentes específicos para fluxos e validações do domínio de Produto.
 
 - `prod.pm-checker.md` - `@prod.pm-checker`
+- `prod.discovery-interviewer.md` - `@prod.discovery-interviewer`: entrevista o usuário sobre uma ideia e gera o rascunho de discovery
 
 ---
 

package/agents/product/prod.discovery-interviewer.md

@@ -0,0 +1,86 @@
+---
+name: prod.discovery-interviewer
+description: Entrevistador de produto que conduz o discovery de uma ideia: entende o problema, os requisitos iniciais e a viabilidade sem chutar, e registra tudo em um rascunho estruturado.
+tools: Read, Write, Edit, Glob, Grep, LS, Bash
+model: sonnet
+---
+
+# @prod.discovery-interviewer
+
+Entrevistador de produto do Jarvis. Conduz o `/prod.spec.discovery`: transforma uma ideia ainda crua em um rascunho estruturado, com o que se sabe, o que é hipótese e o que ainda é lacuna, e indica o próximo passo.
+
+As regras de escrita de especificação ficam em `rules/product/` (`prod.spec-rules.md`). O fluxo do comando (criação e retomada do arquivo, veredito, limites) está no workflow `workflows/product/prod.spec.discovery.md`; este arquivo define a **postura**.
+
+## Persona
+
+Você é um product manager experiente e curioso, e faz o papel de entrevistador: a qualidade do discovery depende das perguntas certas, não de preencher um formulário.
+
+- **Faz perguntas abertas** e escuta a resposta antes de formular a próxima
+- **Aprofunda respostas rasas**: "por quê?", "para quem?", "com que frequência?", "me dá um exemplo real", "o que acontece hoje?"
+- **Pede evidência** quando ouve uma afirmação sem base ("todo mundo quer") e registra se ela é dado, observação ou suposição
+- **Aponta contradições**, entre respostas ou entre o que o usuário disse e o que está no projeto, e pede que o usuário resolva
+- **Levanta o que o usuário provavelmente não considerou**: quem mais é impactado, custo de manutenção, o que acontece se der errado, a alternativa mais simples
+- **Adapta o roteiro às respostas**: não segue uma lista fixa e não repete temas já esgotados
+- Tom direto e respeitoso; não julga a ideia, testa a ideia
+
+## Objetivo
+
+Ajudar o usuário a fazer o melhor discovery possível de uma ideia, cobrindo quatro eixos:
+
+1. **Ideia**: o que é e para quem
+2. **Problema**: qual dor, que evidência existe, quem sofre, como se resolve hoje
+3. **Requisitos iniciais**: o que precisaria ser verdade, em alto nível, como hipóteses
+4. **Viabilidade**: sinal indicativo de valor, usabilidade, técnica e negócio, com riscos e dependências
+
+O resultado é um arquivo no formato do template `$PROD_TEMPLATES/prod-discovery-template.md` (`templates/product/prod-discovery-template.md`), terminando com um veredito (`proceed`, `investigate_more` ou `do_not_proceed`) e um próximo passo sugerido.
+
+## Quando Usar
+
+- O usuário tem uma ideia e ainda não sabe se o problema é real, quais são os requisitos ou se é viável
+- O usuário roda `/prod.spec.discovery`, com uma ideia ou apontando um discovery existente para retomar
+- O `/prod.spec` identifica que só existe uma ideia inicial
+
+Não use quando já existe uma spec (use `/prod.spec.clarify`) ou quando o escopo já está claro e o usuário quer documentá-lo (use `/prod.spec.prd`, `/prod.spec.frd` ou `/prod.spec.issue`).
+
+## Entrada
+
+- A ideia em texto livre (`$ARGUMENTS`), ou o caminho ou nome de um discovery existente para retomar
+- O contexto do projeto: `ENV.md`, documentos em `$PROD_DOCS` e o código, lidos antes de perguntar
+
+## Saída
+
+- O arquivo `$PROD_DOCS/discoveries/discovery-{id}-{nome}.md`, preenchido pelo template e atualizado a cada tema
+- Uma seção de **Próximo passo sugerido**, sempre presente e sempre só uma sugestão
+
+## Como conduzir a entrevista
+
+1. **Comece explicando** em poucas linhas que vai entrevistar, quais temas cobrirá (ideia, problema, requisitos, viabilidade) e que o usuário pode responder "não sei" a qualquer momento
+2. **Consulte o projeto antes de perguntar**: documentos existentes (para não duplicar um PRD) e o código (para embasar a viabilidade)
+3. **Uma pergunta por vez.** Use o `AskUserQuestion` quando estiver disponível; caso contrário, o formato de tabela do `prod-rules.md`. Espere a resposta antes de seguir
+4. **Se o usuário não responde ou diz "não sei"**, não repita a pergunta: registre "não informado" e siga
+5. **Ao cobrir um tema**, resuma em poucas linhas o que entendeu e peça confirmação antes de passar ao próximo
+6. **Priorize as perguntas de maior impacto** na decisão de seguir ou não, em vez de esgotar todas as possíveis
+7. **Quando achar que já tem informação suficiente**, proponha encerrar e pergunte se o usuário quer acrescentar algo antes de fechar o documento
+
+## Não chute (regra inviolável)
+
+- Quando você não tem uma informação (público, volume, custo, prazo, restrição técnica, comportamento de usuários, estado atual do código), **não presuma nem complete com "o que costuma ser"**: pergunte, busque no projeto ou registre como lacuna
+- Todo fato citado indica a origem: resposta do usuário, arquivo do projeto ou documentação consultada. O que não tem origem entra no documento como **suposição a validar**
+- Se o usuário pedir "preencha o que faltar" ou "assuma o padrão", registre o item como **suposição explícita**, nunca como fato, e não a use para sustentar o veredito
+- Uma **lacuna crítica nunca** resulta em `proceed`: o veredito é `investigate_more`
+- Quando a viabilidade técnica depende de bibliotecas, APIs ou serviços, consulte a documentação atual (por exemplo via Context7) em vez de responder de memória
+
+## Apoio de skills (apoio, nunca a fonte da decisão)
+
+- **Sempre:** busca em `$PROD_DOCS`; `docs-central` quando `CENTRAL_DOCS_REPO` estiver configurado; `context-detect` para calibrar a profundidade da entrevista
+- **Só com a confirmação do usuário:** `eng-arch-c4` (arquitetura atual) e `eng-cybersecurity` (quando a ideia envolve autenticação, dados pessoais ou fluxo financeiro). São skills de engenharia: pergunte antes de consultá-las, e o que retornarem entra no discovery como **suposição a validar**, não como fato
+
+## Restrições
+
+- **O discovery é um rascunho.** Você **não** gera PRD, FRD, épico, issue, tarefas, histórias, critérios de aceitação nem estimativas (horas ou pontos). Se o usuário pedir, explique que é outra etapa e indique o comando certo
+- **Não escreve código** e não implementa nada
+- **Não grava credenciais, tokens nem dados pessoais de clientes** no arquivo: o discovery é versionado
+- **Não entrevista terceiros**: a entrevista é sempre com o usuário que executou o comando
+- **Não executa o próximo passo**: só sugere. O usuário pode escolher outro caminho ou parar ali
+- Um rascunho de abordagem técnica pode aparecer na viabilidade, sempre como hipótese a validar; a decisão de arquitetura pertence ao fluxo de engenharia
+- Siga as regras de `$PROD_RULES` (`prod-rules.md`): validação do `ENV.md`, idioma (pt-BR por padrão, ou o idioma da interação do usuário) e confirmação antes de salvar arquivos

package/bin/commands/init.js

@@ -169,7 +169,7 @@ export async function init(flags) {
     `${BOLD}${CYAN}  versão: ${pkg.name} v${pkg.version}${NC}`,
   );
   logger.info(`${DIM}  origem: ${pkg.root}${NC}`);
-  logger.info(`${DIM}Pasta criada: ${ideDir}${NC}`);
+  logger.info(`${DIM}  pasta criada: ${ideDir}${NC}`);
   logger.info("");
 
   const all = discoverAll();

package/bin/lib/config/constants.js

@@ -22,6 +22,18 @@ export const SYNC_DIRS = Object.freeze([
   "scripts",
 ]);
 
+/**
+ * Caminhos que saíram do framework e são removidos das instalações que atualizam.
+ * Lista explícita, relativa à pasta da IDE (ex.: `.claude/`): o `init` nunca varre
+ * nem apaga nada fora dela. Para uma remoção futura, acrescente o caminho aqui.
+ * @constant {ReadonlyArray<string>}
+ */
+export const OBSOLETE_PATHS = Object.freeze([
+  "skills/prod-specs/references",
+  "skills/prod-specs/templates",
+  "skills/prod-specs/rules",
+]);
+
 /**
  * Arquivos da raiz que devem ser sincronizados
  * @constant {ReadonlyArray<string>}

package/bin/lib/core/sync-engine.js

@@ -15,6 +15,7 @@ import { getIDEFolder } from "../config/ide-config.js";
 import {
   SYNC_DIRS,
   SYNC_ROOT_FILES,
+  OBSOLETE_PATHS,
   LOCK_FILE,
   OPENCODE_MODEL_MAP,
   OPENCODE_DEFAULT_PERMISSIONS,
@@ -134,6 +135,17 @@ export function syncAssets(targetDir, ide, opts = {}) {
     } catch {}
   }
 
+  // Cleanup de caminhos que saíram do framework (lista explícita em OBSOLETE_PATHS)
+  for (const obsolete of OBSOLETE_PATHS) {
+    const obsoletePath = join(ideDir, obsolete);
+    if (existsSync(obsoletePath) && !opts.dryRun) {
+      try {
+        rmSync(obsoletePath, { recursive: true, force: true });
+        result.copied.push(`(cleanup) .${getIDEFolder(ide)}/${obsolete} removed`);
+      } catch {}
+    }
+  }
+
   if (!opts.dryRun) {
     writeLockFile(targetDir, ideDir, ide, frameworkRoot);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ai-framework",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Jarvis framework",
   "type": "module",
   "bin": {
@@ -10,9 +10,7 @@
     "postinstall": "node bin/postinstall.js",
     "prepublishOnly": "echo 'Publishing jarvis-framework...'",
     "publish:gitlab": "npm publish",
-    "test": "node test/e2e-docs-central.js",
-    "test:utils": "node test/test-phase1-utils.js",
-    "test:all": "npm run test:utils && npm run test"
+    "test:comandos": "node test/test-comandos-docs.js"
   },
   "files": [
     "bin/",

package/rules/AGENTS.md

@@ -147,7 +147,7 @@ Links para documentacao relacionada.
 | Fase | Comandos | Restricao |
 |------|----------|-----------|
 | Planejamento | `eng.start`, `eng.plan` | Somente analise, SEM codigo |
-| Implementacao | `eng.work` | Codigo e testes, SEM commits |
+| Implementacao | `eng.work` | Codigo e testes, commit por fase, SEM push nem PR |
 | Entrega | `eng.pr` | Branch, commit e PR |
 
 ### Seguranca

package/rules/engineering/eng.breakdown-subtasks-rules.md

@@ -373,35 +373,32 @@ Ao gerar subtarefas com escopo de QA/testes, aplique a seguinte divisão **obrig
 
 ---
 
-## Formato de Saída: JSON
+## Formato de Saída: Markdown
 
 ### Estrutura Obrigatória
 
-```json
-{
-  "subtasks": [
-    {
-      "summary": "[STACK] Título específico da subtarefa",
-      "description": "Template completo com:\n\n## 🎯 O Que Você Vai Fazer\n\n... (resto conforme template acima)"
-    },
-    {
-      "summary": "[STACK] Próxima subtarefa",
-      "description": "..."
-    }
-  ]
-}
+Uma seção por subtarefa, em Markdown puro, na ordem de implementação:
+
+```markdown
+# Subtarefa N: [STACK] Título específico da subtarefa
+
+**Depende de:** Subtarefa X (ou "nenhuma")
+**Desbloqueia:** Subtarefa Y (ou "nenhuma")
+**Paralela com:** Subtarefa Z (ou "nenhuma")
+
+{Description ULTRA DETALHADA seguindo o template da seção "Estrutura de Subtarefa"}
+
+---
 ```
 
-### Regras CRÍTICAS para o JSON
+### Regras CRÍTICAS de formatação
 
-1. **APENAS JSON** - Sem texto antes ou depois
-2. **Use `\n` para quebras de linha** dentro das strings
-3. **Escape aspas com `\"`** dentro das strings
-4. **Todos os títulos com [STACK]** - Obrigatório
-5. **Description ULTRA DETALHADA** - Siga o template COMPLETAMENTE
-6. **Código COMPLETO** - Não use "..." ou placeholder
-7. **Caminhos reais** - Use paths que existem no projeto
-8. **Valide JSON** - Antes de retornar
+1. **Markdown nativo** - sem JSON, sem strings escapadas, sem `\n`
+2. **Todos os títulos com [STACK]** - Obrigatório
+3. **Description ULTRA DETALHADA** - Siga o template COMPLETAMENTE
+4. **Código COMPLETO** - Não use "..." ou placeholder
+5. **Caminhos reais** - Use paths que existem no projeto
+6. **Numeração sequencial** - Subtarefa 1, Subtarefa 2, etc.
 
 ---
 
@@ -434,7 +431,7 @@ Cada subtarefa deve ter seção "🔗 Dependências" indicando:
 
 ## Checklist de Qualidade Final
 
-Antes de retornar o JSON, valide CADA subtarefa:
+Antes de retornar, valide CADA subtarefa:
 
 ### ✅ Completude
 
@@ -479,7 +476,7 @@ Antes de retornar o JSON, valide CADA subtarefa:
 
 ### ✅ Validação
 
-- [ ] JSON é válido
+- [ ] Saída em Markdown válido, uma seção por subtarefa
 - [ ] Nenhuma subtarefa vaga
 - [ ] Toda subtarefa tem ≥ 4h e ≤ 1 dia de trabalho
 - [ ] Nenhuma fatia horizontal (split por camada)
@@ -500,7 +497,7 @@ eng.build-tech-spec → tech-spec.md → eng.breakdown-subtasks
 ### Saída (para onde vai)
 
 ```
-eng.breakdown-subtasks → subtasks JSON → Jira
+eng.breakdown-subtasks → subtarefas em Markdown → board
 ```
 
 ### Relação com Outros Workflows
@@ -550,12 +547,17 @@ eng.breakdown-subtasks → subtasks JSON → Jira
 
 ### ❌ MAL FEITA
 
-```json
-{
-  "summary": "[BACKEND] Criar autenticação",
-  "description": "Implementar o sistema de autenticação com JWT.\n\nFaça: Login, registro e validação.\n\nUse bcrypt para senha e JWT para token.\n\nRetorne o usuário no login."
-}
-```
+````markdown
+# Subtarefa 1: [BACKEND] Criar autenticação
+
+Implementar o sistema de autenticação com JWT.
+
+Faça: Login, registro e validação.
+
+Use bcrypt para senha e JWT para token.
+
+Retorne o usuário no login.
+````
 
 **Problemas:**
 
@@ -567,12 +569,181 @@ eng.breakdown-subtasks → subtasks JSON → Jira
 
 ### ✅ BEM FEITA
 
-````json
-{
-  "summary": "[BACKEND] Criar endpoint POST /api/auth/register com validação",
-  "description": "## 🎯 O Que Você Vai Fazer\n\nCriar o endpoint de registro que recebe email/senha, valida dados, cria usuário no banco e retorna JWT.\n\n---\n\n## 📋 Contexto\n\n### Por que?\nSistema precisa permitir novos usuários se cadastrem.\n\n### Pré-requisitos\n- [ ] Migration de usuários ([DATA] Criar migration tabela users)\n\n---\n\n## 🛠️ Stack\n\n| Tech | Versão | Para |\n|------|--------|------|\n| Express | 4.18+ | Framework HTTP |\n| bcrypt | 5.1+ | Hash de senha |\n| JWT | 9.0+ | Tokens |\n\n---\n\n## 📁 Arquivos\n\n| Arquivo | Ação | Descrição |\n|---------|------|--------|\n| `src/controllers/auth.controller.ts` | 🆕 | Controlador |\n| `src/services/auth.service.ts` | 🆕 | Lógica de negócio |\n| `src/routes/auth.ts` | 🆕 | Rotas |\n| `src/__tests__/auth.spec.ts` | 🆕 | Testes |\n\n---\n\n## 👣 Passos\n\n### Passo 1: Criar schema de validação\n\n```typescript\n// src/schemas/auth.schema.ts\nimport { body } from 'express-validator';\n\nexport const registerSchema = [\n  body('email')\n    .isEmail()\n    .withMessage('Email inválido')\n    .normalizeEmail(),\n  body('password')\n    .isLength({ min: 8 })\n    .withMessage('Mínimo 8 caracteres')\n    .matches(/[A-Z]/)\n    .withMessage('Precisa letra maiúscula'),\n];\n```\n\n**Explicação:**\n- `isEmail()`: Valida formato\n- `normalizeEmail()`: Padroniza\n- `matches(/[A-Z]/)`: Regex para maiúscula\n\n---\n\n### Passo 2: Criar AuthService\n\n```typescript\n// src/services/auth.service.ts\nimport bcrypt from 'bcrypt';\nimport jwt from 'jsonwebtoken';\n\nexport class AuthService {\n  async register(email: string, password: string) {\n    // Hash da senha\n    const hash = await bcrypt.hash(password, 10);\n    \n    // Criar usuário (assumindo repo existe)\n    const user = await this.userRepo.create({\n      email,\n      passwordHash: hash,\n    });\n    \n    // Gerar token\n    const token = jwt.sign(\n      { userId: user.id },\n      process.env.JWT_SECRET!,\n      { expiresIn: '24h' }\n    );\n    \n    return { user, token };\n  }\n}\n```\n\n**Explicação:**\n- `bcrypt.hash(password, 10)`: 10 salt rounds é seguro\n- `jwt.sign()`: Cria token que expira em 24h\n- Não retornamos passwordHash no response\n\n---\n\n## 🧪 Testes\n\n```typescript\n// src/__tests__/auth.spec.ts\nimport request from 'supertest';\nimport { app } from '../app';\n\ndescribe('POST /api/auth/register', () => {\n  it('deve registrar com email e senha válidos', async () => {\n    const response = await request(app)\n      .post('/api/auth/register')\n      .send({\n        email: 'test@example.com',\n        password: 'Senha123!',\n      });\n    \n    expect(response.status).toBe(201);\n    expect(response.body).toHaveProperty('token');\n  });\n  \n  it('deve retornar 400 para email inválido', async () => {\n    const response = await request(app)\n      .post('/api/auth/register')\n      .send({\n        email: 'invalid',\n        password: 'Senha123!',\n      });\n    \n    expect(response.status).toBe(400);\n  });\n});\n```\n\n### Cenários\n\n| Cenário | Input | Output |\n|---------|-------|--------|\n| Válido | email + senha válidos | 201 + token |\n| Email inválido | email sem @ | 400 VALIDATION_ERROR |\n| Senha fraca | < 8 chars | 400 VALIDATION_ERROR |\n\n---\n\n## ✅ Checklist\n\n- [ ] Schema criado\n- [ ] AuthService implementado\n- [ ] AuthController implementado\n- [ ] Rotas configuradas\n- [ ] Testes passando\n- [ ] Linter clean\n- [ ] Build ok\n\n---\n\n## ⚠️ Riscos\n\n| Risco | Como Evitar |\n|-------|-------------|\n| JWT_SECRET exposto | Usar .env, nunca commitar |\n| Senha em log | Não logar req.body |\n\n---\n\n## 🔗 Dependências\n\n**Depende de:** [DATA] Criar migration tabela users\n**Desbloqueia:** [FRONTEND] Criar tela de registro\n**Paralela com:** [INFRA] Configurar variáveis JWT\n"
+`````markdown
+# Subtarefa 1: [BACKEND] Criar endpoint POST /api/auth/register com validação
+
+## 🎯 O Que Você Vai Fazer
+
+Criar o endpoint de registro que recebe email/senha, valida dados, cria usuário no banco e retorna JWT.
+
+---
+
+## 📋 Contexto
+
+### Por que?
+Sistema precisa permitir novos usuários se cadastrem.
+
+### Pré-requisitos
+- [ ] Migration de usuários ([DATA] Criar migration tabela users)
+
+---
+
+## 🛠️ Stack
+
+| Tech | Versão | Para |
+|------|--------|------|
+| Express | 4.18+ | Framework HTTP |
+| bcrypt | 5.1+ | Hash de senha |
+| JWT | 9.0+ | Tokens |
+
+---
+
+## 📁 Arquivos
+
+| Arquivo | Ação | Descrição |
+|---------|------|--------|
+| `src/controllers/auth.controller.ts` | 🆕 | Controlador |
+| `src/services/auth.service.ts` | 🆕 | Lógica de negócio |
+| `src/routes/auth.ts` | 🆕 | Rotas |
+| `src/__tests__/auth.spec.ts` | 🆕 | Testes |
+
+---
+
+## 👣 Passos
+
+### Passo 1: Criar schema de validação
+
+```typescript
+// src/schemas/auth.schema.ts
+import { body } from 'express-validator';
+
+export const registerSchema = [
+  body('email')
+    .isEmail()
+    .withMessage('Email inválido')
+    .normalizeEmail(),
+  body('password')
+    .isLength({ min: 8 })
+    .withMessage('Mínimo 8 caracteres')
+    .matches(/[A-Z]/)
+    .withMessage('Precisa letra maiúscula'),
+];
+```
+
+**Explicação:**
+- `isEmail()`: Valida formato
+- `normalizeEmail()`: Padroniza
+- `matches(/[A-Z]/)`: Regex para maiúscula
+
+---
+
+### Passo 2: Criar AuthService
+
+```typescript
+// src/services/auth.service.ts
+import bcrypt from 'bcrypt';
+import jwt from 'jsonwebtoken';
+
+export class AuthService {
+  async register(email: string, password: string) {
+    // Hash da senha
+    const hash = await bcrypt.hash(password, 10);
+    
+    // Criar usuário (assumindo repo existe)
+    const user = await this.userRepo.create({
+      email,
+      passwordHash: hash,
+    });
+    
+    // Gerar token
+    const token = jwt.sign(
+      { userId: user.id },
+      process.env.JWT_SECRET!,
+      { expiresIn: '24h' }
+    );
+    
+    return { user, token };
+  }
 }
-````
+```
+
+**Explicação:**
+- `bcrypt.hash(password, 10)`: 10 salt rounds é seguro
+- `jwt.sign()`: Cria token que expira em 24h
+- Não retornamos passwordHash no response
+
+---
+
+## 🧪 Testes
+
+```typescript
+// src/__tests__/auth.spec.ts
+import request from 'supertest';
+import { app } from '../app';
+
+describe('POST /api/auth/register', () => {
+  it('deve registrar com email e senha válidos', async () => {
+    const response = await request(app)
+      .post('/api/auth/register')
+      .send({
+        email: 'test@example.com',
+        password: 'Senha123!',
+      });
+    
+    expect(response.status).toBe(201);
+    expect(response.body).toHaveProperty('token');
+  });
+  
+  it('deve retornar 400 para email inválido', async () => {
+    const response = await request(app)
+      .post('/api/auth/register')
+      .send({
+        email: 'invalid',
+        password: 'Senha123!',
+      });
+    
+    expect(response.status).toBe(400);
+  });
+});
+```
+
+### Cenários
+
+| Cenário | Input | Output |
+|---------|-------|--------|
+| Válido | email + senha válidos | 201 + token |
+| Email inválido | email sem @ | 400 VALIDATION_ERROR |
+| Senha fraca | < 8 chars | 400 VALIDATION_ERROR |
+
+---
+
+## ✅ Checklist
+
+- [ ] Schema criado
+- [ ] AuthService implementado
+- [ ] AuthController implementado
+- [ ] Rotas configuradas
+- [ ] Testes passando
+- [ ] Linter clean
+- [ ] Build ok
+
+---
+
+## ⚠️ Riscos
+
+| Risco | Como Evitar |
+|-------|-------------|
+| JWT_SECRET exposto | Usar .env, nunca commitar |
+| Senha em log | Não logar req.body |
+
+---
+
+## 🔗 Dependências
+
+**Depende de:** [DATA] Criar migration tabela users
+**Desbloqueia:** [FRONTEND] Criar tela de registro
+**Paralela com:** [INFRA] Configurar variáveis JWT
+`````
 
 **Diferenças:**
 

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

@@ -18,19 +18,19 @@ O workflow `start` tem como **único objetivo** criar o documento de arquitetura
 
 O `start` é **estritamente proibido** de:
 
-| ❌ Proibido                          | ✅ Permitido                              |
-| ------------------------------------ | ----------------------------------------- |
-| Criar arquivos de código (.ts, .js)  | Criar `architecture.md`                   |
-| Modificar código existente           | Ler código para análise                   |
-| Executar comandos no terminal        | Listar arquivos e estruturas              |
-| Instalar dependências                | Buscar padrões no codebase                |
-| Fazer commits                        | Criar diretório da sessão                 |
-| Executar testes                      | Documentar decisões                       |
-| Iniciar servidores                   | Dialogar com usuário                      |
+| ❌ Proibido                          | ✅ Permitido                                                |
+| ------------------------------------ | ----------------------------------------------------------- |
+| Criar arquivos de código (.ts, .js)  | Criar `architecture.md`                                     |
+| Modificar código existente           | Ler código para análise                                     |
+| Instalar dependências                | Comandos de leitura (`git`, `ls`, `grep`) para investigar   |
+| Fazer commits                        | Criar a branch de feature (Fase 1.1 do workflow)            |
+| Executar testes                      | Criar o diretório da sessão e `context.md`                  |
+| Iniciar servidores                   | Registrar `.timestamp_start` na sessão                      |
+| Alterar arquivos do projeto          | Documentar decisões e dialogar com usuário                  |
 
 ### 2. Artefato Único
 
-O **único artefato** produzido pelo `start` é:
+O **único entregável** do `start` é:
 
 ```
 $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md
@@ -38,7 +38,7 @@ $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md
 
 > 📁 **Padrão**: `TASK_MANAGER_KEY` é o ID do card em **lowercase** (ex: `TASK-123` → `task-123`)
 
-Nenhum outro arquivo deve ser criado, modificado ou deletado.
+Além dele, o `start` pode criar apenas os arquivos de apoio da própria sessão (`context.md` e `.timestamp_start`, em `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`) e a branch de feature. Nenhum arquivo do projeto deve ser criado, modificado ou deletado.
 
 ### 3. Aprovação Obrigatória