diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 20e244b..3319cc4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -11,34 +11,35 @@ Reusable agent skills and architecture decision records live in [darkmatter/skil | ADR | Rule | |-----|------| -| ADR-0001 | Use `bd` (beads) for task tracking and agent memory. No `TodoWrite` or `MEMORY.md` for cross-session state. `bd prime` at session start. | -| ADR-0002 | Every repo exposes `install`, `setup`, `test`, `build`, `ci`, `console` via `./scripts/` or `just `. Bootstrap: `./scripts/install && ./scripts/setup`. Pre-PR: `./scripts/ci`. | +| ADR-0002 | Every repo exposes `install`, `setup`, `server`/`run`, `test`, `build`, `ci`, `console` via `./scripts/` or `just `. Bootstrap: `./scripts/install && ./scripts/setup`. Pre-PR: `./scripts/ci`. | | 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 | README minimum standard — follow [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) structure: title, install, usage, dev commands, config/secrets, testing, contributing, license last. Copy/paste-able commands. | +| ADR-0007 | Type-checked SQL in TypeScript — no inline SQL strings or tagged templates. Use a schema-derived query builder/ORM. Prefer Kysely; Drizzle allowed when already present. | +| ADR-0008 | Per-language reference codebases under `references/` (currently `rust/`, `go/`, `typescript/`). Skills carry prose; references carry code. Precedence: project `.agent/` → `references/` → general idiom. | +| ADR-0009 | Curate the default skill bundle *(superseded by 0010)*. Home Manager enabled a small explicit allowlist; runtime hooks under `presets/`. Replaced by ADR-0010. | +| ADR-0010 | Install all catalogued skills. Home Manager installs every top-level `skills/` directory — the catalog is the inventory, not an allowlist. Client runtime assets remain under `presets//runtime/`. | | 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 +- `diagnose` — before proposing fixes - `definition-of-done` — any complex multi-step task +- `tdd` — before writing implementation code ## Key skills by category -**Task management:** `beads-setup` (no `.beads/`?), `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `finishing-a-development-branch` +**Architecture:** `effect-typescript`, `alchemy`, `darkmatter-ts-toolchain`, `darkmatter-gitops-conventions`, `nix-flake-organization`, `sops-secret-access`, `choose-dev-entrypoints`, `rust-best-practices`, `repository-organization`, `zoom-out`, `improve-codebase-architecture` -**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `end-of-turn-review`, `writing-skills` +**Code quality:** `codebase-cleanup`, `writing-skills` -**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization` +**Workflow:** `finishing-a-development-branch`, `handoff`, `grill-me`, `grill-with-docs`, `find-skills`, `triage` -**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design` +**UI/Frontend:** `darkmatter-design-system`, `ui-ux-pro-max`, `shadcn-registry-first`, `ui-component-architecture`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `prototype`, `run-ui-registry-variations` -**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` +**Runtime policies (auto):** `using-superpowers` (session start), `strategic-compact` (long autonomous sessions) -**Domain:** `neon-postgres`, `openchronicle-setup`, `hl-funding-analysis` +**Client runtimes (opt-in, not task skills — ADR-0010):** `session-context-pipeline` (Claude hook: session summarizer, doc injection, end-of-turn checklist), `end-of-turn-review` (cross-client review utility) diff --git a/AGENTS.md b/AGENTS.md index 0cc4d29..7f6b554 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,38 +12,36 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills) | ADR | Rule | |-----|------| -| [0001](https://github.com/darkmatter/skills/blob/main/docs/adr/0001-beads-as-task-tracker-and-agent-memory.md) | **Beads (`bd`)** for task tracking and agent memory. `bd prime` to load context; `bd remember` to save; `bd create`/`bd close` for tasks. No `TodoWrite` or `MEMORY.md` for cross-session state. | | [0002](https://github.com/darkmatter/skills/blob/main/docs/adr/0002-standard-project-command-surface.md) | Every repo has `install`, `setup`, `server`/`run`, `test`, `build`, `ci`, `console` via `./scripts/` or `just `. Bootstrap: `./scripts/install && ./scripts/setup`. Pre-PR: `./scripts/ci`. | | [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 minimum standard.** Follow [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) structure: title, install, usage, dev commands (aligns with ADR-0002), config/secrets, testing, contributing, license last. Copy/paste-able commands. | +| [0007](https://github.com/darkmatter/skills/blob/main/docs/adr/0007-type-checked-sql-in-typescript.md) | **Type-checked SQL in TypeScript.** No inline SQL strings or tagged templates (`sql\`...\``). Use a schema-derived query builder/ORM. Prefer **Kysely**; **Drizzle** allowed when already present. | +| [0008](https://github.com/darkmatter/skills/blob/main/docs/adr/0008-per-language-reference-codebases.md) | **Per-language reference codebases** under `references/` (currently `rust/`, `go/`, `typescript/`). Skills carry prose; references carry code. Precedence: project `.agent/` → `references/` → general idiom. | +| [0009](https://github.com/darkmatter/skills/blob/main/docs/adr/0009-curate-default-agent-skill-bundle.md) | **Curate the default skill bundle** *(superseded by 0010).* Home Manager enabled a small explicit allowlist; runtime hooks lived under `presets/`. Replaced by ADR-0010. | +| [0010](https://github.com/darkmatter/skills/blob/main/docs/adr/0010-install-all-catalogued-agent-skills.md) | **Install all catalogued skills.** Home Manager installs every top-level `skills/` directory — the catalog is the inventory, not an allowlist. Client runtime assets remain under `presets//runtime/`. | | 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:** `diagnose`, `definition-of-done`, `tdd` -**Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync`, `writing-plans`, `executing-plans` +**Architecture:** `effect-typescript`, `alchemy`, `darkmatter-ts-toolchain`, `darkmatter-gitops-conventions`, `nix-flake-organization`, `sops-secret-access`, `choose-dev-entrypoints`, `rust-best-practices`, `repository-organization`, `zoom-out`, `improve-codebase-architecture` -**Agent orchestration:** `subagent-driven-development`, `dispatching-parallel-agents` +**Code quality:** `codebase-cleanup`, `writing-skills` -**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `repository-organization`, `end-of-turn-review`, `writing-skills` +**Workflow:** `finishing-a-development-branch`, `handoff`, `grill-me`, `grill-with-docs`, `find-skills`, `triage` -**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access` +**UI:** `darkmatter-design-system`, `ui-ux-pro-max`, `shadcn-registry-first`, `ui-component-architecture`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `prototype`, `run-ui-registry-variations` -**Workflow:** `finishing-a-development-branch`, `dm-skill-creator`, `find-skills`, `run-meeting-summary` +**Browser:** `agent-browser` (CDP/Node/Rust) -**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design` +**Runtime policies (auto):** `using-superpowers` (session start), `strategic-compact` (long autonomous sessions) -**Platform:** `nextjs-to-rwsdk-migration`, `openchronicle-setup`, `neon-postgres` - -**Browser:** `browser-use` (Python/persistent), `agent-browser` (CDP/Node/Rust) - -**Communication:** `caveman`, `caveman-commit`, `caveman-review`, `compress` - -**Runtime policies (auto):** `using-superpowers` (session start), `continuous-learning` (session end), `strategic-compact` (long autonomous sessions) +**Client runtimes (opt-in, not task skills — ADR-0010):** `session-context-pipeline` (Claude hook: session summarizer, doc injection, end-of-turn checklist), `end-of-turn-review` (cross-client review utility) --- diff --git a/CLAUDE.md b/CLAUDE.md index 0a90ddd..9460585 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,23 +16,6 @@ Darkmatter is a small, polyglot engineering team shipping developer tools, crypt These decisions apply to **every** darkmatter project repo unless the project explicitly documents an exception. Full ADR text lives in [darkmatter/skills/docs/adr](https://github.com/darkmatter/skills/tree/main/docs/adr). -### ADR-0001: Beads is the standard task tracker and agent memory store -**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0001-beads-as-task-tracker-and-agent-memory.md) - -Use `bd` (beads) for all task tracking and persistent agent memory. **Do not** use `TodoWrite`, `TaskCreate`, `MEMORY.md`, `TODO.md`, or `NOTES.md` for state that must survive a session. - -| Command | Purpose | -|---------|--------| -| `bd prime` | Load task + memory context at session start | -| `bd create "task"` | Create a task | -| `bd ready` | List tasks with all blockers closed | -| `bd remember "insight"` | Store a memory | -| `bd memories ` | Query stored memories | -| `bd close ` | Close a task | -| `bd linear sync` | Sync bidirectionally with Linear | - -When a repo lacks `.beads/`, apply the `beads-setup` skill before creating tasks. - ### ADR-0002: Standard command surface **Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0002-standard-project-command-surface.md) @@ -107,6 +90,31 @@ 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 darkmatter project README follows [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) as the default structure. Required sections: title + short description, install (copy/paste-able), usage (copy/paste-able quickstart), development command surface (aligns with ADR-0002), configuration/secrets, testing/verification, contributing, and license last. Copy/paste-able means commands run as written from the repo root. + +### 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 (including tagged templates like `` sql`...` ``). Use a type-checked query builder or ORM that derives query types from the database schema. **Kysely** is preferred; **Drizzle** is allowed when already present. If a query can't be expressed through the typed surface, improve the abstraction — do not fall back to inline SQL. + +### ADR-0008: Per-language reference codebases +**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0008-per-language-reference-codebases.md) + +The `references/` section of `darkmatter/skills` holds per-language reference codebases (currently `rust/`, `go/`, `typescript/`) with exemplar code showing preferred conventions. Skills carry prose guidance; references carry code. Precedence when conventions conflict: project `.agent/` rules → `references/` exemplars → general language idiom. + +### ADR-0009: Curate the default agent skill bundle *(superseded)* +**Status:** Superseded by ADR-0010 | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0009-curate-default-agent-skill-bundle.md) + +A small explicit allowlist of team-wide skills was enabled by Home Manager; client-runtime hooks lived under `presets//runtime/`. Replaced by ADR-0010, which installs every catalogued skill. + +### ADR-0010: Install all catalogued agent skills +**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0010-install-all-catalogued-agent-skills.md) + +Home Manager installs **every** top-level directory in `skills/`. The module derives the enabled skill IDs from the source directory — the catalog is the human-readable inventory, not an allowlist. Adding a new skill directory includes it automatically. Client runtime assets remain under `presets//runtime/` and are not installed as task skills. + ### OTel-only observability **Status:** Accepted @@ -116,18 +124,15 @@ App code depends only on OpenTelemetry SDKs. Provider-specific packages (`@sentr ## 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). +Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatter/skills) via Nix Home Manager, which installs every top-level `skills/` directory (ADR-0010). Full catalog: [`docs/catalog.md`](https://github.com/darkmatter/skills/blob/main/docs/catalog.md). ### 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 | +| `diagnose` | Before proposing fixes for bugs or failures | | `definition-of-done` | Complex, multi-step tasks | +| `tdd` | Before writing implementation code (red-green-refactor slices) | ### Architecture & infrastructure @@ -135,82 +140,68 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt |-------|--------| | `effect-typescript` | Effect services, Layers, typed errors, Schema, Alchemy deploys | | `alchemy` | Alchemy v2 infrastructure (Cloudflare/AWS providers) | +| `darkmatter-ts-toolchain` | Org TS toolchain contract: Bun, vitest/oxlint, Effect, Alchemy deploys, changesets | +| `darkmatter-gitops-conventions` | Safe-change playbook for `darkmatter/gitops` (validation, sha-pinned images, SOPS, rollback) | | `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 | +| `choose-dev-entrypoints` | Choose responsibility boundaries across Nix, Just, Bun, Turborepo, scripts | +| `rust-best-practices` | Idiomatic Rust: borrowing, error handling, linting, performance, testing | +| `zoom-out` | Map modules and callers using domain glossary vocabulary — read-only orientation | +| `improve-codebase-architecture` | Surface architectural friction and propose deepening opportunities for testability | ### 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 | +| `handoff` | Compact conversation into a handoff document for a fresh agent | +| `grill-me` | Interview the user relentlessly about a plan until reaching shared understanding | +| `grill-with-docs` | Grilling session that challenges a plan and updates CONTEXT.md and ADRs inline | | `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 | +| `triage` | Move issues through a state machine of triage roles — create, review, or prepare for an AFK agent | ### UI/Frontend | Skill | Use for | |-------|--------| -| `frontend-design` | Distinctive, production-grade UI | +| `darkmatter-design-system` | Canonical darkmatter UI design system — tokens, theming, components; prefer over generic shadcn/ui | | `ui-ux-pro-max` | Design system intelligence (styles, palettes, fonts, UX guidelines) | +| `shadcn-registry-first` | Bias UI work toward existing shadcn registry components before hand-rolling | +| `ui-component-architecture` | Keep React screens thin; reuse `@repo/ui` primitives, avoid div-soup | | `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 | +| `prototype` | Throwaway prototype to answer a design question (terminal app or UI variations) | +| `run-ui-registry-variations` | Build three UI variations from shadcnblocks, Aceternity, or the Darkmatter registry | ### 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` | Chrome/Chromium via CDP — browser automation for Node.js/Rust workflows | -### Communication & compression +### Runtime policies & client runtimes (not task skills) -| 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 +These are **not task skills** (ADR-0010). Auto-applied policies configure session behavior; client runtimes are opt-in hook bundles under `presets//runtime/`. -| Skill | Use for | -|-------|--------| -| `neon-postgres` | Neon Serverless Postgres | -| `openchronicle-setup` | Local-first agent memory (macOS) | -| `hl-funding-analysis` | Hyperliquid perp funding rate analysis | - -### Runtime policies (auto-applied by agent client) - -These are **not task skills** — they are consumed by the agent runtime to configure session behavior. - -| Skill | When | -|-------|------| -| `using-superpowers` | Session start — establishes skill discovery and invocation protocol | -| `continuous-learning` | Session end (Stop hook) — extracts reusable patterns into new skills | -| `strategic-compact` | Long autonomous sessions with auto-compaction enabled | +| Item | Type | When | +|-------|------|------| +| `using-superpowers` | Auto policy | Session start — establishes skill discovery and invocation protocol | +| `strategic-compact` | Auto policy | Long autonomous sessions with auto-compaction enabled | +| `session-context-pipeline` | Opt-in runtime (Claude) | Hook-driven session summarizer, library doc injection, end-of-turn checklist | +| `end-of-turn-review` | Opt-in runtime (cross-client) | Review utility triggered at the end of a turn | --- ## Working conventions -1. **Check for Beads first.** No `.beads/`? Apply `beads-setup` before creating tasks. -2. **Use the standard command surface.** `./scripts/setup` before working; `./scripts/ci` before PRs. -3. **Reference ADRs when making architectural decisions.** Surface conflicts before proceeding. -4. **Secrets use SOPS.** Apply `sops-secret-access` skill; never print decrypted contents. -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). +1. **Use the standard command surface.** `./scripts/setup` before working; `./scripts/ci` before PRs. +2. **Reference ADRs when making architectural decisions.** Surface conflicts before proceeding. +3. **Secrets use SOPS.** Apply `sops-secret-access` skill; never print decrypted contents. +4. **Effect is the default for TypeScript services.** See `effect-typescript` skill and ADR-0005. +5. **Protobuf when crossing language boundaries.** Use `buf`, commit generated code (ADR-0003). +6. **One settings module per binary.** No scattered `process.env` reads (ADR-0005). +7. **Type-checked SQL in TypeScript.** No inline SQL strings — use Kysely or Drizzle (ADR-0007). +8. **READMEs meet the minimum standard.** Follow Standard Readme structure with required onboarding anchors (ADR-0006).