trackfw 1.0.2 → 1.0.3

package/bin/README.md

@@ -0,0 +1,301 @@
+# trackfw
+
+> Governed software delivery — ADR → REQ → ROADMAP → backlog / wip / done
+
+[![Release](https://img.shields.io/github/v/release/kgsaran/trackfw)](https://github.com/kgsaran/trackfw/releases/latest)
+[![Go](https://img.shields.io/badge/go-1.21+-00ADD8?logo=go)](go.mod)
+[![License](https://img.shields.io/github/license/kgsaran/trackfw)](LICENSE)
+
+**trackfw** is an open-source CLI that enforces a traceable chain from architectural decision to shipped code — without SaaS, accounts, or databases. Markdown files are state.
+
+```
+ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
+```
+
+Every piece of work traces back to a decision. Every decision links to a requirement. Every requirement lands in a roadmap. No orphan work, no undocumented choices.
+
+---
+
+## The problem
+
+Most teams accumulate technical debt not because they lack tools, but because they lack **governance traceability**. Decisions are made in Slack. Requirements live in someone's head. Roadmaps drift from what was actually shipped.
+
+- **ADR tools** manage decision records, but don't connect them to delivery.
+- **Kanban tools** track tasks, but don't enforce that tasks are backed by a decision.
+- **CI tools** validate code, but don't validate governance.
+
+trackfw closes the loop — connective tissue between *why*, *what*, and *when*.
+
+---
+
+## Demo
+
+![trackfw demo](docs/demo.gif)
+
+```bash
+$ trackfw req new "Login screen"
+
+  ? Describe what you want to build  Login screen for the application
+  ? Motivation                       Users need to authenticate to access the system
+
+  Detected domains: authentication, ui
+
+  ? How will users authenticate?
+  > Local login (email + password)
+    SSO (Google, Azure AD, Okta...)
+    Not decided yet  ← generates ADR draft
+
+  ? Is there an existing UI framework or design system?
+    Yes, already chosen
+  > No, need to choose a UI framework  ← generates ADR draft
+
+ADR drafts created:
+  → ADR-2026-06-12-authentication-strategy.md
+  → ADR-2026-06-12-ui-framework.md
+
+Resolve these ADRs (set Status: Accepted) before creating a roadmap.
+created docs/req/REQ-2026-06-12-login-screen.md
+```
+
+---
+
+## Installation
+
+### macOS / Linux — curl
+
+```bash
+curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
+```
+
+### Homebrew
+
+```bash
+brew install kgsaran/tap/trackfw
+```
+
+### Go
+
+```bash
+go install github.com/kgsaran/trackfw/cmd/trackfw@latest
+```
+
+### npm
+
+```bash
+npm install -g trackfw
+```
+
+### pip
+
+```bash
+pip install trackfw
+```
+
+---
+
+## Quick start
+
+```bash
+# 1. Set up governance in your project (interactive wizard)
+trackfw init
+
+# 2. Document an architectural decision
+trackfw adr new "Use PostgreSQL as primary database"
+
+# 3. Create a requirement — wizard detects domains and proposes ADR drafts
+trackfw req new "User authentication"
+
+# 4. Once ADRs are accepted, plan the work
+trackfw roadmap new "Auth service"
+
+# 5. Check governance health
+trackfw validate
+
+# 6. See what is in flight
+trackfw status
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `trackfw init` | Interactive wizard — scaffolds governance + AI integrations |
+| `trackfw adr new "title"` | Create a new Architecture Decision Record |
+| `trackfw adr list` | List all ADRs with status |
+| `trackfw req new "title"` | Create a REQ with guided ADR discovery |
+| `trackfw req list` | List all REQs with status |
+| `trackfw roadmap new "title"` | Create a roadmap in `backlog/` |
+| `trackfw roadmap move <name> <state>` | Move roadmap between states |
+| `trackfw roadmap list` | List all roadmaps grouped by state |
+| `trackfw validate` | Check governance consistency (use as CI gate) |
+| `trackfw status` | Show wip, blocked, REQs waiting on ADRs |
+| `trackfw agents` | Install Claude Code subagents |
+| `trackfw gemini` | Install Gemini CLI skills and commands |
+| `trackfw cursor` | Install Cursor rules |
+| `trackfw copilot` | Install GitHub Copilot instructions |
+| `trackfw windsurf` | Install Windsurf rules and workflows |
+| `trackfw amazonq` | Install Amazon Q Developer rules |
+| `trackfw version` | Print version |
+
+---
+
+## Governance chain
+
+| Layer | Artifact | Purpose |
+|---|---|---|
+| Decide | `ADR` | Document the *why* behind a technical decision |
+| Specify | `REQ` | Define *what* needs to be delivered, linked to an ADR |
+| Plan | `ROADMAP` | Break the requirement into microbatches with acceptance criteria |
+| Execute | `backlog → wip → done` | Folder position is the source of truth |
+
+### Roadmap states
+
+```
+docs/roadmaps/
+├── backlog/     queued, not started
+├── wip/         actively being worked on (one at a time)
+├── blocked/     waiting on a dependency or decision
+├── done/        completed and validated
+└── abandoned/   discontinued — reason required in file
+```
+
+Moving a file between folders **is** the state transition. No database, no API.
+
+---
+
+## REQ-driven ADR discovery
+
+When you run `trackfw req new`, the wizard analyzes your intent and asks targeted questions for each detected domain — authentication, UI, persistence, API, deploy, events. Unanswered architectural decisions become ADR drafts automatically.
+
+```
+trackfw req new "checkout flow with payment integration"
+```
+
+Detected domains: **persistence**, **api**, **events**
+
+Questions asked:
+- Which database engine will be used? → *Not decided yet* → `ADR: database-engine (Draft)`
+- Which API protocol will be used? → *REST (already decided)* → no ADR
+- Which event broker will be used? → *Not decided yet* → `ADR: event-broker (Draft)`
+
+The REQ is linked to its blocking ADRs. `trackfw validate` enforces that no roadmap is created until every linked ADR reaches `Accepted` status.
+
+This is the difference between experienced architects (who know which decisions to make) and everyone else — trackfw brings the architectural checklist to the requirement.
+
+---
+
+## `trackfw validate` — governance gate
+
+```bash
+$ trackfw validate
+
+✗ REQ-2026-06-12-login-screen.md is blocked by Draft ADR: ADR-authentication-strategy.md
+✗ roadmap/wip/auth-service.md has no linked REQ
+⚠  2 roadmaps in wip/ (recommended: 1)
+
+2 violation(s) found
+```
+
+Designed to run as a **pre-commit hook** and a **CI quality gate**. `trackfw init` wires both automatically for your stack.
+
+---
+
+## `trackfw status` — current state at a glance
+
+```bash
+$ trackfw status
+
+── trackfw status ──────────────────────
+
+🔄 WIP (1)
+   roadmap-auth-service.md
+
+❌ Blocked (0)
+
+⏳ REQs blocked by Draft ADRs (1)
+   REQ-2026-06-12-login-screen.md
+     → ADR-2026-06-12-authentication-strategy.md (Draft)
+
+✅ Done (last 5)
+   roadmap-user-profile.md
+   roadmap-db-setup.md
+```
+
+---
+
+## AI assistant integration
+
+`trackfw init` asks which AI tools your team uses and installs native governance context for each. Commands can also be run independently.
+
+| Command | Installs | Format |
+|---|---|---|
+| `trackfw agents` | 10 subagents in `~/.claude/agents/` | Claude Code `.md` with frontmatter |
+| `trackfw gemini` | GEMINI.md + 10 skills + 3 commands | `~/.gemini/` + project root |
+| `trackfw cursor` | 10 rules in `.cursor/rules/` | `.mdc` with YAML frontmatter |
+| `trackfw copilot` | `copilot-instructions.md` + 10 instructions + 10 prompts | `.github/` |
+| `trackfw windsurf` | 10 rules + workflows in `.windsurf/` + global rules | Appends to `~/.codeium/windsurf/memories/` |
+| `trackfw amazonq` | 10 rules in `.amazonq/rules/` | Plain Markdown |
+
+Each installer is idempotent — running it twice never overwrites your customizations.
+
+The 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**
+
+---
+
+## `trackfw init` — stack-aware scaffolding
+
+```
+? Project type?          Full-stack / Frontend / Backend / Governance only
+? Frontend stack?        React / Vue / Angular
+? Backend stack?         Go / Java / Node / Python
+? Package manager?       npm / pnpm / yarn / bun
+? Git hooks?             husky / lefthook / none
+? CI system?             GitHub Actions / GitLab CI / none
+? Which AI assistants?   Claude Code / Gemini CLI / Cursor / Copilot / Windsurf / Amazon Q
+```
+
+The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always identical — stack-agnostic. The generated hooks, workflows, and AI integrations adapt to your answers.
+
+---
+
+## Design principles
+
+1. **Files are state** — folder position is the source of truth. No database, no lock-in.
+2. **Traceability is mandatory** — `validate` is a gate, not a suggestion.
+3. **Framework-agnostic, integration-aware** — governance never changes; generated artifacts adapt to your stack.
+4. **One active roadmap at a time** — parallel work without traceability is the root of most delivery chaos.
+5. **Human-readable, machine-parseable** — every artifact is a Markdown file with a predictable structure.
+6. **Guided, not prescriptive** — the wizard surfaces decisions you might not know to ask; it never blocks work unnecessarily.
+
+---
+
+## What trackfw is not
+
+- Not a project management SaaS — no UI, no accounts, no cloud sync
+- Not a replacement for Git history — it complements, not duplicates
+- Not a task tracker — use GitHub Issues, Linear, or Jira for tasks; trackfw governs the *why*
+- Not opinionated about how you write code — only about how you document decisions
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/kgsaran/trackfw
+cd trackfw
+make build   # compiles to bin/trackfw
+make test    # go test ./...
+make lint    # go vet ./...
+```
+
+Generators are the stack-specific components — you can add support for a new stack without touching core logic. See `internal/generators/` for examples.
+
+Issues and pull requests welcome at [github.com/kgsaran/trackfw](https://github.com/kgsaran/trackfw).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Governed software delivery framework: ADR → REQ → ROADMAP → kanban",
   "keywords": [
     "cli",
@@ -18,12 +18,8 @@
   "bin": {
     "trackfw": "./bin/trackfw"
   },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js"
-  },
   "files": [
-    "bin/",
-    "scripts/"
+    "bin/"
   ],
   "engines": {
     "node": ">=14"

package/bin/trackfw

@@ -1,22 +0,0 @@
-#!/usr/bin/env node
-
-'use strict'
-
-const { spawnSync } = require('child_process')
-const path = require('path')
-const fs = require('fs')
-
-const isWindows = process.platform === 'win32'
-const binaryName = isWindows ? 'trackfw-bin.exe' : 'trackfw-bin'
-const binaryPath = path.join(__dirname, binaryName)
-
-if (!fs.existsSync(binaryPath)) {
-  console.error(
-    'trackfw: binário não encontrado em ' + binaryPath + '\n' +
-    'Tente reinstalar: npm install -g trackfw'
-  )
-  process.exit(1)
-}
-
-const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: 'inherit' })
-process.exit(result.status ?? 1)

package/scripts/postinstall.js

@@ -1,221 +0,0 @@
-#!/usr/bin/env node
-
-'use strict';
-
-const https = require('https');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const child_process = require('child_process');
-
-// ---------------------------------------------------------------------------
-// Mapeamento de plataforma e arquitetura
-// ---------------------------------------------------------------------------
-
-const PLATFORM_MAP = {
-  linux: 'linux',
-  darwin: 'darwin',
-  win32: 'windows',
-};
-
-const ARCH_MAP = {
-  x64: 'amd64',
-  arm64: 'arm64',
-};
-
-const platform = PLATFORM_MAP[process.platform];
-const arch = ARCH_MAP[process.arch];
-
-if (!platform || !arch) {
-  console.warn('trackfw: plataforma não suportada, pulando instalação do binário');
-  process.exit(0);
-}
-
-// ---------------------------------------------------------------------------
-// Versão — lida do package.json do wrapper npm
-// ---------------------------------------------------------------------------
-
-const pkgPath = path.join(__dirname, '..', 'package.json');
-const { version } = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-
-// ---------------------------------------------------------------------------
-// URL de download
-// ---------------------------------------------------------------------------
-
-const isWindows = platform === 'windows';
-const ext = isWindows ? '.zip' : '.tar.gz';
-const archiveName = `trackfw_${version}_${platform}_${arch}${ext}`;
-const downloadUrl = `https://github.com/kgsaran/trackfw/releases/download/v${version}/${archiveName}`;
-
-// ---------------------------------------------------------------------------
-// Destino final do binário
-// ---------------------------------------------------------------------------
-
-const binDir = path.join(__dirname, '..', 'bin');
-const binName = isWindows ? 'trackfw-bin.exe' : 'trackfw-bin';
-const binDest = path.join(binDir, binName);
-
-if (!fs.existsSync(binDir)) {
-  fs.mkdirSync(binDir, { recursive: true });
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function download(url, destFile) {
-  return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(destFile);
-
-    function get(currentUrl) {
-      https
-        .get(currentUrl, (res) => {
-          if (res.statusCode === 301 || res.statusCode === 302) {
-            const location = res.headers['location'];
-            if (!location) {
-              reject(new Error('Redirect sem Location header'));
-              return;
-            }
-            res.resume();
-            // reabrir o arquivo para a requisição seguinte não acumular lixo
-            file.close(() => {
-              const file2 = fs.createWriteStream(destFile);
-              file2.on('finish', () => file2.close(resolve));
-              file2.on('error', (err) => { fs.unlink(destFile, () => {}); reject(err); });
-              https.get(location, (res2) => {
-                if (res2.statusCode !== 200) {
-                  reject(new Error(`Falha ao baixar ${location}: HTTP ${res2.statusCode}`));
-                  return;
-                }
-                res2.pipe(file2);
-              }).on('error', (err) => { fs.unlink(destFile, () => {}); reject(err); });
-            });
-            return;
-          }
-
-          if (res.statusCode !== 200) {
-            reject(new Error(`Falha ao baixar ${currentUrl}: HTTP ${res.statusCode}`));
-            return;
-          }
-
-          res.pipe(file);
-          file.on('finish', () => file.close(resolve));
-          file.on('error', (err) => {
-            fs.unlink(destFile, () => {});
-            reject(err);
-          });
-        })
-        .on('error', (err) => {
-          fs.unlink(destFile, () => {});
-          reject(err);
-        });
-    }
-
-    get(url);
-  });
-}
-
-function extract(archiveFile, destDir) {
-  if (isWindows) {
-    child_process.execSync(
-      `powershell -NoProfile -Command "Expand-Archive -LiteralPath '${archiveFile}' -DestinationPath '${destDir}' -Force"`,
-      { stdio: 'pipe' }
-    );
-  } else {
-    child_process.execSync(
-      `tar -xzf "${archiveFile}" -C "${destDir}"`,
-      { stdio: 'pipe' }
-    );
-  }
-}
-
-// Busca recursiva pelo binário em qualquer subdiretório após extração
-function findBinary(dir, name) {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      const found = findBinary(full, name);
-      if (found) return found;
-    } else if (entry.name === name) {
-      return full;
-    }
-  }
-  return null;
-}
-
-function cleanup(target) {
-  try {
-    if (!fs.existsSync(target)) return;
-    const stat = fs.statSync(target);
-    if (stat.isDirectory()) {
-      fs.rmSync(target, { recursive: true, force: true });
-    } else {
-      fs.unlinkSync(target);
-    }
-  } catch (_) {}
-}
-
-// ---------------------------------------------------------------------------
-// Função principal
-// ---------------------------------------------------------------------------
-
-async function main() {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trackfw-'));
-  const tmpFile = path.join(tmpDir, archiveName);
-
-  try {
-    console.log(`trackfw: baixando binário para ${platform}/${arch} v${version}...`);
-    console.log(`         ${downloadUrl}`);
-
-    await download(downloadUrl, tmpFile);
-
-    const fileSize = fs.statSync(tmpFile).size;
-    if (fileSize < 1000) {
-      throw new Error(`Arquivo baixado suspeito (${fileSize} bytes) — verifique a conexão ou se a versão v${version} foi publicada no GitHub`);
-    }
-
-    console.log('trackfw: extraindo arquivo...');
-    extract(tmpFile, tmpDir);
-
-    const extractedBinName = isWindows ? 'trackfw.exe' : 'trackfw';
-    const extractedBin = findBinary(tmpDir, extractedBinName);
-
-    if (!extractedBin) {
-      const files = [];
-      function listAll(d) {
-        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
-          const p = path.join(d, e.name);
-          files.push(p);
-          if (e.isDirectory()) listAll(p);
-        }
-      }
-      listAll(tmpDir);
-      throw new Error(
-        `Binário "${extractedBinName}" não encontrado após extração.\nArquivos encontrados:\n${files.join('\n')}`
-      );
-    }
-
-    fs.renameSync(extractedBin, binDest);
-
-    if (!isWindows) {
-      fs.chmodSync(binDest, 0o755);
-    }
-
-    console.log('trackfw: binário instalado com sucesso em ' + binDest);
-  } finally {
-    cleanup(tmpFile);
-    cleanup(tmpDir);
-  }
-}
-
-main().catch((err) => {
-  console.error('\ntrackfw: ERRO ao instalar binário:');
-  console.error('  ' + err.message);
-  console.error('\nAlternativas de instalação:');
-  console.error('  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh');
-  console.error('  brew install kgsaran/tap/trackfw  (macOS/Linux)');
-  console.error('  go install github.com/kgsaran/trackfw/cmd/trackfw@latest\n');
-  // Sair com 0 para não bloquear npm install em CIs sem acesso ao GitHub
-  process.exit(0);
-});