lid-experimental

Linked-Intent Development

A structured design-before-code methodology for agentic coding. Stop building the wrong thing — get alignment on what before writing how. Works with any coding agent that reads per-project instructions.

Quickstart

Using Claude Code? Install the plugins — richest integration, auto-invoking skills, slash commands:

/plugin marketplace add jszmajda/lid
/plugin install linked-intent-dev@jszmajda-lid
/plugin install arrow-maintenance@jszmajda-lid
/linked-intent-dev:lid-setup

Optional: the lid-experimental plugin adds opt-in skills that aren't part of the core workflow but layer on top of it. Currently includes bidirectional-differential for auditing EARS↔code coherence on a chosen scope. See plugins/lid-experimental/README.md for what's in it and how to use it. Install separately:

/plugin install lid-experimental@jszmajda-lid

Using Cursor, Windsurf, GitHub Copilot, Aider, Continue, Junie, Codex, Zed, or other tools? Drop a small rule file into your project that points the agent at an AGENTS.md. Copy-paste snippets for each tool are in docs/setup.md.

Then just describe what you want to build. The methodology handles the rest. For existing codebases, see Getting Started: Brownfield Project.

LID uses LID on itself. This repo is the canonical mature-project example — its own HLD, LLDs, EARS specs, and evals are in docs/ and plugins/*/skills/*/evals/. If you want to see what LID-at-rest looks like on a real codebase, read the docs here. For a small, intent-only demo (HLD + LLDs + specs, no code — meant to be given to an agent to regenerate), see examples/urlshort/.

The Problem

Modern AI coding agents don't really write bugs anymore. What they write are intent gaps — places where the agent assumed you meant something different than you did. The biggest challenge in agentic development isn't getting code to work; it's making sure the agent builds the right thing.

This gets worse as systems grow. Every new session starts a capable but amnesiac programmer from scratch. Context windows help, but there's always a gap between what's in your head and what's in the agent's context. That gap is where intent drifts, and intent drift is where projects go sideways.

The Arrow of Intent

The solution is to make intent explicit and traceable. There's a chain of documents that translates what you want into working software:

HLD → LLDs → EARS → Tests → Code

Each level translates the previous into more specific terms. They aren't independent documents — they're a single expression of intent at different levels of specificity. When you change your mind about something, the change flows downstream through the chain: update the design, then the specs, then the tests, then the code. Never the reverse.

This is the "arrow of intent." It means you don't ask the agent to "fix the bug" — you ask it to "update the arrow so this behavior is clearly specified, tested, and implemented." The documentation becomes the source of truth, not the code. Code is output. Intent is the artifact you maintain.

For more background, see The Arrow of Intent.

How LID Differs from Other SDD Systems

Several spec-driven development (SDD) systems exist for agentic coding. They all share the insight that you should specify before you code. Where LID differs is in what happens after.

Most SDD systems are optimized for the next change: generate specs, plan tasks, implement, ship. The artifacts are scaffolding for delivery. Some have extensions for detecting drift or updating specs post-implementation, but the core workflow is a pipeline that ends at "done."

LID is optimized for the project over time. The design documents aren't scaffolding — they're the system's source of truth. Done well, you should be able to delete all tests and code and regenerate them from the HLD, LLDs, and EARS specs alone. That's the bar. If you can't, there's an intent gap somewhere, and closing it is the work.

	Typical SDD	LID
Primary goal	Clear intent for the next change	Continuous truth for the whole project
Design docs after implementation	Reference material, may drift	The living source of truth — always current
When specs and code disagree	Sync them up (which direction?)	Specs win. Fix the code, or fix the spec and cascade.
Tests and code	The artifact you maintain	Output. Regenerable from intent.
Scope	Per-feature or per-change	Per-project, tracked across all components