| name | using-rolepod |
| description | Use at the start of every request to route work into Rolepod's workflow spine before planning, editing, delegating, verifying, reviewing, or shipping. Determines phase, required skills, skip rules, and evidence needed. |
| when_to_use | every user request unless the task is a clearly trivial answer that requires no repo state, no action, no recommendation, and no workflow decision |
| tier | 0 |
| phase | router |
Using Rolepod — workflow router
Rolepod routes every task through one workflow spine:
Define → Plan → Build → Verify → Review → Ship
Lead reads this skill on the first turn of each request. Pick the phase, fire the required skill, then resume normal work inside that phase. Specialists (frontend / backend / billing / security / etc.) are chosen after the phase is clear, not before.
Iron Rule
Before plan / edit / recommendation / answer → identify task type + required phase + required skill.
User explicit instruction wins. If user says "skip spec", "answer only", "just write the code" → obey, state which gate was skipped, proceed.
Default: route through the spine. Skipping is allowed only when (a) the task is trivial-answer-only, (b) user explicitly authorizes the skip, (c) the request is a question with no action attached, OR (d) the Skip rule below passes (diff ≤5 lines + 1 file + 0 logic-bearing lines + not high-risk).
Router modes
This skill auto-fires on every request and runs in one of two modes.
Auto-router mode (default) — fires on normal requests. Picks the FIRST needed phase only; does not run every phase. May skip Define / Plan / Review / Ship when task size and risk justify it (see Skip rule). The user invokes nothing — routing is automatic. The Quick router table below is the single routing source.
Force-full-lifecycle mode — the user explicitly asks for the full workflow. Run Define → Plan → Build → Verify → Review → Ship with no phase skips unless the user later overrides.
Force-full-lifecycle mode — /rolepod-full
Switch from auto-router to force-full mode when the user's message opens with any of these:
/rolepod-full <task> — cross-CLI invocation of the rolepod-full skill$rolepod-full <task> — Codex skill-picker style- Natural language:
force full lifecycle, run full rolepod lifecycle
rolepod mode: full lifecycle — this exact phrasing only
Bare /rolepod, bare rolepod mode, bare run all phases, and bare no skip are NOT force-full triggers — they fall through to auto-router. /rolepod is not needed for normal use; a normal prompt auto-routes.
The rolepod-full skill is the explicit entrypoint — it loads this skill in force-full mode; the execution backend table lives in references/force-full-lifecycle.md. If the user invoked rolepod-full, you are already in force-full mode; run it here.
Force-full behavior
Force-full runs all six phases in order with no skips — even a one-line fix — with external adversarial reviewers when configured. The full phase-by-phase detail, the execution backend table, the start banner, careful-mode rigor, and the force-full rationalizations live in references/force-full-lifecycle.md. Load it when entering force-full mode.
Boundary
Owns:
- Phase selection, skip decision, force-full detection, next skill.
Does not own:
- Detailed spec content, task planning, implementation, verification, review findings, or branch fate.
- Specialist / domain decisions before the phase is clear.
Hand off:
- Once the phase is chosen, the phase skill owns its own gates.
Quick router
Match the user intent to the FIRST skill that fires. The skill itself decides what comes next. The Model tier column hints which agent tier is appropriate when the work delegates — the tier legend below is the operating rule; the full policy is docs/model-tier-policy.md in the rolepod source repo (not shipped with the plugin).
| User intent (verbs / phrases) | Phase | First skill fires | Model tier |
|---|
| "build / add / create / make / design" + vague target | Define | write-spec | cheap (PM/spec) |
| "build X to spec" + spec exists | Plan | write-plan | cheap–balanced |
| "execute plan / work the plan / implement plan.md" | Plan→Build | write-plan → implement-plan | balanced |
| "write test cases / test this feature / report a bug" — QA hand-off, no fix wanted | Verify (QA) | qa-tester agent (spec-first test-case design); a found bug → debug-issue report-only exit | cheap–balanced |
| "fix bug / failing test / broken / regression / why does X fail" | Build (bug) | debug-issue | balanced |
| "refactor / simplify / clean up" | Build (refactor) | simplify-code → check-work | balanced |
| "use agents / multi-agent / in parallel / parallel-safe" | Plan | write-plan (agent routing + cohesion contract) | balanced |
| vague UI / dashboard / product-design request | Define | write-spec | cheap (PM/spec) |
| clear UI edit (existing design / screenshot / exact acceptance criteria) | Build (UI) | implement-plan → check-work | balanced |
| browser verification / "does the UI work?" | Verify | check-work | balanced |
| "audit UX / UI / a11y" of a page or flow (single surface) | Verify→Review (UI audit) | check-work §3 ladder observes → review-code UI axis (ui-ux-designer when available; /audit-a11y when uiproof installed) | balanced |
| edit / implement / fix on auth / billing / payments / credits / migration / data deletion / secrets / tokens / crypto / permissions / security (a "plan / design" ask on these → Plan row below) | Define (high-risk) | write-spec → write-plan → implement-plan → review-code | strong |
| architecture decision (DB schema / API contract / module split) | Plan | write-plan → system-architect agent when available | strong |
| "is this done / fixed / does it work / verify" | Verify | check-work | balanced |
| "review / check this / look at the diff" | Review | review-code | strong (review) |
| "audit / sweep / map / find all X" on the whole repo | Review (repo-wide) | scope-then-spawn method (see below) → review-code | balanced |
| "ship / merge / push / PR / ready / go live" | Ship | Finish ritual below (check-work → review-code → finish-work) | strong (final review) |
| explain-only / conceptual question (no artifact) | (no phase) | answer directly — needs a wide repo / online sweep first → ONE scout agent returns a research report (always-on Code search rule) | cheap |
| unclear doc artifact / proposal / ADR scope | Define | write-spec | cheap |
| clear doc edit / add runbook section / update README | Build | implement-plan | cheap |
| "context too large / compact / resume / handoff / manage session" / stuck after repeated attempts | (cross-cut) | manage-context | cheap |
If no row matches: ask the user what phase the task is in. Don't pattern-match yourself into Build.
Model tier hint reading
- cheap = haiku-class. Docs, PM, business analysis, customer-facing copy.
- balanced = sonnet-class (default). Normal implementation.
- strong = opus-class. Architecture, billing, security, migration code, and final-pass / adversarial code review (a review context, not a separate tier).
The Lead picks the tier at dispatch time from the row's hint (agent files carry no model pin — the hint column is the policy). Escalate a tier only when the task proves harder than routed (BLOCKED redispatch) or the user explicitly asks; never silently downgrade a strong row.
Scope-then-spawn — repo-wide audit / sweep
For any task touching the whole repo (audit, refactor sweep, dead-code hunt, dependency map, "find every usage of X"): scope the file list first, narrow to the risky subset, then spawn agents only on that subset — never fan one agent per file across hundreds. The 3-step flow, tool order, and exceptions live in references/scope-then-spawn.md.
State machine — phase → exit evidence → next
Router fires the first skill per phase. Phase exits only when its exit evidence is on the table (or user explicitly authorizes skip). Next phase reads from the Next allowed column — no jumping.
| Phase | Required first skill | Exit evidence | Next allowed |
|---|
| Define | write-spec | written spec OR approved one-line design (≤5-line task) OR explicit "skip spec" | Plan |
| Plan | write-plan (+ agent routing + cohesion contract if multi-agent) | ordered task list with done-condition + verify command per task; dependencies marked | Build |
| Build | implement-plan (+ debug-issue for bug intent) | changed files + tests added (or explicit no-test justification) + red→green evidence | Verify |
| Verify | check-work | fresh command output / screenshot / curl / log evidence; OR explicit "verify impossible because X" risk note | Review (high-risk / multi-file) OR Ship (low-risk) |
| Review | review-code | findings fixed OR rejected with line-anchored reason; no unresolved blocker | Ship |
| Ship | finish-work | S+T+F+P gates green (P = PR scope, one concern per PR); required CI lanes pass; user approval when policy requires; 4-option finish menu presented (merge / open PR / keep open / discard) | end |
Router decides the first move only. Each downstream skill owns its own gates; using-rolepod doesn't re-explain them.
Skip rule
Skip a phase WHEN ANY of these holds (state explicitly in response):
- task is pure question / explanation / lookup (no file change)
- OR diff ≤5 lines + 1 file + 0 logic-bearing lines + not on high-risk path
- OR user explicit: "skip spec" / "just commit" / "answer only" / "no plan" / "ship as-is"
Verify never fully skips — verify-first is always-on. Trivial fixes drop the heavyweight verify (full suite, browser drive), not the lightweight one (re-read file, confirm edit landed).
Stop conditions
- Coding before Define on ambiguous request → STOP, run
write-spec.
- Claiming done before Verify → STOP, run
check-work.
- 2nd parallel agent spawn without contract → STOP, run
write-plan and write the cohesion contract first.
- Sub-agent attempting
git commit / git push / gh pr merge → not allowed; Lead commits after the reviewer pass.
- High-risk path (auth / billing / payments / credits / migration / data deletion / secrets / tokens / crypto / permissions / security) with 0 reviewer agents dispatched → STOP, dispatch qa-tester + security-engineer, plus an external CLI reviewer on a model family different from the Lead's if one is installed (routing: review-code's
external-review-routing.md).
- 3rd agent on same issue OR 3rd PR on same surface in one session → STOP, ask user (hard-stop rule).
- Diff mixes 2+ unrelated concerns at push/merge time → STOP, split into separate PRs (
finish-work P1-P4 gate).
- Concurrent sessions: if SessionStart warns "concurrent session(s) detected in this worktree" → before editing a SHARED file, spawn an isolated worktree first (
git worktree add ../<repo>-task-<ts> <branch> && cd) and continue there. rolepod guards against same-file stomp between concurrent sessions; disjoint and solo edits flow free. Override: ROLEPOD_ALLOW_SHARED_WORKTREE=1 for intentional shared/read-only review sessions.
Finish ritual (Ship phase exit)
When the user says "done" / "finished" / "complete" / "ready" — or when the task obviously reached a natural stopping point — fire in order:
check-work — produce concrete evidence the change works (test output / screenshot / curl).review-code — if multi-file or high-risk, pick adversarial reviewers per their domain match: an external CLI whose model differs from the Lead's, plus qa-tester.finish-work — owns the 4-option finish menu (merge / open PR / keep open / discard); never auto-pick — the branch decision is the user's.
Output pattern
Routing: <phase> → <skill>
Reason: <one sentence>
Skipping: <phases + why>, or "none"
Next step: <concrete action>
Use the full Routing / Reason / Skipping / Next-step block for non-trivial work, explicit /rolepod-full, and any case where the routing decision could surprise the user. For trivial answer-only tasks, skip the block — answer naturally and concisely.
Example — vague feature:
Routing: Define → write-spec
Reason: "build a React todo list" = vague target, no spec.
Skipping: none.
Next step: 4-question interview to pin acceptance criteria.
Example — typo fix:
Routing: Build → direct edit (gate-light)
Reason: typo, ≤5 lines, 1 file, 0 logic, not high-risk.
Skipping: Define + Plan + heavyweight Verify. Lightweight Verify runs.
Next step: edit + re-read + commit.
Example — done claim:
Routing: Ship → finish ritual
Reason: user said "is this done?"
Skipping: none — runs check-work → review-code → finish-work.
Next step: run tests, paste pass output, present 4-option menu.
Optional plugin skills (backend awareness)
If the user has installed a sibling plugin under Extension Protocol v1 (spec: docs/EXTENSION-PROTOCOL.md in the rolepod source repo), prefer its skills over manual orchestration. The parent writes <git-root>/.rolepod/parent-active at SessionStart so children switch to with-rolepod mode and route evidence into .rolepod/evidence/ for check-work to aggregate. Currently recognised:
rolepod-uiproof (v0.6+) — /verify-ui, /audit-a11y, /visual-diff, /scaffold-e2e, /check-errors. Used by check-work (verify + a11y + visual), debug-issue (browser repro / console errors), review-code (WCAG + visual regression).rolepod-wplab (v1.9+) — 14 WP skills + 82 MCP tools. Used by check-work (/wp-health-check), debug-issue (/wp-diagnose), implement-plan (/wp-edit-*, /wp-scaffold), review-code (/wp-changes).rolepod-dblab (v0.1+) — /db-introspect, /db-query, /db-explain, /db-migrate-verify, /db-write. Used by check-work (DB state as PASS/FAIL evidence), debug-issue (live data state as root cause), review-code / finish-work (/db-migrate-verify on migration / auth / billing paths). Seam with wplab: a WordPress DB → wplab (WP-semantic); any other database → dblab (raw engine).
When a child is not installed, the phase skill falls back to: (a) Playwright MCP, (b) Chrome DevTools MCP (sharper console / network / perf), or (c) manual instruction. Phase skills carry the explicit chain.
Domain detection — when to suggest a child
| Signal | Suggest |
|---|
wp-config.php at repo root | rolepod-wplab |
package.json lists playwright, cypress, react, vue, svelte, next, nuxt, astro | rolepod-uiproof |
alembic.ini at repo root, or sqlalchemy / psycopg / psycopg2 / asyncpg in requirements.txt / pyproject.toml (non-WordPress DB) | rolepod-dblab |
.rolepod-uiproof/, .rolepod-wplab/, or .rolepod-dblab/ exists | the matching child already in use |
Detect availability by inspecting whether the slash command appears in the available skill list, or by treating tool-call absence as a fallback signal.
Examples
Non-blocking — read when a request does not obviously match a Quick-router row:
examples/routing-transcripts.md — eight worked routing transcripts (vague feature, clear edit, bug, done-claim, repo-wide audit, /rolepod-full, refactor, and a pattern-matched-into-Build correction). Each shows the user message, the routing decision, and the next step.
Common Rationalizations
| Excuse | Reality |
|---|
| "Simple task, skip the spine" | Trivial-answer-only skips are explicit. Coding 5+ lines = run the spine. |
| "I already know what to build" | Even right answers without a spec drift mid-implementation. Write the 5-line spec; 30 seconds. |
| "User just wants a fix" | They want a correct fix. debug-issue finds the root; symptom patches recur. |
| "Tests are obvious, I'll add later" | Later never comes. TDD adds the test now or admits in writing it won't have one. |
| "Solo work, no contract needed" | The moment a second agent (or future-you in a fresh session) touches the surface, contract pays off. |
| "Reviewer takes too long" | Skip review = ship bugs. An external-CLI adversarial pass takes ~30s. |
Don't
- Spawn specialist agents (frontend / backend / billing / etc.) before the phase is clear.
- Use
finish-work as a placeholder ("I'll add it later"). It's the last skill, fires only at Ship.
- Replace
check-work with the agent's confidence ("looks right to me").
- Skip Define just because the user typed in a hurry. Ask 1-2 questions.
- Treat this skill as documentation. It's a router — pick a row, fire the skill.
Influence
Sharpens the workflow spine that already exists in the per-CLI doctrine doc (CLAUDE.md / AGENTS.md / GEMINI.md / Cursor always-on rule) so that small models route the same way large ones do. Pairs with write-plan for specialist selection and finish-work for the final gate.
