From 5fad40e3770187617cc30265599ff96c96bcab54 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Jul 2026 16:14:41 +0000 Subject: [PATCH 1/2] docs: import ADR-0006/0007 and reconcile skill lists with darkmatter/skills Two accepted ADRs (0006 README minimum standard, 0007 type-checked SQL) existed in darkmatter/skills/docs/adr but were never imported here - add them to CLAUDE.md, AGENTS.md, and copilot-instructions.md. Also reconcile the skill catalogs in all three files against the actual skills// directories in darkmatter/skills: remove ~14 phantom skills (coding-standards, systematic-debugging, writing-plans, executing-plans, subagent-driven-development, dispatching-parallel-agents, frontend-design, browser-use, caveman, caveman-review, compress, neon-postgres, hl-funding-analysis, verification-before-completion) that don't exist as skill directories, and add ~14 real skills that were missing (diagnose, choose-dev-entrypoints, grill-me, grill-with-docs, handoff, improve-codebase-architecture, prototype, rust-best-practices, shadcn-registry-first, tdd, triage, ui-component-architecture, run-ui-registry-variations, zoom-out). AGENTS.md is the file OpenAI Codex CLI reads by convention, and copilot-instructions.md is explicitly titled for Copilot & Codex, so this is the concrete "Codex instructions" update alongside the Claude Code (CLAUDE.md) one. --- .github/copilot-instructions.md | 23 ++++++------ AGENTS.md | 24 +++++++----- CLAUDE.md | 66 ++++++++++++++++++++------------- 3 files changed, 67 insertions(+), 46 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 20e244b..5c3db28 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -16,29 +16,30 @@ 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: title, background if needed, TOC over 100 lines, copy-pasteable install + usage, documented command surface (ADR-0002), config/secrets docs, verification command, contributing, license last. | +| ADR-0007 | TypeScript MUST NOT embed SQL as inline strings/template literals (incl. `sql` tags). Use a type-checked query builder — preference order Kysely > Drizzle > comparable alternatives. | | OTel | App code imports only OTel SDKs; provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | ## Always apply -- `coding-standards` — any TypeScript/JS/React/Node code task - `brainstorming` — before implementing anything non-trivial -- `test-driven-development` — before writing implementation code -- `systematic-debugging` — before proposing fixes -- `verification-before-completion` — before claiming work is done +- `test-driven-development` — before writing implementation code (`tdd` is an overlapping, equally valid entry point) - `definition-of-done` — any complex multi-step task +Note: earlier versions of this file also listed `coding-standards`, `systematic-debugging`, and `verification-before-completion` as always-apply skills. None of these exist as a skill directory in darkmatter/skills — see "Known gaps" in [`docs/catalog.md`](https://github.com/darkmatter/skills/blob/main/docs/catalog.md). Don't invoke them by name until they're built. + ## 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/`?), `finishing-a-development-branch`, `handoff` -**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `end-of-turn-review`, `writing-skills` +**Code quality:** `diagnose`, `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `end-of-turn-review`, `writing-skills`, `improve-codebase-architecture` -**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization` +**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization`, `choose-dev-entrypoints` -**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design` +**UI/Frontend:** `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `ui-component-architecture`, `shadcn-registry-first`, `kickoff-dm-design` (manual), `run-ui-registry-variations` (manual) -**Browser automation:** `browser-use` (Python, persistent sessions), `agent-browser` (CDP, Node/Rust) +**Browser automation:** `agent-browser` (CDP, Node/Rust) -**Communication:** `caveman`, `caveman-commit` (compact commit messages), `caveman-review` (compact reviews), `compress` +**Communication:** `caveman-commit` (compact commit messages) -**Domain:** `neon-postgres`, `openchronicle-setup`, `hl-funding-analysis` +**Domain:** `openchronicle-setup`, `rust-best-practices`, `run-meeting-summary` (manual) diff --git a/AGENTS.md b/AGENTS.md index 0cc4d29..3a77e7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,31 +17,35 @@ 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) | READMEs follow **Standard Readme**: title, background if needed, TOC over 100 lines, copy-pasteable install + usage, documented command surface (ADR-0002), config/secrets docs, a verification command, contributing, license last. | +| [0007](https://github.com/darkmatter/skills/blob/main/docs/adr/0007-type-checked-sql-in-typescript.md) | TypeScript MUST NOT embed SQL as inline strings/template literals (including `sql` tags). Use a **type-checked query builder**, preference order **Kysely > Drizzle > other builders with comparable compile-time checking**. | | 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` +The following are confirmed present as `skills//` directories in darkmatter/skills. If you're tempted to invoke `coding-standards`, `systematic-debugging`, `verification-before-completion`, `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `frontend-design`, `browser-use`, `caveman`, `caveman-review`, `compress`, `neon-postgres`, or `hl-funding-analysis` — none of these exist as a skill; see "Known gaps" in [`docs/catalog.md`](https://github.com/darkmatter/skills/blob/main/docs/catalog.md). -**Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync`, `writing-plans`, `executing-plans` +**Always-on:** `brainstorming`, `test-driven-development` (or its overlapping twin `tdd`), `definition-of-done` -**Agent orchestration:** `subagent-driven-development`, `dispatching-parallel-agents` +**Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync`, `finishing-a-development-branch`, `handoff` -**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `repository-organization`, `end-of-turn-review`, `writing-skills` +**Debugging & code quality:** `diagnose`, `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `repository-organization`, `end-of-turn-review`, `writing-skills`, `improve-codebase-architecture` -**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access` +**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `choose-dev-entrypoints` -**Workflow:** `finishing-a-development-branch`, `dm-skill-creator`, `find-skills`, `run-meeting-summary` +**Workflow:** `dm-skill-creator`, `find-skills`, `grill-me`, `grill-with-docs`, `triage`, `zoom-out`, `prototype` -**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design` +**UI:** `ui-ux-pro-max`, `vercel-react-best-practices`, `ui-component-architecture`, `shadcn-registry-first`, `kickoff-dm-design` (manual), `run-ui-registry-variations` (manual) -**Platform:** `nextjs-to-rwsdk-migration`, `openchronicle-setup`, `neon-postgres` +**Platform:** `nextjs-to-rwsdk-migration`, `openchronicle-setup`, `rust-best-practices` -**Browser:** `browser-use` (Python/persistent), `agent-browser` (CDP/Node/Rust) +**Browser:** `agent-browser` (CDP/Node/Rust) -**Communication:** `caveman`, `caveman-commit`, `caveman-review`, `compress` +**Communication:** `caveman-commit` + +**Manual-invocation only:** `run-meeting-summary`, `kickoff-dm-design`, `run-ui-registry-variations` **Runtime policies (auto):** `using-superpowers` (session start), `continuous-learning` (session end), `strategic-compact` (long autonomous sessions) diff --git a/CLAUDE.md b/CLAUDE.md index 0a90ddd..f0eeada 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) + +Project READMEs MUST follow [Standard Readme](https://github.com/RichardLitt/standard-readme) as the default structure. At minimum: title + one-line description, background when needed, a table of contents for READMEs over 100 lines, a copy-pasteable Install block, a copy-pasteable Usage/quickstart block, the standard development command surface (ADR-0002), configuration/secrets documentation (without exposing values), a verification/testing command, contributing guidance, and license last. Documentation-only repos may omit install/usage if they say so explicitly. + +### 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 application code MUST NOT embed SQL as inline strings or template literals — including tagged-template helpers like `` sql`...` `` — since the compiler cannot check table/column names, joins, or nullability through them. Use a type-checked query builder or ORM instead. Preference order: **Kysely > Drizzle > other builders with comparable compile-time checking**. Narrower carve-outs exist for plain `.sql` files consumed by external DB tooling and for TypeScript migration files. + ### OTel-only observability **Status:** Accepted @@ -118,17 +128,28 @@ App code depends only on OpenTelemetry SDKs. Provider-specific packages (`@sentr Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatter/skills) via Nix Home Manager. Full catalog: [`docs/catalog.md`](https://github.com/darkmatter/skills/blob/main/docs/catalog.md). +> **Note:** this section lists skills confirmed present as `skills//` directories in darkmatter/skills. Earlier versions of this file also listed `coding-standards`, `systematic-debugging`, `verification-before-completion`, `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `frontend-design`, `browser-use`, `caveman`, `caveman-review`, `compress`, `neon-postgres`, and `hl-funding-analysis` — none of these have a matching skill directory (some were deliberately removed upstream, most were never built). They're tracked as "Known gaps" in [`docs/catalog.md`](https://github.com/darkmatter/skills/blob/main/docs/catalog.md); don't invoke them by name until they exist. + ### Apply on every task | Skill | When | |-------|------| -| `coding-standards` | Any TypeScript/JS/React/Node code authoring or review | | `brainstorming` | Before any non-trivial implementation | -| `test-driven-development` | Before writing implementation code | -| `systematic-debugging` | Before proposing fixes for bugs or failures | -| `verification-before-completion` | Before claiming work is done | +| `test-driven-development` | Before writing implementation code (`tdd` is an overlapping, equally valid entry point) | | `definition-of-done` | Complex, multi-step tasks | +### Debugging & code quality + +| Skill | Use for | +|-------|--------| +| `diagnose` | Full reproduce → minimise → hypothesise → instrument → fix loop for hard bugs and perf regressions | +| `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 "deepening" refactor opportunities (shallow → deep modules) | +| `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 | + ### Architecture & infrastructure | Skill | Use for | @@ -137,7 +158,8 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `alchemy` | Alchemy v2 infrastructure (Cloudflare/AWS providers) | | `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 | +| `repository-organization` | Repo layout, Standard README (ADR-0006), ADR placement, agent context | +| `choose-dev-entrypoints` | Assign dev-env responsibilities across Nix/Just/Bun/Turborepo/scripts | ### Task and workflow @@ -145,53 +167,47 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt |-------|--------| | `beads-setup` | Onboard a repo onto `bd` (run when `.beads/` is missing) | | `beads-linear-sync` | Configure Beads ↔ Linear sync | -| `writing-plans` | Plan before implementation | -| `executing-plans` | Execute a written implementation plan with review checkpoints | -| `subagent-driven-development` | Execute plans via dispatched subagents | -| `dispatching-parallel-agents` | Delegate 2+ independent tasks to isolated subagents in parallel | | `finishing-a-development-branch` | Merge, PR, or cleanup after implementation | | `dm-skill-creator` | Create a new team-wide skill | -| `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) | -| `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 | +| `handoff` | Compact the current conversation into a handoff doc for a fresh agent | +| `grill-me` | Interview the user relentlessly to stress-test a plan or design | +| `grill-with-docs` | Same, but also updates CONTEXT.md/ADRs inline as decisions crystallize | +| `triage` | State-machine issue triage (bug/enhancement × needs-triage/ready-for-agent/etc.) | +| `zoom-out` | Map relevant modules/callers at a higher abstraction level before diving in | +| `prototype` | Build a throwaway prototype to answer a design question before committing | ### UI/Frontend | Skill | Use for | |-------|--------| -| `frontend-design` | Distinctive, production-grade UI | | `ui-ux-pro-max` | Design system intelligence (styles, palettes, fonts, UX guidelines) | | `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; graduate reusable units into `@repo/ui` | +| `shadcn-registry-first` | Install existing shadcn/shadcnblocks components before hand-rolling UI | +| `kickoff-dm-design` | **Manual.** Design-room kickoff: Linear ticket + Slack post from a Claude Design URL | +| `run-ui-registry-variations` | **Manual.** Build exactly 3 UI variations from shadcn registries | ### Browser automation | Skill | Use for | |-------|--------| -| `browser-use` | Browser automation via `browser-use` CLI with persistent sessions (Python) | -| `agent-browser` | Chrome/Chromium via CDP — prefer for Node.js/Rust workflows | +| `agent-browser` | Browser automation via Chrome/Chromium CDP — Node.js/Rust workflows | -### Communication & compression +### Communication | Skill | Use for | |-------|--------| -| `caveman` | Ultra-compressed communication (~75% token savings) | | `caveman-commit` | Ultra-compressed conventional commit messages (subject ≤50 chars) | -| `caveman-review` | Ultra-compressed code review comments (one line per finding) | -| `compress` | Compress natural-language memory files into caveman format | ### Domain-specific | Skill | Use for | |-------|--------| -| `neon-postgres` | Neon Serverless Postgres | | `openchronicle-setup` | Local-first agent memory (macOS) | -| `hl-funding-analysis` | Hyperliquid perp funding rate analysis | +| `rust-best-practices` | Idiomatic Rust (borrowing, error handling, clippy, perf, type-state) | +| `run-meeting-summary` | **Manual.** Resolve meeting artifacts and draft approved Obsidian summaries | ### Runtime policies (auto-applied by agent client) From ee7417b6f87ef98ea5e6b89d6cb4a006e39c8c8f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Jul 2026 16:18:18 +0000 Subject: [PATCH 2/2] docs: reference ADR-0008 for the telemetry decision, not an unnumbered bullet darkmatter/skills docs/adr now has a filed ADR-0008 (decouple telemetry concerns) backported from the obsidian wiki's already-accepted write-up. Point at it instead of the informal "OTel-only observability" heading. --- .github/copilot-instructions.md | 2 +- AGENTS.md | 2 +- CLAUDE.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5c3db28..02339d3 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -18,7 +18,7 @@ Reusable agent skills and architecture decision records live in [darkmatter/skil | 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: title, background if needed, TOC over 100 lines, copy-pasteable install + usage, documented command surface (ADR-0002), config/secrets docs, verification command, contributing, license last. | | ADR-0007 | TypeScript MUST NOT embed SQL as inline strings/template literals (incl. `sql` tags). Use a type-checked query builder — preference order Kysely > Drizzle > comparable alternatives. | -| OTel | App code imports only OTel SDKs; provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | +| ADR-0008 | App code imports only OTel SDKs; provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | ## Always apply diff --git a/AGENTS.md b/AGENTS.md index 3a77e7e..4e4d92d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,7 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills) | [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) | READMEs follow **Standard Readme**: title, background if needed, TOC over 100 lines, copy-pasteable install + usage, documented command surface (ADR-0002), config/secrets docs, a verification command, contributing, license last. | | [0007](https://github.com/darkmatter/skills/blob/main/docs/adr/0007-type-checked-sql-in-typescript.md) | TypeScript MUST NOT embed SQL as inline strings/template literals (including `sql` tags). Use a **type-checked query builder**, preference order **Kysely > Drizzle > other builders with comparable compile-time checking**. | -| OTel | App code imports only **OpenTelemetry SDKs**. Provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | +| [0008](https://github.com/darkmatter/skills/blob/main/docs/adr/0008-decouple-telemetry-concerns.md) | App code imports only **OpenTelemetry SDKs**. Provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | --- diff --git a/CLAUDE.md b/CLAUDE.md index f0eeada..ca1983a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -117,10 +117,10 @@ Project READMEs MUST follow [Standard Readme](https://github.com/RichardLitt/sta TypeScript application code MUST NOT embed SQL as inline strings or template literals — including tagged-template helpers like `` sql`...` `` — since the compiler cannot check table/column names, joins, or nullability through them. Use a type-checked query builder or ORM instead. Preference order: **Kysely > Drizzle > other builders with comparable compile-time checking**. Narrower carve-outs exist for plain `.sql` files consumed by external DB tooling and for TypeScript migration files. -### OTel-only observability -**Status:** Accepted +### ADR-0008: Decouple telemetry concerns +**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0008-decouple-telemetry-concerns.md) -App code depends only on OpenTelemetry SDKs. Provider-specific packages (`@sentry/*`, PostHog, Datadog) never appear in `apps/*`. Provider wiring is isolated in shared packages. +App code depends only on OpenTelemetry SDKs. Provider-specific packages (`@sentry/*`, PostHog, Datadog) never appear in `apps/*`. Provider wiring is isolated in shared packages, exposed to apps only as OTel exporters/instrumentation plugins — swapping a provider should be a config change, not a refactor. ---