writing-plans
Skill1 starsChanged 3 months agoMITView on GitHub
Writes an executable plan: ordered tasks, their dependencies, and how each one is known to be done. Use when approved requirements or a clearly multi-step task need a per-task plan before implementation, or when the user says break this down, lay out the steps first, or this is too big to do in one go. Skip single-step or trivial work.
188 other projects use a version of this.
Adopted by
Most recently taken up by
- wxxb789/hoatheir own version, first seen Nov 16, 2026
- mintunitish/tandemtheir own version, first seen Nov 15, 2026
- FimawLLC/fimaw-skillstheir own version, first seen Nov 15, 2026
- mdiri-ai/SoduWorktheir own version, first seen Nov 15, 2026
- Wenaixi/dsh-superpowertheir own version, first seen Nov 15, 2026
- theexperiencecompany/gaiatheir own version, first seen Nov 13, 2026
Used with
Projects with it also use chinese-code-review, chinese-commit-conventions and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
Leodorareluctant259Skillchinese-code-review
中文代码审查规范——在保持专业严谨的同时,用符合国内团队文化的方式给出有效反馈
Also in 8 projects that use this
Leodorareluctant259Skillchinese-commit-conventions
中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化
Also in 8 projects that use this
ryanportfolioSkilladdskill
Create, import, update, or install repo or personal skills: runtime ownership, resources, discovery checks.
Also in 6 projects that use this
ryanportfolioSkillapply-firmware
Bring current folder (plain folder, existing repo, old or partial firmware copy) up to full Harness Firmware in place. Mirror external repo → adopt-repo.
Also in 6 projects that use this
- +2 more from Leodorareluctant259
- +6 more from ryanportfolio
Other versions188 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 188
- obra/superpowers★ 314ksame name
- jnMetaCode/superpowers-zh★ 8.5ksame name
- openai/plugins★ 7.8ksame name
- farm-fe/farm★ 5.6ksame name
- microsoft/FluidFramework★ 4.9ksame name
- lingyired/status-trio★ 1.8ksame name
- revokslab/ShipFree★ 1.7ksame name
- GanyuanRan/Aegis★ 1.4ksame name
- pcvelz/superpowers★ 1.3ksame name
- math-inc/OpenGauss★ 1.3ksame name
178 more not listed
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 repository49 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- working-from-a-ticketSkill
- writing-specsSkill
- clarifying-intentSkill
- dispatching-parallel-agentsSkill
- handoffSkill
- mapping-the-codebaseSkill
- prototypingSkill
- using-git-worktreesSkill
- using-sdlc-skillsSkill
- viewing-artifactsSkill
- writing-skillsSkill
- yagniSkill
- finishing-a-branchSkill
- release-readinessSkill
- architecture-decisionsSkill
- coding-standardsSkill
- data-modelSkill
- migration-strategySkill
- reviewing-plansSkill
- system-architectureSkill
- ui-ux-designSkill
- adding-observabilitySkill
- changing-a-live-schemaSkill
- executing-plansSkill
- rollout-controlsSkill
- subagent-driven-developmentSkill
- test-driven-developmentSkill
- complexity-auditSkill
- containing-an-incidentSkill
- debuggingSkill
- deprecating-an-apiSkill
- diagnosing-a-sessionSkill
- eliminating-correctionsSkill
- large-scale-changesSkill
- post-mortemSkill
- refactor-architectureSkill
- brainstormingSkill
- define-goalsSkill
- feasibility-checkSkill
- scopingSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- reviewing-a-prSkill
- security-auditsSkill
- verification-before-completionSkill
- verification-strategySkill
- visual-ui-verificationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. 0 are common, 9 are distinctive, and 11 are very specific to this project.
0
Common
Most of the 170 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Leave the implementation to the executor: write what each task must make true and how that is judged, not the code.
- Very specific: line 16
If the intent is still ambiguous, invoke clarifying-intent first.
- Distinctive: line 27
Write separate plans for independent subsystems unless one cutover or rollback makes them one initiative.
- Very specific: line 52
Leave Integration cadence at plan end.
- Very specific: line 54
Leave Out-of-task findings at log and report.
- Very specific: line 58
If the approved UI design carries Selected visual references, copy the complete keyed collection into the index, filling Approved design …
- Very specific: line 62
Visual reference coverage: If a reference is missing or an ID has no owner, return the plan to ui-ux-design.
- Distinctive: line 66
If one transformation runs across many items, bind the machine-readable inventory and the output pattern instead of listing the items.
- Distinctive: line 88
Put existing code and external input artifacts in Context.
- Distinctive: line 97
Before writing a custom check, look in the repository and its runtime for an existing deterministic checker of that surface (test runner, …
- Distinctive: line 103
If the task's claim rests on a security boundary (path filter, allowlist, rate limit, lock), the Evaluator tries to get past it through the …
- Very specific: line 114
Write 00-index.md plus one file per task to .sdlc-skills/plans/{{YYYY-MM-DD}}-{{topic}}/ or the user-set path.
- Very specific: line 118
After approval, a change the index's Invalidation triggers names is a successor file.
- Very specific: line 127
If you find a gap or contradiction in the approved spec, here or while writing tasks, stop planning.
- Very specific: line 140
Run bash scripts/plan-version.sh --check-contract on the plan directory.
- Distinctive: line 148
If two tasks each define the same fact, give it one owner and make the others consume it.
- Very specific: line 187
Run bash scripts/plan-version.sh on the plan directory.
- Distinctive: line 209
Do not invoke either executor, create a workspace, or write code in this turn.
- Distinctive: line 214
If an approval names no mode, ask the mode question in a separate turn.
- Very specific: line 215
Add one row to the External decision ledger (the ledger: add to it, never rewrite it.
“Common” is measured: kept by at least 6 in 10 of the 170 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
Writing Plans
Leave the implementation to the executor: write what each task must make true and how that is judged, not the code.
When to use
- Detailed requirements are approved, or a precise task spans three or more steps or more than one file.
- Skip for single-step or trivial changes.
- If the intent is still ambiguous, invoke
clarifying-intentfirst. If verifiable behavior is still missing, invokewriting-specsfirst. A precise task needs neither. - Fill the classification block (the index's High-risk classification section). High-risk means any answer there leaves the ordinary route, or the user marks the work high-risk. For a high-risk target, read the approved migration and assurance contracts before writing a task. If they are missing, plan only the gate that is missing, taking the exact proposed contract as its input, and put no target work in the plan; record unsettled facts as evidence, never as accepted deviations.
- Write separate plans for independent subsystems unless one cutover or
rollback makes them one initiative. If the approved design orders the
work in dependency-ordered slices (a later part builds on what an earlier
one lands), write the first slice's plan now and each later one after its
predecessor lands, against the base then current; the index's
Plan setline names the order.
Available scripts
scripts/plan-version.sh— prints the plan's version, or with--check-contractand--verifychecks task-contract invariants and the decision ledger.scripts/plan-files.sh— checks each task'sFilespaths against a base revision. Read-only.
Step 1: Write the index
- REQUIRED SUB-SKILL: invoke
mapping-the-codebaseon every region the plan will change, unless a boundary record inside its freshness limit covers that region at the base revision. Draw each task'sFilesfrom the record, and list the record's path in every task'sContext. Never put the record in the index'sBound inputs: an executor updates it, and that update is not bound-input drift. - Open
assets/index-template.mdwhen starting the index. Fill the header first. - Fill
Plan set:none, or the slices in order, this plan's position, its predecessor plan's path, and the next slice's name. Write only this slice's tasks; the next slice is planned when this one lands. - Leave
Integration cadenceatplan end. Writeper taskonly when the user directly asked for per-task integration, and quote the instruction. - Leave
Out-of-task findingsatlog and report. If the request says to fix whatever turns up along the way, writefix when admitted, quote the instruction, and fill its budget. Plan an instruction with no end as that bounded policy; never copy it into a task or the goal. - If the approved UI design carries Selected visual references, copy
the complete keyed collection into the index, filling
Approved design artifact versionwith the design's identity from its ledger row, and map every Reference ID to an owning task and a conformance evaluator ID in Visual reference coverage. If a reference is missing or an ID has no owner, return the plan toui-ux-design. - Give every file and side effect exactly one owning task. If two tasks fall on the same one, add a dependency and name a single transition owner.
- If one transformation runs across many items, bind the machine-readable inventory and the output pattern instead of listing the items.
Step 2: Write the tasks
Slice vertically: one evaluable capability per task. Split only at a real check boundary. For high-risk target work, read
references/scalable-transformation.mdbefore slicing, and copy the transition policy from the migration contract.A request: let the existing
reportcommand also write CSV. Splitting it into "add a CSV serializer" and "wire a--csvflag" cuts one capability in two: neither half is the requested behavior its own Evaluator could accept. One task, "report --csvwrites the report as CSV", judged by a test that runs the command and parses the file, is the slice. "--csvhonours the--sincefilter" earns a second task: it has its own check.- Open
assets/task-template.mdbefore writing each task. FillTask ID,Depends on,Files,Exclusive ownership/effects,Contextas paths. List the plan's00-index.mdin every task'sContext, so a dispatched worker reads the Constraints and Review focus the task inherits. - Fill Consumes from earlier tasks' exact Produces names and types. Put existing code and external input artifacts in Context; do not invent producer tasks for inputs that already exist.
- Fill
Implementation disciplineswithtest-driven-developmentandyagni, or with the exact carve-out that makes them inapplicable. Fill
Evaluator: a command that returns a verdict, or a rubric with its accountable judge and deciding observations. For a UI task, copyApplicable visual referencesand give every Reference ID a Visual conformance gates row.Before writing a custom check, look in the repository and its runtime for an existing deterministic checker of that surface (test runner, linter, type checker, schema or config validator, the project's check command), and use it when it verifies the claim. Add a heavy new tool only with a stated reason.
If the task's claim rests on a security boundary (path filter, allowlist, rate limit, lock), the Evaluator tries to get past it through the real component chain: encoded separators, dot segments, case variants, input sent without the client's normalisation. For a counting limit, it also sends more simultaneous attempts than the limit and expects at most the limit to pass.
- Fill
Evaluator identity/ownerso the check lives outside what the task may change. If a task may edit its own check, write the permitted scope and require RED or deliberate falsification before GREEN counts. - Fill
Suggested tierwith the Model selection section ofdispatching-parallel-agents. - Write
00-index.mdplus one file per task to.sdlc-skills/plans/{{YYYY-MM-DD}}-{{topic}}/or the user-set path. No approval, execution state, or evidence goes in these files, except the task checkbox and its state label, which mirror the execution ledger. After approval, a change the index'sInvalidation triggersnames is a successor file; any other is an executor's ruling.
Step 3: Self-review against the inputs, by name
- Trace each requirement and each accepted risk gate (the index's Trace column keeps that name: the check that covers an accepted risk) to a task or phase. Fix each uncovered requirement; cut each task that traces to nothing.
- If you find a gap or contradiction in the approved spec, here or while
writing tasks, stop planning. No task lists the spec among its
Filesor edits it. REQUIRED SUB-SKILL: invokewriting-specsfor a successor spec that names the approved one as its predecessor, and plan against the successor once it is approved. - Replace every
TBD,handle edge cases,similar to task Nwith the task it hides. Replace anExpected:value that did not come from running the command on the current tree with the value the command printed, or with a rubric when the command cannot run yet. A user-facing string the plan fixes (message, label, help text, doc sentence) that states a location, condition, or number names the file and symbol it was checked against; rewrite a claim with no such citation to what is known, or remove it. - Run
bash scripts/plan-version.sh --check-contracton the plan directory; it checksConsumes,Depends on,Implementation disciplines, and file overlap. Then confirm every task has an executable Evaluator or a controlled rubric, that the index has one top-level Acceptance check, and that its Constraints block holds across every task. - Name in the index's Architecture the one type or module that owns each domain fact more than one task consumes: a type, a set of kinds and where their traits live, the error type that crosses a module boundary. If two tasks each define the same fact, give it one owner and make the others consume it.
- Walk the tasks in dependency order against the bound base revision, not
against the design's description of it. Run
bash scripts/plan-files.sh --base {{revision}} {{plan dir}}and fix eachgapit prints before presenting. Then confirm at each task boundary that every input the next task reads already exists, that every deleted or renamed artifact has no surviving consumer, and that the task's own Evaluator can run on that state. - For every interface a task changes or removes (a type, a kind in a set of
kinds, a trait, a signature, an exported name, a stored format), search
the base revision for its consumers: callers, exhaustive matches,
implementations, serialized copies, in every package of the repository.
Confirm each consumer sits in this task's
Filesor in a dependent task's. A consumer no task owns is a gap: fix it before presenting. A task whoseObjectiverests on a claim about the current code (a command exists, a format carries a field) resolves that claim against the base revision; if it does not hold, stop planning: a spec claim gets a successor through Step 3.2, and a design claim returns to the owner ofsystem-architecturefor a successor design before planning resumes. - Resolve every path and symbol the plan cites against the current revision, and replace any that does not resolve. Cite a path or a symbol, never a line number.
- Confirm every selected Reference ID has a carrying task and a matching conformance evaluator.
- Fill Review focus with up to five spec-implied inputs or failure
modes that no task Evaluator exercises, or mark it
none; give everynone yetrow a check or name it in the PR. If a task tells things apart by the shape of a string (a key, slug, name, or path used as an identity), name two different inputs that produce the same string and the task test that separates them, or have the task carry the identity as structured data. - REQUIRED SUB-SKILL: invoke
reviewing-planswhen the route is high-risk, and bring every blocker it returns to a recorded decision as that skill says; for any other plan, ask the offer questionreviewing-plansstates.
Step 4: Present, then stop
Run
bash scripts/plan-version.shon the plan directory. Readassets/mode-question.mdbefore presenting, for which modes to offer and recommend. Show the complete index and the printed version to theApproval ruleowner:Plan {{absolute path of the plan directory}} — version {{printed version}} {{goal, architecture, constraints, acceptance, trace, task list, review findings}} 1. Approve — inline, in this session 2. Approve — delegated, a subagent per task 3. Approve — delegated, in waves 4. Approve — inline, in a new session 5. Request changes 6. Reject 7. Cancel Recommendation: {{option}} — {{one sentence}}.Omit modes it does not offer, keeping the numbers. Ask this and end the turn;
clarifying-intentowns what closes it.- Do not invoke either executor, create a workspace, or write code in this turn.
- Under a standing order, proceed without the pause only when its scope, owner, constraints, and mode explicitly cover unseen plan versions. First bind the exact version to that receipt.
- If an approval names no mode, ask the mode question in a separate turn.
- Add one row to the
External decision ledger(the ledger: add to it, never rewrite it; it sits outside the plan):Identity= the printed version,Location= the index path,State= approved,Bound evidence= theApproval ruleowner and their answer, any review report path, then themode:the mode question maps the answer to. Write nothing about approval into the index. - REQUIRED SUB-SKILL: on a direct answer choosing option 1, 2, or 3,
invoke the executor that mode names against the approved version before
any workspace or implementation action:
executing-plansfor inline,subagent-driven-developmentfor delegated. On option 4, print the prompt the mode question gives and end the turn. This skill writes no code.
Gotchas
- A row keyed to the index's
Normative versionline survives a task-file edit; key rows to the printed version. - One plan for a design of several slices plans every later slice against a base the earlier slices will change: a 37-task plan over a sliced design grew through successors until it finished. A slice planned after its predecessor lands is planned against the code it will meet.
- A
Fileslist written from the design names the files the design discusses, not the ones the change breaks: a plan that added a kind to a set of kinds listed its owning module and missed seven exhaustive matches in another package, each found by a worker mid-task and each a successor version. The map comes first; Step 3.7 searches the base, not the design.
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.

