orange-dot/lab-ai-tooling/adr-workflow
Claude Code and agent skill by orange-dot/lab-ai-tooling
- community
Checking that the SKILL.md file is still in the repository.
Author or update an Architecture Decision Record per the project's declared ADR process and keep `docs/adrs/index.md` current. Use when proposing, accepting, superseding, or revisiting an architecture decision in any lab project that uses ADRs.
Install
npx vskill@latest install orange-dot/lab-ai-tooling/adr-workflowSKILL.md
The same SKILL.md was published earlier as orange-dot/lab-ai-tooling/adr-workflow.
adr-workflow
What it does
Several lab projects (notably mamut-platform, parts of pc4-microkit-studio, and the studio docs) use ADRs. This skill walks the user through writing or updating one without inventing a process — it follows whatever the project's own docs/adrs/index.md or 0000-template.md declares.
Inputs
- The project root (auto-detected from the working directory or
passed in).
- Optional: an existing ADR number to update or supersede.
Procedure
- Find the ADR root.
docs/adrs/,docs/decisions/, or
architecture/decisions/. If none exists and the user is proposing a new ADR in a project without ADRs, surface that and ask before scaffolding a new convention.
- Find the template.
0000-template.md,template.md, or the
first existing ADR. Use it verbatim for new ADRs — do not invent sections.
- Pick the next number.
max(existing) + 1, four-digit
zero-padded. Refuse to reuse a retired number.
- Title slug. Kebab-case, ≤ 60 chars, no leading articles.
- Status. New ADR opens as
Proposed. Acceptance is a separate
commit/PR. Superseding requires editing both the old ADR (status → Superseded by NNNN) and the new one (Supersedes NNNN).
- Index update.
docs/adrs/index.md(or README) gets a new
entry on the same change.
- Cross-references. Numbered narrative docs that motivated the
ADR link to it; the ADR's Context section names them.
Authoring rules
- One decision per ADR. If two decisions are entangled, write two
ADRs and link them.
- Concrete context: what real change motivated this? Vague ADRs rot.
- Concrete consequences: list what becomes possible and what becomes
forbidden after acceptance.
- Reversibility: note the cost of unwinding.
Output
The skill produces or edits the ADR file and the index entry. It does not auto-commit.
Related
linux-audio-docs-linter— broader docs discipline.bilingual-pair-diff— for projects with EN/SR ADR pairs.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingclaude/lab/skills/adr-workflow/SKILL.md
Popularity
- 7-day trend score
- 5
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/orange-dot/lab-ai-tooling/adr-workflow)