dld-kit 1.0.0-rc.1

package/templates/skills/dld-retrofit/SKILL.md

@@ -0,0 +1,178 @@
+---
+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.
+---
+
+# /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
+
+{{dld-setup}}
+
+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=$({{dld}} next-id)
+printf "## Context\n\n...\n\n## Decision\n\n...\n\n## Rationale\n\n..." | {{dld}} 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
+{{dld}} update-status DL-NNN accepted
+```
+
+Do this for each generated decision.
+
+## Step 8: Regenerate INDEX.md
+
+```bash
+{{dld}} 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

package/templates/skills/dld-snapshot/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: dld-snapshot
+description: Generate SNAPSHOT.md (detailed decision reference) and OVERVIEW.md (narrative synthesis with diagrams) from the decision log.
+compatibility: Requires Node.js 20+ and git.
+---
+
+# /dld-snapshot — Generate Spec Projection
+
+You are generating documents that project the current state of the decision log into readable formats. The two built-in documents are always generated:
+
+1. **`decisions/SNAPSHOT.md`** — Detailed per-decision reference. Every active decision with its rationale and code references.
+2. **`decisions/OVERVIEW.md`** — High-level narrative synthesis with Mermaid diagrams. The document you'd hand to someone who needs to understand the system.
+
+If the project's `dld.config.yaml` defines `snapshot_artifacts`, additional custom documents are generated as well (see Step 5).
+
+## Commands
+
+{{dld-setup}}
+
+This skill uses: `detect-snapshot-changes`, `collect-active-decisions`, `update-snapshot-state`.
+
+## Prerequisites
+
+Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+
+There must be at least one `accepted` decision. If all decisions are `proposed`, tell the user there's nothing to snapshot yet and suggest `/dld-implement`.
+
+Check for uncommitted changes to decision files. Run `git status --porcelain -- <decisions_dir>/records/` and inspect the output. If there are unstaged or staged-but-uncommitted decision files, commit them first with a message like `"Update decision records"` before proceeding. This ensures the change detection script can rely on git history. Tell the user you are committing pending decision changes.
+
+## Step 1: Determine update mode
+
+If the user's message includes `--full` (e.g., `/dld-snapshot --full`), skip change detection and use **full mode** for all documents.
+
+Otherwise, run:
+
+```bash
+{{dld}} detect-snapshot-changes
+```
+
+This outputs:
+- `mode: full` — no prior snapshot state exists, or SNAPSHOT.md/OVERVIEW.md are missing. Proceed with full generation.
+- `mode: incremental` — prior state exists. The output also includes:
+  - `new_decisions:` — comma-separated list of new accepted decision IDs (e.g., `DL-072, DL-073`)
+  - `modified_decisions:` — comma-separated list of existing decisions changed since last snapshot (status changes, content edits)
+  - `commit_range:` — the git range since last snapshot (e.g., `abc1234..HEAD`)
+
+If mode is `incremental` but both `new_decisions` and `modified_decisions` are empty, tell the user nothing has changed since the last snapshot and stop.
+
+## Step 2: Collect active decisions
+
+```bash
+{{dld}} collect-active-decisions
+```
+
+This outputs the full content of all `accepted` decisions, separated by `===DLD_DECISION_BOUNDARY===` markers. Parse the output to extract each decision's frontmatter and body. Use the project mode from `dld.config.yaml` (already checked in prerequisites) to determine the organization strategy.
+
+## Step 3: Generate or update SNAPSHOT.md
+
+### Full mode
+
+Write `decisions/SNAPSHOT.md` from scratch using the template and rules below.
+
+### Incremental mode
+
+Read the existing `decisions/SNAPSHOT.md` and apply targeted edits:
+
+1. **For each new decision:** Identify which group heading (`## Namespace` or `## Tag Group`) it belongs to. Insert the new `### DL-NNN: Title` section in the correct position (ascending ID order within the group). If the group heading doesn't exist yet, add a new `## Group` section.
+2. **For each modified decision:** Read its current status from the decision file.
+   - If now `superseded` or `deprecated`: remove its `### DL-NNN` section from the file. If the group becomes empty after removal, remove the group heading too.
+   - If still `accepted` but content changed: replace its `### DL-NNN` section with updated content.
+   - If it has a new `amends` relationship: add an `*Amended by: DL-YYY*` line to the target decision's section.
+3. **Update the header:** Adjust the "Active decisions" count, the "DL-001 through DL-XXX" range, and the date.
+
+Do NOT rewrite the entire file. Use targeted edits to insert, remove, or modify only the affected sections.
+
+### Template
+
+```markdown
+# System Snapshot
+
+> Auto-generated from the decision log on YYYY-MM-DD. Do not edit manually.
+> Use `/dld-snapshot` to regenerate. Source of truth: individual decision records.
+>
+> **Active decisions:** N (DL-001 through DL-XXX, excluding superseded/deprecated)
+
+---
+
+## <Namespace or Tag Group>
+
+### DL-NNN: <Title>
+*Supersedes: DL-XXX* ← only if applicable
+*Amends: DL-XXX* ← only if applicable
+*Amended by: DL-YYY* ← only if another decision amends this one
+
+<The Decision section from the record — what was decided. Copy verbatim or lightly condense.>
+
+**Rationale:** <1-3 sentence summary of the Rationale section. Condense, don't copy verbatim.>
+
+**Code:** `<path>` → `<symbol>`, `<path>`
+
+---
+
+### DL-NNN: <Title>
+...
+```
+
+### Organization rules
+
+**Namespaced projects:** Primary grouping by namespace. Within each namespace, decisions listed by ID ascending (oldest first — they build on each other).
+
+**Flat projects:** Group by tag. Decisions with multiple tags appear under their first/primary tag. Decisions with no tags go under a "General" section. Within each group, decisions listed by ID ascending.
+
+### Content rules
+
+- Only include `accepted` decisions
+- Skip `superseded`, `deprecated`, and `proposed` decisions entirely
+- When a decision supersedes another (check the `supersedes` field in the YAML frontmatter), include a `*Supersedes: DL-XXX*` note
+- When a decision amends another (check the `amends` field), include an `*Amends: DL-XXX*` note on the amending decision and an `*Amended by: DL-YYY*` note on the original decision
+- The **Decision** section content should be copied directly or lightly condensed — this is the authoritative statement
+- The **Rationale** should be condensed to 1-3 sentences — enough to understand *why*, not every detail
+- **Code** references should list paths and symbols from the frontmatter `references` field
+- If a decision has no Rationale section, omit the Rationale line
+- If a decision has no references, omit the Code line
+
+## Step 4: Generate or update OVERVIEW.md
+
+This is fundamentally different from SNAPSHOT.md. You are **synthesizing** across decisions to create a readable narrative that explains the system's current design. Think of it as the document you'd give a new team member or use to onboard an AI agent on the project.
+
+### Full mode
+
+Write `decisions/OVERVIEW.md` from scratch using the template and guidelines below.
+
+### Incremental mode
+
+Read the existing `decisions/OVERVIEW.md`. Identify which domain sections are affected by the new and modified decisions — look at their namespaces, tags, and the topics they cover. Then:
+
+1. **Update only the affected sections.** Rewrite each affected section to integrate new decisions or remove references to superseded/deprecated ones. Leave unaffected sections untouched.
+2. **Add new sections** if new decisions introduce a domain area not covered by existing sections.
+3. **Update diagrams** only if the changeset affects the relationships or components they depict.
+4. **Update the header** (decision count, date) and **Key Technical Choices** if any new decisions are cross-cutting.
+
+**Maintaining appropriate abstraction:** The overview should remain a high-level narrative, not grow into a detailed specification. As you update sections, consider whether the overall document still reads as an overview. If adding new decisions makes a section too detailed or the document too long, condense older stable content to make room — summarize established decisions more aggressively to keep focus on what matters for understanding the system. If the document's section structure no longer properly organizes the content (e.g., a new cross-cutting concern spans multiple existing sections), restructure as needed — this may mean a larger rewrite of the document, which is appropriate when the system's shape has meaningfully changed.
+
+### Template
+
+```markdown
+# System Overview
+
+> Auto-generated narrative synthesis from N active decisions. Last updated YYYY-MM-DD.
+> This document is derived from individual decision records — do not edit manually.
+> Use `/dld-snapshot` to regenerate.
+
+## Architecture Overview
+
+<If there are enough architectural decisions to warrant it, include a high-level Mermaid diagram showing key components and their relationships. Base this on the code references and decision content.>
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+```
+
+## <Namespace or Domain Area>
+
+<Narrative prose synthesizing the decisions in this area. Write in present tense.
+Explain what the system does and why, weaving together multiple decisions into
+a coherent story. Reference decision IDs parenthetically, e.g., (DL-012).>
+
+<If the decisions in this area describe a flow or process, include a Mermaid diagram:>
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant PaymentGateway
+    ...
+```
+
+<Continue with other areas...>
+
+## Decision Relationships
+
+<Only include this section if there are supersession chains, amendment relationships, or closely related decision groups.
+If no decisions supersede or amend others and there are no meaningful relationship clusters, omit this section entirely.>
+
+```mermaid
+graph LR
+    DL-003 -->|superseded by| DL-012
+    DL-012 -.->|amends| DL-005
+    DL-012 -.->|related| DL-014
+```
+
+## Key Technical Choices
+
+<Bullet-point summary of the most impactful cross-cutting decisions that don't
+belong to a single area. E.g., "PostgreSQL for primary data store (DL-001)",
+"All API input validated with Zod schemas (DL-008)".>
+```
+
+### Narrative guidelines
+
+- **Write prose, not lists.** The snapshot already provides the structured listing. The overview should read like a design document.
+- **Synthesize, don't enumerate.** Don't just list decisions — explain how they fit together. "The billing system uses banker's rounding for EU VAT calculations (DL-012), replacing the earlier truncation approach that caused reconciliation failures."
+- **Use present tense.** Describe what the system *does*, not what was decided.
+- **Reference decision IDs parenthetically.** Every claim should be traceable: "(DL-012)" after the relevant statement.
+- **Include Mermaid diagrams where they add clarity.** Good candidates:
+  - Architecture/component diagrams when decisions span multiple components
+  - Sequence diagrams when decisions describe flows or protocols
+  - Relationship diagrams when there are supersession chains or amendment relationships
+  - Don't force diagrams if the decisions are simple or unrelated
+- **Keep it proportional.** A project with 5 decisions needs a short overview. A project with 50 needs more structure. Scale the document to the content.
+- **Group by namespace (namespaced projects) or by domain theme (flat projects).** For flat projects, identify natural domain groupings from tags and decision content.
+
+### Diagram guidelines
+
+When creating Mermaid diagrams:
+- Use `graph TD` or `graph LR` for architecture/component/relationship diagrams
+- Use `sequenceDiagram` for flow/protocol diagrams
+- Use `flowchart` for process/workflow diagrams
+- Keep diagrams focused — show the relationships that decisions actually govern, not a complete system map
+- Label edges with the nature of the relationship
+- Reference relevant decision IDs in node labels or notes where helpful
+- **Always quote node labels** with `["..."]` to avoid parse errors from special characters
+- **Escape `@` as `#64;`** inside node labels and edge labels — raw `@` breaks Mermaid parsing
+- **Use `<br/>` for line breaks** inside quoted labels — do not use `\n` or literal newlines
+- **Avoid special characters** (`(`, `)`, `[`, `]`, `{`, `}`, `|`, `#`, `&`) in unquoted labels — use quoted labels or HTML entities instead
+
+## Step 5: Generate custom artifacts
+
+Read the `snapshot_artifacts` key from `dld.config.yaml`. If the key is absent or the list is empty, skip this step entirely.
+
+For each entry in `snapshot_artifacts`:
+
+1. **Validate the `title`:**
+   - Must end in `.md`. If not, warn the user and skip this artifact.
+   - Must not collide (case-insensitive) with reserved filenames: `SNAPSHOT.md`, `OVERVIEW.md`, `INDEX.md`. If it collides, warn the user and skip this artifact.
+
+2. **Generate `decisions/<title>`** using the collected decisions (from Step 2) as context and the `prompt` field as the generation instruction. The file must begin with this standard header:
+
+   ```markdown
+   # <Title without .md extension>
+
+   > Auto-generated from the decision log on YYYY-MM-DD. Do not edit manually.
+   > Use `/dld-snapshot` to regenerate.
+   ```
+
+   Followed by the content generated according to the prompt.
+
+Keep track of which custom artifacts were successfully generated — you will need the list for Step 6 and Step 7.
+
+## Step 6: Update snapshot state
+
+Pass any successfully generated custom artifact filenames as arguments:
+
+```bash
+{{dld}} update-snapshot-state [ARTIFACT_NAME...]
+```
+
+For example, if custom artifacts `ONBOARDING.md` and `API-CONTRACTS.md` were generated:
+
+```bash
+{{dld}} update-snapshot-state ONBOARDING.md API-CONTRACTS.md
+```
+
+If no custom artifacts were generated, run without arguments:
+
+```bash
+{{dld}} update-snapshot-state
+```
+
+## Step 7: Suggest next steps
+
+> Snapshot generated:
+> - `decisions/SNAPSHOT.md` — detailed reference (N active decisions)
+> - `decisions/OVERVIEW.md` — narrative synthesis with diagrams
+> - `decisions/<ARTIFACT>.md` — <one line per custom artifact generated, if any>
+>
+> Next steps:
+> - Review the generated documents for accuracy
+> - `/dld-decide` — record new decisions
+> - `/dld-audit` — check for drift between decisions and code

package/templates/skills/dld-status/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: dld-status
+description: Quick overview of the decision log state — counts by status, recent decisions, and run tracking info.
+compatibility: No external dependencies.
+---
+
+# /dld-status — Decision Log Overview
+
+You are generating a quick overview of the decision log state for the developer.
+
+## Files read
+
+This skill runs no commands. It reads decision files and state files directly:
+- `dld.config.yaml` — project configuration (decisions directory, mode)
+- `decisions/records/DL-*.md` — all decision records (scan YAML frontmatter for status, tags, timestamp, namespace)
+- `decisions/.dld-state.yaml` — run tracking state for audit and snapshot (may not exist)
+
+## 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 (flat vs namespaced, decisions directory)
+2. Read all decision files in the records subdirectory (`decisions/records/`) to gather statistics
+
+## Generate the overview
+
+### 1. Count decisions by status
+
+Scan all `DL-*.md` files in the records subdirectory (`decisions/records/`, including namespace subdirectories). Read the `status` field from each file's YAML frontmatter. Count:
+- `proposed`
+- `accepted`
+- `deprecated`
+- `superseded`
+
+Present as:
+```
+## Decision Log Status
+
+| Status | Count |
+|--------|-------|
+| proposed | 3 |
+| accepted | 12 |
+| deprecated | 2 |
+| superseded | 1 |
+| **Total** | **18** |
+```
+
+### 2. Recent decisions
+
+Show the 5 most recent decisions (by timestamp), with ID, title, status:
+
+```
+## Recent Decisions
+
+| ID | Title | Status | Date |
+|----|-------|--------|------|
+| DL-018 | ... | proposed | 2026-03-07 |
+| DL-017 | ... | accepted | 2026-03-06 |
+| ...
+```
+
+### 3. Decisions by grouping
+
+**Namespaced projects:** Show decision counts per namespace.
+
+```
+## By Namespace
+
+| Namespace | Total | Proposed | Accepted |
+|-----------|-------|----------|----------|
+| billing | 8 | 1 | 7 |
+| auth | 5 | 2 | 3 |
+| shared | 5 | 0 | 5 |
+```
+
+**All projects:** If there are tags in use, show the most active tags (those with the most decisions):
+
+```
+## Active Tags
+
+| Tag | Decisions |
+|-----|-----------|
+| payment-gateway | 4 |
+| auth-refactor | 3 |
+```
+
+### 4. Run tracking info
+
+Read `decisions/.dld-state.yaml` if it exists. Report:
+- Last audit run time and commit hash
+- Last snapshot run time
+
+If the file doesn't exist, note that no audits or snapshots have been run yet.
+
+```
+## Run History
+
+- **Last audit:** 2026-03-06 at commit `a1b2c3d` (1 day ago)
+- **Last snapshot:** 2026-03-05 (2 days ago, covers through DL-015)
+```
+
+Or:
+```
+## Run History
+
+No audits or snapshots have been run yet. Use `/dld-audit` to check for drift.
+```
+
+### 5. Proposed decisions needing action
+
+If there are any `proposed` decisions, list them as a call to action:
+
+```
+## Pending Implementation
+
+These decisions are proposed but not yet implemented:
+- **DL-016**: Rate limiting strategy
+- **DL-017**: Cache invalidation approach
+- **DL-018**: Error response format
+
+Use `/dld-implement DL-NNN` to implement them.
+```