Linked-Intent Dev
Plate 00 / Intro For agentic coding

How do you know your agent built what you meant?

  1. Because you wrote it down — a design, in plain English.
  2. Because everything the agent builds comes from that design.
  3. Because you can check: one ID grep returns the requirement, its tests, and its code.
  4. Because LID helped you get there.

Code that runs can still miss what you meant. Somewhere in there, the agent made a judgment call you never saw — and by the next session, nobody remembers why. With LID (Linked-Intent Development), the design stays linked to everything built from it: fix it once, the agent cascades the change, and you sign off or push back at every step. You'd type these sentences into the chat anyway — LID keeps them where the next session can find them.

Install Read the source
Plate 01 / How it works

Design first. Everything below it cites an ID.

In a LID repo, every code file cites, by ID, the spec it implements; every test, the spec it asserts; every spec traces to a low-level design (LLD), and every design to the high-level design (HLD) at the top — one graph, rooted in your design docs. Checking that code still traces to design is a walk through that graph — mechanical enough to put in CI. Whether the design says what you mean stays your call. And green tests can't catch a misreading on their own: they may come from the same misreading as the code.

FIG · 001 Legend. The HLD names the why; the LLD shapes the how; a spec makes one atomic claim in structured English — one line, one greppable ID (the format is called EARS, Easy Approach to Requirements Syntax); a failing-first test asserts that claim before code exists; code carries matching @spec annotations. The IDs — AUTH-UI-001 and so on — make the graph navigable, and checkable, by name.
  1. § HLD the why
    The app is account-scoped — only the account owner can see or change their data. Every request has to identify the caller.
  2. § LLD the how
    Credentials enter at the login form, pass to the auth service, and resolve to one of two outcomes: a session scoped to the user, or a structured AuthError. The UI translates AuthError into a user-safe message; the session rides subsequent requests.
  3. § EARS the claim AUTH-UI-001
    When a user submits valid credentials, the authentication service shall return a session scoped to that user.
  4. § TESTS failing-first AUTH-UI-001
    test("returns a session on valid credentials") ▸ AUTH-UI-001 test("returns AuthError on invalid credentials") ▸ AUTH-UI-002
  5. § CODE @spec anchors AUTH-UI-001
    // services/auth.ts // @spec AUTH-UI-001, AUTH-UI-002 async function authenticate(credentials) { // ... }

A spec ID is a grep target: run grep -r AUTH-UI-001 and you get everything that cites it — the spec text, the failing-first tests asserting it, and the code implementing it. "This code does what the design says" stops being something you take on faith and becomes something you — or an auditing agent — can check.

Scale one every

That whole traced path — one thought, HLD down to code — is what LID calls an arrow. Now do that for every design, every spec, every test — all in the repo, next to the code. Your whole codebase looks like this:

LID arrows across the codebase — DAG A directed acyclic graph showing one HLD node fanning down through three LLD nodes, six EARS-spec nodes, six failing-first test nodes, and five code-file nodes. Two highlighted edges between tests and code cross or converge, illustrating that one test can cover more than one code file, and one code file can be covered by more than one test. PLATE · 002 / DAG ARROWS · CODEBASE COORD · A1 § HLD § LLDs § EARS § TESTS § CODE HLD LLD LLD LLD EARS EARS EARS EARS EARS EARS Tests Tests Tests Tests Tests Tests code code code code code
FIG · 002 Every arrow, for every piece of code. One HLD, many LLDs and specs, many tests, many files — one graph. Highlighted edges mark where one test covers more than one file, or one file is covered by more than one test.
In practice

It looks like a waterfall; it behaves like source code. Nothing here is a one-way phase: every level stays editable for the life of the project, and an edit at any level recompiles what's below it.

Your time goes into the design. The HLD and, more often, the LLDs — the agent drafts the specs, the tests, and most of the code, and your review lands on the deltas, stop by stop.

Almost every change is an LLD edit, cascaded. A new feature, a bug, a shift in direction — you edit the design. The linkage underneath lets you — or an audit pass, or a fresh agent with no context — verify that everything below still traces to what you wrote down. The demo below is that loop, live.

The price
  • Every change walks design → specs → tests → code; you review at each step before code lands.
  • More design diffs to read, fewer generated lines.
  • Extra agent tokens spent keeping the links current.

That's the trade — minutes of review per change, bought back as a codebase you can hand to any agent or teammate without a tour guide.

I run LID on everything I build — the largest is a public 63k-line Rust project, ~350 specs, with a CI gate that fails the build when a spec goes uncited — and these days it runs on plenty of projects that aren't mine.

Plate 02 / Demonstration

Watch one edit reach the code.

Change one sentence of the design and watch it arrive in the specs, the tests, and the code. Two minutes, one real project.

001CASCADE · LLD → SPECS → TESTS → CODE
Plate 03 / Teams

Alignment is a pull request.

When more than one person holds the intent, LID's artifacts turn design alignment into something your team already knows how to do.

docs/intent/checkout/checkout-design.md design review
## Cart retention - Carts expire after 30 days. + Signed-in carts expire after 90 days; + guest carts expire after 30 days.

maya does the 90-day window cover guest carts too?

sam no — guest carts get 30 days. split it in the diff.

resolved — merged; specs, tests, and code cascade from here

FIG · 003 The review that matters: one page of design, argued and settled before any code exists.
  1. The design conversation happens in the PR. Intent is files in the repo, so a teammate proposes a change to an HLD or LLD the same way they'd propose code. The deep conversation — what should the system be — happens on a one-page design diff before implementation, instead of halfway through a 500-line code review. Once the intent lands, anyone can cascade it to working code.
  2. The intent tree is your onboarding doc. Every design doc is written to be read cold, rationale on the page — exactly what a new teammate needs. The why stays in the repo after its author moves on.
  3. Mixed tools, one source of truth. The tree is plain markdown. One teammate on Claude Code, another on Cursor, a third in a JetBrains IDE — everyone reads and cascades the same intent. No per-tool lock-in.
  4. A sub-team can adopt alone. Scoped mode draws an explicit boundary around your service or subsystem; inside it you get the full discipline, and the rest of the org doesn't have to care yet.
  5. And at 3am, ship the fix. Hotfixes go out outside the workflow. When the fire's out, walk the change back through the design so the intent catches up. Nothing in LID gates a deploy.
Plate 04 / Quickstart

Four commands, inside Claude Code.

Install the two plugins, bootstrap your project. After that you describe what you want to build and the skill walks you through design, specs, and tests before it writes any code.

Using a different coding agent? Same workflow — most tools just need an AGENTS.md at your project root, some want one small rule file alongside. Pick yours:

Corporate environment blocks third-party plugins? Clone the repo directly — same plugins, same behavior.

  1. /plugin marketplace add jszmajda/lid

    Register the plugin source in Claude Code.

  2. /plugin install linked-intent-dev@jszmajda-lid

    Install the core workflow plugin.

  3. /plugin install arrow-maintenance@jszmajda-lid

    Install arrow-maintenance, which tracks the links between specs and code in projects too big for one context window.

  4. /linked-intent-dev

    Describe what you want to build. The workflow scaffolds the docs/ tree and CLAUDE.md as it walks you through the design.

Annex 04A / Experimental

Beyond the core: experimental skills.

The lid-experimental plugin bundles techniques that work in practice but aren't yet part of the core workflow. Right now it ships with bidirectional-differential, which checks whether your specs and your code still agree: two fresh AI sessions run in parallel — one writes naive code from your spec alone, the other reconstructs a spec from your code alone. Matches are evidence the two agree; differences point at drift worth investigating — unstated rules the code enforces, edge cases the spec misses, or genuine bugs.

Lifecycle is explicit — every experiment will either be promoted into core or retired. Adopt with eyes open. 

/plugin install lid-experimental@jszmajda-lid
Read the experimental plugin README
Annex 04B / Ecosystem

What people have built on it.

The core stays deliberately small; the day-to-day tooling comes from an independent, third-party ecosystem — editor plugins, language servers, CLIs, CI checkers, MCP servers. Discovery is an open convention: tag a repository linked-intent-development and link back, and it appears on the topic page — no submission, no gatekeeping.

Listed projects are independent and unvetted — evaluate any extension yourself before use.

Browse projects built on LID
Plate 05 / Entry points

Which path is yours?

Four starting points, depending on where you're coming from. Each one has a short orientation on the Start page.

01 / Path

Evaluating

Decide if LID solves a problem you have. Skim, browse an example, read on.

Orient 02 / Path

Starting new

Greenfield project. Install, describe what you want, let the skill walk you through it.

Begin 03 / Path

Existing codebase

Brownfield. Map the code first, then layer LID's discipline on top of what exists.

Map 04 / Path

Scoped to a subsystem

Solo trying LID on one slice of a larger non-LID project. Scoped mode is made for this.

Scope