Help us improve
Share bugs, ideas, or general feedback.
From obsidian-mcp-server
Orchestrates multi-phase workflows chaining foundational task skills (git-wrapup, release-and-publish, maintenance, etc.) for MCP server projects. Routes user intent to workflow files for greenfield builds, maintenance, or fix-and-release.
npx claudepluginhub cyanheads/cyanheads --plugin obsidian-mcp-serverHow this skill is triggered — by the user, by Claude, or both
Slash command
/obsidian-mcp-server:orchestrationsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Multi-phase work that chains several foundational skills against one or more MCP server projects. Typical triggers:
Orchestrates multi-phase workflows chaining foundational task skills (git-wrapup, release-and-publish, maintenance, etc.) for MCP server projects. Routes user intent to workflow files for greenfield builds, maintenance, or fix-and-release.
Orchestrates multi-agent work at scale: research swarms, parallel feature builds, wave-based dispatch, and build-review-fix pipelines for tasks requiring 3+ agents.
Decomposes and executes large changes, migrations, or multi-issue fixes in parallel with quality gates. Automates work package breakdown and orchestration.
Share bugs, ideas, or general feedback.
Multi-phase work that chains several foundational skills against one or more MCP server projects. Typical triggers:
workflows/greenfield-build.mdworkflows/maintenance-release.mdworkflows/field-test-fix.mdworkflows/fix-wrapup-release.mdSingle-skill work — running just maintenance, just git-wrapup, just release-and-publish — invokes the foundational skill directly. Use this orchestrations skill when at least two phases need to chain.
| Tier | Layer | Examples | Who reads it |
|---|---|---|---|
| 1 | Foundational task skills | git-wrapup, release-and-publish, maintenance, field-test, setup, design-mcp-server, polish-docs-meta, code-simplifier, add-tool, add-resource, add-service, add-test, etc. | Orchestrator AND sub-agents (by direct path reference) |
| 2 | Orchestration workflows | The four files under workflows/ | Orchestrator only |
| 3 | Router | This SKILL.md | Orchestrator only |
Workflows in Tier 2 sequence Tier 1 skills with gates and verification. They never duplicate Tier 1 content — they direct to it. A workflow file says "Phase N: agent reads and runs skills/git-wrapup/SKILL.md," not "here's how to wrap up a release."
The orchestrator is the agent driving the workflow — the one reading this SKILL.md. Sub-agents the orchestrator spawns receive prompts pointing at Tier 1 skills directly; they do not receive this skill or the workflow file. That boundary prevents recursive sub-agent spawning.
Identify the workflow from user intent first, then sanity-check against project state if intent is ambiguous.
| User intent / state signal | Workflow |
|---|---|
New scaffold(s) from bunx @cyanheads/mcp-ts-core init, no implementation yet (echo definitions still present, no released changelog) | workflows/greenfield-build.md |
Existing server(s), bun outdated shows updates, want to land them and ship | workflows/maintenance-release.md |
| Existing server(s), want to find bugs via live testing and fix them, optionally ship | workflows/field-test-fix.md |
| Existing server(s) with known issues (GH issues, handoff document, observed gap), want to fix and ship | workflows/fix-wrapup-release.md |
If intent is ambiguous (no clear signal), surface the candidate workflows to the user and confirm. Don't pick silently.
A workflow file is the orchestrator's playbook for one run. Read it end-to-end before kicking off the first phase.
These apply to every workflow. Workflow files don't restate them; the orchestrator carries them forward and restates them in sub-agent prompts where applicable.
git stash, no git reset --hard, no git restore ., no git clean -f, no git checkout -- .. These bypass safety and risk silent data loss. Read-only git (status, diff, log, show, blame) is always safe.--no-verify, no --no-gpg-sign, no bypassing commit hooks. If a hook fails, investigate the underlying issue.bun run devcheck is the handoff gate between phases. Work phases must hand back a green devcheck. If a phase can't reach green, halt and report the failing step verbatim rather than carrying broken state forward.gh release create --notes-from-tag is incompatible with --repo. Always cd into the target repo directory for gh release commands.git tag -a), never lightweight. Tag annotation subject omits the version number — GitHub prepends v<VERSION>: to release titles when using --notes-from-tag, so including the version in the subject creates stutter.feat|fix|refactor|chore|docs|test|build(scope): message). One logical concern per commit. The release commit (version bump + changelog + regenerated artifacts) lands on top of a stack of feature/fix commits, never collapsed alongside them.The orchestrator owns the goals. Workflow phases are not "run skill X" — they are "achieve goal Y, using skill X as the path." Sub-agents (when used) are instruments for hitting the goals, not the work itself. The same posture applies in linear mode — the orchestrator runs the phase directly, but the goal is still the contract.
Before running a phase (or spawning a sub-agent for it), write down four things:
bun run devcheck green; npm view <pkg>@0.5.2 resolves." Not fuzzy: "ran the release-and-publish skill."gh issue view N --comments (the comment thread) and the timeline cross-reference query in the Orient block (what references the issue, including cross-repo) — the body alone misses both. The orchestrator reads these sources too (to construct the prompt), but that's prompt construction, not a substitute for the sub-agent reading them.Why the framing matters:
Inform without inlining. An enhanced sub-agent prompt names the specific primary sources and the goal — it does NOT paraphrase them. "Review GH issue #123 (read it via gh issue view 123 --comments); the goal is X; verify with Y" is the right shape. Pasting the issue body into the prompt forces the sub-agent to work from a paraphrase. Let the sub-agent read the source and explore for additional context as needed.
Sub-agents are optional. Match the mechanism to your platform's capability — three tiers, in increasing order:
Phases, gates, goals, and constraints are identical across all three tiers — only the fanout mechanism changes. Use the most capable tier available, and don't hand-roll what the platform does natively (e.g., rolling concurrency). Choose by scope and capability, not by default.
Model tier ≠ orchestration tier. A higher orchestration tier is not automatically the right choice. On some platforms, programmatically-orchestrated or nested sub-agents (an agent spawning agents) silently run on a cheaper/downgraded model, while the strongest model is reachable only by sub-agents the main loop spawns directly (tier 2). When a phase needs the top model (heavy generation, design, framework adoption), prefer direct main-loop fanout even when a more "capable" orchestration primitive exists — the primitive can cost you the model. Verify the model your platform actually assigned via its UI/telemetry; never infer it from a sub-agent's transcript, which interleaves auxiliary calls (titles, summaries) on cheaper models and will mislead you.
The decision tree below is orthogonal to tier — it governs whether a given phase fans out, by target count and conflict risk:
| Situation | Strategy |
|---|---|
| Single target, small change | Linear, orchestrator runs the phases itself |
| Single target, large change likely to exhaust orchestrator context | Sub-agent per phase; orchestrator gates between phases |
| N > 1 targets, independent work per target | One sub-agent per target per phase (parallel fanout) |
| N > 1 targets, work that conflicts across targets (e.g., all editing the same file) | Linear or serial — the parallel model assumes target independence |
| Sub-agents not available | Linear, regardless of N — same phases, just sequential |
Every sub-agent prompt opens with this block. Sub-agents do not inherit the orchestrator's CLAUDE.md/AGENTS.md chain or skill registry — both must be reconstructed in the prompt. Substitute the bracketed values per target.
You are working on `[project name]` at `[project absolute path]`.
Orient first. These steps are required before any task work — do them in
order. If any file does not exist, note it and continue.
1. Read the global agent protocol at `~/.claude/CLAUDE.md` (or your agent's equivalent — `~/.codex/AGENTS.md`, etc.).
2. Read the workspace-level protocol if one exists at `[workspace agent protocol path]`
— skip this step if no workspace-tier protocol applies.
3. Read the project protocol at `[project absolute path]/CLAUDE.md` (or `AGENTS.md`, whichever the project keeps).
4. Run `cd [project absolute path] && bun run list-skills` to see the project's
available skills with descriptions and locations.
5. Read the skill file(s) for this task: `[Tier 1 skill paths]`.
6. Read the primary sources for this task directly — design docs (`docs/design.md`),
GH issues, handoff documents, reference/gold-standard files. For a GH issue, read
both the comment thread and its cross-references — the body alone misses both:
- `gh issue view <N> --comments` — description + comment thread
- `gh api 'repos/{owner}/{repo}/issues/<N>/timeline' --paginate --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'` — issues/PRs that reference this one, including from other repos
List each source explicitly: `[primary source paths and gh commands]`. Skip this
step only if no primary source applies (rare).
Only after that, begin the task below.
**Goal:** [the verifiable end state this phase must produce — concrete, testable]
**Path:** [Tier 1 skill(s) and steps the sub-agent should follow]
**Constraints:** [no-go list — restate git/commit rules and other invariants verbatim]
**Expected outputs:** [report shape you want back — e.g., "Step 8 numbered summary", "list of files touched with one-line rationale per fix"]
The sub-agent reads the primary sources directly during orient (step 6) — do not paste their contents into the prompt. The orchestrator names them; the sub-agent reads them.
Bash git only in parallel sub-agents. Do not let parallel sub-agents call mcp__git-mcp-server__* tools — session state (set_working_dir) leaks across parallel calls in the same orchestrator session, causing silent no-ops, wrong-directory operations, and false "tag already exists" errors. Bash git in the agent's CWD is reliable. The orchestrator may still use git-mcp-server itself in serial.
Sub-agents do not receive this orchestrations skill or workflow files. Their prompts include Tier 1 skill paths only. This prevents recursive sub-agent spawning — if a sub-agent decides it needs to fan out work, that's a signal the orchestrator sliced the work too wide. Re-slice; don't let the sub-agent recurse.
Sub-agent prompts must restate the no-git-write and no-stash rules verbatim. The orchestrator's CLAUDE.md/AGENTS.md rules aren't visible to sub-agents at prompt time.
Narrow scope per fanout. A sub-agent doing "implement everything, write tests, run devcheck, polish, commit, tag" will exhaust its context window before finishing — the work lands on disk but the agent can't continue. Split phases so each sub-agent finishes well under the context limit. Plan a follow-up "finish" phase as a normal backstop, not a fallback for failure.
For N targets in a phase:
Barriers only where gates sit. Step 4's "advance to the next phase" implies a barrier — collect every target's phase-N result before any target starts phase N+1. That barrier is only required when a gate sits between the phases: a human decision (authorization, version-bump intent) or cross-target synthesis (the roll-up). Where no gate intervenes, a target may flow through consecutive phases independently — tier-3 platforms pipeline this for wall-clock, and even hand-spawned runs can let one sub-agent carry a target across adjacent gate-free phases. Keep the barrier at gate boundaries; drop it elsewhere. Each workflow's phases table encodes this directly: the Gate after column marks every boundary as barrier (with a terse reason) or gate-free so the spawn/round structure is derivable without re-derivation.
Editing phases and wrap-up phases never go in the same sub-agent. Editing sub-agents make file changes and run devcheck — they do not commit, tag, or push. Wrap-up sub-agents read the working tree, commit, tag, and (when releasing) push and publish — they do not edit source. This separation lets the orchestrator review diffs before they become permanent and keeps the commit graph clean.
Independent sub-agents diverge on incidental choices — scoped vs. unscoped package names, script invocation form, README hero structure, badge ordering. When choices should be uniform across targets, plan an explicit normalization step after the fanout — don't expect alignment for free.
For small N or small diffs, the orchestrator normalizes directly. For large N or non-trivial fixes, spawn a narrow-scope fanout with an explicit rule list.
If your platform manages sub-agent concurrency automatically (tier 3), rely on it rather than hand-rolling the below. Otherwise: rate limits on parallel sub-agent spawning are intermittent — sometimes 15 concurrent agents work fine, sometimes 3 get throttled. Don't hard-cap; use rolling concurrency. Launch an initial batch, then as each agent completes, kick off the next in line. If a wave gets rate-limited, shrink the window for the next wave.
When N targets share a phase, never name other targets in a sub-agent's prompt — even as examples. Sub-agents pattern-match on everything in their prompt, and cross-project names leak into commits, messages, and variable names. Each sub-agent's prompt references its own target only.
Verification runs against the goal you defined for the phase — not against the sub-agent's self-report. A sub-agent that reports "done" without producing the goal state is not done. The artifact checks below are the means of confirming the goal; pick the ones that exercise your specific goal definition.
Sub-agent self-reports describe intent, not always reality. After every phase that touched the filesystem or remote services, run a read-only check against the goal:
ls, git status, git diff --statgit log --oneline -5git tag --points-at HEAD, git ls-remote --tags origingh repo view --json visibility, gh release view v<VERSION>, gh issue list, gh issue view <N> --comments to confirm the fix comment landednpm view <pkg>@<version>, registry-specific checksbun run devcheck if the previous phase was supposed to land greenIf verification disagrees with the sub-agent's report, that's the signal to re-spawn with the actual state and the unmet goal in the prompt — not to trust the report. The goal hasn't changed; only the path needs to.
| Phase type | Authorization required |
|---|---|
| Reads, analysis, file edits (working tree only) | Implicit — initial workflow approval covers these |
| Local commits, annotated tags | Explicit at workflow start; durable through workflow end |
| Push to remote, npm / registry publish, GH release create, Docker push | Explicit at workflow start; durable through workflow end |
| Destructive ops (force push, tag delete, remote branch delete, etc.) | Always re-confirm, never assume |
Pipeline authorization is durable through to completion. Once the user authorizes a workflow run, don't re-ask at each phase boundary — proceed automatically through gates that pass. Conditions that always require a fresh check-in: destructive ops on shared resources, external actions without sign-off, errors that need human judgment.
Workflow files are thin by design. Each phase row in a workflow's phases table maps to a Tier 1 skill or a thin orchestration step. Phase notes are for orchestration overrides only — sequencing rules, fanout-specific constraints, non-obvious instructions, decisions the foundational skill leaves to the caller. Never paraphrase what a foundational skill already documents. A phase that runs a Tier 1 skill end-to-end with no orchestration override needs no phase note — just the row in the table.
The same discipline applies to gotchas: workflow-specific gotchas are about the orchestration pattern itself (e.g., parallel sub-agent context exhaustion, normalization gaps). Gotchas about a Tier 1 skill's internals belong in that skill, not the workflow.
For scenarios that don't map cleanly to one of the four workflow files — security audits across N servers, framework-wide migrations, design-only extensions, ad-hoc multi-step work — the universal rules and sub-agent strategy above still apply. Author a new workflow file at workflows/<scenario>.md when the pattern is repeatable enough to codify. Follow the shape of the existing workflow files. Open with the back-pointer every workflow carries — a "Read ../SKILL.md first" tail on the frontmatter description, plus a "Use after reading ../SKILL.md." line under the H1 — so an orchestrator that opens the file directly (not routed through this skill) still picks up the universal rules and sub-agent strategy. Then, when applicable: Tier 1 skills referenced, pre-flight, phases table, phase notes, workflow-specific gotchas, checklist. Apply the workflow file discipline above.
Verify before kicking off the first phase. Workflow files add their own pre-flight items on top of these.