diff --git a/formulas/run-gardener.toml b/formulas/run-gardener.toml index 4fa067c..9c4869b 100644 --- a/formulas/run-gardener.toml +++ b/formulas/run-gardener.toml @@ -261,16 +261,19 @@ CRITICAL: If this step fails, log the failure and move on. needs = ["dust-bundling"] # ───────────────────────────────────────────────────────────────────── -# Step 5: agents-update — AGENTS.md watermark staleness check +# Step 5: agents-update — AGENTS.md watermark staleness + size enforcement # ───────────────────────────────────────────────────────────────────── [[steps]] id = "agents-update" -title = "Check AGENTS.md watermarks, update stale files" +title = "Check AGENTS.md watermarks, update stale files, enforce size limit" description = """ -Check all AGENTS.md files for staleness and update any that are outdated. +Check all AGENTS.md files for staleness, update any that are outdated, and +enforce the ~200-line size limit via progressive disclosure splitting. This keeps documentation fresh — runs 2x/day so drift stays small. +## Part A: Watermark staleness check and update + 1. Read the HEAD SHA from preflight: HEAD_SHA=$(cat /tmp/gardener-head-sha) @@ -288,12 +291,93 @@ This keeps documentation fresh — runs 2x/day so drift stays small. - Read the AGENTS.md and the source files in that directory - Update the documentation to reflect code changes since the watermark - Set the watermark to the HEAD SHA from the preflight step - - Conventions: max ~200 lines, architecture and WHY not implementation details + - Conventions: architecture and WHY not implementation details -6. Stage ONLY the AGENTS.md files you changed — do NOT commit yet. - All git writes happen in the commit-and-pr step at the end. +## Part B: Size limit enforcement (progressive disclosure split) -7. If no AGENTS.md files need updating, skip this step entirely. +After all updates are done, count lines in the root AGENTS.md: + wc -l < "$PROJECT_REPO_ROOT/AGENTS.md" + +If the root AGENTS.md exceeds 200 lines, perform a progressive disclosure +split. The principle: agent reads the map, drills into detail only when +needed. You wouldn't dump a 500-page wiki on a new hire's first morning. + +6. Identify per-directory sections to extract. Each agent section under + "## Agents" (e.g. "### Dev (`dev/`)", "### Review (`review/`)") and + each helper section (e.g. "### Shared helpers (`lib/`)") is a candidate. + Also extract verbose subsections like "## Issue lifecycle and label + conventions" and "## Phase-Signaling Protocol" into docs/ or the + relevant directory. + +7. For each section to extract, create a `{dir}/AGENTS.md` file with: + - Line 1: watermark + - The full section content (role, trigger, key files, env vars, lifecycle) + - Keep the same markdown structure and detail level + + Example for dev/: + ``` + + # Dev Agent + + **Role**: Implement issues autonomously ... + **Trigger**: dev-poll.sh runs every 10 min ... + **Key files**: ... + **Environment variables consumed**: ... + **Lifecycle**: ... + ``` + +8. Replace extracted sections in the root AGENTS.md with a concise + directory map table. The root file keeps ONLY: + - Watermark (line 1) + - ## What this repo is (brief overview) + - ## Directory layout (existing tree) + - ## Tech stack + - ## Coding conventions + - ## How to lint and test + - ## Agents — replaced with a summary table pointing to per-dir files: + + ## Agents + + | Agent | Directory | Role | Guide | + |-------|-----------|------|-------| + | Dev | dev/ | Issue implementation | [dev/AGENTS.md](dev/AGENTS.md) | + | Review | review/ | PR review | [review/AGENTS.md](review/AGENTS.md) | + | Gardener | gardener/ | Backlog grooming | [gardener/AGENTS.md](gardener/AGENTS.md) | + | ... | ... | ... | ... | + + - ## Shared helpers — replaced with a brief pointer: + "See [lib/AGENTS.md](lib/AGENTS.md) for the full helper reference." + Keep the summary table if it fits, or move it to lib/AGENTS.md. + + - ## Issue lifecycle and label conventions — keep a brief summary + (labels table + dependency convention) or move verbose parts to + docs/PHASE-PROTOCOL.md + + - ## Architecture Decisions — keep in root (humans write, agents enforce) + + - ## Phase-Signaling Protocol — keep a brief summary with pointer: + "See [docs/PHASE-PROTOCOL.md](docs/PHASE-PROTOCOL.md) for the full spec." + +9. Verify the root AGENTS.md is now under 200 lines: + LINE_COUNT=$(wc -l < "$PROJECT_REPO_ROOT/AGENTS.md") + if [ "$LINE_COUNT" -gt 200 ]; then + echo "WARNING: root AGENTS.md still $LINE_COUNT lines after split" + fi + If still over 200, trim further — move more detail into per-directory + files. The root should read like a table of contents, not an encyclopedia. + +10. Each new per-directory AGENTS.md must have a watermark on line 1. + The gardener maintains freshness for ALL AGENTS.md files — root and + per-directory — using the same watermark mechanism from Part A. + +## Staging + +11. Stage ALL AGENTS.md files you created or changed — do NOT commit yet. + All git writes happen in the commit-and-pr step at the end: + find . -name "AGENTS.md" -not -path "./.git/*" -exec git add {} + + +12. If no AGENTS.md files need updating AND root is under 200 lines, + skip this step entirely. CRITICAL: If this step fails for any reason, log the failure and move on. Do NOT let an AGENTS.md failure prevent the commit-and-pr step.