Author, update, and manage Skillset ADRs. Use when creating new ADRs, promoting drafts, updating the ADR index, renaming or renumbering ADRs, or when the user mentions ADR, architecture decision, or decision record.
Author, update, and manage Skillset ADRs. Use when creating new ADRs, promoting drafts, updating the ADR index, renaming or renumbering ADRs, or when the user mentions ADR, architecture decision, or decision record.
metadata
{"generated":"skillset@0.1.0","version":"0.1.0"}
name
skillset-adrs
Skillset ADR Authoring
ADRs document the significant design decisions behind Skillset: choices that, if reversed, would change the source contract, target rendering model, compiler promises, or authoring workflow.
Core Principles
Read docs/tenets.md before writing or changing an ADR. Every ADR must be consistent with the tenets, or it must explicitly argue for changing them.
Use these tenets as the review lens:
Source-first loadouts. Authors write portable source once, then Skillset renders it faithfully to target-native provider output.
Source is the product. Skillset source is the authored truth; generated provider trees are reproducible renderings.
One meaning, one key. Portable source keys should describe one semantic concept, not duplicate provider vocabulary.
Render intent, not filenames. Near matches are modeled from the author's intended outcome, then rendered in the target-native way.
Target truth beats fake portability. Unsupported target behavior must be visible through diagnostics, opt-outs, or explicit target-native escape hatches.
Builds do not imply trust. Build output may define plugins, hooks, skills, and instructions, but activation is separate.
Drift should become visible early. Stale output, unsupported destination, malformed locks, and unmanaged destination collisions should surface before runtime surprises, with reversible backups where confirmed builds replace existing files.
When an ADR proposes something new, test it against these questions. Does it reduce repeated authoring? Does it preserve target-native truth? Does it make unsupported behavior easier to see? Does it keep activation separate from compilation?
Before Writing
Read related ADRs before drafting. Use docs/adrs/decision-map.json or browse docs/adrs/ and docs/adrs/drafts/ to find records that touch similar concerns. Good ADRs build on the existing decision graph: they reference specific sections of prior ADRs, link to their headings, and explain how the new decision compounds with, specializes, or supersedes what is already decided.
When your ADR relates to an existing one:
Link to it in References with a one-line description of the relationship.
Link to specific headings when referencing a particular decision.
Explain whether you are extending, specializing, or building on the prior decision.
If you contradict a prior ADR, call that out explicitly and use the supersedes mechanism.
Script
All ADR operations go through the skill-local scripts/adr.ts helper when available.
Destructive commands preview by default. Pass --yes to apply changes.
# Create a new draft (applies immediately because it is non-destructive)
bun scripts/adr.ts create --title "Compile Target Selection"# Preview a promote, then apply
bun scripts/adr.ts promote compile-target-selection
bun scripts/adr.ts promote compile-target-selection --yes# Update title, slug, status, or number
bun scripts/adr.ts update source-first-loadouts --title "Source-First Loadouts"
bun scripts/adr.ts update 013 --renumber 0013
bun scripts/adr.ts update compile-target-selection --slug compile-targets
bun scripts/adr.ts update compile-targets --status proposed --yes# Demote a numbered ADR back to drafts
bun scripts/adr.ts demote 0014 --yes# Auto-fix common issues (number padding, cross-refs)
bun scripts/adr.ts fix
bun scripts/adr.ts fix --yes# Validate format and consistency
bun scripts/adr.ts check
# Regenerate decision maps and draft index
bun scripts/adr.ts map
The script handles file creation, git moves, title/slug/number updates, index rebuilding, decision-map generation for numbered and draft ADRs, and cross-reference updates.
depends_on accepts numbered ADR IDs and draft slugs (the filename without date prefix and .md). Use integers for numbered ADRs and slugs for drafts. The decision map renders these as graph edges.
amends records a narrow change to one or more existing accepted decisions without replacing their historical body or status. Authors may declare it while the successor is a draft or numbered proposal, but targets must be accepted, numbered ADRs; draft slugs are not valid amendment identities. The relationship becomes active only when the successor is accepted. Decision maps preserve the authored amends list and derive the reciprocal amended_by list; never author amended_by directly.
Use supersedes when the successor replaces the earlier decision as a whole. Supersession marks the predecessor superseded and records superseded_by; accepted later replacements, including recursively evidenced supersession chains, preserve previously accepted amendment history. A bare status: superseded edit or a proposed/rejected replacement is not acceptance-history evidence. Amendment leaves predecessor source unchanged.
Content
Minimal ADR
# ADR-NNNN: Descriptive Title## Context
What problem, tension, or drift prompted the decision.
## Decision
What we chose and why. Include concrete source or output examples when they make the decision clearer.
## Consequences
What this enables, what it constrains, and what remains open.
## References- [Tenets](../tenets.md) - governing design principles.
Detailed ADR
# ADR-NNNN: Descriptive Title## Context## Decision
The decision in one declarative sentence.
### Focused Subsection
Use subsections when the reasoning has distinct parts.
## Non-Goals
What this ADR is not trying to solve.
## Consequences### Positive
What this enables.
### Tradeoffs
Known costs or constraints we accept.
### Risks
Uncertain outcomes we are watching, with mitigation.
## Non-Decisions
Explicitly deferred decisions.
## References
Reference Format
For numbered ADRs:
- [ADR-NNNN: Title](NNNN-slug.md) - one-line relationship
For draft ADRs:
- ADR: Title (draft) - one-line relationship
For docs:
- [Doc title](../path.md) - one-line relationship
Style Guide
Voice
Declarative, not tentative. State the decision. If there is uncertainty, name it as a risk or non-decision.
Conversational but precise. Write like a sharp maintainer explaining what future agents and contributors must preserve.
Active voice. Skillset derives, renders, validates, rejects, and explains. Authors declare, opt out, and review.
First person sparingly. Use it in Context when grounding the problem in real experience. Drop it in Decision.
Structure
Context tells a story. Start with the pressure that made the decision necessary, not abstract background.
Decision subsections start with a one-sentence thesis. The first sentence should stand alone as a summary.
Show the concrete failure. Explain what breaks without the decision: duplicated config, silent target skips, fake portability, stale output, or unsafe activation.
Code examples are primary evidence. Source and generated-output snippets often explain the contract better than prose.
Claims must be backed up. Reference code, docs, ADRs, official docs, or live verification. If you cannot back a claim, soften or remove it.
Patterns To Use
"This means:" lists after a principle.
"The test:" heuristics that future agents can apply.
Good/Bad examples for contract shape.
Tables for structured tradeoffs.
Footnotes for external references.
Heading links for internal cross-references.
Patterns To Avoid
No hedging.
No restating the title.
No wall-of-text paragraphs.
No future benefit claims without present justification.
No "as mentioned above"; link directly.
No disparaging other tools or agent surfaces.
No numbered headings; descriptive headings preserve stable markdown anchors.
Consequences Style
Positive items are capabilities, not restatements.
Tradeoffs are honest. Name what we gave up.
"What this does NOT decide" is useful to future authors. Be specific and explain why it is deferred.
Vocabulary
Use accepted Skillset vocabulary consistently:
source, not generated output, when discussing .skillset/.
target or provider, not runtime, when discussing provider build destinations.
render/rendering, not copying, when source intent becomes target-native output.
rendered output, not source truth, for generated provider files.
compile.targets, not bare targets, for root provider selection.
compile.unsupportedDestination, not silent fallback, for unsupported destination policy.
provenance, not comments, for lock/status evidence.
Read docs/tenets.md before writing. Every ADR must be consistent with the tenets.
Tone Calibration
Read the draft aloud. If it sounds like a corporate design document, rewrite it. If it sounds like a blog post, tighten it. The target is the precision of a spec with the readability of a well-written README: someone who knows the domain deeply explaining the reasoning to someone who will have to live with the consequences.
