| name | orchestrion-universal-agent-router |
| description | Universal host-neutral agent orchestration skill. Use this at the start of any non-trivial task to discover the current agent host, load the right installed skills, route ambiguous human requests through planning/TDD/debugging/review/QA/council gates, create TODOs, and prevent false completion. Designed to coordinate Superpowers, gstack, Matt Pocock skills, and llm-council-plus without assuming Claude, Codex, OpenCode, Hermes, OpenClaw, Cline, KiloCode, Antigravity, or any other specific agent.
|
Orchestrion: Universal Agent Skill Router
A host-neutral skill for agents that must coordinate many other skills without pretending every agent is the same machine.
0. Activation
Use Orchestrion whenever the human asks for any of the following:
- Build, modify, debug, refactor, review, test, document, ship, or deploy software.
- Turn vague human intent into a plan or implementation.
- Use or combine skills from Superpowers, gstack, Matt Pocock skills, or llm-council-plus.
- Work in an unfamiliar repository.
- Make a decision with architecture, security, product, data, deployment, or long-term maintenance risk.
- Continue work after another agent/session.
- Create TODOs for agent execution.
If the task is trivial, still perform a lightweight host/capability check, but do not run the full orchestration ceremony.
1. Prime directive
The human may provide vague, messy, contradictory, incomplete, emotional, or misspelled tasks.
Do not jump straight into implementation.
Route the task through the strongest available workflow:
INTAKE
→ HOST DISCOVERY
→ SKILL DISCOVERY
→ AMBIGUITY REDUCTION
→ PLAN
→ COUNCIL CHECK WHEN HIGH-RISK
→ TODO CREATION
→ ISOLATED EXECUTION
→ TDD / DEBUG / IMPLEMENT
→ REVIEW
→ QA / SECURITY / PERFORMANCE
→ VERIFICATION
→ DOCS
→ SHIP / HANDOFF / RETRO
Non-negotiable contract
1. Do not pretend a skill, MCP tool, plugin, browser, or CLI exists.
2. Do not claim a skill was loaded unless it was actually invoked, read, imported, or applied through a declared fallback.
3. Do not implement through ambiguity when clarification/planning skills are available.
4. Do not patch bugs without reproduction and root-cause evidence.
5. Do not claim completion without verification evidence.
6. Do not ship without review and QA when those skills/tools exist.
7. Do not deploy without post-deploy observation when deployment/canary tools exist.
8. TODOs are the execution spine, not decoration.
2. Host-neutral vocabulary
Different agents expose skills differently. Use these abstract operations and map them to the current host.
| Abstract operation | Meaning |
|---|
DISCOVER_HOST() | Identify current agent/runtime and available capability surfaces. |
DISCOVER_SKILLS() | Find installed skills, slash commands, MCP tools, plugins, rule files, and project docs. |
LOAD_SKILL(name) | Invoke/read/import the real skill through the host's native mechanism. |
RUN_SKILL(name, input) | Execute the skill if the host supports executable skills or slash commands. |
FALLBACK_METHOD(name) | Apply the documented method manually, clearly labeled as fallback. |
CREATE_TODO_LEDGER() | Create a living task list with states, evidence, blockers, and skill gates. |
COUNCIL_QUERY() | Use llm-council-plus through MCP, REST/API skill, CLI/web UI, or fallback prompt handoff. |
Never expose these names as fake tool calls. They are implementation-independent mental handles.
3. Host discovery
Before choosing paths, identify where you are running.
3.1 Detect host identity
Inspect what is available, in this order:
1. System/developer/runtime metadata.
2. Built-in tool names.
3. Agent-specific command palette/slash command list.
4. Environment variables.
5. Project instruction files.
6. Local skill/plugin directories.
7. Process names or CLI help output, if terminal access exists.
3.2 Known host hints
Use these as hints, not truth. Verify locally.
| Host / agent family | Common clues | Likely skill surfaces |
|---|
| Claude Code | CLAUDE.md, ~/.claude/skills, /plugin, claude mcp | Skills, slash commands, MCP |
| OpenAI Codex CLI | AGENTS.md, ~/.codex, codex CLI | Instructions, skills/plugins where supported, terminal |
| OpenCode | ~/.config/opencode, opencode CLI | Skills/config, terminal |
| Cursor | .cursor, Cursor rules, IDE agent context | Rules, commands, MCP/tool integrations |
| Cline / Roo / KiloCode style agents | VS Code extension context, MCP config, task plan UI | MCP, project rules, edit/terminal/browser tools |
| Antigravity-style IDE agents | IDE workspace context, task/run panels | Project docs, tool use, terminal/browser if exposed |
| Hermes | ~/.hermes, Hermes memory/skills, handoff/delegation patterns | Skills, memory, CLI delegation |
| OpenClaw | OpenClaw/ClawHub context, ACP/agent sessions | Native skills, spawned coding sessions |
| Gemini CLI | GEMINI.md, Gemini CLI, MCP config | Instructions, MCP, terminal |
| GitHub Copilot coding agent | GitHub issue/PR context, Copilot agent environment | Repository instructions, PR workflows |
| Pi | ~/.pi/agent/skills, ~/.pi/agent/AGENTS.md, pi CLI | Skills, extensions, MCP |
| Unknown agent | No reliable host signal | Markdown method fallback + available tools only |
If the host is unknown, proceed with the portable fallback protocol. Do not block unless the task requires unavailable tools.
4. Capability discovery
Create a capability matrix before running a serious workflow.
## Capability Matrix
- Host:
- Skill mechanism available: yes/no/unknown
- Slash commands available: yes/no/unknown
- MCP available: yes/no/unknown
- Terminal available: yes/no/unknown
- File editing available: yes/no/unknown
- Browser available: yes/no/unknown
- Git available: yes/no/unknown
- Issue tracker available: yes/no/unknown
- LLM Council Plus available: yes/no/unknown
- Existing project instructions: [AGENTS.md / CLAUDE.md / GEMINI.md / .cursor rules / other]
- Missing critical capabilities:
4.1 Generic local search commands
Use only if terminal/filesystem access exists.
for d in \
"$HOME/.claude/skills" \
"$HOME/.codex/skills" \
"$HOME/.config/opencode/skills" \
"$HOME/.cursor/skills" \
"$HOME/.hermes/skills" \
"$HOME/.gbrain/skills" \
"$HOME/.kiro/skills" \
"$HOME/.slate/skills" \
"$HOME/.factory/skills" \
"$HOME/.pi/agent/skills" \
"$HOME/.agents/skills" \
".claude" ".cursor" ".codex" ".opencode" ".hermes" ".roo" ".clinerules" ".kilocode"
do
[ -e "$d" ] && echo "FOUND $d"
done
find "$HOME" "$(pwd)" \
-maxdepth 5 \( -iname "SKILL.md" -o -iname "AGENTS.md" -o -iname "CLAUDE.md" -o -iname "GEMINI.md" -o -iname "*rules*" \) \
2>/dev/null | sort | head -200
5. Skill loading precedence
When multiple mechanisms exist, prefer the one with the strongest native semantics.
1. Native executable skill/slash command/plugin.
2. MCP tool that performs the intended action.
3. Local SKILL.md read/import.
4. Project instruction file, such as AGENTS.md, CLAUDE.md, GEMINI.md, rules files.
5. Official repo docs.
6. Manual fallback method, clearly labeled.
5.1 Missing skill rule
If a required skill is missing:
## Missing Skill Handling
- [ ] Name the missing skill.
- [ ] State which host/capability was checked.
- [ ] Search likely locations.
- [ ] If install is safe and permitted, install or print exact install steps.
- [ ] If install is not possible, use `FALLBACK_METHOD(skill-name)` and label it.
- [ ] Continue with best-effort only if correctness and safety are not compromised.
Never say "loaded X" if the agent only copied the idea of X.
6. Always-start skill gate
For non-trivial software work, first try to load:
using-superpowers
using-superpowers is the dispatcher/constitution layer. If present, obey it first.
If unavailable, apply this fallback:
## Fallback: using-superpowers
- [ ] Search for applicable skills before acting.
- [ ] Prefer process skills before implementation skills.
- [ ] If any skill has even a small chance of applying, inspect/load it before proceeding.
- [ ] Treat debugging/TDD/verification skills as rigid workflows.
- [ ] Treat product/design/planning skills as adaptable workflows.
7. Core skill families
7.1 Superpowers: discipline and workflow gates
Use as the constitutional workflow.
| Skill | Use when |
|---|
using-superpowers | Start every non-trivial task; route to skills. |
brainstorming | Human request is rough, ambiguous, product/design-heavy, or underspecified. |
using-git-worktrees | Work should be isolated before implementation. |
writing-plans | Convert accepted direction into small executable tasks. |
executing-plans | Execute a plan with checkpoints. |
dispatching-parallel-agents | Independent tasks can run in parallel without shared mutable conflict. |
subagent-driven-development | Use fresh agents per task/slice. |
test-driven-development | Build or fix via red/green/refactor. |
systematic-debugging | Bug, regression, unknown failure, flaky behavior. |
requesting-code-review | Ask for review before continuing/merging. |
receiving-code-review | Process review feedback without defensiveness. |
verification-before-completion | Before saying done. |
finishing-a-development-branch | Final branch/PR/merge/keep/discard decision. |
writing-skills | Create or improve skills. |
7.2 Matt Pocock skills: engineering clarity
Use to turn unclear work into crisp engineering artifacts.
| Skill | Use when |
|---|
setup-matt-pocock-skills | First-time repo setup. |
grill-me | Non-code or general ambiguity. |
grill-with-docs | Code/product task requiring shared context, CONTEXT.md, ADRs. |
to-prd | Convert conversation/plan to PRD. |
to-issues | Slice PRD/plan into vertical issues. |
tdd | Implement a vertical slice with tests. |
diagnose | Debug hard issues with reproduce/minimize/hypothesize/instrument/fix/regression-test. |
triage | Classify and route issues. |
zoom-out | Understand architecture/system context. |
improve-codebase-architecture | Refactor toward better boundaries/deep modules. |
prototype | Explore throwaway UI/business-logic direction. |
handoff | Compress context for another session/agent. |
caveman | Ultra-compressed token-saving mode. |
write-a-skill | Create a new skill. |
git-guardrails-claude-code | Apply git safety patterns even if host is not Claude. |
setup-pre-commit | Add quality gates. |
migrate-to-shoehorn | TypeScript assertion migration. |
scaffold-exercises | Course/exercise scaffolding. |
7.3 gstack: specialist product/engineering team
Use for role-based scrutiny and shipping.
| Skill | Use when |
|---|
/office-hours | Product idea or vague request; find real pain and wedge. |
/autoplan | Run broad plan-review pipeline. |
/plan-ceo-review | Scope, strategy, "10-star" product challenge. |
/plan-eng-review | Architecture, data flow, edge cases, test matrix. |
/plan-design-review | UI/UX plan quality. |
/plan-devex-review | CLI/API/SDK/docs/onboarding planning. |
/review | Staff-level code review. |
/investigate | Root-cause investigation before fix. |
/qa | Browser/product QA, fixes allowed. |
/qa-only | Browser/product QA report only. |
/ship | Tests, PR prep, release readiness. |
/land-and-deploy | Merge/deploy/verify production when approved. |
/canary | Post-deploy monitoring. |
/benchmark | Performance/Core Web Vitals/page-speed risk. |
/cso | OWASP/STRIDE-style security review. |
/retro | Retrospective and learning capture. |
/design-consultation | Research design direction. |
/design-shotgun | Generate several visual directions. |
/design-html | Convert approved mockup to production HTML. |
/design-review | Review implemented UX/UI. |
/devex-review | Review developer experience. |
/document-generate | Create missing docs. |
/document-release |
7.4 llm-council-plus: deliberation gate
Use for high-stakes decisions, not routine edits.
Council should be used for:
architecture decisions
security-sensitive work
irreversible migrations
large refactors
unclear product strategy
major UI direction choices
multiple plausible root causes
performance tradeoffs
API/data model design
deployment risk
when skills disagree
before high-impact shipping
Council should usually be skipped for:
typos
formatting
simple copy changes
obvious one-line fixes
routine tests
low-risk dependency bumps
Council access precedence
1. MCP tool/server if available.
2. Native skill/API wrapper if installed.
3. REST API or local web app if available.
4. CLI/script wrapper if present.
5. Human-readable council prompt prepared for manual use.
Council prompt
# Council Request
## Task
[One paragraph]
## Context
- Repo:
- Branch:
- Host agent:
- User goal:
- Constraints:
- Files:
- Existing behavior:
- Known failures:
## Options
1. Option A:
2. Option B:
3. Option C:
## Judge by
- Correctness
- Simplicity
- Maintainability
- Security
- Testability
- User impact
- Reversibility
- Implementation risk
## Required output
- Recommended option
- Why
- Rejected alternatives
- Hidden risks
- Required tests
- Stop/go decision
8. Task router
8.1 Vague or ambiguous task
using-superpowers
→ brainstorming
→ grill-me OR grill-with-docs
→ /office-hours if product-ish
→ llm-council-plus if high-impact or options conflict
TODO:
## Ambiguity TODO
- [ ] Restate the task concretely.
- [ ] Identify missing requirements.
- [ ] Identify hidden assumptions.
- [ ] Define success criteria.
- [ ] Define non-goals.
- [ ] Ask only blocking questions.
- [ ] Infer safely when blocked, and mark assumptions.
- [ ] Update CONTEXT.md/ADRs if appropriate.
8.2 New feature
using-superpowers
→ brainstorming
→ grill-with-docs
→ /office-hours
→ /autoplan
→ /plan-ceo-review
→ /plan-eng-review
→ /plan-design-review if UI/UX
→ /plan-devex-review if developer-facing
→ llm-council-plus if high-impact
→ to-prd
→ to-issues
→ using-git-worktrees
→ writing-plans
→ subagent-driven-development OR executing-plans
→ test-driven-development OR tdd
→ /review
→ requesting-code-review
→ receiving-code-review if needed
→ /qa
→ verification-before-completion
→ /document-release
→ /ship
TODO:
## Feature TODO
### Intake
- [ ] Host/capability matrix complete.
- [ ] Relevant skills loaded or fallback declared.
- [ ] User, pain, success metric, constraints defined.
### Product
- [ ] Product wedge reviewed.
- [ ] Scope mode chosen: expand / selective expand / hold / reduce.
- [ ] Non-goals documented.
### Architecture
- [ ] Current system understood.
- [ ] Data flow / state machine / failure paths documented.
- [ ] Test matrix defined.
### Council
- [ ] Council run or explicitly skipped as low-risk.
- [ ] Plan revised if council found material flaws.
### Execution
- [ ] Worktree/branch prepared.
- [ ] PRD/issues/tasks written.
- [ ] TDD loop used.
- [ ] Review and QA completed.
- [ ] Verification evidence captured.
8.3 Bug, regression, or flaky behavior
using-superpowers
→ systematic-debugging
→ diagnose
→ /investigate
→ zoom-out if architecture unclear
→ llm-council-plus if root cause disputed
→ test-driven-development OR tdd
→ /review
→ /qa OR /qa-only
→ verification-before-completion
TODO:
## Bug TODO
- [ ] Reproduce bug.
- [ ] Minimize reproduction.
- [ ] Define expected vs actual behavior.
- [ ] Trace data flow.
- [ ] Instrument if needed.
- [ ] Form hypotheses.
- [ ] Test hypotheses.
- [ ] Write failing regression test.
- [ ] Fix minimally.
- [ ] Verify test fails before fix and passes after fix.
- [ ] Re-run relevant suite.
- [ ] Capture evidence.
Hard rule:
No root cause, no fix.
No regression test, no completion.
8.4 Architecture cleanup/refactor
using-superpowers
→ zoom-out
→ improve-codebase-architecture
→ /plan-eng-review
→ llm-council-plus
→ to-prd
→ to-issues
→ using-git-worktrees
→ writing-plans
→ test-driven-development OR tdd
→ /review
→ verification-before-completion
TODO:
## Architecture TODO
- [ ] Current architecture mapped.
- [ ] Coupling/duplication/boundary issues identified.
- [ ] Refactor goal stated in behavior-preserving terms.
- [ ] Council critique obtained unless low-risk.
- [ ] Characterization tests added.
- [ ] Smallest reversible change chosen.
- [ ] No unrelated edits.
8.5 UI/UX/frontend polish
using-superpowers
→ brainstorming
→ grill-with-docs
→ /plan-design-review
→ /design-consultation if direction unclear
→ /design-shotgun if alternatives useful
→ /design-html if converting approved mockup
→ /design-review
→ /qa
→ /benchmark if performance-sensitive
TODO:
## Design TODO
- [ ] Target user and desired feeling identified.
- [ ] Existing design system inspected.
- [ ] Visual direction chosen.
- [ ] Accessibility considered.
- [ ] Before/after screenshots captured if browser available.
- [ ] UX reviewed.
- [ ] Browser QA completed.
8.6 Developer experience, APIs, SDKs, CLI, docs
using-superpowers
→ grill-with-docs
→ /plan-devex-review
→ /devex-review
→ to-prd
→ to-issues
→ tdd
→ /document-generate OR /document-release
→ /qa if browser flow exists
TODO:
## DX TODO
- [ ] Developer persona identified.
- [ ] First successful action defined.
- [ ] Setup flow tested or reason documented.
- [ ] API/CLI/docs friction listed.
- [ ] Examples verified.
- [ ] Docs updated.
8.7 Security-sensitive work
using-superpowers
→ careful / guard / freeze if available
→ git-guardrails-claude-code or equivalent
→ /cso
→ llm-council-plus
→ /review
→ verification-before-completion
Security-sensitive triggers:
auth
permissions
payments
PII
secrets
tokens
database access
file upload
admin flows
network calls
browser automation
deployment config
sandboxing
prompt injection surfaces
TODO:
## Security TODO
- [ ] Assets, actors, trust boundaries listed.
- [ ] Authn/authz checked.
- [ ] Input validation checked.
- [ ] Secrets checked.
- [ ] Injection paths checked.
- [ ] Unsafe file/network/browser paths checked.
- [ ] Council critique obtained for high-severity items.
- [ ] Exploit/regression test added where possible.
8.8 Testing/QA/browser verification
using-superpowers
→ test-driven-development OR tdd
→ /qa-only if report only
→ /qa if fixes allowed
→ /benchmark if performance-sensitive
→ verification-before-completion
TODO:
## QA TODO
- [ ] Critical flows listed.
- [ ] Expected results defined.
- [ ] Browser/devtools/logs/screenshots used if available.
- [ ] Bugs recorded by severity.
- [ ] Fixes limited to verified bugs.
- [ ] Regression tests added.
- [ ] Exact failing flow re-run.
8.9 Docs-only or docs-after-code
using-superpowers
→ grill-with-docs
→ /document-generate if missing docs
→ /document-release if code changed
→ /devex-review if onboarding docs
TODO:
## Docs TODO
- [ ] Doc type chosen: tutorial / how-to / reference / explanation.
- [ ] Code inspected before writing.
- [ ] Examples tested where possible.
- [ ] README/ARCHITECTURE/CONTRIBUTING/AGENTS-style files updated if affected.
8.10 Release/deploy/PR finalization
using-superpowers
→ finishing-a-development-branch
→ /ship
→ /land-and-deploy if approved
→ /canary
→ /retro
TODO:
## Release TODO
- [ ] Branch clean.
- [ ] Tests pass.
- [ ] Review complete.
- [ ] QA complete.
- [ ] Security/perf/doc gates complete as applicable.
- [ ] Verification evidence captured.
- [ ] PR/release notes prepared.
- [ ] Deploy only if approved.
- [ ] Canary/post-deploy checks complete.
- [ ] Retro captured if non-trivial.
9. Master TODO ledger
Maintain a living ledger. Use the host's TODO tool if available; otherwise maintain this Markdown.
# Orchestrion TODO Ledger
## Task
- Human request:
- Interpreted goal:
- Host:
- Repo:
- Branch/worktree:
- Risk level: low / medium / high / critical
## Capabilities
- Skills:
- MCP:
- Terminal:
- Browser:
- Git:
- Council:
## Assumptions
- [ ] ...
## Skill gates
- [ ] using-superpowers: loaded / fallback / unavailable
- [ ] ambiguity reducer:
- [ ] product gate:
- [ ] engineering gate:
- [ ] council gate:
- [ ] TDD/debug gate:
- [ ] review gate:
- [ ] QA gate:
- [ ] security gate:
- [ ] verification gate:
- [ ] docs gate:
- [ ] ship/handoff gate:
## Work items
| ID | State | Task | Skill/source | Evidence | Blocker |
|---|---|---|---|---|---|
| T1 | todo | | | | |
## Evidence
- Tests:
- Logs:
- Screenshots:
- URLs:
- Commits:
- PR:
- Council result:
- Review result:
State values:
todo
doing
blocked
needs-human
needs-council
needs-review
needs-qa
done
discarded
10. Bootstrap and installation appendix
Use this only when the human explicitly wants installation or when missing skills block safe work.
10.1 gstack
Generic install/detect:
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack
./setup
Target known host:
./setup --host codex
./setup --host opencode
./setup --host cursor
./setup --host factory
./setup --host slate
./setup --host kiro
./setup --host hermes
./setup --host gbrain
If OpenClaw delegates to another coding agent, install gstack in the spawned coding agent and add routing instructions to the parent agent's project instructions.
10.2 Superpowers
If native plugin marketplace exists, search for superpowers.
Known Claude-style commands:
/plugin install superpowers@claude-plugins-official
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
For other agents, prefer their plugin/extension marketplace or read/import the relevant skills/*/SKILL.md files.
10.3 Matt Pocock skills
npx skills@latest add mattpocock/skills
Then run the setup skill if available:
/setup-matt-pocock-skills
If slash commands are unavailable, read/import the installed skill Markdown files and apply them as documented methodologies.
10.4 llm-council-plus
Local app:
git clone https://github.com/jacob-bd/llm-council-plus.git
cd llm-council-plus
uv sync
cd frontend && npm install
cd ..
./start.sh
MCP mode where supported (use uv pip install -e . if pip is wrapped, or activate the project venv first):
uv pip install -e .
Claude-style MCP registration example:
claude mcp add llm-council python -m llm_council_mcp
Direct REST/API skill mode where supported:
mkdir -p ~/.claude/skills/llm-council-api
curl -o ~/.claude/skills/llm-council-api/SKILL.md \
https://raw.githubusercontent.com/jacob-bd/llm-council-plus/main/skills/llm-council-api/SKILL.md
For non-Claude hosts, adapt this as:
- make the Council API reachable,
- expose it through MCP if the host supports MCP,
- otherwise document the REST endpoints/tool wrapper in the host's project instructions.
11. Output rules
When reporting back to the human:
1. Say what was done.
2. Say which skills were actually loaded or which fallbacks were used.
3. Show the TODO ledger state.
4. Show verification evidence.
5. State remaining risks honestly.
6. Do not dump unnecessary ceremony unless useful.
Minimal completion format:
## Done
### Skills used
- ...
### Changes
- ...
### Verification
- ...
### Remaining risks
- ...
### Next action
- ...
12. Final mnemonic
Discover the room.
Load the right instruments.
Question the brief.
Plan the route.
Ask the council when the bridge is expensive.
Cut one slice.
Test the slice.
Invite review.
Walk the product in a browser.
Verify before victory.
Document the map.
Ship only with smoke cleared.
