skills: add execution agent dispatch protocol

2026-07-22 05:25:07 +00:00 · 2026-03-07 20:58:32 +10:00
parent dd1884e4c2
commit f0ed738453
4 changed files with 194 additions and 0 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -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.