Darkmatter Repo Setup

You are a setup agent. Your job is to bring the current repository up to darkmatter's production-ready template standards. You audit what exists, fill in what's missing, update what's outdated, and validate the result.

Code organization

Apply codebase-design for the shared readability rules and examples, and domain-organization for names and role directories. Group by owner, then role; keep related SQL, bindings, decoding, and private helpers with the adapter. Expose complete operations through explicit package entries. A template supplies tooling and examples, not a requirement to reproduce its internal file splits.

Preserve configured line limits. Use a documented, targeted increase when a forced split would scatter one responsibility. Do not create a file, service, or test for every helper. Verify behavior through the public interface, including required completion, failure, and cleanup.

Canonical template

Clone the canonical template repo to a temp directory and read from it:

git clone --depth 1 git@github.com:darkmatter/template.git /tmp/darkmatter-template

Read files from

/tmp/darkmatter-template

to understand the target state. Adapt content to the target repo — do not blindly copy project names, package names, or app logic. The structure and conventions are the standard; the specific app is the example.

The template root

package.json

catalog is the preferred-libs home. Align new dependency choices with that catalog, then add only the app-specific libraries the target repo needs. When the current template demonstrates a narrower resource such as D1, keep the current Darkmatter preference in mind: new application data starts on Postgres unless the repo records a specific edge-local or demo reason.

Clean up when done:

rm -rf /tmp/darkmatter-template

Effect best practices

All Effect-related setup and code must follow the Effect Solutions quick-start — the canonical field manual for idiomatic Effect.

Install the

effect-solutions

CLI for agent-accessible best-practice lookup:

bun add -g effect-solutions@latest

Before writing or auditing any Effect-related file, consult the relevant topic:

effect-solutions list                      # list all topics
effect-solutions show project-setup        # language service, reference repos
effect-solutions show tsconfig             # TS compiler settings for Effect
effect-solutions show basics               # Effect.fn and Effect.gen conventions
effect-solutions show services-and-layers  # Context.Service + Layer patterns
effect-solutions show data-modeling        # Schema for data modeling
effect-solutions show error-handling       # Schema.TaggedError
effect-solutions show config               # Effect.Config
effect-solutions show testing              # @effect/vitest

See references/effect-solutions.md for the full topic reference. Use the CLI alongside the repository's installed version and pinned source. Version-specific APIs must match that source; upstream examples do not override local ownership, extraction, or testing conventions.

Workflow

1. Pre-flight

Clone the template repo first (you will need it throughout):

git clone --depth 1 git@github.com:darkmatter/template.git /tmp/darkmatter-template

Determine the repo's current state:

Run
```
git rev-parse --show-toplevel
```
to find the repo root.
List the top-level directory contents.
Read
```
package.json
```
if it exists.
Read
```
AGENTS.md
```
if it exists.
Read
```
flake.nix
```
if it exists.
Check for
```
.zed/
```
,
```
ops/
```
,
```
.github/
```
,
```
docs/
```
,
```
justfile
```
.

Classify the repo:

New repo: no
```
package.json
```
or no
```
flake.nix
```
. Start from the template and adapt.
Existing repo: has some structure already. Audit against the checklist and fill gaps.

2. Audit

Read the supporting checklist at references/checklist.md. Work through every section. For each item, check if the file exists and matches the template standard. Record findings as:

✅ present and compliant
⚠️ present but partial or outdated
❌ missing

Present a summary table to the user before making changes. Include the count of ✅ / ⚠️ / ❌ items.

3. Remediate

For each ❌ or ⚠️ item, create or update the file. Read the corresponding file from the cloned template at

/tmp/darkmatter-template

, adapt it to the target repo, and write it. Work section by section in this order — later sections may depend on earlier ones:

package.json — root manifest, scripts, catalog, engines
packages/tooling — shared tsconfig and oxc config
TypeScript configs — root + per-package (consult
```
effect-solutions show tsconfig
```
)
Linting & formatting — oxlint.config.ts, .oxfmtrc.json
Testing — vitest.config.ts (consult
```
effect-solutions show testing
```
)
Zed config — .zed/settings.json (consult
```
effect-solutions show project-setup
```
)
Nix flake — flake.nix, flake/, nix/, bun.nix
justfile
ops/ directory — full structure with READMEs
CI — .github/workflows/ci.yaml
.gitignore
Docs — architecture.md, getting-started.md, README.md
Effect source code — services, data models, errors, config, effect-orpc routes when the repo needs typed RPC, and Postgres adapters for application data unless the repo documents a different database choice (consult
```
effect-solutions show
```
for each area)

AGENTS.md — last, because it documents everything else. Keep repo-specific instructions in

docs/AGENTS.repo.md

; never edit the generated

AGENTS.md

directly. Add

darkmatter-skills

(

github:darkmatter/skills

) as a flake input and concatenate the shared topics the repo adopts with its own text:

nix

let agents = inputs.darkmatter-skills.agentsMd; in
packages.agents-md = pkgs.writeText "AGENTS.md" (lib.concatStringsSep "\n" [
  (builtins.readFile agents.preamble)
  (builtins.readFile agents.defaults)
  (builtins.readFile agents.showing-code)
  (builtins.readFile agents.must-always)
  (builtins.readFile agents.must-never)
  (builtins.readFile agents.readability)
  (builtins.readFile agents.should)
  (builtins.readFile agents.authority-order)
  (builtins.readFile agents.completion-evidence)
  (builtins.readFile ./docs/AGENTS.repo.md)
]);

Refresh the committed file with:

cp "$(nix build --no-link --print-out-paths .#agents-md)" AGENTS.md

CLAUDE.md

is missing, create it containing

@AGENTS.md

(an existing one is never touched). Add a CI step so a stale

AGENTS.md

fails the build:

diff -u AGENTS.md "$(nix build --no-link --print-out-paths .#agents-md)"

Adaptation rules:

Replace
```
ops-monorepo-demo
```
/
```
@ops-demo/web
```
with the target repo's actual name and package names.
Replace
```
Ops monorepo demo
```
in user-facing strings with the repo's actual display name.
If the repo has an existing app, keep its app logic — only add/fix the surrounding tooling and structure.
If the repo has no app yet, scaffold a minimal
```
apps/web
```
with an Effect/Bun HTTP server and
```
packages/web-core
```
with domain helpers, mirroring the template.
Regenerate
```
bun.nix
```
after any
```
package.json
```
dependency changes by running
```
bun run generate:bun-nix
```
(requires
```
bun2nix
```
on PATH).

4. Validate

After all changes, run the full validation suite from the repo root:

bun install
bun run prepare
bun run check
bun run test
bun run lint
bun run fmt:check
nix flake check
docker compose -f ops/compose/local.yaml config

If any step fails, attempt to fix it. If a step is not applicable (e.g., no Docker), note it and skip. Report the final status of each step.

5. Report

Clean up the cloned template:

rm -rf /tmp/darkmatter-template

Produce a final summary:

What was ✅ already compliant
What was ⚠️ updated
What was ❌ created from scratch
Validation results for each step
Any items that need manual attention (e.g., SOPS age key generation, real secret creation, CI secrets setup)

Constraints

Never commit unless the user explicitly asks.
Preserve existing app logic and unrelated worktree changes.
Never write decrypted SOPS values or plaintext credentials.
Do not add dependencies beyond what the template standard requires.
If a file already exists and is compliant, do not rewrite it.
If a file exists but uses a different valid approach (e.g., a different but equivalent Nix structure), note it but do not force-rewrite unless the user asks.

darkmatter-repo-setup

NPX Install

Tags

SKILL.md Content