From b1a74d642b2807a2c02bd93584a13664371d3fe8 Mon Sep 17 00:00:00 2001 From: cooper <1325802+czxtm@users.noreply.github.com> Date: Mon, 22 Jun 2026 09:09:25 -0700 Subject: [PATCH] feat: sync ADR-0006, ADR-0007 and missing skills from darkmatter/skills catalog Adds two ADRs present in skills/docs/adr but absent from org instructions: - ADR-0006: README minimum standard (Standard Readme structure) - ADR-0007: Type-checked SQL in TypeScript (Kysely preferred, no inline SQL) Adds three skills present in catalog.md but absent from org skill tables: - ui-component-architecture - shadcn-registry-first - run-ui-registry-variations Updates CLAUDE.md, AGENTS.md, and .github/copilot-instructions.md. --- .github/copilot-instructions.md | 4 +++- AGENTS.md | 4 +++- CLAUDE.md | 33 +++++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 20e244b..d5c74c8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -17,6 +17,8 @@ Reusable agent skills and architecture decision records live in [darkmatter/skil | ADR-0004 | No reinvention — check for existing libraries before implementing. A dependency beats private code. | | ADR-0005 | One typed `src/settings.` per binary. Only place that reads raw env vars. Validates at startup. Secret values use redacted wrappers — never plain strings. | | OTel | App code imports only OTel SDKs; provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | +| ADR-0006 | READMEs MUST follow Standard Readme structure: title, install, usage/quickstart, command surface (ADR-0002), config/secrets, verification, contributing, license. All commands must be copy/paste-able from repo root. | +| ADR-0007 | No inline SQL strings in TypeScript (including `` sql`...` ``). Use **Kysely** (preferred) or **Drizzle** for type-checked queries. No fallback to raw SQL. | ## Always apply @@ -35,7 +37,7 @@ Reusable agent skills and architecture decision records live in [darkmatter/skil **Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization` -**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design` +**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design`, `ui-component-architecture`, `shadcn-registry-first`, `run-ui-registry-variations` **Browser automation:** `browser-use` (Python, persistent sessions), `agent-browser` (CDP, Node/Rust) diff --git a/AGENTS.md b/AGENTS.md index 0cc4d29..99cecd6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,8 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills) | [0004](https://github.com/darkmatter/skills/blob/main/docs/adr/0004-no-reinvention.md) | **No reinvention.** Check for existing libraries before implementing. A dependency beats a private reimplementation. | | [0005](https://github.com/darkmatter/skills/blob/main/docs/adr/0005-typed-settings-module-decoupled-from-provider.md) | **One typed `src/settings.`** per binary. Only place that reads raw env. Validates at startup. Decoupled from provider. Secret values must use redacted wrappers (`Config.redacted`, `SecretStr`, `secrecy::Secret`). | | OTel | App code imports only **OpenTelemetry SDKs**. Provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | +| [0006](https://github.com/darkmatter/skills/blob/main/docs/adr/0006-readme-minimum-standard.md) | **README minimum standard.** Every non-trivial project README MUST follow Standard Readme structure: title, install, usage/quickstart, command surface (ADR-0002 aligned), config/secrets, verification, contributing, license. Commands must be copy/paste-able from repo root. | +| [0007](https://github.com/darkmatter/skills/blob/main/docs/adr/0007-type-checked-sql-in-typescript.md) | **Type-checked SQL only in TypeScript.** No inline SQL strings or tagged-template `` sql ``. Use **Kysely** (preferred) or **Drizzle** (allowed). Other typed query builders acceptable if they provide compile-time table/column/join checking. | --- @@ -35,7 +37,7 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills) **Workflow:** `finishing-a-development-branch`, `dm-skill-creator`, `find-skills`, `run-meeting-summary` -**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design` +**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design`, `ui-component-architecture`, `shadcn-registry-first`, `run-ui-registry-variations` **Platform:** `nextjs-to-rwsdk-migration`, `openchronicle-setup`, `neon-postgres` diff --git a/CLAUDE.md b/CLAUDE.md index 0a90ddd..6a52f32 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -112,6 +112,34 @@ Secret values MUST be typed as redacted wrappers (`Config.redacted`, Pydantic `S App code depends only on OpenTelemetry SDKs. Provider-specific packages (`@sentry/*`, PostHog, Datadog) never appear in `apps/*`. Provider wiring is isolated in shared packages. +### ADR-0006: README minimum standard +**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0006-readme-minimum-standard.md) + +Every non-trivial darkmatter project README MUST follow [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) as the default structure. At minimum: + +1. **Title + short description** — one line, matches repo/package name +2. **Install** — copy/paste-able command block for host tools/prerequisites +3. **Usage** — copy/paste-able quickstart from fresh clone to useful result +4. **Development command surface** — aligned with ADR-0002 (`install`, `setup`, `server`/`run`, `test`, `build`, `ci`, `console`) +5. **Configuration and secrets** — where they come from, without exposing values +6. **Testing/verification** — command to run before claiming the repo works +7. **Contributing** — where questions go, PR acceptance, contribution requirements +8. **License** (last section) + +Copy/paste-able means commands run as-written from repo root after preceding steps. Documentation-only repos may omit runnable sections only when explicitly stated. + +### ADR-0007: Type-checked SQL in TypeScript +**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0007-type-checked-sql-in-typescript.md) + +TypeScript code MUST NOT embed SQL as inline strings or template literals for application queries (including tagged-template `` sql`...` ``). Use a type-checked query builder derived from the database schema. + +Preference order: +1. **Kysely** — preferred for query-heavy TypeScript; strong inference across selects, joins, aliases, nullability, and result shapes +2. **Drizzle** — allowed when already present; weaker inference for complex queries +3. Other tools with comparable compile-time table/column/join/result checking + +If a query cannot be expressed through the typed surface, improve the abstraction or schema — do not fall back to inline SQL. + --- ## Skills catalog @@ -168,6 +196,9 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `vercel-react-best-practices` | React/Next.js performance | | `nextjs-to-rwsdk-migration` | Port Next.js App Router to RedwoodSDK on Cloudflare Workers | | `kickoff-dm-design` | Design-room kickoff: Linear ticket + Slack post from a Claude Design URL | +| `ui-component-architecture` | Keep React screens thin; reuse `@repo/ui` primitives; graduate reusable units to the shared package | +| `shadcn-registry-first` | Bias UI toward existing shadcn registry components before hand-rolling; always build 3+ variations | +| `run-ui-registry-variations` | Build exactly three UI variations from shadcnblocks, Aceternity, or the Darkmatter shadcn registry | ### Browser automation @@ -214,3 +245,5 @@ These are **not task skills** — they are consumed by the agent runtime to conf 5. **Effect is the default for TypeScript services.** See `effect-typescript` skill and ADR-0005. 6. **Protobuf when crossing language boundaries.** Use `buf`, commit generated code (ADR-0003). 7. **One settings module per binary.** No scattered `process.env` reads (ADR-0005). +8. **READMEs follow Standard Readme structure.** Copy/paste-able commands, aligned with ADR-0002 (ADR-0006). +9. **No inline SQL in TypeScript.** Use Kysely or Drizzle for type-checked queries (ADR-0007).