@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/adia-ui-ops/references/recipes/adr-introduction.md

@@ -1,211 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - greenfield-setup.md
-  - memory-organization.md
-  - audit-existing-repo.md
-  - continuous-learning-loop.md
-  - ../doc-types/adr-pattern.md
-primary_sources:
-  - https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
-  - https://adr.github.io/madr/
-  - https://github.com/joelparkerhenderson/architecture-decision-record
-  - https://github.com/npryce/adr-tools
-status: research-verified
----
-
-# Recipe: introduce ADRs to an established repo (delivers Promise 5)
-
-> **The premise.** A repo without ADRs has scattered architectural memory — decisions live in PR descriptions, Slack archives, code comments, and senior engineers' heads. The "continuously-learning" promise is broken until the repo has a place to land decisions *at decision time*. This recipe creates that place and seeds it just enough that the practice survives.
-
-## What this recipe is *not*
-
-- **Not** a backfill-everything-ever campaign. Reconstructing 10 years of decisions almost never finishes.
-- **Not** a bureaucratic gate. Most PRs aren't architectural; most don't need ADRs.
-- **Not** a tooling adoption. `adr-tools` (Pryce) is optional and lightly maintained as of April 2026. `mkdir .brain/adrs/` is enough to start.
-
-## What this recipe *is*
-
-A 60-minute setup that (1) creates `.brain/adrs/` with an index and the bootstrap ADR; (2) backfills 3-5 *load-bearing* historical decisions; (3) wires the AGENTS.md `Memory primitives` section; (4) adds the architectural-impact checkbox to the PR template; (5) briefs the team in one paragraph.
-
-## Step 1 — Create the ADR home + index
-
-```bash
-mkdir -p docs/adrs
-
-cat > .brain/adrs/README.md <<'EOF'
-# Architecture Decision Records
-
-This folder captures architectural decisions. Each ADR is dated, numbered,
-and immutable — decisions don't get edited; they get superseded.
-
-Format: MADR 4.0.0 (https://adr.github.io/madr/) for new ADRs.
-Read newest-first. See `../../AGENTS.md` "Memory primitives" for when
-to consult.
-
-## Index
-
-| # | Title | Status | Date |
-|---|---|---|---|
-| 0001 | Record architecture decisions | Accepted | 2026-04-27 |
-
-_Last reviewed: 2026-04-27_
-EOF
-```
-
-## Step 2 — Bootstrap ADR 0001
-
-Use the Nygard format ([cognitect.com 2011](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)) for the bootstrap; canonical templates in `../doc-types/adr-pattern.md`. The bootstrap ADR records the decision to *use ADRs* — without it, future contributors don't know whether the practice is required.
-
-Save as `.brain/adrs/0001-record-architecture-decisions.md` (full content in `greenfield-setup.md`). Update the README index.
-
-## Step 3 — Backfill 3-5 load-bearing historical ADRs
-
-This is where teams either succeed or burn out. **Do not try to backfill every past decision.** Pick the 3-5 commitments that (a) are still live, (b) get questioned by new contributors, (c) would change the agent's behavior if it knew them.
-
-### How to find them — git archaeology in 20 minutes
-
-```bash
-# 1. Framework / library / runtime introductions
-git log --diff-filter=A --name-only --pretty=format:'%h %ad %s' --date=short \
-    -- 'package.json' 'Gemfile' 'requirements.txt' 'go.mod' 'Cargo.toml' \
-       'pyproject.toml' '*.csproj' 'pom.xml' 'mix.exs' | head -50
-
-# 2. DB-related decisions
-git log --all --oneline --grep -E -i 'postgres|mysql|mongo|redis|sqlite|dynamo' | head -30
-
-# 3. Deployment platform decisions
-git log --all --oneline --grep -E -i 'deploy|kubernetes|cloud-run|fly|render|vercel|heroku' | head -30
-
-# 4. Auth / security decisions
-git log --all --oneline --grep -E -i 'auth|jwt|session|oauth|saml' | head -20
-```
-
-Triangulate with the team: "What three things do people ask about most often?"
-
-### Typical high-value backfill candidates
-
-| ADR # | Decision shape | Why it earns its place |
-|---|---|---|
-| 0002 | Framework choice (e.g., Next.js over Remix) | Agent reaches for wrong framework conventions otherwise |
-| 0003 | Database choice (e.g., Postgres over MySQL) | Affects schema design, query patterns |
-| 0004 | Deployment platform (e.g., Cloud Run, not k8s) | Affects observability, CI, ops |
-| 0005 | Auth provider (e.g., Auth0 over rolling our own) | Affects security model, user model |
-| 0006 | Module boundaries (e.g., monorepo, not split repos) | Affects refactor blast radius |
-
-### Backfill ADR template
-
-Backfill ADRs **explicitly mark themselves as backfilled**. The team didn't go through the ADR process at the time — that's fine, just be honest.
-
-```markdown
-# 2. Use Postgres over MySQL
-
-Date: 2026-04-27 (decision made: 2024-03-12; backfilled retroactively)
-
-## Status
-Accepted
-
-## Context
-[Reconstructed from git log + PR #142 + memory of who was around. Some
-of the original constraint analysis is unrecoverable; this ADR captures
-the load-bearing context.]
-
-In Q1 2024, we needed a relational database for the user-account service.
-Drivers: JSONB for flexible user-profile fields, mature partitioning for
-the multi-tenant rollout, team familiarity (3 of 5 had Postgres experience).
-
-## Decision
-Postgres 15. Hosted on RDS in us-east-1.
-
-## Consequences
-- Locked into Postgres dialect (we use JSONB ops + LATERAL joins).
-- Migrating later requires schema rewrite + data backfill.
-- Connection pool management is a known op concern (see
-  `.brain/postmortems/2026-04-12-checkout-outage.md`).
-```
-
-The "(decision made: ... ; backfilled retroactively)" tag is critical — tells the next reader the ADR isn't reconstructing perfect history, just the load-bearing summary.
-
-**Stop at 3-5.** A 6th tempting backfill is usually scope creep. Add to the backlog and let it appear when someone next touches the relevant area.
-
-## Step 4 — Wire AGENTS.md Memory primitives
-
-If AGENTS.md doesn't have a `Memory primitives` section, add one. If it does, add the ADR pointer:
-
-```markdown
-## Where to find things
-(...)
-- **Architecture Decision Records:** `.brain/adrs/` (index: `.brain/adrs/README.md`)
-
-## Memory primitives
-- **Before architectural decisions**, read `.brain/adrs/` newest-first.
-  If your proposed change conflicts with an `Accepted` ADR, write a new
-  ADR superseding it; don't silently override.
-```
-
-Without this section, the ADRs exist but the agent doesn't know to read them — single most-common loop break (see `continuous-learning-loop.md`).
-
-## Step 5 — Update the PR template
-
-Add the architectural-impact checkbox to `.github/pull_request_template.md`:
-
-```markdown
-## Architectural impact
-- [ ] No architectural change (no ADR needed)
-- [ ] Architectural change — ADR added at: `.brain/adrs/NNNN-*.md`
-- [ ] Architectural change — ADR exemption granted by: [name]
-      Reason: [why no ADR]
-```
-
-Optionally add the auto-detection CI workflow from `continuous-learning-loop.md` that warns when architectural files change without an accompanying ADR.
-
-## Step 6 — Brief the team
-
-One paragraph. Post in #engineering:
-
-> We've added `.brain/adrs/` for architectural decisions. New decisions
-> that change framework / DB / deployment / auth / module boundaries
-> get an ADR alongside the PR. The PR template has a checkbox to remind.
-> We've backfilled 5 historical ones (Postgres, Cloud Run, Next.js,
-> Auth0, monorepo). Format is MADR 4.0.0 — see `.brain/adrs/README.md`.
-> AGENTS.md now points to this folder so LLM agents read it before
-> architectural changes.
-
-Don't send a 500-word memo — short, factual, links.
-
-## Verification checklist
-
-- [ ] `.brain/adrs/` exists with `README.md` index
-- [ ] `0001-record-architecture-decisions.md` is `Accepted`
-- [ ] 3-5 backfill ADRs landed, each marked retroactive in the date line
-- [ ] AGENTS.md `Where to find things` references `.brain/adrs/`
-- [ ] AGENTS.md `Memory primitives` instructs newest-first reading
-- [ ] `.github/pull_request_template.md` has architectural-impact checkbox
-- [ ] Team brief sent
-
-## When to choose Nygard vs MADR vs Y-statements
-
-| Format | When to use |
-|---|---|
-| **Nygard** (Title / Date / Status / Context / Decision / Consequences) | Small teams, fast cadence, straightforward decisions |
-| **MADR 4.0.0** (adds Deciders / Considered Options / Decision Drivers) | Larger teams, audit-trail matters, multi-option |
-| **Y-statements** (Zimmermann SATURN 2012) | One-line reversible choices; or summary atop a longer ADR |
-
-The audit treats all three as valid; `../doc-types/adr-pattern.md` covers detection.
-
-## Common mistakes
-
-- **Backfilling everything.** Past 5 ADRs you're doing archaeology, not setup.
-- **No bootstrap ADR.** Without `0001`, future contributors don't know whether ADRs are mandatory.
-- **Backfill ADRs that pretend they were written contemporaneously.** Reads as historical revisionism.
-- **Adding ADRs but not the AGENTS.md pointer.** Corpus exists; agent doesn't read it.
-- **PR template without the checkbox.** New decisions don't get captured.
-
-## Cross-references
-
-- ADR pattern (templates, anti-patterns, audit checks): `../doc-types/adr-pattern.md`
-- Memory organization (where ADRs sit relative to runbooks/postmortems): `memory-organization.md`
-- Greenfield setup (the day-one version): `greenfield-setup.md`
-- Continuous-learning loop (the system this plugs into): `continuous-learning-loop.md`
-- AGENTS.md Memory primitives section: `../standards/agents-md-spec.md`

package/skills/adia-ui-ops/references/recipes/audit-existing-repo.md

@@ -1,234 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - greenfield-setup.md
-  - adr-introduction.md
-  - memory-organization.md
-primary_sources:
-  - SKILL.md (this skill's own audit categories)
-status: needs-research-enhancement
----
-
-# Recipe: audit an existing repo
-
-> **The end-to-end procedure** for running `ops-repo` against a real repo and producing an actionable gap report. Includes the v1.5 `.brain/` layout migration recipe.
-
-## Inputs
-
-- A path to a git repo (working tree)
-- Optional: severity threshold (`critical` / `high` / `medium` / `low`) — default `medium`
-- Optional: write-mode flag (`recommend-only` / `apply-fixes`) — default `recommend-only`
-
-## Outputs
-
-- `stale-docs-audit.md` (or stdout) with the gap report
-- (If `apply-fixes`) edits to `AGENTS.md`, `CLAUDE.md`, etc., or new files in `.brain/`
-
-## The 7-step procedure
-
-### Step 1 — Discovery
-
-Enumerate everything that matters:
-
-```bash
-# Entry-file candidates at root
-ls -la AGENTS.md CLAUDE.md README.md CONTRIBUTING.md SECURITY.md \
-       .cursorrules .windsurfrules .aider.conf.yml 2>/dev/null
-
-# Cursor newer-style rules folder
-ls -la .cursor/rules/ 2>/dev/null
-
-# Continue config
-ls -la .continue/ 2>/dev/null
-
-# GitHub Copilot instructions
-ls -la .github/copilot-instructions.md 2>/dev/null
-
-# Brain artifacts (v1.5 layout) + legacy docs/ tree
-find .brain docs -type f -name '*.md' 2>/dev/null
-find . -maxdepth 2 \( -name 'CHANGELOG*.md' -o -name 'ARCHITECTURE.md' -o -name 'PLAN.md' -o -name 'ROADMAP.md' \) 2>/dev/null
-```
-
-Build two sets:
-- **EntryFiles**: files found at the root that are entry candidates
-- **DocFiles**: files found anywhere under `.brain/` or `docs/`, plus well-known top-level docs (CHANGELOG.md, ARCHITECTURE.md, PLAN.md, ROADMAP.md)
-
-**Git-sync mode detection.** Check `.gitignore`. If `.brain/` (the directory itself, not just `.brain/cache/` or `.brain/cold-start/`) appears in `.gitignore`, the repo is in `local-only` mode (per `../guidance/reliability-dial.md` § Git sync). The audit still runs against the working tree, but Promise 5 findings apply to the local clone only — multi-contributor recipes (`concurrent-learnings-merge.md`, `cold-start-harvest.md`) and the auto-archive PR workflow are moot in this mode and should be skipped.
-
-### Step 2 — Pointer trace
-
-For each file in `EntryFiles`, parse it as Markdown and extract every relative-path link or backtick-quoted path. Build a set:
-
-- **PointedTo**: union of all paths referenced from any entry file
-
-Cross-check against `DocFiles`:
-
-- **PointedTo ∩ DocFiles** — files reachable from entry. ✅
-- **PointedTo \ DocFiles** — referenced but missing. ❌ *Broken pointer.*
-- **DocFiles \ PointedTo** — exist but unreachable. 🟡 *Orphan.*
-
-### Step 3 — Canonical determination
-
-Decide which entry file is *canonical* (the one that should hold instructions; others should redirect to it).
-
-Decision tree:
-
-```
-Is AGENTS.md present and ≥30 lines?
-  YES → AGENTS.md is canonical.
-  NO  → Is exactly one fat (≥30 lines) entry file present?
-          YES → Recommend renaming it to AGENTS.md.
-          NO  → Are multiple fat files present?
-                  YES → DRIFT. Recommend consolidation.
-                  NO  → No canonical file. CRITICAL gap.
-```
-
-### Step 4 — Thin-pointer compliance
-
-For every entry file that is NOT canonical, verify it's a thin pointer:
-
-- Length ≤ 15 lines
-- References the canonical file by name
-- No substantive instructions of its own
-
-Findings:
-- **Fat non-canonical** → drift risk → recommend converting to pointer.
-- **Wrong target** → e.g. CLAUDE.md exists, points at `AGENTS.md`, but AGENTS.md doesn't exist → broken redirect.
-
-### Step 5 — Memory-primitive check
-
-For each of the standard memory homes, check existence and pointer-from-AGENTS.md:
-
-| Home | Required? | If missing |
-|---|---|---|
-| `.brain/adrs/` (or legacy `docs/adrs/`) | Recommended | "No ADR home — recommend introducing them. See `recipes/adr-introduction.md`." |
-| `.brain/decisions/` | Optional | If absent and no ADRs either, both flagged. |
-| `.brain/postmortems/` (or legacy `docs/postmortems/` / `docs/incidents/`) | Optional | Flag only if repo has had production incidents (heuristic: search for `incident`, `outage`, `post-mortem` in commit log). |
-| `CHANGELOG.md` | Strongly recommended | Flag as gap if missing. |
-| `.brain/runbooks/` (or legacy `docs/runbooks/`) | Optional | Flag if production-facing repo. |
-
-### Step 6 — Staleness probe
-
-For each file in `DocFiles`:
-
-- **Last modified** > 6 months ago AND **no `_Last reviewed:_` line** → flag as needs-review.
-- File contains references to symbols/files that no longer exist in the repo → flag as broken-reference.
-- File contains commands that fail dry-run (e.g., `npm install` but project is pnpm) → flag as command-stale. (Best-effort; may require running commands.)
-
-### Step 7 — Synthesize the gap report
-
-Write `stale-docs-audit.md` with sections:
-
-```markdown
-# Stale-docs audit — <repo name>
-
-_Generated: 2026-04-27_
-
-## Summary
-
-- **Critical**: 1 finding
-- **High**: 3 findings
-- **Medium**: 7 findings
-- **Low**: 4 findings
-
-## Critical
-
-### MISSING — AGENTS.md
-[detail per the entry-file-coverage.md output shape]
-
-## High
-
-### DRIFT — CLAUDE.md vs .cursorrules
-[detail]
-
-### NO ADR HOME
-The repo has architectural decisions scattered across PR descriptions and code
-comments but no `.brain/adrs/`. Recommend introducing ADRs.
-
-[continue per severity]
-
-## Recommended fixes (ordered)
-
-1. Rename `CLAUDE.md` → `AGENTS.md`; create thin `CLAUDE.md` redirect.
-2. Create `.brain/adrs/` with `0001-record-architecture-decisions.md`.
-3. Add "Where to find things" and "Memory primitives" sections to AGENTS.md.
-4. Update `.cursorrules` to be a thin pointer.
-5. Resolve drift between CLAUDE.md and .cursorrules: pnpm vs npm.
-
-## Suggested edits (when in apply-fixes mode)
-
-[concrete diffs — not applied without explicit user confirmation]
-```
-
-## Migration: legacy `docs/` layout → `.brain/`
-
-If the audit finds memory artifacts in `docs/{adrs,postmortems,runbooks,archive,architecture}/` (the pre-v1.5 layout), the recommended migration is one git move that preserves history:
-
-```bash
-mkdir -p .brain
-
-# Move each memory primitive that exists. Skip silently if absent.
-[ -d docs/adrs ]         && git mv docs/adrs         .brain/adrs
-[ -d docs/postmortems ]  && git mv docs/postmortems  .brain/postmortems
-# Or if the repo used the docs/incidents alias:
-[ -d docs/incidents ] && [ ! -d .brain/postmortems ] && git mv docs/incidents .brain/postmortems
-[ -d docs/runbooks ]     && git mv docs/runbooks     .brain/runbooks
-[ -d docs/archive ]      && git mv docs/archive      .brain/archive
-[ -d docs/architecture ] && git mv docs/architecture .brain/architecture
-[ -d docs/ops-repo/audit-history ] && git mv docs/ops-repo/audit-history .brain/audit-history
-
-# Config + transient state homes
-[ -f .ops-repo.toml ] && git mv .ops-repo.toml .brain/config.toml
-[ -d .ops-repo/changesets ] && git mv .ops-repo/changesets .brain/changesets
-
-git commit -m "chore: migrate memory layer to .brain/ (ops-repo v1.5)"
-```
-
-After the move, also update:
-
-- **`AGENTS.md`** — every "Where to find things" pointer (`docs/adrs/` → `.brain/adrs/`, etc.)
-- **`.gitignore`** — add `.brain/cache/` and `.brain/cold-start/working/` (transient state)
-- **`.github/workflows/`** — rename `repo-fixer-*.yml` → `repo-brain-*.yml` if hooks were installed pre-v1.3
-- **Workflow path filters / lychee globs** — add `'.brain/**/*.md'` next to `'docs/**/*.md'` (verbatim recipes in `self-healing-hooks.md`)
-
-The audit recognizes either layout — **migration is opt-in for v1.5**, not enforced. Repos that prefer the established `docs/{adrs,...}/` convention can stay there; the audit's checks adapt. Greenfield setup defaults to `.brain/`.
-
-**What stays at the repo root regardless of layout:**
-
-- `AGENTS.md`, `CLAUDE.md`
-- `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`
-- `ARCHITECTURE.md` (matklad pattern)
-- `CHANGELOG.md`
-- `PLAN.md`, `ROADMAP.md` (if used)
-
-## Apply-fixes mode safety rules
-
-When `apply-fixes` is on:
-
-1. **Never delete a file** without showing the user and asking.
-2. **Never overwrite a file >50 lines** without showing a diff and asking.
-3. **Always commit each fix as a separate commit** with a clear message — this is reversible.
-4. **Never rewrite git history.**
-5. If asked to delete an orphaned doc, prefer **moving to `.brain/archive/`** with a date suffix over outright deletion.
-
-## Common findings on real repos
-
-From running this audit across real-world projects, the most frequent gaps:
-
-1. **No AGENTS.md, fat CLAUDE.md** — repo predates the standard or only used Claude Code.
-2. **No "Where to find things" section** — naked entry; agent has nothing to navigate.
-3. **CLAUDE.md and .cursorrules drifted** — duplicate maintenance burden, rarely consistent.
-4. **No ADR home** — decisions scattered across PRs.
-5. **Stale build commands** — entry file says `npm` but repo migrated to pnpm/bun.
-6. **Orphaned `docs/old-plan.md`** — never cleaned up after being superseded.
-7. **Undated `ARCHITECTURE.md`** — no way to know if it's current.
-8. **Pre-v1.5 `docs/` layout** — opportunity to migrate to `.brain/` (see § Migration above).
-
-## Cross-references
-
-- Entry-file checks: `../audit-patterns/entry-file-coverage.md`
-- Pointer validation: `../audit-patterns/pointer-validation.md`
-- Orphan detection: `../audit-patterns/orphan-detection.md`
-- Greenfield setup: `greenfield-setup.md`
-- Adding ADRs to existing repo: `adr-introduction.md`