My Router
Overview
A routing layer that sits between the outer workflow (e.g., superpowers brainstorm/plan/execute/verify) and domain skills. The router reads the working directory, file types, and user prompt to decide which skill to invoke, so the user does not need to remember skill names.
In this repo's shipped form, the routing table has concrete entries for the six shipped skills (implement-review, ci-mockup-figure, readme-polish, editable-figure, my-router itself, and prun for explicit parallel fan-out intent). It is also designed as a pattern you extend. A fork of this repo edits references/routing-table.md directly. A consuming project, where that file is overwritten on every bootstrap, instead registers its own skills in a bootstrap-proof local file (routing-table.local.md at the repo root, or a ## Routing section in AGENTS.local.md); the router reads those rows and dispatches to them. See Extending the Router.
When to Use Superpowers vs. Direct Dispatch
The router decides this. Not all tasks need superpowers' full ceremony.
| Task shape | Route | Why |
|---|---|---|
| Clear, scoped task with an obvious skill match (e.g., "review staged changes") | Direct dispatch — router picks the domain skill and runs it immediately | Brainstorming and planning add no value when the task is already well-defined |
| Open-ended, multi-step, or ambiguous task (e.g., "build a new feature", "restructure the paper") | Superpowers first — brainstorm → plan → execute (router dispatches during execute) → verify | These benefit from thinking before doing |
| Quick edit or fix (e.g., "fix the typo on line 42", "rename this variable") | Neither — just do it directly | No routing or workflow needed |
The rule: if the domain skill is obvious and the scope is clear, skip superpowers and dispatch directly. If the task needs exploration or planning, let superpowers run the outer loop and the router dispatches during execution.
Integration with Superpowers
When superpowers is active, it handles workflow phases: brainstorm → plan → execute → verify. The router activates during the execute phase and dispatches to the right domain skill.
When superpowers is not active (direct dispatch or quick task), the router works standalone.
How Routing Works
At dispatch time, the router checks three signals in order (keywords, file types, project structure). In a consuming project, before applying the shipped table below, it first merges any consumer-local routing extensions: a routing-table.local.md at the repo root, or a ## Routing section in AGENTS.local.md. These two files survive bootstrap (the shipped table does not), so they are where a consuming repo registers its own skills; on a keyword or file-type conflict, the local row wins. See Extending the Router.
1. Prompt keywords (highest priority)
The user's prompt often contains the clearest signal. The shipped routing table includes keyword entries for implement-review, ci-mockup-figure, readme-polish, and editable-figure. Add entries for your own skills in your fork's references/routing-table.md, or, in a consuming project, in a bootstrap-proof local file (see Extending the Router).
When a figure request explicitly asks for PowerPoint or native editability, take the editable-figure route ahead of the generic figure, README-polish, or slide routes. A request to simplify an existing editable figure stays on that route. An explicit HTML mockup, TikZ, screenshot, or prompt-only request keeps its requested format. Before taking that route, check that the session can perform the desktop PowerPoint validation editable-figure requires. If it cannot, explain the limitation and offer ci-mockup-figure only when its output fits the request. Do not silently substitute HTML for an explicitly requested PPTX.
See references/routing-table.md for the current table and the extension template.
For a paper or proposal explanatory figure, especially an overview or "Figure 1", read editable-figure/references/gallery/index.md through the normal skill lookup. Do this whichever figure skill the route selects, including a project-local variant such as nsf-figure-builder. When working for Yue Zhao, enforce its required preference-first design protocol as the top design priority. Inspect selected images and feedback, map confirmed qualities to the new design, and carry that mapping into prompts and implementation. Compare the result against those references. Preserve the requested output format; reading the gallery does not require PowerPoint or change a prompt-only task into a figure build.
2. File types in working directory
If prompt keywords are ambiguous, inspect the files being worked on. The shipped router recognizes staged git changes → implement-review, HTML mockup files for dashboards/timelines → ci-mockup-figure, a top-level README.md flagged for polish → readme-polish, and .pptx figure sources beside a paper, proposal, or README → editable-figure. Add your own file-type rules when you add new skills.
3. Project structure hints
Some projects declare their type in AGENTS.local.md or via directory naming conventions (e.g., a proposals/ or papers/ directory, or a submodule pointing at a shared editorial repo). Use these hints to pick content-aware behavior when relevant to your skills.
Dispatch Rules
- Local-first override: before dispatching, scan
skills/(project-local) for any skill that is a more specific variant of the matched skill. If a local variant exists, use it instead of any pack-deployed or bootstrapped copy. - If a prompt keyword matches → invoke that skill.
- If file context matches but prompt is vague (e.g., "help me with this") → state the detected context and proposed skill, ask the user to confirm before proceeding.
- If multiple skills could apply → state the candidates and ask the user to choose.
- If nothing matches → fall through to superpowers or general agent behavior. Do not force a skill where none fits.
Skill Lookup Order
In consuming project repos, skills can be project-local, pack-deployed, or bootstrapped from shared config. When dispatching, look for each skill in this order:
skills/<name>/SKILL.md: project-local (highest priority). Projects can add their own skills here..claude/skills/<name>/SKILL.md: pack-deployed by bootstrap from the configured packs (anywhere-agents pack addadds one). The.claude/prefix is a historical Claude Code convention; the SKILL.md contents are agent-agnostic..agent-config/repo/skills/<name>/SKILL.md: bootstrapped from the shared config repo.- Installed plugins: agent-specific plugin skills (e.g., Claude Code plugins), check
/skillsoutput.
If a project-local skill matches the task better than a pack-deployed or bootstrapped skill, prefer the project-local one. The router itself follows this same lookup order.
Extending the Router
Where you register a new skill depends on whether you own this repo or only consume it. The mechanism is the same: a routing row keyed on prompt keywords, file types, and directory hints. Only the location differs, and it must survive your config-refresh path.
In a fork of this repo (you own the shipped table):
- Add the skill directory under
skills/<your-skill>/. - Add a row to
references/routing-table.md. - Add a matching
.claude/commands/<your-skill>.mdpointer so Claude Code can invoke it directly.
In a consuming project (this skill arrives via bootstrap, which deploys the configured packs):
Do not edit references/routing-table.md here. Every on-disk copy (.agent-config/repo/skills/my-router/, .claude/skills/my-router/) is overwritten on the next bootstrap or pack verify --fix. Register your skill where bootstrap never reaches:
- Add the skill directory under
skills/<your-skill>/(project-local, bootstrap-proof by construction). - Register its routing in either of these bootstrap-proof files:
routing-table.local.mdat the repo root, using the same table format asreferences/routing-table.md; or- a
## Routingsection inAGENTS.local.md, convenient when you already keep project overrides there.
- Optionally add a project-local
.claude/commands/<your-skill>.mdpointer. The bootstrap copy step is non-destructive and never deletes command files absent from upstream, so a consumer-only pointer survives.
At dispatch time the router merges these local rows on top of the shipped table; on a keyword or file-type conflict, the local entry wins. Both routing-table.local.md and AGENTS.local.md sit outside the set of files bootstrap rewrites, so the registration persists across refreshes.
Combining with Implement-Review
When review is needed after a domain skill finishes:
- Domain skill runs (e.g., code changes, paper edits)
- Changes are staged
- Router dispatches to
implement-reviewwith the appropriate lens (code, paper, proposal, general) - Reviewer applies the lens-specific criteria
See implement-review/SKILL.md for the review loop protocol.
Examples
User says: "Review this"
→ Router detects: staged changes exist → dispatches to implement-review; content-type lens (code, paper, proposal, general) selected based on staged files.
User says: "Build the feature and review it"
→ Router detects: code context → superpowers handles the build, then router dispatches to implement-review with code lens.
User says: "Make an HTML mockup for the method figure"
→ Router detects: keyword "mockup" → dispatches to ci-mockup-figure.
User says: "Polish the README with modern patterns"
→ Router detects: keyword "polish README" → dispatches to readme-polish.
User says: (anything else, shipped router has no rule)
→ Router falls through to superpowers or general agent behavior. Add more rules in references/routing-table.md (in a fork) or in routing-table.local.md / an AGENTS.local.md ## Routing section (in a consuming project).
