Menu
Create/list Architecture Decision Records. Triggers: "create an ADR" | "architecture decision" | "document why we chose" | "list ADRs".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Set up local dev environment — stack.yml, CLAUDE.md Critical Rules, docs scaffolding, LSP. Triggered by /dev-init or standalone /env-setup. Triggers: "env setup" | "setup environment" | "configure stack" | "scaffold rules".
Populate scaffolded architecture/standards docs with real content extracted from CLAUDE.md and codebase analysis — fills TODO stubs, writes AI Quick Reference sections. Triggers: "seed docs" | "bootstrap docs" | "populate docs" | "fill architecture docs" | "seed architecture".
Initialize project — orchestrates env-setup, ci-setup, release-setup + axial ADR. Use when setting up a new repo or re-running Roxabi project init. Triggers: "dev-init" | "setup project" | "initialize project" | "/dev-init". Not the harness built-in /init (CLAUDE.md scaffold only).
Promote staging→main — pre-flight, version bump, changelog, PR & tag. Triggers: "promote staging" | "release" | "deploy" | "cut a release" | "--finalize" | "merge to main" | "promote to production" | "ship a release" | "tag and release" | "publish release".
Set up CI/CD — GitHub Actions workflows, TruffleHog, Dependabot, pre-commit hooks, marketplace plugins. Triggers: "ci setup" | "setup ci" | "configure ci" | "setup hooks" | "setup github actions".
Health check — verify dev-core config, GitHub project, labels, workflows, branch protection, secret scanning, CI hardening. Triggers: "checkup" | "health check" | "check setup" | "verify config" | "security baseline".
| name | adr |
| description | Create/list Architecture Decision Records. Triggers: "create an ADR" | "architecture decision" | "document why we chose" | "list ADRs". |
Let:
D := docs/architecture/adr/
NNN := zero-padded 3-digit sequence number
AQ := ask user
ADR_GLOB := {NNN}-*.md + legacy {NNN}-*.mdx (read only)
Create and manage ADRs — document why technical choices were made.
Write format: always Markdown (.md). Legacy .mdx ADRs are still readable for list/scan; never write new .mdx.
/adr "Title" → Create mode
/adr --list → List mode
1. Next NNN: Scan D for {NNN}-*.md and legacy {NNN}-*.mdx → highest + 1. ¬D ∨ ¬files → create D, start at 001.
2. Resolve title: ∃ title in $ARGUMENTS → use. ¬title → AQ.
3. Interview: AQ (1–2 calls, ≤3 questions). Skip if clear from title:
| Topic | Ask |
|---|---|
| Context | What problem prompted this decision? |
| Options | What alternatives were considered? (≥2, key pros/cons each) |
| Decision | Which was chosen and why? |
| Consequences | Positive, negative, neutral trade-offs? |
4. Write ADR: D/{NNN}-{slug}.md (slug = kebab-case title).
---
title: "ADR-{NNN}: {Title}"
description: {one-line summary}
---
## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-XXX}
## Context
{What is the issue? Why does this decision need to be made?}
## Options Considered
### Option A: {Name}
- **Pros:** {advantages}
- **Cons:** {disadvantages}
### Option B: {Name}
- **Pros:** {advantages}
- **Cons:** {disadvantages}
## Decision
{What was decided and why.}
## Consequences
### Positive
- {benefit}
### Negative
- {trade-off}
### Neutral
- {side effect}
Default status: Accepted unless stated otherwise. Min 2 options.
5. Confirm: Inform: file path, NNN + title, status.
Scan D for .md and legacy .mdx files. ¬∃ → inform + suggest /adr "Title".
∃ → ∀ file: read frontmatter for title, status, date. Sort by NNN ascending.
Architecture Decision Records
══════════════════════════════
# │ Title │ Status │ Date
001 │ Fastify over Express │ Accepted │ 2025-03-15
002 │ Bun as runtime │ Accepted │ 2025-04-01
003 │ REST over GraphQL │ Deprecated│ 2025-04-10
| Scenario | Behavior |
|---|---|
| First ADR ever | Create D from scratch |
| ¬title provided | AQ before proceeding |
| Superseding an ADR | Update old status to Superseded by ADR-{NNN}; reference old in new context |
Legacy .mdx present | Include in NNN scan + list; new ADRs still write .md |
Same NNN as both .md and .mdx | Prefer .md for display; do not write over either |
$ARGUMENTS