Level 9Lesson 79⏱️ 45 min

LID - Linked Intent Development

A different flavor of SDD: make your whole codebase a chain where every line of code traces back to a single, stated intent - and a robot enforces it

A Different Bet Than BMAD

BMAD optimizes for building the next thing well with a team of agents. Linked Intent Development (LID), created by Jess Szmajda, optimizes for something else: keeping a project coherent over its whole lifetime. Its big idea is that your repository should be a graph rooted in intent - and that graph is provable.

The reframe LID makes: it doesn't call itself an "SDD methodology" so much as "a structured way to write the English your coding agent compiles." Your effort goes into design documents; the agent writes the specs, tests, and code from them.

The "Arrow": Everything Traces to Intent

LID's core is a chain it calls the arrow. Every piece of code is reachable, by name, walking up a ladder of intent:

        HLD  (High-Level Design - the WHY, the big direction)
         │
         ▼
        LLD  (Low-Level Design - the HOW for one component)
         │
         ▼
        EARS spec  (one atomic, checkable claim - Lesson 74!)
         │
         ▼
        failing-first test  (asserts the claim BEFORE code exists)
         │
         ▼
        code  (carries a matching @spec annotation)

Read it bottom-up: every code file → a test → a spec → a design → the HLD.
Nothing exists without a reason you can point to.
The problem it kills: intent gaps (Lesson 73). If every line of code must trace back to a stated intent, the agent can't quietly build something you didn't ask for - there'd be code with no spec above it, and the system would flag it.

Greppable Spec IDs: Intent You Can Search

LID gives every spec a short, searchable ID - like AUTH-UI-001. Code that implements it carries a matching @spec AUTH-UI-001 annotation, and the test for it references the same ID. Now the whole chain is navigable by name.

spec:   AUTH-UI-001  "WHEN login fails, show an error message."
test:   it('AUTH-UI-001: shows error on failed login', ...)
code:   // @spec AUTH-UI-001
        function showLoginError() { ... }

→ grep "AUTH-UI-001" and you instantly see the spec, its test,
  and its code. The intent is searchable across the whole repo.

The Robot That Enforces It: The CI Gate

Here's what makes LID more than a nice diagram. It ships a CI gate - an automated check that runs on every change and fails the build unless the arrow is intact:

The gate fails the build unless:
  • every spec is cited by at least one test, AND
  • every @spec citation in the code resolves to a real spec

So you literally cannot merge code that:
  - has no spec above it (unexplained code), or
  - cites a spec that doesn't exist (broken intent link)
This is Level 7 in disguise: the CI gate is the "objective, automated verifier" from loop engineering, pointed at traceability instead of behavior. The arrow isn't a guideline you hope people follow - it's mechanically enforced.

Tests Before Code (Failing-First)

Notice the order in the arrow: the test comes before the code. LID writes a test that fails first (because the feature doesn't exist yet), proving the test actually checks the claim. Only then does the agent write code to make it pass. This is classic test-driven development, now used to pin down intent, not just correctness.

Three Ways to Adopt It

Greenfield (new project)

Where LID shines - nothing to reconcile. You describe what you want; the workflow takes you through HLD → LLDs → EARS specs → tests → code, stopping for your approval at each phase.

Brownfield (existing code)

A /map-codebase command reads your existing code and works backward - inferring LLDs and a high-level design from what's there, then building the arrow over your current system and flagging what has drifted.

Scoped (one slice)

Pilot LID on a single subsystem. The discipline applies inside your scope and relaxes at the boundary, so you don't force it on teammates' code yet.

It even ships a coach: a /lid-coach skill reads your project and reports - advisory only, never editing - where your usage is drifting from the method. A nice way to learn the discipline on your own work.

BMAD vs. LID - When to Reach for Which

BMAD                              LID
team of role-based agents         a traceability graph + a gate
optimizes the NEXT feature        optimizes the project OVER TIME
great for: structure, governance, great for: provable "why does this
  agile flow, regulated audits      code exist?", long-lived systems,
                                     killing intent drift
heavier process, more roles       heavier discipline, enforced by CI

They're not rivals - some teams plan with BMAD and enforce
traceability with LID-style specs + tests.

Hands-On: Build One Arrow

Hands-on (15 min): Take one requirement from your app (reuse an EARS spec from Lesson 74). Now write the full arrow for it by hand: give it a greppable ID (e.g. TASK-ADD-001), write the one-line spec, write a failing-first test that references that ID, and sketch the code stub with a // @spec TASK-ADD-001 comment. You've just hand-built a single link of the chain LID enforces across an entire codebase - and felt why it makes intent impossible to lose.
Lesson 79 Quick Reference
LID

Linked Intent Development - make the whole repo a graph where every code file traces back to a stated intent

The arrow

HLD → LLD → EARS spec → failing-first test → code with @spec annotation

Greppable spec IDs

Short IDs like AUTH-UI-001 link spec, test, and code so intent is searchable across the repo

The CI gate

Fails the build unless every spec is cited by a test and every @spec citation resolves - enforced, not optional

Failing-first test

Write a test that fails before code exists, proving it really checks the claim, then make it pass

Adoption modes

Greenfield (new), brownfield (/map-codebase reverse-engineers the arrow), scoped (one subsystem)

BMAD vs LID

BMAD = agent team optimizing the next feature; LID = enforced traceability optimizing the project over time

← BMAD Part 3 - Build a Small App
Unlocks in ~12 min of reading