Merlin Skills Routing

Merlin Skills Routing

Use this skill before non-trivial implementation work, and always before creating or executing a Codex /goal.

Your job is to identify the current development phase and load only the next useful skill. Keep routing short. Do not load every skill and do not turn routing into a separate planning ceremony when the next step is obvious.

Spec Kit Consultation Pass

For every non-trivial request, do a short Spec Kit consultation before choosing the next skill.

Inspect whether the current work already has:

• .specify/ project infrastructure;
• an active specs// directory;
• current spec.md, plan.md, and tasks.md;
• an existing GOAL.md;
• completed task checkboxes, QA reports, browser proof, PRs, or release artifacts.

Then decide whether the next step should create, refresh, or reuse Spec Kit artifacts. This pass is mandatory even when the next visible skill is brainstorming, to-prd, tdd, diagnose, gstack-qa, or gstack-ship.

If the idea is ambiguous or product-shaped, route to brainstorming, but keep Spec Kit as the destination: the design output should be concrete enough to become spec.md, plan.md, and tasks.md.

Inputs To Inspect

1. The user's newest request.
2. The current repository state and instruction files.
3. Existing Spec Kit infrastructure in .specify/.
4. Existing Spec Kit artifacts in specs//.
5. Existing GOAL.md, test output, QA reports, browser screenshots, PRs, or release artifacts.

If there is a conflict, the user's newest request and current checkout win over old docs.

Required Decision

Return a short routing decision before doing major work:

Phase: 
Spec Kit consultation: create | refresh | reuse | not applicable, with one short reason
Next skill: 
Feature dir: 
Why: 
Required proof: 

Then continue with the next skill or task. Do not stop after routing unless a required artifact is missing or the user asked only for a plan.

Default Route

For autonomous web coding:

spec-kit consultation
  -> brainstorming or to-prd when useful
  -> speckit-cli/setup
  -> speckit-constitution
  -> speckit-specify
  -> speckit-clarify
  -> speckit-plan
  -> speckit-tasks
  -> speckit-analyze/checklist
  -> create-goal
  -> /goal
  -> tdd/diagnose
  -> gstack-qa
  -> playwright-cli/playwright-skill
  -> gstack-ship

In this default route, tdd is an execution mode after speckit-tasks has produced tasks.md, create-goal has produced GOAL.md, and /goal is working an implementation slice. Do not use tdd to replace speckit-tasks or to bulk-write every test before implementation.

Compact form:

spec-kit consultation -> brainstorming or to-prd -> speckit-cli/setup -> speckit-constitution -> speckit-specify -> speckit-clarify -> speckit-plan -> speckit-tasks -> speckit-analyze/checklist -> create-goal -> /goal -> tdd/diagnose -> gstack-qa -> playwright-cli/playwright-skill -> gstack-ship

Most work skips some phases. If .specify/, spec.md, plan.md, tasks.md, or GOAL.md already exists and is current, route to the first missing or stale phase. The durable progress layer remains Spec Kit-native: tasks.md checkboxes track task completion, GOAL.md defines the resume protocol, and QA/browser proof lives next to the feature or in the repo's existing evidence location.

Phase Router

| Phase | User situation | Use this skill | Requires | Produces | Stop or skip condition | | --- | --- | --- | --- | --- | --- | | Pack install | Install, update, refresh, or project-local setup for Merlin Skills | install-merlin-skills | Target root or reasonable default | Installed pack and optional instruction block | Skip for normal feature work | | Spec Kit setup | Need .specify/, specify CLI, Codex $speckit-* skills, integrations, extensions, or presets | speckit-cli | Repo target and permission to initialize | .specify/, .agents/skills/speckit-*, managed context | Skip when .specify/ and needed skills already exist | | Product shaping | Ambiguous product idea, early UX concept, or "is this worth building?" | brainstorming | User intent and repo context | Approved design direction | Skip when the requested behavior is already concrete | | PRD synthesis | Existing conversation needs to become a PRD or issue | to-prd | Enough conversation/repo context | PRD-style requirements | Skip when Spec Kit spec.md already covers the requirement | | Context map | Unfamiliar code area needs a broader map | zoom-out | Code area or topic | Module/context map | Skip when the implementer already knows the area | | Constitution | Project principles are missing or stale | speckit-constitution | .specify/ initialized | .specify/memory/constitution.md | Skip when current principles are good enough | | Feature spec | Need to create or update requirements from natural language | speckit-specify | .specify/ initialized and feature description | specs//spec.md | Skip when spec.md is current | | Spec clarification | Spec has ambiguity, [NEEDS CLARIFICATION], or high-risk assumptions | speckit-clarify | Active spec.md | Clarifications written into the spec | Skip only for explicit spikes or trivial changes | | Technical plan | Need implementation approach, research, data model, contracts, or quickstart | speckit-plan | Active clarified spec.md | plan.md plus optional design artifacts | Skip when plan.md is current | | Plan pressure | Need to challenge terminology, ADRs, docs, or domain assumptions | grill-with-docs | Draft plan and project docs | Sharpened decisions/docs | Skip when the plan is routine and grounded | | Tasks | Need executable implementation checklist | speckit-tasks | spec.md and plan.md | tasks.md | Skip when tasks.md is current and agent-runnable | | Requirements checks | Need requirement-quality checklist | speckit-checklist | Active feature artifacts | Checklist under feature artifacts | Optional; skip for small low-risk changes | | Artifact audit | Need cross-artifact consistency before goal or implementation | speckit-analyze | spec.md, plan.md, tasks.md | Non-destructive consistency report | Skip when artifacts are tiny and obviously aligned | | GitHub issues | User explicitly wants tasks converted to GitHub issues | speckit-taskstoissues | GitHub auth/MCP and tasks.md | GitHub issues | Never default; it has external side effects | | Goal contract | Need durable Codex /goal contract | create-goal | Clear spec.md, plan.md, tasks.md | specs//GOAL.md | Required before long /goal work | | Native upstream implementation | User explicitly wants Spec Kit native implementation instead of Merlin /goal | speckit-implement | Complete Spec Kit artifacts and approval to execute | Implementation driven by upstream tasks | Non-default; prefer create-goal -> /goal | | Autonomous execution | Goal exists and user wants Codex to work until done | /goal | Current GOAL.md | Implemented tasks and verification | Do not launch from loose chat summary | | Test-first build | Building a feature or normal bug fix with tests | tdd | Spec Kit work: GOAL.md plus tasks.md; small non-Spec-Kit fix: clear behavior target | Tested implementation | Skip for read-only review/analysis | | Hard diagnosis | Broken behavior, flaky test, unknown failure, performance regression | diagnose | Repro target or failing signal | Root cause, fix, regression test | Route back to tdd for implementation if needed | | QA gate | Implementation exists and needs proof or fixes before ship | gstack-qa | Active spec/goal and runnable app/checks | QA report, tests, browser evidence, in-scope fixes | Required before ship for web work | | Browser proof | Need live browser interaction, screenshots, or Playwright tests | playwright-cli | URL/dev server or browser target | Browser proof and optional generated tests | Use before ship when UI/user flow changed | | Custom browser automation | Browser workflow needs loops, login setup, screenshots, or reusable logic | playwright-skill | URL/dev server and scenario | Custom Playwright script/evidence | Use only when CLI steps are not enough | | Ship | Ready to commit, push, PR, tag, release, merge, or deploy | gstack-ship | QA evidence and explicit ship intent | Shipped artifact/PR/release/deploy | Do not use before implementation and QA evidence |

/goal Gate

Before /goal, require:

1. A Spec Kit feature directory or explicit user approval to create one.
2. No unresolved [NEEDS CLARIFICATION] markers in spec.md.
3. plan.md names the technical approach and checks.
4. tasks.md is executable by an agent.
5. create-goal has produced or refreshed GOAL.md.

If these are not true, route to the missing step instead of launching /goal.

Skill Cards

merlin-skills-routing

Use before non-trivial implementation work and always before /goal. Requires the newest user request and current repo state. Produces the next phase decision. Do not use as a long planning ceremony.

install-merlin-skills

Use when installing, updating, or vendoring this pack into Codex, Claude, or a project-local skill root. Requires a target root or clear default. Produces installed skills and optional AGENTS.md/CLAUDE.md block. Do not use for feature work.

speckit-cli

Use when installing or running the official specify CLI, initializing .specify/, or managing Spec Kit integrations/extensions/presets. Requires permission to mutate project setup. Produces the Spec Kit project infrastructure. Do not use for writing an already-initialized feature spec.

brainstorming

Use when the product direction, UX, or feature shape is still ambiguous. Requires user intent and repo context. Produces an approved design direction. Do not use when the requested behavior is already concrete.

to-prd

Use when existing conversation context should become product requirements or an issue. Requires enough context to synthesize without interviewing. Produces a PRD-style requirement. Do not use when speckit-specify is the better source-of-truth path.

zoom-out

Use when the code area is unfamiliar and the agent needs a map before edits. Requires a topic or area. Produces module/context orientation. Do not use as a substitute for implementation.

speckit-constitution

Use to create or refresh .specify/memory/constitution.md. Requires initialized Spec Kit infrastructure. Produces project principles for later specs and plans.

speckit-specify

Use to create or update specs//spec.md from natural-language requirements. Requires .specify/ and a feature description. Produces the feature spec.

speckit-clarify

Use before planning when requirements are underspecified. Requires a feature spec. Produces recorded clarifications. Do not skip if [NEEDS CLARIFICATION] remains.

speckit-plan

Use to create the technical plan and optional design artifacts. Requires a clarified spec. Produces plan.md, plus optional research.md, data-model.md, contracts/, and quickstart.md.

grill-with-docs

Use to pressure-test a plan against project docs, domain language, and ADRs. Requires a draft plan and docs. Produces sharper decisions. Do not use when no meaningful decision is open.

speckit-tasks

Use to convert spec and plan into executable work. Requires current spec.md and plan.md. Produces tasks.md.

speckit-checklist

Use to generate requirement-quality checklists. Requires active feature artifacts. Produces checklist files. Optional for small changes.

speckit-analyze

Use after tasks to check consistency across spec, plan, and tasks. Requires all three artifacts. Produces a non-destructive analysis. Prefer it before create-goal on non-trivial work.

speckit-taskstoissues

Use only when the user explicitly wants GitHub issues from tasks.md. Requires GitHub capability and approval for external side effects. Produces issues.

create-goal

Use to generate GOAL.md from Spec Kit artifacts. Requires clear spec.md, plan.md, and tasks.md. Produces a durable /goal contract. Do not start implementation from this skill.

speckit-implement

Use only when the user explicitly wants upstream Spec Kit native implementation. Requires complete artifacts and approval to execute. Produces implementation directly from tasks.md. Merlin's default is create-goal -> /goal instead.

tdd

Use for feature work and normal bug fixes where tests can drive the change. For Spec Kit work, use it after tasks.md and GOAL.md exist and /goal is executing a concrete implementation slice. For small non-Spec-Kit fixes, a clear behavior target is enough. Produces tested code.

diagnose

Use for hard bugs, unknown failures, flaky tests, or performance regressions. Requires a repro or failing signal. Produces root cause, fix direction, and regression coverage.

gstack-qa

Use after implementation or before ship. Requires active spec/goal and runnable checks. Produces QA evidence and in-scope fixes.

playwright-cli

Use for token-efficient browser interaction, screenshots, and Playwright test workflow. Requires a URL or browser target. Produces browser proof.

playwright-skill

Use when browser proof needs custom scripting or repeatable automation. Requires a scenario. Produces a Playwright script and evidence.

gstack-ship

Use when implementation and QA evidence are ready and the user asks to package, commit, push, PR, tag, release, merge, or deploy. Requires explicit ship intent.

Skill-First Rules

• Load only the next required skill file.
• Prefer Spec Kit artifacts over chat memory for feature truth.
• Prefer tests, browser proof, and QA reports over confidence.
• Keep generated proof next to the feature or in the repo's existing evidence location.
• Keep gstack limited to gstack-qa and gstack-ship unless the source-selection policy is intentionally changed.
• Keep upstream-generated speckit-* skills close to GitHub Spec Kit. Merlin-owned adaptations are speckit-cli, create-goal, gstack-qa, and gstack-ship.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: merllinsbeard
• Source: merllinsbeard/merlin-skills
• License: MIT

Install and usage instructions live in the source repository linked above.