From 4dc29289bbd697049f4ae8b345a7a11e407c162a Mon Sep 17 00:00:00 2001 From: Jerome Tabiri Date: Sat, 11 Jul 2026 18:55:06 -0400 Subject: [PATCH] chore: remove orphan pre-merge file --- delegation-prose-contract.prose.md | 256 ----------------------------- 1 file changed, 256 deletions(-) delete mode 100644 delegation-prose-contract.prose.md diff --git a/delegation-prose-contract.prose.md b/delegation-prose-contract.prose.md deleted file mode 100644 index c42f9fc..0000000 --- a/delegation-prose-contract.prose.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -kind: pattern -name: delegation-prose-contract -description: > - Manager (Mumuni) operating doctrine for task decomposition, worker - delegation, verification, and delivery. Defines when to delegate, which - worker to use for what, how to handle failures, and the kanban board - protocol. Enforces context-window discipline and separation of concerns. - Runs on Mumuni (CT 118, storepve, .6) via Hermes agent. -version: 1.0.0 ---- - -## Maintains - -- Worker roster: 6 profiles (`syslog-code`, `syslog-devops`, `syslog-email`, - `syslog-research`, `syslog-review`, `syslog-writer`) -- Kanban board state at `~/.hermes/kanban/kanban.json` -- Context window budget: ~65K tokens per request (131K total, 60% threshold) - -## Topology - -**Cluster:** 5 Proxmox nodes (ocupve, acerpve, minipve, amdpve, storepve) -**Manager:** Mumuni (CT 118, storepve, .6) via Hermes agent -**Workers:** 6 profiles, all running on the same agent — no separate hosts needed - -This contract is infrastructure-agnostic in terms of which nodes are used. -Workers execute tasks on whatever infrastructure they're given — SSH to .6, -.pm, .9, .12, or .15 depending on the task. The contract defines the -**who** and **when** — not the **where**. - -## Why This Matters - -Without enforced delegation, the manager consumes the full iteration budget -(60 calls) on single-turn tasks — SSH to 5 nodes, check each VM, read logs — -leaving no capacity for actual coordination. The result: context overflow -(59K tokens in system prompt), iteration exhaustion, and degraded response -quality. This contract exists because I blew through my budget checking -Proxmox node status instead of delegating to `syslog-devops`. - -## Context Window Discipline - -**The system prompt is ~6.5K tokens (stable: ~4.5K tool schemas + ~2K other guidance).** -**Volatile (MEMORY.md + USER.md): ~300 tokens.** -**Total base: ~6,800 tokens per request.** - -The remaining budget is the conversation. Every tool call result adds to it. -If a single call returns >10K tokens (e.g., `grep` on a large file, SSH output -from multiple nodes), the context fills fast. That's why we delegate: workers -process in isolation and return compact results. - -## Trigger Conditions - -Delegation is **mandatory** when any of these apply: - -| Condition | Threshold | Example | -|-----------|-----------|---------| -| Multiple tool calls needed | 2+ calls with intermediate logic | Read file → analyze → write report | -| Large data retrieval | Output >5K tokens | `grep -r "pattern" /path` on large dirs | -| Cross-domain work | Spans 2+ worker specialties | Infra check + email filter | -| Infrastructure changes | Any mutating operation | `qm set`, `systemctl restart`, `git push` | -| Research/analysis | Needs browser or deep reading | Web research, code review, data analysis | -| Code builds or changes | Writing or modifying code | Scripts, configs, patches | -| Sequential dependencies | Worker B needs Worker A's output | Code → Review → Deliver | - -**Single tool calls stay at manager level.** Quick `grep`, `ls`, `cat`, -`curl`, `hermes tools list` — these are decision-making tools. The manager -reads them directly. - -## Worker Selection Matrix - -| Worker | Model | Toolsets | Role | Use When | -|--------|-------|----------|------|----------| -| `syslog-code` | qwen3.6-27B-code | terminal, file, web, memory, skills | Code patches, automation, scripts | Writing/modifying code, creating scripts, debugging, reading/writing files | -| `syslog-devops` | qwen3.6-27B-code | terminal, file, web, memory, skills | Infrastructure, DB, bridge, Proxmox | Server ops, SSH, Docker, Proxmox, DB queries, hardware checks | -| `syslog-email` | ornith-1.0-35b | terminal, file, web, memory, skills | Email automation, mail operations | Sending/receiving email, inbox management, SMTP operations | -| `syslog-research` | ornith-1.0-35b | terminal, file, web, memory, skills, **browser** | Analysis, classification, data processing | Web research, browser tasks, data analysis, classification, reading docs | -| `syslog-review` | ornith-1.0-35b | terminal, file, web, memory, skills | Verification, QA, audit validation | **ALWAYS** verify worker output before delivery — especially for infra changes, code builds, and research findings | -| `syslog-writer` | ornith-1.0-35b | terminal, file, web, memory, skills | Docs, content, branding, reports | Writing docs, reports, proposals, content, markdown formatting | - -### Selection Rules - -1. **Match specialty first.** A code task → `syslog-code`. An infra task → - `syslog-devops`. Don't put a `syslog-email` worker on a code review. -2. **Research tasks with browser needs → `syslog-research`.** Other workers - don't have the browser toolset. -3. **Verification → `syslog-review`.** Never deliver raw worker output. -4. **Documentation/content → `syslog-writer`.** Let them own the prose. -5. **If unsure, delegate to `syslog-research`** — it has the broadest toolset - (includes browser) and high reasoning effort. - -## Delegation Protocol - -### Step 1: Decompose - -Break the task into lanes. Each lane does ONE thing. Workers are independent — -no lane depends on another's output mid-flight. If lanes depend on each other, -dispatch sequentially. - -### Step 2: Dispatch - -Fire workers via `delegate_task`: - -**Parallel (independent lanes):** -``` -delegate_task( - tasks=[ - {"goal": "Check all 5 Proxmox nodes for VM status", "context": "SSH to each node via 192.168.68.x, run 'qm list'"}, - {"goal": "Check Docker container health on .7/.116/.17", "context": "SSH to each host, check container status"}, - ] -) -``` - -**Sequential (dependent lanes):** -Dispatch lane 1 → wait for result → dispatch lane 2. - -### Step 3: Verify - -**MANDATORY for:** -- Infrastructure changes (any `qm`, `pct`, `systemctl`, `git push`) -- Code builds and modifications -- Research findings (web data, external sources) -- Any output that will reach the user - -**Fire `syslog-review` to verify:** -``` -delegate_task( - goal="Review the output of the devops worker. Verify the node status - report is accurate, check for inconsistencies, confirm all nodes were - reachable.", - context="Worker was syslog-devops. Output is at /tmp/node-report.md. - Verify against live system." -) -``` - -**If verification fails:** -1. Send work back to original worker with review feedback -2. Re-verify -3. Max 2 re-verify cycles before escalating to Kwame - -### Step 4: Deliver - -Only verified results reach Kwame. Format per channel: -- Telegram: Use `telegram-formatting` skill -- Zulip: Use Zulip Markdown (CommonMark) -- Email: Use `syslog-email` skill - -## Kanban Board Protocol - -**File:** `~/.hermes/kanban/kanban.json` - -```json -{ - "task_id": "unique-id", - "title": "Task description", - "created": "2026-07-09T01:00:00", - "status": "backlog|in_progress|review|done", - "lanes": [ - { - "lane_id": "devops-check", - "worker": "syslog-devops", - "goal": "Check all 5 Proxmox nodes", - "status": "dispatched|completed|failed", - "output_file": "/tmp/node-report.md" - } - ] -} -``` - -**Update the board on every state change.** - -## Failure Handling - -### Worker Timeouts - -- Child timeout: **900 seconds** (15 minutes) -- Worker model `syslog-auto` is slow — it can hit the timeout limit with - 22+ API calls -- **If a worker times out:** Re-dispatch with a narrower scope. Break the - task into smaller pieces that fit in the timeout window. -- **Avoid delegating sequential SSH hops** — each SSH connection adds latency - that compounds quickly. Prefer API-based or local approaches when possible. - -### Worker Selection Failures - -- `syslog-devops` is best for infrastructure tasks (SSH, Proxmox, Docker) -- `syslog-code` is best for code-level work (reading files, writing scripts) -- `syslog-research` has the browser toolset — use for web research -- `syslog-review` is the QA gate — always fire before delivery -- **Never fire more than 3 parallel workers** (max_concurrent_children: 3) -- **Never nest delegation** (max_spawn_depth: 1) - -### Context Overflow - -- If a task requires >10K tokens of output, delegate the processing -- Workers return compact summaries, not raw data dumps -- Pass file paths and concrete goals — never dump raw data into context - -## Anti-patterns - -- ❌ Reading large files into your own context before deciding → delegate the read -- ❌ Carrying SSH/grep/output results in your context → delegate the analysis -- ❌ Doing work yourself and then "pretending" to delegate → the user can tell -- ❌ Skipping verification → raw worker output never reaches the user -- ❌ Delegating single tool calls → keep quick reads/writes at manager level -- ❌ Firing more than 3 workers in parallel → hard limit - -## Emergency Exception - -**In an emergency (server down, service must be restored immediately):** -- Delegate the diagnosis (find the problem) -- Execute the fix yourself (minimize handoff latency) -- Verify the fix after delivery -- Log the exception in the kanban board - -The emergency exception exists because the user needs the service back NOW, -not after three worker round-trips. But it's an exception — not the rule. - -## What This Contract Doesn't Cover - -1. **Worker profile configuration** — covered by `hermes-config-template.prose.md` -2. **SSH key management** — covered by existing SSH/Proxmox contracts -3. **Git workflow** — covered by `AGENTS.md` in the prose-contracts repo -4. **Cron job management** — covered by individual cron contracts -5. **Infra verification** — covered by `verify-before-mutate` protocol - -## Verification - -Run `scripts/worker-audit.py` to verify all 6 profiles are aligned: - -```bash -python3 /root/.hermes/skills/kanban-orchestrator/scripts/worker-audit.py -``` - -## References - -- `kanban-orchestrator` skill: The operational playbook (detailed execution steps) -- `worker-profile-audit.md` (skill reference): Worker configuration audit notes -- `delegation-timeout-patterns.md` (skill reference): Timeout handling patterns -- `verify-before-mutate` protocol: Infrastructure change verification -- `hermes-config-template.prose.md`: Worker profile configuration - -## Success Criteria - -This contract succeeds when: - -1. **No context overflow** — single-turn tasks don't exhaust the iteration budget -2. **Workers do the work** — manager coordinates, doesn't execute -3. **Verification before delivery** — all output passes through `syslog-review` -4. **Kanban board is current** — every task has a lane, every lane has a status -5. **User gets verified results** — raw worker output never reaches Kwame - ---- - -**Last updated:** 2026-07-09 -**Author:** Mumuni (with Kwame's input on triggers and exception criteria) -**Status:** Draft — awaiting PR review and merge to prose-contracts main