dld-kit 1.0.0-rc.5 → 1.0.0-rc.6

package/README.md

@@ -6,7 +6,7 @@ Code is full of choices that look odd without their reason: a retry tuned to one
 
 <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.">
+  <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. Agents read the linked decision before editing annotated code.">
 </picture>
 
 > [!NOTE]
@@ -18,7 +18,7 @@ DLD Kit is a set of [Agent Skills](https://agentskills.io) for Claude Code, Code
 
 ## Quickstart
 
-You need Node.js 20+ and git. In the root of your repository, run:
+You need Node.js 22+ and git. In the root of your repository, run:
 
 ```bash
 npx dld-kit init
@@ -34,7 +34,7 @@ Then, in your agent:
 /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.
+`/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.
 
 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".
 
@@ -74,7 +74,7 @@ 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.
+- **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.
 
@@ -103,13 +103,13 @@ More detail, with diagrams: [workflows](docs/workflows.md).
 | `/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-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 20+ and git. `gh` is optional: `/dld-reindex` uses it to check open PRs.
+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
 
@@ -147,7 +147,8 @@ Tessl installs and skills copied to other folders need one more step first: see
 `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`.
+- **`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`.
@@ -178,7 +179,7 @@ Run `npx dld-kit <command>`, or `npm install --global dld-kit` for a `dld` comma
 
 `init` and `update` won't overwrite files from a newer dld-kit unless you pass `--force`.
 
-These five 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.
+These five commands, with their flags, exit codes and documented output, follow semantic versioning, as do `--help` and `--version`. So do the formats and names your project relies on: decision records, annotations, `dld.config.yaml`, the skill names and the install channels; [What a version number promises](docs/releasing.md#what-a-version-number-promises) has the full list. 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