Repository organization

Keep each repository easy for humans and agents to navigate by putting durable context, reusable guidance, automation, and decisions in the right layer. Prefer the smallest durable home that will be loaded at the time it matters.

When to use

• A user asks where to put a new instruction, convention, policy, skill, command, script, workflow, reference doc, or ADR.
• A repo is accumulating scattered Markdown, duplicated agent instructions, or ad hoc decision notes.
• A change introduces a naming, layout, vendor, architecture, security, deployment, or process decision that future contributors should not re-litigate.
• A README is being created, reorganized, or reviewed for standard structure.
• A user asks whether something belongs in AGENTS.md, .agent/context/, .agent/policy/, .agent/workflows/, skills/, docs/, scripts/, or presets/.
• A project is being bootstrapped from the darkmatter template and needs its local context filled in cleanly.

When NOT to use

• The task is specifically reorganizing Nix flakes, flake-parts outputs, NixOS modules, nix-darwin modules, or Home Manager modules. Use nix-flake-organization.
• The user only asks to create or edit a team-wide skill. Use dm-skill-creator; layer this skill only for placement or ADR questions around that change.
• The user is asking for one-off implementation notes that do not need to survive beyond the current task.
• The repository already has a clear local convention that conflicts with this guidance and the user explicitly wants to preserve it. Follow the local convention and note the tradeoff.