# Healthcare Agents Repository Instructions

## Repository Map

- Agent prompts live in `agents/*.md`.
- The simple self-improvement kit lives in `.claude/commands/eval.md`, `eval/rubric.md`, `eval/results.tsv`, and `eval/role-baselines/`.
- The old Python eval harness has been removed. The active eval path is the simple self-improvement kit above.
- This repo uses `bd` as the active bead tracker. If external skills or copied
  prompts mention `br` or `bv`, translate to the equivalent `bd` workflow
  instead of abandoning tracker work. Useful local commands: `bd prime`,
  `bd show <id>`, `bd children <id>`, `bd ready -n 100`, `bd list --json`,
  `bd dep tree <id>`, `bd update <id> --claim`, and `bd close <id> --reason "..."`
  after current evidence proves the acceptance criteria.
- Use `bd-agent-sync pull` before creating, claiming, updating, or closing
  beads, and `bd-agent-sync push` after Beads changes. Do not create markdown
  TODO ledgers, scratch JSONL files, or parallel agent backlogs. `.beads/issues.jsonl`
  is the only supported JSONL bridge and must be managed by `bd import` and
  `bd export`, not hand-edited. `bd sync` is not available in bd 1.0.2 on
  Plumbob.

## Git Workflow

- Do not push directly to `main`.
- For requested edits, create a short-lived branch, commit there, push the branch, open a PR, and merge the PR with `gh pr merge`.
- 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.
- After a PR is merged, run `git fetch origin --prune` and align local `main` to `origin/main` before continuing work.
- 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`.

## Self-Improvement Loop

- 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.
- Treat `.claude/commands/eval.md` as the canonical workflow for both Claude Code and Codex.
- 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`.
- Avoid recursive CLI invocation when native subagents are available.
- Never modify `eval/rubric.md` or any file under `eval/role-baselines/`.
- Never modify `eval/results.tsv` except to append rows.
- Preserve the agent's distinctive role identity; do not flatten prompts into generic "best practices" boilerplate.
- 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/`.