dld-kit 1.0.0-rc.3 → 1.0.0-rc.4

package/README.md

@@ -1,434 +1,197 @@
-# DLD Kit — Decision-Linked Development
+# DLD Kit | Decision-Linked Development
 
-Stop AI agents from breaking code they don't understand.
+**Stop AI agents from breaking code they don't understand.**
 
-> [!NOTE]
-> Early development — APIs, file formats, and skill interfaces may change.
-
----
+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.
 
-AI agents write code confidently. They just don't know *why* your code looks the way it does. That retry logic tuned for a specific API's rate limiting? That validation step catching a production-only edge case? Those decisions live in Jira tickets, Slack threads, and departed engineers' heads. DLD aims to fix this with an **append-only decision log** and `@decision(DL-XXX)` annotations that link code directly to the reasoning behind it. When an agent encounters an annotation, it reads the decision *before* modifying anything. DLDs primary focus is to connect context to code in a highly visible and directly accessible way, avoiding guesswork & git or JIRA archeology to retrieve core business context. Ensuring absolute, immediate, correctness of the produced software is however *not* within the core scope of DLD; for that you will need to combine it with sound general test & validation practices.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dld-workflow-dark.svg">
+  <img src="docs/assets/dld-workflow-light.svg" width="880" alt="DLD workflow: /dld-plan records proposed decisions; /dld-implement writes and reviews the code and links it to the decisions with @decision comments; /dld-snapshot, run on demand, on a schedule or in CI, generates OVERVIEW.md and SNAPSHOT.md. Agents read the linked decision before editing annotated code.">
+</picture>
 
-## Install
-
-Requirements: Node.js 20+ and git. `gh` is optional; `/dld-reindex` uses it to check open PRs.
+> [!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](#upgrading-from-0x). The last 0.x release is [v0.9.0](https://github.com/jimutt/dld-kit/releases/tag/v0.9.0).
 
-Each channel below installs the same skills. They differ in which agents they reach, how the always-on rule gets into the agent's context, and how you update.
+DLD Kit is a set of [Agent Skills](https://agentskills.io) for Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity and Copilot CLI, plus a small CLI that installs them.
 
-| Channel | Agents | Installs into | Always-on rule | Update with |
-|---|---|---|---|---|
-| [`npx dld-kit init`](#npx-dld-kit-init) | Claude Code, Antigravity, Codex, Cursor, OpenCode, Pi | The project, committed | Written by `init` | `npx dld-kit@latest update` |
-| [Claude Code plugin](#claude-code-plugin) | Claude Code | Your user profile | SessionStart hook | `claude plugin marketplace update dld-kit`, then `claude plugin update dld@dld-kit` |
-| [Codex and Copilot CLI plugins](#codex-and-copilot-cli-plugins) | Codex, Copilot CLI | Your user profile | dld-init skill | Codex's plugin manager; `copilot plugin update` |
-| [Pi package](#pi-package) | Pi | Your user profile, or the project with `-l` | dld-init skill | `pi update npm:dld-kit` |
-| [`npx skills` / `gh skill`](#npx-skills-or-gh-skill) | Any agent those tools support | The project, or your user profile with `-g` | dld-init skill | `npx skills update` / `gh skill update` |
-| [Manual copy](#manual-copy) | Any Agent Skills harness | Wherever you copy them | dld-init skill | Copy again |
+**Contents:** [Quickstart](#quickstart) · [How it works](#how-it-works) · [Workflows](#workflows) · [Skills](#skills) · [Install](#install) · [Configuration](#configuration) · [DLD and spec-driven development](#dld-and-spec-driven-development) · [CLI](#cli) · [Learn more](#learn-more)
 
-### `npx dld-kit init`
+## Quickstart
 
-Run in the root of a git repository:
+You need Node.js 20+ and git. In the root of your repository, run:
 
 ```bash
 npx dld-kit init
 ```
 
-This writes:
-
-- `dld.config.yaml`, `decisions/records/` and `decisions/INDEX.md`
-- the `dld-*` skills for each selected agent: `.claude/skills/` for Claude Code, `.agents/skills/` for the others
-- the always-on rule, once per agent: a block between `<!-- dld-kit:start -->` and `<!-- dld-kit:end -->` in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi, `.agents/rules/dld-workflow.md` for Antigravity, and `.claude/rules/dld-workflow.md` for Claude Code unless Claude Code already reads the block (see [Agents](#agents)). When the block goes into `AGENTS.md` and the project has no `CLAUDE.md` or `.claude/CLAUDE.md`, it writes `.claude/CLAUDE.md` instead, which imports `AGENTS.md` for Claude Code
-
-`init` detects the agents from files in the project (`.claude/`, `.codex/`, `.cursor/`, `opencode.json`, `.pi/`, `AGENTS.md` and so on) and asks you to confirm the list. Options:
-
-- `--agent claude,codex`: add agents to the detected ones
-- `--namespaces billing,auth`: one decision directory per namespace (for monorepos)
-- `--yes`: skip the question and use the detected agents plus `--agent`
-
-Commit the files. Teammates then need nothing installed.
-
-To upgrade, run `npx dld-kit@latest update`. It rewrites the `dld-*` skills and the rule for the agents already installed, and never touches decision records or `dld.config.yaml`. Add `--agent <name>` to install for another agent.
-
-### Claude Code plugin
-
-In Claude Code:
-
-```
-/plugin marketplace add jimutt/dld-kit
-/plugin install dld@dld-kit
-```
-
-Then run `/dld-init` in each project. The plugin's SessionStart hook adds the always-on rule to each session in projects that have `dld.config.yaml` and do not already load the rule. `/dld-init` also installs `.claude/rules/dld-workflow.md`, so teammates without the plugin get the rule too.
-
-Skills run as `/dld-plan`, or as `/dld:dld-plan` if another skill has the same name. Third-party marketplaces do not auto-update by default. To update:
-
-```bash
-claude plugin marketplace update dld-kit
-claude plugin update dld@dld-kit
-```
-
-### Codex and Copilot CLI plugins
-
-Both install the portable skills from the repository root, with no hook.
-
-```bash
-codex plugin marketplace add jimutt/dld-kit       # then install dld from /plugins in Codex
-copilot plugin marketplace add jimutt/dld-kit
-copilot plugin install dld@dld-kit
-```
-
-Then run the dld-init skill in each project for the config and the rule. For Copilot CLI it installs the rule as for Codex.
-
-### Pi package
-
-```bash
-pi install npm:dld-kit        # for your user
-pi install -l npm:dld-kit     # for this project (.pi/settings.json)
-```
-
-Run `/skill:dld-init` in each project for the config and the rule. Update with `pi update npm:dld-kit`.
-
-### `npx skills` or `gh skill`
-
-```bash
-npx skills add jimutt/dld-kit
-gh skill install jimutt/dld-kit --all
-```
-
-Install all the skills. If you pick some with `--skill`, include `dld-common`: it holds the `dld` CLI the other skills run. Then run the dld-init skill in each project for the config and the rule. Update with `npx skills update` or `gh skill update`.
-
-`npx skills` puts the files in `.agents/skills/` and links them from `.claude/skills/` for Claude Code. `dld update` refuses to write through those links; keep updating with `npx skills update`.
-
-### Manual copy
-
-Copy the `dld-*` directories from [`skills/`](skills/) into your agent's skills directory, or from [`.claude/skills/`](.claude/skills/) into a project's `.claude/skills/` for Claude Code. Include `dld-common`. Then run the dld-init skill for the config and the rule.
-
-### Combining channels
-
-Channels can be combined. These combinations need care:
-
-- **A user-level plugin or package, plus skills committed in the project for the same agent.** The agent sees each skill twice, possibly at different versions. In Claude Code, run the plugin's copy as `/dld:dld-plan`.
-- **Skills for Claude Code and for an `.agents/skills/` agent in one project.** OpenCode and Cursor read both `.claude/skills/` and `.agents/skills/`. OpenCode 2.x loads the `.agents/skills/` copy; OpenCode 1.x and Cursor may load either. Both copies work.
-- **`dld update` and `npx skills` on the same skills.** `dld update` refuses symlinked skills and warns when `skills-lock.json` lists `dld-*` skills. Update those skills with one tool.
-
-### Agents
-
-| Agent | Skills (`dld init`) | Always-on rule (`dld init`, `/dld-init`) | Run a skill |
-|---|---|---|---|
-| Claude Code | `.claude/skills/` | `.claude/rules/dld-workflow.md`, or the block in `CLAUDE.md`, or in `AGENTS.md` imported from a CLAUDE file (`@AGENTS.md`) | `/dld-plan` |
-| Antigravity | `.agents/skills/` | `.agents/rules/dld-workflow.md` | Ask for the dld-plan skill |
-| Codex | `.agents/skills/` | Block in `AGENTS.md` | Ask for the dld-plan skill |
-| Cursor | `.agents/skills/` | Block in `AGENTS.md` or `CLAUDE.md` (Cursor reads both) | Ask for the dld-plan skill |
-| OpenCode | `.agents/skills/` | Block in `AGENTS.md` (OpenCode 2.x reads no `CLAUDE.md`) | Ask for the dld-plan skill |
-| Pi | `.agents/skills/` | Block in `AGENTS.md`, or `CLAUDE.md` if there is no `AGENTS.md` | `/skill:dld-plan` |
-| Copilot CLI | Plugin only | Block in `AGENTS.md` (installed as for Codex) | Ask for the dld-plan skill |
-
-A new block goes into `AGENTS.md` if it exists. Otherwise it goes into an existing `CLAUDE.md` only when every selected agent that takes the block (Codex, Cursor, OpenCode, Pi) reads that file, which Cursor and Pi do, and into a new `AGENTS.md` in all other cases. Pi reads `CLAUDE.md` only while there is no `AGENTS.md`, so when `dld` creates `AGENTS.md` next to a `CLAUDE.md` for Pi, it warns you to move anything Pi needs. A block already in `CLAUDE.md` stays there; `dld install-rule` warns about agents that cannot see it (Codex, OpenCode) and says how to move it.
-
-Each agent gets the rule once. Claude Code reads `AGENTS.md` by itself only when the project has no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md`, so adding one of those (even an uncommitted `CLAUDE.local.md`) would stop it. When the block is in `AGENTS.md` and the project has no `CLAUDE.md` or `.claude/CLAUDE.md`, `init` writes `.claude/CLAUDE.md` with the line `@../AGENTS.md`. Claude Code then loads `AGENTS.md` through that import, once, whichever CLAUDE files are added later. If a `CLAUDE.md` of yours already imports `@AGENTS.md`, the block there is Claude Code's rule and no other file is written.
-
-The examples below use Claude Code's `/dld-plan` form. In other agents, name the skill instead, e.g. "use the dld-plan skill to plan the retry feature".
-
-### Upgrading from 0.x
-
-Before 1.0, the skills were copied by hand or installed with Tessl, each skill carried `scripts/*.sh`, and `/dld-init` appended a `## DLD (Decision-Linked Development)` section to `CLAUDE.md`.
-
-- **Your data carries over unchanged:** `dld.config.yaml`, `decisions/records/`, `decisions/INDEX.md` and `decisions/.dld-state.yaml`. 1.0 reads them as 0.x wrote them.
-- **Skills copied into `.claude/skills/` or `.agents/skills/`:** in the project, run `npx dld-kit@latest update --agent <names>` (e.g. `--agent claude,codex`). It rewrites the `dld-*` skills, deletes their old `scripts/*.sh`, and installs the always-on rule. Commit the result.
-- **Skills copied anywhere else** (e.g. `.cursor/skills/`, `.codex/skills/`): delete those `dld-*` directories, then run the same `update`.
-- **Tessl installs:** remove the `dld-kit/dld` tile with Tessl, and delete any DLD rule text Tessl added. Then run `update`. The Tessl tile gets no new versions.
-- **The old `CLAUDE.md` section:** once the rule is installed, delete the `## DLD (Decision-Linked Development)` section yourself. Until then Claude Code and Cursor read the rule twice. `update` warns while the section is there, and never edits it.
-- **To use the plugin or `npx skills` instead:** delete the copied `dld-*` directories and the old `CLAUDE.md` section first, then install through that channel.
-
-## Get started
-
-### New feature or change
-
-Use `/dld-plan` to break it down into decisions, then implement:
-
-```
-/dld-init              # Bootstrap DLD in your repo (run once)
-/dld-plan              # Break it down into decisions interactively
-/dld-adjust DL-001     # Refine decisions if details change before implementing
-/dld-implement DL-001  # Implement each decision (or batch related ones)
-/dld-snapshot          # Generate overview docs from the decision log
-```
-
-For a small, isolated change (a bug fix, a single design choice), `/dld-decide` records one decision directly without the planning step.
-
-### Existing codebase
+`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.
 
-Use `/dld-retrofit` to generate decisions from code that already exists:
+Then, in your agent:
 
 ```
-/dld-init              # Bootstrap DLD in your repo (run once)
-/dld-retrofit          # Analyze code, generate decisions and annotations
-/dld-snapshot          # Generate overview docs from the decision log
+/dld-plan add retries to the payment client
+/dld-implement
+/dld-snapshot
 ```
 
-This works as a standalone "document this codebase" action. You get structured decision records, code annotations, and a generated system overview. From there you can adopt the full workflow, or just re-run `/dld-audit-auto` and `/dld-snapshot` on a schedule to keep documentation in sync.
+`/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.
 
-### Working in a team
+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".
 
-When multiple developers draft decisions in parallel, two of them can end up picking the same `DL-NNN` ID. Once one of those PRs lands on the base branch, the other can't rebase cleanly — the colliding decision file path appears in both histories.
-
-```
-/dld-reindex           # Renames the local draft(s) to the next free ID,
-                       # rewrites @decision annotations and cross-references,
-                       # squashes the branch into a single rebase-clean commit
-```
-
-Run this before rebasing onto an updated base. The skill resolves the ID against the base branch and, when `gh` is installed and authenticated, also against open PRs so the new IDs don't collide with someone else's in-flight work.
+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](#install).
 
 ## How it works
 
-DLD is implemented as a set of AI agent skills following the [Agent Skills](https://agentskills.io) open standard.
-
-### The decision record
-
-Each decision is a markdown file with YAML frontmatter:
+A **decision** is a markdown file in `decisions/records/`:
 
 ```markdown
 ---
-id: DL-008
+id: DL-012
 title: "Use exponential backoff for payment gateway retries"
 timestamp: 2026-02-15T09:20:00Z
 status: accepted
-supersedes: [DL-002]
-amends: []
-tags: [payments, resilience]
+tags: [payments]
 references:
   - path: src/payments/gateway.ts
-    symbol: retryWithBackoff
 ---
 
 ## Context
-The payment gateway occasionally returns 503s under load. Our initial
-fixed-interval retry (DL-002) caused retry storms that made things worse.
+The gateway returns 503s under load. Fixed-interval retries made it worse.
 
 ## Decision
-Use exponential backoff with jitter, capped at 30 seconds, max 5 attempts.
-
-## Rationale
-Exponential backoff prevents retry storms. Jitter avoids thundering herd
-when multiple requests fail simultaneously...
-
-## Consequences
-Failed payments take longer to resolve (up to ~60s worst case)...
+Exponential backoff with jitter, capped at 30 seconds, at most 5 attempts.
 ```
 
-### The code annotation
+A full record also has Rationale and Consequences sections; see the [decision record format](docs/framework/decision-record-format.md).
+
+An **annotation** links code to the decision:
 
 ```typescript
-// @decision(DL-008)
+// @decision(DL-012)
 function retryWithBackoff(fn: () => Promise<Response>): Promise<Response> {
-  // ...
-}
 ```
 
-When an AI agent encounters this annotation, it reads the decision before modifying the code. If the planned change conflicts with the decision, it tells you and suggests recording a new decision.
+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.
 
-## How DLD compares to spec-driven development
+- **Accepted decisions aren't rewritten.** Once a decision is `accepted` and shared, you don't edit its reasoning. To change course, record a new decision that supersedes or amends it, so the history stays complete. Only metadata such as `status` and `references` gets updated. 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.
 
-There are great spec-driven tools out there ([Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/), [OpenSpec](https://openspec.dev/), [Kiro](https://kiro.dev/)) and they work well for many teams, especially for structured greenfield development. If they fit your workflow, use them.
+DLD gives agents context, not guarantees. Keep your tests.
 
-DLD is a different approach for teams that find spec documents hard to maintain over time, or that want decision context embedded closer to the code. It borrows from **event sourcing**:
+## Workflows
 
-- **Decisions are append-only events** — once accepted, a decision's content is immutable. Metadata (`status`, `references`) can be updated mechanically (e.g., after refactors), but the reasoning is never rewritten. Decisions can be superseded but never edited or deleted. This creates a complete timeline of how the system evolved.
-- **The spec is a derived projection** — generated from the decision log, never manually maintained. Like a read model built from an event stream.
-- **Tight code coupling** — `@decision` annotations in code act as mechanical triggers for AI agents. The decision context lives *where the code is* rather than in a separate document.
+- **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.
 
-DLD is designed for long-lived codebases where decisions accumulate, original authors move on, and AI agents need to safely modify code they didn't write. If that sounds like your situation, give it a try.
+More detail, with diagrams: [workflows](docs/workflows.md).
 
 ## Skills
 
-The table uses Claude Code's slash form; in Pi use `/skill:<name>`, and in other agents ask for the skill by name.
-
-| Skill | Purpose |
-|-------|---------|
-| `/dld-init` | Bootstrap DLD in a repository (run once) |
-| `/dld-decide` | Record a single decision interactively |
-| `/dld-plan` | Break down a feature into multiple grouped decisions |
-| `/dld-implement` | Implement proposed decisions — writes code, adds annotations, updates status |
-| `/dld-adjust` | Adjust or update existing decisions — handles permission gating and correct intent interpretation |
-| `/dld-lookup` | Query decisions by ID, tag, code path, or keyword |
-| `/dld-status` | Overview of the decision log — counts, recent decisions, run tracking |
-| `/dld-audit` | Scan for drift between decisions and code |
-| `/dld-audit-auto` | Autonomous audit — detects drift, fixes issues, opens a PR (for scheduled/CI use) |
-| `/dld-snapshot` | Generate SNAPSHOT.md (detailed reference) and OVERVIEW.md (narrative synthesis with diagrams) |
-| `/dld-retrofit` | Bootstrap decisions from an existing codebase (broad or detailed mode) |
-| `/dld-reindex` | Resolve decision ID collisions with the base branch (and open PRs) before rebasing — renames colliding local drafts, rewrites annotations and cross-references, squashes branch commits into a rebase-clean reindex commit |
-
-### Active workflow
-
-The core DLD loop: record decisions via `/dld-decide` or `/dld-plan`, implement them with `/dld-implement`, and the framework maintains tight coupling between the decision log and code through `@decision` annotations. `/dld-audit` periodically checks for drift, and `/dld-snapshot` regenerates the derived specification.
-
-<img width="3180" height="2100" alt="DLD high-level workflow overview showing the decision log, code annotations, generated specification, and drift detection" src="https://github.com/user-attachments/assets/fc8b7804-10ce-439b-ba0c-1f431a26a46e" />
-
-### Passive mode
-
-For teams that want living documentation without changing how they work. Run `/dld-init` and `/dld-retrofit` once to bootstrap, then schedule `/dld-audit-auto` and `/dld-snapshot` to run automatically (e.g. nightly via CI). The audit detects unreferenced code changes, infers new decisions, and back-annotates the code — all without developers invoking any DLD commands during their normal workflow.
-
-<img width="2880" height="2760" alt="DLD passive mode showing scheduled automation that keeps decisions and docs in sync without workflow changes" src="https://github.com/user-attachments/assets/36bba4e1-e8eb-4390-a484-f18f54638fa1" />
-
-> [!NOTE]
-> DLD doesn't include a scheduler. How you trigger the automated runs is up to you — [Claude Code's built-in cron support](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#2171), a CI pipeline step, or any other external scheduler all work.
-
-## Project structure
-
-### Flat mode (default)
-
-```
-dld.config.yaml
-decisions/
-  INDEX.md          # Auto-generated decision index
-  SNAPSHOT.md       # Detailed per-decision reference
-  OVERVIEW.md       # Narrative synthesis with Mermaid diagrams
-  PRACTICES.md      # Development practices manifest (optional)
-  .dld-state.yaml   # Last audit and snapshot runs
-  records/
-    DL-001.md
-    DL-002.md
-```
-
-### Namespaced mode (monorepos)
+| 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 `SNAPSHOT.md` 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 |
 
-```
-dld.config.yaml
-decisions/
-  INDEX.md
-  SNAPSHOT.md
-  OVERVIEW.md
-  PRACTICES.md
-  records/
-    billing/
-      DL-001.md
-      DL-004.md
-      PRACTICES.md  # Namespace-specific practices (optional)
-    auth/
-      DL-002.md
-      DL-005.md
-```
+## Install
 
-IDs are globally sequential across namespaces, so `@decision(DL-012)` is unambiguous regardless of which namespace it belongs to.
+Every option installs the same skills. You need Node.js 20+ and git. `gh` is optional: `/dld-reindex` uses it to check open PRs.
 
-## Status lifecycle
+### Which one to use
 
-```
-proposed --> accepted --> deprecated
-                     --> superseded (by a newer decision)
-```
+**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.
 
-- **proposed** — recorded but not yet implemented (mutable — can be refined during implementation)
-- **accepted** — implemented, code references this decision via annotations (content immutable, metadata like `status` and `references` can be updated)
-- **deprecated** — no longer relevant, no replacement
-- **superseded** — replaced by a newer decision
+- **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`.
 
-## Concepts
+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.
 
-### Practices manifest
+| Option | Agents | Install | Update |
+|---|---|---|---|
+| [`npx dld-kit init`](docs/install.md#npx-dld-kit-init) | Claude Code, Antigravity, Codex, Cursor, OpenCode, Pi | `npx dld-kit init` | `npx dld-kit@latest update` |
+| [Claude Code plugin](docs/install.md#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](docs/install.md#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](docs/install.md#pi-package) | Pi | `pi install npm:dld-kit` | `pi update npm:dld-kit` |
+| [`npx skills` / `gh skill`](docs/install.md#npx-skills-or-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](docs/install.md#manual-copy) | Any Agent Skills agent | Copy the `dld-*` folders from [`skills/`](skills/) | Copy again |
 
-An optional `decisions/PRACTICES.md` captures project development conventions (testing approach, code style, architecture patterns). The AI agent reads this when making and implementing decisions — it's most useful during `/dld-implement` where it directly influences how code is written.
+With any option except `init`, run the dld-init skill once in each repository to create the config and install the rule.
 
-### Spec as projection
+<a name="combining-channels"></a><a name="agents"></a><a name="manual-rule-setup"></a><a name="npx-dld-kit-init"></a><a name="claude-code-plugin"></a>
+See [install details](docs/install.md) for where each agent keeps its skills and rule, how to combine options, and how to add the rule by hand.
 
-The snapshot and overview documents are **generated, not maintained**. Like event sourcing read models, they're derived from the decision log and can be regenerated at any time. You maintain individual decisions; the framework derives the consolidated view.
+### Upgrading from 0.x
 
-### Drift detection
+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`.
 
-`/dld-audit` detects when code and decisions have drifted apart — orphaned annotations, stale references, modified annotated files that may need decision updates.
+Tessl installs and skills copied to other folders need one more step first: see [upgrading from 0.x](docs/upgrading-from-0x.md).
 
-## Advanced configuration
+## Configuration
 
-### Custom snapshot artifacts
+`dld.config.yaml` holds the settings. The ones you're most likely to change:
 
-By default, `/dld-snapshot` generates `SNAPSHOT.md` and `OVERVIEW.md`. You can define additional documentation artifacts in `dld.config.yaml` — each one synthesized from the decision log using a prompt you provide:
+- **`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.
 
-```yaml
-snapshot_artifacts:
-  - title: ONBOARDING.md
-    prompt: >
-      Generate a developer onboarding guide that explains the system
-      from scratch, assuming no prior context. Focus on what a new
-      contributor needs to know to start working.
-  - title: API-CONTRACTS.md
-    prompt: >
-      Summarize all API-related decisions into a single API contract
-      reference. Include endpoints, payload shapes, and auth requirements.
-```
+All the options: [project configuration](docs/framework/project-configuration.md).
 
-Custom artifacts are written to `decisions/` alongside the built-in files and regenerated every time `/dld-snapshot` runs. The `title` serves as both the filename and the document heading. See [project configuration](docs/framework/project-configuration.md#snapshot-artifacts) for details.
+## DLD and spec-driven development
 
-### Implementation review
+Spec-driven tools such as [Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/), [OpenSpec](https://openspec.dev/) and [Kiro](https://kiro.dev/) 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:
 
-`/dld-implement` includes a built-in review step that launches a subagent to check all code changes before finalizing. The reviewer scans for correctness, security issues, type safety problems, and consistency with existing patterns — then reports findings grouped by severity (critical, moderate, minor).
+- **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.
 
-This is enabled by default. To disable it, set `implement_review` to `false` in `dld.config.yaml`:
-
-```yaml
-implement_review: false
-```
-
-The review subagent operates with limited context and may flag false positives. The implementing agent uses its own judgment and asks for user input when uncertain about a finding.
+More in the [FAQ](docs/concept/dld-faq.md) and the [concept paper](docs/concept/dld-concept.md).
 
 ## CLI
 
-The `dld` command comes with the npm package (`npx dld-kit <command>`, or `npm install --global dld-kit`). The skills carry their own copy in `dld-common/scripts/dld.mjs`, so they never need a global install.
+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` | Creates `dld.config.yaml`, `decisions/` and `INDEX.md`, then installs the skills and the rule (see [above](#npx-dld-kit-init)) |
-| `dld update` | Rewrites the installed skills and rule with this version; `--agent` adds agents |
-| `dld install-rule --agent <names>` | Installs or refreshes only the always-on rule |
-| `dld session-context --agent <name>` | Prints the rule for a session hook, unless the agent loads it already (used by the Claude Code plugin) |
-| `dld --help` | Lists the setup commands above, then the commands the skills run |
+| `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) |
 
-`init` and `update` refuse to overwrite files from a newer dld-kit unless given `--force`.
+`init` and `update` won't overwrite files from a newer dld-kit unless you pass `--force`.
 
-Semantic versioning covers the four commands above, their flags, exit codes and documented output, and `--help` and `--version`. The other commands (`next-id`, `create-decision`, `regenerate-index` and so on) are internal: the skills run them from their own bundled copy of the CLI, and their names, arguments and output can change in a minor release. Don't script against them.
+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.
 
-## Development
+## Learn more
 
-```bash
-bun install                               # dev dependencies (Bun is a dev tool; the CLI runs on Node 20+)
-npm run lint && npm run typecheck && npm test
-```
+- [Concept paper](docs/concept/dld-concept.md): the full reasoning behind DLD
+- [TL;DR](docs/concept/dld-tldr.md) and [FAQ](docs/concept/dld-faq.md)
+- [Decision record format](docs/framework/decision-record-format.md) and [project configuration](docs/framework/project-configuration.md)
+- [Install details](docs/install.md), [workflows](docs/workflows.md) and [upgrading from 0.x](docs/upgrading-from-0x.md)
+- [Skill design plan](docs/plan/skill-design.md): what each skill does, in detail
+- [Contributing](CONTRIBUTING.md) and [releasing](docs/releasing.md)
 
-Skills and plugin manifests are generated: edit `templates/`, then run `npm run generate` to rebuild `skills/`, `.claude/skills/`, `claude-plugin/` and the manifests. See `CLAUDE.md` for the full set of commands, `docs/releasing.md` for releases, and `docs/plan/v1.md` for the 1.0 plan.
-
-## Further reading
-
-- [Concept paper](docs/concept/dld-concept.md) — full rationale and design philosophy
-- [TL;DR](docs/concept/dld-tldr.md) — one-page summary
-- [FAQ](docs/concept/dld-faq.md) — anticipated questions
-- [Decision record format](docs/framework/decision-record-format.md) — schema and field reference
-- [Project configuration](docs/framework/project-configuration.md) — config file and directory layout
-- [Skill design plan](docs/plan/skill-design.md) — detailed skill specifications
+Ideas and bug reports are welcome: [open an issue](https://github.com/jimutt/dld-kit/issues).
 
 ## Acknowledgements
 
-DLD builds on ideas from several projects and people:
-
-- **[Architecture Decision Records (ADRs)](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)** — Michael Nygard's foundational concept (2011) of recording architectural decisions as structured documents. DLD extends ADRs to cover all decision types and adds code-level coupling.
-- **[Embedded ADRs (e-adr)](https://github.com/adr/e-adr)** — Pioneered `@ADR` annotations in Java code, linking decisions to classes and methods. DLD generalizes this to be language-agnostic and AI-agent-aware.
-- **[Vibe ADR](https://medium.com/devops-ai/vibe-adr-building-with-intention-in-the-age-of-ai-d01e93f36696)** — Owen Zanzal's concept of decision records as "living nodes of intent" for both humans and AI.
-- **[OpenSpec](https://openspec.dev/)** — A change-based specification framework with a delta model and archive workflow. Its brownfield-first philosophy and incremental approach validated key assumptions behind DLD.
-- **[Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)** — GitHub's spec-driven development toolkit. DLD shares the goal of giving AI agents better context but inverts the relationship — the spec is derived from decisions rather than being the primary artifact.
-- **[IIC Kit (Intent Integrity Kit)](https://github.com/docsforadobe/intent-integrity-for-claude-code)** — A constitution-driven framework for Claude Code that influenced DLD's skill organization and practices manifest approach.
-- **[Kiro](https://kiro.dev/)** — AWS's spec-driven development IDE, part of the broader SDD movement that motivated DLD's alternative approach.
-- **Event Sourcing / CQRS** — The architectural pattern behind DLD's core model: decisions as an append-only event stream, specs as derived projections.
-- **[ADR community resources](https://adr.github.io)** — The comprehensive collection of ADR tools, templates, and guidance that provided a foundation for DLD's record format.
-
-See the [concept paper](docs/concept/dld-concept.md) for a detailed discussion of how DLD relates to these approaches.
-
-## Roadmap
-
-DLD is under active development. Feature requests and ideas are welcome — [open an issue](https://github.com/jimutt/dld-kit/issues).
-
-## Manual rule setup
-
-The always-on rule tells the agent to read a decision before changing code annotated with it. `/dld-init` installs it with `dld install-rule --agent <harness>`, which picks the file the harness loads: `.claude/rules/dld-workflow.md` for Claude Code (unless it reads the block in `AGENTS.md`, directly or through a `.claude/CLAUDE.md` import), `.agents/rules/dld-workflow.md` for Antigravity, or a marked block in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi.
-
-To add it by hand instead, copy [`templates/rules/dld-workflow.md`](templates/rules/dld-workflow.md) into one of those files.
+DLD builds on [Architecture Decision Records](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions), [Embedded ADRs](https://github.com/adr/e-adr), [Vibe ADR](https://medium.com/devops-ai/vibe-adr-building-with-intention-in-the-age-of-ai-d01e93f36696), [OpenSpec](https://openspec.dev/), [Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/), [IIC Kit](https://github.com/docsforadobe/intent-integrity-for-claude-code), [Kiro](https://kiro.dev/) and event sourcing. See [what each one contributed](docs/concept/acknowledgements.md).
 
 ## License