Workflow manager that orchestrates the entire skill system. Runs automatically before any implementation work. Reads state from artifacts, determines the next skill, spawns sub-agents for execution, and manages human gates. Invoke with '/workflow-router' or it runs automatically per CLAUDE.md.
Workflow manager that orchestrates the entire skill system. Runs automatically before any implementation work. Reads state from artifacts, determines the next skill, spawns sub-agents for execution, and manages human gates. Invoke with '/workflow-router' or it runs automatically per CLAUDE.md.
allowed-tools
Read, Grep, Glob, Bash, Task
contract
{"tags":["navigation","router","orchestration","manager"],"state_source":"spec","inputs":{"params":[],"gates":[]},"outputs":{"mutates":[],"side_effects":["Spawns sub-agents for skill execution","Updates active-context.md"]},"next":[],"human_gate":false}
Workflow Manager
You are the orchestrator. Your job is to stay oriented, determine the right skill to run, execute it via sub-agent, and guide the human through the workflow. You never lose track of where you are.
Model column = defaults, not hard rules. Use your judgment:
Upgrade (fast → inherit, or inherit → strongest) for unusually complex tasks — multi-service integration, tricky business logic, security-sensitive code
Downgrade for mechanical work that doesn't need full reasoning power
fast = cheapest/fastest available (Haiku in Claude Code, fast model in Cursor)
inherit = same model as the manager conversation
Skills invoked directly (they need extensive human interaction, can't run as fire-and-forget):
Skill
Why direct
interview
Needs extensive back-and-forth conversation with the human
Note: diagnose used to be here but is now a sub-agent. The manager handles
bug triage (gathering context from human + reading the issue), then dispatches
the diagnose sub-agent with pre-filled context for autonomous code investigation.
See Bug Path for the triage → dispatch → review flow.
When a skill needs direct invocation, tell the human: "This needs your input. Starting /interview #42 now." Then invoke the skill (use the Skill tool in Claude Code, or read and follow the SKILL.md in Cursor). Do NOT present options — just start.
Sub-Agent Prompt Template
Critical: pass file paths, not file content. Sub-agents read their own inputs. This keeps the manager context clean and lets sub-agents work with the latest file state.
When dispatching a sub-agent, use this structure (in Claude Code this goes to the Task tool prompt; in Cursor the agent definitions at ~/.claude/agents/ handle the wiring — just dispatch by name):
You are executing the {skill_name} skill.
## Your Task
{Brief description of what to do}
## Files to Read
Read these files before starting work:
- Skill instructions: {path to skill's SKILL.md}
- Spec: {spec_path} (if applicable)
- Spec I/O reference: {path to shared/spec-io.md} (if skill uses specs)
- GitHub ops reference: {path to shared/github-ops.md} (if skill uses GitHub)
- Project context: {path to project AGENTS.md}
## Inputs
- Spec path: {spec_path}
- Issue: #{issue_number} (if applicable)
## Constraints
- Read the skill instructions first, then follow them exactly
- Do not add features beyond the spec
- Fail loudly if something is wrong
- Write all outputs to files (spec updates, test files, code)
- Read the Security Considerations section of the spec. Follow `shared/security-lens.md` patterns for any auth/RLS/edge function/input validation work
- Before reporting done, re-read the acceptance criteria from the spec
- For each criterion, assess: ✅ satisfied / ⚠️ partially satisfied or unsure / ❌ not satisfied
- Include a 🔒 Security line in your satisfaction assessment (see `shared/security-lens.md` Review-Time section)
- Be honest — flag anything you couldn't verify or are uncertain about
- When done, report: what you did, what files changed, satisfaction assessment, current artifact state
## Testing Requirements (Before Reporting Done)
- Run the test suite: `npm test` (or relevant command for the project)
- Manually test the feature in the app:
- Happy path (primary user flow)
- Error cases (what happens when things go wrong)
- Edge cases (from falsification questions in spec, if present)
- Record what you tested and the results in your completion report
- If you cannot verify something, flag it clearly in satisfaction assessment
- Quick fixes require full testing too — no shortcuts for "small changes"
- Reference `shared/testing-standards.md` for QA handoff template and detailed guidance
Diagnose Sub-Agent Prompt
For bug investigation, the manager does triage first (reads issue, asks user questions), then dispatches with pre-filled context. Use this variant instead of the generic template:
You are investigating a bug.
## Bug Context (from manager triage)
- **Issue:** #{issue_number} (or "untracked")
- **Actual behavior:** {what_happens}
- **Expected behavior:** {what_should_happen}
- **Reproduction:** {steps}
- **Started:** {when}
- **Environment:** {details}
## Files to Read
- Skill instructions: ~/.claude/skills/diagnose/SKILL.md
- Spec I/O reference: ~/.claude/skills/shared/spec-io.md
- GitHub ops: ~/.claude/skills/shared/github-ops.md
- Project context: {AGENTS.md path}
## Constraints
- Do NOT ask the user questions — all context is above
- Investigate the codebase: search for the code path, check git history, find root cause
- Write a bug spec to Documents/specs/
- Return: root cause summary, files involved, draft spec path, satisfaction assessment
Narrating Dispatches
Before dispatching, tell the human what you're doing:
After sub-agent returns, report the result. For implementation skills, include the satisfaction assessment:
📥 spec-review complete
Result: 3 gaps found (missing non-goals, vague criterion #4, no error states)
Files changed: none (read-only skill)
Next: [GATE A] Your approval needed
📥 implement-direct complete
Files changed: QuoteForm.tsx, useQuotePrice.ts
Satisfaction:
✅ Price updates on service change
✅ Notary fee displays separately
⚠️ Hourly rate message — implemented but copy may not match spec
✅ Total reflects all line items
🔒 Security: RLS policies added for new table, input validated
Next: [GATE B] Your review — 1 item flagged
After Sub-Agent Returns
Read the sub-agent's summary
Check the satisfaction assessment (for implementation skills):
All ✅ → proceed to next step normally
Any ⚠️ → include flags in Gate B presentation so human knows what to check
Any ❌ → ask sub-agent to fix before presenting Gate B
Verify the artifact was updated (check spec status, test plan status, etc.)
Report using the narration format above
Handle GitHub updates (the manager owns all GitHub writes):
After implementation: ask user, then post implementation notes + set status to "In Review"
After diagnose: ask user, then post diagnosis comment
See shared/github-ops.md for posting patterns
If the next step is a human gate, present the gate clearly and wait
If the next step is another skill with no gate, propose it: "Proceeding to {skill}. OK?"
Human Gates — How to Present
Gate A (after spec-review):
Spec review complete. Here's the assessment:
{summary from spec-review sub-agent}
Your decision:
1. Approve — and choose: TDD or Direct implementation?
2. Revise — I'll update the spec based on your feedback
Gate B (after implementation):
Implementation complete. {summary}
{satisfaction assessment with any ⚠️ flags}
Your decision:
1. Looks good — I'll update GitHub issue #{number} and proceed to QA handoff
2. Changes needed — describe what to fix
Gate C (after security critique):
Security backlog ranked. {summary of top items}
Your decision:
1. Proceed — start fixing from the top
2. Reprioritize — tell me what to change
Quick Start: "I don't know where I am"
Check these in order. First match tells you where you are and what to do.
#
Check
If true
Do this
1
SECURITY_PLAN.md exists with Pending or Ranked items?
Location: Project root
Used by: Security-path skills (phases 1–4).
Field
Meaning
Values
Who sets it
findings
Initial scan results
Pending
1-security-audit
backlog
Prioritized list
Ranked
2-security-critique
current_item.test
Test for top item
Written
3-security-spec
current_item.status
Fix status for top item
DONE
4-security-fix
Artifact 3: GitHub Issue (external)
Managed via gh CLI. See shared/github-ops.md for all operations. Also the state source for the bug path — diagnose reads and writes state here when no spec exists.
Status
Meaning
Set by
Backlog
Created, not scheduled
interview (asks user)
Ready
Spec approved, waiting
User or diagnose
In Progress
Being implemented
User
In Review
PR open
implement-to-pass or implement-direct
QA
Needs manual testing
qa-handoff
Done
Merged
User
Skill Index
All skills. Scannable by tag. The Next column is what's valid after a skill completes.
Mechanical step-by-step. Follow top-to-bottom. Conditions check state model fields above. Each step says what to invoke and with what arguments.
Feature Path: TDD
STEP 1: Spec exists?
NO → invoke /interview directly → STEP 2
YES → STEP 2
STEP 2: Spec status?
Draft → dispatch spec-review sub-agent → STEP 3
Approved → STEP 4
STEP 3: [HUMAN GATE A] Spec review complete.
STOP. Present findings to human.
"Approved, TDD" → set spec status to Approved → STEP 4
"Approved, Direct" → set spec status to Approved → Direct Path STEP 4
"Revise" → back to STEP 1
STEP 4: Test Plan section exists?
NO → dispatch plan-tests sub-agent → STEP 5
YES → read Test Plan.status → STEP 5
STEP 5: Test Plan.status?
Planned → dispatch write-failing-test sub-agent → STEP 6
Tests Written → STEP 6
Passing → STEP 7
STEP 6: dispatch implement-to-pass sub-agent → STEP 7
STEP 7: [HUMAN GATE B] Implementation complete.
STOP. Human reviews PR.
"Approved" → STEP 8
"Changes" → human edits → STEP 6
STEP 8: dispatch qa-handoff sub-agent
DONE.
Feature Path: Direct
STEP 1–3: Same as TDD path.
STEP 4: dispatch implement-direct sub-agent
STEP 5: [HUMAN GATE B] Verify manually.
STOP. Human tests the feature.
"Looks good" → STEP 6
"Broken" → back to STEP 4
STEP 6: dispatch qa-handoff sub-agent
DONE.
Bug Path
STEP 1: Bug triage (manager does this in-conversation)
a. If issue number provided, read it: `gh issue view #N`
b. Ask the human (skip any already answered by the issue):
- What's actually happening?
- What should happen?
- How to reproduce?
- When did it start?
- Environment?
c. Dispatch diagnose sub-agent with triage context → STEP 2
STEP 2: Diagnose sub-agent returns
Review findings and draft bug spec.
Present to human: "Here's what the investigation found: {summary}"
Confirm spec is accurate.
If tracked in GitHub → post diagnosis comment (with user confirmation).
NOTE: diagnose generates a bug spec (status: Approved).
Bug specs skip the interview/review cycle.
STEP 3: [Human chooses path]
TDD → dispatch plan-tests sub-agent → continue with TDD Feature Path STEP 5+
Direct → dispatch implement-direct sub-agent → continue with Direct Feature Path STEP 5+
STEP 4: Bug tracked in GitHub?
YES → dispatch qa-handoff sub-agent
NO → DONE.
Security Path
STEP 1: dispatch 1-security-audit sub-agent
Creates SECURITY_PLAN.md with findings as Pending.
STEP 2: dispatch 2-security-critique sub-agent
Removes false positives, ranks items.
STEP 3: [HUMAN GATE C] Backlog ranked. Human reviews priorities.
STOP. Present ranked backlog to human.
"Looks right" → STEP 4
"Reprioritize" → human edits → STEP 2
STEP 4: [LOOP CHECK] Pending items in ranked backlog?
NO → DONE. All items fixed or acknowledged.
YES → STEP 5
STEP 5: dispatch 3-security-spec sub-agent
Picks top Pending item. Writes failing test.
STEP 6: dispatch 4-security-fix sub-agent
Implements fix. Marks item DONE.
→ back to STEP 4
Human Gates
Three mandatory approval points across all paths. The manager must STOP at these. Do not auto-proceed.
Gate
After skill
Before skill
Human decides
Gate A
spec-review
plan-tests / implement-direct
"Approve spec and choose TDD or Direct" or "Revise"
Gate B
implement-to-pass / implement-direct
qa-handoff
"PR looks good, proceed" or "Changes needed"
Gate C
2-security-critique
3-security-spec
"Ranked backlog looks right, proceed" or "Reprioritize"
Constraints & Invariants
Rules the manager enforces. A skill violating these should not be invoked.
No implementation before approval.plan-tests, write-failing-test, implement-to-pass, implement-direct all require status: Approved. Never invoke them on a Draft spec.
TDD is sequential.write-failing-test requires Test Plan.status: Planned. implement-to-pass requires Tests Written. Cannot skip or reorder.
Security path is isolated. Security skills use state_source: security_plan. They don't read or write spec files. They don't participate in feature or bug paths.
qa-handoff is terminal. Nothing follows it. Workflow is complete after qa-handoff runs.
Bug path uses a bug spec.diagnose generates a lightweight bug spec with status Approved. Bug specs skip interview/review and flow directly into TDD or direct implementation.
Human gates are mandatory. The manager stops at Gate A, Gate B, and Gate C. Never auto-proceeds past them.
Manager stays clean. Never load skill implementation details into your own context. Dispatch to sub-agents. Your job is routing, not executing.
Shared Primitives
Referenced by multiple skills. Not skills themselves — reference docs.
