diff --git a/BRAIN.md b/BRAIN.md index 16504d0..cb2f502 100644 --- a/BRAIN.md +++ b/BRAIN.md @@ -34,6 +34,127 @@ --- +## 🤖 Subagent Orchestration Rules (MANDATORY) + +**When spawning Bob, Alice, or Charlie, these rules are NON-NEGOTIABLE:** + +### 1. Progress Comment Requirement +- Subagent MUST add task comment every **15 minutes** using format: + ``` + [YYYY-MM-DD HH:MM] 🔄 In Progress + **What was just done:** [completed items] + **What is next:** [immediate step] + **What is left to do:** [remaining checklist] + ``` +- Use: `./scripts/task.sh update --add-comment "..."` + +### 2. Timeout Behavior +- If subagent times out, it MUST have either: + - Marked task complete, OR + - Added comment explaining blocker +- **Never let subagents die silently** + +### 3. My Responsibility (Max) +- Check subagent status every 20 minutes during active work +- If no comment in 20 min → investigate immediately +- If user asks "what's happening with X" → I failed, not the subagent + +### 4. Spawn Instructions Template +Always include in task spawn: +``` +**CRITICAL RULES:** +1. Read your SOUL.md at /Users/mattbruce/.openclaw/workspace/agents/[your-name]/SOUL.md +2. Add progress comment every 15 minutes +3. DO NOT timeout without finishing OR explaining blocker +4. DO NOT mark task as done - end with "Ready for Charlie" or "Needs fixes" +5. You have [X] minutes +``` + +### 5. Task Status Rules (VIOLATION = REOPEN) +**Bob (Implementer):** +- ✅ CAN: Mark task "in-progress" when starting +- ❌ CANNOT: Mark task "done" or "review" +- ✅ MUST: End with "Ready for Charlie" announcement +- **SOUL.md:** `/Users/mattbruce/.openclaw/workspace/agents/bob-implementer/SOUL.md` + +**Charlie (Tester):** +- ✅ CAN: Mark task "review" if issues found +- ❌ CANNOT: Mark task "done" +- ✅ MUST: End with "Ready for deploy" or "Needs fixes" +- **SOUL.md:** `/Users/mattbruce/.openclaw/workspace/agents/charlie-tester/SOUL.md` + +**Alice (Researcher):** +- ✅ CAN: Mark task "in-progress" when starting +- ❌ CANNOT: Mark task "done" +- ✅ MUST: End with "Ready for Bob" or report to user +- **SOUL.md:** `/Users/mattbruce/.openclaw/workspace/agents/alice-researcher/SOUL.md` + +**Human (Matt) only:** +- ✅ CAN: Mark task "done" after validation + +--- + +## 🚧 Cap Gates - Task Admission Control (NEW) + +**From Alice's Multi-Agent Research (@aiedge_ patterns, 2026-02-24)** + +### Maker-Checker Loop Limits +When Bob implements and Charlie reviews: +- **Maximum 3 review cycles** before human escalation +- Cycle 1: Bob → Charlie reject → Bob revises → Charlie re-reviews +- Cycle 2: Repeat once more +- Cycle 3: **HUMAN DECISION REQUIRED** (Cap reached) + +### Cap Gate Triggers +When iteration cap reached: +1. Add comment: "Cap reached at 3 review cycles" +2. Summarize: "Unresolved issues: [list]" +3. Task status → `review` (awaiting human) +4. Human decides: approve / reject / extend cap + +### Task Admission Criteria (Before Spawning Subagents) +Before spawning Alice/Bob/Charlie, verify: +- [ ] Task has clear deliverable (not just "research X") +- [ ] Task has defined success criteria +- [ ] Estimated effort < 2 hours (else break down) +- [ ] Required inputs are available + +**If any unchecked → Do not spawn, ask human for clarification** + +--- + +## 🔗 URL Research Workflow (For Alice-Researcher) + +**Choose the right skill based on user intent:** + +### Quick Save (No Analysis) +**When user says:** "Save this", "Add to documents", "Archive this", "Keep this for later" + +```bash +sessions_spawn: + task: "Save URL to documents: [LINK]. Use save-url-to-documents skill. Extract via Tavily, save to Mission Control Documents (Research/[folder]/), report back with location and quick summary. No task creation, no analysis." + label: "Alice-Save-URL" + runTimeoutSeconds: 300 +``` + +**Output:** Document only (~5 min) + +### Full Research (With Analysis) +**When user says:** "Research this", "Should we use this?", "Analyze this" + +```bash +sessions_spawn: + task: "Research URL: [LINK]. Use url-research-to-documents-and-tasks skill. Full workflow: 1) Extract via Tavily, 2) Save to Mission Control Documents, 3) Read BRAIN.md + TOOLS.md for context, 4) Analyze fit against current infrastructure, 5) Create Gantt task with verdict (ADOPT/EVALUATE LATER/PASS), 6) Attach implementation plan if applicable. Report back with verdict, rationale, and key insight." + label: "Alice-URL-Research" + runTimeoutSeconds: 1200 +``` + +**Output:** Document + Task + Analysis + Plan (~15-20 min) + +**Key difference:** Save = just archive it. Research = should we use it? + +--- + ## 📋 Recurring Patterns *Code patterns, conventions, and templates used frequently.*