Skip to content

Import full skills catalog + fix ADR-0005 in org agent context #3

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 1 commit into
base: main
Choose a base branch
from
Draft

Import full skills catalog + fix ADR-0005 in org agent context #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
41 changes: 29 additions & 12 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Darkmatter — GitHub Copilot Instructions
# Darkmatter — GitHub Copilot & Codex Instructions

## Skills and ADRs

Expand All @@ -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/<name>` or `just <name>` |
| 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.<ext>` 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/<name>` or `just <name>`. 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.<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. |

## 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`
20 changes: 14 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>` or `just <name>`. 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.<ext>`** 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.<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. |

---
Expand All @@ -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
Expand Down
43 changes: 38 additions & 5 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.<ext>`) that:
- Declares all configuration inputs in a typed struct/service
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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).