Linked-Intent Dev· v0.1
Plate 00 / Intro For agentic coding

How to write code when your compiler speaks English.

  1. LID is the language.
  2. Your agent is the compiler.
  3. Code is the output.

Modern coding agents write code that runs. What they miss is what you meant — the agent assumed one thing, you had another in mind, and the next session starts over with no memory of why. LID closes that gap: you put the design down in plain English, the agent compiles specs, tests, and code from it — and when something's off, you fix the design once and everything downstream rewrites itself to match.

Install Read the source
Plate 01 / How it works

You design. The agent writes the rest.

LID treats your whole repository as a graph rooted in intent. Every code file reachable, by name, from a test; every test from a spec; every spec from a low-level design (LLD); every design from the high-level design (HLD) at the top. Checking that the code still matches the design is just a walk through the graph — and when an agent writes most of the code, that's the difference between taking what landed on faith and being able to check it.

  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) { // ... }

Every implementation file carries @spec comments pointing back at the EARS claims it satisfies. 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. That's more than navigation; it's how the work gets verified: "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, and every test in your repository — not in a binder somewhere, in the code itself. 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

The diagram reads top-down, but 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. It looks like a waterfall; it behaves like source code. You spend your time in the HLD and, more often, in the LLDs. That's where the design work lives. The agent handles the specs, the tests, and most of the code from your design — you read, you nod, you move on. Your review lands on intent and the deltas the agent proposes; the linkage underneath is what lets you — or an audit pass, or a fresh agent with no context — verify that everything below still traces to what you meant. When something needs to change — a new feature, a bug, a shift in direction — you almost always go back to an LLD, edit it, and let everything built on the old answer rewrite itself to match the new one. The demo below is what that loop looks like live.

The price

None of this is free, and it's worth saying plainly: every change walks design → specs → tests → code, and you review at each step before code lands. You'll read more design diffs and fewer generated lines, and the agent spends extra tokens 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 any teammate, without a tour guide.

Plate 02 / Demonstration

See the cascade.

The most persuasive thing about LID isn't the prose — it's watching intent propagate. Describe a change in English. The agent updates the LLD, cascades through the specs, regenerates the tests, and rewrites 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 — the one about what the system should be — happens on a one-page design diff, before implementation, instead of surfacing halfway through a 500-line code review. Once the intent lands, anyone on the team 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 — which is exactly what a new teammate needs. The why travels with the repo, not with whoever wrote it.
  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. LID is a source-of-truth discipline, not a deployment gate.
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 the arrow-maintenance overlay for spec-to-code coherence audits.

  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 have earned their place but aren't yet promoted into the core workflow. Right now it ships with bidirectional-differential — a way to check whether your specs and your code still agree on what the system does. It runs two fresh AI sessions in parallel: one writes naive code from your spec alone; the other reconstructs a spec from your code alone. When both reconstructions match what you already have, intent and implementation are coherent. When they don't, the differences point at drift worth investigating — unstated rules the code enforces, edge cases the spec doesn't pin down, 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

Built on LID.

The core stays deliberately small, so the tooling that makes LID pleasant day to day comes from an independent, third-party ecosystem — editor plugins, language servers, CLIs, CI coherence checkers, MCP servers. Discovery is by 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 — surfaced, not vetted or endorsed. 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