Skip to content

feat: add decision-records skill #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
markphelps merged 1 commit into from
Sep 13, 2026
Merged

feat: add decision-records skill #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
19 changes: 13 additions & 6 deletions development/.codex-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
},
Expand Down Expand Up @@ -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"],
Expand All @@ -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."
]
}
}
7 changes: 7 additions & 0 deletions development/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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/`.
24 changes: 14 additions & 10 deletions development/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
202 changes: 202 additions & 0 deletions development/skills/decision-records/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 `<id>-<short-kebab-case-title>.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) — <short title>` 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.
Loading
Loading