blueprint
Author an implementation plan as a file, in whatever permission mode the session is already in, without entering plan mode and without implementing what it plans. Use when asked to build, write, draft, or revise a plan, design doc, or implementation strategy for work that happens later, or a living tracker for a long piece of work that spans many sessions. Every claim in the plan cites the tree or is labeled unverified, and the plan is checked before its path is reported. It never offers to start the work.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- lane
- coding
- name
- blueprint
- strictness
- standard
- description
- Author an implementation plan as a file, in whatever permission mode the session is already in, without entering plan mode and without implementing what it plans. Use when asked to build, write, draft, or revise a plan, design doc, or implementation strategy for work that happens later, or a living tracker for a long piece of work that spans many sessions. Every claim in the plan cites the tree or is labeled unverified, and the plan is checked before its path is reported. It never offers to start the work.
- allowed-tools
- Read, Grep, Glob, Bash, Write, Edit, Agent
03 SKILL.md 正文
Blueprint
Authors an implementation plan as a file, checks it, and ends there.
This is not plan mode, and it must never become plan mode. The harness plan mode is a permission state: it blocks writes, so every read, every search, and the plan itself arrives as a prompt the operator has to approve, and it exits by asking to execute. Blueprint is instructions, not a permission state, so it works unchanged in any mode the session is already in, including auto. Nothing mechanical stops the work here. The plan-only contract below is the only thing that holds, and it holds because it is followed.
Interface
| Row | Contract |
|---|---|
Invoke |
/blueprint <what to plan> | /blueprint track <what to track> | /blueprint revise <path> [what changed] |
Returns |
One markdown file in the project's plan directory, its path, and one line saying how it was checked. Nothing the plan describes is built. |
Fails |
No exit codes declared; the skill ships no script. It fails by stating a claim nothing on disk supports, by reporting a plan it did not check, or by starting the work it planned. |
Commands
| Command | Action |
|---|---|
/blueprint <what to plan> |
A plan for one change you implement once. Dated filename. |
/blueprint track <what to track> |
A living tracker for work that runs across many sessions: status block, checkboxes, resume procedure. Undated filename. |
/blueprint revise <path> [what changed] |
Edit an existing plan or tracker in place, keeping its filename. On a tracker this is the per-session update. |
When the operator typed a mode, use it. Otherwise pick track when the request describes a
module, a multi-stage build, or anything the operator says they will come back to. Don't ask
which mode; the request answers it.
The plan-only contract
- Never call
EnterPlanModeorExitPlanMode. Not to start, not to present the plan, not to hand it over. Entering plan mode reintroduces exactly the approval traffic this skill exists to avoid, andExitPlanModeasks to execute, which rule 2 forbids. - Never implement what the plan describes, in the same turn or a later one, unless the operator asks for it in a new message. Writing the plan is not consent to run it. Ticking a tracker box records work that already happened; it is never a reason to do the work.
- Never close by offering to start. "Want me to implement this?" is the offer this skill is defined against. Close with the report line and stop.
- Editing files that are not the plan file is out of scope. Reading the whole tree is
expected; writing anywhere but the plan file is not, apart from creating
plan/when the directory search below ends there. That includes the project's own state record: a tracker points at it and never edits it.
Research may run read-only commands: git log, grep, git diff. They are often the difference
between a plan that cites the code and a plan that guesses at it. Don't run commands that write,
such as a test suite that leaves caches or build output; cite the last recorded result instead,
or name the command in Verification for later.
The sourcing rule
Every factual claim about the project cites where a reader can check it: path:line, a commit,
or a read-only command they can re-run. A claim that comes from memory, an earlier conversation,
another session's notes, or a file that is no longer on disk is marked (unverified: <where it
came from>). An unverified claim may sit in the plan as context. It may not be the reason for a
step, and it may never tick a box.
This rule exists because a plan that states recollections as facts reads exactly like a plan that checked them, and the reader has no way to tell the two apart.
Resolving the plan directory
Use the first of these that gives an answer:
- A directory the operator typed. If you wrote the invocation arguments yourself, a directory you put there is your guess, not the operator's choice, and it does not skip step 2.
- Where plans already live. List the project's files (
git ls-files, or outside gitfind . -type f -not -path '*/node_modules/*' -not -path '*/.git/*') and filter withgrep -iE '(^|[/_.-])(plans?|blueprints?|roadmap)([/_.-].*)?\.md$', which matches the name in a filename or a folder. If the request is about an existing plan, write beside it. Otherwise use the directory that holds the most matches, and on a tie the one holding the most recently modified match. - The first of these that exists in the project root:
plan/ docs/plans/ .claude/plans/ notes/plans/ docs/plan/ - Create
plan/.
Don't ask which one; the order is the answer.
Filename. A plan is <slug>-<YYYY-MM-DD>.md, because it is a snapshot of one decision. A
tracker is <slug>.md with its start date inside the file, because it will be edited for months
and a date in the name says it is frozen. The slug is a short kebab-case noun phrase. Match the
date format of existing files in the directory if it differs. On revise the filename never
changes.
Workflow
- Read the record before writing anything. The project's own
CLAUDE.md, the existing plans found above,git logfor the area, and the code the plan will touch. A plan that restates the request back in headings adds nothing; its value is what the research found. - In
trackmode, find the state record. Look for a file the project already uses to record what is done: itsCLAUDE.mdor README may name one, and the same file listing filtered withgrep -iE '(^|[/_.-])(state|status|progress|tracker)([/_.-].*)?\.md$'finds the usual names, including files inside a folder such asbuild-state/. The tracker must say which file owns state. If one exists, it wins: the tracker is the work list on top of it, and where the two disagree the tracker is corrected. If none exists, the tracker says it owns state. Skipping this produces two trackers that drift apart. - Name what is uncertain, and resolve what can be resolved. Anything the code or the record answers, answer there rather than carrying it to the operator. What genuinely needs a decision goes in Open questions with the options and a recommendation, not as a blocking question, because an unanswered question does not stop the plan being written.
- Write the file. The shapes are below. Apply the sourcing rule as you write, not after.
- Check it. See below. Fix what the check finds before reporting.
- Report and stop. The path, then one line on the check: what was re-verified, what the independent read found and what was fixed, and how many claims remain unverified. See rule 3.
Take the time the subject deserves. A plan is read more often than it is written.
Checking the plan before reporting
A written file only proves the file exists. Before reporting it:
- Re-verify every citation. Re-read each
path:lineand confirm it still says what the plan claims. Re-run each cited read-only command and compare the output. A claim that fails becomes a correction or is marked unverified. - Run the project's own checker if it has one for citations or links in docs, named in its
CLAUDE.md, README, or package scripts. - Get one independent read. Spawn one fresh agent with the plan's path and this instruction: check each factual claim against its citation, and return every claim the evidence does not support, every step resting on an unverified claim, and every ticked box without evidence. The session that wrote the plan cannot grade it. If spawning is unavailable, say so in the report line; do not replace it with a self-review and call it a check.
On revise, check what changed plus every box ticked in this session.
Plan shape
For /blueprint <what to plan>. Sections in order; drop any that would be empty rather than
filling it with restatement.
| Section | Holds |
|---|---|
| Title + date | What this plans, and when it was written |
| Problem | What is actually wrong or missing now, with path:line evidence |
| Approach | The shape of the fix, and why this shape over the alternatives considered |
| Steps | Ordered, each one small enough to verify on its own |
| Files touched | Every path the work will create, edit, or delete |
| Verification | How anyone can tell the work succeeded, by command where possible |
| Open questions | Decisions that need the operator, each with options and a recommendation |
| Risks | What breaks if this is wrong, and what is hard to reverse |
A step that names no file is not yet a step.
Tracker shape
For /blueprint track. Paths that later stages will create can't all be known today, so a stage
names the directory or module it works in and its items name files as they become known.
| Section | Holds |
|---|---|
| Title + started | What this tracks, and the date it was started |
| Status | Last updated date, current stage, next open item, blockers. Rewritten every session. |
| State record | Which file owns state, and that it wins on conflict. Or: this file owns state. |
| Resume | What a fresh session does first, in order (below) |
| Definition of done | What must be true for the whole tracker to close, by command where possible |
| Human gates | Points where the operator must decide or approve before work continues |
| Stages | Ordered, each with a goal and checkbox items |
| Open questions | As in a plan |
| Unverified | Every claim still marked unverified, and what would verify it |
Checkboxes.
- [ ] itemis open.- [x] item (evidence: <path:line | commit | command>)is done. A box is ticked only with evidence, and the evidence must pass the check above. No evidence, no tick.- [x] ~~item~~ (dropped <YYYY-MM-DD>: <reason>)is obsolete. The box is filled so it never reads as open work; the strike and the reason say it was dropped, not done. Never delete an item: what was dropped and why is part of the record.
Resume is written into the tracker for the session that picks the work back up. A
/blueprint revise run does steps 1 and 2 and stops there; step 3 is the work, and rule 2 still
holds.
- Read Status and the state record. Where they disagree, the state record is right; fix Status.
- Re-check the evidence on the most recently ticked items. Untick any whose evidence no longer holds.
- Continue from the next open item, stopping at any human gate before it.
Revising a tracker means: update Status, tick boxes that now have evidence, strike items that no longer apply, add items the work uncovered, then check and report as above.
04 同仓库更多 Skills
ui-design
Set a RENDERED interface's design direction before it is built, then evaluate what shipped. `direct` reads the project's CSS stack, asks about the case, researches real references for the job each screen does, hands the pick to the user, and writes the project's design record; `review` and `sweep` grade declared-vs-rendered slots (no missing or placeholder art), applied theme vs framework default, visual hierarchy, typography, colour roles, CTA, WCAG 2.2 AA contrast and focus, reflow at 320 CSS pixels, situation ergonomics, and AI-slop/templated-default tells. Use `direct` before the first UI build on a surface or for a new component pattern; use `review` after a UI-shipping change is written, when asked to design-review a page, or to decide whether a surface looks right to ship. Grades against a cited catalog with stable rule IDs and BLOCKS on hard-fail red flags. `review` and `sweep` are report-only.
timezone
Set the time zone Claude Code shows times in — the "done 7:55 PM" at the end of a turn, and the clock every command Claude runs sees. Use when the user asks to change, pick, set, fix or clear their time zone, or says the times shown are wrong (a remote server on UTC is the usual cause). Writes one key, env.TZ, into the user's own settings file.
text-eval
Evaluate written prose for AI-generation tells and register drift — mechanical character and punctuation defects, clustered judgment-class signals, citation integrity, and conversational register. Use after writing or editing any prose a person will read, when asked to check whether text reads as AI-generated, or before publishing copy. Grades against a cited catalog with clustering thresholds and hard rows that fire on first occurrence. Report-only.
shared-artifact
The house style for any shareable online artifact — a claude.ai Artifact, a published HTML page, a report or brief someone will be sent a link to. Use before writing or republishing any artifact page, when asked to create, share, publish or clean up an online artifact, and when deciding between an HTML page and a Claude Docs document. Carries the token set, the dark-mode contract, the briefing-binder layout, a starter template, and the sharing hygiene rules.
security-evaluator
Evaluate a code change for web-security flaws — OWASP Top 10:2025 classes as source-review classes, taint signals from source to sink, and a per-language sink appendix. Use after writing or editing code that handles input, auth, data access, templating, deserialization, or external requests; when asked to security-review a change, check for injection/XSS/SSRF/authz flaws, or evaluate the security of what was just written. Report-only, candidate-tier by construction.
records-code-map
The code map for this project — where a file's sections and definitions are by line number, which files and lines mention a topic, and which checks, fixtures and cases cover a file. Use before searching or reading code to find something, before changing a file, and when deciding which test to run after an edit. The map is generated from the files on every call and never stored.