sync: ADR-0006, ADR-0007, and 12 new skills into org context files

.github/copilot-instructions.md

@@ -16,6 +16,8 @@ Reusable agent skills and architecture decision records live in [darkmatter/skil
 | ADR-0003 | Cross-language types use Protobuf + `buf`. Default transport: ConnectRPC. Commit generated code. `buf lint` + `buf breaking` in CI. |
 | ADR-0004 | No reinvention — check for existing libraries before implementing. A dependency beats private code. |
 | ADR-0005 | One typed `src/settings.<ext>` per binary. Only place that reads raw env vars. Validates at startup. Secret values use redacted wrappers — never plain strings. |
+| ADR-0006 | READMEs follow Standard Readme. Required: title, install (copy/paste-able), usage with quickstart, ADR-0002 command surface, config/secrets docs, verify command, contributing, license. No unexplained placeholders. |
+| ADR-0007 | No inline SQL in TypeScript — no `sql<Row>\`...\`` or raw strings. Use Kysely (preferred) or Drizzle. Improve the abstraction before falling back to inline SQL. |
 | OTel | App code imports only OTel SDKs; provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. |
 
 ## Always apply
@@ -24,18 +26,21 @@ Reusable agent skills and architecture decision records live in [darkmatter/skil
 - `brainstorming` — before implementing anything non-trivial
 - `test-driven-development` — before writing implementation code
 - `systematic-debugging` — before proposing fixes
+- `diagnose` — hard bugs and performance regressions (reproduce → minimise → hypothesise → instrument → fix)
 - `verification-before-completion` — before claiming work is done
 - `definition-of-done` — any complex multi-step task
 
 ## Key skills by category
 
-**Task management:** `beads-setup` (no `.beads/`?), `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `finishing-a-development-branch`
+**Task management:** `beads-setup` (no `.beads/`?), `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `finishing-a-development-branch`, `triage`, `handoff`
 
-**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `end-of-turn-review`, `writing-skills`
+**Design & planning:** `grill-me` (stress-test a plan), `grill-with-docs` (grill + persist decisions to CONTEXT.md/ADRs), `prototype` (throwaway logic or UI prototype), `zoom-out` (map modules and callers)
 
-**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization`
+**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `improve-codebase-architecture`, `end-of-turn-review`, `writing-skills`
 
-**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design`
+**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization`, `rust-best-practices`
+
+**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design`, `shadcn-registry-first`, `ui-component-architecture`, `run-ui-registry-variations`
 
 **Browser automation:** `browser-use` (Python, persistent sessions), `agent-browser` (CDP, Node/Rust)
 

AGENTS.md

@@ -17,25 +17,29 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills)
 | [0003](https://github.com/darkmatter/skills/blob/main/docs/adr/0003-protobuf-as-service-source-of-truth.md) | Cross-language types use **Protobuf + `buf`**. Default transport: **ConnectRPC**. Generated code is committed. `buf lint` + `buf breaking` in CI. |
 | [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.<ext>`** 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<T>`). |
+| [0006](https://github.com/darkmatter/skills/blob/main/docs/adr/0006-readme-minimum-standard.md) | **README follows Standard Readme.** Required: title, install (copy/paste-able), usage with quickstart, ADR-0002 command surface, config/secrets, verify command, contributing, license. No unexplained placeholders. |
+| [0007](https://github.com/darkmatter/skills/blob/main/docs/adr/0007-type-checked-sql-in-typescript.md) | **No inline SQL in TypeScript.** No `sql<Row>\`...\`` or raw strings. Use **Kysely** (preferred) or Drizzle. If a query can't be expressed through the typed surface, improve the abstraction. |
 | OTel | App code imports only **OpenTelemetry SDKs**. Provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. |
 
 ---
 
 ## Skills to apply proactively
 
-**Always-on:** `coding-standards`, `brainstorming`, `test-driven-development`, `systematic-debugging`, `verification-before-completion`, `definition-of-done`
+**Always-on:** `coding-standards`, `brainstorming`, `test-driven-development`, `systematic-debugging`, `diagnose` (hard bugs/regressions), `verification-before-completion`, `definition-of-done`
 
 **Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync`, `writing-plans`, `executing-plans`
 
 **Agent orchestration:** `subagent-driven-development`, `dispatching-parallel-agents`
 
 **Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `repository-organization`, `end-of-turn-review`, `writing-skills`
 
-**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`
+**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `improve-codebase-architecture`, `rust-best-practices`
 
-**Workflow:** `finishing-a-development-branch`, `dm-skill-creator`, `find-skills`, `run-meeting-summary`
+**Workflow:** `finishing-a-development-branch`, `dm-skill-creator`, `find-skills`, `run-meeting-summary`, `triage`, `handoff`
 
-**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design`
+**Design & planning:** `grill-me`, `grill-with-docs`, `prototype`, `zoom-out`
+
+**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design`, `shadcn-registry-first`, `ui-component-architecture`, `run-ui-registry-variations`
 
 **Platform:** `nextjs-to-rwsdk-migration`, `openchronicle-setup`, `neon-postgres`
 

CLAUDE.md

@@ -107,6 +107,16 @@ export class Settings extends Effect.Service<Settings>()("Settings", {
 
 Secret values MUST be typed as redacted wrappers (`Config.redacted`, Pydantic `SecretStr`, Rust `secrecy::Secret<T>`). Plain string typing for a secret is a defect.
 
+### 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 project README MUST follow [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) as the default structure and include at minimum: title + short description, install (copy/paste-able), usage with a quickstart path, the ADR-0002 command surface, configuration and secrets documentation, a verification/test command, contributing guidance, and license last. Commands must run as written from the repo root — no unexplained placeholders.
+
+### 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 tagged templates (including `sql<Row>\`...\``). Use a type-checked query builder: **Kysely** is preferred for query-heavy code; Drizzle is allowed when already present. If a query cannot be expressed through the typed surface, improve the abstraction — never fall back to inline SQL.
+
 ### OTel-only observability
 **Status:** Accepted
 
@@ -126,6 +136,7 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt
 | `brainstorming` | Before any non-trivial implementation |
 | `test-driven-development` | Before writing implementation code |
 | `systematic-debugging` | Before proposing fixes for bugs or failures |
+| `diagnose` | Hard bugs and performance regressions — reproduce → minimise → hypothesise → instrument → fix |
 | `verification-before-completion` | Before claiming work is done |
 | `definition-of-done` | Complex, multi-step tasks |
 
@@ -138,6 +149,7 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt
 | `nix-flake-organization` | Thin `flake/` public layer + `src/` implementation |
 | `sops-secret-access` | SOPS-encrypted config, private registries |
 | `repository-organization` | Repo layout, Standard README, ADR placement, agent context |
+| `rust-best-practices` | Idiomatic Rust — borrowing, error handling, linting, performance, testing |
 
 ### Task and workflow
 
@@ -154,10 +166,17 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt
 | `requesting-code-review` | Dispatch code-reviewer subagent before merge |
 | `receiving-code-review` | Evaluate review feedback rigorously before implementing |
 | `codebase-cleanup` | Multi-pass refactor sweep (8 specialist subagents) |
+| `improve-codebase-architecture` | Surface architectural friction; find deepening opportunities for testability and AI-navigability |
 | `end-of-turn-review` | GPT second-opinion pass over diffs or plans at end of turn |
 | `writing-skills` | TDD applied to process documentation — create, edit, verify skills |
 | `find-skills` | Discover and install agent skills from the open ecosystem |
 | `run-meeting-summary` | Resolve meeting artifacts and draft approved Obsidian summaries |
+| `grill-me` | Stress-test a plan or design — relentless Q&A through the decision tree, one question at a time |
+| `grill-with-docs` | Grill on a plan against the domain model; update CONTEXT.md and ADRs inline as decisions crystallize |
+| `triage` | Issue triage state machine — classify bugs/enhancements, write agent briefs, manage wontfix |
+| `handoff` | Compact the current session into a handoff document for a fresh agent |
+| `zoom-out` | Map modules and callers when unfamiliar with an area of code; get broader context |
+| `prototype` | Build a throwaway prototype (terminal logic app or UI variations) to validate a design question |
 
 ### UI/Frontend
 
@@ -168,6 +187,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 |
+| `shadcn-registry-first` | Install from shadcn/shadcnblocks registries before hand-rolling; always build 3+ variations |
+| `ui-component-architecture` | Keep screens thin; graduate reusable units into `@repo/ui`; avoid div-soup |
+| `run-ui-registry-variations` | Build exactly three UI variations from shadcnblocks, Aceternity, or the DM registry |
 
 ### Browser automation
 
@@ -214,3 +236,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.** Copy/paste-able commands, all mandatory sections (ADR-0006).
+9. **No inline SQL in TypeScript.** Use Kysely (preferred) or Drizzle; never `sql<Row>\`...\`` (ADR-0007).