Capture an architectural decision from the current conversation as an ADR
From agonpx claudepluginhub eyev0/ago --plugin ago[title or topic]/write-adrInteractively creates an Architecture Decision Record (ADR) in docs/adr/ using Michael Nygard format, gathering context, options, decision, consequences, and status; auto-numbers sequentially.
/write-adrFull Architecture Decision Record with alternatives, consequences, and review trigger
/write-adrCreate an Architecture Decision Record (ADR) through an interactive process with the Architect sub-agent. ADRs capture important technical decisions with their context, alternatives considered, and consequences — ensuring institutional memory persists beyond any individual's involvement.
You are executing the ago:write-adr command. This command captures an architectural decision from the current conversation context and writes it as an ADR file with status "To Review".
This command does NOT require .workflow/ — it works with any project that has a docs/ directory.
Argument: $ARGUMENTS (optional title or topic hint for the ADR).
Check for ADR files in these locations:
docs/adr/*.mddocs/decisions/*.mdIf ADRs exist, note the highest ADR number in use (e.g., if 018-*.md exists, the next ADR is 019). If no ADRs exist, the next number is 001.
Also read docs/adr/README.md if it exists to understand the index format.
Read the following if they exist:
CLAUDE.md — project instructionsREADME.md — project overviewStore a brief summary of the project's purpose and tech stack.
From the current conversation context, identify the decision being made and draft an ADR.
If $ARGUMENTS is provided, use it as a hint for the ADR title/topic. If not, infer from the conversation.
If the conversation does not contain a clear decision (no alternatives discussed, no trade-offs weighed), tell the user: "I couldn't identify a clear decision in our conversation. Can you describe what you decided and why?" Wait for their response.
Draft the ADR:
# ADR-{NNN}: {Title}
**Status:** To Review
**Date:** {YYYY-MM-DD}
## Context
{Why this decision came up — extracted from the conversation. What problem or question was being discussed.}
## Decision
{What was decided — the specific choice made.}
## Alternatives Considered
{What other options were discussed and why they were rejected. If only one option was discussed, note "No alternatives were explicitly discussed."}
## Consequences
### Positive
- {What becomes easier or better}
### Negative
- {What becomes harder or worse}
### Risks
- {What could go wrong}
Present the draft to the user:
Here's the ADR I formulated from our discussion:
{draft}
Look good? (yes / edit)
Wait for user approval or edits. If the user provides edits, incorporate them and re-present.
Create docs/adr/ directory if it doesn't exist. Create docs/ directory if it doesn't exist.
Write the ADR to docs/adr/{NNN}-{kebab-case-title}.md.
If docs/adr/README.md exists, append the new ADR to its index table, matching the existing format exactly. If it doesn't exist, do NOT create one.
Report:
Created: docs/adr/{NNN}-{kebab-case-title}.md (Status: To Review)
Check whether the decision implies implementation work (code changes, new components, refactoring). If the ADR is purely informational (e.g., a naming convention, a process decision), skip the bridge and end with:
ADR saved. Run `ago:audit-docs` to validate consistency with existing documentation.
If implementation work is implied, present the bridge:
## Ready to plan?
ADR saved: `docs/adr/{NNN}-{title}.md` (To Review)
Based on this decision, here's the context for implementation planning:
**Artifacts:**
- `docs/adr/{NNN}-{title}.md`
{- `docs/research/YYYY-MM-DD-{topic}.md` (if a related research artifact exists)}
{- `docs/audit/YYYY-MM-DD-audit.md` (if a recent audit exists)}
**Decision:** {1-line summary}
**Key constraints:**
- {from Consequences section — most impactful items}
**Suggested pipeline:** brainstorming → writing-plans → implementation
Want to start brainstorming with this context?
[yes / adjust context / not now]
superpowers:brainstorming skill. Pass the context block above as the starting point. Brainstorming will read the referenced files itself.ago:audit-docs will flag it for review if it stays unaccepted for >4 days..workflow/ dependency. Uses only docs/ and conversation context.