# Adr Writer

> Capture major technical decisions in an architecture decision record (ADR)

- **Type:** Skill
- **Install:** `agentstack add skill-brpaz-agent-skills-adr-writer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [brpaz](https://agentstack.voostack.com/s/brpaz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [brpaz](https://github.com/brpaz)
- **Source:** https://github.com/brpaz/agent-skills/tree/main/skills/adr-writer

## Install

```sh
agentstack add skill-brpaz-agent-skills-adr-writer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ADR Writer

Use this skill when the project needs a durable record of a major technical decision.

## When to Use

- A significant architectural or technology choice is being made
- A decision spans multiple code changes or will matter to future contributors
- You need to document rejected alternatives and their tradeoffs
- An existing ADR needs to be superseded with a new decision

## Purpose

Capture important technical decisions in `adr_directory` so future implementation work can understand the context, tradeoffs, and consequences.

Use an ADR for decisions that are broader than one code change and likely to matter again later.

## Good ADR Candidates

- architecture or subsystem boundaries
- database or persistence strategy
- authentication or authorization approach
- external integration strategy
- deployment or infrastructure pattern
- major shared abstractions
- consequential performance or reliability tradeoffs

## Avoid

- routine implementation details
- temporary coding tactics
- decisions that only affect one tiny local change
- rewriting history to make a decision look cleaner than it was

## Output Location

Write ADRs to `adr_directory`.

File name format:

```text
/0001-short-kebab-title.md
```

If ADRs already exist, continue the numbering.

## ADR Template

```md
# ADR 0001: Short Title

## Status
Proposed

## Context
What problem or pressure led to this decision?

## Decision
What are we deciding?

## Alternatives Considered
- Option A
- Option B

## Consequences
- Positive consequence
- Negative consequence
- Follow-up consequence

## Related Artifacts
- canonical PRD artifact
- related design doc, if any
- GitHub issue or PR
```

## Writing Rules

- keep it concise and durable
- explain why, not just what
- name the rejected alternatives when they matter
- record tradeoffs honestly
- prefer one ADR per major decision
- update status if a proposed decision later becomes accepted, superseded, or rejected

## Workflow Guidance

- read the related canonical PRD artifact, design doc, issue, plan, and any existing ADRs first
- avoid duplicating an existing ADR
- if a prior ADR is being changed, create a new ADR that supersedes it unless a minor edit is enough
- reference the ADR from the relevant issue or plan when appropriate

## Inputs

- `adr_directory` – target directory path for ADR files. If not provided, defaults to `docs/adr`.
- Description of the decision to record, including context, alternatives considered, and consequences

## Outputs

- A new numbered Markdown ADR file in `adr_directory` following the template format (e.g. `0001-short-kebab-title.md`)

## Examples

```
# Decision: use PostgreSQL instead of SQLite
adr_directory: docs/adr
```

Produces `docs/adr/0001-use-postgresql.md` with Status, Context, Decision, Alternatives, and Consequences sections.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [brpaz](https://github.com/brpaz)
- **Source:** [brpaz/agent-skills](https://github.com/brpaz/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-brpaz-agent-skills-adr-writer
- Seller: https://agentstack.voostack.com/s/brpaz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.