# Adr

> WHAT — Create and maintain Architecture Decision Records (ADRs) per the process. Covers when

- **Type:** Skill
- **Install:** `agentstack add skill-ulises-jeremias-agent-toolkit-adr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ulises-jeremias](https://agentstack.voostack.com/s/ulises-jeremias)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ulises-jeremias](https://github.com/ulises-jeremias)
- **Source:** https://github.com/ulises-jeremias/agent-toolkit/tree/main/plugins/agent-toolkit-complete/.github/skills/adr
- **Website:** https://ulises-jeremias.github.io/agent-toolkit-archive/

## Install

```sh
agentstack add skill-ulises-jeremias-agent-toolkit-adr
```

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

## About

# ADR — Architecture Decisions (WHAT)

**Template:** `references/default-template.md` — local reference for ADR structure and workflow.

## Default guardrails (before any final content)

1. Apply **`output-handshake`**: confirm **where** the final ADR will be recorded and that a **human** will review.
2. Then follow the steps below.

## When to use

Use **`decision-log`** for lightweight product/project/operational decisions and **`agreement`** for explicit commitments or terms among parties. Use this ADR skill only for durable architecture or technical decisions.

- A change has **long-term** architectural, security, data-model, or cost impact.
- You need **options with pros/cons** and a **record** for future readers (and for supersession later).
- The project needs decisions linked to PRDs, TRDs, tasks, PRs, diagrams, or other supporting artifacts.

## Instructions

0. **Match existing convention first** (per `addyosmani/agent-skills` `documentation-and-adrs` 2026-08-12, diff `docs/research/diff-394-documentation-and-adrs.md`): inspect `docs/adr/` (or `Documentation/Decisions/`, MADR, `adr-tools` `.adr-dir`) — location/format (Markdown vs reStructuredText), numbering/naming (`0004-*.md` vs `ADR-004-*.rst`), section headings. Surface conflict rather than silently introducing another scheme. Only when no convention can be established, default to `docs/adr/000N-*.md` six-part structure.

1. **Confirm the decision qualifies** (new service, tech selection, schema change, deployment change, etc.) per the "When to Create an ADR" criteria.
2. **Draft** using the six-part structure: Title & status, Context, Options, Decision, Consequences, References (link **PRD/TRD**, tasks, PRs, diagrams as applicable). Use lifecycle `PROPOSED → ACCEPTED → (SUPERSEDED | DEPRECATED)` and **don't delete old ADRs** — when decision changes, write new ADR that references and supersedes old (per upstream 2026-08-12).
3. **Review** with the tech lead / peers as in the workflow; keep ADRs **short and actionable** (clarity over completeness).
4. **Link** the ADR to the relevant **epic or story** and to **PRs** in the forge (use **`github-cli-workflow` / `gitlab-cli-workflow`** for PR text when applicable).
5. If an ADR is **superseded**, **preserve history**: update status and point to the replacement document.

### Red flags & verification (after documenting)

* **No ADR for significant architectural choices** — every expensive-to-reverse decision needs one.
* **README missing quick start / architecture overview**, API without types, rules files (`CLAUDE.md`/`AGENTS.md`) stale, commented-out code, week-old `TODO`s, or docs that restate code.
* Verify: ADRs exist, README covers quick start/commands/architecture (link ADRs), API docs have types, gotchas inline, no commented-out code, `personas/` (HOW agent thinks) vs `skills/` (HOW task executes) preserved — see `docs/CONCEPTS.md`.

## What not to do

- Do not use an ADR for one-line fixes with no long-term effect (use a normal task or PR description).
- Do not paste the full org policy into this skill; keep a single **canonical** copy in the wiki.

## References

- `output-handshake` — destination and review
- `references/default-template.md` — ADR structure and workflow
- `references/example-001-graphql-adoption.md` — example ADR for a GraphQL migration decision
- `trd` — where technical design references decisions
- `decision-log` — lightweight decisions
- `agreement` — explicit commitments or terms
- `workflow-generic-project` — traceability and plan approval
- `clickup-cli`, `jira-*` — ticket and comment operations (per engagement)

## Source & license

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

- **Author:** [ulises-jeremias](https://github.com/ulises-jeremias)
- **Source:** [ulises-jeremias/agent-toolkit](https://github.com/ulises-jeremias/agent-toolkit)
- **License:** MIT
- **Homepage:** https://ulises-jeremias.github.io/agent-toolkit-archive/

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-ulises-jeremias-agent-toolkit-adr
- Seller: https://agentstack.voostack.com/s/ulises-jeremias
- 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%.