From 42dc36ef81c386dc6db135519fe71551c33dc59a Mon Sep 17 00:00:00 2001 From: cooper <1325802+czxtm@users.noreply.github.com> Date: Mon, 29 Jun 2026 09:16:00 -0700 Subject: [PATCH] feat: sync ADR-0006, ADR-0007, and new skills from darkmatter/skills Adds two new accepted ADRs (README standard, type-checked SQL) and 12 new skills (diagnose, grill-me, grill-with-docs, handoff, improve- codebase-architecture, prototype, rust-best-practices, triage, zoom- out, shadcn-registry-first, ui-component-architecture, run-ui-registry- variations) to CLAUDE.md, AGENTS.md, and copilot-instructions.md. --- .github/copilot-instructions.md | 13 +++++++++---- AGENTS.md | 12 ++++++++---- CLAUDE.md | 24 ++++++++++++++++++++++++ 3 files changed, 41 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 20e244b..57996dc 100644 --- a/.github/copilot-instructions.md +++ b/.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.` 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\`...\`` 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) diff --git a/AGENTS.md b/AGENTS.md index 0cc4d29..6172d6f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,13 +17,15 @@ 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.`** 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`). | +| [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\`...\`` 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` @@ -31,11 +33,13 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills) **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` diff --git a/CLAUDE.md b/CLAUDE.md index 0a90ddd..ee0f451 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -107,6 +107,16 @@ export class Settings extends Effect.Service()("Settings", { Secret values MUST be typed as redacted wrappers (`Config.redacted`, Pydantic `SecretStr`, Rust `secrecy::Secret`). 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\`...\``). 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\`...\`` (ADR-0007).