24 added, 0 removed. Audit B to B.
# AGENTS.md—River Reviewer
## Scope
Canonical instructions for all AI coding agents in this repository.
Tool-specific files (`CLAUDE.md`, `GEMINI.md`, `.codex/`, `copilot-instructions.md`) contain only tool-specific policy and point here for repo-wide rules.
If a rule applies to all tools, it belongs in this file.
## Repository Map
| Directory | Purpose |
| ------------------------ | ---------------------------------------------------- |
| `skills/` | Core review skills and registry content |
| `skills/agent-skills/` | Packaged agent skills (`SKILL.md` + `references/`) |
| `src/` | Runtime, CLI, and runner logic |
| `tests/` | Node.js test suites |
| `pages/` | Public docs; Japanese content is the source of truth |
| `docs/` | Internal notes and runbooks; ask before editing |
| `runners/github-action/` | GitHub Action runner implementation |
| `runners/node-api/` | Separate TypeScript package (built with `tsc`) |
| `schemas/` | JSON schemas for skills, output, and riverbed |
| `scripts/` | Validation, evaluation, and build scripts |
## Package Manager
Use **npm**.
| Task | Command |
| ----------------------- | ----------------------------------------------------------------- |
| Install | `npm install` or `npm ci` |
| Lint | `npm run lint` |
| Test | `npm test` |
| Skills validation | `npm run skills:validate` |
| Agent skills validation | `npm run agent-skills:validate` |
| Agent definitions | `npm run agents:validate` |
| Local link check | `npm run check:links:local` |
| Docs dev server | `npm run dev` |
| Docs build | `npm run build` |
| TypeScript check | `npm run build` in `runners/node-api/` (no root typecheck script) |
## Safety
- Do not read or commit `.env*`, `secrets/`, `*.pem`, or `*.key`.
- Do not make direct network calls (curl, wget, fetch) from scripts or code. Allowed CLI tools like `gh` are exempt.
- Do not use destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, etc.).
- Do not hand-edit `package-lock.json`.
- Do not push directly to `main` or to already-merged PR branches. If fixes are needed after merge, create a new branch and new PR.
- Do not omit timeout and exception handling in code that calls external APIs.
## Edit Scope
- **Editable**: `pages/`, `skills/`, `schemas/`, `scripts/`, `tests/`, `.github/`, `.claude/`, `AGENT_LEARNINGS.md`
- **Ask before editing**: `docs/`, `assets/`, `src/`, `runners/`, `README.md`, `README.en.md`, `AGENTS.md`
- **Never edit**: `package-lock.json`, `LICENSE*`, `CITATION.cff`
## Verification Criteria
Run the applicable checks before handoff. All must pass.
| Changed path | Required validation |
| -------------------------------------- | ---------------------------------- |
| `skills/**/*.md` | `npm run skills:validate` |
| `skills/agent-skills/**` | `npm run agent-skills:validate` |
| `.github/agents/` or `.claude/agents/` | `npm run agents:validate` |
| `pages/**/*.md` | `npm run check:links:local` |
| `src/` changes that affect skills | Confirm schema and skill alignment |
| Any file | `npm run lint && npm test` |
Completion gate: all applicable validations pass. If any fail, fix before handoff.
## Workflow
- Keep each change small and cohesive.
- If `src/` changes, confirm schema and skill alignment first.
- Run the verification criteria above before handoff.
- Prefer existing patterns over new conventions.
+ ## Self-Review Checklist
+
+ Apply before handoff. Derived from retrospectives where defects shipped and were caught only by multi-perspective review (see `docs/development/retrospectives/2026-05-21-25.md`).
+
+ ### Codify-then-validate (when adding a rule or convention)
+
+ Before merging a new rule (Stop conditions, severity policy, naming convention, etc.), answer:
+
+ 1. What 3 concrete scenarios would make this rule fail or be misapplied?
+ 2. What is the reopen / exception condition? (e.g. for a Stop rule: how does it lift?)
+ 3. What is the soft-violation gray zone? (e.g. "status report during Stop"—is it allowed?)
+
+ If any answer is "I don't know," defer the rule until the gap is filled. Codify-without-validate produced a same-session defect in #898 → #902.
+
+ ### Code-gen review (when writing a workflow / script / automation)
+
+ Before merging GitHub Actions workflows, shell scripts, or any CI automation, verify:
+
+ 1. Concurrency: can two simultaneous invocations race on shared state (refs, locks, deploys)? Add a `concurrency:` group if yes.
+ 2. Default coupling: do hard-coded defaults (branch names, package names, paths) silently break when an upstream config changes? Prefer auto-detection or fail-loud over silent fallback.
+ 3. Failure mode: what happens on partial failure (network error mid-PATCH, exit code 0 but nothing changed)? Is the error surfaced or swallowed?
+
+ These were the convergent gaps in `.github/workflows/release-please-kick.yml` and `scripts/release-please-kick.sh` at first delivery, fixed in #902.
+
## Commit Attribution
AI-authored commits MUST include a `Co-Authored-By:` trailer with the acting model identity.
## Project Conventions
- `README.md` is the Japanese source of truth; `README.en.md` is best effort.
- `skills/` content is the product surface; validate it after edits.
- Record only durable, reusable repo learnings in `AGENT_LEARNINGS.md`.
- Use English or Japanese skill searches when locating repo conventions.
## Local References
- Core repository architecture: `docs/architecture.md`
- 4-layer agent architecture: `docs/agent-layers.md`
- Development runbook: `docs/runbook/dev.md`
- Skill structure: `skills/README.md`