DLD Kit | Decision-Linked Development

Stop AI agents from breaking code they don't understand.

Code is full of choices that look odd without their reason: a retry tuned to one API's rate limits, a check for a bug that only shows up in production. The reasons live in tickets, chat threads and people's heads, where an agent can't find them. With Decision-Linked Development (DLD), you write each choice down as a short decision record and link it to the code with an @decision(DL-012) comment. When an agent sees that comment, it reads the decision before it changes the code.

Note

Coming from 0.x? 1.0 replaces the 0.x skills and scripts: see Upgrading from 0.x. The last 0.x release is v0.9.0.

DLD Kit is a set of Agent Skills for Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity and Copilot CLI, plus a small CLI that installs them.

Contents: Quickstart · How it works · Workflows · Skills · Install · Configuration · DLD and spec-driven development · CLI · Learn more

Quickstart

You need Node.js 22+ and git. In the root of your repository, run:

npx dld-kit init

init asks which agents your team uses, suggesting the ones it finds. It then writes dld.config.yaml, a decisions/ folder, the DLD skills and a short always-on rule that tells the agent to look decisions up (every file it writes). Commit the files; teammates don't need to install dld-kit. Start a new agent session so it loads the skills and the rule.

The commands below are Claude Code's slash commands. In Pi, use /skill:dld-decide. In other agents, ask for the skill by name: "use the dld-decide skill to record why the payment client retries with backoff".

Try it on code you already have

Pick a piece of code that looks odd without its reason, and record the reason:

/dld-decide the payment client retries with exponential backoff because the gateway returns 503s under load
/dld-implement DL-001

/dld-decide asks what it needs to know and writes decisions/records/DL-001.md as a proposed decision. /dld-implement finds that the code already does what the decision says, adds // @decision(DL-001) above it and marks the decision accepted. Commit, start a new session, and ask the agent for a change that goes against it, such as "retry the payment client at a fixed one-second interval". The agent reads DL-001 before it edits the code, and asks you before it goes against the decision.

Build a feature

/dld-plan add retries to the payment client
/dld-implement
/dld-snapshot

/dld-plan talks the feature through with you and records proposed decisions. /dld-implement writes the code, has it reviewed, and adds the @decision comments. /dld-snapshot regenerates OVERVIEW.md from the decisions.

To document a whole existing codebase, start with /dld-retrofit. To install DLD in your own agent setup rather than in the repository, see Install. Questions about cost, what runs in your repository, or how to stop using DLD: see the FAQ.

How it works

A decision is a markdown file in decisions/records/:

---
id: DL-012
title: "Use exponential backoff for payment gateway retries"
timestamp: 2026-02-15T09:20:00Z
status: accepted
tags: [payments]
references:
  - path: src/payments/gateway.ts
---

## Context
The gateway returns 503s under load. Fixed-interval retries made it worse.

## Decision
Exponential backoff with jitter, capped at 30 seconds, at most 5 attempts.

A full record also has Rationale and Consequences sections; see the decision record format. dld-kit records its own decisions this way: browse its decision log and the overview generated from it.

An annotation links code to the decision:

// @decision(DL-012)
function retryWithBackoff(fn: () => Promise<Response>): Promise<Response> {

The always-on rule is a short instruction installed for each agent: read the decision behind an annotation before changing that code. If a change would contradict it, the agent checks with you, and a new decision records the change.

• Merged decisions aren't rewritten. While a decision is only on your branch, edit it as much as you like. Once it's on the main branch (the base branch), you don't edit its reasoning: to change course, record a new decision that supersedes or amends it, so the history stays complete. The frontmatter (status, references, links, title) can always be updated; id and timestamp can't. decision_edits in the config can relax this. Statuses run proposed → accepted → superseded or deprecated.
• The docs are generated. /dld-snapshot builds OVERVIEW.md, and any documents you define in snapshot_artifacts, from the decisions. You never edit a spec by hand.
• Drift gets caught. /dld-audit finds annotations without a decision, references to files that no longer exist, and annotated code that changed.
• Conventions live in one file. An optional decisions/PRACTICES.md holds your testing, style and architecture conventions, and /dld-implement follows it.

DLD gives agents context, not guarantees. Keep your tests.

Workflows

• New feature: /dld-plan, then /dld-implement, then /dld-snapshot. /dld-adjust refines a decision before it's implemented.
• Small change: /dld-decide records one decision, then /dld-implement.
• Existing codebase: /dld-retrofit writes decisions and annotations for code you already have. Follow it with /dld-snapshot.
• Hands-off: after a one-time /dld-retrofit, run /dld-audit-auto and /dld-snapshot on a schedule or in CI. The audit finds changes to annotated code that no decision covers, records decisions for them and opens a PR, so nobody has to change how they work.
• Teams: two branches can pick the same DL-NNN. When the other one gets there first, run /dld-reindex. It renames your drafts to free IDs, updates everything that refers to them, and commits the renames on top of your branch.

More detail, with diagrams: workflows.

Skills

Skill	What it does
/dld-init	Set up DLD in a repository: config, decisions folder and always-on rule
/dld-plan	Break a feature into proposed decisions
/dld-decide	Record one decision
/dld-implement	Implement proposed decisions, with a review step
/dld-adjust	Change a decision, following the rules for its status
/dld-lookup	Find decisions by ID, tag, file or keyword
/dld-status	Summarize the decision log
/dld-audit	Find drift between decisions and code
/dld-audit-auto	Audit, fix and open a PR, for scheduled runs
/dld-snapshot	Generate OVERVIEW.md and your custom artifacts from the decisions
/dld-retrofit	Write decisions for existing code, broadly or in detail
/dld-reindex	Fix decision ID clashes with the base branch and open PRs

Install

Every option installs the same skills. You need Node.js 22+ and git. gh is optional: /dld-reindex uses it to check open PRs.

Which one to use

Not sure? Run npx dld-kit init in the repository and commit the result. It works for every supported agent except Copilot CLI, which uses the plugin, and teammates don't need to install dld-kit.

• Use npx dld-kit init if DLD is for a shared repository, the team uses more than one agent, or you want the setup reviewed and versioned with the code. This fits most projects, new or existing.
• Use the Claude Code plugin if you use Claude Code and want DLD in your own setup across many repositories, without committing skills to each one. Run /dld-init once per repository for the config and the rule.
• Use the Pi package, or the Codex or Copilot CLI plugin, for the same setup in those agents.
• Use npx skills or gh skill if you already manage your agents' skills with that tool. Then update with it, not with dld update.

Use one option per agent in each repository. If you commit skills with init and also install a plugin, the agent sees every skill twice.

Option	Agents	Install	Update
npx dld-kit init	Claude Code, Antigravity, Codex, Cursor, OpenCode, Pi	npx dld-kit init	npx dld-kit@latest update
Claude Code plugin	Claude Code	/plugin marketplace add jimutt/dld-kit, then /plugin install dld@dld-kit	claude plugin marketplace update dld-kit, then claude plugin update dld@dld-kit
Codex and Copilot CLI plugins	Codex, Copilot CLI	codex plugin marketplace add jimutt/dld-kit, then install dld from /plugins; copilot plugin marketplace add jimutt/dld-kit, then copilot plugin install dld@dld-kit	Codex's plugin manager; copilot plugin update
Pi package	Pi	pi install npm:dld-kit	pi update npm:dld-kit
npx skills / gh skill	Any agent those tools support	npx skills add jimutt/dld-kit; gh skill install jimutt/dld-kit --all	npx skills update; gh skill update
Manual copy	Any Agent Skills agent	Copy the dld-* folders from skills/	Copy again

With any option except init, run the dld-init skill once in each repository to create the config and install the rule.

See install details for where each agent keeps its skills and rule, how to combine options, and how to add the rule by hand.

Upgrading from 0.x

Your config, decisions, index and state carry over as they are. In the repository, run npx dld-kit@latest update --agent <names> (for example --agent claude,codex) and commit the result. It replaces the copied skills and their scripts, and installs the always-on rule. Then delete the old ## DLD (Decision-Linked Development) section from CLAUDE.md.

Tessl installs and skills copied to other folders need one more step first: see upgrading from 0.x.

Configuration

dld.config.yaml holds the settings. The ones you're most likely to change:

• mode: namespaced with a namespaces list gives each area of a monorepo its own decision folder (npx dld-kit init --namespaces billing,auth). IDs stay unique across namespaces.
• implement_review: false skips the review subagent in /dld-implement; plan_review: true adds one to /dld-plan. review_model picks the model the reviewers run on.
• dld.local.yaml, which isn't committed, holds your own review settings for a checkout, over the team's.
• snapshot_artifacts adds documents for /dld-snapshot to generate, each from a prompt you write.
• annotation_exclude lists paths whose @decision comments are only examples, such as docs.
• decision_edits sets whether agents may edit the prose of decisions already on the main branch: block (default), ask or allow.

All the options: project configuration.

DLD and spec-driven development

If your team uses a spec-driven tool such as Spec Kit, OpenSpec or Kiro and it works for you, switching isn't necessarily worth it. DLD differs in three ways:

• Decisions instead of a spec. You record each decision once and never rewrite it. Changing course is a new decision that supersedes or amends the old one, so the history of why the code looks the way it does stays complete.
• The current picture is generated. Most spec tools write a spec per feature or change, which then describes what was planned at the time. DLD builds the overview docs from the decisions in effect, the way event sourcing builds a read model from events.
• The context sits in the code. An annotation next to the code sends the agent straight to the reasoning, instead of leaving it to work out which spec applies.

More in the FAQ, and in the concept paper from DLD's early thinking.

CLI

Run npx dld-kit <command>, or npm install --global dld-kit for a dld command. The skills carry their own copy of the CLI, so they never need a global install.

Command	What it does
dld init	Set up DLD, the skills and the always-on rule
dld update	Update the installed skills and rule; --agent adds agents
dld install-rule --agent <names>	Install or refresh only the always-on rule
dld session-context --agent <name>	Print the rule for a session hook, unless the agent loads it already (used by the Claude Code plugin)
dld check-decision-edits	List edits to the prose of decisions already on the base branch; exits 3 under decision_edits: block, for a CI gate (details)

init and update won't overwrite files from a newer dld-kit unless you pass --force.

These five commands, with --help and --version, follow semantic versioning, as do the formats and names your project relies on: what a version number promises. The other commands in dld --help are internal to the skills and can change in a minor release, so don't script against them.

Learn more

• FAQ: cost, what runs in your repository, CI, stopping
• Decision record format and project configuration
• Install details, workflows and upgrading from 0.x
• Skill sources: what each skill does, step by step
• dld-kit's own decision log: a real one, with its overview
• The original early thinking, from before dld-kit was built: concept paper, TL;DR and FAQ
• Contributing and releasing

Ideas and bug reports are welcome: open an issue.

Acknowledgements

DLD builds on Architecture Decision Records, Embedded ADRs, Vibe ADR, OpenSpec, Spec Kit, IIC Kit, Kiro and event sourcing. See what each one contributed.

License

MIT