Multi-Phase Skills Framework
A set of Claude Code skills that take a piece of work through distinct phases, from a rough idea to tested code, with a clear handoff artifact at each step. Each phase is small and does one thing, so you can start anywhere in the chain and stop when you have what you need. One skill (plan-gate) ships with a companion agent, hook, and command; everything else is a plain skill directory.
Source: docs/framework-flows.drawio (editable in draw.io).
The phase chain
The skills are designed to run in this order, but each is usable on its own.
- capture-brainstorming — turn an exploratory thinking session into a
BRAINSTORM.md handoff log. Runs as a full capture (mines the conversation plus past session transcripts) or as a cheap checkpoint you can repeat during a long session. Surfaces deferred action items and hands them to todo.
- analyst — interview the user and the codebase, then write
REQUIREMENTS.md (the problem space: WHAT and WHY, not HOW). Warm-starts from BRAINSTORM.md when one exists.
- architect — read
REQUIREMENTS.md, decide the design with the user, write SPEC.md plus an architecture.drawio, then slice the work via prd-to-issues.
- prd-to-issues — break a plan or spec into independently-grabbable, tracer-bullet vertical slices as issues on the project tracker. First slice is always a walking skeleton.
- tdd — implement each issue with the red-green-refactor loop, one vertical slice at a time. Hands the branch off for review and a PR per your team's process.
Supporting skills used across the chain:
- write-a-prd — lightweight single-feature alternative to the
analyst then architect pass: one interview, one PRD, filed as one issue. Based on the Matt Pocock skills set.
- grill-me — adversarial interview to stress-test a plan, design, or doc before committing to it. Based on the grill-me skill by Matt Pocock.
- plan-gate — pre-execution checkpoint on an approved plan (for example one you just approved in Claude Code's plan mode): surface every weak spot and drive each one to fixed or explicitly accepted with the user, one at a time, before any code is written. Spawns the bundled
plan-auditor agent for the read-only audit; an optional hook fires the gate automatically the moment you leave plan mode. Use grill-me to stress-test an early idea; plan-gate is for a plan that is already approved.
/pause-after-planning: optional command for anyone who plans and builds on different models. Run it during a planning session and it arms a stop, so Claude finishes planning and the gate, then hands off and waits for you to switch the model instead of rolling straight into implementation. See Model routing.- build-a-poc: decide during planning whether a throwaway prototype is worth building, then build one that answers one to three written questions and nothing more. It picks the cheapest medium that answers them, from asking the owner up to a tracer bullet in the real stack, and ends by listing what the prototype could not validate, so each item becomes a conformance check in the real plan.
plan-auditor and the plan-gate hook point to it.
- init-project — seed a project
CLAUDE.md for a data/automation project from its description and files.
- plan-status-sheet: keep a project's plan status in one Google Sheet with a link that never changes. It checks that every numbered plan section has a row or a written reason, that every date is a real past date, and that the shared columns are intact, then rewrites the Sheet and reads it back.
--check runs offline; pushing needs your own Google OAuth client, set up once as its SKILL.md describes.
- todo — persistent per-project
TODO.md with a cross-project index. Other skills hand deferred work to it.
- save-context — end-of-session save into the project
CLAUDE.md and memory.
- close-session — save-context plus teardown of resources this session started.
A start-of-session briefing is available separately as the /new-session command in the companion commands pack; it is not bundled here.
Install
On Windows: install Git for Windows, so Claude Code runs these scripts in Git Bash. Where a command here says python3 and your PC has only python, use python. In WSL, follow the Linux steps.
Each subdirectory here is a self-contained skill (a SKILL.md plus any helper files). To use them, copy or symlink the skill directories into your ~/.claude/skills/ so Claude Code picks them up:
# Copy only the skill directories (those containing a SKILL.md),
# skipping docs/ and the repo's own README/LICENSE/NOTICE.
for d in multi-phase-skills-framework/*/; do
[ -f "$d/SKILL.md" ] && cp -R "$d" ~/.claude/skills/
done
tdd, todo and plan-status-sheet ship with companion files next to their SKILL.md (reference notes and helper scripts); keep each skill's directory intact when you copy it.
plan-gate companions (agent, hook, command)
plan-gate is a four-part system, and only the first part is required. The skill directory installs like the others; its companions live outside it:
# The plan-auditor agent (plan-gate spawns it for the read-only plan audit)
mkdir -p ~/.claude/agents ~/.claude/hooks ~/.claude/commands
cp multi-phase-skills-framework/agents/plan-auditor.md ~/.claude/agents/
# Optional: the hook that reminds Claude to run the gate whenever a plan is approved
cp multi-phase-skills-framework/hooks/plan-gate-reminder.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/plan-gate-reminder.sh
# Optional: the command that stops after the gate so you can switch models
cp multi-phase-skills-framework/commands/pause-after-planning.md ~/.claude/commands/
To wire the hook, add this entry to ~/.claude/settings.json under hooks (merge with any existing PostToolUse list):
{
"hooks": {
"PostToolUse": [
{
"matcher": "ExitPlanMode",
"hooks": [
{ "type": "command", "command": "$HOME/.claude/hooks/plan-gate-reminder.sh" }
]
}
]
}
}
The hook is optional and non-blocking: without it, plan-gate still runs whenever you ask for it ("gate this plan"); with it, Claude is reminded to run the gate the moment a plan is approved, before the first change is made. Without the agent, the skill falls back to doing the audit inline, so install the agent to keep the heavy plan-vs-codebase reading out of your main context. The command is only useful if you plan and build on different models; skip it otherwise.
The persistence skills (capture-brainstorming, analyst, todo, save-context, close-session) assume the standard Claude Code layout: a per-project data dir at ~/.claude/projects/<X>/ and a memory index under the dash-encoded home path (e.g. -Users-jdoe for /Users/jdoe). They derive that path from $HOME, so they work on any machine without editing.
Development-flow rules (optional)
rules/ holds short standing rules for how Claude should work during development. Each file is one topic:
testing-and-review.md: what makes a test real, checks that cannot fail, when to run heavier proof, how to treat reviewsfind-the-rule.md: when each fix contains the next bug, stop and find the one rule behind all of themmeasure-a-new-guard.md: run a new check over what is already live before it shipsvalidate-before-you-build.md: when to build a throwaway proof of concept firstconsult-the-documented-source.md: read where a credential or tool is documented before reporting it missingmodel-routing.md: which model tier plans, builds and does routine workrelease-workflow.md: the two-stage ship flow (needs the claude-release-workflow pack)improve-dev-workflow.md: when something slips past the harness, improve the development workflow in the same session (needs the claude-maintenance-skills pack)
Copy the ones you want into your rules folder:
mkdir -p ~/.claude/rules
cp multi-phase-skills-framework/rules/*.md ~/.claude/rules/
Claude Code loads every .md file in ~/.claude/rules/ at the start of each session, in every project, so each file you copy is read on every session. Copy only the ones you want applied everywhere.
Dependencies and companions (not bundled)
These skills reference a few things this framework does not include. None are required to use the core chain; they are points where the framework hands off to your own tooling.
- Review and pull-request / checkpoint step after
tdd. The framework deliberately does not prescribe a review or PR tool. When tests are green, tdd tells you to hand the branch off for review and open a PR per your team's process. Plug in whatever you use (a code-review skill, your CI, a manual review).
- OpenSpec (optional,
architect Path A). architect defaults to slicing straight into issues via prd-to-issues (Path B). It can instead scaffold an OpenSpec change if your repo already uses OpenSpec, which is a separately installed tool (npm install -g @fission-ai/openspec). Skip it unless your team has standardized on it.
- draw.io tooling (optional,
architect deliverable 2). architect asks for an architecture.drawio next to SPEC.md and leaves how you produce it up to you. The draw-diagram skill in the drawio-diagram-skill pack covers that part: a visual grammar to author against, plus a validator and renderer so the diagram gets looked at before it is called done. Any other draw.io workflow does the job equally well.
- Commands and skills from the sibling packs (optional). A few skills mention a command that ships elsewhere:
/instruct and /new-session in claude-commands, /split-claude-md in claude-maintenance-skills, and /pr-checkpoint and /release in claude-release-workflow. Each mention is a pointer, not a requirement; without the other pack the step is skipped.
/improve-dev-workflow (optional, save-context step 7). At the end of a session, save-context (and so close-session) checks whether something reached you or a reviewer that a skill, hook, agent or rule should have caught. When it did, it asks once whether to improve the development workflow now, and runs /improve-dev-workflow from claude-maintenance-skills on a yes. Without that pack, the answer is filed as an open action item instead.
Docs
- docs/AUTHORING-GUIDE.md — how to author and package Claude Code commands, skills, and agents (the method behind this framework, reusable for building your own packs).
- docs/framework-flows.png — the phase chain as a diagram (source:
docs/framework-flows.drawio).
Conventions baked in
- Every phase produces one named artifact (
BRAINSTORM.md, REQUIREMENTS.md, SPEC.md, issues, code) so the next phase starts warm instead of cold.
- Requirements and decisions carry stable IDs (FR-N, NFR-X-N, D-N) so issues, tests, and later review can all anchor to them.
- Writing follows plain-prose conventions: no em dashes, no marketing adjectives, no Unicode box-drawing characters in tables (markdown pipe tables are fine).
Credits
Several skills here are based on Matt Pocock's open-source skills set (https://github.com/mattpocock/skills): tdd, prd-to-issues (his to-issues), write-a-prd, and grill-me. To install his full upstream set and its per-repo config, run /setup-matt-pocock-skills from that repo. analyst and architect are original to this framework, they add the explicit requirements and design phases his set does not include. The plan-gate system (skill, plan-auditor agent, and reminder hook) is also original.
License
MIT. See LICENSE and NOTICE. The skills derived from Matt Pocock's set are used under its MIT License, with his copyright retained.
Model routing
The skills and the plan-auditor agent in this pack pin a Claude Code model alias in their frontmatter, so each artifact runs on the tier its work needs:
model: inherit: planning and judgment-heavy review. These run on your session model, so start a planning or review session on your strongest model (switch with /model).model: opus: execution and content workmodel: sonnet: routine or mechanical steps
If a pinned model is not available on your plan, or you prefer different routing, edit the model: line in the artifact's frontmatter, or delete it to inherit your session model.
Switching models partway through one piece of work
A pin only lasts the turn that invoked the artifact, so a long implementation session needs an explicit /model switch. Two things make that switch land in the right place:
- The boundary is implementation, not plan approval. Planning, evidence-gathering, audits, and strategy brainstorming are all analysis and belong on the planning model. The switch to a cheaper model belongs at the first repo or code edit. Approving a plan is not itself the boundary, and a plan whose early phases are research or audit should still run those on the planning model.
/pause-after-planning enforces it. It arms a stop after the gate so the session hands off (gate tally, plan file, resume point) and waits for you to switch, rather than rolling into implementation on whatever model was planning. When the plan has analysis phases after the gate, it stops twice: once to confirm those run on the planning model, again at the first code edit.
That command deliberately carries no model: pin, unlike every other artifact here. A pin takes effect on the turn that invokes it, which would switch the model in the middle of the planning session the command exists to protect. Leave it unpinned if you audit this pack for routing consistency.
