From 531d39ace97f1af8a5021b1ca1927407137d773d Mon Sep 17 00:00:00 2001 From: indifferentketchup Date: Sun, 24 May 2026 23:22:57 +0000 Subject: [PATCH] v2.0 proposal update: add AGENTS.md extensions, Boomerang pattern, observation hooks, follow-up batches Additions from second pass of boocode_code_review.md: - AGENTS.md extensions: output_schema, exit_expression, execution_strategy (qodo-ai/agents MIT), expert_model escape hatch (RA.Aid Apache-2.0) - Subagent isolation via Boomerang Tasks pattern: orchestrator-only-dispatches, down-pass/up-pass context discipline, fresh session per subtask - Observation hooks: 5-event taxonomy from budi (SessionStart, UserPromptSubmit, PostToolUse, SubagentStart, Stop) mapped to WS frames - Follow-up batches table: PR-resolver, HMAC audit log, blind-validation gate, majority-vote ensembler, drift detection, anti-slop, globstar gate, Docker sandbox, multi-provider LLM - Additional repo to clone: qodo-ai/agents for agent.toml schema reference Co-Authored-By: Claude Opus 4.7 (1M context) --- openspec/changes/v2.0-boocoder/proposal.md | 78 +++++++++++++++++++++- 1 file changed, 75 insertions(+), 3 deletions(-) diff --git a/openspec/changes/v2.0-boocoder/proposal.md b/openspec/changes/v2.0-boocoder/proposal.md index a9177b0..c0b346e 100644 --- a/openspec/changes/v2.0-boocoder/proposal.md +++ b/openspec/changes/v2.0-boocoder/proposal.md @@ -262,13 +262,85 @@ All dependencies shipped. v2.0 is unblocked. - No OAuth in v2.0. MCP server is stdio-only until secret storage lands. - DB rename `boocode_db` → `boochat_db` lands with v2.0.0 (one-time migration). +## AGENTS.md extensions (v2.0.0) + +Port from `qodo-ai/agents` (MIT) `agent.toml` schema and `ai-christianson/RA.Aid` (Apache-2.0) three-stage pattern: + +| Field | Type | Purpose | Source | +|---|---|---|---| +| `steps` | number | Per-agent step cap (already shipped v1.14.0) | opencode | +| `output_schema` | JSON Schema | Structured output constraint for the agent's final response | qodo-ai/agents | +| `exit_expression` | string | Regex/predicate — when the agent considers itself done | qodo-ai/agents | +| `execution_strategy` | `plan` \| `act` \| `research` | Which phase of the RA.Aid three-stage pattern this agent operates in | qodo-ai/agents + RA.Aid | +| `model` | string | Per-agent model override (already shipped v1.8) | — | +| `expert_model` | string | Escalation model for hard reasoning (RA.Aid "expert tool" escape hatch) | RA.Aid | + +The three-stage pattern maps to BooCoder's use case: +- **Research agent** (cheap model) → understand the task, find relevant files +- **Planning agent** (standard model) → decide which files to edit, what the changes look like +- **Implementation agent** (full model) → produce the actual diffs + +`expert_model` is the escape hatch: a routine model handles most subtasks, but can call the expert model (e.g. qwopus27b) when stuck. Matches Sam's existing cost-routing discipline. + +## Subagent isolation (Boomerang pattern, v2.0.1) + +From Roo Code Boomerang Tasks (Apache-2.0 pattern): + +When an orchestrator agent calls a `new_task` tool, BooCoder: +1. Creates a fresh `tasks` row with `parent_task_id` pointing to the orchestrator's task +2. Spawns a fresh inference session (Path A) or dispatch (Path B) with ONLY the task spec as context — no inherited conversation +3. Child runs to `attempt_completion`, writes a summary to `tasks.output_summary` +4. Parent resumes reading ONLY the summary (not the child's full conversation) + +**Three principles:** +- Orchestrator capability restriction: the orchestrator agent's tool list includes ONLY `new_task`, `list_tasks`, `check_task_status` — it cannot read files or call MCP tools directly +- Down-pass: parent sends task spec via `new_task(input)`, nothing else inherited +- Up-pass: child sends result via `attempt_completion(summary)`, nothing else surfaces to parent + +This is the **single most important context-management primitive** — it prevents long-running orchestrators from poisoning their context with implementation detail. + +## Observation hooks (v2.0.3) + +From `siropkin/budi` (MIT) Claude Code 5-hook taxonomy: + +Register BooCoder as a hook receiver for dispatched agents. Five events: +- `SessionStart` — agent spawned +- `UserPromptSubmit` — task spec delivered +- `PostToolUse` — each tool call completed +- `SubagentStart` — nested dispatch +- `Stop` — agent finished + +These map directly to BooCode's existing WS frame protocol. The hook receiver is the BooCoder Fastify server; events flow into the `message_parts` taxonomy as `step_start`-style instrumentation parts. + +## Follow-up batches (v2.0+ optional, ordered by value) + +| Batch | Source | What | When | +|---|---|---|---| +| **PR-resolver tool** | `qodo-ai/qodo-skills` (MIT) | Fetch GitHub issues → batch/interactive fix → inline PR reply. BooCoder tool that replaces Sam's manual PR workflow. | v2.0.3+ | +| **HMAC audit log** | `sipyourdrink-ltd/bernstein` (verify license) | One new `audit_log` table with `prev_hmac` field. Tamper-evident history of every edit BooCoder makes. Small lift (~50 LoC). | v2.0.1+ | +| **Blind-validation gate** | `covibes/zeroshot` (MIT) | Verify gate runs in a separate agent context that sees ONLY the diff + acceptance criteria, not the producing conversation. Complements Boomerang (isolation) + bernstein (lineage). | v2.0.2+ | +| **Majority-vote ensembler** | `augmentcode/augment-swebench-agent` (MIT) | K candidate diffs from K agents → ranker model picks the best one. Optional layer above `pending_changes`. | v2.1+ | +| **Drift detection** | `memovai/memov` (MIT) | `validate_commit` concept — detects when actual changes diverge from what was requested. Shadow timeline comparison. | v2.0.3+ | +| **Anti-slop for frontend** | `Leonxlnx/taste-skill` (MIT) | 100+ specific font/color/layout ban list + 3-dial parameterization. Vendor into skills/ when BooCoder generates frontend code. | v2.0+ | +| **Verify-before-commit gate** | `DeepSourceCorp/globstar` (MIT) | Rule-based AST linter as a pre-apply quality gate. YAML checkers in `.globstar/`. | v2.1+ (parked) | +| **Docker sandbox** | `OpenHands/OpenHands` (MIT) | Per-session Docker container for write tools. Closes the `/opt:rw` mount risk if path-guard ever proves insufficient. | v2.1 (optional) | +| **Multi-provider LLM** | `earendil-works/pi` (MIT) | Provider abstraction if a need for Anthropic/OpenAI/Mistral direct surfaces beyond llama-swap. | v2.x (optional) | + ## Repos to clone before starting ```bash cd /opt/forks -git clone https://github.com/Dominic789654/agent-hub.git # Apache-2.0, task DAG reference +git clone https://github.com/Dominic789654/agent-hub.git # Apache-2.0, task DAG + dispatcher git clone https://github.com/plandex-ai/plandex.git # MIT, pending-changes UX -git clone https://github.com/anomalyco/opencode.git # MIT, permission evaluate.ts + MCP client reference +git clone https://github.com/anomalyco/opencode.git # MIT, permission evaluate.ts reference +git clone https://github.com/qodo-ai/agents.git # MIT, agent.toml schema (output_schema, exit_expression, execution_strategy) ``` -ACP SDK is an npm package (`@zed-industries/agent-client-protocol`), installed at implementation time. Paseo is design-only (AGPL, no code lift). +Also read (no clone needed): +- `ai-christianson/RA.Aid` README — three-stage pattern + expert-tool escape hatch +- `getpaseo/paseo` README + `skills/` directory — daemon architecture + CLI verbs (AGPL, design-only) +- `agentclientprotocol.com` spec — ACP stdio protocol +- `goose-docs.ai/docs/guides/acp-clients/` — `context_servers` auto-forward pattern +- `siropkin/budi` README — 5-hook Claude Code taxonomy for observation + +ACP SDK and MCP SDK are npm packages installed at implementation time.