From 2f9fbc3131c72a3d4aa4f38dc11806377a146200 Mon Sep 17 00:00:00 2001 From: Mark Phelps Date: Sun, 13 Sep 2026 12:35:16 +0000 Subject: [PATCH] feat: add decision-records skill --- README.md | 8 +- development/.codex-plugin/plugin.json | 19 +- development/AGENTS.md | 7 + development/README.md | 24 ++- development/skills/decision-records/SKILL.md | 202 +++++++++++++++++++ skills/decision-records/SKILL.md | 202 +++++++++++++++++++ 6 files changed, 442 insertions(+), 20 deletions(-) create mode 100644 development/skills/decision-records/SKILL.md create mode 100644 skills/decision-records/SKILL.md diff --git a/README.md b/README.md index 339c7a4..ea6a738 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,10 @@ Reusable agent plugins and skills following AGENTS/skills conventions. ## Plugins -| Plugin | Description | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------- | -| [vault](./vault/) | Zettelkasten-style vault workflows for Obsidian notes | -| [development](./development/) | Agent context, PR fixups, CLI design, OSS readiness and marketing, session log audits, and self-hosted runners | +| Plugin | Description | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| [vault](./vault/) | Zettelkasten-style vault workflows for Obsidian notes | +| [development](./development/) | Agent context, PR fixups, CLI design, OSS readiness and marketing, session log audits, decision records, and self-hosted runners | ## Layout diff --git a/development/.codex-plugin/plugin.json b/development/.codex-plugin/plugin.json index 7129bc4..dacf645 100644 --- a/development/.codex-plugin/plugin.json +++ b/development/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "development", - "version": "0.0.4", - "description": "Developer workflow skills for agent context, PR fixups, CLI design, OSS readiness, OSS marketing, session log audits, and GitHub Actions self-hosted runners.", + "version": "0.0.5", + "description": "Developer workflow skills for agent context, PR fixups, CLI design, OSS readiness, OSS marketing, session log audits, decision records, and GitHub Actions self-hosted runners.", "author": { "name": "Mark Phelps" }, @@ -29,13 +29,17 @@ "github-actions", "self-hosted-runner", "ci", - "systemd" + "systemd", + "decision-records", + "adr", + "architecture-decision-record", + "design-docs" ], "skills": "./skills/", "interface": { "displayName": "Development", - "shortDescription": "Agent context, PR fixup, CLI design, OSS readiness, OSS marketing, session log audit, and self-hosted runner workflows", - "longDescription": "Development workflow skills for auditing agent context files, fixing existing GitHub PRs, designing humane command-line interfaces, preparing GitHub repos for open source release, sharpening OSS README positioning, mining local agent session logs for papercuts in your own tools, and running GitHub Actions self-hosted runners on a Linux host.", + "shortDescription": "Agent context, PR fixup, CLI design, OSS readiness, OSS marketing, session log audit, decision records, and self-hosted runner workflows", + "longDescription": "Development workflow skills for auditing agent context files, fixing existing GitHub PRs, designing humane command-line interfaces, preparing GitHub repos for open source release, sharpening OSS README positioning, mining local agent session logs for papercuts in your own tools, writing and maintaining decision and plan records (ADRs), and running GitHub Actions self-hosted runners on a Linux host.", "developerName": "Mark Phelps", "category": "Development", "capabilities": ["Read", "Write"], @@ -52,7 +56,10 @@ "Audit my agent session logs for papercuts in this project and rank the fixes.", "Why do I keep working around my own tool? Check the last week of sessions.", "Install a GitHub Actions self-hosted runner for this repository on this Linux host.", - "Add a second repository runner to this machine and verify it is listening." + "Add a second repository runner to this machine and verify it is listening.", + "Write a decision record for switching our job queue to Postgres.", + "Supersede record 012 with a new plan and update the registry.", + "Set up a docs/records directory with a registry README for this repo." ] } } diff --git a/development/AGENTS.md b/development/AGENTS.md index 0a2fb8c..a60589a 100644 --- a/development/AGENTS.md +++ b/development/AGENTS.md @@ -20,6 +20,9 @@ agent context. Command Line Interface Guidelines from clig.dev - `context-file-tuneup`: audit and rewrite `CLAUDE.md` / `AGENTS.md` files so they stay short, specific, and grounded in the repo +- `decision-records`: write or update decision and implementation-plan records + (ADRs) in a repo's records directory, keep the registry table in sync, and + preserve history through amendments and supersession - `github-pr-fixup`: check out an existing GitHub PR branch, address active unresolved review comments and failing CI, then push fixes back to that PR - `github-self-hosted-runner`: install, register, namespace, verify, or remove @@ -48,5 +51,9 @@ agent context. user or home directory, keep one namespaced instance per target, treat tokens as secrets that never reach a file that persists, and confirm no job is running before you stop, replace, or delete an instance. +- For decision records, the registry `README.md` is the contract. Read it and + the related records before writing. Never rewrite an existing record's + history; add a dated amendment or a superseding record instead. Ask before + bootstrapping a records directory in a repo that has none. - Do not manually restore removed development skills in top-level `skills/`. Run `npm run sync` so the generated mirror matches `development/skills/`. diff --git a/development/README.md b/development/README.md index 84189fa..9658228 100644 --- a/development/README.md +++ b/development/README.md @@ -2,19 +2,21 @@ Developer workflow skills for repo-facing agent context, GitHub PR follow-up, command-line interface design, open source release preparation, audits of your -own agent session logs, and GitHub Actions self-hosted runners. +own agent session logs, decision records, and GitHub Actions self-hosted +runners. ## Skill Set -| Skill | What It Does | When to Invoke | -| --------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `cli-design` | Designs and reviews command-line interfaces using clig.dev guidance. | When creating CLI commands, flags, help text, output contracts, error messages, or destructive workflows. | -| `context-file-tuneup` | Audits, rewrites, and tightens `CLAUDE.md` / `AGENTS.md` context files. | When reviewing, shrinking, restructuring, or improving agent context. | -| `github-pr-fixup` | Addresses unresolved GitHub PR review comments and failing CI on the existing source branch. | When a user gives you an existing PR URL and wants review feedback or CI failures fixed without a new PR. | -| `github-self-hosted-runner` | Installs, registers, verifies, or removes namespaced GitHub Actions self-hosted runners on a Linux host. | When a user gives a repository or organization URL and wants a persistent runner managed by systemd. | -| `oss-marketing` | Sharpens README and public-doc positioning for first-time visitors. | When a repo needs launch copy, clearer positioning, or a README that explains what the project is. | -| `oss-repo-readiness` | Audits and prepares a repo for open source release, focused on developer experience. | When making a repo public, writing CONTRIBUTING or issue templates, or running a pre-launch checklist. | -| `session-log-audit` | Mines local agent session logs for papercuts and produces a ranked fix list. | When the user wants to know what is annoying about their own tool, or why they work around it. | +| Skill | What It Does | When to Invoke | +| --------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `cli-design` | Designs and reviews command-line interfaces using clig.dev guidance. | When creating CLI commands, flags, help text, output contracts, error messages, or destructive workflows. | +| `context-file-tuneup` | Audits, rewrites, and tightens `CLAUDE.md` / `AGENTS.md` context files. | When reviewing, shrinking, restructuring, or improving agent context. | +| `decision-records` | Writes and maintains decision and plan records (ADRs) and their registry table, preserving history. | When recording an architecture, product, design, or dependency decision, amending or superseding a record, or starting a records directory. | +| `github-pr-fixup` | Addresses unresolved GitHub PR review comments and failing CI on the existing source branch. | When a user gives you an existing PR URL and wants review feedback or CI failures fixed without a new PR. | +| `github-self-hosted-runner` | Installs, registers, verifies, or removes namespaced GitHub Actions self-hosted runners on a Linux host. | When a user gives a repository or organization URL and wants a persistent runner managed by systemd. | +| `oss-marketing` | Sharpens README and public-doc positioning for first-time visitors. | When a repo needs launch copy, clearer positioning, or a README that explains what the project is. | +| `oss-repo-readiness` | Audits and prepares a repo for open source release, focused on developer experience. | When making a repo public, writing CONTRIBUTING or issue templates, or running a pre-launch checklist. | +| `session-log-audit` | Mines local agent session logs for papercuts and produces a ranked fix list. | When the user wants to know what is annoying about their own tool, or why they work around it. | ## Notes @@ -34,6 +36,8 @@ own agent session logs, and GitHub Actions self-hosted runners. contribution mechanics; marketing covers first-visit clarity and conversion. - Session log audits need a project the user built with agents and used recently. Every finding must carry a dated receipt from a real session. +- Decision records are historical evidence. Preserve IDs, filenames, and past + decisions; add amendments or superseding records rather than editing history. - Self-hosted runner work is destructive on a live machine. Create one instance per registration target, never print or persist the token, and check for running jobs before you stop, replace, or remove a runner. diff --git a/development/skills/decision-records/SKILL.md b/development/skills/decision-records/SKILL.md new file mode 100644 index 0000000..154e721 --- /dev/null +++ b/development/skills/decision-records/SKILL.md @@ -0,0 +1,202 @@ +--- +name: decision-records +description: + Write or update decision and implementation-plan records in a repository's + records directory (usually `docs/records/`, also known as ADRs, decision logs, + or design docs). Use for architecture, product, design, privacy, security, + dependency, delivery, or other durable project decisions. Use when creating a + record, changing a record's status, writing an amendment, superseding a + record, updating the record registry, or bootstrapping a records directory in + a repo that has none. +--- + +# Project records + +A records directory is a repository's durable registry for decisions and +implementation plans. A record explains what the team decided, why, and what +follows from that decision. Records are historical evidence: they are appended +to and amended, not rewritten. + +Do not use a record for a routine code change, a temporary task, a release note, +or an investigation without a durable outcome. + +## Find the records directory + +1. Look for an existing registry, in this order: `docs/records/`, `docs/adr/`, + `docs/decisions/`, `adr/`, `decisions/`, or any directory that contains a + `README.md` with a table of numbered records. Check the project's + `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, or `CLAUDE.md` for a pointer. +2. If a registry exists, its `README.md` is the contract. It is the authority + for ID format, filename pattern, frontmatter, status vocabulary, and required + headings. Follow it even where it differs from the defaults below. +3. If no registry exists, ask the user whether to create one. If they agree, + create `docs/records/README.md` from the template in "Bootstrap a registry" + before writing the first record. + +## Read first + +1. Read the registry `README.md` completely. +2. Read the records that relate to the work. +3. Read the product, design, or architecture source that defines the facts. +4. If a record conflicts with newer evidence, preserve the record's history and + record the correction or new decision. Do not edit the old text in place. + +Do not copy a legacy record's errors into a new record. When a legacy record and +the registry contract disagree, the contract wins. + +## Create a record + +Create a record only after the decision or plan has a clear scope. Ask for +missing product or technical facts before you invent them. + +1. Find the next unused ID in the registry table. Default format is a global + three-digit number (`001`, `002`, ...). Never reuse or skip an ID. +2. Name the file `-.md`. +3. Add the exact frontmatter contract from the registry README. Keep every list + key, even when the list is empty. +4. Use `kind: decision` for a durable choice. Use `kind: plan` for committed, + outcome-based work. +5. New decisions start as `proposed` until accepted. New plans start as + `planned` until work begins. Use another valid status only when the current + state differs. +6. Set `date` and `updated` to the creation date. Use ISO dates (`YYYY-MM-DD`). +7. Start with the six required headings, in this order: + - `## Intent` + - `## Context` + - `## Record` + - `## Consequences` + - `## Validation / Current state` + - `## Related records` +8. Add the new row to the registry table in the README. + +The table row is part of the change. Keep its ID, title, kind, status, date, +supersession, and related-record fields aligned with the record's frontmatter. + +### Default frontmatter + +Use this when the registry README does not define its own: + +```yaml +--- +id: 007 +title: Short title +kind: decision # decision | plan +status: proposed # see "Status rules" +date: 2026-09-13 +updated: 2026-09-13 +supersedes: [] +superseded_by: [] +related: [] +--- +``` + +## Write the sections + +Write factual, direct prose in plain English. Use the project's own terms, +matching the related records. Prefer short sentences and concrete nouns over +abstractions. If the repo has a writing-style skill or guide, apply it. + +### Intent + +State the user or project outcome. State what the record makes possible or +protects. Do not repeat implementation detail here. + +### Context + +State the facts, constraints, research, risks, and alternatives that shaped the +choice. Link evidence (issues, PRs, benchmarks, docs) when it is useful. Mark +assumptions and open questions as such. + +### Record + +State the decision or plan precisely. Use numbered items when the contract has +several rules. Name scope boundaries and required behavior. For a plan, make the +desired outcome and completion evidence clear. + +### Consequences + +State costs, tradeoffs, follow-up work, and intentionally deferred work. Do not +present a consequence as a requirement unless the record commits to it. + +### Validation / Current state + +State the current, observable status. For completed work, name the evidence: +tests, checks, measurements, or human acceptance. For proposed or active work, +state what remains. Do not claim that work shipped or passed unless the evidence +exists. + +### Related records + +Use this form: + +```md +**Supersedes:** None. + +**Related:** + +- [005 — Short title of record 005](005-short-title.md) +``` + +Use relative links. Keep the frontmatter ID lists in the same order as the links +in this section. + +## Update a record + +A record is historical evidence. Preserve its ID, filename, creation date, and +past decisions. + +- Change `updated` only for a substantive content change. +- Change `status` only to a value valid for the record kind. +- Add a dated `## Amendment (YYYY-MM-DD) — ` for a later decision, + correction, or material scope change. Put it after the existing material. +- Update `## Validation / Current state` when new evidence changes the status. +- Create a new record when a decision or plan is fully replaced. Put the old IDs + in the new record's `supersedes`, set the old record's status to `superseded` + and its `superseded_by`, and update the registry rows. +- Use `related`, not `supersedes`, for a dependency, coordinated work, or a + partial refinement. +- Never silently rewrite history to make an old decision look current. + +A superseded record stays in the registry. Do not renumber, delete, or reuse its +ID. + +## Status rules + +Default vocabulary, unless the registry README defines its own: + +- Decisions: `proposed`, `accepted`, `superseded`, `rejected`. +- Plans: `planned`, `active`, `completed`, `blocked`, `superseded`, `rejected`. + +A status tells the truth about the record. It does not predict the desired +outcome. + +## Bootstrap a registry + +Only when the user agrees to create one. Write `docs/records/README.md` with: + +1. A one-paragraph statement of what belongs in a record and what does not. +2. The ID and filename pattern. +3. The frontmatter contract (copy the default above). +4. The status vocabulary per kind. +5. The six required headings in order. +6. An empty registry table with these columns: + `ID | Title | Kind | Status | Date | Supersedes | Related`. + +Keep the README short. It is a contract, not a guide. + +## Final review + +Before you finish: + +1. Make sure that the new ID is unique and matches the filename. +2. Make sure that the frontmatter has every required key and valid values. +3. Make sure that the required headings exist in the required order. +4. Make sure that every linked or listed record ID exists. +5. Make sure that `supersedes` means full replacement. +6. Make sure that the registry row and frontmatter agree. +7. Read the record as a future maintainer. Remove vague promises and unsupported + claims. +8. Run `git diff --check`. If the repo has a Markdown linter or link checker, + run it on the changed files. + +Do not run the app build or test suite for a records-only change. diff --git a/skills/decision-records/SKILL.md b/skills/decision-records/SKILL.md new file mode 100644 index 0000000..154e721 --- /dev/null +++ b/skills/decision-records/SKILL.md @@ -0,0 +1,202 @@ +--- +name: decision-records +description: + Write or update decision and implementation-plan records in a repository's + records directory (usually `docs/records/`, also known as ADRs, decision logs, + or design docs). Use for architecture, product, design, privacy, security, + dependency, delivery, or other durable project decisions. Use when creating a + record, changing a record's status, writing an amendment, superseding a + record, updating the record registry, or bootstrapping a records directory in + a repo that has none. +--- + +# Project records + +A records directory is a repository's durable registry for decisions and +implementation plans. A record explains what the team decided, why, and what +follows from that decision. Records are historical evidence: they are appended +to and amended, not rewritten. + +Do not use a record for a routine code change, a temporary task, a release note, +or an investigation without a durable outcome. + +## Find the records directory + +1. Look for an existing registry, in this order: `docs/records/`, `docs/adr/`, + `docs/decisions/`, `adr/`, `decisions/`, or any directory that contains a + `README.md` with a table of numbered records. Check the project's + `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, or `CLAUDE.md` for a pointer. +2. If a registry exists, its `README.md` is the contract. It is the authority + for ID format, filename pattern, frontmatter, status vocabulary, and required + headings. Follow it even where it differs from the defaults below. +3. If no registry exists, ask the user whether to create one. If they agree, + create `docs/records/README.md` from the template in "Bootstrap a registry" + before writing the first record. + +## Read first + +1. Read the registry `README.md` completely. +2. Read the records that relate to the work. +3. Read the product, design, or architecture source that defines the facts. +4. If a record conflicts with newer evidence, preserve the record's history and + record the correction or new decision. Do not edit the old text in place. + +Do not copy a legacy record's errors into a new record. When a legacy record and +the registry contract disagree, the contract wins. + +## Create a record + +Create a record only after the decision or plan has a clear scope. Ask for +missing product or technical facts before you invent them. + +1. Find the next unused ID in the registry table. Default format is a global + three-digit number (`001`, `002`, ...). Never reuse or skip an ID. +2. Name the file `-.md`. +3. Add the exact frontmatter contract from the registry README. Keep every list + key, even when the list is empty. +4. Use `kind: decision` for a durable choice. Use `kind: plan` for committed, + outcome-based work. +5. New decisions start as `proposed` until accepted. New plans start as + `planned` until work begins. Use another valid status only when the current + state differs. +6. Set `date` and `updated` to the creation date. Use ISO dates (`YYYY-MM-DD`). +7. Start with the six required headings, in this order: + - `## Intent` + - `## Context` + - `## Record` + - `## Consequences` + - `## Validation / Current state` + - `## Related records` +8. Add the new row to the registry table in the README. + +The table row is part of the change. Keep its ID, title, kind, status, date, +supersession, and related-record fields aligned with the record's frontmatter. + +### Default frontmatter + +Use this when the registry README does not define its own: + +```yaml +--- +id: 007 +title: Short title +kind: decision # decision | plan +status: proposed # see "Status rules" +date: 2026-09-13 +updated: 2026-09-13 +supersedes: [] +superseded_by: [] +related: [] +--- +``` + +## Write the sections + +Write factual, direct prose in plain English. Use the project's own terms, +matching the related records. Prefer short sentences and concrete nouns over +abstractions. If the repo has a writing-style skill or guide, apply it. + +### Intent + +State the user or project outcome. State what the record makes possible or +protects. Do not repeat implementation detail here. + +### Context + +State the facts, constraints, research, risks, and alternatives that shaped the +choice. Link evidence (issues, PRs, benchmarks, docs) when it is useful. Mark +assumptions and open questions as such. + +### Record + +State the decision or plan precisely. Use numbered items when the contract has +several rules. Name scope boundaries and required behavior. For a plan, make the +desired outcome and completion evidence clear. + +### Consequences + +State costs, tradeoffs, follow-up work, and intentionally deferred work. Do not +present a consequence as a requirement unless the record commits to it. + +### Validation / Current state + +State the current, observable status. For completed work, name the evidence: +tests, checks, measurements, or human acceptance. For proposed or active work, +state what remains. Do not claim that work shipped or passed unless the evidence +exists. + +### Related records + +Use this form: + +```md +**Supersedes:** None. + +**Related:** + +- [005 — Short title of record 005](005-short-title.md) +``` + +Use relative links. Keep the frontmatter ID lists in the same order as the links +in this section. + +## Update a record + +A record is historical evidence. Preserve its ID, filename, creation date, and +past decisions. + +- Change `updated` only for a substantive content change. +- Change `status` only to a value valid for the record kind. +- Add a dated `## Amendment (YYYY-MM-DD) — ` for a later decision, + correction, or material scope change. Put it after the existing material. +- Update `## Validation / Current state` when new evidence changes the status. +- Create a new record when a decision or plan is fully replaced. Put the old IDs + in the new record's `supersedes`, set the old record's status to `superseded` + and its `superseded_by`, and update the registry rows. +- Use `related`, not `supersedes`, for a dependency, coordinated work, or a + partial refinement. +- Never silently rewrite history to make an old decision look current. + +A superseded record stays in the registry. Do not renumber, delete, or reuse its +ID. + +## Status rules + +Default vocabulary, unless the registry README defines its own: + +- Decisions: `proposed`, `accepted`, `superseded`, `rejected`. +- Plans: `planned`, `active`, `completed`, `blocked`, `superseded`, `rejected`. + +A status tells the truth about the record. It does not predict the desired +outcome. + +## Bootstrap a registry + +Only when the user agrees to create one. Write `docs/records/README.md` with: + +1. A one-paragraph statement of what belongs in a record and what does not. +2. The ID and filename pattern. +3. The frontmatter contract (copy the default above). +4. The status vocabulary per kind. +5. The six required headings in order. +6. An empty registry table with these columns: + `ID | Title | Kind | Status | Date | Supersedes | Related`. + +Keep the README short. It is a contract, not a guide. + +## Final review + +Before you finish: + +1. Make sure that the new ID is unique and matches the filename. +2. Make sure that the frontmatter has every required key and valid values. +3. Make sure that the required headings exist in the required order. +4. Make sure that every linked or listed record ID exists. +5. Make sure that `supersedes` means full replacement. +6. Make sure that the registry row and frontmatter agree. +7. Read the record as a future maintainer. Remove vague promises and unsupported + claims. +8. Run `git diff --check`. If the repo has a Markdown linter or link checker, + run it on the changed files. + +Do not run the app build or test suite for a records-only change.