https://github.com/helderberto/tracerkit
Spec-driven development workflow for AI agents - PRD, plan, check.
https://github.com/helderberto/tracerkit
ai claude-code context-engineering engineering prd sdd sdlc spec-driven-development spec-planning specification tracerkit
Last synced: 8 days ago
JSON representation
Spec-driven development workflow for AI agents - PRD, plan, check.
- Host: GitHub
- URL: https://github.com/helderberto/tracerkit
- Owner: helderberto
- License: mit
- Created: 2026-03-31T15:19:24.000Z (17 days ago)
- Default Branch: main
- Last Pushed: 2026-04-02T16:59:53.000Z (15 days ago)
- Last Synced: 2026-04-03T08:32:35.344Z (14 days ago)
- Topics: ai, claude-code, context-engineering, engineering, prd, sdd, sdlc, spec-driven-development, spec-planning, specification, tracerkit
- Language: TypeScript
- Homepage:
- Size: 11.6 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/helderberto/tracerkit/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/tracerkit)
[](https://www.npmjs.com/package/tracerkit)
[](https://opensource.org/licenses/MIT)
Replace ad-hoc AI prompts with a repeatable spec-driven workflow: from idea to verified, archived spec.
Named after the tracer-bullet technique from _The Pragmatic Programmer_: **Tracer** + **Kit**.
**Markdown skills, zero runtime deps.** No build step, no project dependencies.
## Why TracerKit?
AI assistants work best with small, well-scoped tasks — not sprawling layers or flat task lists. TracerKit structures every feature as **tracer-bullet vertical slices**: each phase cuts through every layer (schema → service → API → UI → tests) and is demoable on its own. Integration problems surface early, not at the end.
The workflow is three skills: **define** (`/tk:prd`), **plan** (`/tk:plan`), **verify** (`/tk:check`). Skills are pure Markdown with zero runtime deps — the AI reads your specs directly, counts progress, and archives completed work. No build step, no CLI at runtime.
## Get Started
### Install
```bash
$ npm install -g tracerkit
$ tracerkit init
```
Skills are installed to `~/.claude/skills/`, available in every project. Safe to re-run — adds missing skills without overwriting ones you've modified.
### Workflow
```
You: /tk:prd add dark mode support
AI: Written .tracerkit/prds/dark-mode-support.md
Run `/tk:plan dark-mode-support` next?
You: /tk:plan dark-mode-support
AI: Phase 1 — Theme visible end-to-end
Phase 2 — User can toggle and persist preference
Written .tracerkit/plans/dark-mode-support.md
Run `/tk:check dark-mode-support` when ready?
You: # open the plan, implement each phase, write tests...
You: /tk:check dark-mode-support
AI: Status: done | Total: 5/5
Archived to .tracerkit/archives/dark-mode-support/
```
Use `/tk:brief` at the start of any session to see active features and pick up where you left off:
```
You: /tk:brief
AI: | Feature | Status | Age | Progress | Next |
|-------------------|-------------|-----|----------|------------------------------|
| dark-mode-support | in_progress | 3d | 3/7 | Toggle component renders ... |
**Focus → dark-mode-support**
```
See [Examples](docs/examples.md) for full walkthroughs.
Per-project usage
To scope skills to a single project (team members get them via git):
```bash
$ tracerkit init . # install to .claude/skills/ in current dir
$ tracerkit update . # update project-scoped skills
$ tracerkit uninstall . # remove project-scoped skills
```
## Skills
TracerKit ships skills that take a feature from idea to verified archive.
### `/tk:prd `: Write a PRD
Interactive interview that explores your codebase, asks scoping questions one at a time, designs deep modules, and writes a structured PRD.
**Output:** `.tracerkit/prds/.md`
### `/tk:plan `: Create an implementation plan
Reads a PRD and breaks it into phased **tracer-bullet vertical slices**. Each phase is a thin but complete path through every layer (schema, service, API, UI, tests), demoable on its own.
**Output:** `.tracerkit/plans/.md`
### `/tk:brief`: Session briefing
Shows active features, their progress, and suggested focus. Use at the start of a session to orient.
**Output:** Feature dashboard in the terminal — no files written.
### `/tk:check [slug]`: Verify and archive
Verifies the codebase against the plan's done-when checkboxes. Runs tests, validates user stories, updates phase progress, and transitions the PRD status. On `done`, archives the PRD and plan to `.tracerkit/archives//` automatically.
Without arguments, shows a feature dashboard with status and progress before asking which feature to check.
**Output:** Verdict block in `.tracerkit/plans/.md`. On `done`: `.tracerkit/archives//prd.md` + `.tracerkit/archives//plan.md`
## Docs
| Document | Description |
| ------------------------------------------------ | -------------------------------------------------- |
| [Examples](docs/examples.md) | Walk through end-to-end usage scenarios |
| [CLI Reference](docs/cli-reference.md) | Lifecycle commands: init, update, uninstall |
| [Configuration](docs/configuration.md) | Configure custom artifact paths via `config.json` |
| [Metadata Lifecycle](docs/metadata-lifecycle.md) | Understand YAML frontmatter states and transitions |
| [Comparison](docs/comparison.md) | Compare TracerKit to Spec Kit, Kiro, and OpenSpec |
## Contributing
1. Fork the repo and create a feature branch
2. Use TracerKit itself to plan your change (`/tk:prd` + `/tk:plan`)
3. Implement following the plan phases
4. `npm run lint:fix && npm run test:run && npm run typecheck`
5. [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitlint)
6. Open a PR against `main`
## Support
For support, please [open a GitHub issue](https://github.com/helderberto/tracerkit/issues). We welcome bug reports, feature requests, and questions.
## Acknowledgments
This project was born out of [Claude Code for Real Engineers](https://www.aihero.dev/cohorts/claude-code-for-real-engineers-2026-04), a cohort by [Matt Pocock](https://github.com/mattpocock). The hands-on approach to building real things with Claude Code sparked the idea for TracerKit. If you're serious about AI-assisted engineering, I can't recommend Matt's cohorts and content highly enough.
## License
[MIT License](LICENSE) © [helderberto](https://helderberto.com)