From f0ed73845328009eeab052b7f49602e5af85f49f Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Sat, 7 Mar 2026 20:58:32 +1000 Subject: [PATCH] skills: add execution agent dispatch protocol --- MEMORY.md | 1 + memory/2026-03-07.md | 36 ++++++++ skills/execution-agent-dispatch/README.md | 53 +++++++++++ skills/execution-agent-dispatch/SKILL.md | 104 ++++++++++++++++++++++ 4 files changed, 194 insertions(+) create mode 100644 skills/execution-agent-dispatch/README.md create mode 100644 skills/execution-agent-dispatch/SKILL.md diff --git a/MEMORY.md b/MEMORY.md index 4ed9735..2e3e304 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -39,6 +39,7 @@ - Historical temporary preference once was: all subagents **primary** = `openai-codex/gpt-5.2`, **fallback** = `github-copilot/claude-opus-4.6`. - Current important exception / newer rule: **codex_worker** should use **primary** = `openai-codex/gpt-5.4`, prefer high/extra/xhigh thinking when available, and should **not auto-fallback** to another model. If its primary model is unavailable, report to Tao and let Tao decide the replacement model. - Additional long-lived execution agents initialized locally for repeat use: **docs_worker**, **qa_worker**, **ops_worker**. +- Execution-agent system still needs a standardized dispatch/handoff layer: task input template, result format, and blocker/escalation rules. ## 8) Watchdog / automation policy - Tao preference: avoid watchdog-style auto-restart automation. diff --git a/memory/2026-03-07.md b/memory/2026-03-07.md index 75e5f2d..1627b03 100644 --- a/memory/2026-03-07.md +++ b/memory/2026-03-07.md @@ -60,3 +60,39 @@ - New agent-splitting rule clarified: create multiple execution agents when work is parallelizable, responsibilities differ, contexts would otherwise get mixed, or separate validation/release tracks are needed; avoid splitting tiny or tightly coupled work. - Long-lived execution agents initialized locally: `docs_worker`, `qa_worker`, `ops_worker` (with dedicated agent dirs + workspaces + basic role files). `codex_worker` remains the default general execution worker. - This architecture is the current default, but Tao may revise it as needs change. + +## OCM / workflow / agent architecture updates (late evening) +- OCM work completed today: + - Rewrote README opening around first-run value, support positioning, and product framing. + - Refreshed README hero screenshots using newer redacted Dashboard / Agents / CLI captures. + - Adjusted README screenshot layout to use one large Dashboard hero image plus a secondary row (Agents / CLI / Actions) because mixed aspect ratios looked awkward in a single row. + - Unified OCM built-in CLI completion text to English: + - success: `✅ Done (exit 0)` + - non-zero exit: `❌ Exit code N` +- OCM GitHub flow today confirmed again that the repo is effectively PR-only even when approvals are set to 0: + - PR #5: README positioning + screenshot refresh + - PR #6: version bump to `v0.9.1` + - PR #7: English CLI completion messages + - PR #8: README screenshot layout A + - Release published: `v0.9.1` +- Tao explicitly said that for status updates, accuracy matters more than token saving; concise is fine, but not at the cost of ambiguity. +- Tao approved a multi-agent dev architecture as the default pattern: + - main = PM / architect / reviewer / user-facing coordinator + - execution agents = hands-on implementers + - use `codex_worker` as the default coding execution agent + - create more execution agents when work is parallelizable, responsibilities differ, contexts would mix, or separate validation/release tracks are needed + - avoid splitting tiny or tightly coupled work +- Tao approved a stronger delegation rule: + - unless work is truly tiny and can be completed in one short pass, main should avoid personally implementing/editing and should delegate execution to `codex_worker` first +- Long-lived execution agents initialized locally for repeat use: + - `docs_worker` + - `qa_worker` + - `ops_worker` + - `codex_worker` remains the default general execution worker +- Two workflow/architecture skills were created and published to GitHub: + - `gh-pr-release-flow` → https://github.com/dtzp555-max/gh-pr-release-flow + - `execution-agent-planner` → https://github.com/dtzp555-max/execution-agent-planner +- Tao's preferred lifecycle rule for execution agents was clarified: + - keep long-lived role-based agents for reuse + - delete or archive project-specific temporary agents after the project ends to avoid an “agent graveyard” +- Next improvement approved: add a standardized execution-agent dispatch / handoff protocol so workers receive clearer task packets and report blockers/results consistently. diff --git a/skills/execution-agent-dispatch/README.md b/skills/execution-agent-dispatch/README.md new file mode 100644 index 0000000..38819b5 --- /dev/null +++ b/skills/execution-agent-dispatch/README.md @@ -0,0 +1,53 @@ +# execution-agent-dispatch + +A lightweight skill for turning PM decisions into clear worker handoffs. + +## Why this exists + +It is not enough to have execution agents. +They also need a consistent way to receive work and report results. + +Without that, the system drifts into familiar failure modes: +- vague delegation +- role boundary drift +- workers doing too much or too little +- silent blocking +- messy result reporting + +This skill exists to standardize the handoff layer between **main** and execution agents. + +## What it standardizes + +- the task packet main sends to a worker +- the result format a worker returns +- when a worker must escalate instead of staying silent +- milestone / ETA discipline for delegated work + +## Core idea + +A good worker handoff should answer: +1. What exactly should be done? +2. What is out of bounds? +3. What does success look like? +4. When should the worker report back? +5. What should trigger escalation? + +## Recommended task packet + +- Task +- Scope +- Deliverable +- Constraints +- Milestone 1 + ETA + +## Recommended result packet + +- `status:` ok | blocked | failed +- `changed:` ... +- `notes:` ... +- `next:` ... + +## Notes + +This is a dispatch / coordination skill, not an implementation skill. +It works best after `execution-agent-planner` has already decided which workers should exist and what they should own. diff --git a/skills/execution-agent-dispatch/SKILL.md b/skills/execution-agent-dispatch/SKILL.md new file mode 100644 index 0000000..6bcc470 --- /dev/null +++ b/skills/execution-agent-dispatch/SKILL.md @@ -0,0 +1,104 @@ +--- +name: execution-agent-dispatch +description: Standardize how main dispatches work to execution agents and how execution agents report back. Use when main has already decided which execution agent(s) should do the work and needs a clear handoff packet, result format, blocker/escalation rules, and milestone discipline so workers do not drift or go silent. +--- + +# Execution agent dispatch + +Use this skill after execution architecture is decided. + +## Goal + +Turn vague delegation into a clear handoff. +Every dispatched task should make it obvious: +- what to do +- what not to do +- what counts as done +- when to escalate back to main + +## Dispatch packet + +When main assigns work to an execution agent, include these sections: + +### 1) Task +One short statement of the goal. + +### 2) Scope +Specify: +- repo / path / files if known +- what area is in bounds +- what is explicitly out of bounds + +### 3) Deliverable +Define the expected output: +- code change +- docs update +- validation report +- PR / commit / test result +- recommendation only + +### 4) Constraints +List non-negotiables, such as: +- do not change unrelated files +- do not switch models automatically +- do not message users directly +- ask before destructive actions + +### 5) Milestone 1 + ETA +Tell the worker what first checkpoint matters and when main expects the first update. + +## Worker response format + +Execution agents should respond compactly with: +- `status:` ok | blocked | failed +- `changed:` files changed/created, commands run, or "none" +- `notes:` short summary +- `next:` next action or handoff need + +## Escalate immediately when + +A worker should report back to main instead of silently stalling when: +- permissions are missing +- the model/tooling is unavailable +- repo rules block the intended action +- requirements are contradictory or underspecified +- the task is crossing role boundaries +- the ETA has clearly slipped +- the requested change is riskier or broader than the original handoff suggested + +## Silence rule + +Workers should not chatter, but should also not disappear. + +Default rule: +- acknowledge briefly +- do the work +- report at milestone +- report immediately on blockers + +## Completion rule + +A task is not complete just because files changed. +Completion should include: +- the requested deliverable exists +- basic verification happened when relevant +- blockers or caveats are disclosed +- main has enough information to review and report upward + +## Main's responsibility + +Main must not delegate sloppily. +Before dispatching, main should decide: +- why this worker is the right worker +- what the boundary is +- what review criteria will be used +- whether the task is small enough that delegation is unnecessary + +## Good default tone + +- short +- operational +- explicit +- non-dramatic + +Prefer a clean task packet over a long motivational speech.