trackfw 1.0.3 → 1.1.0

package/src/generators/init.js

@@ -0,0 +1,702 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const GOV_DIRS = [
+  'docs/adr',
+  'docs/req',
+  'docs/roadmaps/backlog',
+  'docs/roadmaps/wip',
+  'docs/roadmaps/blocked',
+  'docs/roadmaps/done',
+  'docs/roadmaps/abandoned',
+]
+
+/**
+ * scaffold(cfg) — cria diretórios de governança e gera arquivos de configuração.
+ * cfg = { projectName, projectType, frontend, backend, pkgManager, hooks, ci }
+ */
+async function scaffold(cfg) {
+  for (const dir of GOV_DIRS) {
+    fs.mkdirSync(dir, { recursive: true })
+    console.log(`  ✓ ${dir}`)
+  }
+
+  writeTrackfwConfig(cfg)
+  generateValidateScript(cfg)
+  generateCIWorkflow(cfg)
+  generateGitHooks(cfg)
+  generateClaudeMD(cfg)
+  if (cfg.backend === 'java') generatePomXml(cfg)
+  generateClaudeCommands()
+}
+
+// ---------------------------------------------------------------------------
+// trackfw.yaml
+// ---------------------------------------------------------------------------
+
+function writeTrackfwConfig(cfg) {
+  const today = new Date().toISOString().slice(0, 10)
+  const content = `# trackfw configuration
+# generated: ${today}
+
+frontend: ${cfg.frontend || ''}
+backend: ${cfg.backend || ''}
+backend_framework: ${cfg.backendFramework || ''}
+pkg_manager: ${cfg.pkgManager || ''}
+hooks: ${cfg.hooks || ''}
+ci: ${cfg.ci || ''}
+`
+  fs.writeFileSync('trackfw.yaml', content, 'utf8')
+  console.log('  ✓ trackfw.yaml')
+}
+
+// ---------------------------------------------------------------------------
+// scripts/trackfw-validate.sh
+// ---------------------------------------------------------------------------
+
+function generateValidateScript(cfg) {
+  fs.mkdirSync('scripts', { recursive: true })
+
+  const script = buildValidateScript(cfg)
+  const scriptPath = path.join('scripts', 'trackfw-validate.sh')
+  fs.writeFileSync(scriptPath, script, { encoding: 'utf8', mode: 0o755 })
+  console.log(`  ✓ ${scriptPath}`)
+}
+
+function buildValidateScript(cfg) {
+  let base = `#!/usr/bin/env sh
+# trackfw governance gate — generated by trackfw init
+set -e
+
+echo "→ trackfw: validating governance..."
+trackfw validate
+
+`
+
+  switch (cfg.backend) {
+    case 'go':
+      base += 'echo "→ build check (go)..."\ngo build ./...\n'
+      break
+    case 'java':
+      base += 'echo "→ build check (maven)..."\nmvn compile -q\n'
+      break
+    case 'node': {
+      const pm = cfg.pkgManager || 'npm'
+      base += `echo "→ build check (node)..."\n${pm} run build\n`
+      break
+    }
+    case 'python':
+      base += "echo \"→ build check (python)...\"\npython -m py_compile $(find . -name '*.py' -not -path './.venv/*' -not -path './venv/*')\n"
+      break
+  }
+
+  if (['react', 'vue', 'angular'].includes(cfg.frontend)) {
+    const pm = cfg.pkgManager && cfg.pkgManager !== 'none' ? cfg.pkgManager : 'npm'
+    base += `echo "→ frontend build check..."\n${pm} run build\n`
+  }
+
+  base += '\necho "✓ all checks passed."\n'
+  return base
+}
+
+// ---------------------------------------------------------------------------
+// CI workflows
+// ---------------------------------------------------------------------------
+
+function generateCIWorkflow(cfg) {
+  switch (cfg.ci) {
+    case 'github-actions':
+      generateGitHubActionsWorkflow()
+      break
+    case 'gitlab-ci':
+      generateGitLabCIWorkflow()
+      break
+  }
+}
+
+function generateGitHubActionsWorkflow() {
+  fs.mkdirSync('.github/workflows', { recursive: true })
+
+  const content = `name: trackfw-gate
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install trackfw
+        run: |
+          curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+
+      - name: Governance gate
+        run: trackfw validate
+`
+
+  const filePath = '.github/workflows/trackfw-gate.yml'
+  fs.writeFileSync(filePath, content, 'utf8')
+  console.log(`  ✓ ${filePath}`)
+}
+
+function generateGitLabCIWorkflow() {
+  const content = `# trackfw governance gate
+trackfw-gate:
+  stage: test
+  image: alpine:latest
+  before_script:
+    - apk add --no-cache curl
+    - curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+  script:
+    - trackfw validate
+  only:
+    - merge_requests
+`
+
+  fs.writeFileSync('.gitlab-ci-trackfw.yml', content, 'utf8')
+  console.log('  ✓ .gitlab-ci-trackfw.yml')
+}
+
+// ---------------------------------------------------------------------------
+// Git hooks
+// ---------------------------------------------------------------------------
+
+function generateGitHooks(cfg) {
+  switch (cfg.hooks) {
+    case 'husky':
+      generateHuskyHook()
+      break
+    case 'lefthook':
+      generateLefthookHook()
+      break
+  }
+}
+
+function generateHuskyHook() {
+  fs.mkdirSync('.husky', { recursive: true })
+  const content = '#!/usr/bin/env sh\n. "$(dirname -- "$0")/_/husky.sh"\n\ntrackfw validate\n'
+  const filePath = '.husky/pre-commit'
+  fs.writeFileSync(filePath, content, { encoding: 'utf8', mode: 0o755 })
+  console.log(`  ✓ ${filePath}`)
+}
+
+function generateLefthookHook() {
+  const content = `pre-commit:
+  commands:
+    trackfw-validate:
+      run: trackfw validate
+`
+  fs.writeFileSync('lefthook.yml', content, 'utf8')
+  console.log('  ✓ lefthook.yml')
+}
+
+// ---------------------------------------------------------------------------
+// pom.xml (Java / Spring Boot)
+// ---------------------------------------------------------------------------
+
+function generatePomXml(cfg) {
+  const slug = cfg.projectName
+    ? cfg.projectName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')
+    : 'my-app'
+  const name = cfg.projectName || 'My App'
+  const content = `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>3.3.0</version>
+    <relativePath/>
+  </parent>
+  <groupId>com.example</groupId>
+  <artifactId>${slug}</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+  <name>${name}</name>
+  <description>${name} — generated by trackfw</description>
+  <properties>
+    <java.version>21</java.version>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-actuator</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+`
+  fs.writeFileSync('pom.xml', content, 'utf8')
+  console.log('  ✓ pom.xml')
+}
+
+// ---------------------------------------------------------------------------
+// CLAUDE.md
+// ---------------------------------------------------------------------------
+
+function generateClaudeMD(cfg) {
+  const today = new Date().toISOString().slice(0, 10)
+  const projectName = cfg.projectName || 'my-project'
+
+  let content = `# ${projectName} — Claude Code Instructions\n\n`
+  content += `> Generated by trackfw on ${today}. Update this file as the project evolves.\n\n`
+
+  content += '## Project overview\n\n'
+  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 += '## 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 += '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'
+
+  content += '## Slash commands (Claude Code)\n\n'
+  content += '| Command | When to use |\n'
+  content += '|---|---|\n'
+  content += '| `/trackfw:implement <req>` | **Start here** — orchestrates full implementation flow |\n'
+  content += '| `/trackfw:adr <title>` | Before any architectural decision |\n'
+  content += '| `/trackfw:req <title>` | Before any implementation work |\n'
+  content += '| `/trackfw:roadmap <req>` | Generate AI roadmap from a REQ |\n'
+  content += '| `/trackfw:move <name> <state>` | Move roadmap between states manually |\n'
+  content += '| `/trackfw:validate` | Run governance validation |\n'
+  content += '| `/trackfw:status` | Check what is in flight |\n\n'
+
+  content += '## CLI commands (terminal / CI)\n\n'
+  content += '| Command | When to use |\n'
+  content += '|---|---|\n'
+  content += '| `trackfw adr new "title"` | Create ADR |\n'
+  content += '| `trackfw req new "title"` | Create REQ |\n'
+  content += '| `trackfw roadmap new` | Create empty roadmap linked to a REQ |\n'
+  content += '| `trackfw roadmap move <name> <state>` | Move roadmap state |\n'
+  content += '| `trackfw validate` | Governance validation gate |\n'
+  content += '| `trackfw status` | Show governance status |\n\n'
+
+  // Frontend section
+  if (cfg.frontend && cfg.frontend !== 'none' && cfg.frontend !== '') {
+    const pm = (cfg.pkgManager && cfg.pkgManager !== 'none') ? cfg.pkgManager : 'npm'
+    content += '## Frontend\n\n'
+    content += `Stack: ${cfg.frontend}\n`
+    content += `Package manager: ${pm}\n\n`
+    content += 'Build commands:\n'
+    content += `  ${pm} run build     # build\n`
+    content += `  ${pm} run dev       # dev server\n`
+    content += `  ${pm} run test      # tests\n\n`
+    content += 'Rules:\n'
+    content += `- Build must pass (\`${pm} run build\`) before marking any ML as done\n`
+    content += '- Run `trackfw validate` before committing frontend changes\n\n'
+  }
+
+  // Backend section
+  if (cfg.backend && cfg.backend !== 'none' && cfg.backend !== '') {
+    const [buildCmd, testCmd, lintCmd] = backendCommands(cfg)
+    content += '## Backend\n\n'
+    content += `Stack: ${cfg.backend}\n\n`
+    content += 'Build commands:\n'
+    content += `  ${buildCmd}   # build / compile check\n`
+    content += `  ${testCmd}   # tests\n`
+    content += `  ${lintCmd}   # lint / vet\n\n`
+    content += 'Rules:\n'
+    content += '- Build must pass before marking any ML as done\n'
+    content += '- Run `trackfw validate` before committing backend changes\n\n'
+  }
+
+  // Pre-commit checklist
+  content += '## Pre-commit checklist\n\n'
+  content += 'Before every commit:\n'
+  content += '- [ ] `trackfw validate` passes with zero violations\n'
+  if (cfg.backend && cfg.backend !== 'none' && cfg.backend !== '') {
+    const [buildCmd] = backendCommands(cfg)
+    content += `- [ ] \`${buildCmd}\` passes\n`
+  }
+  if (cfg.frontend && cfg.frontend !== 'none' && cfg.frontend !== '') {
+    const pm = (cfg.pkgManager && cfg.pkgManager !== 'none') ? cfg.pkgManager : 'npm'
+    content += `- [ ] \`${pm} run build\` passes\n`
+  }
+  content += '\n'
+
+  // Git hooks section
+  content += '## Git hooks\n\n'
+  switch (cfg.hooks) {
+    case 'husky':
+      content += 'Git hook configured in `.husky/pre-commit` — runs `trackfw validate` automatically.\n\n'
+      break
+    case 'lefthook':
+      content += 'Git hook configured in `lefthook.yml` — runs `trackfw validate` automatically.\n\n'
+      break
+    default:
+      content += 'No git hook configured. Run `trackfw validate` manually before every commit.\n\n'
+  }
+
+  // CI gate section
+  content += '## CI gate\n\n'
+  switch (cfg.ci) {
+    case 'github-actions':
+      content += '`.github/workflows/trackfw-gate.yml` runs `trackfw validate` on every pull request to main.\n'
+      break
+    case 'gitlab-ci':
+      content += '`.gitlab-ci-trackfw.yml` runs `trackfw validate` on every merge request.\n'
+      break
+    default:
+      content += 'No CI gate configured.\n'
+  }
+
+  fs.writeFileSync('CLAUDE.md', content, 'utf8')
+  console.log('  ✓ CLAUDE.md')
+}
+
+/**
+ * Retorna [buildCmd, testCmd, lintCmd] para o backend configurado.
+ */
+function backendCommands(cfg) {
+  const pm = (cfg.pkgManager && cfg.pkgManager !== 'none') ? cfg.pkgManager : 'npm'
+  switch (cfg.backend) {
+    case 'go':
+      return ['go build ./...', 'go test ./...', 'go vet ./...']
+    case 'java':
+      return ['mvn package -q', 'mvn test', 'mvn compile -q']
+    case 'node':
+      return [`${pm} run build`, `${pm} test`, `${pm} run lint`]
+    case 'python':
+      return [
+        "python -m py_compile $(find . -name '*.py' -not -path './.venv/*' -not -path './venv/*')",
+        'python -m pytest',
+        'ruff check .',
+      ]
+    default:
+      return ['', '', '']
+  }
+}
+
+// ---------------------------------------------------------------------------
+// .claude/commands/trackfw/ — 7 slash commands
+// ---------------------------------------------------------------------------
+
+function generateClaudeCommands() {
+  const dir = '.claude/commands/trackfw'
+  fs.mkdirSync(dir, { recursive: true })
+
+  const commands = {
+    'adr.md': `Execute o seguinte comando bash: \`trackfw adr new "$ARGUMENTS"\`
+
+Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
+
+\`\`\`
+trackfw não está instalado. Instale com uma das opções:
+
+  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+  npm install -g trackfw
+  pip install trackfw
+\`\`\``,
+
+    'req.md': `Execute o seguinte comando bash: \`trackfw req new "$ARGUMENTS"\`
+
+Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
+
+\`\`\`
+trackfw não está instalado. Instale com uma das opções:
+
+  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+  npm install -g trackfw
+  pip install trackfw
+\`\`\``,
+
+    'validate.md': `Execute o seguinte comando bash: \`trackfw validate\`
+
+Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
+
+\`\`\`
+trackfw não está instalado. Instale com uma das opções:
+
+  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+  npm install -g trackfw
+  pip install trackfw
+\`\`\``,
+
+    'status.md': `Execute o seguinte comando bash: \`trackfw status\`
+
+Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
+
+\`\`\`
+trackfw não está instalado. Instale com uma das opções:
+
+  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+  npm install -g trackfw
+  pip install trackfw
+\`\`\``,
+
+    'move.md': `Execute o seguinte comando bash: \`trackfw roadmap move $ARGUMENTS\`
+
+O formato esperado é: \`<nome-do-roadmap> <estado>\`
+
+Estados válidos: \`backlog\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`
+
+Exemplo: \`/trackfw:move meu-roadmap wip\`
+
+Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
+trackfw não está instalado. Instale com:
+  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+  npm install -g trackfw
+  pip install trackfw`,
+
+    'roadmap.md': `Gere um roadmap de implementação em microlotes para uma REQ do projeto.
+
+## Passos
+
+1. **Listar REQs disponíveis**
+   Use Glob para listar \`docs/req/*.md\`. Se nenhum arquivo encontrado, informe:
+   > Nenhuma REQ encontrada em \`docs/req/\`. Crie uma primeiro com \`/trackfw:req\`.
+
+2. **Selecionar a REQ**
+   - Se \`$ARGUMENTS\` foi fornecido: use como filtro (substring case-insensitive) para encontrar o arquivo
+   - Se não foi fornecido ou o filtro não encontrar exatamente um: liste os arquivos disponíveis e pergunte ao usuário qual usar
+   - Leia o conteúdo completo do arquivo REQ selecionado
+
+3. **Gerar o roadmap**
+   Com base no conteúdo da REQ, gere um roadmap seguindo **estritamente** este formato:
+
+   \`\`\`markdown
+   # Roadmap: <título derivado da REQ>
+
+   > Criado em: <YYYY-MM-DD> | Status: ⬜ Backlog
+
+   ## Diagnóstico / Contexto
+   <resumo do problema, motivação e escopo extraídos da REQ>
+
+   ## Wave 1 — <nome descritivo> (<N> MLs em paralelo)
+   > Dependências: Independente
+
+   ### ML-1A — <título>
+   **Status:** ⬜ Pendente
+   **Arquivos afetados:**
+   - \`caminho/exato/do/arquivo\`
+   **Ações:**
+   - Descrição detalhada da ação com valores, chaves e comandos exatos
+   **Critérios de aceite:**
+   - [ ] build sem erros
+   - [ ] testes verdes
+   **Comandos de validação:** \`<comando de build e teste do projeto>\`
+   \`\`\`
+
+   **Princípios obrigatórios:**
+   - MLs dentro da mesma Wave são **independentes** (arquivos distintos, sem conflito)
+   - Cada ML deve ser detalhado o suficiente para execução por um agente sem contexto extra
+   - Maximizar paralelismo: agrupe em paralelo tudo que não compartilhar arquivos
+   - Waves sequenciais apenas quando há dependência real de resultado
+   - Critérios de aceite mensuráveis em cada ML
+
+4. **Salvar o arquivo**
+   - Calcule o slug: título em lowercase, espaços → hifens, remova caracteres especiais
+   - Crie o arquivo em \`docs/roadmaps/backlog/ROADMAP-<YYYY-MM-DD>-<slug>.md\`
+   - Use a data de hoje
+
+5. **Confirmar**
+   Informe o caminho do arquivo criado e um resumo das Waves e total de MLs gerados.`,
+
+    'implement.md': `Você é o orquestrador de implementação do trackfw. Siga o fluxo abaixo **sem pular etapas**.
+
+## Argumento
+
+\`$ARGUMENTS\` é opcional. Se fornecido, é usado como filtro (substring case-insensitive) sobre os nomes de arquivo das REQs.
+
+---
+
+## Passo 1 — Selecionar a REQ
+
+Use Glob para listar \`docs/req/*.md\`.
+
+- Se **nenhum arquivo encontrado**: informe que não há REQs disponíveis e sugira criar com \`/trackfw:req\`.
+- Se **\`$ARGUMENTS\` foi fornecido** e filtra para exatamente uma REQ: use-a diretamente.
+- Em **todos os outros casos** (sem argumento, ou argumento ambíguo): apresente a lista de REQs disponíveis e pergunte ao usuário qual deseja implementar.
+
+Leia o conteúdo completo da REQ selecionada.
+
+---
+
+## Passo 2 — Encontrar ou gerar o Roadmap
+
+Verifique se existe um roadmap vinculado à REQ buscando em \`docs/roadmaps/\` (backlog, wip, blocked, done, abandoned) por arquivo cujo nome contenha o slug da REQ.
+
+**Se o roadmap ainda não existe:**
+- Informe o usuário: "Nenhum roadmap encontrado para esta REQ. Gerando agora..."
+- Execute o fluxo completo de geração do \`/trackfw:roadmap\` (leia o arquivo \`.claude/commands/trackfw/roadmap.md\` para seguir as instruções exatas), passando a REQ já selecionada — não pergunte novamente.
+- Salve o roadmap gerado em \`docs/roadmaps/backlog/ROADMAP-<YYYY-MM-DD>-<slug>.md\`.
+
+**Se o roadmap existe e já está em \`done/\` ou \`abandoned/\`:**
+- Informe o usuário e pergunte se deseja criar um novo roadmap ou encerrar.
+
+**Se o roadmap existe em \`backlog/\` ou \`blocked/\`:**
+- Prossiga para o Passo 3.
+
+**Se já está em \`wip/\`:**
+- Prossiga diretamente para o Passo 4 (já está em execução).
+
+---
+
+## Passo 3 — Mover roadmap para WIP
+
+Execute:
+\`\`\`bash
+trackfw roadmap move <nome-do-roadmap> wip
+\`\`\`
+
+Confirme que o arquivo foi movido para \`docs/roadmaps/wip/\`.
+
+---
+
+## Passo 4 — Ler e apresentar o plano
+
+Leia o roadmap (agora em \`wip/\`). Apresente ao usuário:
+- Título do roadmap
+- Total de Waves e MLs
+- Lista resumida dos MLs por Wave
+
+Confirme: "Iniciando implementação. Vou executar cada ML em ordem e atualizar o roadmap a cada conclusão."
+
+---
+
+## Passo 5 — Executar cada ML em ordem
+
+Para cada Wave (em sequência), execute os MLs da Wave:
+
+### Para cada ML:
+
+**5a. Anunciar:** informe qual ML está sendo executado (ex: "Executando ML-1A — Criar client.go").
+
+**5b. Implementar:** execute as ações descritas no ML usando suas ferramentas (Read, Write, Edit, Bash). Siga exatamente os arquivos afetados, ações e critérios de aceite listados no roadmap.
+
+**5c. Validar:** execute os comandos de validação do ML. Se falhar, corrija antes de avançar.
+
+**5d. Atualizar o roadmap:** edite o arquivo de roadmap em \`docs/roadmaps/wip/\` substituindo o status do ML:
+- \`**Status:** ⬜ Pendente\` → \`**Status:** ✅ Concluído\`
+
+**5e. Commitar:**
+\`\`\`bash
+git add -A
+git commit -m "feat(<escopo>): <descrição do ML>"
+\`\`\`
+
+Só avance para a próxima Wave após todos os MLs da Wave atual estarem ✅.
+
+---
+
+## Passo 6 — Finalizar
+
+Quando todos os MLs estiverem ✅:
+
+**6a.** Execute \`trackfw validate\` — deve passar com zero violations.
+
+**6b.** Mova o roadmap para done:
+\`\`\`bash
+trackfw roadmap move <nome-do-roadmap> done
+\`\`\`
+
+**6c.** Faça o commit final:
+\`\`\`bash
+git add docs/roadmaps/
+git commit -m "docs(trackfw): roadmap <nome> → done"
+\`\`\`
+
+**6d.** Informe o usuário:
+\`\`\`
+✅ Implementação concluída.
+Roadmap: docs/roadmaps/done/<nome>.md
+Próximo passo: abrir PR com gh pr create
+\`\`\``,
+  }
+
+  let created = 0
+  let skipped = 0
+  for (const [filename, content] of Object.entries(commands)) {
+    const filePath = path.join(dir, filename)
+    if (fs.existsSync(filePath)) {
+      skipped++
+      continue
+    }
+    fs.writeFileSync(filePath, content, 'utf8')
+    created++
+  }
+
+  if (skipped > 0) {
+    console.log(`  ✓ ${dir} (${created} slash commands criados, ${skipped} já existiam — não sobrescritos)`)
+  } else {
+    console.log(`  ✓ ${dir} (${created} slash commands)`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AI tool installers
+// ---------------------------------------------------------------------------
+
+/**
+ * installAgents — instala agentes Claude Code em ~/.claude/agents/
+ * O pacote npm não embute os templates binários do Go, por isso informa
+ * ao usuário que esta operação requer o binário Go instalado.
+ */
+async function installAgents() {
+  console.log('  ✓ claude (agentes — execute `trackfw install agents` com o binário Go para instalar os templates)')
+}
+
+async function installGemini() {
+  console.log('  ✓ gemini (sem templates disponíveis no pacote npm — instale o binário Go para acesso completo)')
+}
+
+async function installCursor() {
+  console.log('  ✓ cursor (sem templates disponíveis no pacote npm — instale o binário Go para acesso completo)')
+}
+
+async function installCopilot() {
+  console.log('  ✓ copilot (sem templates disponíveis no pacote npm — instale o binário Go para acesso completo)')
+}
+
+async function installWindsurf() {
+  console.log('  ✓ windsurf (sem templates disponíveis no pacote npm — instale o binário Go para acesso completo)')
+}
+
+async function installAmazonQ() {
+  console.log('  ✓ amazonq (sem templates disponíveis no pacote npm — instale o binário Go para acesso completo)')
+}
+
+module.exports = {
+  GOV_DIRS,
+  scaffold,
+  writeTrackfwConfig,
+  generateValidateScript,
+  generateCIWorkflow,
+  generateGitHooks,
+  generateClaudeMD,
+  generateClaudeCommands,
+  installAgents,
+  installGemini,
+  installCursor,
+  installCopilot,
+  installWindsurf,
+  installAmazonQ,
+}