@imix-js/taproot

Taproot

AI-driven specs, enforced at commit time. Code without traceability doesn't merge.

AI coding agents generate code fast — but six months later, nobody knows why a module exists, who asked for it, or whether it's still needed. The requirement lived in a chat window. The chat window is gone.

Taproot keeps requirements as first-class files in your repo. The agent writes the spec, writes the code, and git refuses to accept one without the other.

• Single source of truth — Why → What → How, three layers, committed alongside code
• Every change traces back to a spec — no orphan code, no mystery modules
• Plan and backlog — prioritise, batch, and execute requirements autonomously or step-by-step
• Enforced at commit time — git hooks block code without traceability, failing tests, or incomplete specs
• Global truths — architecture rules, security constraints, and domain terms enforced at every commit

Quick Start

npx @imix-js/taproot init        # installs agent adapter + pre-commit hook

Then in your agent:

/tr-ineed user authentication    # describe a requirement → spec written + placed
/tr-implement taproot/auth/      # implement it: code + tests + traceability, committed

That's the loop. Spec first, code second, git enforces both.

Planning a batch of work:

/tr-plan                         # build a prioritised plan from backlog + unimplemented specs
/tr-plan-execute                 # run through it — autonomous items execute; HITL items pause for you

Describe ten requirements, review the plan, walk away. When you return, everything autonomous is done and the human decisions are waiting.

/tr-guide     ← onboarding walkthrough
/tr-status    ← health dashboard: coverage, orphans, stale specs
/tr-discover  ← reverse-engineer an existing codebase into taproot

Full workflow guide: docs/workflows.md

How enforcement works

taproot init installs a pre-commit hook. It runs automatically on every git commit — no commands to invoke:

Commit type	Gate	What it checks
Declaring a new impl (impl.md only)	DoR — Definition of Ready	Behaviour spec is specified; required sections present; custom conditions in settings.yaml
Committing source code	DoD — Definition of Done	Tests pass; all configured conditions resolved and recorded
Committing specs (intent.md, usecase.md)	Truth check	Staged specs are consistent with taproot/global-truths/

Code that fails these checks doesn't reach the repo.

Concepts

Already know what Intent, Behaviour, and Implementation mean? Jump to Why it matters ↓

Intent — the business goal behind a feature, written from a user perspective. Example: password-reset — Allow users to recover access to their account

Behaviour — one observable, testable thing the system does for a specific actor. Example: request-reset — User submits their email; system sends a reset link

Implementation — the code that satisfies a behaviour, with a traceable link back to the spec. Example: email-trigger/impl.md lists the source files and the commit that built them

Global truth — a project-wide fact enforced at every commit (business rule, entity definition, project convention), stored in taproot/global-truths/. Example: prices are always exclusive of VAT — a spec that contradicts this is blocked before it merges

Backlog — a lightweight scratchpad for ideas and deferred work captured mid-session, stored in taproot/agent/backlog.md — separate from the requirement hierarchy. Example: /tr-backlog "consider a caching layer" captures the thought without interrupting flow

Further reading

• Intent, Behaviour, Implementation — docs/concepts.md
• Global truths — taproot/global-truths/
• Backlog, DoR, DoD, sync-check — docs/workflows.md

Why it matters

• Ask "why does this code exist?" and get a structured answer — intent, actor, acceptance criteria — not a two-year-old git blame
• AI agents generate better code because they have the business goal alongside the technical context
• Requirements always show current state — when a spec changes, it's refined in place. No amendment chains, no "change request #4 layered on top of #3 layered on top of #2". The document is always the truth as it stands today.
• Changes are safer — trace any file back to its behaviour spec and understand what breaks if you touch it
• Nothing drifts silently — taproot sync-check flags source files modified after their spec was last reviewed
• Vague specs are caught at commit time — DoD/DoR gates block incomplete implementations before they merge

How requirements are stored:

taproot/
├── password-reset/        ← Intent: why this exists and for whom
│   ├── intent.md
│   └── request-reset/     ← Behaviour: what the system does
│       ├── usecase.md
│       └── email-trigger/ ← Implementation: how it's built
│           └── impl.md

Plain Markdown files, no database, git-versioned with your code. Any agent that can read files can use taproot.

Taproot tracks itself

Taproot's own requirements are managed with Taproot. taproot/OVERVIEW.md shows 18 intents, 53 behaviours, and 53 implementations — all complete — covering everything from validation rules to agent skill architecture to this README.

It's a working example of what a mature hierarchy looks like in practice.

Multi-repo projects

Taproot works across repository boundaries. If your system spans multiple repos — a platform repo plus plugin repos, a coordination repo plus service repos — you can define specs in one place and implement them independently in each repo.

A link file in the linking repo points to the spec that lives elsewhere:

# Link: Plugin Login

**Repo:** https://github.com/org/platform-repo
**Path:** taproot/specs/auth/plugin-login/usecase.md
**Type:** behaviour

Each repo's taproot coverage runs independently. The linking repo counts the behaviour as implemented via its local impl.md; the source repo marks it delegated. Both stay clean with no duplication.

Shared global truths (API contracts, domain models) work the same way — a truth link in taproot/global-truths/ is enforced at commit time, even when the truth file lives in another repo.

Use /tr-link to set up either side of the two-sided workflow interactively.

Full documentation: docs/cross-repo.md

Quality modules

Taproot ships three optional quality modules — installable skill packages that give agents the conventions and checklists needed for consistent, domain-appropriate implementations.

Module	Activation	What it captures
User experience	/tr-ux-define	10 UX aspects: orientation, flow, feedback, input, presentation, language, accessibility, adaptation, consistency, visual
Security	/tr-security-define	5 enforcement layers: coding rules, local tooling, CI/CD gates, deployment hardening, periodic review
Architecture	/tr-arch-define	7 structural aspects: interfaces, code reuse, dependencies, module boundaries, error handling, test structure, naming

Each module writes conventions to taproot/global-truths/ and wires an optional DoD condition so agents verify compliance at every implementation commit.

Opt in per project — declare which modules apply in taproot/settings.yaml, then run taproot update:

modules:
  - user-experience
  - security
  - architecture

Only declared module skills are installed. Undeclared modules have no effect.

Full documentation: docs/modules.md

Docs

• Workflows — common patterns: new feature, bug fix, onboarding, discovery
• Document types & examples
• CLI reference
• Agent setup & tiers
• Configuration & CI
• Patterns
• Cross-repo linking

License

MIT