From 33851013d8d7bc93a3594d90a4cbc7097f58506d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Feb 2026 18:54:14 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20add=20Agent=20Execution=20Protocol=20(A?= =?UTF-8?q?GENTS.md=20=C2=A715)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduces a structured meta-workflow for AI agents that ensures safe incremental changes, persistent state across context resets, and a clear decision trail for multi-agent coordination. Key additions: - Work scoping (goal, success criteria, non-goals) - External notes files (CONTEXT.md, TODO.md, DECISIONS.md, TEST_LOG.md) - Locate → Implement → Verify → Update notes work loop - Context recovery procedure for new agent sessions - Quality bar principles - Cross-references from CLAUDE.md to the new section https://claude.ai/code/session_0159eSJrqKvKpgDiwYZ2iGxK --- AGENTS.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 7 +++- 2 files changed, 105 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 58de9098..0f3a5c55 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -407,6 +407,105 @@ Use these for stable element targeting: --- +## 15. Agent Execution Protocol + +This section defines the meta-workflow that **every AI agent** must follow when executing tasks in this codebase. It ensures safe, incremental changes, a clear decision trail, and continuity across context resets or agent hand-offs. + +### Mindset + +- Implement changes safely. Match existing conventions. Leave a clear trail of decisions. +- Correctness > cleverness. Consistent conventions > personal preference. Explicit tradeoffs > "should work." +- Prefer minimal, incremental changes over rewrites. Keep the build and tests green. +- Do not invent files, APIs, libraries, or behaviors. If unsure, inspect the codebase first. + +### Scoping the Work + +Before writing any code, establish clarity on three things: + +1. **Primary goal** — What is being built or fixed? +2. **Success criteria** — How will we know it's done? (e.g., tests pass, feature visible in UI, lint clean) +3. **Non-goals** — What is explicitly out of scope? (Prevents scope creep across agent sessions.) + +### External Notes (Persistent State Files) + +Agents lose context across sessions. These files in the repo root act as persistent memory that any agent (or human) can read to resume work or understand project status. **Update them before any likely context reset.** + +| File | Purpose | When to Update | +|------|---------|----------------| +| `CONTEXT.md` | Current goal, scope, assumptions, constraints, and a "Definition of Done" checklist | At the start of a task; when scope changes | +| `TODO.md` | Checkbox task list with "Done" and "Blocked/Questions" sections | After planning; after completing or discovering tasks | +| `DECISIONS.md` | Key choices made, alternatives considered, and rationale | When making tradeoffs or architectural decisions | +| `TEST_LOG.md` | Commands run and their results (including failures) | After every lint/test/build run | + +**Rules for external notes:** +- These files are working documents, not permanent artifacts. They should reflect the *current* state of work. +- When starting a fresh task, clear stale content and re-scope. Don't let old context mislead the next agent. +- Keep entries concise — bullet points and checklists, not prose. +- `DECISIONS.md` is especially important: when you make a tradeoff (e.g., "used innerHTML here because the template is static HTML, updated the baseline"), write it down so the next agent doesn't undo it. + +### Work Loop + +For each task item, repeat this cycle: + +#### A) Locate + +- Identify the relevant code and existing patterns. Find the "right place" to make the change. +- Write a short plan (3–7 bullets) before editing. If the task touches multiple subsystem zones (see Section 12), flag this — it may need to be split into separate PRs. + +#### B) Implement + +- Make the smallest change that satisfies the requirement. +- Keep edits cohesive. Avoid unrelated refactors in the same commit. +- Follow all conventions already documented in this file (logging via `logger`, token-first styling, magnet safety, schema definitions in `nostrEventSchemas.js`, etc.). + +#### C) Verify + +- Run the most relevant lint/test commands (see CLAUDE.md "Available Scripts" for the full list): + ```bash + npm run lint # Required + npm run test:unit:shard1 # Fast feedback; run full suite before PR + ``` +- If there's no test coverage for your change, add focused tests or document in `DECISIONS.md` why tests aren't feasible. +- Log all commands and results in `TEST_LOG.md`. + +#### D) Update Notes + +- Check off completed items in `TODO.md`. +- Record decisions in `DECISIONS.md`. +- Log verification results in `TEST_LOG.md`. +- **Do this before any likely context/memory reset** — if you're about to hit a token limit, finish a long session, or hand off to another agent, update notes first. + +### Context Recovery + +If an agent starts a session and finds existing work-in-progress: + +1. **Immediately read** `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, and `TEST_LOG.md`. +2. Resume from the next unchecked item in `TODO.md`. +3. Verify the current state by running `git status`, `git log --oneline -10`, and a quick lint/test pass. +4. Do not re-do work that `TEST_LOG.md` shows already passed — unless the code has changed since. + +### Output Requirements + +When finishing a task or handing off, provide: + +- **Summary** of what changed and why. +- **Files changed** (list). +- **Verification results** (from `TEST_LOG.md`). +- **Follow-ups / risks / remaining TODOs**. +- **If blocked:** Ask specific questions and propose 1–2 options. + +### Quality Bar + +| Principle | Meaning | +|-----------|---------| +| Correctness over cleverness | Simple, working code beats elegant abstractions | +| Conventions over preference | Match what's already in the repo, even if you'd do it differently | +| Explicit tradeoffs | Write down *why* in `DECISIONS.md`, don't leave the next agent guessing | +| Logged verification | Every claim of "tests pass" must have a `TEST_LOG.md` entry to back it up | +| Incremental over sweeping | Small, reviewable changes that keep the build green at every step | + +--- + ## Next Please read these documents next. diff --git a/CLAUDE.md b/CLAUDE.md index 2c3c9897..5890894e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -84,6 +84,10 @@ bitvid/ | `tests/e2e/helpers/bitvidTestFixture.ts` | Reusable Playwright fixture for agent testing | | `scripts/agent/simple-relay.mjs` | Mock Nostr relay with HTTP seeding API | | `docs/nostr-event-schemas.md` | Event schema documentation | +| `CONTEXT.md` | Agent working state: current goal, scope, assumptions (see AGENTS.md §15) | +| `TODO.md` | Agent task checklist with done/blocked sections (see AGENTS.md §15) | +| `DECISIONS.md` | Agent decision log: choices, alternatives, rationale (see AGENTS.md §15) | +| `TEST_LOG.md` | Agent verification log: commands run and results (see AGENTS.md §15) | --- @@ -475,6 +479,7 @@ When assigning work to agents: | `docs/playback-fallback.md` | URL-first strategy | | `docs/moderation/README.md` | Moderation system | | `docs/logging.md` | Logger usage | +| `CONTEXT.md` / `TODO.md` / `DECISIONS.md` / `TEST_LOG.md` | Agent persistent state files (see AGENTS.md §15) | --- @@ -525,7 +530,7 @@ Validation: Must have `title` + at least one of `url` or `magnet`. ## Final Notes -1. **Read AGENTS.md first** — it contains mission-critical architectural decisions +1. **Read AGENTS.md first** — it contains mission-critical architectural decisions and the Agent Execution Protocol (§15) 2. **Check KNOWN_ISSUES.md** — avoid investigating pre-existing failures 3. **Use sharded tests** — faster feedback during development 4. **Never commit generated CSS** — `css/tailwind.generated.css` is gitignored