AGENT SKILL

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

  1. Never call EnterPlanMode or ExitPlanMode. 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, and ExitPlanMode asks to execute, which rule 2 forbids.
  2. 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.
  3. 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.
  4. 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:

  1. 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.
  2. Where plans already live. List the project's files (git ls-files, or outside git find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*') and filter with grep -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.
  3. The first of these that exists in the project root: plan/ docs/plans/ .claude/plans/ notes/plans/ docs/plan/
  4. 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

  1. Read the record before writing anything. The project's own CLAUDE.md, the existing plans found above, git log for 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.
  2. In track mode, find the state record. Look for a file the project already uses to record what is done: its CLAUDE.md or README may name one, and the same file listing filtered with grep -iE '(^|[/_.-])(state|status|progress|tracker)([/_.-].*)?\.md$' finds the usual names, including files inside a folder such as build-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.
  3. 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.
  4. Write the file. The shapes are below. Apply the sourcing rule as you write, not after.
  5. Check it. See below. Fix what the check finds before reporting.
  6. 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:

  1. Re-verify every citation. Re-read each path:line and 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.
  2. 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.
  3. 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.

  • - [ ] item is 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.

  1. Read Status and the state record. Where they disagree, the state record is right; fix Status.
  2. Re-check the evidence on the most recently ticked items. Untick any whose evidence no longer holds.
  3. 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

odysseyalive
odysseyalive/claude-workforce

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.

★ 2
odysseyalive
odysseyalive/claude-workforce

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.

★ 2
odysseyalive
odysseyalive/claude-workforce

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.

★ 2
odysseyalive
odysseyalive/claude-workforce

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.

★ 2
odysseyalive
odysseyalive/claude-workforce

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.

★ 2
odysseyalive
odysseyalive/claude-workforce

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.

★ 2