| name | smith-routing |
| description | Educational routing skill. Walks the user through smith's methodology routing matrix without committing to a specific task. Use to learn "when do I apply BMAD vs SPARC?", "what methodology for brownfield?", "explain the bug fix workflow". Pulls from routing-map.md (14 contexts + 29 methodology cards) and sections/NN-*.md (detailed playbooks). Output: educational comparison + recommendation when user describes their situation. Does NOT produce a Plan artifact — for that, use /smith-plan.
Triggers: "smith routing", "/smith-routing", "explain methodology", "какая методология", "when do I use", "compare methodologies", "routing walkthrough", "BMAD vs SPARC", "Strangler Fig or rewrite", "show me the routing matrix"
|
| origin | forgeplan |
/smith-routing — educational walkthrough
This skill is the teacher companion to smith. Where /smith-plan produces a concrete Plan
artifact for a specific task, /smith-routing explains the routing matrix in the abstract: it
walks the user through smith's 14 contexts, compares methodologies side-by-side, and answers
"which methodology fits my situation?" without committing to action.
Read-only contract: this skill never writes artifacts (no PRD / RFC / ADR / EVID / NOTE),
never calls forgeplan_new, forgeplan_update, or any mutating tool. It reads the routing-map
and section playbooks and renders explanations.
Foundation: plugins/fpl-skills/skills/smith/routing-map.md (14 contexts × 29 methodology cards)
plugins/fpl-skills/skills/smith/sections/NN-*.md (per-context detailed playbooks).
When to invoke
- The user wants to learn, not commit ("explain when BMAD vs SPARC", "что лучше — Strangler Fig или rewrite?").
- The user is unsure which context applies to their situation and wants the matrix surfaced.
- The user wants to see all methodologies in the routing matrix at once.
- A comparison is asked — "BMAD vs SPARC for my case", "Strangler Fig or full rewrite?", "OWASP or STRIDE?".
- Before going to
/smith-plan — when the user hasn't yet formed a specific task and wants orientation first.
- The user types a methodology name they've heard but isn't sure when it applies — "what's RIPER-5?", "что такое A3 Problem Solving?".
When NOT to invoke
- The user has a concrete task ready to plan — use
/smith-plan <task> instead.
- The user wants to bootstrap a new project — use
/smith-bootstrap.
- The user wants smith's default orientation ("what does smith do?") — use
/smith.
- The user is in the middle of an incident — that needs
/smith-plan "incident", not education.
Three modes
/smith-routing operates in one of three modes. Mode is inferred from the user's phrasing.
| Mode | Trigger phrases | Behaviour |
|---|
| Comparison | "X vs Y" / "compare A and B" / "BMAD or SPARC?" | Side-by-side pros/cons + when each shines + recommendation for user's context |
| Walkthrough | "walk me through routing" / "show all contexts" / "explain the matrix" | Iterate through 14 contexts with one-line summaries; ask user which to dig into |
| Question-Answer | "what for brownfield?" / "for bug fix?" / "какая методология для аудита?" | Quick answer with citation to routing-map row + load matching section file |
Modes are not mutually exclusive — a user may start in Walkthrough, then ask for a Comparison within it. The skill stays educational across the whole flow.
Procedure
Step 1 — Parse the user's question
Classify the user's input into one of the three modes:
- Contains
vs / or / versus / compare / какой лучше → Comparison.
- Contains
walk me through / show all / explain the matrix / все контексты → Walkthrough.
- Contains a single domain phrase ("for brownfield", "security audit", "tech debt") → Question-Answer.
If ambiguous, ask the user one clarifying question before proceeding:
"Would you like a side-by-side comparison, a full walkthrough of all 14 contexts, or a quick answer for your specific situation?"
Step 2 — Read the routing brain
Always read plugins/fpl-skills/skills/smith/routing-map.md first. It contains the 14-row routing
table (one row per context) and the 29 methodology cards. Treat it as the single source of truth —
never invent rows, never blend rows.
Step 3 — Comparison mode
If Comparison mode:
- Identify the 2 (or more) methodology names in the user's question.
- Look them up in the Methodology cards section of
routing-map.md.
- Render a side-by-side table: name, year/author, style, best for, worst for, source link.
- Conclude with a one-paragraph recommendation tailored to whatever context the user mentioned.
If the user gave no context, ask one question to identify it before recommending.
Step 4 — Walkthrough mode
If Walkthrough mode:
- Render the 14-context table with one-line summaries (use the
sections/_index.md one-liners for rows 1-12, and the routing-map.md row summary for rows 13-14, which do not yet have dedicated section files).
- Ask the user to pick a row to dig into.
- On pick, load the matching section file (
sections/NN-*.md) and render its playbook. Rows 13-14 do not yet have a dedicated section file — fall back to the full row in routing-map.md.
- After the playbook, offer two follow-ups: "compare with another context?" or "ready to plan? →
/smith-plan <task>".
Step 5 — Question-Answer mode
If Question-Answer mode:
- Classify the user's described situation into one of the 14 contexts.
- Cite the routing-map row number + primary methodology + secondary methodologies.
- List the dispatch sequence (agent chain).
- Name the evidence artifacts required.
- Load the corresponding
sections/NN-*.md file for the detailed playbook and render the salient parts.
- Always include a hand-off line: "Want to make this concrete? Run
/smith-plan <task>."
Step 6 — Hand-off
At the end of every interaction, always offer the next step:
- If the user has a specific task in mind →
/smith-plan <task> (commits to action, produces Plan artifact).
- If the user still wants general orientation →
/smith (default smith mode).
- If the user wants to compare more methodologies → re-invoke
/smith-routing with a new question.
Never assume the user is ready to commit — wait for them to ask.
Mode 1: Comparison — example output
User asks: "BMAD vs SPARC — which one for my project?"
Skill response shape:
## BMAD-METHOD vs SPARC
| | BMAD-METHOD | SPARC |
|---|---|---|
| Year / author | 2024 / Brian Madison (bmad-code-org) | 2024 / Reuven Cohen (ruvnet) |
| Style | Multi-role persona split (Analyst → PM → Architect → Dev → QA) | Five-phase iterative loop (Specification → Pseudocode → Architecture → Refinement → Completion) |
| Best for | Clean greenfield where role specialisation pays off; AGENTS.md-friendly | New feature inside existing service where spec iteration is cheap and tests anchor refinement |
| Worst for | Brownfield modernisation (Analyst persona has nothing to discover); tactical bug fixes | Architectural decisions (no SPARC phase for irreversible choices); incident response (no time for Pseudocode) |
| Source | https://github.com/bmad-code-org/BMAD-METHOD | https://github.com/ruvnet/sparc |
**Recommendation**: If you're starting a brand-new repository with no legacy gravity, BMAD's
persona-based artifacts (one Analyst NOTE, one PM PRD, one Architect RFC) map cleanly onto our
Profile A creator chain — pick BMAD. If you're adding a feature to an existing service where
tests already exist, SPARC's Refinement loop will give you faster iteration — pick SPARC.
Tell me your situation (greenfield repo? existing service?) and I'll narrow further.
If you're ready to commit, run `/smith-plan <task>` and smith will route to the right
methodology automatically.
The Comparison mode never picks for the user without context — it surfaces the trade-off and asks.
Mode 2: Walkthrough — example output
User asks: "walk me through the routing matrix" / "show me all 14 contexts"
Skill response shape:
## Smith handles 14 contexts
1. **Greenfield bootstrap** — fresh project with no legacy. Methodology: BMAD + GitHub Spec Kit. Pick if no `.git` history yet.
2. **Brownfield modernisation** — legacy monolith that needs replacement. Methodology: Strangler Fig + DDD + Anti-Corruption Layer. Pick if existing codebase with running cashflow.
3. **New feature** — adding capability to existing service. Methodology: SPARC + Hexagonal + JTBD. Pick if the service runs and you're extending it.
4. **Production bug (non-trivial)** — race condition, data corruption, anything needing RCA. Methodology: RIPER-5 + 5 Whys. Pick if the bug is in prod and the cause is unclear.
5. **Trivial bug / hotfix** — typo, off-by-one, broken link. Methodology: tactical fast-path (no formal methodology). Pick if scope is genuinely one-line.
6. **Refactor** — restructuring code without changing behaviour. Methodology: Branch-by-Abstraction + Mikado + DDD. Pick if you need to clean up without breaking callers.
7. **Architecture decision** — "we need to choose between X and Y". Methodology: FPF ADI + ADR/MADR + C4 (if ≥3 modules). Pick when the choice is irreversible.
8. **Security audit** — pre-launch review, OWASP coverage, threat modelling. Methodology: OWASP Top 10 2025 + STRIDE/ASTRIDE. Pick before any production exposure.
9. **Performance audit** — slow endpoint, latency spike, perf review. Methodology: DORA + SRE error-budget + perf-budget. Pick when you have a measurable regression or target.
10. **Product discovery (PDLC)** — "what should we build?". Methodology: JTBD + Lean MVP + Double Diamond. Pick pre-product or pre-feature.
11. **Tech debt cleanup** — cleanup sprint, debt backlog. Methodology: A3 Problem Solving + Fishbone. Pick when you need to justify the trade-off out loud.
12. **Live incident** — production down right now. Methodology: Incident Command System + blameless post-mortem + 5 Whys (after). Pick during the fire.
13. **TDD-first feature** — active SPEC already has `#### Scenario`s ready to drive tests. Methodology: Enforced-TDD sub-cycle (agents-tdd master) + Hexagonal + Ground-truth verification. Pick when the design is already frozen and the work is implementing test-first.
14. **Design-system → code** — porting Pencil/Figma to Storybook + native framework components. Methodology: CANVAS (agents-canvas master) + token pipeline + visual-regression. Pick when the design IS the spec and the work is token-fidelity, not feature logic.
Which one matches your situation? Tell me a row number or describe what you're doing and I'll dig in.
On user pick (e.g. "row 2"), the skill loads sections/02-brownfield.md and renders the detailed
playbook from it — phases, dispatch sequence, evidence requirements, failure modes.
Mode 3: Question-Answer — example output
User asks: "What methodology for security audit?"
Skill response shape:
## Security audit — routing-map row #8
**Primary methodology**: OWASP Top 10 2025 + STRIDE threat modelling.
**Secondary methodologies**: ASTRIDE (for AI-agent specific threats — Adversarial inputs,
Model-theft, Training-data poisoning), ADR for mitigation decisions that change architecture.
**Dispatch sequence**:
1. `research-analyst` (Profile A) — synthesises threat landscape and prior incidents.
2. `security-expert` (Profile B) — STRIDE/OWASP coverage adversarial review.
3. `injection-analyst` (Profile B) — SQL, prompt, command injection specialisation.
4. `pii-detector` (Profile B) — PII exposure surface review.
5. `adr-architect` (Profile A) — only for mitigations that change architecture.
6. `guardian` (Profile B-gate) — final PASS/CONCERNS/BLOCKER verdict.
**Evidence required**:
- EVID from security-expert + injection-analyst + pii-detector (all Profile B, with `## Findings` section).
- ADR for any mitigation that crosses module boundaries.
- BMAD adversarial EVID with ≥1 finding (EPIC-001 S11).
**Why this combo**: OWASP gives the checklist coverage; STRIDE forces threat-model reasoning per
data-flow boundary; AI-specific apps need ASTRIDE which STRIDE alone misses.
**Detailed playbook**: see `plugins/fpl-skills/skills/smith/sections/08-security-audit.md`.
**Methodology sources**:
- OWASP Top 10 2025: https://owasp.org/Top10/
- STRIDE: https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats
- ASTRIDE: https://arxiv.org/abs/2403.13309
---
Want to make this concrete? Run `/smith-plan audit <module-name>` and smith will produce a
Plan artifact with the exact dispatch sequence and evidence requirements for your module.
Hand-off
Every interaction with /smith-routing ends with one or more of these offers:
- Ready to plan a specific task? →
/smith-plan <task> — converts education into a concrete Plan artifact.
- Want default smith orientation? →
/smith — general routing decision for whatever you're working on.
- Want to bootstrap a fresh project? →
/smith-bootstrap <project-name> — produces the BMAD + Spec Kit greenfield scaffold.
- Want to compare more methodologies? → re-invoke
/smith-routing with a new comparison question.
The skill never pushes the user toward action. The user picks the next step.
Hard rules
- Read-only —
/smith-routing produces explanations only. It never creates NOTE, PRD, RFC, ADR, EVID, or any other artifact. It never calls forgeplan_new, forgeplan_update, forgeplan_link, forgeplan_activate, or any mutating tool.
- Always cite the routing-map row and methodology source link in every response. The user must be able to trace every claim back to
routing-map.md and the upstream methodology source.
- When the user's question doesn't match any of the 14 contexts — explain why (e.g. "this sounds like both brownfield and a security audit — which is the primary risk?") and suggest the closest match. Never invent a 15th row. The 14 contexts are the canonical surface; if a situation truly doesn't fit, escalate to the user, don't paper over it.
- Educational tone, not directive —
/smith-routing explains and asks. /smith-plan directs and commits. Keep the line clear. The user should leave /smith-routing more knowledgeable; /smith-plan should leave them with a Plan.
- Never blend methodologies in an explanation — if the user asks "BMAD + SPARC together?" explain that smith picks one row, never blends, and the same applies to methodologies. Show why blending is an anti-pattern (see
routing-map.md paragraph 3).
Examples
Example 1 — Comparison mode
User: "BMAD vs SPARC?"
→ Comparison mode → side-by-side table (Year / author / Style / Best for / Worst for / Source) → one-paragraph recommendation framed around user's context (and if no context given, ask one clarifying question) → hand-off line "ready to commit? /smith-plan <task>".
Example 2 — Walkthrough mode
User: "show me all 14 contexts"
→ Walkthrough mode → render 14-row table with one-line summaries (per sections/_index.md for rows 1-12, routing-map.md for rows 13-14) → "which row matches your situation?" → on pick, load corresponding sections/NN-*.md and render the detailed playbook → end with "/smith-plan to commit, /smith-routing to compare another".
Example 3 — Question-Answer mode (brownfield)
User: "we have a legacy Rails monolith that we want to modernise — what methodology?"
→ Question-Answer mode → classify situation: context #2 brownfield modernisation → cite routing-map row #2: primary Strangler Fig + DDD + ACL; secondary Event Storming + Branch-by-Abstraction + ADR-supersede → dispatch sequence (discover → research-analyst → ddd-domain-expert → adr-architect → goal-planner → coder → tester → architect-reviewer → guardian) → evidence (EVID with 9 brownfield findings + ADR + PRD + ADI EVID + BMAD EVID) → load sections/02-brownfield.md and render the phased walkthrough → hand-off "run /smith-plan modernise rails-monolith when you're ready to commit".
Integration
This skill reads from but never writes to:
plugins/fpl-skills/skills/smith/routing-map.md — primary source: 14-row routing table + 29 methodology cards + agent index + evidence quality bar.plugins/fpl-skills/skills/smith/sections/_index.md — one-line summaries for the Walkthrough mode (rows 1-12 only; rows 13-14 do not yet have dedicated section files — fall back to routing-map.md).plugins/fpl-skills/skills/smith/sections/NN-*.md — 12 detailed per-context playbooks (loaded one at a time, never bundled).
Sibling skills (when to redirect)
| If the user wants to... | Redirect to |
|---|
| Plan a specific task right now | /smith-plan <task> |
| Bootstrap a fresh greenfield project | /smith-bootstrap <project-name> |
| Get default smith orientation | /smith |
| Check methodology coverage on an existing artifact | /methodology-check <ARTIFACT-ID> |
| Generate ADI hypotheses for a hard decision | /fpf-reason |
| Produce a full ADR with C4 diagrams | invoke adr-architect agent via the appropriate skill |
Cross-CLI portability
The educational outputs of this skill (markdown tables, methodology comparisons) are plain
Markdown and portable across CLIs. If used outside Claude Code (Gemini, Codex), the skill body
reads the same; only the slash-command surface differs.
References
Methodology primary sources (sample — full list in routing-map.md)
Forgeplan repo references
- EPIC-002 — smith master-orchestrator epic (this skill is Wave 2-B4).
plugins/fpl-skills/AGENT-AUTHORING-GUIDE.md — canonical Profile A/B/C/D agent patterns referenced in dispatch sequences.- CLAUDE.md
4-Layer Pipeline (S10→S13) — pipeline foundation that smith's evidence requirements enforce.
plugins/fpl-skills/skills/methodology-check/SKILL.md — companion skill for checking coverage on an existing artifact (different scope from this educational walkthrough).
This skill is the teacher; /smith-plan is the doer. Use this one to understand; use that one to commit.
