trackfw 2.9.1 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "CLI de governança para entrega de software: ADR → REQ → ROADMAP → kanban. Suporte nativo a agentes de IA (Claude Code, Gemini CLI, Cursor).",
   "keywords": [
     "cli",

package/src/commands/discover.js

@@ -61,10 +61,11 @@ function scan(rootDir) {
     for (const sub of agentDirs) {
       const wipDir = path.join(roadmapRoot, sub, 'wip');
       const backlogDir = path.join(roadmapRoot, sub, 'backlog');
+      const analyzingDir = path.join(roadmapRoot, sub, 'analyzing');
       const doneDir = path.join(roadmapRoot, sub, 'done');
       const abandonedDir = path.join(roadmapRoot, sub, 'abandoned');
       const blockedDir = path.join(roadmapRoot, sub, 'blocked');
-      if (isDir(wipDir) || isDir(backlogDir) || isDir(doneDir) || isDir(abandonedDir) || isDir(blockedDir)) {
+      if (isDir(wipDir) || isDir(backlogDir) || isDir(analyzingDir) || isDir(doneDir) || isDir(abandonedDir) || isDir(blockedDir)) {
         byAgent = true;
         agents.push(sub);
       }
@@ -73,13 +74,13 @@ function scan(rootDir) {
       r.roadmapNamespacing = 'by_agent';
       r.agents = agents;
       for (const agent of agents) {
-        for (const state of ['backlog', 'wip', 'blocked', 'done', 'abandoned']) {
+        for (const state of ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']) {
           r.roadmapCount += countMD(path.join(roadmapRoot, agent, state));
         }
       }
     } else {
       r.roadmapNamespacing = 'flat';
-      for (const state of ['backlog', 'wip', 'blocked', 'done', 'abandoned']) {
+      for (const state of ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']) {
         r.roadmapCount += countMD(path.join(roadmapRoot, state));
       }
     }
@@ -395,6 +396,10 @@ cmd.action((opts) => {
       } catch (e) {
         console.log(`⚠ agent rules inject partial: ${e.message}`);
       }
+      try {
+        const generators = require('../generators/init')
+        generators.printArchitectNextSteps(cwd)
+      } catch (e) {}
     }
   }
 

package/src/commands/init.js

@@ -21,6 +21,7 @@ cmd.action(async () => {
     }
     await generators.scaffold(cfg)
     console.log(`\n${t('init.success')}`)
+    require('../generators/init').printArchitectNextSteps(process.cwd())
     return
   }
 
@@ -160,6 +161,7 @@ cmd.action(async () => {
     }
     await generators.scaffold(cfg)
     console.log(`\n${t('init.success')}`)
+    require('../generators/init').printArchitectNextSteps(process.cwd())
     return
   }
 
@@ -178,6 +180,7 @@ cmd.action(async () => {
   }
 
   console.log(`\n${t('init.success')}`)
+  require('../generators/init').printArchitectNextSteps(process.cwd())
 })
 
 module.exports = cmd

package/src/commands/update.js

@@ -110,6 +110,7 @@ cmd.action(() => {
   }
 
   console.log('\n✓ trackfw update concluído');
+  require('../generators/init').printArchitectNextSteps(process.cwd())
 });
 
 module.exports = cmd;

package/src/generators/init.js

@@ -8,6 +8,7 @@ const GOV_DIRS = [
   'docs/adr',
   'docs/req',
   'docs/roadmaps/backlog',
+  'docs/roadmaps/analyzing',
   'docs/roadmaps/wip',
   'docs/roadmaps/blocked',
   'docs/roadmaps/done',
@@ -333,18 +334,31 @@ function trackfwRulesBlock() {
 ## trackfw — Governance Rules
 
 This project uses **trackfw** for AI-native delivery governance.
-Chain: \`ADR → REQ → ROADMAP\` · States: \`backlog / wip / blocked / done / abandoned\`
+Chain: \`ADR → REQ → ROADMAP\` · States: \`backlog / analyzing / wip / blocked / done / abandoned\`
+
+\`\`\`
+backlog     → roadmaps aguardando execução
+analyzing   → roadmap em análise/validação pré-wip
+wip         → roadmap em execução ativa (máximo 1)
+blocked     → impedido por dependência ou decisão
+done        → concluído e validado
+abandoned   → descontinuado ou superado
+\`\`\`
 
 ### Agent Protocol
 1. **Before starting:** run \`trackfw context\` · read \`docs/agents-working-context.md\`
 2. **After finishing:** update \`docs/agents-working-context.md\` with what changed
 3. **Before PR:** \`trackfw validate\` must pass
+4. **Ciclo de vida do ML — obrigatório:**
+   - Ao **iniciar** um ML: edite o roadmap alterando \`**Status:** ⬜ Pendente\` → \`**Status:** 🔄 Em andamento\` e faça commit do roadmap.
+   - Ao **concluir** um ML: edite o roadmap alterando \`**Status:** 🔄 Em andamento\` → \`**Status:** ✅ Concluído\` e inclua essa mudança no commit do ML.
+   - Ao **analisar** um roadmap antes de iniciar: mova o arquivo de \`backlog/\` para \`analyzing/\`; só mova para \`wip/\` ao começar a codificar de fato.
 
 ### Key Commands
 - \`trackfw context\` — current governance state (always run first)
 - \`trackfw status\` — all artifacts and states
 - \`trackfw validate\` — governance consistency check
-- \`trackfw roadmap move <name> <state>\` — transition roadmap state
+- \`trackfw roadmap move <name> <state>\` — transition roadmap state (\`backlog\`, \`analyzing\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`)
 - \`trackfw serve\` — live Kanban board at http://localhost:4080
 
 ### Attention Signal (when you need user input during a task)
@@ -353,7 +367,18 @@ Write \`docs/roadmaps/.trackfw-attention.json\`:
 {"roadmap":"file.md","ml":"ML-1A","message":"what you need","level":"action_required","timestamp":"ISO8601Z"}
 \`\`\`
 Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
-` + RULES_END
+` +
+'\n### Architecture Directives (mandatory)\n' +
+'- **3-layer separation:** frontend / backend / database — never mix concerns\n' +
+'- **No in-memory data:** always database + ORM (never arrays/globals for persistence)\n' +
+'- **Auth from day 1:** never defer — refactoring auth later is very costly\n' +
+'- **Docker + .env from day 1:** containerize early; all config via env vars\n' +
+'- **2-layer validation:** frontend (UX) + backend (security) — never only one\n' +
+'- **API-first:** define OpenAPI contract before coding frontend/backend integration\n' +
+'- **Security wave:** include a red-team review wave in every feature roadmap\n' +
+'- **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)\n' +
+'- Use `/trackfw:architect` to define stack before the first REQ\n' +
+RULES_END
 }
 
 /**
@@ -446,14 +471,17 @@ function generateClaudeMD(cfg) {
   content += '<!-- Describe what this project does in 2-3 sentences. -->\n\n'
 
   content += '## Governance chain\n\n'
-  content += '```\nADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned\n```\n\n'
+  content += '```\nADR → REQ → ROADMAP → backlog / analyzing / wip / blocked / done / abandoned\n```\n\n'
 
   content += '## Agent rules (mandatory)\n\n'
   content += 'These rules apply to every agent or AI assistant working in this project:\n\n'
   content += '1. **Never start coding without a REQ and a ROADMAP.** If none exists, create them first.\n'
   content += '2. **Use `/trackfw:implement <req-slug>` to start any implementation.** This skill orchestrates the full flow automatically: finds or generates the roadmap, moves it to `wip/`, executes each ML, updates the roadmap, and moves to `done/`.\n'
   content += '3. **Only one roadmap in `wip/` at a time.** Before starting a new one, complete or move to `blocked/` the current one.\n'
-  content += '4. **Update the roadmap after every ML.** Mark completed MLs as `✅ Concluído` in the roadmap file before moving to the next.\n'
+  content += '4. **Ciclo de vida do ML — obrigatório:**\n'
+  content += '   - Ao **iniciar** um ML: edite o roadmap alterando `**Status:** ⬜ Pendente` → `**Status:** 🔄 Em andamento` e faça commit do roadmap.\n'
+  content += '   - Ao **concluir** um ML: edite o roadmap alterando `**Status:** 🔄 Em andamento` → `**Status:** ✅ Concluído` e inclua essa mudança no commit do ML.\n'
+  content += '   - Ao **analisar** um roadmap antes de iniciar: mova o arquivo de `backlog/` para `analyzing/`; só mova para `wip/` ao começar a codificar de fato.\n'
   content += '5. **Run `trackfw validate` before every commit.** Zero violations required.\n'
   content += '6. **ADRs before decisions.** Any architectural or technical decision must have an ADR (`/trackfw:adr`).\n\n'
 
@@ -635,9 +663,9 @@ trackfw não está instalado. Instale com uma das opções:
 
 O formato esperado é: \`<nome-do-roadmap> <estado>\`
 
-Estados válidos: \`backlog\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`
+Estados válidos: \`backlog\`, \`analyzing\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`
 
-Exemplo: \`/trackfw:move meu-roadmap wip\`
+Exemplo: \`/trackfw:move meu-roadmap analyzing\`
 
 Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
 trackfw não está instalado. Instale com:
@@ -808,6 +836,92 @@ git commit -m "docs(trackfw): roadmap <nome> → done"
 ✅ Implementação concluída.
 Roadmap: docs/roadmaps/done/<nome>.md
 Próximo passo: abrir PR com gh pr create
+\`\`\``,
+
+    'architect.md': `Você é o guia de arquitetura do trackfw. Ajude o usuário a escolher a stack correta e arquitetar a aplicação em linguagem simples, acessível para times não técnicos.
+
+## Passo 1 — Descoberta de Negócio
+
+Faça ao usuário as seguintes perguntas em linguagem simples, uma por vez:
+
+1. "O que sua aplicação vai fazer? Descreva em 2-3 frases como se fosse explicar para alguém de fora da TI."
+2. "Quantas pessoas vão usar esse sistema simultaneamente? (< 10 pessoas / 10-100 pessoas / > 100 pessoas)"
+3. "Esse sistema vai para produção de verdade ou é um protótipo para validar uma ideia?"
+4. "Você precisa de login/autenticação de usuários? (Sim / Não / Não sei)"
+5. "Tem alguma restrição de tecnologia ou preferência da empresa? (ex: só Java, só Microsoft, etc.)"
+
+---
+
+## Passo 2 — Recomendação de Stack
+
+Com base nas respostas, escolha **UM** dos combos pré-validados:
+
+### Combo A — Protótipo Rápido
+**Quando usar:** prototipagem, validação de ideia, até ~10 usuários, sem pressão de produção.
+- **Frontend:** React + Vite
+- **Backend:** FastAPI (Python) ou Express (Node.js)
+- **Banco:** SQLite + SQLAlchemy / Prisma
+- **Auth:** JWT simples quando necessário
+- **Docker:** Dockerfile básico para o backend
+
+### Combo B — Sistema Pequeno/Médio em Produção
+**Quando usar:** sistema real, 10-100 usuários, robustez e manutenibilidade.
+- **Frontend:** Next.js (SSR + rotas prontas)
+- **Backend:** FastAPI (Python) ou NestJS (Node.js)
+- **Banco:** PostgreSQL + ORM (SQLAlchemy / Prisma / TypeORM)
+- **Auth:** OAuth2 com JWT (Supabase Auth ou Auth0)
+- **Docker:** docker-compose com frontend + backend + banco
+
+### Combo C — Enterprise / Java
+**Quando usar:** integração com sistemas corporativos, > 100 usuários, exigência de Java.
+- **Frontend:** Angular
+- **Backend:** Spring Boot
+- **Banco:** PostgreSQL + Hibernate
+- **Auth:** Spring Security + OAuth2 (Keycloak ou Azure AD)
+- **Docker:** docker-compose com todos os serviços
+
+Apresente o combo recomendado com explicação simples do motivo.
+
+---
+
+## Passo 3 — Arquitetura em Camadas (explicação simples)
+
+Explique a arquitetura com uma metáfora de negócio:
+
+"Pense na aplicação como um restaurante:
+- **Frontend** = o salão: o que o cliente vê e interage
+- **Backend** = a cozinha: onde as regras de negócio acontecem, nunca exposta diretamente
+- **Banco de dados** = a despensa: onde os dados ficam guardados, acessada só pela cozinha"
+
+Reforce as regras obrigatórias:
+- **Nunca dados em memória** (arrays, variáveis globais): sempre banco + ORM
+- **Docker + .env desde o dia 1**: facilita deploys e evita problemas de ambiente
+- **Auth desde o início**: nunca deixe para depois — refatorar auth é muito custoso
+- **Validação em 2 camadas**: frontend (UX) + backend (segurança)
+- **API-first**: defina o contrato OpenAPI antes de codar frontend e backend juntos
+- **Red team wave**: reserve 1 wave de segurança no roadmap para revisar vulnerabilidades
+- **Cobertura mínima de testes**: 60% (protótipo) / 80% (produção)
+
+---
+
+## Passo 4 — Gerar o ADR de Stack
+
+Execute \`/trackfw:adr\` com o título: \`"Stack e arquitetura em camadas — [nome do projeto]"\`
+
+O ADR deve registrar a stack escolhida (combo e componentes), motivação baseada nas respostas, alternativas descartadas e princípios de arquitetura adotados.
+
+---
+
+## Passo 5 — Próximos Passos
+
+Oriente o usuário:
+
+\`\`\`
+✅ Stack definida. Próximos passos:
+
+1. Crie a REQ da primeira feature com /trackfw:req
+2. Gere o roadmap em microlotes com /trackfw:roadmap
+3. Inicie a implementação com /trackfw:implement
 \`\`\``,
   }
 
@@ -901,7 +1015,8 @@ function generateClaudeCommandsForce(rootDir) {
     'req.md': `Execute o seguinte comando bash: \`trackfw req new "$ARGUMENTS"\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
     'validate.md': `Execute o seguinte comando bash: \`trackfw validate\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
     'status.md': `Execute o seguinte comando bash: \`trackfw status\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'move.md': `Execute o seguinte comando bash: \`trackfw roadmap move $ARGUMENTS\`\n\nO formato esperado é: \`<nome-do-roadmap> <estado>\`\nEstados válidos: \`backlog\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`\n\nSe o comando falhar, instale trackfw com:\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh`,
+    'move.md': `Execute o seguinte comando bash: \`trackfw roadmap move $ARGUMENTS\`\n\nO formato esperado é: \`<nome-do-roadmap> <estado>\`\nEstados válidos: \`backlog\`, \`analyzing\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`\n\nSe o comando falhar, instale trackfw com:\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh`,
+    'architect.md': `Você é o guia de arquitetura do trackfw. Ajude o usuário a escolher a stack correta e arquitetar a aplicação em linguagem simples, acessível para times não técnicos.\n\n## Passo 1 — Descoberta de Negócio\n\nFaça ao usuário as seguintes perguntas em linguagem simples, uma por vez:\n\n1. "O que sua aplicação vai fazer? Descreva em 2-3 frases como se fosse explicar para alguém de fora da TI."\n2. "Quantas pessoas vão usar esse sistema simultaneamente? (< 10 pessoas / 10-100 pessoas / > 100 pessoas)"\n3. "Esse sistema vai para produção de verdade ou é um protótipo para validar uma ideia?"\n4. "Você precisa de login/autenticação de usuários? (Sim / Não / Não sei)"\n5. "Tem alguma restrição de tecnologia ou preferência da empresa? (ex: só Java, só Microsoft, etc.)"\n\n---\n\n## Passo 2 — Recomendação de Stack\n\nCom base nas respostas, escolha **UM** dos combos pré-validados:\n\n### Combo A — Protótipo Rápido\n**Quando usar:** prototipagem, validação de ideia, até ~10 usuários, sem pressão de produção.\n- **Frontend:** React + Vite\n- **Backend:** FastAPI (Python) ou Express (Node.js)\n- **Banco:** SQLite + SQLAlchemy / Prisma\n- **Auth:** JWT simples quando necessário\n- **Docker:** Dockerfile básico para o backend\n\n### Combo B — Sistema Pequeno/Médio em Produção\n**Quando usar:** sistema real, 10-100 usuários, robustez e manutenibilidade.\n- **Frontend:** Next.js (SSR + rotas prontas)\n- **Backend:** FastAPI (Python) ou NestJS (Node.js)\n- **Banco:** PostgreSQL + ORM (SQLAlchemy / Prisma / TypeORM)\n- **Auth:** OAuth2 com JWT (Supabase Auth ou Auth0)\n- **Docker:** docker-compose com frontend + backend + banco\n\n### Combo C — Enterprise / Java\n**Quando usar:** integração com sistemas corporativos, > 100 usuários, exigência de Java.\n- **Frontend:** Angular\n- **Backend:** Spring Boot\n- **Banco:** PostgreSQL + Hibernate\n- **Auth:** Spring Security + OAuth2 (Keycloak ou Azure AD)\n- **Docker:** docker-compose com todos os serviços\n\nApresente o combo recomendado com explicação simples do motivo.\n\n---\n\n## Passo 3 — Arquitetura em Camadas (explicação simples)\n\nExplique a arquitetura com uma metáfora de negócio:\n\n"Pense na aplicação como um restaurante:\n- **Frontend** = o salão: o que o cliente vê e interage\n- **Backend** = a cozinha: onde as regras de negócio acontecem, nunca exposta diretamente\n- **Banco de dados** = a despensa: onde os dados ficam guardados, acessada só pela cozinha"\n\nReforce as regras obrigatórias:\n- **Nunca dados em memória** (arrays, variáveis globais): sempre banco + ORM\n- **Docker + .env desde o dia 1**: facilita deploys e evita problemas de ambiente\n- **Auth desde o início**: nunca deixe para depois — refatorar auth é muito custoso\n- **Validação em 2 camadas**: frontend (UX) + backend (segurança)\n- **API-first**: defina o contrato OpenAPI antes de codar frontend e backend juntos\n- **Red team wave**: reserve 1 wave de segurança no roadmap para revisar vulnerabilidades\n- **Cobertura mínima de testes**: 60% (protótipo) / 80% (produção)\n\n---\n\n## Passo 4 — Gerar o ADR de Stack\n\nExecute \`/trackfw:adr\` com o título: \`"Stack e arquitetura em camadas — [nome do projeto]"\`\n\nO ADR deve registrar a stack escolhida (combo e componentes), motivação baseada nas respostas, alternativas descartadas e princípios de arquitetura adotados.\n\n---\n\n## Passo 5 — Próximos Passos\n\nOriente o usuário:\n\n\`\`\`\n✅ Stack definida. Próximos passos:\n\n1. Crie a REQ da primeira feature com /trackfw:req\n2. Gere o roadmap em microlotes com /trackfw:roadmap\n3. Inicie a implementação com /trackfw:implement\n\`\`\``,
   }
 
   for (const [filename, content] of Object.entries(commands)) {
@@ -948,6 +1063,34 @@ Cadeia: **ADR → REQ → ROADMAP** · Estados: \`backlog / wip / blocked / done
   console.log(`  ✓ skill global atualizada em ${dest}`)
 }
 
+function printArchitectNextSteps(cwd) {
+  const candidates = [
+    { file: 'CLAUDE.md',                              cmd: 'claude' },
+    { file: '.cursor/rules/trackfw.mdc',              cmd: 'cursor .' },
+    { file: '.windsurfrules',                         cmd: 'windsurf .' },
+    { file: '.github/copilot-instructions.md',        cmd: 'code . (Copilot)' },
+    { file: '.amazonq/developer/guidelines.md',       cmd: 'code . (Amazon Q)' },
+    { file: 'GEMINI.md',                              cmd: 'gemini' },
+    { file: 'AGENTS.md',                              cmd: 'codex' },
+  ]
+
+  const detected = candidates.filter(t => {
+    try { return fs.existsSync(path.join(cwd, t.file)) } catch { return false }
+  })
+
+  const tools = detected.length > 0 ? detected : [{ cmd: 'claude' }]
+
+  console.log()
+  console.log('Próximo passo — inicie com o guia de arquitetura:')
+  console.log()
+  for (const t of tools) {
+    console.log(`  ${t.cmd}`)
+  }
+  console.log()
+  console.log('  Execute /trackfw:architect no chat do seu assistente de IA.')
+  console.log()
+}
+
 module.exports = {
   GOV_DIRS,
   scaffold,
@@ -969,4 +1112,5 @@ module.exports = {
   injectRulesForTool,
   injectRulesDetected,
   trackfwRulesBlock,
+  printArchitectNextSteps,
 }