trackfw 2.9.1 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.9.1",
+  "version": "2.11.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,19 +334,16 @@ 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\`
 
 ### 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
-
-### 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 serve\` — live Kanban board at http://localhost:4080
+4. **ML lifecycle — mandatory:**
+   - Starting a ML: edit roadmap \`**Status:** ⬜ Pendente\` → \`**Status:** 🔄 Em andamento\` + commit.
+   - Completing a ML: edit roadmap → \`**Status:** ✅ Concluído\` + include in ML commit.
+   - Analyzing a roadmap: move from \`backlog/\` to \`analyzing/\`; to \`wip/\` only when coding starts.
 
 ### Attention Signal (when you need user input during a task)
 Write \`docs/roadmaps/.trackfw-attention.json\`:
@@ -353,7 +351,14 @@ 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 arch + no in-memory data:** frontend / backend / database; always DB + ORM — never arrays/globals\n' +
+'- **Auth + Docker + .env from day 1:** never defer auth; containerize early; all config via env vars\n' +
+'- **2-layer validation + API-first:** frontend (UX) + backend (security); define OpenAPI contract first\n' +
+'- **Security wave + test coverage:** red-team review in every roadmap; TDD for critical; min 60%/80%\n' +
+'- Use `/trackfw:architect` to define stack before the first REQ\n' +
+RULES_END
 }
 
 /**
@@ -446,14 +451,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 +643,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 +816,85 @@ 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 **Architecture Directives** já injetadas no CLAUDE.md deste projeto: separação em 3 camadas sem dados em memória (sempre DB + ORM), auth + Docker + .env desde o dia 1, validação em 2 camadas, contrato OpenAPI antes de codar, wave de segurança em todo roadmap e 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 +988,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 **Architecture Directives** já injetadas no CLAUDE.md deste projeto: separação em 3 camadas sem dados em memória (sempre DB + ORM), auth + Docker + .env desde o dia 1, validação em 2 camadas, contrato OpenAPI antes de codar, wave de segurança em todo roadmap e 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 +1036,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 +1085,5 @@ module.exports = {
   injectRulesForTool,
   injectRulesDetected,
   trackfwRulesBlock,
+  printArchitectNextSteps,
 }