domain-experts: Instructions file for Claude Code

Domain Experts — session bootstrap

Before doing ANY work in this repo, read these three files in full, in this order:

1. AGENTS.md — what lives where, the rules, release checklist, known pitfalls
2. CONTRIBUTING.md — especially the "Exact recipe for adding a role (follow verbatim)" section
3. docs/CONTEXT.md — where the last session left off

Non-negotiables when adding or editing roles

• New roles are spec: 2 per AUTHORING.md: SKILL.md + references/ trio, worked example with real reconciling numbers, each idea stated exactly once.
• Order of operations: write files → git add roles/<slug> → python3 scripts/lint_roles.py <slug> until 0 errors → python3 scripts/generate_roadmap.py → commit everything together → git pull --rebase --autostash → push.
• Never hand-edit generated content: README role-count block, ROADMAP checklist, data/roles.json.
• Another session may be pushing to main concurrently — always pull --rebase --autostash before push.
• Quality bar: a practitioner should nod, not shrug. If a role would ship generic, skip it and pick another — an empty slot is recoverable, a generic role poisons trust.

Dual-Graph Context Policy

This project uses a local dual-graph MCP server for efficient context retrieval.

MANDATORY: Always follow this order

1. Call graph_continue first — before any file exploration, grep, or code reading.

2. If graph_continue returns needs_project=true: call graph_scan with the current project directory (pwd). Do NOT ask the user.

3. If graph_continue returns skip=true: project has fewer than 5 files. Do NOT do broad or recursive exploration. Read only specific files if their names are mentioned, or ask the user what to work on.

4. Read recommended_files using graph_read — one call per file.

   • graph_read accepts a single file parameter (string). Call it separately for each recommended file. Do NOT pass an array or batch multiple files into one call.
   • recommended_files may contain file::symbol entries (e.g. src/auth.ts::handleLogin). Pass them verbatim to graph_read(file: "src/auth.ts::handleLogin") — it reads only that symbol's lines, not the full file.
   • Example: if recommended_files is ["src/auth.ts::handleLogin", "src/db.ts"], call graph_read(file: "src/auth.ts::handleLogin") and graph_read(file: "src/db.ts") as two separate calls (they can be parallel).