indifferentketchup/boocode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v2.0 proposal update: add AGENTS.md extensions, Boomerang pattern, observation hooks, follow-up batches

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
indifferentketchup
2026-05-24 23:22:57 +00:00
parent f2974d6887
commit 531d39ace9
1 changed files with 75 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
openspec/changes/v2.0-boocoder/proposal.md
View File

@@ -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. - 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). - 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 ## Repos to clone before starting
```bash ```bash
cd /opt/forks 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/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.