Skills (slash commands)
The big picture: A skill is a packaged workflow you start by typing /name in Claude
Code. Blueprint ships 21 of them, covering a project’s whole life: setup, planning,
building, releasing, and keeping the process itself healthy.
Why it matters: Each skill turns a multi-step chore you’d otherwise explain from scratch every time (“check the branch, write a description, link the issue, open the MR…”) into one command that does it the same way every time.
The lifecycle page puts these skills in order.
How to read this page:
- ⛔ means you have to type it — Claude can’t start it on its own, because it touches GitLab, git history, or your budget.
- Each entry has What it does, Why it matters, Use it when, and two fixed
lines: Before this: (what should be done first) and Next: (what normally
follows). The full instructions live in
.claude/skills/<name>/SKILL.md. - A check (
make check-commands-doc) fails when a skill has no entry here or an entry lacks either line, so a new skill cannot ship undocumented. - New to the terms? See the Glossary.
At a glance
Section titled “At a glance”| Stage | Skills |
|---|---|
| Set up | /kickoff ⛔ · /spec ⛔ · /import-design |
| Plan | /dotplanning ⛔ · /voc · /adr · /sunset-check |
| Build and ship a change | /conventions-review · /mr ⛔ · /ci-debug · /fix-mr ⛔ · /wave ⛔ |
| Release | /pre-release · /mass-merge ⛔ · /release ⛔ |
| Keep the process healthy | /next · /kaizen · /voc-audit ⛔ · /incident-postmortem · /tracker-hygiene · /memory-audit ⛔ |
Set up a project
Section titled “Set up a project”/kickoff ⛔
Section titled “/kickoff ⛔”What it does: Asks what you’re building, who uses it, your stack and what version
one must do in one message, then up to four multiple-choice rounds with sourced defaults
(plus a short repository-layout follow-up on GitLab: a personal namespace with one repo, or a group with several; and, for Open core only, a follow-up for the enterprise package names that writes edition-boundary.conf):
persona context (device, accessibility, locale, privacy), forge and license (optionally also mirrored to GitHub), public API
contract, CI includes and add-ins, test and docs paths, branching variant, fast-path rows,
version callouts, and the commitment label for seed issues. It writes AGENTS.md,
CLAUDE.md, .claude/personas.md, the Makefile, the CI includes, CONTRIBUTING.md,
LICENSE (with its copyright line), CODEOWNERS, SECURITY.md (public repos) and README.md. On GitLab it then runs scripts/gitlab-bootstrap.sh after one
preview and confirmation: it creates the project if missing, applies the recommended
merge-request settings, protects main and v* tags, creates the labels, writes
MERGE_METHOD, and creates the seed issues without duplicating any on a retry. It reports
what it assumed and what it did not touch. It never commits; the first push of main is
asked separately.
With a product spec in docs/specs/: it reads the spec first (asking which one when
there are several, and offering git add -N for one git does not know about yet), prefills
the first message from it, and Round 3’s project path when the spec has a valid
GitLab project path section, with each value’s section and line for you to confirm or
correct, and on GitLab by default creates no seed issues, naming /spec import <path> as the next
step instead (/spec <path> first while the spec is a draft). On GitHub it still creates
them. See Start a project, step 4.
Why it matters: Everything downstream reads these answers. The review agents check
against your stack, /voc role-plays your personas, and the first issues give you a
backlog on day one. Ten minutes here saves re-explaining the project in every session.
Use it when: once, right after cloning. See Start a project, step 4.
Before this: a clone of the template with make setup run. This is the first step (Configure); nothing else comes before it.
Next: /spec to write the product spec (Specify), or make customize to see what is still unconfigured. Then /dotplanning <version> for the first milestone.
/spec ⛔
Section titled “/spec ⛔”What it does: Runs a product spec’s whole lifecycle in docs/specs/. Bare /spec
reads the spec’s status and does the next step: with no spec it starts new; a
draft is resumed or audited; a ready spec gets the import plan and waits for your
explicit yes; an imported spec is revised. Its verbs:
/spec new <slug> [--from <path>] # staged interview into docs/specs/<slug>.md/spec docs/specs/x.md # audit until the completeness gate passes/spec revise docs/specs/x.md # the next version/spec lint [docs/specs/x.md] [--fix] [--json]/spec import docs/specs/x.md [--dry-run] [--allow-incomplete "<reason>"]newasks the template’s sections one stage at a time, each question with a default that names its source (AGENTS.md,.claude/personas.md, the gate’s derivation line, or “spec says nothing”). It first asks whether this is a product, an internal tool or a feature-sized spec, and writes the file after every stage with a<!-- TODO(spec): <stage> -->marker on anything pending, so rerunning/spec new <slug>resumes at the first incomplete stage. A choice you call “probably” or “leaning X” becomes aD-nndecision, never “Decided”. A “reuse X from repo Y” claim is checked against that repo first: confirmed claims get a<!-- verified: … -->marker, claims it cannot find are put back to you, and claims it cannot check are tagged[UNVERIFIED]with an open question; such a spec staysdraftuntil the claim is verified or dropped.--from <path>pre-fills stages from a document you already have, read as data and offered as proposals you confirm. A threshold you have not confirmed is written(proposed; confirm at /dotplanning).- The audit (
/spec <path>) runs the completeness gate, prints its derivation lines verbatim, asks only what each gap needs, rewrites the file and re-runs the gate, for at most three loops. It runs the read-onlyspec-reviewagent at most twice, and only once the gate passes. A question you skip becomes an Open-questions row owned by[unassigned]; nothing is invented. It setsstatus: readyonly on your explicit yes. reviselints first, asks what changes, bumpsversion(minor by default), setssupersedes:andstatus: draft, and keeps aChanges in v<new>table. Ids are never renumbered: a removed item is marked(withdrawn in v<new>). A decision settled during the revise is suggested for/adr.lintrunsscripts/check-spec-completeness.pyand prints its output verbatim.importruns the gate first and refuses a spec that isFAIL,INCOMPLETEor stillstatus: draft, printing the gate’s derivation and creating nothing; a file with no front matter is not a spec and is pointed at/spec new.--allow-incomplete "<reason>"proceeds past a refusal and writesOverride: <reason>into every issue it creates (an empty reason is rejected). It reads features, phases and acceptance criteria from the gate’s parse, shows a confirmation table, then creates one milestone per phase (reusing one with the same title) and one issue per feature, each with aSpec:/Spec-version:trace, the criteria copied verbatim, andDepends on:resolved to issue numbers where it can. A feature in thebacklogphase gets an issue with no milestone; a withdrawn feature is reported, never closed. It asks once which commitment label (committed,uncommitted, …) to apply, with “leave unlabeled” as an option (when a feature is blocked by a spec decision that is still undecided, the question names the decision and offerscommittedwith or without those features), and checks open issues for the same title before each creation. It then writesIssue: #Nbeside each feature, setsstatus: importedandimported-version:.--dry-runprints the plan table and stops: no milestone, label or issue is created or updated and the spec is not written.
It never commits or pushes. /spec is user-only because import creates issues.
/spec-intake and /import-spec still work as deprecated aliases (they print a notice
and run the same procedure) until they are removed after the next minor release.
Why it matters: A spec that fails the gate cannot become issues, and a spec in a
document can’t be worked; issues can. Every mechanism in Blueprint — branch names, the
duplicate-work gate, Closes #N — keys off an issue number, and the trace lets you go
from an issue back to the spec feature that asked for it. One skill means one schema and
one gate, and a spec’s later versions reach the issues that track it.
Re-import: a feature that already has Issue: #N creates nothing, and a spec that
gained a feature creates exactly one issue, even when the gate also reports warnings.
After a revise, each stamped issue whose body carries this spec’s exact Spec: line is
compared with the spec: you see the diff (title, criteria, Spec-version:) and say yes
or no per issue. Ticked criteria whose text is unchanged stay ticked, new ones are added
unticked, and removed ones are shown before they are dropped. See docs/specs/README.md.
An --allow-incomplete run also writes an override: "<reason>" front matter line and
changes status only when the final gate verdict is exit 0.
Use it when: you are starting a product-area spec, have a draft and want it ready,
have a ready spec and an empty tracker, or need the next version of an imported spec.
With a spec in docs/specs/ at kickoff on GitLab, /kickoff creates no seed issues by default, so
import is the path to the tracker; skip it only if you chose seed issues at kickoff and
they already cover the spec’s features (pick one source: step 9). The rule table is in
docs/specs/README.md.
Before this: Configure: /kickoff has run. /spec import requires it (the check ships in 0.8).
Next: /spec import once the spec is ready, then /dotplanning <version> (Plan) for the milestone it created.
/import-design
Section titled “/import-design”What it does: Turns a design guide, brand guidelines, or a design-token export into
.claude/rules/frontend.md.
Why it matters: Without it, ux-design and ux-review can only give generic advice.
With it, they check against your colors, components, and spacing.
Use it when: your project has a UI and a design system, before the first UI feature.
Before this: /kickoff has run and you have a design guide or token export. It is optional.
Next: Build UI features against the rules it wrote; /dotplanning <version> if the milestone is not planned yet.
Plan the work
Section titled “Plan the work”/dotplanning ⛔
Section titled “/dotplanning ⛔”What it does: Plans one release milestone before any code is written. It:
- asks twelve kickoff questions that decide the release’s shape (theme, date vs. scope, capacity, how many slots to hold for real-user reports, freeze date, cut line);
- maps every feature to the screens, endpoints, models, and docs it needs, and flags anything with no issue or design behind it;
- orders the work into workstreams and names each one’s review chain;
- proposes a
committed/uncommittedlabel (orrelease::committed/reserve/stretchwith dated milestones) for every issue and fits the committed set to your stated capacity — asking you, never guessing; - reads the decisions table of any spec your issues cite (
Spec:lines) and flags a feature whose blocking decision has no ADR yet, so it is never proposed as committed without you choosing to decide now, accept the risk, or defer; - records the plan on a
Plan: <version>issue (created or reused by title, linked from the milestone description, updated after each kickoff question asstatus: draftand set toreadyat the end), so a teammate ormake statuscan see it (ships in 0.8); - writes a self-contained HTML report to
~/Downloads, generated from the same data.
Why it matters: Most late releases were late on day one — a missing screen, an undecided question, or more committed work than the team can do. This finds those while they’re still cheap to fix.
Use it when: once per milestone, before the first feature branch. Re-run only if the
scope changes materially. It’s the begin-gate; /pre-release is the end-gate.
Before this: Specify: a ready spec (/spec), or an explicit “no spec for this milestone”. The check ships in 0.8.
Next: /wave <version> to build the committed issues (Build).
What it does: Runs a Voice of the Customer panel. It first looks for real evidence (your tracker, then public discussion of this kind of product) and records how strong that evidence is. Then each of your personas reviews the proposed feature, and it reports adoption blockers, usability worries, and priority mismatches.
Why it matters: It surfaces the “who is this actually for?” questions before anyone designs anything — the cheapest moment to change course.
Yes, but: it is a simulation, not user research. Never present its output as customer feedback; a real user report always outranks it.
Use it when: before architect, when the change’s row in the fast-paths table includes /voc. Run it as
/voc all <feature> or /voc <persona-name> <feature>. For a product area with its own
users, /voc --spec docs/specs/<slug>.md all <feature> runs the panel on the personas in
that spec’s Users table instead of .claude/personas.md; the report header lists them by
name and the banner names the spec as the source. A spec is refused rather than given a thin
panel when it has fewer than 3 personas, a persona without a goal or frustration, placeholder
personas, or a Users section that is missing; the gate’s S-02/S-03/S-04 line is printed verbatim.
Before this: a proposed change whose fast-paths row includes /voc and, ideally, the milestone plan from /dotplanning.
Next: Hand the blockers and their falsification lines (never the score) to architect, then ux-design. From 0.8 the skill also posts them, once you confirm, as one comment on the feature’s issue headed as a simulated persona panel, so /voc-audit --calibrate can score them later (ships in 0.8).
What it does: Creates a numbered Architecture Decision Record in docs/adr/ using the
classic Context / Decision / Consequences template.
Why it matters: Six months from now, “why did we pick this database?” has a one-page answer instead of an archaeology project. The skill also carries two rules that bite later:
Acceptedmeans the decision was made, not that it shipped — say so in anImplementation statusblockquote.- When an ADR is accepted, re-read the open issues that cite it. They were written before
the decision and may still argue for an option it rejected
(
scripts/adr-accepted-issue-sweep.pyfinds them, and also issues citing a specD-nn, once the spec’s ADR cell names this ADR).
Use it when: you make a choice that would be expensive to reverse — stack, data storage, auth approach.
Before this: a decision worth recording, usually the architect output or a blocking question from /dotplanning.
Next: Link the ADR from the issues that cite it and re-read them; then continue implementing.
/sunset-check
Section titled “/sunset-check”What it does: Asks each persona the opposite of /voc: “this is gone next release —
what breaks for you?” It first verifies what the feature really does in the code (not
what its docs claim), then recommends one of four verbs: remove, fix, narrow,
or demote.
Why it matters: Every feature costs maintenance forever. Without a disciplined way to ask whether something should still exist, half-built and oversold features pile up.
Use it when: a feature is half-finished, rarely used, or costing more than it returns.
Before this: a surface you are considering removing, fixing, narrowing, or demoting.
Next: Take the decision issue into /dotplanning for the next milestone. From 0.8 the skill records its recommendation and falsification lines on that issue (or files a Sunset check: <surface> issue) once you confirm, and files keep-and-fix gaps as it confirms each one (ships in 0.8).
Build and ship a change
Section titled “Build and ship a change”/conventions-review
Section titled “/conventions-review”What it does: A general code review of one file or the whole branch diff: correctness, conventions, consistency, testing gaps, and documentation gaps.
Why it matters: The specialist agents each look for one kind of problem. /conventions-review is
the generalist pass that catches what falls between them.
Renamed from /review: /review is the alias of Claude Code’s bundled
/code-review. A project skill never
replaces a bundled alias (skills docs,
checked: 2026-10-15), so /review always ran the built-in and this skill was
unreachable by that command. Type /conventions-review for this skill and
/code-review for the bundled correctness review.
Use it when: any time before /mr, especially on a change no specialist agent covers.
Before this: changes committed (or at least staged) on a feature branch.
Next: Fix what it found, then /mr.
What it does: Opens a merge request for the current branch. First it checks that the
branch is clean, a changelog fragment exists, and no other MR already covers the issue.
Then it writes a structured description — summary, a Requirements table, test plan,
the Gates ledger, and Closes #N. Before creating the MR it renders a verification
verdict from those sections (scripts/mr-verdict.py): it stops on FAIL, shows the reasons
for INCOMPLETE, and prints the full verdict in its report. Then it creates the MR with
glab.
Why it matters: The MR description is the permanent record of what changed and which
reviews ran. Writing it the same way every time is what lets /kaizen later measure which
reviews actually find problems.
Use it when: your branch is committed and its gates have run. It never merges — you do that on a green pipeline.
Before this: the branch is committed, its gates have run, and make pre-push-checks is green.
It asks scripts/cost-ledger enabled before writing any measured cost line: with the cost
ledger off it writes cost-ledger: off instead and the ledger reads no transcript
(the gates ledger). With it on,
scripts/cost-table.py --comment renders the ## Cost of this MR comment, which the PostToolUse hook post-mr-cost.py posts after glab mr create, split by Sonnet and Opus, the only readable cost table; later work on the MR (a fix round, /fix-mr) posts a numbered record with a running total.
Next: A person reviews and merges. If the pipeline is red or conflicts, /ci-debug then /fix-mr; once several are green, /mass-merge.
/ci-debug
Section titled “/ci-debug”What it does: Pulls the logs of every failed job in a pipeline (in parallel), identifies the root cause, and prescribes a specific fix — file and change — without applying it.
Why it matters: Retrying a red pipeline and hoping it turns green wastes time and hides real bugs. Reading the log first is the rule; this does the reading for you.
Use it when: a pipeline fails and you want a diagnosis before anyone touches code.
Before this: a pipeline has failed and you have its ID or MR number.
Next: Apply the fix it prescribes and push, or hand the MR to /fix-mr to drive it to green.
/fix-mr ⛔
Section titled “/fix-mr ⛔”What it does: Gets a blocked MR to green and mergeable. It checks both the
pipeline and whether the MR conflicts with main, resolves conflicts, diagnoses failures,
fixes, commits, pushes, and re-checks — at most three rounds. It reads the failing log
itself and picks the cheapest check that can vouch for the fix (a rerun, mechanical
checks on a conflict resolution, or one narrow fresh-agent re-check for a code fix),
so an agent runs only when the cheap checks cannot answer. It never merges.
Why it matters: “Pipeline green” isn’t “ready.” An MR can pass CI and still conflict
with main. Checking both stops the “but it was green!” surprise.
Use it when: an MR is red or shows a merge conflict. Pass several MR numbers to work through them one at a time.
Before this: an open MR that is red or conflicting.
Next: A person merges it; with several green MRs, /mass-merge.
/wave ⛔
Section titled “/wave ⛔”The step-by-step walkthrough, with worked examples, is the guide Start work with /wave. This entry is the reference.
What it does: Lands several milestone issues in parallel. It asks which milestone and
labels to pull from (never guesses), then gives each issue its own worktree and its own
agent. It skips issues already checked out (the status::wip label), and checks out each
one it starts (scripts/wt claim; scripts/wt new on a --harness run), so a second wave
or session cannot grab the same issue. Each pinned worker runs in a Claude Code isolated
worktree with a fixed tool allowlist; the orchestrator pushes its branch and opens the MR
(ADR 0010):
- Before it picks new work,
scripts/wave-resume.pylists the claims you hold and classifies each leftover: no commits, committed not pushed, pushed with no MR, MR open with a red pipeline, or MR open and green. For each it offers resume, hand back, or release the claim; the script only reads, and the orchestrator acts on the answer. It never re-spawns an agent on an issue whose MR is open and green. A worktree whose agent is live or unknown, that holds uncommitted changes, or whose branch is behind origin or has an unsafe name is only ever handed back. It also looks at the issue’s other branches and MRs: an open MR on another branch is never respawned over, and another branch ahead of main blocks release. A claim with no local worktree is classified from the remote branch and the issue’s related MRs (an open MR on any branch counts; a merged one must be this project’s MR from the issue’s own branch); its liveness is unknown, so it is handed back unless the MR merged: resuming a claim from another machine is hand-back-only by design, and taking it over (wt releasethenwt claim) is the user’s own step. The orchestrator posts a one-line progress comment on every issue the wave touches, so a wave can resume from another machine. The resumed worker still runs in an isolated worktree, not acd(ships in 0.8). - Before any worktree exists,
scripts/wave-preflight.pychecks every candidate and reportsopen,done on main (<sha or MR>), orremaining: <what>. Onlyopenissues get an agent; an issue that merged already, is in flight, or needs only an owner decision is reported instead. An issue whose code landed but that still has unchecked items readsremaining: ... - landed: !N, not done.done on mainis evidence, not proof: the orchestrator confirms before asking to close an issue, and the owner-decision check reads only unchecked checkboxes and the title, not comments (ships in 0.8). - Each pinned worker implements, tests, commits, and stops. The orchestrator then runs
its pre-MR gate batch against the worktree. A
--harnessworker runs its own gates. - The orchestrator runs
completeness-checkon each branch — a fresh auditor, because an agent shouldn’t grade its own work and can’t start one itself. - Fixes land as a new commit; at most one more audit pass runs.
- A stale-base check, then the push and the MR.
- The orchestrator verifies every agent’s commits before believing its “done.”
Why it matters: Parallel agents multiply both throughput and cost. The skill’s rules come from measuring real waves, where re-reading context — not writing code — was 95.9% of the spend. So: Sonnet by default with named reasons to escalate to Opus, Fable only as a rescue you approve after Opus failed, a capped wave size (default 5), and self-contained briefs.
Choosing the model: /wave reads each issue and picks the model for that issue’s
agent, so one wave can mix models. The default is Sonnet. It escalates to Opus only when an
issue’s root cause is unknown (not met when the issue already names the candidate mechanisms and the work is to confirm which one holds), the fix spans three or more packages, it changes the
product’s core semantics, or it needs a design call the issue doesn’t settle, and it names
the reason in its report. “Important” and “security fix” are not reasons on their own.
/wave runs its read-only gates (regression-check, perf-check, security-review,
schema-check, generated-artifact-check) on Sonnet. rbac-check and completeness-check
are the exceptions: rbac-check runs on Opus, and completeness-check on Opus or Sonnet by risk tier, trials whose yield the gate ledger measures.
security-review lists model: opus in .claude/agents/ as its default, so it uses Opus
when you run it directly. /wave overrides that at spawn time by passing
model: "sonnet" on the Agent call, which takes precedence over the agent file.
Rescue on Fable, only after Opus failed (ships in 0.8): Fable costs about 2.5 times Opus, so /wave
never chooses it up front. When an escalated Opus implementer reaches its budget a second time
with no progress, or (under --harness only) a completeness-check round 2 still reports a blocker after an Opus fix
round, /wave stops and asks you: run one Fable agent (recommended, with a cost estimate), run
Opus again, or drop the issue from the wave. It never escalates on its own. A run that cannot
ask reports the issue as escalation-pending: fable. Each issue gets at most one Fable rescue
per wave, and the report adds a rescue: line per issue.
Model and effort on every agent: /wave passes both model and effort on every
agent it spawns, because an agent spawned without a model inherits the orchestrator’s
Opus. Implementers run at medium effort, or high when escalated to Opus; read-only
gates at medium; completeness-check rounds at high (its fix-diff re-check at medium), since finding what a diff leaves out is
reasoning. The selection list, the status table while the wave runs, and the final report
all show each agent’s model and effort.
Per-agent budget: every agent’s brief carries a provisional budget, in tool calls and
wall-clock minutes, for its role (implementer, read-only gate, completeness-check). An agent
that reaches it stops and reports; /wave expands it once by half and then stops it. The
numbers ship as provisional, seeded from one measured outlier rather than from the ledger, and
the budget-exceeded: ledger line (with a role split) lets scripts/gate-yield.py report how
many agents hit a budget. A gate stopped at its budget is marked budget-stopped, never
recorded as a clean count. An implementer also has a lifetime limit of 120 tool calls across
every run and resume, which the pre-tool-agent-budget.sh hook enforces (ships in 0.8; see
Hooks); /wave reads the hook’s stop marker after every implementer result
and hands the work to a fresh agent.
Keeping token use down: run your own session on Sonnet. /wave defaults the agents it
spawns to Sonnet too, so the whole wave stays cheap unless an issue earns Opus. Write
issues with a clear root cause and acceptance criteria. That is what lets /wave keep an
issue on Sonnet.
Where Opus is pinned: a few skills and agents specify Opus on purpose, because they
make judgment calls. /wave itself runs on Opus as the orchestrator, and the agents
architect, ux-design, threat-model, spec-review, security-review, rbac-check,
and completeness-check are Opus by default (/wave runs security-review on Sonnet). The model: line in a skill’s or agent’s frontmatter (.claude/skills/,
.claude/agents/) shows its choice, and the Agents page lists the
model for each agent.
Renamed from /batch: Claude Code ships a bundled /batch skill that fans one
instruction out to many agents. A project skill with the same name replaces the bundled
one (documented precedence,
checked: 2026-10-15), so Blueprint’s old /batch made the built-in unreachable
(observed on Claude Code 2.1.300), and anyone following Anthropic’s docs ran this
milestone wave instead. Since macrodream/blueprint#101 this skill is /wave and /batch is the built-in again.
scripts/check-skill-names.sh fails CI if a skill name collides with a bundled skill,
built-in command, or alias again, and scripts/check-stale-references.sh fails on a
leftover reference to this skill by its old name.
Next: /mass-merge once the MRs are green; /fix-mr first for any that are red. The
final report points to /mass-merge for landing them.
Permissions: the agents it spawns run under your session’s permission mode; nothing pins their tools or mode yet (macrodream/blueprint#118).
Yes, but: it spawns many agents and spends real money. Start with a small wave.
Use it when: you have several independent, well-understood issues in one milestone.
Before this: Plan: a /dotplanning <version> record for <version>. A free-form /wave with no milestone needs no plan. The check ships in 0.8.
Next: Review the MRs it opened, then /mass-merge to land them (Build).
Release
Section titled “Release”/pre-release
Section titled “/pre-release”What it does: A cross-cutting audit of everything since the last release tag:
security, performance, regression, and documentation. Before launching it tells you how
many agents it will start (six for full) and estimates the token cost, and it forbids
those agents from starting more. Findings come back as blocking, important, or
informational. It files each blocking finding as an issue as soon as it is confirmed. /pre-release full also posts a dated summary comment on the Plan: <version> issue (audited commit, counts, issues filed); targeted runs post nothing, so they never count as the full audit (ships in 0.8). Re-running it resumes: it reports the issues earlier runs filed and the earlier summary comments, and never refiles a finding already filed (ships in 0.8). After a full run with blocking or important findings, it proposes writing each finding’s class into the day-to-day gate that should have caught it, landed in its own MR (or a kaizen issue when no gate fits), so the next instance is caught during feature work (ships in 0.8).
Why it matters: Day-to-day reviews each see one branch. Only a whole-release view catches problems that live between changes — and anything that’s about to become a public promise.
Use it when: at feature freeze, then once more before tagging. It’s a one-time gate,
not a loop: re-running after every fix just finds new adjacent things forever. Run part of
it with /pre-release security, performance, or docs.
Before this: Build: no open committed issue left in the milestone; /pre-release full warns otherwise. The check ships in 0.8.
Next: Fix or defer the findings in separate commits, then /release <version>.
/mass-merge ⛔
Section titled “/mass-merge ⛔”What it does: Lands a batch of already-green MRs without breaking main. It stacks
them on a local integration branch, re-runs the whole-repo checks after each one, then
merges only the safe prefix one at a time — updating each MR to the latest main the same
way GitLab will merge it.
Before this: the MRs a /wave opened (or any related MRs) are green.
Why it matters: Two MRs can each pass alone and break main together — for example,
each adds a few warnings under a “maximum N warnings” limit, and together they exceed it.
This catches that before it lands.
Use it when: several related MRs are green and you want to land them in one sitting. It force-pushes and merges, so only you can start it.
Yes, but: it needs permission to run glab mr merge, and the template denies that by
default so an agent can never merge on its own. Without the permission, /mass-merge
still stacks the MRs and re-runs the checks, so it can tell you whether they conflict, but
it cannot land anything. To enable it, remove Bash(glab mr merge:*) from deny (a deny rule overrides an
allow) and allow Bash(glab mr merge:*) for your own sessions; .claude/settings.local.json
is git-ignored and a safe place for the allow rule. That is a personal decision. Don’t
commit the allow rule or the removed deny entry, because that would change the default for
the whole team.
Before this: two or more green, reviewed MRs, usually from /wave.
Next: /pre-release full once the milestone’s committed issues are all merged.
/release ⛔
Section titled “/release ⛔”What it does: Suggests the next version from the changelog (patch, minor, or major),
runs pre-flight checks, assembles the changelog, bumps every version-bearing file, and
opens a release branch. You merge that MR, then tag and publish by hand. If an earlier run
left a chore/release-<version> branch, an MR or a tag, it reports them and offers to resume
at the matching step instead of starting over (ships in 0.8).
Why it matters: Release day is when mistakes become public. A scripted, checked release runs the same steps every time — including refusing a version that’s already published.
Use it when: after /pre-release comes back clean. See Release workflow.
Before this: a /pre-release full summary on Plan: <version> dated after the last merge to main. The check ships in 0.8.
Next: Plan the next milestone with /dotplanning <next version>.
Keep the process healthy
Section titled “Keep the process healthy”These skills audit the way you work, not the code.
Ships in 0.8.
What it does: Runs scripts/blueprint-status --markdown --explain and shows where this
Blueprint project is in its lifecycle: the checklist as a table, what the current step is
for, what done looks like, and the one command to type. When the current step is interrupted (⏸), that command
resumes it. /next #<iid> runs scripts/blueprint-status --issue <iid> instead and shows where
that one issue sits: its phase, its worktree or MR, what blocks it, and the command to
continue it. Claude can start it on its own when you ask where things stand, but it never
runs the command it names.
Why it matters: Being lost is a reason to stop. /next answers “what now?” from the
project’s real state instead of from anyone’s memory.
Use it when: you have been away, you have just finished a step, or you are not sure which skill comes next.
Before this: nothing required; it works from a fresh clone.
Next: Type the command on its Type: line.
/kaizen
Section titled “/kaizen”What it does: Audits the development harness — CI, the review gates, pre-push, the MR
flow, the AGENTS.md and CLAUDE.md rules — for friction, and proposes a short, ranked list of speed
wins. It reads every MR’s gate ledger to show which reviews actually find problems. It
reports and can file tooling issues; it never edits the harness itself.
Why it matters: Process only ever grows unless something measures it. A review that
hasn’t found anything in 20 runs is costing time for nothing; /kaizen is how you notice.
From 0.8 it also reads the weekly eval runs and reports
any agent whose cases dropped, or that makes no difference against the bare model.
Use it when: every few weeks, or whenever the workflow starts to feel slow.
Before this: nothing required; run it between releases or when the process feels slow.
Next: File issues for the speed wins you accept; it never changes the harness itself.
/voc-audit ⛔
Section titled “/voc-audit ⛔”What it does: Runs the persona panel against something that has already shipped,
checks every finding against the actual code, and sorts the survivors into “file new,”
“boost priority,” or “already tracked.” --calibrate compares what the panel predicted
with what real users later reported. From 0.8 it also records, once you confirm, each
boost candidate as a comment on the tracked issue and each regression as a new issue
(labeled escaped-from::<MR iid> when the MR that introduced the regression is known), instead of leaving them in
the transcript (ships in 0.8).
Why it matters: It closes the loop on /voc: was the simulated panel right? Without
calibration, a simulation’s confidence never meets reality.
Use it when: after a user-facing feature ships, and again once real user reports arrive.
Before this: a feature, page, or flow that has already shipped.
Next: File the items it ranks as “file new” or “boost priority”; run --calibrate once real users have it. From 0.8 it also offers, once you confirm, to post each boost candidate as a comment and file each regression as an issue (ships in 0.8).
/incident-postmortem
Section titled “/incident-postmortem”What it does: Reconstructs one resolved process incident — a broken main, a check
that stayed green when it shouldn’t have, lost work — from the git and CI trail. It
separates root cause from contributing factors, asks whether an existing gate should have
caught it, and writes the lesson into memory. From 0.8 it also files each follow-up as an
issue as it finds it and posts its report on the incident issue, each once you confirm
(ships in 0.8).
Why it matters: A lesson that stays in a chat transcript changes nothing. This one lands where the next session will read it, and the follow-up work lands where a teammate can see it.
Use it when: right after an incident is resolved. (/kaizen is the periodic,
pattern-level counterpart.)
Before this: an incident has happened and its mechanical trail (logs, MRs, pipelines) is still available.
Next: Work the follow-up issues it filed; the lesson it writes into memory is kept for later sessions, and the report on the incident issue is the record a teammate reads.
/tracker-hygiene
Section titled “/tracker-hygiene”What it does: Sweeps the issue tracker for drift: an issue holding both committed and
uncommitted, likely duplicates, stale uncommitted issues, and bugs with no
escaped-from:: label, and issues accidentally closed by an MR description such as “does not close #N” (plus release:: label checks if you use dated milestones). It only reports — it never relabels or closes
anything.
Why it matters: A tracker that has drifted quietly misleads everyone planning from it. Small, frequent sweeps prevent a painful rescue triage later.
Use it when: between milestone kickoffs, as often as you like — it’s cheap.
Before this: nothing required; run it between /dotplanning kickoffs.
Next: Fix the drift it reports by hand; it never relabels or closes anything.
/memory-audit ⛔
Section titled “/memory-audit ⛔”What it does: Checks Claude Code’s saved memory for this project. It looks for files with no description (which recall can’t find), files cramming in several facts, index lines that are bare pointers, broken links, and claims about files or flags that no longer exist. It reports first and applies only the safe fixes when you confirm.
Why it matters: Memory is only useful if the right note comes back at the right time. A messy store returns the wrong notes — or none.
Use it when: at each release, or when Claude starts “remembering” things that are no longer true.
Before this: nothing required; run it when the memory index nears its size limit.
Next: Apply the repairs it ranks, then re-run the index check.
Go deeper
Section titled “Go deeper”- Skills vs. agents, and how to write your own: Agent architecture.
- Which skills and agents run for which change: Development workflow.
- The source of truth for each skill:
.claude/skills/<name>/SKILL.md. Its front matter (description:,argument-hint:,disable-model-invocation:) is what Claude Code itself reads.