From a6da0e0b8bfaece32b7c3dfdcc31f5e6688ea9ce Mon Sep 17 00:00:00 2001 From: Mateusz Paulski Date: Tue, 18 Aug 2026 19:29:36 +0200 Subject: [PATCH] docs: move ADR log to repo root (ADR.md), point CLAUDE.md at global ADR rule The when/how-to-write-an-ADR rule now lives in the global ~/.claude/CLAUDE.md so every repo shares it; the project CLAUDE.md keeps only a pointer. docs/adr.md is renamed to ADR.md at the root so agents find it without a map. Co-Authored-By: Claude Fable 5 --- .claude/agents/airside-spec-author.md | 2 +- .claude/skills/airside-agent/SKILL.md | 6 ++--- .claude/skills/filing-github-issues/SKILL.md | 2 +- docs/adr.md => ADR.md | 0 CLAUDE.md | 25 ++------------------ docs/architecture.md | 4 ++-- docs/milestones.md | 2 +- 7 files changed, 10 insertions(+), 31 deletions(-) rename docs/adr.md => ADR.md (100%) diff --git a/.claude/agents/airside-spec-author.md b/.claude/agents/airside-spec-author.md index 3b303feb..9e380781 100644 --- a/.claude/agents/airside-spec-author.md +++ b/.claude/agents/airside-spec-author.md @@ -22,7 +22,7 @@ comment for the owner to `/approve` or `/revise`, so write it for that reader. `docs/ideas.md`/`docs/issues.md` entry; that backlog was retired — ignore the dead link and work from the issue body.) 2. **Ground it in the project.** This repo's design is the source of truth — read what's relevant - in `docs/architecture.md`, `docs/prd.md`, `docs/adr.md`, and `CLAUDE.md`. Read the actual code + in `docs/architecture.md`, `docs/prd.md`, `ADR.md`, and `CLAUDE.md`. Read the actual code the change would touch (Grep for the seams, Read the files). Note the rules that apply: backend (`core`/`server`/adapters) is **TDD**; publishable-package changes need a **changeset**; `pnpm lint` (biome) must pass. Web-research only if genuinely needed (an external API/library). diff --git a/.claude/skills/airside-agent/SKILL.md b/.claude/skills/airside-agent/SKILL.md index b31b37d0..d8575c1a 100644 --- a/.claude/skills/airside-agent/SKILL.md +++ b/.claude/skills/airside-agent/SKILL.md @@ -28,7 +28,7 @@ once, by hand, to run a single tick (this is how you test it). > **In review:** the comments you leave — **inline review threads and top-level PR comments** — are > picked up, fixed, and acknowledged. **Terminal:** a merge → `done`, a close → `done`/`cancelled` > (kill switch). The runbook parks anything it can't handle with a note (it never silently drops -> work). See `docs/adr.md` (ADR-0042, ADR-0043). +> work). See `ADR.md` (ADR-0042, ADR-0043). > > **Deferred (no observed need yet):** round-robin fairness across many simultaneously-active issues, > and a global `MAX_ACTIVE` ceiling — the `≤1 op/tick` invariant + the user-started loop already bound @@ -127,7 +127,7 @@ Mirror the computed phase to exactly one `state:*` label (mutually exclusive): ` - `gh auth status` succeeds; default repo resolves to `Airnauts/airside`. - Ensure labels exist (idempotent upsert — safe to run every tick): `gh label create "agent" --color 5319e7 --force` … and the five `agent:simple` / `state:*` - labels (see `docs/adr.md` for the full list). Skip if you confirmed them this session. + labels (see `ADR.md` for the full list). Skip if you confirmed them this session. ### 1. Scan @@ -520,7 +520,7 @@ Spawn with the **Agent tool**, `subagent_type: "airside-spec-reviser"` (no workt ## Builder spawn contract Spawn with the **Agent tool**, `isolation: "worktree"` (verified to give a real, locally-built -worktree — see `docs/adr.md`), and `subagent_type: "airside-builder"`. If that subagent type is +worktree — see `ADR.md`), and `subagent_type: "airside-builder"`. If that subagent type is not yet registered in this session, fall back to `subagent_type: "general-purpose"` and pass the **full contents of `.claude/agents/airside-builder.md`** as the prompt preamble. diff --git a/.claude/skills/filing-github-issues/SKILL.md b/.claude/skills/filing-github-issues/SKILL.md index 4f5e92b9..85da89d9 100644 --- a/.claude/skills/filing-github-issues/SKILL.md +++ b/.claude/skills/filing-github-issues/SKILL.md @@ -17,7 +17,7 @@ own**: the full rationale lives in the issue body, not in a doc it links back to An issue is a pitch + an implementation sketch + (for bugs) a root cause + the load-bearing detail someone would need to pick it up later. Keep it concrete but not a full design doc — -deeper design still graduates to `docs/adr.md` + a milestone if and when the item is +deeper design still graduates to `ADR.md` + a milestone if and when the item is committed to. Use the authenticated `gh` CLI. Default repo: `Airnauts/airside`. diff --git a/docs/adr.md b/ADR.md similarity index 100% rename from docs/adr.md rename to ADR.md diff --git a/CLAUDE.md b/CLAUDE.md index ac2cab97..2b575fc1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,7 +7,7 @@ restating it here: - `docs/prd.md` — product requirements. - `docs/architecture.md` — the integrated v1 system architecture (start here). -- `docs/adr.md` — the per-decision rationale log (ADR-0001…). +- `ADR.md` — the per-decision rationale log (ADR-0001…). - `docs/milestones.md` — delivery milestones. ## Development practices @@ -66,25 +66,4 @@ include), use the `writing-changesets` skill in `.claude/skills/`. ## Architecture decision records -`docs/adr.md` is the running log of architecture decisions for this project. Whenever an architecturally significant choice is made or changed. - -### When to add an ADR - -Add an ADR when a decision is difficult to change later. Specifically, write one when you: - -- Choose a framework, language, or database. -- Define communication protocols (e.g., REST vs. gRPC). -- Establish coding standards or architectural patterns. -- Introduce a change with significant trade-offs. - -### What each record captures - -Keep entries newest-last, and for each record capture: - -- **Title and date** (use the current date). -- **Status** — proposed / accepted / superseded (note which record supersedes it). -- **Context** — the problem and the forces in play. -- **Decision** — what was chosen. -- **Consequences** — trade-offs and follow-on implications. - -Don't edit decided history in place: to reverse a past decision, add a new record that supersedes the old one rather than rewriting it. +`ADR.md` at the repo root is the running log of architecture decisions (ADR-0001…). The rule for when and how to write one lives in the global `~/.claude/CLAUDE.md`. diff --git a/docs/architecture.md b/docs/architecture.md index a671d5a1..af8c277e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,8 +2,8 @@ - **Status:** Approved (brainstorm complete) - **Date:** 2026-05-27 -- **Inputs:** [`docs/prd.md`](prd.md) · [`docs/adr.md`](adr.md) · reference: [`docs/reference/vercel-comments-payloads.md`](reference/vercel-comments-payloads.md), [`docs/reference/vercel-widget-dom.md`](reference/vercel-widget-dom.md) -- **Scope:** the v1 system architecture. Product requirements are in the PRD; this document is the system shape that realizes them. Decision rationale is captured per-decision in `adr.md` (ADR-0001…0010); this spec is the integrated picture. +- **Inputs:** [`docs/prd.md`](prd.md) · [`ADR.md`](../ADR.md) · reference: [`docs/reference/vercel-comments-payloads.md`](reference/vercel-comments-payloads.md), [`docs/reference/vercel-widget-dom.md`](reference/vercel-widget-dom.md) +- **Scope:** the v1 system architecture. Product requirements are in the PRD; this document is the system shape that realizes them. Decision rationale is captured per-decision in `ADR.md` (ADR-0001…0010); this spec is the integrated picture. --- diff --git a/docs/milestones.md b/docs/milestones.md index 3f05d465..778c9b94 100644 --- a/docs/milestones.md +++ b/docs/milestones.md @@ -2,7 +2,7 @@ - **Status:** Proposed - **Date:** 2026-05-27 -- **Source of truth:** [`docs/architecture.md`](architecture.md) + ADRs in [`docs/adr.md`](adr.md) +- **Source of truth:** [`docs/architecture.md`](architecture.md) + ADRs in [`ADR.md`](../ADR.md) ## How to use this document