trackfw 2.15.1

Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.

trackfw

AI governance CLI for software delivery teams — ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned

trackfw is an open-source governance CLI for AI-native software delivery. It enforces a traceable chain from architectural decision to shipped code — without SaaS, accounts, or databases. Markdown files are state.

It is designed for teams looking for an ADR / REQ / ROADMAP governance framework with native support for AI coding assistants such as Codex, Claude Code, Gemini CLI, Antigravity, Cursor, GitHub Copilot, Windsurf, Amazon Q, and Kiro.

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.
• AI coding assistants generate code at unprecedented speed, but without traceability: who decided what? Why? Which requirement authorized this roadmap?

trackfw adds the governance layer that makes AI-assisted delivery auditable.

trackfw closes the loop — connective tissue between why, what, and when.

---

Demo

$ 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

curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh

Homebrew

brew install kgsaran/tap/trackfw

Go

go install github.com/kgsaran/trackfw/cmd/trackfw@latest

npm (pure Node.js — no binary)

npm install -g trackfw

The npm package is pure Node.js — no compiled binary or postinstall download. It works wherever Node.js ≥ 18 is installed. Shared behavior, including the AI integration lifecycle, follows the CLI parity contract.

pip

pip install trackfw

The pip package is pure Python 3.10+ — no compiled binary or postinstall download. Shared commands, validation rules, and by_agent behavior follow the CLI parity contract.

---

Quick start

# 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 show <name>	Print a roadmap with its current state
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 context	Print a structured summary of the project's governance state (REQs, Roadmaps, ADRs with counts and statuses)
trackfw serve	Start a local governance dashboard (no cloud, no accounts)
trackfw status	Show wip, blocked, REQs waiting on ADRs
trackfw log [--tail N]	Show roadmap state transition history
trackfw plugins list	List installed plugins
trackfw plugins add <user/repo>	Install a plugin from GitHub Releases
trackfw plugins remove <name>	Remove an installed plugin
trackfw agents list	List available agents and deployment state across AI CLIs
trackfw agents install	Install selected specialist agents
trackfw agents update	Safely update managed agents
trackfw agents uninstall	Remove selected owned agent deployments
trackfw skills list	List available governance skills and deployment state
trackfw skills install/update/uninstall	Manage selected governance skills
trackfw gemini, cursor, copilot, windsurf, amazonq	Historical aliases in the Go distribution only; use agents/skills
trackfw version	Print version

The same lifecycle contract is available from the Go/Homebrew, npm, and PyPI distributions.

---

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.

---

AI-native governance

trackfw v2.6.0 introduces features designed for teams where AI agents are first-class contributors.

Multi-agent namespacing

# trackfw.yaml
roadmap_namespacing: by_agent
agents: [claude, gemini, copilot]

Artifacts are organized by agent: docs/roadmaps/claude/wip/, docs/req/gemini/done/. trackfw validate and trackfw context are fully by_agent-aware — no false positives.

Bidirectional traceability (trace_id_field)

# trackfw.yaml
trace_id_field: req_id

Automatically verifies the REQ↔ROADMAP link in both directions. Reports 5 check types:

• traceid_orphan_req — REQ with no matching ROADMAP
• traceid_orphan_roadmap — ROADMAP with no matching REQ
• traceid_state_mismatch — REQ and ROADMAP in different states
• traceid_duplicate_req / traceid_duplicate_roadmap — duplicate trace IDs

Configurable rules

Every governance rule has configurable severity:

# trackfw.yaml
rules:
  req_has_adr:      "error"    # default
  req_has_roadmap:  "warning"  # relax for tactical REQs
  blocked_has_req:  "error"
  wip_limit:        "warning"
  stale_wip:        "warning"
  adr_orphan:       "off"      # silence during migration

15+ rules available. Adopt progressively — start with warning, tighten to error as your team builds the habit.

Governance gate

# trackfw.yaml
governance_mode: strict   # CI fails on any violation
# governance_mode: lenient # CI passes with warnings only

---

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

$ 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.

JSON output for CI integration

trackfw validate --json

{
  "summary": { "violations": 2, "warnings": 1, "mode": "strict", "exit_code": 1 },
  "violations": [
    { "rule": "wip_has_req", "file": "roadmaps/wip/auth-service.md" }
  ],
  "warnings": [
    { "rule": "stale_wip", "file": "roadmaps/wip/auth-service.md" }
  ]
}

Use --json for programmatic CI parsing, Slack notifications, or custom reporting.

---

trackfw status — current state at a glance

$ 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 can install initial AI integrations. The agents and skills command families provide the complete lifecycle in every distribution.

Target	Native/fallback representation
Claude Code	Subagent Markdown and Agent Skills
Codex	Custom-agent TOML and Agent Skills
Gemini CLI	Agent Markdown and skills
Antigravity	Agent/skill directories; explicit legacy-cli surface available
Cursor	Agent Markdown and skills
GitHub Copilot	Custom agents and Agent Skills
Windsurf	Specialist-skill fallback for agents and native skills
Amazon Q	CLI agent JSON and workflow-rule fallback
Kiro	Native IDE/CLI agents and Agent Skills

# Inspect every deployment, including legacy surfaces
trackfw agents list --json

# Install selected items in the repository
trackfw agents install --targets codex,claude --items architect,backend --scope project
trackfw skills install --targets codex,antigravity --items governance,implement --scope project

# Select an alternate surface explicitly
trackfw agents install --targets kiro --surface kiro=cli
trackfw agents list --targets antigravity --surface antigravity=legacy-cli

Without --targets, mutations open a numbered/checkbox selector in a TTY and fail with an actionable error in CI. The lifecycle reports not-installed, current, outdated, or modified. A manifest under .trackfw/ records scope-specific ownership, version, SHA-256, and shared claims. Modified files are never replaced or removed unless --force is explicit, and unmanaged files are never removed. Known historical templates are adopted without overwriting; unknown unmanaged content cannot be adopted by update, even with --force.

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 / Codex / Gemini / Antigravity / Cursor / Copilot / Windsurf / Amazon Q / Kiro

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.

The Codex integration is repository-scoped: AGENTS.md carries persistent instructions, .agents/skills/ provides governance workflows, .codex/agents/ provides specialist subagents, and .codex/hooks.json signals permission requests to the local dashboard.

---

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.
7. Configurable by design — every governance rule has a severity (off/warning/error). Start permissive, tighten as your team builds the habit.
8. AI-agent aware — roadmap_namespacing: by_agent and trace_id_field make AI-generated work traceable and auditable by default.

---

What trackfw is not

• Not a project management SaaS — no accounts, no cloud sync, no data leaving your repository. A local dashboard is available via trackfw serve.
• 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

---

Compared to alternatives

Tool	What it does	What's missing
adr-tools	Creates ADR files	No link to requirements or roadmaps
madr	ADR template format	No enforcement, no delivery tracking
Linear / Jira	Task tracking	No traceability to architectural decisions
Kosli	SDLC compliance for regulated industries	SaaS, accounts, cost — not for every team
trackfw	Enforces the full chain: decision → requirement → roadmap → delivery	—

trackfw is the only open-source CLI that links ADRs to requirements, requirements to roadmaps, and enforces the chain as a pre-commit and CI gate — with native support for AI coding assistants.

---

Contributing

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.

---

License

MIT — see LICENSE