AGENTS.md

1# Healthcare Agents Repository Instructions
2 
3## Repository Map
4 
5- Agent prompts live in `agents/*.md`.
6- The simple self-improvement kit lives in `.claude/commands/eval.md`, `eval/rubric.md`, `eval/results.tsv`, and `eval/role-baselines/`.
7- The old Python eval harness has been removed. The active eval path is the simple self-improvement kit above.
8- This repo uses `bd` as the active bead tracker. If external skills or copied
9  prompts mention `br` or `bv`, translate to the equivalent `bd` workflow
10  instead of abandoning tracker work. Useful local commands: `bd prime`,
11  `bd show <id>`, `bd children <id>`, `bd ready -n 100`, `bd list --json`,
12  `bd dep tree <id>`, `bd update <id> --claim`, and `bd close <id> --reason "..."`
13  after current evidence proves the acceptance criteria.
14- Use `bd-agent-sync pull` before creating, claiming, updating, or closing
15  beads, and `bd-agent-sync push` after Beads changes. Do not create markdown
16  TODO ledgers, scratch JSONL files, or parallel agent backlogs. `.beads/issues.jsonl`
17  is the only supported JSONL bridge and must be managed by `bd import` and
18  `bd export`, not hand-edited. `bd sync` is not available in bd 1.0.2 on
19  Plumbob.
20 
21## Git Workflow
22 
23- Do not push directly to `main`.
24- For requested edits, create a short-lived branch, commit there, push the branch, open a PR, and merge the PR with `gh pr merge`.
25- Do not merge the feature branch into local `main` before opening or merging the PR. That creates duplicate local merge commits and makes `main` appear ahead/behind after GitHub merges the PR.
26- After a PR is merged, run `git fetch origin --prune` and align local `main` to `origin/main` before continuing work.
27- For docs-only or metadata-only changes, the streamlined path is: branch -> commit -> push branch -> `gh pr create` -> `gh pr merge --merge --delete-branch` -> sync local `main`.
28 
29## Self-Improvement Loop
30 
31- When asked to run the healthcare self-improvement loop for an agent, first read `.claude/commands/eval.md` and execute that procedure as a normal task, substituting `$ARGUMENTS` with the requested agent slug.
32- Treat `.claude/commands/eval.md` as the canonical workflow for both Claude Code and Codex.
33- If the runtime supports native subagents or model specialization, prefer a strongest scorer/judge plus a faster editor, with the parent agent owning git writes and `eval/results.tsv`.
34- Avoid recursive CLI invocation when native subagents are available.
35- Never modify `eval/rubric.md` or any file under `eval/role-baselines/`.
36- Never modify `eval/results.tsv` except to append rows.
37- Preserve the agent's distinctive role identity; do not flatten prompts into generic "best practices" boilerplate.
38- During a normal eval run, only edit the requested `agents/<slug>.md`, append `eval/results.tsv`, and write local ignored artifacts under `eval/run-logs/`.
39