From dc43898d8f18013bf9c4559306c3678e42ad2440 Mon Sep 17 00:00:00 2001 From: Christopher Date: Thu, 2 Jul 2026 09:33:19 +1000 Subject: [PATCH] docs(agents): make .agents/*.md guide reads a required, trigger-keyed gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents (including this one) were skipping the deeper `.agents/*.md` guides because AGENTS.md framed them as optional ("read the relevant guide before specialized work") while its own Always-Read Rules inlined enough summarized content to feel sufficient. That led to concrete misses (e.g. the verification.md rule to publish browser UAT evidence to `agentv-private`). - Intro + Always-Read Rules now state the inline rules are a summary and the linked guide is authoritative when a Routing trigger matches. - Replace the soft guide list + "common entry points" with one required, trigger-keyed Routing table mapping concrete change signals (file paths, wire/naming/grader changes, published surfaces, eval/UAT work, worktree/PR flow, product-boundary calls) to the guide to read first. - Add a completion-gate note: run the verification.md checklist (live dogfood, private evidence) before marking ready even if the start-of-work read was skipped. No guide content changed — the guides were well-scoped; only their invocation from AGENTS.md was unreliable. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6ab4ece17..226a9db6f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AgentV Agent Guide -This file is the root index for repo-facing agent instructions. Read the linked `.agents/*.md` guide for the kind of work you are doing, and read [STRATEGY.md](STRATEGY.md) plus [ROADMAP.md](ROADMAP.md) before making product-boundary calls. +This file is the root index for repo-facing agent instructions. It carries baseline rules that always apply plus a [Routing](#routing) table that maps your change to the deeper `.agents/*.md` guide you must read **before** starting that work. The rules in this file are a summary; each linked guide is authoritative for its area, so a matching Routing trigger means "read the guide," not "the summary is enough." Read [STRATEGY.md](STRATEGY.md) plus [ROADMAP.md](ROADMAP.md) before making product-boundary calls. ## Product Direction @@ -34,6 +34,8 @@ Read the full rationale and examples in [.agents/product-boundary.md](.agents/pr ## Always-Read Rules +These baseline rules apply to every repo change. They summarize the most common cases; when your change matches a [Routing](#routing) trigger, the linked guide is authoritative and required reading before you start — do not treat these bullets as a substitute for it. + - Start every repo change with `git fetch origin` and `git status --short --branch`. - Use `bun` for package and script operations. - Use the operator-supplied tracker when present. Do not commit tracker runtime state, local coordination config, or other machine-local artifacts. @@ -69,19 +71,15 @@ Read the full rationale and examples in [.agents/product-boundary.md](.agents/pr ## Routing -Read the relevant guide before specialized work: - -- [.agents/product-boundary.md](.agents/product-boundary.md): full goals, design principles, AI-first guidance, and how to decide core vs plugin vs docs. -- [.agents/workflow.md](.agents/workflow.md): tracker handling, worktrees, planning, execution, git workflow, PR flow, and documentation update expectations. -- [.agents/verification.md](.agents/verification.md): CI gates, CLI and browser E2E, grader verification, concurrency limits, and the completion checklist. -- [.agents/conventions.md](.agents/conventions.md): TypeScript and Bun conventions, subprocess rules, naming contracts, wire formats, grader type rules, and Python script usage. -- [.agents/publish.md](.agents/publish.md): versioning, publish workflow, contract gates, and published package surfaces. +Reading the guide that matches your change is **required, not optional** — read it before you start the work, not after review. This file only summarizes; the guide is the contract. If your change matches more than one trigger, read each matching guide. -Common entry points: +| If your change… | Read first (required) | +| --- | --- | +| touches TypeScript in `packages/**` or `apps/**`, wire-format keys, naming (`project`/`benchmark`, snake_case vs camelCase), grader types, `artifact_pointers`, or subprocess handling | [.agents/conventions.md](.agents/conventions.md) | +| runs or changes eval execution, experiments, repeat runs, providers, graders, or run artifacts — or needs CLI, Dashboard, docs-site, or browser/screenshot UAT | [.agents/verification.md](.agents/verification.md) | +| involves worktrees, the operator tracker, planning, branches/commits/PR flow, build/artifact reuse, or which docs/examples to update | [.agents/workflow.md](.agents/workflow.md) | +| changes a published package surface (`@agentv/core`, `@agentv/sdk`, `agentv`) — exported types, CLI flags, versioning, or npm publishing | [.agents/publish.md](.agents/publish.md) | +| proposes a feature, changes a core abstraction, or decides core vs plugin vs docs | [.agents/product-boundary.md](.agents/product-boundary.md) (start with [STRATEGY.md](STRATEGY.md) + [ROADMAP.md](ROADMAP.md)) | +| bootstraps or recovers Beads in a worktree | [docs/runbooks/beads-worktree-recovery.md](docs/runbooks/beads-worktree-recovery.md) | -- Product or architecture decisions: start with [STRATEGY.md](STRATEGY.md), [ROADMAP.md](ROADMAP.md), and [.agents/product-boundary.md](.agents/product-boundary.md). -- Tracker, worktree, or PR flow questions: read [.agents/workflow.md](.agents/workflow.md). -- Beads bootstrap or recovery questions: read [docs/runbooks/beads-worktree-recovery.md](docs/runbooks/beads-worktree-recovery.md). -- Dashboard, docs, CLI UX, or grader verification work: read [.agents/verification.md](.agents/verification.md). -- Wire-format, naming, or grader-type changes: read [.agents/conventions.md](.agents/conventions.md). -- Version bumps or npm publishing: read [.agents/publish.md](.agents/publish.md). +Before marking any branch ready for review, run the completion checklist in [.agents/verification.md](.agents/verification.md) — including live dogfood for eval/provider/grader/artifact changes and publishing browser/screenshot UAT evidence to an `agentv-private` branch. Skipping the start-of-work read does not waive these completion gates.