dld-kit 1.0.0-rc.1

package/skills/dld-plan/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: dld-plan
+description: Break down a feature into multiple decisions interactively. Creates a set of decision records grouped by a shared tag.
+compatibility: Requires Node.js 20+ and git.
+metadata:
+  dld-kit-version: "1.0.0-rc.1"
+---
+<!-- Generated by dld-kit from templates/skills/dld-plan/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-plan — Plan a Feature as Multiple Decisions
+
+You are helping the developer break down a larger feature into discrete decisions. Each decision gets its own record, and they're grouped by a shared tag.
+
+## Interaction style
+
+Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user rather than waiting for freeform replies.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`.
+
+This skill uses: `next-id`, `create-decision`, `update-status`, `regenerate-index`.
+
+## Prerequisites
+
+Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+
+## Read project context
+
+1. Read `dld.config.yaml` to understand the project structure
+2. Read `decisions/PRACTICES.md` if it exists — consider project conventions when breaking down the feature
+
+## Conversation flow
+
+### 1. Collect the feature description
+
+If the user provided context with the skill invocation, use it. Otherwise ask:
+
+> What feature are you planning? Describe what you want to build and why.
+
+### 2. Determine namespace (namespaced projects only)
+
+If the project is namespaced, determine which namespace(s) this feature belongs to early — infer from the description if possible, otherwise ask. They can span multiple namespaces if the feature crosses boundaries.
+
+Once determined, also read `decisions/records/<namespace>/PRACTICES.md` if it exists for namespace-specific conventions.
+
+### 3. Check for related existing decisions
+
+Before proposing the breakdown, scan existing decision files for:
+- Decisions that reference the same code areas
+- Decisions with overlapping tags or topics
+- Decisions that the new feature might supersede or amend
+
+Mention any related decisions to the developer so the breakdown accounts for them.
+
+### 4. Break it down
+
+Analyze the feature and propose a breakdown into discrete decisions. Each decision should be:
+- **Independent enough** to stand on its own as a rationale record
+- **Concrete enough** that it captures a specific choice, not just "build X"
+- **Ordered** by dependency where relevant (which decisions depend on others)
+
+Present the proposed breakdown:
+
+> I'd suggest breaking this into the following decisions:
+>
+> 1. **Choose payment gateway adapter pattern** — How to abstract the gateway interface
+> 2. **Define retry strategy for failed payments** — Backoff logic and max attempts
+> 3. **Idempotency key format** — How to prevent duplicate charges
+>
+> Does this look right? Want to add, remove, or adjust any?
+
+Iterate with the developer until the breakdown is agreed.
+
+### 5. Choose a grouping tag
+
+Propose a tag that groups these decisions:
+
+> I'll tag all of these with `payment-gateway` so they're grouped together. Sound good?
+
+The tag should be descriptive, kebab-case, and specific to this feature.
+
+### 6. Create decision records
+
+For each decision in the breakdown, run the same commands used by `/dld-decide`:
+
+First, get the next ID:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" next-id
+```
+
+Then create the record, piping the body via `printf` with `\n` for newlines (do **not** use literal newlines in the body — use `\n` escape sequences):
+```bash
+printf "## Context\n\n...\n\n## Decision\n\n...\n\n## Rationale\n\n...\n\n## Consequences\n\n..." | node "<skill-dir>/../dld-common/scripts/dld.mjs" create-decision \
+  --id "DL-NNN" \
+  --title "Short descriptive title" \
+  --namespace "billing" \
+  --tags "payment-gateway" \
+  --supersedes "DL-003" \
+  --amends "DL-005" \
+  --body-stdin
+```
+
+Repeat for each decision, incrementing the ID each time. Run `next-id` before each creation to ensure correct sequencing.
+
+If any decision supersedes an existing one, also update the old decision's status:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" update-status DL-003 superseded
+```
+
+**Do not** update the status of amended decisions — they stay `accepted`.
+
+For each decision, compose a focused body. Keep it concise — the full feature context is captured across the group. Each individual decision should capture its own specific rationale.
+
+### 7. Regenerate INDEX.md
+
+After all decisions are created:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
+```
+
+### 8. Suggest next steps
+
+> Created **N** decisions for feature `<tag>`:
+>
+> | ID | Title | Status |
+> |----|-------|--------|
+> | DL-010 | Choose payment gateway adapter pattern | proposed |
+> | DL-011 | Define retry strategy for failed payments | proposed |
+> | DL-012 | Idempotency key format | proposed |
+>
+> Next steps:
+> - `/dld-adjust` — refine any decisions before implementing
+> - `/dld-implement` — implement all proposed decisions (or `/dld-implement DL-NNN` for a specific one)
+> - `/dld-lookup tag:<tag>` — review all decisions in this group

package/skills/dld-reindex/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: dld-reindex
+description: Resolve decision ID collisions between a local branch and the base branch (and open PRs) before rebasing. Renames colliding local decisions with git mv, rewrites cross-references and annotations, then squashes branch commits into a single rebase-clean reindex commit.
+compatibility: Requires Node.js 20+ and git. Open-PR scanning additionally needs the `gh` CLI authenticated against a GitHub remote — the skill falls back gracefully when unavailable.
+metadata:
+  dld-kit-version: "1.0.0-rc.1"
+---
+<!-- Generated by dld-kit from templates/skills/dld-reindex/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-reindex — Resolve Decision ID Collisions
+
+You are helping the developer untangle decision ID collisions before they rebase. Two or more developers can draft `DL-NNN` decisions in parallel; once one of them lands on the base branch (or appears in an open PR), the others must rename their local copies to the next free ID. This skill handles that mechanically and produces a branch state that rebases cleanly.
+
+**This skill rewrites branch history.** That's not optional: if a colliding path (e.g. `decisions/records/DL-205.md`) was added by any commit on the branch, `git rebase` will hit an add/add conflict on that commit *before* it ever sees a later rename. The only fix is to ensure the colliding path never appears in the branch's history. The skill does this by squashing all branch commits since the merge-base into one reindex commit containing the renamed files.
+
+If the branch has already been pushed, finishing the reindex will require a `--force-with-lease` push. The skill asks for explicit consent before rewriting history.
+
+## Interaction style
+
+Use the `AskUserQuestion` tool when prompting for consent and at the finish step. Everything else is deterministic.
+
+**Do not redirect any command output to `/tmp` files.** The commands in this skill emit only what you need to act on; piping to `/tmp/*.txt`, `tee`-ing into scratch files, or stashing stderr separately is unnecessary and creates clutter outside the repo. If a command's output is too long to read in one go, narrow it (`| tail -N`, `| head -N`, or pass a more specific flag) rather than persisting it.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`.
+
+This skill uses: `resolve-base`, `plan-renames`, `rename-decision`, `find-stale-mentions`, `commit-reindex`, `regenerate-index`.
+
+## Prerequisites
+
+1. Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+2. Verify the working tree is clean (`git status --porcelain` empty). If not, ask the user to commit or stash first, then stop.
+3. Fetch the latest base state:
+   ```bash
+   git fetch origin
+   ```
+
+## Step 1: Resolve the base ref
+
+```bash
+BASE=$(node "<skill-dir>/../dld-common/scripts/dld.mjs" resolve-base)
+```
+
+`resolve-base` prefers the branch's upstream when it tracks a *different* branch (the typical "feature → main" setup). It falls back to `origin/main` if the upstream is unset OR if the upstream tracks the same branch name as the current branch (i.e. it's just the remote copy of this same branch, not a useful collision base).
+
+The user may pass an explicit base when invoking the skill (e.g. `/dld-reindex origin/develop`) — honor it if present.
+
+## Step 2: Plan the renames
+
+```bash
+PLAN=$(node "<skill-dir>/../dld-common/scripts/dld.mjs" plan-renames --base "$BASE")
+echo "$PLAN"
+```
+
+Output is tab-separated, one rename per line:
+
+```
+<relative-path>\t<DL-OLD>\t<DL-NEW>
+```
+
+If the output is empty, exit with:
+
+> No ID collisions detected. Safe to rebase onto `$BASE`.
+
+`plan-renames` may print a stderr note like `[dld-reindex] open PRs not scanned: gh CLI not installed`. **Always surface this to the user** so they know the renamed IDs were chosen against base-branch state only and may still collide with an open PR.
+
+The underlying helpers (`find-collisions`, `list-taken-ids`) remain available for debugging, but the SKILL flow always goes through `plan-renames`.
+
+## Step 3: Get explicit consent for the history rewrite
+
+Show the user the rename plan and the implication. Use `AskUserQuestion`:
+
+> Resolving these collisions requires rewriting branch history. I will squash the N commits since `<merge-base>` into a single reindex commit. The original commit subjects will be preserved in the new commit body. If the branch has already been pushed, finishing will require `git push --force-with-lease`. How should I proceed?
+
+Options:
+- **Rewrite and force-push** — agent applies renames, squashes, commits, and runs `git push --force-with-lease`.
+- **Rewrite only** — agent applies renames, squashes, and commits. User pushes when ready.
+- **Cancel** — abort with no changes.
+
+If the user cancels, exit without touching anything.
+
+## Step 4: Apply renames
+
+For each line in the plan, call:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" rename-decision --old DL-OLD --new DL-NEW --path <relative-path> --base "$BASE"
+```
+
+`rename-decision` does all of:
+
+- `git mv` the file from `DL-OLD.md` to `DL-NEW.md`.
+- Patches the `id:` frontmatter field in the renamed file.
+- Rewrites `DL-OLD` mentions inside the renamed file's body.
+- Rewrites `DL-OLD` mentions inside OTHER locally-added/modified decision files (frontmatter `supersedes` / `amends` / `references` and body). Scoped to the local change set vs the base ref.
+- Rewrites `` `@decision` ``(DL-OLD) annotations to `` `@decision` ``(DL-NEW) in non-decision files that are part of the local change set.
+
+The substitution is digit-aware: renaming `DL-100` will not accidentally rewrite `DL-1000`.
+
+**Note on plain-text DL-NNN mentions in code:** In non-decision files (source code, READMEs, etc.) `rename-decision`'s rewrite is **scoped to `` `@decision` ``(DL-NNN) annotations only**. Bare `DL-NNN` references in comments, log strings, or test fixtures are left untouched here to avoid false-positive matches against unrelated identifiers. Step 5 handles them.
+
+## Step 5: Review plain-text DL-OLD mentions
+
+After all renames are applied (but before the squash), find any remaining bare `DL-OLD` references in non-decision changed files:
+
+```bash
+echo "$PLAN" | node "<skill-dir>/../dld-common/scripts/dld.mjs" find-stale-mentions --base "$BASE"
+```
+
+Output is tab-separated, one match per line: `<path>\t<line>\t<DL-OLD>\t<DL-NEW>\t<line-content>`. Empty output means nothing to review.
+
+For each match:
+
+1. Read the surrounding context in the file.
+2. Decide whether the reference makes sense as `DL-OLD` or should become `DL-NEW`. A code comment like `// Span-driven batching (DL-207) groups resolutions sharing the same turn context (DL-202)` after a `DL-207 → DL-213` rename almost certainly wants `DL-213` (it's prose alongside an annotation). A test fixture string that's checking historical data may need to stay as `DL-OLD`.
+3. If the line should change, use the `Edit` tool to update that specific occurrence — don't do a blanket find-and-replace.
+4. If the line should stay, leave it.
+
+Surface the list of matches to the user with your verdicts before you finish, so they can sanity-check the judgment calls.
+
+## Step 6: Squash and commit
+
+Pipe the rename plan into `commit-reindex`:
+
+```bash
+echo "$PLAN" | node "<skill-dir>/../dld-common/scripts/dld.mjs" commit-reindex --base "$BASE"
+```
+
+This:
+
+1. Computes the merge-base with `$BASE`.
+2. Mixed-resets HEAD to the merge-base (working tree is preserved — it already holds the post-rename state from step 4).
+3. Restores `INDEX.md` in the working tree to its merge-base state so the working tree is consistent with what we're about to commit. **INDEX.md is intentionally excluded from the reindex commit** — including it would cause a content conflict during rebase whenever the base branch also modified INDEX.md (git's 3-way merge fails to align both sides' top-of-file inserts even when row content overlaps). INDEX.md gets regenerated post-rebase instead.
+4. Stages **only** an explicit path list derived from the original branch diff and the rename plan — the old paths (for deletions), the new paths (for additions), every other file the branch touched. Untracked unrelated paths (e.g. `.claude/worktrees`, scratch files, in-progress edits to unrelated files) are deliberately NOT swept in.
+5. Commits with a templated message that lists the renames in the subject and preserves the original branch commits' subjects in the body.
+
+**Do not use `git add -A` or `git commit -a` anywhere in this flow.** Use only `commit-reindex` to commit. Targeting paths explicitly is the whole point of this step.
+
+## Step 7: Push (if the user chose force-push)
+
+If step 3's answer was "Rewrite and force-push":
+
+```bash
+if git rev-parse --verify --quiet "@{upstream}" >/dev/null; then
+  git push --force-with-lease
+else
+  git push -u origin HEAD
+fi
+```
+
+`--force-with-lease` is mandatory over `--force` here — it refuses to push if the remote moved since the last fetch, which protects against overwriting concurrent collaborator pushes.
+
+## Step 8: Report
+
+Print:
+
+- The renames table.
+- The stderr note from step 2 if `gh` was skipped.
+- The number of commits squashed.
+- The next steps:
+
+> 1. `git rebase $BASE`
+> 2. `node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index` (to repopulate INDEX.md with the renamed locals — the reindex commit intentionally leaves INDEX.md alone to keep the rebase conflict-free; INDEX.md is missing the renamed rows until you regenerate)
+> 3. Commit the INDEX.md update
+
+The skill never rebases or merges — that is always the user's call.
+
+## Out of scope
+
+- **Already-conflicted rebases.** If the user is mid-rebase with conflicts, tell them to `git rebase --abort` first and re-run this skill.
+- **Preserving per-commit granularity.** The squash trades original commit boundaries for a deterministic rewrite. A future `--preserve-history` flag could perform a cherry-pick walk that rewrites each commit individually, but the edge cases (commits modifying an already-renamed file, merge commits, partial reruns) make it materially more complex than the squash.
+- **Cross-namespace ID reconciliation** in namespaced projects. IDs are assumed globally unique across namespaces, matching `next-id`.

package/skills/dld-retrofit/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: dld-retrofit
+description: Bootstrap DLD decisions from an existing codebase. Analyzes code to infer rationale, generates decision records, and adds `@decision` annotations.
+compatibility: Requires Node.js 20+ and git.
+metadata:
+  dld-kit-version: "1.0.0-rc.1"
+---
+<!-- Generated by dld-kit from templates/skills/dld-retrofit/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-retrofit — Retrofit Decisions onto Existing Code
+
+You are helping the developer bootstrap DLD in an existing codebase by generating decision records from what the code already does. The goal is **not** 100% decision coverage — it's to create enough scaffolding that the DLD workflow feels natural for future development.
+
+## Interaction style
+
+Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user rather than waiting for freeform replies.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`.
+
+This skill uses: `next-id`, `create-decision`, `update-status`, `regenerate-index`.
+
+## Prerequisites
+
+1. Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+2. There should be existing application code in the repository. If the repo is empty or only has boilerplate, suggest `/dld-decide` or `/dld-plan` instead.
+
+## Read project context
+
+1. Read `dld.config.yaml` for project structure (flat vs namespaced, decisions directory)
+2. Read `decisions/PRACTICES.md` if it exists
+3. Check for any existing decisions — retrofit can be run alongside existing decisions
+
+## Step 1: Analyze the codebase
+
+Perform a broad analysis of the codebase:
+- Identify the main components, modules, and domain areas
+- Note the tech stack, frameworks, and key dependencies
+- Identify architectural patterns in use (layered architecture, domain-driven modules, etc.)
+- Look for non-obvious implementation choices — these are the best candidates for decisions
+
+Present a brief summary to the user:
+
+> **Codebase analysis:**
+> - [Tech stack summary]
+> - [N] main components/modules identified: [list]
+> - [Notable patterns or architectural choices observed]
+
+## Step 2: Determine scope
+
+Ask the user:
+
+> Would you like to retrofit the **entire codebase**, or focus on a **specific area**?
+
+If a specific area, ask them to identify it (a directory, module, or domain concept). Narrow the analysis scope accordingly.
+
+## Step 3: Choose granularity
+
+Explain the two modes and ask the user to choose:
+
+> **Broad mode** — Creates high-level decisions covering major features and components. Produces file-level references only (e.g., `path: src/billing/service.ts`). Good for getting started quickly with a general decision scaffold.
+>
+> **Detailed mode** — Creates finer-grained decisions covering specific behaviors and design choices. Produces method-level references and annotations (e.g., `symbol: calculateVAT`). Takes longer but creates richer traceability from the start.
+>
+> Which mode would you like to use?
+
+## Step 4: Identify decisions
+
+### System-framing decisions (always include these first)
+
+Before diving into implementation details, identify **foundational decisions that frame the system itself**. These establish the context that all other decisions hang on:
+
+- **System purpose** — What is this service/application and why does it exist? What problem does it solve? (e.g., "Auth integration microservice bridging platform accounts to Firebase Auth")
+- **Core domain model** — What are the key domain concepts and their relationships? (e.g., "Multi-provider account linking with one primary identity per provider")
+- **Key integration boundaries** — What external systems does this interact with and how? (e.g., "Dual Firebase integration: Admin SDK for backend, REST API for OOB flows")
+
+These framing decisions may not map to a single function — they often reference the application entry point, main service interface, or core domain model files. Without them, the projected OVERVIEW.md would read as a collection of implementation details with no narrative anchor.
+
+Aim for 1-3 framing decisions depending on the system's complexity. Ask the user to help articulate these — they capture the kind of high-level context that's hardest to infer from code alone.
+
+### Implementation-level decisions
+
+Then identify decisions at the implementation level. Focus on:
+
+- **Architectural choices** — why the code is structured this way (module boundaries, layer patterns, data flow)
+- **Non-obvious implementation details** — retry logic, caching strategies, validation approaches, error handling patterns
+- **Domain rules** — business logic that encodes specific rules or policies
+- **Technology choices** — framework selection, library usage, storage approach
+- **Trade-offs** — places where the code chose one approach over alternatives
+
+**Broad mode:** Aim for 1-2 decisions per major component or feature area. Each decision should cover a significant chunk of functionality.
+
+**Detailed mode:** Aim for decisions wherever there's a meaningful "why" behind the code. Still don't try to cover everything — focus on the decisions a future developer (or AI agent) would most benefit from knowing about.
+
+**Ask when unsure:** If you encounter code that looks like a deliberate design choice but you can't confidently infer the rationale, ask the user. These are often the most valuable decisions to capture — the ones where the "why" isn't obvious from the code alone. For example:
+
+> I see the order service retries with a 7-second delay and max 3 attempts. Is there a specific reason for these values, or is it a general resilience pattern?
+
+Don't ask about everything — focus on cases where the implementation seems intentionally specific and the rationale would be lost without human input.
+
+Present the proposed decisions as a numbered list, with framing decisions first:
+
+> **Proposed decisions:**
+>
+> *System framing:*
+> 1. **[System purpose/identity]** — [what this system is and why it exists]
+>    - Affects: `src/Application.ts` (or equivalent entry point)
+> 2. **[Core domain model]** — [key concepts and relationships]
+>    - Affects: `src/models/Account.ts`, `src/models/Identity.ts`
+>
+> *Implementation decisions:*
+> 3. **[Title]** — [one-line summary]
+>    - Affects: `src/path/to/code.ts`
+> 4. **[Title]** — [one-line summary]
+>    - Affects: `src/path/to/other.ts`
+> ...
+>
+> Want me to proceed with all of these, remove any, or adjust?
+
+Let the user review and adjust the list before proceeding.
+
+## Step 5: Generate decision records
+
+For each approved decision:
+
+1. Read the relevant code to understand what it does and infer the rationale
+2. Write the decision record with Context, Decision, and Rationale sections. The **Context** should describe the problem the code solves. The **Decision** should describe what the code does. The **Rationale** should be your best inference of *why* — acknowledge when you're inferring rather than stating known facts (e.g., "likely chosen because..." or "this approach avoids...").
+3. Include a Consequences section only when trade-offs are apparent from the code
+4. Assign sequential IDs using `next-id`
+5. Create each record using `create-decision`
+
+```bash
+ID=$(node "<skill-dir>/../dld-common/scripts/dld.mjs" next-id)
+printf "## Context\n\n...\n\n## Decision\n\n...\n\n## Rationale\n\n..." | node "<skill-dir>/../dld-common/scripts/dld.mjs" create-decision \
+  --id "$ID" \
+  --title "Title" \
+  --tags "tag1, tag2" \
+  --body-stdin
+```
+
+## Step 6: Add annotations and references
+
+For each decision, add `@decision(DL-NNN)` annotations to the relevant code:
+
+- **Broad mode:** Annotate at the file/module level — typically at the top of the file or on the main export/class.
+- **Detailed mode:** Annotate at the function/method/class level where the decision is embodied.
+
+Then update each decision record's `references` field directly in the YAML frontmatter with the annotated code paths and symbols.
+
+## Step 7: Mark as accepted
+
+Since the code already exists, these decisions go directly to `accepted` status:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" update-status DL-NNN accepted
+```
+
+Do this for each generated decision.
+
+## Step 8: Regenerate INDEX.md
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
+```
+
+## Step 9: Summary and next steps
+
+> **Retrofit complete:**
+> - Created **N** decisions (DL-XXX through DL-YYY)
+> - Added **M** `@decision` annotations across the codebase
+> - Mode: [broad/detailed]
+> - Scope: [entire codebase / specific area]
+>
+> These decisions capture the current state of the codebase — not every design choice, but enough to establish a working decision scaffold.
+>
+> Next steps:
+> - Review the generated decisions for accuracy — especially the inferred rationale
+> - `/dld-snapshot` — generate SNAPSHOT.md and OVERVIEW.md from the new decisions
+> - `/dld-decide` — record new decisions as you make changes going forward
+> - `/dld-retrofit` — run again on other areas if you scoped to a specific component