trackfw 0.2.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +301 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
# trackfw
|
|
2
|
+
|
|
3
|
+
> Governed software delivery — ADR → REQ → ROADMAP → backlog / wip / done
|
|
4
|
+
|
|
5
|
+
[](https://github.com/kgsaran/trackfw/releases/latest)
|
|
6
|
+
[](go.mod)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
9
|
+
**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.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## The problem
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
- **ADR tools** manage decision records, but don't connect them to delivery.
|
|
24
|
+
- **Kanban tools** track tasks, but don't enforce that tasks are backed by a decision.
|
|
25
|
+
- **CI tools** validate code, but don't validate governance.
|
|
26
|
+
|
|
27
|
+
trackfw closes the loop — connective tissue between *why*, *what*, and *when*.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Demo
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
$ trackfw req new "Login screen"
|
|
37
|
+
|
|
38
|
+
? Describe what you want to build Login screen for the application
|
|
39
|
+
? Motivation Users need to authenticate to access the system
|
|
40
|
+
|
|
41
|
+
Detected domains: authentication, ui
|
|
42
|
+
|
|
43
|
+
? How will users authenticate?
|
|
44
|
+
> Local login (email + password)
|
|
45
|
+
SSO (Google, Azure AD, Okta...)
|
|
46
|
+
Not decided yet ← generates ADR draft
|
|
47
|
+
|
|
48
|
+
? Is there an existing UI framework or design system?
|
|
49
|
+
Yes, already chosen
|
|
50
|
+
> No, need to choose a UI framework ← generates ADR draft
|
|
51
|
+
|
|
52
|
+
ADR drafts created:
|
|
53
|
+
→ ADR-2026-06-12-authentication-strategy.md
|
|
54
|
+
→ ADR-2026-06-12-ui-framework.md
|
|
55
|
+
|
|
56
|
+
Resolve these ADRs (set Status: Accepted) before creating a roadmap.
|
|
57
|
+
created docs/req/REQ-2026-06-12-login-screen.md
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Installation
|
|
63
|
+
|
|
64
|
+
### macOS / Linux — curl
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Homebrew
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
brew install kgsaran/tap/trackfw
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Go
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
go install github.com/kgsaran/trackfw/cmd/trackfw@latest
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### npm
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npm install -g trackfw
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### pip
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
pip install trackfw
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Quick start
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
# 1. Set up governance in your project (interactive wizard)
|
|
100
|
+
trackfw init
|
|
101
|
+
|
|
102
|
+
# 2. Document an architectural decision
|
|
103
|
+
trackfw adr new "Use PostgreSQL as primary database"
|
|
104
|
+
|
|
105
|
+
# 3. Create a requirement — wizard detects domains and proposes ADR drafts
|
|
106
|
+
trackfw req new "User authentication"
|
|
107
|
+
|
|
108
|
+
# 4. Once ADRs are accepted, plan the work
|
|
109
|
+
trackfw roadmap new "Auth service"
|
|
110
|
+
|
|
111
|
+
# 5. Check governance health
|
|
112
|
+
trackfw validate
|
|
113
|
+
|
|
114
|
+
# 6. See what is in flight
|
|
115
|
+
trackfw status
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Commands
|
|
121
|
+
|
|
122
|
+
| Command | Description |
|
|
123
|
+
|---|---|
|
|
124
|
+
| `trackfw init` | Interactive wizard — scaffolds governance + AI integrations |
|
|
125
|
+
| `trackfw adr new "title"` | Create a new Architecture Decision Record |
|
|
126
|
+
| `trackfw adr list` | List all ADRs with status |
|
|
127
|
+
| `trackfw req new "title"` | Create a REQ with guided ADR discovery |
|
|
128
|
+
| `trackfw req list` | List all REQs with status |
|
|
129
|
+
| `trackfw roadmap new "title"` | Create a roadmap in `backlog/` |
|
|
130
|
+
| `trackfw roadmap move <name> <state>` | Move roadmap between states |
|
|
131
|
+
| `trackfw roadmap list` | List all roadmaps grouped by state |
|
|
132
|
+
| `trackfw validate` | Check governance consistency (use as CI gate) |
|
|
133
|
+
| `trackfw status` | Show wip, blocked, REQs waiting on ADRs |
|
|
134
|
+
| `trackfw agents` | Install Claude Code subagents |
|
|
135
|
+
| `trackfw gemini` | Install Gemini CLI skills and commands |
|
|
136
|
+
| `trackfw cursor` | Install Cursor rules |
|
|
137
|
+
| `trackfw copilot` | Install GitHub Copilot instructions |
|
|
138
|
+
| `trackfw windsurf` | Install Windsurf rules and workflows |
|
|
139
|
+
| `trackfw amazonq` | Install Amazon Q Developer rules |
|
|
140
|
+
| `trackfw version` | Print version |
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Governance chain
|
|
145
|
+
|
|
146
|
+
| Layer | Artifact | Purpose |
|
|
147
|
+
|---|---|---|
|
|
148
|
+
| Decide | `ADR` | Document the *why* behind a technical decision |
|
|
149
|
+
| Specify | `REQ` | Define *what* needs to be delivered, linked to an ADR |
|
|
150
|
+
| Plan | `ROADMAP` | Break the requirement into microbatches with acceptance criteria |
|
|
151
|
+
| Execute | `backlog → wip → done` | Folder position is the source of truth |
|
|
152
|
+
|
|
153
|
+
### Roadmap states
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
docs/roadmaps/
|
|
157
|
+
├── backlog/ queued, not started
|
|
158
|
+
├── wip/ actively being worked on (one at a time)
|
|
159
|
+
├── blocked/ waiting on a dependency or decision
|
|
160
|
+
├── done/ completed and validated
|
|
161
|
+
└── abandoned/ discontinued — reason required in file
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Moving a file between folders **is** the state transition. No database, no API.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## REQ-driven ADR discovery
|
|
169
|
+
|
|
170
|
+
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.
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
trackfw req new "checkout flow with payment integration"
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Detected domains: **persistence**, **api**, **events**
|
|
177
|
+
|
|
178
|
+
Questions asked:
|
|
179
|
+
- Which database engine will be used? → *Not decided yet* → `ADR: database-engine (Draft)`
|
|
180
|
+
- Which API protocol will be used? → *REST (already decided)* → no ADR
|
|
181
|
+
- Which event broker will be used? → *Not decided yet* → `ADR: event-broker (Draft)`
|
|
182
|
+
|
|
183
|
+
The REQ is linked to its blocking ADRs. `trackfw validate` enforces that no roadmap is created until every linked ADR reaches `Accepted` status.
|
|
184
|
+
|
|
185
|
+
This is the difference between experienced architects (who know which decisions to make) and everyone else — trackfw brings the architectural checklist to the requirement.
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## `trackfw validate` — governance gate
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
$ trackfw validate
|
|
193
|
+
|
|
194
|
+
✗ REQ-2026-06-12-login-screen.md is blocked by Draft ADR: ADR-authentication-strategy.md
|
|
195
|
+
✗ roadmap/wip/auth-service.md has no linked REQ
|
|
196
|
+
⚠ 2 roadmaps in wip/ (recommended: 1)
|
|
197
|
+
|
|
198
|
+
2 violation(s) found
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Designed to run as a **pre-commit hook** and a **CI quality gate**. `trackfw init` wires both automatically for your stack.
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## `trackfw status` — current state at a glance
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
$ trackfw status
|
|
209
|
+
|
|
210
|
+
── trackfw status ──────────────────────
|
|
211
|
+
|
|
212
|
+
🔄 WIP (1)
|
|
213
|
+
roadmap-auth-service.md
|
|
214
|
+
|
|
215
|
+
❌ Blocked (0)
|
|
216
|
+
|
|
217
|
+
⏳ REQs blocked by Draft ADRs (1)
|
|
218
|
+
REQ-2026-06-12-login-screen.md
|
|
219
|
+
→ ADR-2026-06-12-authentication-strategy.md (Draft)
|
|
220
|
+
|
|
221
|
+
✅ Done (last 5)
|
|
222
|
+
roadmap-user-profile.md
|
|
223
|
+
roadmap-db-setup.md
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## AI assistant integration
|
|
229
|
+
|
|
230
|
+
`trackfw init` asks which AI tools your team uses and installs native governance context for each. Commands can also be run independently.
|
|
231
|
+
|
|
232
|
+
| Command | Installs | Format |
|
|
233
|
+
|---|---|---|
|
|
234
|
+
| `trackfw agents` | 10 subagents in `~/.claude/agents/` | Claude Code `.md` with frontmatter |
|
|
235
|
+
| `trackfw gemini` | GEMINI.md + 10 skills + 3 commands | `~/.gemini/` + project root |
|
|
236
|
+
| `trackfw cursor` | 10 rules in `.cursor/rules/` | `.mdc` with YAML frontmatter |
|
|
237
|
+
| `trackfw copilot` | `copilot-instructions.md` + 10 instructions + 10 prompts | `.github/` |
|
|
238
|
+
| `trackfw windsurf` | 10 rules + workflows in `.windsurf/` + global rules | Appends to `~/.codeium/windsurf/memories/` |
|
|
239
|
+
| `trackfw amazonq` | 10 rules in `.amazonq/rules/` | Plain Markdown |
|
|
240
|
+
|
|
241
|
+
Each installer is idempotent — running it twice never overwrites your customizations.
|
|
242
|
+
|
|
243
|
+
The 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## `trackfw init` — stack-aware scaffolding
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
? Project type? Full-stack / Frontend / Backend / Governance only
|
|
251
|
+
? Frontend stack? React / Vue / Angular
|
|
252
|
+
? Backend stack? Go / Java / Node / Python
|
|
253
|
+
? Package manager? npm / pnpm / yarn / bun
|
|
254
|
+
? Git hooks? husky / lefthook / none
|
|
255
|
+
? CI system? GitHub Actions / GitLab CI / none
|
|
256
|
+
? Which AI assistants? Claude Code / Gemini CLI / Cursor / Copilot / Windsurf / Amazon Q
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
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.
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## Design principles
|
|
264
|
+
|
|
265
|
+
1. **Files are state** — folder position is the source of truth. No database, no lock-in.
|
|
266
|
+
2. **Traceability is mandatory** — `validate` is a gate, not a suggestion.
|
|
267
|
+
3. **Framework-agnostic, integration-aware** — governance never changes; generated artifacts adapt to your stack.
|
|
268
|
+
4. **One active roadmap at a time** — parallel work without traceability is the root of most delivery chaos.
|
|
269
|
+
5. **Human-readable, machine-parseable** — every artifact is a Markdown file with a predictable structure.
|
|
270
|
+
6. **Guided, not prescriptive** — the wizard surfaces decisions you might not know to ask; it never blocks work unnecessarily.
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## What trackfw is not
|
|
275
|
+
|
|
276
|
+
- Not a project management SaaS — no UI, no accounts, no cloud sync
|
|
277
|
+
- Not a replacement for Git history — it complements, not duplicates
|
|
278
|
+
- Not a task tracker — use GitHub Issues, Linear, or Jira for tasks; trackfw governs the *why*
|
|
279
|
+
- Not opinionated about how you write code — only about how you document decisions
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Contributing
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
git clone https://github.com/kgsaran/trackfw
|
|
287
|
+
cd trackfw
|
|
288
|
+
make build # compiles to bin/trackfw
|
|
289
|
+
make test # go test ./...
|
|
290
|
+
make lint # go vet ./...
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
Generators are the stack-specific components — you can add support for a new stack without touching core logic. See `internal/generators/` for examples.
|
|
294
|
+
|
|
295
|
+
Issues and pull requests welcome at [github.com/kgsaran/trackfw](https://github.com/kgsaran/trackfw).
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## License
|
|
300
|
+
|
|
301
|
+
MIT — see [LICENSE](LICENSE)
|