orange-dot/lab-ai-tooling/adr-workflow

Claude Code and agent skill by orange-dot/lab-ai-tooling

Trust tier 3
  • community
Source check pending

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-workflow

SKILL.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

  1. 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.

  1. Find the template. 0000-template.md, template.md, or the

first existing ADR. Use it verbatim for new ADRs — do not invent sections.

  1. Pick the next number. max(existing) + 1, four-digit

zero-padded. Refuse to reuse a retired number.

  1. Title slug. Kebab-case, ≤ 60 chars, no leading articles.
  2. 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).

  1. Index update. docs/adrs/index.md (or README) gets a new

entry on the same change.

  1. 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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/orange-dot/lab-ai-tooling/adr-workflow/badge)](https://verified-skill.com/skills/orange-dot/lab-ai-tooling/adr-workflow)

Something wrong with this skill or its page? Tell us.