plan-and-build
Skill0 starsChanged 11 days agoMITView on GitHub
Takes a feature or change that spans several files from a vague idea to an approved design, a plan, and a reviewed, merged branch; Use when asked to build or change something non-trivial, requirements are unclear, or the user says "plan this", "let's build X", "brainstorm", "write a spec", or "execute the plan".
6 other projects use a version of this.
Adopted by
Most recently taken up by
- daryaKuto/claude-skillstheir own version, first seen Nov 15, 2026
- newrise0410/claude-codex-workflowtheir own version, first seen Oct 28, 2026
- greatSumini/cc-systemtheir own version, first seen Oct 8, 2026
- KarmaBlackshaw/claude-skillstheir own version, first seen Sep 17, 2026
- dennisrongo/claude-skillstheir own version, first seen Aug 16, 2026
- jattanjie21/plan-and-buildtheir own version, first seen May 5, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- greatSumini/cc-system★ 438same name
- jattanjie21/plan-and-build★ 14same name
- newrise0410/claude-codex-workflow★ 4same name
- dennisrongo/claude-skills★ 1same name
- daryaKuto/claude-skills★ 0same name
- KarmaBlackshaw/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository42 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- agent-handoverSkill
- brand-sweepSkill
- design-tokensSkill
- experiment-labSkill
- parity-checkSkill
- pitch-from-evidenceSkill
- platform-reachSkill
- product-kickoffSkill
- product-reconSkill
- quality-loopSkill
- repository-auditSkill
- review-miningSkill
- review-practiceSkill
- security-auditSkill
- stack-foundationSkill
- systematic-debuggingSkill
- technical-reconSkill
- ux-qualitySkill
- web-qualitySkill
- agent-handoverSkill
- brand-sweepSkill
- design-tokensSkill
- experiment-labSkill
- parity-checkSkill
- pitch-from-evidenceSkill
- plan-and-buildSkill
- platform-reachSkill
- product-kickoffSkill
- product-reconSkill
- quality-loopSkill
- repository-auditSkill
- review-miningSkill
- review-practiceSkill
- security-auditSkill
- stack-foundationSkill
- systematic-debuggingSkill
- technical-reconSkill
- ux-qualitySkill
- web-qualitySkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 5 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Not for: fully specified small fixes (just do them), bugs (operations.md), reviews, UI polish (ux-quality).
- Distinctive: line 11
If work outgrows its size mid-task, stop and say so.
- Very specific: line 17
Read first (make where Q="<topic>", nearest AGENTS.md, issues).
- Distinctive: line 19
Ask one question per message, one sentence, open before multiple choice ("walk me through the last time this bit you").
- Distinctive: line 46
Hard gate: no product code, scaffolding, or dependency installs until the owner approves the posted design in a later message ("sounds …
- Distinctive: line 61
Every task lists exact files, Consumes/Produces signatures, the failing test first with real assertion values, and one verification command …
- Very specific: line 83
Read its return block (Done/Verified/Residuals, see implementer.md).
- Very specific: line 92
Use the critic; at high risk its verdict is the final gate.
- Distinctive: line 109
Stop and ask only for: irreversible steps, security-sensitive actions, side effects outside the worktree (merge, shared push, publish), or …
- Very specific: line 122
After merge or push: make pull-first before relying on the base, make ci-status until green.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Plan and build
Not for: fully specified small fixes (just do them), bugs
(operations.md), reviews, UI polish
(ux-quality). A new product starts at product-kickoff.
If work outgrows its size mid-task, stop and say so.
1. Refine the idea (owner dialogue)
Find out what the owner actually wants and why before designing anything.
- Read first (
make where Q="<topic>", nearestAGENTS.md, issues); never ask what the repo can answer. - Ask one question per message, one sentence, open before multiple choice ("walk me through the last time this bit you"); a guess they can correct often beats a question. Cover: who it is for, success, non-goals and anti-goals, prior art, current state, constraints, what would make them wince.
- Think wide privately, then show 2-3 genuinely different
approaches with trade-offs and your pick (
strategistrole for large goals). A labeled throwaway spike is fine; keeping it goes through step 2. - Surface assumptions as
ASSUMPTIONS: 1..n - correct me now. Mark every guess as yours. - Several independent capabilities: get a short capability map approved (id, responsibility, depends on, build order), then run steps 1-5 per module.
- Play back each understood part in ~250 words, ask what is wrong. Reframe vague asks as measurable criteria ("faster" becomes "LCP under 2.5 s").
2. Write the design and get it approved
The design is the write-ahead issue, not a new file (ISSUE_TEMPLATE.md):
search for duplicates, then make issue (a Local-WAL draft when there is no
remote). It carries intent and why, goals, non-goals, constraints, the decisions
the owner made (yours marked as yours), evidence-producing acceptance criteria,
risks, and a "Not doing" list. Run make risk for the ceremony level
and follow verification.md.
For a project-size design, have a fresh critic read it as the builder would;
sort its questions: already answered, minor (settle, mark as your call), theirs
(ask in ONE message).
Hard gate: no product code, scaffolding, or dependency installs until the owner approves the posted design in a later message ("sounds good" to an idea is not approval of a description you have not written). End the turn after posting. Owner opts out of questions: state major how-it-is-made choices in one line, continue.
3. Write the plan
Map the files first (each with one responsibility; follow existing patterns).
Then cut tasks (template:
references/plan-template.md):
- A task = the smallest unit with its own test cycle and review gate; fold
setup and docs into the task that needs them. Vertical slices (schema + logic
- surface for one behavior), not horizontal layers. XL (8+ files) is too big.
- Risky slice first; checkpoint (
make donegreen) every 2-3 tasks. - Every task lists exact files, Consumes/Produces signatures, the failing test first with real assertion values, and one verification command with its expected result. A step is done when exactly one reasonable thing can be written from it; "handle edge cases" or "TBD" decides nothing.
- Self-review against the design (checklist in the template); fix inline.
Store the plan as an issue comment (or in the Local-WAL draft), checkboxes
ticked as tasks land. Never a tracked backlog file; make check rejects those.
Owner confirms the plan.
4. Build
First a clean baseline: separate worktree per session
(collaboration.md, never on the default
branch), make start, tests green. Tasks in plan order; per task:
- Record
BASE=$(git rev-parse HEAD). - Dispatch a fresh
implementerwith the brief fields: Goal, one Deliverable, Scope, Out of scope, Context (issue link, task text, interfaces earlier tasks produced), Done when (the verification command). Pointers, not pasted history. It spawns no subagents; it commits per slice. - Read its return block (
Done/Verified/Residuals, seeimplementer.md). Residuals touching correctness or scope: fix before review. It stopped for missing context: answer and redispatch. It could not finish: change something (context, deeper tier, smaller task, plan fix), never retry unchanged. - Review in two passes on
git diff BASE..HEAD: (a) spec compliance against the task text, nothing missing or extra; (b) quality, incl. real assertions, simplicity, no weakened checks (.skip, loosened thresholds, suppressions). Tier scales with diff risk. Use thecritic; athighrisk its verdict is the final gate. - Findings loop: Critical/Important go back to the same implementer, then a scoped re-review of the fix diff only; 3 rounds, then a deeper-tier fresh implementer, then you rule. Minor ones go on the issue. Never fix in your own context or skip the re-review.
- Tick the task on the issue with the commit range. After compaction trust
the checklist and
git log; never re-dispatch ticked tasks.
Small plans (a few mechanical tasks) may run inline: same TDD (watch the test
fail) and ticking, then one fresh critic over the whole branch.
Parallel only if independent: disjoint write scopes, no shared state or
interface still undefined. Define a shared contract first, then fan out, one worktree each; merge through you, then run make done once
on the combination. Related failures or unknown causes are not parallel work.
Rulings, not stalls. Decide plan defects and ambiguities yourself, the
design wins; record Ruling: <what> - <why> - <cost if wrong> on the issue.
Stop and ask only for: irreversible steps, security-sensitive actions, side
effects outside the worktree (merge, shared push, publish), or a plan so broken
every path is a guess.
5. Finish
make doneon the exact tree you will integrate; a stale green does not count. Observe the real artifact; update docs you made stale. Failing: stop.- One whole-branch
critic(deep tier) with the design, Rulings, deferred minors; one fix wave, one scoped re-check. - Confirm the base branch, then offer exactly: merge locally; push and open a PR (keep the worktree); keep as is. Integration is the owner's decision. Discard or force only on explicit request, after listing what is lost.
- After merge or push:
make pull-firstbefore relying on the base,make ci-statusuntil green. File residuals as issues. List every Ruling you made in the final message. Remove only worktrees you made, never--force.
Red flags
| Thought | Reality |
| "Simple, skip the design" | Short is fine; unwritten is not. |
| "I'll offer options to save effort" | Options steer. Let them describe it first. |
| "The implementer self-reviewed" | It never replaces the fresh two-pass review. |
| "One more round" | After the cap the failure is structural; rule it. |
| "Plan is wrong here" | Rule against the design, record it, continue. |
| "Tests passed earlier" | Run them on the tree you integrate. |
Superpowers (make upstream ID=superpowers-workflow): the original planning and review templates. Pull code-reviewer.md when a reviewer brief needs a fuller checklist.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

