Skip to content

richfrem/agent-plugins-skills / plugins/agent-orchestration/.apm/skills/orchestrating-agent-work

orchestrating-agent-work

Verified

Interactive 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 git write 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 run validates the contract and budget, retrieves lessons, dispatches each attempt through cli-agent (claim first, atomic admission, immutable attempt ids), assesses with evaluating-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 none require 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

  1. Analyze: Ingest requirements, evaluate dependency structure, ordering barriers, concurrency, and risk (routing-and-closure.md).
  2. 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).
  3. Plan:
  4. Execute:
    • Graph: Run state machine via graph_runner.py with 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.py with resume support.
  5. Verify & Close: Run test suites, audit diffs (agent_orchestrator.py verify), and complete retrospective survey before completion.

Strategies

StrategyWhen to ChoosePlan ArtifactReference
directMinimal localized edit without sub-agent overheadImplementation planrouting-and-closure.md
graphDistinct dependent steps, parallel fan-out reads, join barriers, ordered mutationsgraph-manifest.jsongraph-planning.md, graph-execution.md
dual-loopOne bounded task; outer supervisor orchestrates tactical inner workerhandoffs/task_packet_<id>.mdstrategy-dual-loop.md
agent-swarmMany identical independent tasks partitioned across bulk files or items<id>.job.mdstrategy-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

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: 469kUpdated Claude CodeCodexVerifiedInstall
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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 321kUpdated Claude CodeCodexVerifiedInstall