From 36c2ad1b52a05c18b3ac7737723e9777689978b8 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 23 Feb 2026 18:49:15 -0800 Subject: [PATCH] docs(agents): require ai-optimized diagram updates on flow changes --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 94ffba5..a44d660 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,8 @@ - **Commit structure:** Prefer small, atomic commits that each represent one meaningful unit of work. Keep unrelated changes out of the same commit. When a change affects docs/diagrams/state, update and commit those alongside the code change (not later). - **Branch + merge workflow:** Do work on a feature branch (`git switch -c feature/`). Keep branches rebased onto `main` (avoid merge commits). When finished: `git rebase main`, then fast-forward merge back to main: `git switch main && git merge --ff-only feature/`, then delete the merged feature branch: `git branch -d feature/`. - **Update state.json:** After every feature implementation, modification, or significant change, update `docs/plans/state.json` accordingly — add new phases/entries, update test counts, adjust the `overall_progress` section, and update the `feature_gap_scorecard` if the gap analysis is affected. Commit state.json alongside the feature change, not as a separate afterthought. -- **Keep docs + diagrams current:** When behavior, config keys, APIs, or architecture changes, update the relevant docs in the same change (README + `docs/`). If the change affects a documented flow, also update the corresponding Mermaid diagrams (e.g. `docs/architecture/AGENT_DIAGRAM.md`, `docs/api/PROTOCOL.md`) so they stay source-of-truth. +- **Keep docs + diagrams current:** When behavior, config keys, APIs, or architecture changes, update the relevant docs in the same change (README + `docs/`). If the change affects a documented flow, also update the corresponding Mermaid diagrams (e.g. `docs/architecture/AGENT_DIAGRAM.md`, `docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md`, `docs/api/PROTOCOL.md`) so they stay source-of-truth. +- **AI-optimized diagram updates are mandatory on flow changes:** Any change to auth/token lifecycle, model routing/fallback/retry behavior, provider execution semantics, gateway queue/session behavior, or config profile generation MUST include matching Mermaid diagram updates in the same PR. - **Track OpenClaw evolution:** Review OpenClaw updates (repo + docs + ecosystem) on a regular cadence (at least monthly, and before major Flynn planning cycles) to identify high-value assistant patterns and candidate features for Flynn. Capture actionable findings in `docs/plans/` and reflect prioritized gaps in `docs/plans/state.json`. ## Build, Lint, and Test Commands