git:20260428.65f8b2e to git:20260501.5824c48

10 added, 4 removed. Audit A to A.

# AGENTS.md

Repo-local agent instructions live in [AGENT_RULES.md](./AGENT_RULES.md).

Any coding agent working in this repository must:

1. Read `AGENT_RULES.md` before creating or materially revising a skill.

2. Treat `SKILL.md` frontmatter as the canonical skill metadata source.

3. Apply `standards/skill-content-contract.md` (what to say) and `standards/skill-authoring-style.md` (how to say it) when authoring or editing SKILL.md content.

4. Use `python3 scripts/search_knowledge.py` before creating a new skill or claiming a coverage gap.

5. Run `python3 scripts/skill_sync.py` and `python3 scripts/validate_repo.py` after skill changes.

6. Never hand-edit generated files in `registry/`, `vector_index/`, or `docs/SKILLS.md`.

## Working on agents (not skills)

Agents live under `agents/<slug>/AGENT.md`. Before editing or adding one:

1. Read `agents/_shared/AGENT_CONTRACT.md` for the frontmatter spec, required

section order, confidence rubric, and structured citation/output formats.

2. For skill-builder agents, also read `agents/_shared/SKILL_BUILDER_CORE.md`.

3. Reuse probes from `agents/_shared/probes/` instead of hand-rolling MCP

queries.

4. Use refusal codes from `agents/_shared/REFUSAL_CODES.md` in output envelopes.

After editing any `AGENT.md` run:

```bash

python3 scripts/validate_repo.py --agents

```

`validate_repo.py --all` runs both skill and agent validation (slow; skill

compilation + query fixtures). Use `--agents` or `--skills-only` for fast

iteration.

## Install the git hooks (strongly recommended)

One-time setup per clone:

```bash

python3 scripts/install_hooks.py

```

This configures `core.hooksPath` to `.githooks/` and installs two hooks:

- **`pre-commit`** — runs `skill_sync --changed-only` and `validate_repo --changed-only`. Fast (<5s).

- **`pre-push`** — runs the full 4-shard validation CI runs. Catches cross-cutting drift (stale registries, schema-enum drift, missing query fixtures) that `--changed-only` can't see. 10–20s.

Bypass for WIP: `git commit --no-verify` / `git push --no-verify`. CI still gates merge.

## Reading / updating the skill queue

- `MASTER_QUEUE.md` is the authoritative queue. Do not `grep`/`sed` it — use:

+ `BACKLOG.yaml` is the authoritative machine-readable queue (the row data formerly

+ inside `MASTER_QUEUE.md`, migrated 2026-05-01). Do not hand-edit it — use:

```bash

python3 scripts/queue_reader.py --summary

python3 scripts/queue_reader.py --next --status TODO,RESEARCHED

python3 scripts/queue_reader.py --set-status IN_PROGRESS \

- --id <skill-name-or-row-id> --actor "<agent-name>@<host>"

+ --id <entry-id> --actor "<agent-name>@<host>"

```

- See `docs/QUEUE_FORMAT_PROPOSAL.md` for the reader contract and the deferred

- YAML migration plan.

+ The generated dashboard at `docs/queue-progress.md` shows status counts, drift

+ between queue and disk, oldest TODO, and the next 10 picks. It regenerates on

+ every `skill_sync.py` run.

+ `MASTER_QUEUE.md` is now a short prose intro + agent workflow doc. The

+ historical row data is preserved in git history and reproducible from a

+ pre-migration `MASTER_QUEUE.md` via `scripts/_migrations/migrate_queue_to_yaml.py`.

## Running agent evals

```bash

python3 evals/agents/scripts/run_agent_evals.py --structure # lint fixtures

python3 evals/agents/scripts/run_agent_evals.py --agent field-impact-analyzer --output path/to/output.json

```

Fixture format lives in `evals/agents/framework.md`.