# Orchestrator

> Coordinate complex work with Codex App worker threads. Keep the main thread as orchestrator: clarify, delegate, wait for worker completion, review outputs, iterate, verify, and ship without doing substantial implementation directly.

- **Type:** Skill
- **Install:** `agentstack add skill-minghinmatthewlam-agent-guards-orchestrator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [minghinmatthewlam](https://agentstack.voostack.com/s/minghinmatthewlam)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [minghinmatthewlam](https://github.com/minghinmatthewlam)
- **Source:** https://github.com/minghinmatthewlam/agent-guards/tree/main/skills/orchestrator

## Install

```sh
agentstack add skill-minghinmatthewlam-agent-guards-orchestrator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Orchestrator

Use this skill when the user wants the main Codex App thread to coordinate work across other Codex threads. The orchestrator owns context, decisions, integration, and final judgment. Worker threads do research, implementation slices, verification, or review.

Read `~/dev/agent-guards/AGENTS.md` before starting.

## Core Rule

The orchestrator orchestrates; it does not implement substantial work itself.

Keep the main thread focused on:

- Clarifying the goal and success criteria.
- Choosing worker tasks.
- Creating worker threads.
- Waiting for workers to finish.
- Reviewing worker outputs and evidence.
- Sending follow-ups after completion when needed.
- Integrating results, deciding next steps, and reporting to the user.

## Codex App Tools

Use `tool_search` to expose these tools when they are not already available:

- `create_thread`: start a user-owned Codex App worker thread.
- `read_thread`: inspect worker status and read completed turns.
- `send_message_to_thread`: send follow-up work, missing context, or changed decisions.
- `fork_thread`: branch completed context into a new thread when a second path should share history.
- `handoff_thread`: move a thread between local checkout and Codex worktree when isolation needs change.
- `list_threads`: find an existing worker thread before continuing it.
- `set_thread_title`, `set_thread_pinned`, `set_thread_archived`: keep orchestration threads tidy.
- `automation_update`: create a heartbeat when worker completion should be checked later without keeping the current turn open.

`create_thread` basics:

- Use a project local target by default, especially for read-only investigation, planning, review, explanation, and normal same-branch app work.
- Use a project worktree target only when isolation is useful: parallel edit-heavy workers, risky experiments, or tasks that should not touch the shared checkout.
- Include model/thinking only when the task needs an override; otherwise inherit defaults.
- After a successful creation, report the created thread id using the Codex App thread directive required by the host.
- After starting a worker, immediately establish heartbeat supervision, including for short tasks, unless the user explicitly wants the current turn to stay open.

`read_thread` is the normal inspection mechanism. Worker threads do not return results directly to the caller and should not normally message the orchestrator thread. Use it for immediate spot checks, heartbeat wakeups, final result reads, and focused follow-up review.

Use `automation_update` after worker creation. Default to a 3-minute heartbeat unless the user specifies a cadence. The heartbeat should wake the orchestrator thread, read the worker, summarize progress if still active, send a focused follow-up if the result is incomplete, and disable itself after the worker completes and the result is summarized.

Keep heartbeat messages compact. Do not paste full worker histories, full logs, or large status inventories into every wakeup. The orchestrator thread already has context; the heartbeat only needs to wake it and point at the current supervision goal. Store detail in worker threads, PR/check links, patch artifacts, or a ledger.

```text
Wake message: Continue supervising . Read the active worker thread(s), send focused follow-up if blocked or incomplete, report only meaningful changes or final completion, and stop when .
```

## Worker Prompt

Give every worker a concrete, bounded task.

```text
You are working in this thread on one delegated task.
Use /use-loop.
Goal: .
Permissions: .
Do not: .
Success criteria: .
Return in this thread: .
```

Use `/use-loop` by default in worker prompts. The worker identifies the verifiable target, checks tool/self-test access, iterates until the target is met or blocked, and writes status/blocker/final reports in its own thread. The orchestrator supervises by reading that thread.

Broad discovery tasks are allowed when the desired output is broad. Examples:

- "Read how X works in this repo and explain it."
- "Find the top-priority improvements for this app."
- "Map the release pipeline and identify weak spots."

For broad tasks, bound the return format instead of pretending the investigation is narrow: ask for a ranked list, evidence, confidence, open questions, and recommended next actions. After that worker returns, follow-ups should be specific to the missing evidence or chosen next step.

## Main Loop

1. Clarify success criteria before creating workers.
2. Split work by separable outcome, module, or evidence source.
3. Spawn workers with explicit prompts and permissions.
4. Set up heartbeat automation immediately after worker creation so the orchestrator is guaranteed to check the worker. Use direct `read_thread` polling only for immediate spot checks, final reads, or when the user explicitly wants this turn to stay open.
5. When a worker completes, read its final response and inspect claimed evidence.
6. Decide centrally:
   - accept the result,
   - send a focused follow-up to the same worker,
   - spawn another worker for an independent pass,
   - revise the plan,
   - or integrate and move to verification.
7. Repeat until the success criteria are met or a real blocker is surfaced.

Do not end after merely creating a worker unless you have also established how the orchestrator will continue supervision. The user should not need to manually check worker threads.

## Waiting Policy

Default to passive supervision. A worker that is `inProgress` may be thinking, running tools, or waiting on a command.

Use heartbeat supervision instead of keeping the current turn open for manual polling. The heartbeat is still polling with `read_thread`; it just moves the wait out of the current turn and into scheduled follow-ups.

Use direct `read_thread` polling only when you need an immediate spot check, a final result read, or the user explicitly wants live coordination in the current turn. For low-noise reads, start with the newest turn only and omit tool outputs where possible, such as `turnLimit=1` and `includeOutputs=false`. Broaden the read only when the latest turn does not contain enough context.

Do not send mid-turn status checks or steering messages by default. Steer only when:

- New user context, product decisions, or constraints arrive.
- The original prompt was wrong or missing critical context.
- The worker asks a blocking question.
- The worker explicitly reports a blocker.
- A task-specific timeout is exceeded with no new visible progress.

If the worker finishes with an incomplete answer, send a follow-up after completion. Do not interrupt an active turn just because it is quiet.

Important limitation: `read_thread` shows status, visible messages, and final outputs. It does not expose private reasoning. Treat `inProgress` as active unless there is concrete evidence otherwise.

## Review And Integration

Worker output is evidence, not an automatic final answer.

Before accepting a worker result:

- Check that every success criterion was answered.
- Separate verified facts from inference.
- Confirm claimed file edits, tests, links, or timestamps where practical.
- For broad audits or discovery, check the response shape for every finding, then spot-check the highest-impact P0/P1 claims against the cited source before presenting them as accepted.
- Fully verify any finding that will drive implementation delegation; otherwise label it as worker-reported or source-inferred.
- Resolve conflicts between workers in the orchestrator thread.
- Ask follow-ups for missing evidence instead of filling gaps silently.

When reporting worker output to the user, label the confidence level clearly:

- **Orchestrator-accepted:** spot-checked or otherwise verified enough to drive decisions.
- **Worker-reported:** plausible worker result that has not been independently checked.
- **Unverified / needs proof:** useful lead that requires follow-up, live surface proof, or implementation-specific verification.

## Gotchas

- Do not convert orchestration into main-thread implementation.
- Do not stop at "worker created." Supervision is the orchestrator's job.
- Do not over-steer active workers; wait for completion first.
- Broad initial discovery tasks are fine; broad follow-ups are the problem. After a worker responds, ask for the exact missing evidence, decision, or fix.
- Do not let worker confidence replace verification on the real affected surface.
- Do not ignore material overlap, conflicts, or duplicated work between workers; resolve those centrally when they appear.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [minghinmatthewlam](https://github.com/minghinmatthewlam)
- **Source:** [minghinmatthewlam/agent-guards](https://github.com/minghinmatthewlam/agent-guards)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-minghinmatthewlam-agent-guards-orchestrator
- Seller: https://agentstack.voostack.com/s/minghinmatthewlam
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.