Repo notes for AI coding agents
## Commit identity (required)
All commits in this repo must be authored as:
- **Name:** `Ryan Alexander Alberts`
- **Email:** `25306145+RyanAlberts@users.noreply.github.com` — GitHub's noreply address
agents.
Claude Code-specific reminders:
- The optional Claude Code sub-agent prompts live in `plugins/spec-driven-develop/agents/`, including `code-reviewer.md`, the per-lane review-and-fix sub-agent used in the execution loop
build UI, running this setup is the **FIRST thing you do — before any code.** Skipping it
is exactly how the output lands generic (default indigo, tight type, template layout
TypeScript CLI plus ink/React TUI that manages
Agent Skills installed for Claude Code, Codex, Gemini, and OpenClaw.
## Critical commands
```bash
npm install # postinstall no-ops when CI or ASM_SKIP
CONTRACT= RATIONALE="…"`. No bypass flag; "reviewed, no doc change needed" is a legitimate rationale. See `docs/contribute/drift-contracts.md`.
- **`make agent-test` at the end of every coding session.** Heartbeat lines while running
This is the last gate before code enters the repository — treat it as a codereview, not a formality.
- **Read the full diff** (`git diff` for unstaged, `git diff --cached
there is a less complex alternative.
when planning a task that involves writing code:
First research review the existing code. Think about the best way to structure the solution, such
runtime; a CLI lacking `get` abandons a live review); `pane zoom` is unprobed as cosmetic. The wait loop treats `{"error":{"code":"pane_not_found"}}` as authoritative death (nothing closed, nothing
buffa-types/src/generated/` shows as modified, you forgot to commit the regen.
## Pre-Commit CodeReview
Before producing a commit, run **both** review agents in parallel (single message, two Agent
Astro site, deployed to Cloudflare Pages from this repository's `main` branch. MIT licensed (code) / CC BY 4.0 (content).
Live: <https://specification.website> and <https://specification-website.pages.dev>.
## Top-level rule: everything
A file Claude Code reads at the start of every session. It holds the commands, conventions and warnings the agent needs for this project.
Where does it go?
At the repository root. Claude Code also reads CLAUDE.md files in subdirectories when it works there.
What should it contain?
Build and test commands, the project's layout, conventions that aren't obvious from the code, and mistakes to avoid. Short files tend to work better than long ones.
CLAUDE.md or AGENTS.md?
Claude Code reads CLAUDE.md; most other agents read AGENTS.md. Many projects keep one and point the other at it.