prose-contracts/mumuni-delegation-prose-contract.prose.md

kind, name, description, version

kind	name	description	version
pattern	mumuni-delegation	Mumuni-specific 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 (inside Abiba CT100, hwepve, .24) via Hermes agent (Pi + Hermes Zulip gateway).	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: 6 Proxmox nodes (ocupve, acerpve, minipve, amdpve, storepve, hwepve) Manager: Mumuni (inside Abiba CT100, hwepve, .24) 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.

Data Source Integrity (CRITICAL)

Workers MUST use the data provided in their task context. They MUST NOT fetch their own data from external sources unless explicitly told to.

When a task says "Read file X and format it", the worker reads file X. It does not query a separate API, run its own diagnostics, or pull data from a different system. This is the #1 source of cross-worker inconsistency: one worker gathers SSH data, another queries the Proxmox API, and the report merges two incompatible datasets.

Rule: If a worker needs additional data beyond what's in its task description, it asks the manager (via relay) — it doesn't go find it on its own.

This is a hard rule, not a recommendation. Violating it produces the exact type of discrepancy the kanban pipeline exists to prevent: a review worker finds "5 nodes present" in the raw data but "5/5 online" in the report — even though one of those nodes was unreachable. The report lied because it used data the raw data never provided.

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	strix-moe	terminal, file, web, memory, skills	Email automation, mail operations	Sending/receiving email, inbox management, SMTP operations
syslog-research	strix-moe	terminal, file, web, memory, skills, browser	Analysis, classification, data processing	Web research, browser tasks, data analysis, classification, reading docs
syslog-review	strix-moe	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	strix-moe	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:

Critical: Pass the data, not just the goal. When dispatching a worker that processes output from another worker, include the file path AND explicit instructions to use ONLY that source. Example:

delegate_task(
    goal="Format the cluster check into a clean report",
    context="Source data is at /tmp/proxmox-check-raw.md. Format ONLY the data
    in that file. Do NOT query the Proxmox API or any other data source. Use the
    file as your sole source of truth."
)

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

{
  "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
• ❌ Workers fetching their own data sources → a writer worker that queries the Proxmox API when told to "format the raw file" is fabricating data. Use the input given, not external sources

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:

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