Immutable. This exact content is served forever at /api/v1/blob/09f66456845c9429.
# AGENTS.md—River Review ## 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` | | `skills/**/*.md` (manifest freshness) | `npm run skills:manifest:check` (regenerate with `npm run skills:manifest` if stale) | | `.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`