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

1.0 is in release candidates (1.0.0-rc.N). The install steps below get the latest candidate, which replaces the 0.x skills and scripts. Commands, file formats and skills may still change before 1.0.0. Coming from 0.x? 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 20+ 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. Commit the files; teammates don't need to install dld-kit.

Then, in your agent:

/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 and SNAPSHOT.md from the decisions.

These are Claude Code's slash commands. In Pi, use /skill:dld-plan. In other agents, ask for the skill by name: "use the dld-plan skill to plan retries for the payment client".

For a small, one-off choice, /dld-decide records a single decision. For an existing codebase, start with /dld-retrofit. To install DLD in your own agent setup rather than in the repository, see Install.

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.

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, 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 SNAPSHOT.md 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

Install

Every option installs the same skills. You need Node.js 20+ 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.

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.
• 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

Spec-driven tools such as Spec Kit, OpenSpec and Kiro work well, especially for new projects. If they fit your team, use them. DLD is for long-lived code, where specs tend to go stale:

• Decisions instead of a spec. You record each decision once and never rewrite it, so the history of why the code looks the way it does stays complete.
• The spec is generated. The overview docs are built from the decisions, 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.

More in the FAQ and the concept paper.

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.

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

These four commands, with their flags, exit codes and documented output, follow semantic versioning, as do --help and --version. The other commands in dld --help (next-id, create-decision, regenerate-index and so on) are internal: the skills run them from their bundled copy, and they can change in a minor release. Don't script against them.

Learn more

• Concept paper: the full reasoning behind DLD
• TL;DR and FAQ
• Decision record format and project configuration
• Install details, workflows and upgrading from 0.x
• Skill design plan: what each skill does, in detail
• 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