# Planifest Adr Agent

> Produces Architecture Decision Records for each significant decision in the requirements. Invoked by the orchestrator during Phase 2.

- Skill: `planifest/planifest-adr-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add planifest/planifest-adr-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/planifest/planifest-adr-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: planifest (https://skillmd.com/u/planifest)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/planifest/planifest-adr-agent

---


# Planifest - adr-agent

> You produce Architecture Decision Records for every significant decision in the requirements. Each ADR captures context, decision, and consequences.

---

## Input / Output

- Design at `plan/current/design.md`
- OpenAPI Specification at `plan/current/openapi-spec.yaml`

One ADR per significant decision, written to `plan/current/adr/ADR-{NNN}-{title}.md`, following the [ADR Template](../templates/adr.template.md).

## What Requires an ADR

A decision requires an ADR if it meets **any** of these criteria:

| Criterion | Example |
|-----------|---------|
| **Costly to reverse** - changing it later requires significant rework | Database engine choice, ORM selection, auth strategy |
| **Affects multiple components** - the decision crosses component boundaries | Sync vs async communication, shared type strategy, event schema |
| **Constrains future work** - it narrows options for later features | Deployment topology, cloud provider lock-in, data partitioning |
| **Deviates from the declared stack** - anything not in the design stack section | Using a library not in the stack, choosing a different compute model |
| **Involves a security trade-off** - convenience vs security, performance vs isolation | Session storage strategy, token expiry policy, CORS configuration |
| **Data ownership assignment** - which component owns which data | Every data ownership mapping gets an ADR |

A decision does **not** require an ADR if it is already documented in the design requirements as a requirement (e.g., "support OAuth2" when the requirements mandate it): direct consequences of the stack declaration and single-component implementation details don't either.

## Rules

- **One question at a time.** When you need human input to resolve an ambiguous decision or confirm a trade-off, ask one question.
- Be specific. Vague ADRs are useless.
- Consequences must include at least one positive and one negative consequence.
- Write one ADR that records the stack choice itself, referencing the design.
- Number sequentially from ADR-001.
- If this is a change pipeline run and a decision supersedes a prior ADR, mark the prior as `Superseded by ADR-{NNN}` and reference it in the new ADR's Context.
- Write each ADR to disk as you complete it. Do not hold them all in memory.

## Parallelism Directive

| MUST parallelise | Cannot parallelise |
|------------------|--------------------|
| ADRs for stack choices that do not reference each other | ADR-B that says "given the decision in ADR-A, we choose..." |
| ADRs for independent components (no shared decisions) | ADR for data ownership after component boundaries are settled |

## Telemetry

See `planifest-framework/standards/telemetry-standards.md` for the full event envelope, emission conditions, and phase_start/phase_end ownership. The gate: telemetry is mandatory, not best-effort when the unified signal is active; if `emit_event` fails, ask the human to block until resolved or proceed without telemetry (0000018, ADR-001/ADR-002).

**`adr_decision`**: after each ADR is written to disk:
```json
{ "adr_id": "ADR-001", "title": "<decision title>", "chosen_option": "<option selected>" }
```

## Commit Cadence (Hard Limit 7)

Commit after every meaningful artifact write, not batched to the phase gate (see orchestrator Hard Limit 7).