AGENTS.md@src/claude git:20261018.5d69fdbA

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

# src/claude/

`project-toolkit` plugin source (ADR-109 B6; `claude-agents` retired) in the `rjmurillo/ai-agents` repository. The trees below binplace into `.claude/`, the dogfood copy (ADR-119: `agents/`, `skills/` as symlinks).

<!-- vendor-portability: repo-only contributor guide; templates/, build/, .github/agents/ and sibling src/ trees do not ship with this plugin -->

## Matters

- Generated (ADR-109 B1 to B4): `agents/` 30, `rules/` 23 (repo-only rules stay in `.claude/rules/`), `skills/<name>/SKILL.md` 111, `hooks/` plus `hooks.json`.
- Hand-maintained: `claude-instructions.template.md`, `security/references/`, `.claude-plugin/plugin.json`, this file, `skills/<name>/` files but `SKILL.md`.
- Edit the template, never the render. A hand-edit fails its Template Drift gate next run.
- Agent frontmatter: `name`, `description`, `argument-hint` in all 30. `metadata.role` in 24. `tools:` only `analyst.md`, `security.md`.
- `skills/<name>/`: `SKILL.md` renders from its template; `scripts/`, `references/`, `tests/` are hand-maintained here.

## Entry points

- `templates/agents|rules|skills|hooks/` is the edit location; per-class render map in `templates/AGENTS.md`. Generator order, owned prefixes, binplace, gate semantics: `build/AGENTS.md`.

## Where to look

| Path | Why |
|---|---|
| `agents/merge-resolver.md`, `agents/pr-comment-responder.md`, `agents/quality-auditor.md` | Hard-code a plugin-root skills path; see Constraints |

## Skip

- `.claude/agents/`, shipped `.claude/skills/<name>`, shipped `.claude/rules/<name>.md`: symlinks here. `.claude/hooks/` minus its seven docs: binplace copies.

## Constraints

- Cross-harness change: read `agent-harness-reference` first. In the ai-agents repository, route through `ai-agents-portability-campaign`.
- `model:` needs an ADR-080 `KEEP_PIN` sidecar entry, or a bare alias (`sonnet`, `opus`, `haiku`) plus `model-rationale:` priced below the harness default through the platform `model_tiers` map (`check_model_pins.py`). None qualifies; no Copilot agent may pin, since `.github/agents` links to it.
- Those three agents read `${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/<name>/scripts` (`merge-resolver.md` still bare `${CLAUDE_PLUGIN_ROOT:-.claude}`; `plugin-self-containment.md` MUST 2 wants the nested form). Resolves against this plugin's own `skills/`, where support files live (#5794); before that the fallback needed a second install.

## Dangerous assumptions

- `git add` silences the `src/` staleness gate and proves nothing; commit.

## Dependencies

- Marketplace entry `project-toolkit`, `source: ./src/claude` (B6); `.claude/` is not listed. Nothing above this directory ships to an installer.

## Architecture

- A render stage, not a source.

## Commands

```bash
uv run python build/scripts/build_all.py                   # regenerate every tree
uv run python build/scripts/build_all.py --check            # drift gate, all four classes
```