From c3b97da5f7a8e902d94b58688c694304c4d78ac7 Mon Sep 17 00:00:00 2001 From: cooper <1325802+czxtm@users.noreply.github.com> Date: Mon, 1 Jun 2026 09:10:23 -0700 Subject: [PATCH] import skills catalog + fix ADR-0005 numbering from darkmatter/skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix ADR-0004b reference → ADR-0005 (typed settings module) with correct file link - Add missing skills to CLAUDE.md: browser-use, agent-browser, caveman family, compress, continuous-learning, dispatching-parallel-agents, end-of-turn-review, executing-plans, find-skills, kickoff-dm-design, run-meeting-summary, strategic-compact, using-superpowers, writing-skills - Add Runtime policies and Browser automation skill sections - Update AGENTS.md with full skill list including all new categories - Expand copilot-instructions.md with complete skill catalog and ADR-0005 fix --- .github/copilot-instructions.md | 41 ++++++++++++++++++++++--------- AGENTS.md | 20 ++++++++++----- CLAUDE.md | 43 +++++++++++++++++++++++++++++---- 3 files changed, 81 insertions(+), 23 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2995f36..20e244b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,4 +1,4 @@ -# Darkmatter — GitHub Copilot Instructions +# Darkmatter — GitHub Copilot & Codex Instructions ## Skills and ADRs @@ -11,17 +11,34 @@ 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. | -| ADR-0002 | Every repo exposes `install`, `setup`, `test`, `build`, `ci`, `console` via `./scripts/` or `just ` | -| ADR-0003 | Cross-language types use Protobuf + `buf`. Default transport: ConnectRPC. Commit generated code. | -| ADR-0004a | No reinvention — check for existing libraries before implementing | -| ADR-0004b | One typed `src/settings.` per binary; no scattered `process.env` reads; fail fast at startup | -| OTel | App code imports only OTel SDKs; provider wiring lives in shared packages | +| 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-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. | +| OTel | App code imports only OTel SDKs; provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | ## Always apply -- `coding-standards` on any 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 +- `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 +- `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` + +**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `end-of-turn-review`, `writing-skills` + +**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization` + +**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design` + +**Browser automation:** `browser-use` (Python, persistent sessions), `agent-browser` (CDP, Node/Rust) + +**Communication:** `caveman`, `caveman-commit` (compact commit messages), `caveman-review` (compact reviews), `compress` + +**Domain:** `neon-postgres`, `openchronicle-setup`, `hl-funding-analysis` diff --git a/AGENTS.md b/AGENTS.md index f1a0647..0cc4d29 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,8 +15,8 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills) | [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. | -| [0004a](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. | -| [0004b](https://github.com/darkmatter/skills/blob/main/docs/adr/0004-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. | +| [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`). | | OTel | App code imports only **OpenTelemetry SDKs**. Provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | --- @@ -25,18 +25,26 @@ Full details: [darkmatter/skills](https://github.com/darkmatter/skills) **Always-on:** `coding-standards`, `brainstorming`, `test-driven-development`, `systematic-debugging`, `verification-before-completion`, `definition-of-done` -**Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync` +**Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync`, `writing-plans`, `executing-plans` -**Code quality:** `requesting-code-review`, `receiving-code-review`, `codebase-cleanup`, `repository-organization` +**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` -**Workflow:** `finishing-a-development-branch`, `writing-plans`, `subagent-driven-development`, `dm-skill-creator` +**Workflow:** `finishing-a-development-branch`, `dm-skill-creator`, `find-skills`, `run-meeting-summary` -**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices` +**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design` **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) + --- ## Per-repo agent context diff --git a/CLAUDE.md b/CLAUDE.md index ceada60..0a90ddd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,7 +72,7 @@ Any codebase sharing types across a language boundary MUST use Protobuf as the I Exemptions: pure libraries, services with ≤5 endpoints + single language + single first-party client, schema-as-code setups where all typed consumers are in the same language. -### ADR-0004a: No reinvention +### ADR-0004: No reinvention **Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0004-no-reinvention.md) Before writing an implementation, check whether it's a solved problem. @@ -81,8 +81,8 @@ Before writing an implementation, check whether it's a solved problem. 2. **Search before writing.** If it would exceed ~20 lines or touches a well-known domain (encoding, escaping, formatting, parsing, cryptography, date/time, protocols), assume a library exists. 3. **A dependency is preferable to a private reimplementation.** Libraries have tests, handle edge cases, and receive upstream fixes. -### ADR-0004b: Application config in one typed settings module -**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0004-typed-settings-module-decoupled-from-provider.md) +### ADR-0005: Application config in one typed settings module +**Status:** Accepted | [Full ADR](https://github.com/darkmatter/skills/blob/main/docs/adr/0005-typed-settings-module-decoupled-from-provider.md) Every binary has exactly one settings module (`src/settings.`) that: - Declares all configuration inputs in a typed struct/service @@ -146,12 +146,18 @@ 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 | ### UI/Frontend @@ -161,6 +167,23 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `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 | + +### 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 | + +### Communication & compression + +| 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 @@ -170,6 +193,16 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `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 | + --- ## Working conventions @@ -178,6 +211,6 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt 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-0004b. +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-0004b). +7. **One settings module per binary.** No scattered `process.env` reads (ADR-0005).