AGENTS.md@.claude git:20260919.78f0586A

Immutable. This exact content never changes and is served at /api/v1/blob/f28471d89025d50d.

# .claude/

Binplaced dogfood copy of the `project-toolkit` plugin tree (`src/claude/`), not a marketplace source since ADR-109 B6; `hooks/` and `skills/` have own guides.

## Matters

- Generated, never hand-edit: `agents/`, `rules/`, `skills/<name>/SKILL.md`, `hooks/`, `settings.json`, `lib/` packages plus `lib/bootstrap.py`. Sources are `templates/` files and the repo's `scripts/` packages in the `rjmurillo/ai-agents` repository.
- Hand-maintained here: `lib/` (mixed, see next line), `CLAUDE.md`, this guide, the seven doc files under `hooks/`, each skill's non-`SKILL.md` files. No manifest: `.claude-plugin/plugin.json` was deleted at B6.
- `lib/` mixed: `ai_review_common/`, `github_core/`, `hook_utilities/`, `bootstrap.py` are binplaced renders of `scripts/` packages, never hand-edit; the top-level modules (`claude_hook_dispatch.py`, `paths.py`, siblings) have no `scripts/` source and are edited here.

## Entry points

- New rule: `templates/rules/<name>.md` with `paths:` frontmatter; a literal `{{` is written `\{{`. Needs an activation scenario or its id in the pre-PR `Rule Activation Coverage` baseline. Language-universal scope is budget-gated, not blocked: pre-PR `Instruction Budget (always-on)`.
- Always-on rules use `paths: ["**"]` and `priority: critical`: `rules/universal.md`, `builder-ethos.md`, and `voice.md`. Keep membership aligned with `skills/context-optimizer/references/model-context-doctrine.md`. The pre-PR `Always-on Corpus Claims` gate checks that membership.
- `settings.json` renders from `templates/hooks/settings.tmpl`, no plugin-tree hop: `hooks` wires four session-boundary events for this checkout (`SessionStart`, `UserPromptSubmit`, `SessionEnd`, `PreCompact`); `permissions`, `env`, `enabledPlugins` are separate top-level keys; `enabledPlugins` pins `project-toolkit@ai-agents` to `false` (JSON `false` only) so this checkout does not load its own plugin twice.

## Where to look

| Path | Why |
|---|---|
| `rules/*.md` | Rendered copy binplaced by `build_all.py`; `generate_rules.py` mirrors the plugin tree, not this copy, to two instruction trees |
| `CLAUDE.md` | Passive every session; edit outside `<claude-mem-context>` |

## Skip

- `.gitignore`: excludes `settings.local.json`, `*.local.*` only.

## Constraints

- Every `.md` under `agents/` needs a non-empty `description:`; the loader registers any file there as a subagent regardless. Pre-PR `Agent Tree Frontmatter (.claude/agents)` fails on a miss, no allowlist. Fix the template, never here.
- Adding a per-call event (`PreToolUse`, `PostToolUse`, `PermissionRequest`, `PostToolUseFailure`): clear every MUST in `tool-use-hook-bar.md` (auto-loads for `settings.json`). The four session-boundary entries are outside it.

## Dangerous assumptions

- "`rules/`, `agents/`, `skills/<name>/SKILL.md`, `hooks/`, `settings.json`, `lib/` packages are hand-authored" is false since ADR-109 B1 to B5; `generated-artifacts.md` auto-loads for all but `settings.json`.
- "A hook wired in `settings.json` ships to plugin consumers" is false; see `.claude/hooks/AGENTS.md`.
- "This guide loads like `CLAUDE.md`" is false: on demand, never passively budgeted.

## Dependencies

- `lib/` packages and `bootstrap.py` arrive by binplace from the repo build, one command, no separate sync step (ADR-109 B5); a hand edit here reds pre-PR `Generated Artifact Staleness`.

## Architecture

- `lib/` is both origin and waypoint.

## Commands

Repository-only, from the `rjmurillo/ai-agents` root, not shipped:

```bash
# paths: only, never applyTo:/globs:/alwaysApply:.
uv run python scripts/validation/check_rule_scope_keys.py
uv run python scripts/validation/check_agent_tree_frontmatter.py
uv run python scripts/validation/pre_pr.py
```