darkmatter-repo-setup

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.

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:

1. package.json — root manifest, scripts, catalog, engines
2. packages/tooling — shared tsconfig and oxc config
3. TypeScript configs — root + per-package (consult

effect-solutions show tsconfig)

1. Linting & formatting — oxlint.config.ts, .oxfmtrc.json
2. Testing — vitest.config.ts (consult effect-solutions show testing)
3. Zed config — .zed/settings.json (consult

effect-solutions show project-setup)

1. Nix flake — flake.nix, flake/, nix/, bun.nix
2. justfile
3. ops/ directory — full structure with READMEs
4. CI — .github/workflows/ci.yaml
5. .gitignore
6. Docs — architecture.md, getting-started.md, README.md
7. Effect source code — services, data models, errors, config

(consult effect-solutions show for each area)

1. AGENTS.md — last, because it documents everything else. First run

nix run github:darkmatter/skills#install in the repo root: it writes the org-wide shared instructions into AGENTS.md between <!-- BEGIN docs/AGENTS.md --> / <!-- END docs/AGENTS.md --> markers and creates CLAUDE.md as @AGENTS.md if missing. Never edit inside the markers; put repo-specific text below them. Add nix run github:darkmatter/skills#install -- --check to CI.

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.