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