# adr-writer

Adopt this skill: https://proskills.md/skills/other/llopresto87-cypress-skills-adr-writer

Page: https://proskills.md/skills/other/llopresto87-cypress-skills-adr-writer
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/adr-writer/SKILL.md
size: 8014
upstream: https://github.com/llopresto87/cypress/blob/main/skills/adr-writer/SKILL.md

```text
---
name: adr-writer
description: Author an Architecture Decision Record that captures a non-obvious technical choice — its context, the decision, the consequences, the rejected alternatives, and the reversibility cost. Use whenever a non-trivial dependency is picked, a framework is chosen, a one-way door is opened, two specialists disagree and the orchestrator must pick, or anyone in a future session would ask "why did we do this?" An ADR exists so the answer is on disk, not in someone's head. Its lifecycle status lives in frontmatter in the schema's one vocabulary (proposed, accepted, open, deferred, hotfix, rejected, superseded, closed); superseding is a new ADR plus a status flip on the old — never an edit of its body.
id: skill.adr-writer
tier: 2
kind: skill
origin: seed
title: adr-writer — record non-obvious technical choices as short, superseded-never-edited ADRs
owns:
  - adr-writer.method
  - adr-writer.reversibility
  - adr-writer.numbering
requires:
peers:
  - skill.grill-planner
  - agent.architect
  - skill.humanizer
load_when:
  - "write an ADR"
  - "record an architecture decision"
  - "why did we choose this dependency or design"
  - "supersede an existing decision record, mark an ADR superseded"
  - "which ADRs are still open, hotfix, or deferred"
  - "ADR status: proposed, accepted, superseded_by"
  - "opening a one-way door decision"
  - "accepted risk, declined fix, or an owner-declared no-go area"
artifacts:
  - templates/adr.template.md
  - decisions/README.md
prevents: Choices whose reasoning exists only in the session that made them, so a later reader sees what was decided but not what was rejected or what reversing it would cost.
est_tokens: 2760
---

# adr-writer

ADRs (Architecture Decision Records) live in `docs/graph/decisions/` and
record every non-obvious technical choice. Each is a short, recorded
answer to "why did we pick this?"; a design doc is a different artifact.

This skill encodes the discipline of writing them well.

## When to apply this skill

- A new dependency is being committed to (the wiki page handles the
  *what*; the ADR handles the *why*).
- A framework, language, or platform is being chosen.
- A one-way door is being opened (data model, public API contract,
  vendor lock-in).
- A boundary between two services or modules is being drawn.
- Two specialists disagreed and the orchestrator picked an option.
- A bug post-mortem revealed an implicit decision that should have been
  explicit.
- A **T2 contained-lane** change made a real choice among options and
  owes its why-record (`tiers.contained-lane`). Write the short form:
  Context, Decision, Consequences, Reversibility, the sections that
  carry the why. Skip Alternatives when none were weighed, and say so in
  one line. A contained change whose why needs every section was
  misclassified: hand it back for T3.
- Anyone asks "why did we do it this way?" and the answer isn't in an
  existing ADR.

## ADR numbering and status

ADRs are numbered monotonically: `adr-NNNN-short-slug.md`. Find the next
free number in `docs/graph/decisions/` and in the index, because a
number can be taken without a file. Each number names one decision for
good, because citations outlive files.

A number allocated to a decision that is owed but not yet written (a
spec reserves it, or the owner has not ruled yet) gets an index row
marked reserved or owed, naming who owes the body. The index row is the
whole reservation, because a stub ADR file is fiction that satisfies a
linter. The reservation holds even when the decision is abandoned. Where
a program keeps more than one ADR series (one per repository, say), a
citation names the series as well as the number, so two ADRs with the
same number cannot be confused.

Status lives in **frontmatter**, in the schema's lifecycle vocabulary
(`docs/graph/_schema.md` §"Lifecycle status" is the home; read it for
the meanings):
`status: proposed | accepted | open | deferred | hotfix | rejected | superseded | closed`,
always with `status_date`, plus the companion the value requires:
`owner` while `open | hotfix | deferred`, `reopen_when` when `deferred`,
`status_evidence` when `closed`, `superseded_by` when `superseded`. The
body's `## Status` section is a pointer to the frontmatter; a body value
that disagrees is a lint failure
(`python3 docs/graph/status-register.py --root docs/graph`), the drift
the register exists to catch. An ADR is born `proposed` and becomes
`accepted` when the owner ratifies it (the grill.md §6 row); the base
values apply as the schema defines them: a "do nothing now" decision
parked behind a named trigger is `deferred` with `reopen_when`, a choice
taken under pressure that owes a proper decision is `hotfix` with an
`owner`.

To replace a decision, write a new ADR with a new number and
`status: accepted`, and set the old ADR's frontmatter to
`status: superseded` + `superseded_by: ADR-NNNN` + a fresh
`status_date`. A ratified ADR's body is never rewritten (the append-only
exception in `holistic-editing`). Besides the supersede flip it takes
one other change: when the decision stands but a fact in its context or
reasons proves false, or execution reached the decision by a route the
body does not describe, a dated `## Correction` is appended after the
body, stating the corrected fact with its evidence and a pointer, and
the text above it stays as written. When the decision itself moves,
supersede it. To see what is still owed:
`python3 docs/graph/status-register.py --by-kind adr --open --hotfix`
(add `--deferred` for parked decisions). The register is the query
surface; the index at `docs/graph/decisions/README.md` is the human
table.

## The template (4 sections that matter most)

Use `docs/graph/templates/adr.template.md`. Its frontmatter is the
status home (above); the four body sections that earn their keep:

### Context

What is the situation that forces a decision? Include the constraint
that makes "do nothing" not viable. Cross-link to grill.md and the
relevant spec.

Bad: "We need a database."

Good: "Spec SPEC-0003 requires submissions to persist across restarts.
Grill.md §4 caps p95 latency at 200ms and cost at $X/month. The current
implementation uses an in-memory map, which loses state on restart. We
need to choose a persistent store."

When the owner states how an external arrangement works (a partner
handles a class of requests, a contract covers a duty), record it as a
declaration attributed to them, in their words where they matter, and
name what it leaves open. Conclusions drawn from it, legal ones above
all, are `agent.legal`'s to reach against its corpus; until then the ADR
records the question as owed.

### Decision

What we have decided, in **one sentence**. Optionally a short paragraph
naming the central tradeoff. A sentence that holds several decisions is
several ADRs: split it.

Bad: "We'll use PostgreSQL."

Good: "We will persist submissions in PostgreSQL 16, using the managed
instance on platform X, accepting an additional ~$45/mo in exchange for
ACID guarantees and ecosystem maturity over the in-memory alternative."

### Consequences

What changes downstream. Be concrete:
- New constraints (e.g. "migrations now belong in `migrations/` and run
  on deploy").
- Migration or rewrite cost if reversed.
- Effect on the verification plan (new gates, integration tests against
  a test database).
- Effect on the wiki (new library to wikify: the database driver and the
  migration tool).

### Alternatives considered

For each rejected alternative: one paragraph naming the alternative and
the **concrete** reason it lost, because "not as good" tells the next
agent nothing.

Bad: "SQLite — not as good for our use case."

Good: "SQLite — rejected because grill.md §4 requires concurrent writes
from multiple workers; SQLite serializes them and would violate the
200ms p95 budget at the projected request rate."

## Reversibility tag

Every ADR tags reversibility as one of:

- **`reversible`**: can be changed
```

## File: README.md
upstream: https://github.com/llopresto87/cypress/blob/main/README.md

````text
# CYPRESS

## What CYPRESS is

CYPRESS is an installer that gives the AI coding [tool](DOCUMENTATION.md#term-tool) you already use a written way of working on your repository. It copies three kinds of file into the repository: instruction files, the method itself in Markdown, and a few small Python scripts that need only the standard library of Python 3.14 or newer. It is not a library your code imports, not a service and not a model. Installing only places those files; the work starts when you paste one prompt into a session of your tool, and that session reads your repository and builds its [knowledge graph](DOCUMENTATION.md#term-knowledge-graph): short linked notes about your project that later sessions open a few at a time instead of rereading the code.

From then on, the method in those files asks each session to size its process to the task's risk, to write a [specification](DOCUMENTATION.md#term-specification) before the code and a failing test wherever a test can catch something, and to hand steps that need a clean context to separate [agents](DOCUMENTATION.md#term-agent); the glossary's [skill](DOCUMENTATION.md#term-skill) entry says how an agent differs from a skill. Most of this is asked of the model, and only part of it is checked by a tool: [What it does not do](#what-it-does-not-do) says which part is which.

## Who it is for and not for

It is for developers who work in a code repository through a coding [harness](DOCUMENTATION.md#term-harness) the installer supports: Claude Code, Prime Agent, opencode, Codex or GitHub Copilot. Support is not the same on each: Claude Code, opencode (OpenCode 2) and Prime Agent are first-class, and Codex and GitHub Copilot are deprecated, installed only when you name them and given no new features. The [host capability matrix's support table](documentation/host-capability-matrix.md#support-tiers-adr-0009) and the host support decision records ([tiers](docs/decisions/adr-0009-host-support-tiers.md), [opencode](docs/decisions/adr-0033-opencode-first-class-on-opencode-2.md)) say what each level means.

The method assumes no language, framework or stack. The reference [corpora](DOCUMENTATION.md#term-corpus) that ship with it are narrower: the library notes lean toward .NET, Java and Node.js, and the legal citations cover one national jurisdiction. Both are placed in your project only when you ask: the library notes page by page, from a list the installer proposes, and the legal citations whole. The [corpora reference](documentation/corpora-and-integrations-reference.md) has the breakdown.

It is not for someone who does not use an AI coding [tool](DOCUMENTATION.md#term-tool), because nothing in the install acts until a session in that tool reads it.

## What installing does to your repository

An install for Claude Code writes the files below into your project. If one of them is already there and differs, your version is kept beside it as a timestamped copy before the new one replaces it, and nothing is merged.

- the [kernel](DOCUMENTATION.md#term-kernel), a short instruction file the harness reads at the start of every session: `CLAUDE.md` at the project root, with `AGENTS.md` beside it as a symlink to it (a copy where symlinks are unavailable); on the other harnesses, or where your project already has a plain `AGENTS.md` and no `CLAUDE.md`, `AGENTS.md` holds the kernel and `CLAUDE.md` is the symlink; with `--kernel-mode compose`, a team's own `AGENTS.md` stays as it is and `CLAUDE.md` imports it ahead of the kernel ([install guide](INSTALL.md#an-instruction-hub-your-team-already-keeps));
- the harness directory `.claude/`, holding the agent definitions, the [skills](DOCUMENTATION.md#term-skill), slash commands, hook scripts and settings;
- `docs/graph/`, where the knowledge graph lives: the method's own notes, and a skeleton that the first session fills in from your code, including `docs/graph/models.md`, where you name the model each host runs for each kind of work;
- the install stamp `.cypress/seed.json`, which records the version and options of the install and keeps any key the installer does not own, and beside it `.cypress/recreated-nodes.txt`, which lists the method's notes this install had to put back because they were missing;
- `EXPERT_SEED_INSTALL_PROMPT.md`, a local copy of the entry prompt for later sessions;
- the [source index](documentation/source-index.md) cache under `.cypress/source-index/`, which the install's last step builds from your code. Git ignores it through a `.gitignore` inside it. The install then prints a short report of what the index found and what you still need to set up, with the fix for each item.

Other harnesses get their own directory in place of `.claude/`, such as `.opencode/` or `.prime/agent/`, and the [install guide](INSTALL.md) lists each one.

A file that already matches is left alone. The install stamp `.cypress/seed.json` and the list beside it are replaced without a copy ([backup before replace](DOCUMENTATION.md#enf-backup-before-replace)). Files under `docs/graph/` that belong to your project, such as the graph's index, are only added where missing ([project files kept](DOCUMENTATION.md#enf-plant-files-kept)), with one exception: the installer rewrites the `plant:` entry of `docs/graph/index.md` in place, also without a copy. It adds the entry if it is absent and writes each value you pass on the command line into a line still left as a placeholder, keeping any value already declared.

The install does not touch your application source, `.gitignore`, git history or CI.

## What it costs

| Figure | What it covers, and how it was obtained |
|---|---|
| 67 065 bytes | per session on Claude Code: the kernel, the one-line description of every agent and skill, and the orchestrator's charter with its always-loaded nodes, computed from the [seed](DOCUMENTATION.md#term-seed)'s files by this repository's test run; a lower bound, not a live reading |
| 11% more tokens | per task, against a session with no method: 131 583 tokens against 118 973. The same run took 20% more tool calls (72 against 60) and 20% more wall-clock time (12 min 40 s against 10 min 32 s), and the run without the method found a defect that the run with the method missed. Measured once, on one small, well-specified task ([evidence record](docs/plans/grill-7.29.0-front-door/method-overhead-evidence.md)) |

The always-loaded figure leaves out the notes a session opens on demand, each worker it starts, the text the hooks add to each prompt, and the one-time pass that builds the graph. The [host capability matrix](documentation/host-capability-matrix.md) gives the figure for each other harness. No money figure exists.

## Try it

```sh
git clone https://github.com/llopresto87/Cypress
./Cypress/install.sh claude-code --project-dir /path/to/your/project
```

You need bash and Python 3.14 or newer; with no Python at that version on `PATH`, the installer stops before it writes anything. The clone takes whatever the default branch holds when you run it, not a tagged release. In the second command, put your repository's path in place of the placeholder. That command only places files; its last line says the files are placed and the project's graph is not built yet. Then open a session rooted at your project and paste [`INSTALL_PROMPT.md`](INSTALL_PROMPT.md) into it. That starts the one-time [growth](DOCUMENTATION.md#term-growth) pass, which reads your repository and builds its graph. None of these steps asks you to learn the project's vocabulary first.

On a first install, a harness may need a fresh session before it can start the agents that were just placed; the [delegation notes](core/method/delegation-bounds.md) record when, under `delegation.harness-registration`.

<!-- first-screen-end -->

## How it works

CYPRESS is a written [workflow](DOCUMENTATION.md#term-workflow), not a program. The session reads which steps a task needs and in what order, carries them out itself, and hands the steps that 
````
