⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

adr-writer

llopresto87@llopresto87⭐ 121 stars· last commit 4d ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 121 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

CYPRESS

What CYPRESS is

CYPRESS is an installer that gives the AI coding 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: 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 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; the glossary's 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 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 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 and the host support decision records (tiers, opencode) say what each level means.

The method assumes no language, framework or stack. The reference corpora 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 has the breakdown.

It is not for someone who does not use an AI coding 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, 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);
  • the harness directory .claude/, holding the agent definitions, the skills, 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 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 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). Files under docs/graph/ that belong to your project, such as the graph's index, are only added where missing (project 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

FigureWhat it covers, and how it was obtained
67 065 bytesper 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's files by this repository's test run; a lower bound, not a live reading
11% more tokensper 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)

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 gives the figure for each other harness. No money figure exists.

Try it

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 into it. That starts the one-time 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 record when, under delegation.harness-registration.

How it works

CYPRESS is a written 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

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/adr-writer/SKILL.md7.8 KBupstream ↗
    ---
    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
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/llopresto87-cypress-skills-adr-writer.md

// REPO STATS

121 stars
0 open issues
Last commit: 4d ago