{"id":50776219,"url":"https://github.com/kgsaran/trackfw","last_synced_at":"2026-06-18T07:01:08.609Z","repository":{"id":364159980,"uuid":"1266478121","full_name":"kgsaran/trackfw","owner":"kgsaran","description":"CLI de governança para entrega de software: ADR → REQ → ROADMAP → kanban. Suporte a agentes de IA.","archived":false,"fork":false,"pushed_at":"2026-06-15T13:58:21.000Z","size":1198,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T06:27:56.576Z","etag":null,"topics":["adr","ai-agents","architecture-decision-records","cli","developer-tools","devops","go","governance","roadmap","software-delivery"],"latest_commit_sha":null,"homepage":"https://github.com/kgsaran/trackfw","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kgsaran.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/artemis/done/ROADMAP-2026-06-14-serve-api-tests-nodejs.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T16:49:16.000Z","updated_at":"2026-06-15T13:57:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kgsaran/trackfw","commit_stats":null,"previous_names":["kgsaran/trackfw"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/kgsaran/trackfw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgsaran%2Ftrackfw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgsaran%2Ftrackfw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgsaran%2Ftrackfw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgsaran%2Ftrackfw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kgsaran","download_url":"https://codeload.github.com/kgsaran/trackfw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgsaran%2Ftrackfw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34479555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","ai-agents","architecture-decision-records","cli","developer-tools","devops","go","governance","roadmap","software-delivery"],"created_at":"2026-06-12T00:00:33.956Z","updated_at":"2026-06-18T07:01:08.566Z","avatar_url":"https://github.com/kgsaran.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# trackfw\n\n\u003e Governed software delivery — ADR → REQ → ROADMAP → backlog / wip / done\n\n[![Release](https://img.shields.io/github/v/release/kgsaran/trackfw)](https://github.com/kgsaran/trackfw/releases/latest)\n[![Go](https://img.shields.io/badge/go-1.21+-00ADD8?logo=go)](go.mod)\n[![License](https://img.shields.io/github/license/kgsaran/trackfw)](LICENSE)\n\n**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.\n\n```\nADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned\n```\n\nEvery 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.\n\n---\n\n## The problem\n\nMost 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.\n\n- **ADR tools** manage decision records, but don't connect them to delivery.\n- **Kanban tools** track tasks, but don't enforce that tasks are backed by a decision.\n- **CI tools** validate code, but don't validate governance.\n\ntrackfw closes the loop — connective tissue between *why*, *what*, and *when*.\n\n---\n\n## Demo\n\n![trackfw demo](docs/demo.gif)\n\n```bash\n$ trackfw req new \"Login screen\"\n\n  ? Describe what you want to build  Login screen for the application\n  ? Motivation                       Users need to authenticate to access the system\n\n  Detected domains: authentication, ui\n\n  ? How will users authenticate?\n  \u003e Local login (email + password)\n    SSO (Google, Azure AD, Okta...)\n    Not decided yet  ← generates ADR draft\n\n  ? Is there an existing UI framework or design system?\n    Yes, already chosen\n  \u003e No, need to choose a UI framework  ← generates ADR draft\n\nADR drafts created:\n  → ADR-2026-06-12-authentication-strategy.md\n  → ADR-2026-06-12-ui-framework.md\n\nResolve these ADRs (set Status: Accepted) before creating a roadmap.\ncreated docs/req/REQ-2026-06-12-login-screen.md\n```\n\n---\n\n## Installation\n\n### macOS / Linux — curl\n\n```bash\ncurl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n```\n\n### Homebrew\n\n```bash\nbrew install kgsaran/tap/trackfw\n```\n\n### Go\n\n```bash\ngo install github.com/kgsaran/trackfw/cmd/trackfw@latest\n```\n\n### npm (pure Node.js — no binary)\n\n```bash\nnpm install -g trackfw\n```\n\nThe npm package is pure Node.js — no compiled binary, no postinstall download. Works everywhere Node.js ≥ 18 is installed, including corporate Windows environments where unsigned `.exe` files are blocked by antivirus.\n\n### pip\n\n```bash\npip install trackfw\n```\n\n---\n\n## Quick start\n\n```bash\n# 1. Set up governance in your project (interactive wizard)\ntrackfw init\n\n# 2. Document an architectural decision\ntrackfw adr new \"Use PostgreSQL as primary database\"\n\n# 3. Create a requirement — wizard detects domains and proposes ADR drafts\ntrackfw req new \"User authentication\"\n\n# 4. Once ADRs are accepted, plan the work\ntrackfw roadmap new \"Auth service\"\n\n# 5. Check governance health\ntrackfw validate\n\n# 6. See what is in flight\ntrackfw status\n```\n\n---\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `trackfw init` | Interactive wizard — scaffolds governance + AI integrations |\n| `trackfw adr new \"title\"` | Create a new Architecture Decision Record |\n| `trackfw adr list` | List all ADRs with status |\n| `trackfw req new \"title\"` | Create a REQ with guided ADR discovery |\n| `trackfw req list` | List all REQs with status |\n| `trackfw roadmap new \"title\"` | Create a roadmap in `backlog/` |\n| `trackfw roadmap show \u003cname\u003e` | Print a roadmap with its current state |\n| `trackfw roadmap move \u003cname\u003e \u003cstate\u003e` | Move roadmap between states |\n| `trackfw roadmap list` | List all roadmaps grouped by state |\n| `trackfw validate` | Check governance consistency (use as CI gate) |\n| `trackfw status` | Show wip, blocked, REQs waiting on ADRs |\n| `trackfw log [--tail N]` | Show roadmap state transition history |\n| `trackfw plugins list` | List installed plugins |\n| `trackfw plugins add \u003cuser/repo\u003e` | Install a plugin from GitHub Releases |\n| `trackfw plugins remove \u003cname\u003e` | Remove an installed plugin |\n| `trackfw agents` | Install Claude Code subagents *(Go binary only)* |\n| `trackfw gemini` | Install Gemini CLI skills and commands *(Go binary only)* |\n| `trackfw cursor` | Install Cursor rules *(Go binary only)* |\n| `trackfw copilot` | Install GitHub Copilot instructions *(Go binary only)* |\n| `trackfw windsurf` | Install Windsurf rules and workflows *(Go binary only)* |\n| `trackfw amazonq` | Install Amazon Q Developer rules *(Go binary only)* |\n| `trackfw version` | Print version |\n\n\u003e **Go binary only** commands (`agents`, `gemini`, `cursor`, `copilot`, `windsurf`, `amazonq`) are available when installed via brew, `install.sh`, or `go install`. When using the npm package, AI integrations are installed through `trackfw init`.\n\n---\n\n## Governance chain\n\n| Layer | Artifact | Purpose |\n|---|---|---|\n| Decide | `ADR` | Document the *why* behind a technical decision |\n| Specify | `REQ` | Define *what* needs to be delivered, linked to an ADR |\n| Plan | `ROADMAP` | Break the requirement into microbatches with acceptance criteria |\n| Execute | `backlog → wip → done` | Folder position is the source of truth |\n\n### Roadmap states\n\n```\ndocs/roadmaps/\n├── backlog/     queued, not started\n├── wip/         actively being worked on (one at a time)\n├── blocked/     waiting on a dependency or decision\n├── done/        completed and validated\n└── abandoned/   discontinued — reason required in file\n```\n\nMoving a file between folders **is** the state transition. No database, no API.\n\n---\n\n## REQ-driven ADR discovery\n\nWhen 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.\n\n```\ntrackfw req new \"checkout flow with payment integration\"\n```\n\nDetected domains: **persistence**, **api**, **events**\n\nQuestions asked:\n- Which database engine will be used? → *Not decided yet* → `ADR: database-engine (Draft)`\n- Which API protocol will be used? → *REST (already decided)* → no ADR\n- Which event broker will be used? → *Not decided yet* → `ADR: event-broker (Draft)`\n\nThe REQ is linked to its blocking ADRs. `trackfw validate` enforces that no roadmap is created until every linked ADR reaches `Accepted` status.\n\nThis is the difference between experienced architects (who know which decisions to make) and everyone else — trackfw brings the architectural checklist to the requirement.\n\n---\n\n## `trackfw validate` — governance gate\n\n```bash\n$ trackfw validate\n\n✗ REQ-2026-06-12-login-screen.md is blocked by Draft ADR: ADR-authentication-strategy.md\n✗ roadmap/wip/auth-service.md has no linked REQ\n⚠  2 roadmaps in wip/ (recommended: 1)\n\n2 violation(s) found\n```\n\nDesigned to run as a **pre-commit hook** and a **CI quality gate**. `trackfw init` wires both automatically for your stack.\n\n---\n\n## `trackfw status` — current state at a glance\n\n```bash\n$ trackfw status\n\n── trackfw status ──────────────────────\n\n🔄 WIP (1)\n   roadmap-auth-service.md\n\n❌ Blocked (0)\n\n⏳ REQs blocked by Draft ADRs (1)\n   REQ-2026-06-12-login-screen.md\n     → ADR-2026-06-12-authentication-strategy.md (Draft)\n\n✅ Done (last 5)\n   roadmap-user-profile.md\n   roadmap-db-setup.md\n```\n\n---\n\n## AI assistant integration\n\n`trackfw init` asks which AI tools your team uses and installs native governance context for each. When using the Go binary (brew, `install.sh`, `go install`), each integration can also be run as a standalone command.\n\n| Command | Installs | Format |\n|---|---|---|\n| `trackfw agents` | 10 subagents in `~/.claude/agents/` | Claude Code `.md` with frontmatter |\n| `trackfw gemini` | GEMINI.md + 10 skills + 3 commands | `~/.gemini/` + project root |\n| `trackfw cursor` | 10 rules in `.cursor/rules/` | `.mdc` with YAML frontmatter |\n| `trackfw copilot` | `copilot-instructions.md` + 10 instructions + 10 prompts | `.github/` |\n| `trackfw windsurf` | 10 rules + workflows in `.windsurf/` + global rules | Appends to `~/.codeium/windsurf/memories/` |\n| `trackfw amazonq` | 10 rules in `.amazonq/rules/` | Plain Markdown |\n\nEach installer is idempotent — running it twice never overwrites your customizations.\n\nThe 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**\n\n---\n\n## `trackfw init` — stack-aware scaffolding\n\n```\n? Project type?          Full-stack / Frontend / Backend / Governance only\n? Frontend stack?        React / Vue / Angular\n? Backend stack?         Go / Java / Node / Python\n? Package manager?       npm / pnpm / yarn / bun\n? Git hooks?             husky / lefthook / none\n? CI system?             GitHub Actions / GitLab CI / none\n? Which AI assistants?   Claude Code / Gemini CLI / Cursor / Copilot / Windsurf / Amazon Q\n```\n\nThe governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always identical — stack-agnostic. The generated hooks, workflows, and AI integrations adapt to your answers.\n\n---\n\n## Design principles\n\n1. **Files are state** — folder position is the source of truth. No database, no lock-in.\n2. **Traceability is mandatory** — `validate` is a gate, not a suggestion.\n3. **Framework-agnostic, integration-aware** — governance never changes; generated artifacts adapt to your stack.\n4. **One active roadmap at a time** — parallel work without traceability is the root of most delivery chaos.\n5. **Human-readable, machine-parseable** — every artifact is a Markdown file with a predictable structure.\n6. **Guided, not prescriptive** — the wizard surfaces decisions you might not know to ask; it never blocks work unnecessarily.\n\n---\n\n## What trackfw is not\n\n- Not a project management SaaS — no UI, no accounts, no cloud sync\n- Not a replacement for Git history — it complements, not duplicates\n- Not a task tracker — use GitHub Issues, Linear, or Jira for tasks; trackfw governs the *why*\n- Not opinionated about how you write code — only about how you document decisions\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/kgsaran/trackfw\ncd trackfw\nmake build   # compiles to bin/trackfw\nmake test    # go test ./...\nmake lint    # go vet ./...\n```\n\nGenerators are the stack-specific components — you can add support for a new stack without touching core logic. See `internal/generators/` for examples.\n\nIssues and pull requests welcome at [github.com/kgsaran/trackfw](https://github.com/kgsaran/trackfw).\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgsaran%2Ftrackfw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkgsaran%2Ftrackfw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgsaran%2Ftrackfw/lists"}