# Orchestrate > Generic, portable orchestration router with a tiered complexity architecture. Refines the request, DISCOVERS the skills installed in the environment (and searches/installs missing ones), detects the right tier (0-3), then DELEGATES execution to subagents β€” it never executes code itself. Use when a task needs routing/decomposition across multiple steps or domains, when you want a template-driven pipeline, a planned multi-wave build, or a custom validated workflow. Triggers: "orchestrate", "route this task", "plan and build", "multi-step", "which tier", "run a workflow/template". - Skill: `qrcommunication/orchestrate` (Agent Skill, multi-file: 13 files) - Install (CLI): `npx skillmds@latest add qrcommunication/orchestrate` - Raw SKILL.md: https://api.skillmd.com/api/skills/qrcommunication/orchestrate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: QrCommunication (https://skillmd.com/u/qrcommunication) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/qrcommunication/orchestrate --- # orchestrate β€” generic tiered orchestration router This skill is **self-contained and portable**: every dependency it needs lives inside `./skills/` (bundled skills) and `./agents/` (optional helper agents). It makes **no assumption** about a specific stack, agent registry, or directory layout. Where a capability is missing in the host environment, it **discovers, searches and installs** the right skill instead of hard-coding one. ## Mandatory rules (read first) - πŸ“‹ **You are a ROUTER, not an executor.** Detect β†’ delegate. Never write code directly. - πŸ›‘ Run **STEP 0 (prompt refinement)** before anything else, except `--simple`. - πŸ›‘ Run **STEP 0.5 (skill discovery)** before delegating, so each step uses the best available (or newly installed) skill. - πŸ›‘ Detect the **tier** when no flag is given; honor an explicit flag otherwise. - πŸ›‘ **TIER_3** requires explicit human validation (AskUserQuestion) before it runs. - πŸ›‘ Never auto-add a custom workflow to the template catalog. - βœ… Delegate TIER_1/2/3 execution to an **orchestration subagent**; TIER_0 may delegate to a single subagent directly. ## Bundled dependencies (all inside this skill β€” no external install required) | Path | Role | |------|------| | `./skills/prompt-creator/` | STEP 0 β€” refine/disambiguate the raw request | | `./skills/find-skills/` | STEP 0.5 β€” **search** the skills ecosystem (`npx skills find`) | | `./skills/skill-installer/` | STEP 0.5 β€” **install/validate** a skill locally | | `./skills/meta-workflow-rl/` | TIER_1/2 β€” template engine + YAML pipeline catalog (`./skills/meta-workflow-rl/templates/`) | | `./skills/parallel-workers/` | Parallel ad-hoc decomposition (alternative executor) | | `./agents/` | Optional helper agents: `step-orchestrator`, `impact-analyzer`, `regression-guard`. Install into your agent registry to enable the full protection workflow; otherwise generic subagents stand in (see "Genericity" below). | ## Genericity β€” how this differs from a stack-specific orchestrator This version replaces every environment-specific assumption with a portable one: | Original (coupled) | Generic (this version) | |--------------------|------------------------| | Hard-coded agents (`backend-laravel`, `frontend-react`, …) | **Discovered skills** + generic subagents (`general-purpose`, `Explore`, `Plan`) | | Required custom agents `impact-analyzer` / `regression-guard` | Optional: bundled in `./agents/`, else a `general-purpose` subagent runs the same review prompt | | Absolute paths `~/.claude/skills/…` | Relative paths `./skills/…` inside this skill | | Session folder `.claude/{SESSION}/` | Workspace-relative `./.orchestrate/{SESSION}/` | | Assumes templates pre-installed | Templates bundled; missing capabilities are **searched & installed** | --- ## STEP 0 β€” Prompt refinement (bundled `prompt-creator`) Mandatory unless `--simple`. Invoke the bundled skill: ``` Skill(skill: "prompt-creator", args: "") ``` It returns: clarified **context**, a precise **task**, explicit **requirements** (constraints, edge cases), and measurable **success criteria**. The refined request replaces the raw one for every later step. ## STEP 0.5 β€” Skill discovery & install (bundled `find-skills` + `skill-installer`) Before delegating, resolve the capabilities each step needs: ``` 1. INVENTORY β€” list the skills available in the host environment (the session's available-skills list). 2. MATCH β€” for each capability the task needs (e.g. "postgres", "accessibility audit", "stripe"), is there an installed skill? 3. IF MISSING β€” SEARCH the ecosystem with the bundled find-skills skill: npx skills find "" then INSTALL the best match: npx skills add (ecosystem) or use ./skills/skill-installer/ (local validate + register) 4. RE-CHECK β€” confirm the skill is now available; record it in the plan. ``` Rules: never invent a skill name β€” only use a skill that the inventory or a successful install confirms exists. If a capability cannot be found or installed, fall back to a generic subagent (`general-purpose`) and **say so**. --- ## Tiered architecture ``` /orchestrate [task] β”‚ STEP 0 prompt-creator (skip if --simple) β”‚ STEP 0.5 skill discovery/install β”‚ FLAG / TIER DETECTION --simpleβ†’T0 --templateβ†’T1 --planβ†’T2 --customβ†’T3 elseβ†’detect β”‚ β”‚ β”‚ β”‚ β–Ό β–Ό β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ TIER_0 β”‚ β”‚ TIER_1 β”‚ β”‚ TIER_2 β”‚ β”‚ TIER_3 β”‚ β”‚ direct β”‚ β”‚ template β”‚ β”‚ planned β”‚ β”‚ custom β”‚ β”‚ subagt β”‚ β”‚ pipeline β”‚ β”‚ +master β”‚ β”‚ +human β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ### Tier detection (no flag) Score the **refined** request on: `domains_count`, `complexity (0-100)`, `ambiguity (low/med/high)`, `template_match (0-1)`. | Result | Tier | |--------|------| | 1 domain, complexity < 20, ambiguity low | **TIER_0** | | `template_match > 0.8` | **TIER_1** | | complexity 20-70, ambiguity β‰  high, no strong template | **TIER_2** | | complexity > 70 or ambiguity high | **TIER_3** | `--detect` / `-d` prints the recommended tier and metrics **without** executing. ### TIER_0 β€” simple (direct delegation) One atomic task β†’ delegate to a single subagent. No master plan, no protection. Pick the executor by discovery: a matching installed skill, else a generic subagent. ``` Task(subagent_type: "", prompt: "") ``` ### TIER_1 β€” template pipeline (bundled `meta-workflow-rl`) Run a catalog pipeline from `./skills/meta-workflow-rl/templates/`: ``` Skill(skill: "meta-workflow-rl", args: "") ``` Browse templates in that folder (feature-dev, security-audit, db-postgresql, seo-audit, deploy-production, …). Protection runs before/after (see below). ### TIER_2 β€” planned (master plan) 1. Generate a master plan (template `create-master-plan`) β†’ `./.orchestrate/{SESSION}/L0_MASTER_PLAN.md`. 2. Protection BEFORE. 3. Execute the plan wave by wave via the orchestration subagent; launch unblocked waves as their blockers complete. 4. Protection AFTER. Final report with metrics. ### TIER_3 β€” custom (human-validated) 1. Analyze deeply, generate a bespoke YAML workflow. 2. **AskUserQuestion** showing the YAML β€” require approval before running. 3. Protection BEFORE β†’ execute β†’ protection AFTER β†’ report. 4. Never auto-save to the catalog (only on explicit request). --- ## Execution & protection (portable) **Delegate, never execute.** TIER_1/2/3 go through an orchestration subagent; prefer the bundled `step-orchestrator` agent if installed, otherwise a `general-purpose` subagent given the pipeline as its brief. **Protection workflow** (TIER_1+), portable: ``` BEFORE: impact review β€” agent "impact-analyzer" if installed, else general-purpose subagent prompted to assess blast radius, dependencies, regressions. ... work ... AFTER: regression review β€” agent "regression-guard" if installed, else general-purpose subagent prompted to run/inspect tests and confirm no regressions. ``` TIER_0 skips protection. ### Pipeline YAML schema ```yaml name: "workflow-name" description: "what it does" protection: { before: impact-analyzer, after: regression-guard } # or generic skills_global: [clean-code, review-code] steps: - name: "Step" agent: skills: [skill1, skill2] task: "what to do" output: "deliverable" validation: "success criteria" rollback: "if failed" depends_on: ["Previous Step"] ``` --- ## Invocation examples ```bash /orchestrate -s "Add a phone field to the Contact model" # TIER_0 /orchestrate -t security-audit # TIER_1 (template) /orchestrate -p "Implement pagination on the /users API" # TIER_2 (plan) /orchestrate -c "Migrate REST to GraphQL" # TIER_3 (custom) /orchestrate -d "Refactor the payment module" # detect only ``` ## Success metrics βœ… Prompt refined (unless `--simple`) and the refined prompt drives every step. βœ… Skill discovery ran; missing capabilities searched & installed, or a generic fallback was used **and disclosed**. βœ… Correct tier detected (or flag honored). βœ… TIER_1+ delegated to an orchestration subagent with protection before/after. βœ… TIER_3 validated by a human before running. βœ… No direct code execution β€” everything delegated. Session folder created. ## Failure modes ❌ Skipping prompt refinement / skill discovery. ❌ Going "free style" past tier detection. ❌ Executing code instead of delegating. ❌ Inventing a skill name instead of discovering/installing it. ❌ Running TIER_3 without human approval. ❌ Auto-adding custom workflows to the catalog. ## See also - `./skills/meta-workflow-rl/` β€” template engine & catalog. - `./skills/find-skills/` + `./skills/skill-installer/` β€” discover & install. - `./skills/prompt-creator/` β€” request refinement. - `./skills/parallel-workers/` β€” alternative parallel executor. - `./agents/` β€” optional protection/orchestration agents.