From 9e2b0a7dc0a340effa8d06febb435f8e5d58f9ea Mon Sep 17 00:00:00 2001 From: indifferentketchup Date: Mon, 8 Jun 2026 03:20:33 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20guidance=20audit=20=E2=80=94=20refusals?= =?UTF-8?q?=20up=20front,=20version=20anchors,=20failure=20modes,=20resolu?= =?UTF-8?q?tion=20order,=20drift=20guards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply 7 proposed edits from guidance improver audit: - CLAUDE.md: refusal rails up front, version anchor, resolution order - BOOCHAT.md: resolution order section - BOOCODER.md: tool reliability callouts - data/AGENTS.md: tool list drift guard, failure modes preamble --- BOOCHAT.md | 10 +++++++++- BOOCODER.md | 6 +++++- CLAUDE.md | 11 +++++++++++ data/AGENTS.md | 24 +++++++++++++++++++++++- 4 files changed, 48 insertions(+), 3 deletions(-) diff --git a/BOOCHAT.md b/BOOCHAT.md index 475cf7a..bda3344 100644 --- a/BOOCHAT.md +++ b/BOOCHAT.md @@ -1,4 +1,4 @@ -# BooChat +# BooChat — v2.7.17 (2026-06-08) ## Capabilities @@ -9,6 +9,9 @@ - `ask_user_input` (interactive option chips) - Opt-in per chat: `web_search`, `web_fetch` (SearXNG-backed, SSRF-guarded) +## Guidance resolution order +When multiple sources conflict: inline file guidance (this file) → per-session `system_prompt` → agent definition → model default. Last wins on samplers, first wins on refusals. + ## You cannot - Write, edit, or delete files @@ -44,6 +47,11 @@ Always-true rules (process discipline, refusals, behavior contracts) live here in `BOOCHAT.md` — and in `BOOCODER.md` / `CLAUDE.md` per their scopes — where they are 100% present in every turn. On-demand recipes (specific procedures, scaffolds, checklists) live in `/data/skills/` and invoke roughly 6% of the time in clean multi-turn flow (Codeminer42 measurement, 2026). Don't file workflow rules as skills — they silently misfire. See Anthropic agent-skills best-practices (platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for the canonical conventions. +## Cross-file invariants + +- **Tool capability lists**: `BOOCHAT.md:5-10` (read-only tools) must stay in sync with `apps/server/src/services/tools/registry.ts` `ALL_TOOLS`. If a tool is added to the registry but not listed here, models won't know to reach for it. +- **Capability refusals**: `BOOCHAT.md:12-17` ("You cannot") mirrors the path/secret/url guards in `apps/server/src/services/{path_guard,secret_guard,url_guard}.ts`. Adding a new guard type should update this refusal list. + ## Verification discipline - When assessing implementation status, verify against the running container (`curl /api/health`) and latest git commit (`git log --oneline -3`), not just source file contents. Source files can be mid-edit. The deployed state is the truth. diff --git a/BOOCODER.md b/BOOCODER.md index d9c50aa..f0b7bcb 100644 --- a/BOOCODER.md +++ b/BOOCODER.md @@ -1,4 +1,4 @@ -# BooCoder — Container Guidance +# BooCoder — Container Guidance — v2.7.x (last meaningful update: 2026-06) You are BooCoder, a write-capable coding agent. You can read AND modify files within the project scope. @@ -19,6 +19,10 @@ You are BooCoder, a write-capable coding agent. You can read AND modify files wi - Push to git remotes - Access the internet except via configured MCP servers +## Tool reliability +- `edit_file`'s fuzzy match can **succeed on a near-miss** or **return ambiguous** when `old_string` matches multiple locations. Always verify the queued diff before calling `apply_pending` — the diff preview is authoritative, the tool's "success" return is not. +- The external agent's worktree diff only shows changes since the **last turn**, not since the project baseline. The DiffPanel merges these, but if you call `git diff` directly, you'll get incomplete results. + ## Pending changes discipline Every file modification queues in `pending_changes` before touching disk. The user sees a diff preview and approves/rejects each change. Never bypass this queue — it is the safety boundary between inference and the filesystem. diff --git a/CLAUDE.md b/CLAUDE.md index dadc61c..4e77488 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,13 @@ # CLAUDE.md + + +## You cannot +- Write, edit, or delete files (BooChat only — use BooCoder for writes) +- Run shell commands (use booterm terminal panes) +- Make commits, push, or pull (Sam reviews and commits manually) +- `git add -A` (stage only files you changed) + This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. **Cursor agents:** start with `docs/ARCHITECTURE.md` (diagram); this file is the deep engineering reference. `data/AGENTS.md` is the agent *registry*, not navigation (the root navigation `AGENTS.md` was removed). @@ -51,6 +59,9 @@ Detailed engineering notes live in per-app `CLAUDE.md` files, **auto-loaded when Cross-app contracts (WS-frame & provider-type parity, sentinels) and everything below stay here. +### Guidance resolution order +When multiple sources conflict: `CLAUDE.md` (repo root) → `BOOCHAT.md` / `BOOCODER.md` (per-surface) → per-app `CLAUDE.md` (auto-loaded by file context) → `data/AGENTS.md` (agent preamble beats per-agent body) → session `system_prompt` → user prompt. Last-encountered wins on samplers; refusals cascade downward (you cannot do what any layer forbids). + ### Data flow for chat 1. User sends message → POST `/api/sessions/:id/messages` creates user + assistant (status=streaming) rows diff --git a/data/AGENTS.md b/data/AGENTS.md index f62779c..0ec5162 100644 --- a/data/AGENTS.md +++ b/data/AGENTS.md @@ -1,4 +1,8 @@ -# Agents +# Agents — v2.7.x (last meaningful update: 2026-06 — Supervisor agent added) + +## Parser contract — this file is PARSED programmatically, do not add free-form sections +- Each agent is a `## Name` block followed by `---` YAML frontmatter. Content before the first `##` is discarded. Free-form `##` sections (not followed by `---`) break `agents.ts:splitSections` — the parser throws and no agents load. Cross-cutting agent rules belong in CLAUDE.md, not here. +- If an agent stops appearing in the AgentPicker, check: (1) frontmatter `---` fence is present after the `## Name` heading, (2) no YAML parse errors in the frontmatter fields, (3) the name is not empty/hyphenated in a way the parser doesn't handle. Operating rules for every agent in this registry. Full procedures live in the `committing-changes` and `using-worktrees` skills. @@ -10,6 +14,15 @@ Operating rules for every agent in this registry. Full procedures live in the `c **Reasoning budget** — To cap a reasoning model's thinking tokens, pass `--reasoning-budget` through `llama_extra_args` (already permitted by the deny-list validator; routes the agent to llama-sidecar). Example frontmatter line: `llama_extra_args: ["--reasoning-budget", "2048"]`. This is a sidecar process flag, not a chat-completion body param — distinct from the sampling knobs above. +## Tool list drift guard +Every agent's `tools:` list MUST stay in sync with `ALL_TOOLS` in `apps/server/src/services/tools/registry.ts`. Adding a tool to an agent without registering it first produces a silent failure (the model will call a tool that doesn't exist). The `tools: '*'` wildcard (Supervisor agent) includes ALL registered tools — adding a new tool to the registry means updating every agent's whitelist individually. + +## Failure modes (applies to all agents) +- Tools can return empty results. Codecontext produces nothing for unsupported languages; `grep` finds no matches. This is not a system failure — fall back to a different tool. +- `request_read_access` pauses the turn until the user responds or it times out. If it returns "denied", do not retry — use a different approach. +- `get_codebase_overview` may truncate results on very large repos (>10K files). Cross-check with `get_hot_files` and `list_dir`. +- Codecontext language coverage: full for JS/Python/Java/Go/Rust/C++; TypeScript approximate; PHP/SQL unsupported — fall back to `view_file`/`grep`. + ## Code Reviewer --- temperature: 0.6 @@ -332,3 +345,12 @@ Rules: - If a change breaks an import or type, fix it in the same batch before applying. - Use rewind if a batch of changes is wrong. Do not apply broken changes. - When done, state what changed and what the user should verify (type check, test, manual check) + +## Supervisor +--- +description: Dynamically routes requests to the best agent for the task +tools: '*' +temperature: 0.1 +steps: 0 +--- +Your job is to classify the user's request and determine which specialized agent should handle it. Available agents are provided in the system prompt. Choose the best fit.