/skill

Blueprint

This skill comes from the open-source community. Full credit goes to its original author and contributors.

Turn a short goal into a build plan that any coding agent can follow from a cold start.

When to Use It

Use this skill when the work:

• Needs more than one pull request.
• Will take more than one session.
• Can be split across two or more agents.
• Has steps that must happen in a set order.
• May fail if key facts are lost between sessions.

Do not use this skill when:

• The work fits in one pull request.
• The work needs fewer than three tool calls.
• The user asks you to do the work now.
• The user only wants a quick answer or review.

If the size is not clear, inspect the project first. Use this skill only if the work is large.

Process

Follow these five stages.

1. Research

Run safe checks before making the plan:

• Check if the folder is a Git repo.
• Check the current branch and working tree.
• Check the remote and default branch.
• Check if gh exists and is signed in.
• Read project guide files, such as AGENTS.md, README.md, and CONTRIBUTING.md.
• Look for old plans, design notes, and memory files.
• Find the main code, tests, build tools, and CI files.
• Note local changes. Do not overwrite or remove them.
• Do not print secrets or open secret files without a clear need.

If Git or gh is missing, use direct mode. In direct mode, plan file changes and checks without branch or pull request steps.

If the project cannot be read, stop and list the missing access or files.

2. Design

Split the goal into 3 to 12 small steps. Each step should fit in one pull request when Git is in use.

For each step, define:

• Goal.
• Reason.
• Files or parts of the app that may change.
• Work items.
• Steps that must finish first.
• Steps that can run at the same time.
• Test commands.
• Clear exit rules.
• Risks and rollback steps.
• Suggested agent or model level, if useful.

Keep related code and tests in the same step. Avoid steps that only say “update code” or “add tests.”

Build a simple dependency list. Do not mark two steps as parallel if they edit the same files, change the same data, or depend on the same unfinished rule.

Put risky base work first. Remove old code only after the new path works and has tests.

3. Draft

Write the plan to:

plans/<project>-<short-goal>.md

Create plans/ if it does not exist and file writes are allowed. Use a short, safe file name with lowercase words and hyphens. If that name exists, add a short number instead of replacing it.

Each plan must include:

1. Goal and scope.
2. Facts found in the project.
3. Assumptions and open questions.
4. Work that is out of scope.
5. Step summary.
6. Dependency graph.
7. Full step briefs.
8. Review gates.
9. Plan change rules.
10. Final release and rollback checks.

Each step brief must stand alone. A new agent must be able to run it without reading earlier chat or step notes. Include exact paths and commands when known. Never invent paths, tools, or commands. Mark unknown facts as checks to perform.

If file writes are not allowed, return the full plan in the chat.

4. Review

Ask a strong review agent to challenge the draft when sub-agents are available and allowed.

The reviewer must check for:

• Missing steps or dependencies.
• Steps that are too large.
• Unsafe order of work.
• Hidden file or data conflicts.
• Weak or missing tests.
• No rollback path.
• Unclear exit rules.
• Made-up project facts.
• Security, data loss, or release risks.
• Steps that cannot run from a cold start.

Fix every high-risk issue before the plan is final. List lower-risk issues as open notes.

If no review agent is available, run the same checklist yourself. Do not skip review.

5. Register

Save the final plan. Update a plan index or project memory file only if one already exists and its format is clear. Do not create a new memory system.

Tell the user:

• Where the plan was saved.
• How many steps it has.
• Which steps can run at the same time.
• Which questions still need an answer.
• Whether the plan uses pull request mode or direct mode.

Do not create branches, change code, open pull requests, or start the build unless the user also asks for that work.

Review Gates

Add gates at key points:

• Base gate: Shared types, data rules, or core tools work.
• Feature gate: The new path works in tests.
• Switch gate: The app can safely use the new path.
• Cleanup gate: Old code can be removed.
• Release gate: CI, docs, rollback, and checks are ready.

A gate must name the command to run and the result that means “pass.”

Common Bad Plans

Do not make plans with these faults:

• One large step called “build the feature.”
• Tests saved for the last step.
• Cleanup before the new path works.
• Parallel steps that edit the same files.
• Commands that do not exist in the project.
• Steps that depend on old chat messages.
• Vague exit rules such as “looks good.”
• No plan for failed data changes.
• No note about user changes in the working tree.
• A pull request plan when Git or gh is not ready.

Changing the Plan

Plans may change after work starts.

When a change is needed:

1. Record the new fact.
2. List the steps it affects.
3. Update dependencies and parallel work.
4. Add or change tests and rollback steps.
5. Mark replaced steps as replaced. Do not erase their history.
6. Run the review checklist again.
7. Tell the user what changed and why.

Do not silently change finished steps. Add a repair step when old work must be fixed.

Concrete Example

Input:

/blueprint myapp "Move the database from SQLite to PostgreSQL"

Output file:

plans/myapp-move-database-to-postgresql.md

Possible step summary:

1. Add the PostgreSQL driver and test settings.
2. Define the new schema and data rules.
3. Build and test the data move script.
4. Update the data access code.
5. Run app tests against PostgreSQL.
6. Add a safe switch and rollback check.
7. Remove SQLite code after the release gate passes.

Example step brief:

## Step 3: Build the Data Move Script

Goal: Copy all SQLite rows to PostgreSQL without data loss.

Needs: Step 2 must be complete.

Work:
- Add the move script under the project’s existing script folder.
- Keep IDs and time values unchanged.
- Make repeat runs safe.
- Stop on a failed row.
- Write a clear error message without secret data.

Checks:
- Run the project’s data move test.
- Compare row counts for every table.
- Check key links between tables.
- Run the script twice and confirm it does not add copies.

Exit rules:
- All rows move with no missing links.
- A second run makes no extra rows.
- A failed run leaves the old database unchanged.

Rollback:
- Keep SQLite as the live database.
- Remove the new PostgreSQL test data.
- Fix the script before trying again.

Install Check

This skill is part of Everything Claude Code. If that project is installed, no extra setup is needed.

From an Everything Claude Code checkout, confirm the file exists:

test -f skills/blueprint/SKILL.md