richfrem/agent-plugins-skills / plugins/agent-orchestration/.apm/skills/orchestrating-agent-work
orchestrating-agent-work
VerifiedInteractive orchestrator for complex engineering work. Analyzes the task, conducts a diagnostic interview to select the appropriate execution strategy (Directed Acyclic Graph versus Loop, and which Loop type), plans the artifact, and supervises execution and verification. Use for "how should I orchestrate this", "plan this workflow", "should this be a DAG or a loop", "run these jobs in parallel", "delegate this to a worker agent", or "run/resume this graph manifest". Not for single trivial edits or skill self-improvement.
Orchestrating Agent Work (orchestrating-agent-work)
Interactive front door: analyze the task, conduct diagnostic interview, select Graph vs. Loop, plan, execute, and verify.
Contents
Dependencies
Python 3.8+ (standard library only); sibling skills cli-agent and evaluating-agent-outcomes for the learning loop.
Constraints
- Interactive Confirmation: Ask at most 3 questions (one per turn) for ambiguous dimensions; present structured choices with
Option A [Recommended]; human confirms or overrides selection before planning. - Topology First (Graph vs. Loop): Choose Graph (DAG) for distinct steps, parallel fan-out reads, or ordering barriers; choose Loop for iterative delegation.
- Trust but Verify: Never accept worker output without running automated test suites and auditing the git diff.
- Loop Isolation: Inner execution loops are strictly forbidden from running
gitwrite commands (commits and merges stay with caller). - Confinement & Redirection: Workspace mutations run in an isolated worktree; background CLI calls redirect stdin (
< /dev/null). - Outcome Completion: A worker returning is not completion; done means the assigned outcome. Review ready deliveries while independent work continues; honor a standing authorization instead of re-asking.
- Learning Loop:
scripts/work_loop.py runvalidates the contract and budget, retrieves lessons, dispatches each attempt throughcli-agent(claim first, atomic admission, immutable attempt ids), assesses withevaluating-agent-outcomes, and repairs within the attempt/token budget. Lessons, manual criteria and integration stay agent-supervised (learning-loop.md). - Human Gate Integrity: Graph runs with
--approval nonerequire an explicit human-approved manifest SHA; never self-sign manifests you wrote.
Quick Start
python3 scripts/select_strategy.py --out docs/plans/work-tasks/<task-id>/
python3 scripts/validate_manifest.py graph-manifest.json
python3 scripts/graph_runner.py graph-manifest.json --worktree .worktrees/task-<id> --approval prompt
Workflow
- Analyze: Ingest requirements, evaluate dependency structure, ordering barriers, concurrency, and risk (routing-and-closure.md).
- Interview & Select: Ask 1–3 structured questions; run
select_strategy.py; present Graph (DAG) vs Loop (Dual-Loop vs Swarm); confirm human agreement (strategy-selection.md). - Plan:
- Graph (DAG): Compile and validate
graph-manifest.json(graph-planning.md, topology-rules.md). - Dual-Loop: Author
handoffs/task_packet_<id>.mdwith atomic scope and "NO GIT" rule (strategy-dual-loop.md). - Parallel Swarm: Partition tasks into independent units; author
<id>.job.md(strategy-agent-swarm.md).
- Graph (DAG): Compile and validate
- Execute:
- Graph: Run state machine via
graph_runner.pywith worktree isolation and rollback (graph-execution.md). - Dual-Loop: Dispatch tactical coding worker into isolated worktree with stdin redirection (
< /dev/null). - Parallel Swarm: Run
swarm_run.pywith resume support.
- Graph: Run state machine via
- Verify & Close: Run test suites, audit diffs (
agent_orchestrator.py verify), and complete retrospective survey before completion.
Strategies
| Strategy | When to Choose | Plan Artifact | Reference |
|---|---|---|---|
direct | Minimal localized edit without sub-agent overhead | Implementation plan | routing-and-closure.md |
graph | Distinct dependent steps, parallel fan-out reads, join barriers, ordered mutations | graph-manifest.json | graph-planning.md, graph-execution.md |
dual-loop | One bounded task; outer supervisor orchestrates tactical inner worker | handoffs/task_packet_<id>.md | strategy-dual-loop.md |
agent-swarm | Many identical independent tasks partitioned across bulk files or items | <id>.job.md | strategy-agent-swarm.md |
Verification
python3 scripts/agent_orchestrator.py verify --packet handoffs/task_packet_<id>.md --worktree .
cat "$(git rev-parse --git-common-dir)/graph-run/<graph_id>/<run_id>/state.json"
Consult matching section in acceptance-criteria.md; on failure use fallback-tree.md.
References
- Steps: routing-and-closure.md • strategy-selection.md • graph-planning.md • graph-execution.md • delegated-dag-refactoring-playbook.md
- Strategies: strategy-dual-loop.md • strategy-agent-swarm.md • strategy-red-team-review.md • bot-delegation-patterns.md
- Contracts: topology-rules.md • graph-manifest-schema.json • PATTERN_GUIDE.md • patterns.json • cli-agent-executor.md • learning-loop.md • dispatch-preflight.md • cheapest_models.md • post_run_survey.md
- Architecture: orchestrating_agent_work_architecture.mmd • acceptance-criteria.md • fallback-tree.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |