---
name: bartsoj/ORCHESTRATOR_CREATOR.md
source: https://app.decimal.ai/s/bartsoj-orchestrator-creator-md@1/SKILL.md
source_sha256: b72f1f7ef38a
---

# Task: Design and Create an Orchestration Agent

## Objective

Given a set of skills and a workflow describing how they connect, produce an orchestration agent as a single flat markdown file — `agents/{agent-name}.md` — that can autonomously execute the workflow end-to-end by authoring dynamic workflows that spawn a subagent per skill, reading their output files, making decisions, and managing feedback loops. The agent never does the skill's job. It invokes, inspects, decides, and proceeds.

---

## Inputs

1. **Skills** (required) — the set of skills the agent will invoke. Each skill must produce a named output file and be non-interactive (no pausing for input, ambiguities go into Open Questions). If skills require human interaction during execution, they are not compatible with orchestration — fix them first.
2. **Workflow** (required) — a defined sequence or graph showing which skills run in what order, what feeds into what, and where feedback loops exist. Can be a diagram, a list, or prose.
3. **Decision criteria** (optional) — for each skill output, what constitutes success, failure, and what triggers a feedback loop. If not provided, design these based on the skill outputs (look for verdicts, issue counts, Open Questions patterns).
4. **Project context** (optional) — architecture docs, conventions, or constraints that inform how the agent should operate.

---

## Workflow

Agent creation follows four phases: map, design, write, and validate.

### Phase 1: Map the Workflow

Analyze the skills and workflow to build a complete picture. For each skill, identify:

| Property | Question to answer |
|---|---|
| **Inputs** | What files does this skill read? User-provided or from earlier skills? |
| **Output** | What file does it produce? Exact filename? |
| **Dependencies** | Which skills must complete first? |
| **Parallelism** | Can multiple instances run concurrently? Under what conditions? |
| **Success criteria** | How do you know the output is good? Verdicts, section checks, test results? |
| **Failure modes** | What goes wrong? What does bad output look like? |
| **Feedback target** | If problems surface, which earlier skill gets re-run? |

Draw the workflow as a directed graph (ASCII art). Mark feedback loops explicitly. This becomes the skeleton of the agent's decision logic.

**Example:**
```
ANALYZE.md → DESIGN.md → BUILD.md → TEST.md → DEPLOY.md
                 ^            ^
                 |            |
              TEST.md      TEST.md
             (design       (build
              flaws)        bugs)
```

Divide the workflow into phases:
- **Parallel phases** — multiple independent invocations inspected together. One `parallel()` workflow (a barrier over an array of `() => agent(...)` thunks). Common pattern: generating the same document type for multiple independent items.
- **Sequential phases** — a step whose output the orchestrator inspects before the next runs. Its own single-agent workflow; the orchestrator reads the file and decides before authoring the next.

Rules of thumb:
- Two invocations reading/writing different files with no overlap → parallel is safe.
- A skill reads another skill's output → sequential is required.
- Multiple invocations modify the same codebase → sequential (one agent writes code at a time).

### Phase 2: Design Decisions

Before writing, make four key design decisions:

**1. File organization.** Design a directory structure for all output:
- Isolate each work item in its own subdirectory
- Use predictable paths: `{output_dir}/{item_id}/{SKILL_OUTPUT.md}`
- Separate orchestration artifacts from application code

```
{output_dir}/
  {phase_1_output}.md                    # Top-level outputs
  {item_id}/
    {skill_1_output}.md                  # Per-item outputs
    {skill_2_output}.md
    BLOCKED.md                           # Created if item hits retry limit
  {item_id}/
    ...
```

**2. Decision tree.** For every skill output, write a decision table:

```
After SKILL_X produces OUTPUT_X.md:
  1. Read OUTPUT_X.md
  2. Check: file exists and is non-empty?
     - No → retry once, then mark failed
  3. Check: Open Questions with unresolved items?
     - Yes → resolve by editing, then proceed or re-run
  4. Check: skill-specific success criteria?
     - Success → proceed to SKILL_Y
     - Failure type A → go back to SKILL_W with context
     - Failure type B → go back to SKILL_V with context
```

Be explicit about what success looks like (a verdict, an empty issues section, all tests passing), what failure looks like, and where to route each failure type.

**3. Feedback loop bounds.** Every feedback loop needs a limit:
- Maximum attempts per skill per item — recommended: 3
- What context to carry backward (failure information from the later skill)
- Escalation path when blocked (skip and continue, stop workflow, or aggregate for human review)

**4. Prompt patterns.** Design the prompt template for each skill invocation. Every prompt needs three things:

```
/{SKILL_NAME}.md {Input references — file paths to read} {Additional context — feedback from previous phases, constraints} Write the output to {output_path}.
```

Keep prompts focused. Reference file paths rather than embedding content — the skill agent has filesystem access. Embed inline only when content is short (<50 lines), is feedback that doesn't exist as a file, or is a specific excerpt from a larger file.

For feedback loops, include failure context inline using XML tags on the same line:
```
/{SKILL_NAME}.md The previous implementation was reviewed and these issues were found: <issues>{paste from the review output}</issues> Read the plan from {path}. Fix the issues and write to {output_path}.
```

### Phase 3: Write the Agent

Create a single flat file at `agents/{agent-name}.md` with YAML frontmatter and system prompt. Agents are single markdown files directly in the `agents/` directory — the filename (minus `.md`) becomes the agent name. There is no subdirectory and no separate `references/` folder. All reference material (the dynamic-workflow invocation patterns) must be inlined directly in the agent's body.

Read `references/dynamic-workflows.md` from this skill's directory — it contains the invocation patterns to inline into the agent.

**Frontmatter:**

```yaml
---
name: {agent-name}
description: {Action phrase}. Use when asked to "{trigger 1}", "{trigger 2}", "{trigger 3}".
model: opus
---
```

- `name` — lowercase, hyphenated identifier. Must match the filename: `agents/{name}.md`
- `description` — action verb + 3-5 trigger phrases. This is how the plugin matches user intent.
- `model` — `opus` for orchestration agents (strong reasoning for decisions); use `opus[1m]` when the orchestrator juggles many artifacts.

**System prompt structure:**

The body follows this structure. Every section is important — omitting one produces an incomplete agent.

```markdown
# {Agent Name} — Autonomous Skill Execution Agent

{One paragraph: who this agent is, what it does, what it never does.}

---

## Workflow Overview

{ASCII diagram of the full workflow with feedback loops.}

---

## File Organization

{Directory structure. Exact paths.}

---

## How to Invoke Skills

{Dynamic-workflow patterns — inlined from `references/dynamic-workflows.md`:
 the `meta` block, `agent()` for one skill, `parallel()`/`pipeline()` for fan-out
 (with `pipeline()`'s gated-use caveat), single-workflow patterns for mechanical
 stretches (loop-until-pass, fan-out-then-verify), regeneration/resume, and
 failure handling.}

---

## Phase N: {Phase Name}

{For each phase:
 - Goal (one line)
 - Exact `agent()` / `parallel()` / `pipeline()` call
 - Output inspection (what to check, what success/failure looks like)
 - Decision logic (proceed, retry, go back)
 - Open question resolution}

---

## Feedback Loop Rules

{When to go back to which phase. How to include context.
 Retry limits. What happens when blocked.}

---

## Open Question Resolution

{Universal process for resolving open questions.}

---

## Output Inspection Checklist

{Universal checks plus per-skill checks.}

---

## Error Handling

{Process failures, missing output, infinite loop detection.}

---

## Complete Execution Flow

{Full algorithm as pseudocode — the definitive reference.}

---

## What You Never Do

{Hard constraints the orchestrator must never violate.}
```

**Include these universal patterns in every agent:**

Workflow invocation (one skill):
```javascript
export const meta = { name: '<step>', description: '<what it does>' }
await agent(`/SKILL_NAME.md Read <inputs>. Write the output to <output_path>.`)
```
- The prompt names the skill and instructs the subagent to invoke it via its `Skill` tool — begin with `/SKILL_NAME.md ` and keep the instructions on the same line; use the plugin-qualified id if a bare name doesn't resolve.
- Always specify input and output file paths in the prompt.
- Never route on the return value — read the output file.
- In the agent's phase sections, show the bare `agent()`/`parallel()`/`pipeline()` calls and add one sentence telling the reader to wrap each in a `Workflow` script that begins with a `meta` block (as above).

Fan-out (parallel siblings): wrap the per-item `() => agent(...)` thunks in one `parallel()` — a barrier that returns results with failures as `null` (`.filter(Boolean)`). Use `pipeline()` only for a gate-free multi-stage stretch. Pass every item; the runtime caps concurrency at `min(16, cores−2)`.

Mechanical stretches (loop-until-pass, fan-out-then-verify): when a stretch has a mechanical pass/fail check — a lint/test-fix loop, or fanning out then adversarially verifying each finding — codify it inside a single workflow instead of an orchestrator turn. Reserve this for success criteria checkable without the orchestrator's judgment; anything needing the orchestrator to read and decide stays its own workflow.

Output inspection (after every workflow):
1. File exists? No → re-author that `agent()` once
2. File non-empty? No → re-author once
3. Open Questions present? Yes → resolve by editing
4. Placeholder language? Grep for "appropriate", "relevant", "as needed", "TBD", "TODO", "etc." Found → re-run
5. Skill-specific checks (verdict, sections, test results)

Open question resolution:
1. Read each question's options and recommendation
2. Decide using project context and the recommendation
3. Edit the file: write decision into relevant section, mark resolved
4. All resolved → "All questions resolved."
5. Genuinely unresolvable → leave, note in final report, use recommendation provisionally

Retry limits:
- Maximum 3 attempts per skill per item
- After 3 → create `BLOCKED.md`, skip to next item
- Track attempts per phase, not globally

Regeneration and resume:
- Feedback by regeneration is a fresh `agent()` with corrected context pointed at the same output path — subagents are always fresh.
- To resume an interrupted workflow, relaunch it: finished agents return cached results; only the rest re-run.

Error handling:

| Error | Action |
|---|---|
| `agent()` returns `null` / artifact missing | Retries were exhausted. Re-author that single `agent()` in a fresh workflow with sharper context. Context too long → summarize inputs / reduce read set. |
| Output file at wrong path | Glob for `*.md` nearby. Found elsewhere → move. Not found → re-author with explicit path. |
| Infinite loop (3 cycles same two phases) | Create `BLOCKED.md`, move on. |

### Phase 4: Validate

Verify the agent file is at the correct location:

```
agents/
  {agent-name}.md               # Single flat file, no subdirectory
```

Verify that the dynamic-workflow invocation patterns are fully inlined in the "How to Invoke Skills" section — the agent must be self-contained with no external reference dependencies.

Then validate the agent against the quality checklist.

**Testing recommendations** (not mandatory, but strongly recommended):
1. **Dry run with one item.** Full workflow, single simple item. Verify files get created at expected paths.
2. **Test the feedback loop.** Bad input → verify correct routing to earlier phase with context.
3. **Test the retry limit.** Persistent failure → verify `BLOCKED.md` after 3 attempts.
4. **Test parallel execution.** At least 3 concurrent items. Verify no file collisions.
5. **Test open question resolution.** Input that generates questions → verify resolution editing.

---

## Output Format

The skill produces a single flat file at `agents/{agent-name}.md`. The filename (minus `.md`) is the agent name. No subdirectory, no separate reference files — everything is inlined.

```markdown
---
name: {agent-name}
description: {Action phrase}. Use when asked to "{trigger 1}", "{trigger 2}", "{trigger 3}".
model: opus
---

# {Agent Name} — Autonomous Skill Execution Agent

{Identity paragraph: who, what it does, what it never does.}

---

## Workflow Overview

{ASCII workflow diagram with feedback loops}

---

## File Organization

{Directory structure with exact paths}

---

## How to Invoke Skills

{Dynamic-workflow patterns — inlined from `references/dynamic-workflows.md`:
 the `meta` block, `agent()` for one skill, `parallel()`/`pipeline()` for fan-out
 (with `pipeline()`'s gated-use caveat), single-workflow patterns for mechanical
 stretches (loop-until-pass, fan-out-then-verify), regeneration/resume, and
 failure handling.}

---

## Phase 1: {Name}

{Goal, invocation, inspection, decision logic}

(Repeat for each phase.)

---

## Feedback Loop Rules

{Triggers, targets, context to carry, retry limits, blocked behavior}

---

## Open Question Resolution

{Universal resolution process}

---

## Output Inspection Checklist

{Universal checks + per-skill checks}

---

## Error Handling

{Process failures, missing output, infinite loops}

---

## Complete Execution Flow

{Full pseudocode algorithm}

---

## What You Never Do

{Hard constraints}
```

---

## Scope

### In scope

- Designing and writing a complete orchestration agent as a single flat file (`agents/{name}.md`)
- Mapping workflows into phases with parallel/sequential classification
- Designing decision trees, feedback loops, and retry bounds
- Defining file organization for orchestration output
- Inlining the dynamic-workflow invocation patterns from `references/dynamic-workflows.md` into the agent
- Including all universal patterns (output inspection, open question resolution, error handling)

### Out of scope

- Creating the skills the agent will invoke — use the skill-creator skill (`/SKILL_CREATOR.md`) for that
- Running or testing the created agent — that is a separate step after creation
- Writing application code or business logic
- Modifying existing agents — edit them directly

---

## Quality Checklist

Before the agent is ready, verify:

- [ ] Agent is a single flat file at `agents/{name}.md` — no subdirectory, no separate reference files
- [ ] Filename (minus `.md`) matches the `name` field in frontmatter
- [ ] Frontmatter has `name`, `description` (action verb + 3-5 triggers) and `model`
- [ ] Identity paragraph states what the agent does and what it never does
- [ ] Workflow overview has an ASCII diagram showing all phases and feedback loops
- [ ] File organization specifies exact paths for every output file
- [ ] Every skill in the workflow has a corresponding phase section
- [ ] Every phase section has the exact invocation call (`agent()` / `parallel()` / `pipeline()`)
- [ ] Every phase section has output inspection criteria specific to that skill
- [ ] Every feedback loop has a defined trigger, target phase, and context to carry
- [ ] Retry limits are defined (recommended: 3) and blocked-item behavior is specified
- [ ] Complete execution flow covers every branch including retries and blocked items
- [ ] The dynamic-workflow invocation patterns are fully inlined in the agent (not in separate reference files)
- [ ] Open question resolution process is defined
- [ ] Error handling covers: agent failure (`null`/missing artifact), wrong output path, infinite loops
- [ ] "What You Never Do" prevents the orchestrator from doing skill work itself
- [ ] No placeholders, TODOs, or vague language