Skip to content

sync org instructions: ADR-0006 + 11 new skills from darkmatter/skills #5

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

sync org instructions: ADR-0006 + 11 new skills from darkmatter/skills #5

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
12 changes: 8 additions & 4 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,26 +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. |
| 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

- `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)

Expand Down
11 changes: 7 additions & 4 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<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>`). |
| [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`

Expand Down
35 changes: 34 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,22 @@ 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.

### 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

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

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

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

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

Expand Down Expand Up @@ -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).
Loading