अनुबंध — Anubandh

The constitution engine for AI-speed software

AI writes code faster than humans can read it. Anubandh binds every piece of code to the prose that explains it — by hash, not by good intentions. When either side changes, the other must follow. CI enforces it.

⚡ Quick start

# Install
npm install -g anubandh    # or: pnpm add -g anubandh

# 1. Add an anchor to any markdown doc
#    ## Upload validation {#spec:vault.upload.validation}
#    Max file size is 25 MB. Rejection must state the limit.

# 2. Mark the code that honors it
#    /** @spec vault.upload.validation */
#    export function validateUpload(file) { ... }

# 3. Record the agreement
anu map

# 4. Check for drift (CI gate)
anu check

# 5. When the doc changes first, get a work order
anu plan vault.upload.validation

That's it. Docs lead, code follows, CI enforces. No server, no config, works with any agent.

| Command | What it does | |---|---| | anu map | Hash both sides into anubandh.lock — the act of consent | | anu check | Report drift; exit 1 on violations (the CI gate) | | anu check --changed | Fast mode — only re-scan files that changed since last commit | | anu accept <id> --reason "why" | Consciously carry a violation (content-bound, expiring) | | anu plan <id> | Compile a work order for your coding agent | | anu coverage | Report what % of public symbols are governed by a clause | | anu human | Compile the tasks only a human can do (API keys, sign-offs) |

Zero-pollution option: Don't want @spec in your source? Use anumap.yaml to declare bindings externally.

🧬 The formula

Karpathy's LLM Wiki + Garry's 23 Engineers + Google OKF + OpenWiki = अनुबंध

Four famous pieces. Each proved half the future. Each is missing the same thing:

| The hero | What it proved | What it's missing | |---|---|---| | 🧠 Karpathy's LLM Wiki (~5K forks) | An LLM should maintain a compounding wiki, not RAG-and-forget | Nothing keeps the wiki honest against the code | | 👥 Garry's 23 Engineers / gstack (~90K ⭐) | Prompts-as-personas can replace a whole eng team | The personas aren't bound to repo state | | 📚 Google OKF (v0.1) | Knowledge = interlinked markdown + frontmatter, agent-readable | No drift-checking — the standard trusts you | | 🔄 LangChain OpenWiki (~12K ⭐) | The LLM wiki, productized: daily git-diff refresh | Freshness by regeneration, zero verification — code leads, docs follow |

Anubandh is the missing thing itself: a mechanical binding between prose and code. Stable anchors link doc sections to code symbols, a lockfile hashes both sides, CI fails on drift — and changes flow both directions: code changes force doc updates, and editing the doc generates code changes (via your coding agent, constrained by your ADRs).

OpenWiki keeps the wiki fresh. Anubandh keeps it honest — and lets it lead.

🧩 The riddle we're solving

Agents create code faster than any human can. Writing is no longer the constraint — English is the working language now: the highest-bandwidth format humans have, and the format LLMs reason over best.

But writing was never the whole lifecycle. In the AI development lifecycle (AIDLC), everything after generation still runs at human speed:

| 🚧 The human-speed wall | The question nobody can answer at AI speed | |---|---| | ✅ Verification | Is this what we meant? | | 🧪 Testing | Which requirement does this test prove? | | 🛡️ Keeping it working | Did the refactor silently drop the security rule? | | 🗂️ Managing | Who builds what, in what order? | | 📊 Tracking | How done are we — really? |

That's the break in AIDLC: code arrives at machine speed and piles up against a human-speed wall of trust.

💥 The problem, concretely

It shows up as 22 named dev-speed problems across four fronts — a taste:

| Front | The pain you already know | |---|---| | 🤝 Understanding & Trust | One stale doc burns one engineer; the whole team stops reading docs forever. Agents produce 3,000-line PRs reviewed by skimming and vibes. | | 🛡️ Correctness & Safety | The constant-time comparison, the rate limit, the redaction call — removed by an agent that didn't know why it was there. Agents confidently import packages that don't exist. | | 🔀 Coordination & Flow | README says X, wiki says Y, Notion says Z, a comment says W. "How done is the project?" answered by feelings. | | 💸 Knowledge Economics | Every agent session re-derives the architecture from raw code — orgs pay for the same 50–200k tokens of exploration thousands of times. A senior leaves; their mental model leaves with them. |

Anubandh's answer — Constitution-Driven Development (CDD): if English is the language of work, make English mechanically binding. Then trust becomes computation:

• 🔍 Drift is detected by hash, not by review vibes
• ✅ "Done" is a hash match, not an opinion
• 🧪 Tests are bound to the claims they prove — a claim without a test is flagged
• 📊 Progress is derived from the repo, never manually synced
• 🗂️ The project board is a lens over git — delete the server, lose nothing

💡 The solution, in one paragraph

The bottleneck of software is no longer writing code — agents do that at machine speed. The bottleneck is human understanding per unit of code. Prose is the highest-bandwidth format humans have and the format LLMs reason over best, but today docs are decorative: nothing mechanically binds them to code, so they rot, trust dies, and humans fall back to reading diffs at human speed. Anubandh makes the binding mechanical: stable anchors link doc sections to code symbols, a lockfile hashes both sides, CI fails on drift, and changes flow both directions — code changes force doc updates, and editing the doc generates code changes (via your coding agent, constrained by your ADRs). Docs become the source of truth humans can actually operate at AI speed.

⚖️ How it works — the constitution

The prose is the constitution. The code is bound to it. Authority flows downward and is mechanically enforced:

• 📜 The spec is the constitution. Each anchor is one clause; the lockfile is the signed contract between a clause and the code that honors it.
• 📋 ADRs are the amendments. Binding decisions, append-only — superseded, never silently edited.
• ⚖️ Drift is unconstitutional, and CI is the court. Code that changes meaning without honoring its clause fails the gate; a clause that changes ahead of code becomes a work order.
• 🤖 Agents are bound by it too. Machine-speed development still obeys the document humans actually read.
• 🧪 Tests are part of the contract. A test carrying @spec proves a clause; an anchor without a bound test is flagged.

One clause, in a doc:

## Upload validation {#spec:vault.upload.validation}

Max file size is 25 MB. Rejection must state the limit.
Allowed types: pdf, jpg, png. Type is verified by magic bytes, never extension.

The code that honors it:

/** @spec vault.upload.validation */
export function validateUpload(file: UploadCandidate): ValidationResult {
  // ...
}

The contract between them — anubandh.lock — hashes both sides. Then:

$ anu check
✅ vault.upload.validation      in sync
🔵 billing.invoice.gst-rounding doc-ahead   → work order: implementation owes performance
🟠 sharing.link.expiry          code-ahead  → VIOLATION: code changed meaning, doc did not follow

exit 1  ← CI fails. The constitution is enforced, not suggested.

The eight drift states

| State | Meaning | Consequence | |---|---|---| | ✅ in-sync | prose and code agree, hash-verified | peace | | 🟣 planned | clause written, no code yet | the backlog, derived from the repo | | 🟡 in-progress | claimed on a branch | live "who builds what" map, from git | | 🔵 doc-ahead | the clause changed first | a work order — feed it to your agent | | 🟠 code-ahead | code changed meaning silently | a violation — fails CI | | 🔴 broken | bound symbol or test vanished | the alarm | | ⚪ unanchored | public code no clause governs | the coverage gap, measured | | ⚫ deprecated | tombstoned, history preserved | the archive |

The asymmetry between 🔵 and 🟠 is the whole point: the constitution leads; the implementation answers.

flowchart LR
    D["📜 Doc clause<br>{#spec:vault.upload.validation}"] ---|anubandh.lock<br>hashes both sides| C["⌨️ Code symbol<br>@spec vault.upload.validation"]
    C -->|meaning changed,<br>doc didn't| V["🟠 code-ahead<br>CI FAILS"]
    D -->|clause edited<br>first| W["🔵 doc-ahead<br>work order"]
    W -->|"anu plan → your agent<br>(constrained by ADRs)"| PR["🔀 PR restores"]
    V -->|doc update or<br>expiring waiver| PR
    PR --> S["✅ in sync"]

🪷 The name: Anubandh (अनुबंध)

The name carries the product three times over:

1. 🤝 Modern Hindi: अनुबंध = contract / agreement / bond. That is literally what anubandh.lock is — a contract between the docs and the code. The mapping is exact:

   | Contract concept | Anubandh mechanism | |---|---| | A clause | An anchor — one binding claim about behavior | | Signing | anu map — both parties hashed into the lockfile | | Breach | 🟠 code-ahead drift | | Renegotiation | 🔵 doc-ahead — implementation owes performance | | A recorded amendment | A waiver (anu accept --reason) — visible, expiring, content-bound | | An expired clause | ⚫ tombstone | | The audit | anu check --json — every clause, hash-verified, machine-readable |

2. 🕉️ Pāṇini's Sanskrit grammar: an anubandha is the world's first annotation. In the Aṣṭādhyāyī (~5th century BCE — the first formal grammar in history, routinely compared to a programming language), an anubandha is a marker letter attached to a grammatical element: it carries metadata about how that element behaves, drives the rules that process it, and is elided from the final surface form. That is, character for character, what an @spec marker is. Formal systems needed bound metadata 2,500 years ago — we're restoring it to the newest formal system: software written in English.

3. 🧵 Etymology: anu- (along, after) + bandha (binding, from √bandh, to tie). "That which binds along" — documentation bound alongside code, traveling with it, never allowed to fall behind.

The CLI ships as anu — three keystrokes. Shipped today: anu map, anu check, anu plan, anu accept, anu coverage, anu human. Coming: anu serve (the wiki).

🚀 What's coming (building in the open)

The engine's first slice is real, and it passes its own gate. anu map → anu check runs on this repository today: 26 clauses in docs/anchor-spec.md, 38 bound symbols, 26/26 in sync, exit 0 — Anubandh's first user is Anubandh. 153 tests cover each rule of the state machine by name. What is not built yet is listed below and in the spec's Deferred table, named rather than implied.

| | Feature | What it does | |---|---|---| | ✅ F-1 | anu CLI core | anchors → anubandh.lock → anu check → anu plan · the gate, shipped | | 🪝 F-1.5 | anu backfill | existing docs + existing code → bindings, deterministically; LLM only touches the review pile, never invents a binding | | 🏗️ F-1.6 | anu adopt | brownfield on-ramp: inventory scattered prose → migrate into a standard docs tree → draft missing docs from the symbol graph → human ratifies (generated docs are proposals, never constitution) — ingests existing openwiki/ OKF bundles directly | | ✅ F-1.7 | anu human | shipped — human.todo.txt: every task only a human can do (API keys, sign-offs, filings), each with what-to-do and a verify condition, so done is checked, not ticked | | 🧰 F-1.8 | anu init | scaffolds the docs constitution and the stack's toolchain — formatter, linter, type-checker, tests, one gate command, git hook — so nobody re-derives best practice per project | | 📖 F-2 | anu serve | the writable LLM wiki: files are the only truth, live drift badges, backlinks, dual rendering — every page has a "what does my agent see?" mode — and @tag aggregated views (@sec = the entire security story, assembled) | | 🤖 | Agent layer | 7 MCP tools; verifySymbol kills API hallucination before the agent builds on it; verified context packs (1–3k tokens replacing 50–200k of cold-start exploration, stamped with whether prose matches code right now) | | 🎛️ | Orchestrator | a kanban that is a lens, never a database: computed columns you cannot drag into (Done is earned), drag = git operation, drop a card = launch an agent in an isolated worktree | | 🧑‍🎨 | Requirements Studio | author features by conversation with specialist lenses (the gstack idea, bound to repo state) — output is an anchored feature doc, not a transcript |

Start any project with it — the Architect lens asks scale/team/deploy at project birth, recommends monorepo · modular monolith · microservices · combination, and scaffolds the full docs constitution (46 battle-tested templates) as the project's own ADR-0001. Already have a project? anu adopt → anu backfill → anu check.

🥊 Why not just…

| | Docs honest against code? | Docs drive code? | Tests bound to claims? | Survives tool deletion? | |---|---|---|---|---| | Anubandh | ✅ hash-verified, CI-gated | ✅ doc-ahead work orders | ✅ acceptance chain | ✅ plain md + git | | OpenWiki / DeepWiki | ⚠️ LLM re-writes daily — unverified | ❌ code leads, always | ❌ | ✅ | | Confluence / Notion | ❌ rots silently | ❌ | ❌ | ❌ their database | | Jira / Linear | n/a — status is opinions, manually synced | ❌ | ❌ | ❌ their database | | CLAUDE.md alone | ❌ can't label its own staleness | ❌ | ❌ | ✅ |

Everything degrades gracefully: every file stays valid markdown and valid source without Anubandh — better with it. The agent is replaceable; the format isn't.

📖 Origin story

Anubandh was extracted from practice, not invented in the abstract. Building Kagaz — a compliance-heavy, doc-driven, agent-built app handling Aadhaar/PAN-grade PII — we hand-rolled all of this: a checklist binding every feature to its spec/security/legal docs, commit hashes next to completed items, gate tags ([SEC], [LEGAL]) forcing agents to read governing docs before coding, per-page .skill.md files agents read instead of source, ADRs constraining what agents may change. It worked — and every piece was manual, fragile, convention-only. Anubandh is that system, mechanized into a paradigm anyone can adopt.

🗺️ This repository

| Path | What's in it | |---|---| | docs/anchor-spec.md | 📜 The constitution — anchor syntax, hashing, the lockfile schema, the drift-state machine. The document anu implements | | FEATURES.md | The feature ledger — every decision, dated. Chat shapes things; this file is where they survive | | DEVELOPMENT-CHECKLIST.md | The living index of work: status, gate, Definition of Done, commit journal | | src/ · tests/ | The engine — scanners, hashing, lockfile, state machine, CLI (TypeScript, 153 tests) | | feature-anubandh.md | 41 extracted keeper features (X-1…X-41) + the spike state discovery | | skills/anubandh/ | 📦 The first docs-pack: the Kagaz doc architecture as an installable Agent Skill — 5 references + 46 header-skeleton templates. Also our own build guide | | research/ | OpenWiki analysis, Harness/Backstage integration research | | vendor/gstack/ | gstack (MIT, vendored) — source material for the persona packs |

Concept authority now lives in this repo: docs/anchor-spec.md is the constitution, FEATURES.md the dated decision record. Reading order — founders: README → FEATURES · engineers: anchor-spec → FEATURES F-1.

⭐ Star the repo and watch the constitution get built

The bottleneck of software is no longer writing code.It's human understanding per unit of code. That's the product.

अनुबंध — "that which binds along."