From b4d7a236e80ec95d488d867b91d7416183e583e1 Mon Sep 17 00:00:00 2001 From: cooper <1325802+czxtm@users.noreply.github.com> Date: Mon, 15 Jun 2026 09:11:10 -0700 Subject: [PATCH] feat: sync ADR-0006 and 11 new skills from darkmatter/skills - Add ADR-0006 (README minimum standard) to all org instruction files - Add 8 new skills not yet in org docs: diagnose, grill-me, grill-with-docs, handoff, improve-codebase-architecture, prototype, triage, zoom-out - Add 3 catalog skills missing from org docs: shadcn-registry-first, run-ui-registry-variations, ui-component-architecture - Add "Design & discovery" skills section to CLAUDE.md - Add working convention #8 for README standard --- .github/copilot-instructions.md | 12 +++++++---- AGENTS.md | 11 +++++++---- CLAUDE.md | 35 ++++++++++++++++++++++++++++++++- 3 files changed, 49 insertions(+), 9 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 20e244b..c1bec34 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -16,6 +16,7 @@ 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 | Every non-trivial README follows Standard Readme. Must include: title, install, usage/quickstart, command surface (ADR-0002), config/secrets, verify command, contributing, license. All commands copy/paste-able from repo root. | | OTel | App code imports only OTel SDKs; provider wiring (`@sentry/*`, PostHog, etc.) lives in shared packages only. | ## Always apply @@ -23,19 +24,22 @@ Reusable agent skills and architecture decision records live in [darkmatter/skil - `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 +- `diagnose` — before proposing fixes for hard bugs or performance regressions +- `systematic-debugging` — structured approach to bugs and unexpected behavior - `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` +**Task management:** `beads-setup` (no `.beads/`?), `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `finishing-a-development-branch`, `triage` (issue workflow), `handoff` (session continuity) **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` +**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `repository-organization`, `improve-codebase-architecture`, `zoom-out` -**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design` +**Design & discovery:** `grill-me`, `grill-with-docs`, `prototype` + +**UI/Frontend:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `nextjs-to-rwsdk-migration`, `kickoff-dm-design`, `shadcn-registry-first`, `run-ui-registry-variations`, `ui-component-architecture` **Browser automation:** `browser-use` (Python, persistent sessions), `agent-browser` (CDP, Node/Rust) diff --git a/AGENTS.md b/AGENTS.md index 0cc4d29..caf113b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,25 +17,28 @@ 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) | Every non-trivial README follows **Standard Readme** structure. Must include: title, install, usage/quickstart, command surface (ADR-0002), config/secrets, verify command, contributing, license. All commands copy/paste-able from repo root. | | 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:** `coding-standards`, `brainstorming`, `test-driven-development`, `diagnose` (hard bugs/regressions), `systematic-debugging`, `verification-before-completion`, `definition-of-done` -**Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync`, `writing-plans`, `executing-plans` +**Task management:** `beads-setup` (when `.beads/` missing), `beads-linear-sync`, `writing-plans`, `executing-plans`, `triage` (issue workflow), `handoff` (session continuity) **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` +**Architecture:** `effect-typescript`, `alchemy`, `nix-flake-organization`, `sops-secret-access`, `improve-codebase-architecture`, `zoom-out` + +**Design & discovery:** `grill-me`, `grill-with-docs`, `prototype` **Workflow:** `finishing-a-development-branch`, `dm-skill-creator`, `find-skills`, `run-meeting-summary` -**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design` +**UI:** `frontend-design`, `ui-ux-pro-max`, `vercel-react-best-practices`, `kickoff-dm-design`, `shadcn-registry-first`, `run-ui-registry-variations`, `ui-component-architecture` **Platform:** `nextjs-to-rwsdk-migration`, `openchronicle-setup`, `neon-postgres` diff --git a/CLAUDE.md b/CLAUDE.md index 0a90ddd..d6e62e5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -107,6 +107,22 @@ 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 non-trivial project README MUST follow [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) as the default structure and include at minimum: + +1. **Title and short description** (one line) +2. **Install** — copy/paste-able command block +3. **Usage** — copy/paste-able quickstart from fresh clone to useful result +4. **Development command surface** — standard commands per ADR-0002 +5. **Configuration and secrets** — where env vars, local config, or secrets come from +6. **Testing/verification** — the command a contributor runs to verify the checkout works +7. **Contributing** — where questions go, whether PRs are accepted +8. **License** — state the license (last section) + +Copy/paste-able commands must run as written from the repo root. Agents bootstrap from READMEs — missing anchors increase discovery tax on every contributor and agent. + ### OTel-only observability **Status:** Accepted @@ -125,7 +141,8 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `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 | +| `diagnose` | Before proposing fixes for hard bugs or performance regressions | +| `systematic-debugging` | Structured approach to bugs and unexpected behavior | | `verification-before-completion` | Before claiming work is done | | `definition-of-done` | Complex, multi-step tasks | @@ -138,6 +155,8 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `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 | +| `improve-codebase-architecture` | Surface architectural friction and propose deepening opportunities | +| `zoom-out` | Get a module map when unfamiliar with an area of code | ### Task and workflow @@ -158,6 +177,16 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `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 (needs-triage → ready-for-agent/human/wontfix) | +| `handoff` | Compact the current conversation into a handoff document for the next agent | + +### Design & discovery + +| Skill | Use for | +|-------|--------| +| `grill-me` | Interview you relentlessly to stress-test a plan or design | +| `grill-with-docs` | Grilling against domain model; sharpens terminology and updates CONTEXT.md/ADRs inline | +| `prototype` | Build a throwaway prototype (terminal app for logic, UI variations for design) | ### UI/Frontend @@ -168,6 +197,9 @@ Team-wide skills distribute from [darkmatter/skills](https://github.com/darkmatt | `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 | +| `shadcn-registry-first` | Install registry components before hand-rolling; build 3+ variations | +| `run-ui-registry-variations` | Build exactly three UI variations from shadcnblocks, Aceternity, or Darkmatter registry | +| `ui-component-architecture` | Keep screens thin; reuse `@repo/ui` primitives and graduate components to shared packages | ### Browser automation @@ -214,3 +246,4 @@ These are **not task skills** — they are consumed by the agent runtime to conf 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). +8. **README follows Standard Readme.** Every non-trivial repo needs the standard anchors (ADR-0006).