Skip to content

docs: import ADR-0006/0007/0008 and reconcile skill lists #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cooper (czxtm) wants to merge 2 commits into
base: main
Choose a base branch
from
+72 −51
Draft

docs: import ADR-0006/0007/0008 and reconcile skill lists #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5fad40e
docs: import ADR-0006/0007 and reconcile skill lists with darkmatter/…
claude Jul 6, 2026
ee7417b
docs: reference ADR-0008 for the telemetry decision, not an unnumbere…
claude Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<ext>` 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 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<Row>` tags). Use a type-checked query builder — preference order Kysely > Drizzle > comparable alternatives. |
| ADR-0008 | 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)
26 changes: 15 additions & 11 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<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>`). |
| 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) | 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<Row>` tags). Use a **type-checked query builder**, preference order **Kysely > Drizzle > other builders with comparable compile-time checking**. |
| [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. |

---

## 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/<name>/` 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)

Expand Down
72 changes: 44 additions & 28 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,28 +107,49 @@ 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.

### OTel-only observability
**Status:** Accepted
### ADR-0006: README minimum standard
**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0006-readme-minimum-standard.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.
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<Row>`...` `` — 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.

### 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, exposed to apps only as OTel exporters/instrumentation plugins — swapping a provider should be a config change, not a refactor.

---

## Skills catalog

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/<name>/` 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 |
Expand All @@ -137,61 +158,56 @@ 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

| Skill | Use for |
|-------|--------|
| `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)

Expand Down
Loading