writing-plans
Skill3 starsChanged 53 days agoMITView on GitHub
Write an implementation plan that an agent with zero context for the codebase can execute without guessing: exact file paths, complete code, test commands with expected output, and bite-sized tasks of 2–5 minutes each. Use before any multi-step feature, complex requirement breakdown, or hand-off to a task-per-subagent executor. Not for setting outcomes and ambition (that is goal definition) and not for exploring whether the work should happen at all.
188 other projects use a version of this, 106 of them edited.
Adopted by
Most recently taken up by
- mintunitish/tandemtheir own version, first seen Nov 15, 2026
- FimawLLC/fimaw-skillsedited, first seen Nov 15, 2026
- mdiri-ai/SoduWorkedited, first seen Nov 15, 2026
- Wenaixi/dsh-superpowertheir own version, first seen Nov 15, 2026
- theexperiencecompany/gaiaedited, first seen Nov 13, 2026
- bordenet/superpowers-plustheir 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 · 106
- openai/plugins★ 7.8k13% same
- farm-fe/farm★ 5.6k16% same
- revokslab/ShipFree★ 1.7k29% same
- math-inc/OpenGauss★ 1.3k80% same
- DemonDamon/AgenticX★ 1k29% same
- mdiri-ai/SoduWork★ 93013% same
- coco-research/coco★ 79717% same
- AgentTeam-TaichuAI/ScienceClaw★ 67117% same
- Tommy-yw/RunbookHermes★ 54680% same
- involvex/youtube-music-cli★ 47729% same
96 more not listed
Wrote their own version · 82
- obra/superpowers★ 314ksame name
- jnMetaCode/superpowers-zh★ 8.5ksame name
- microsoft/FluidFramework★ 4.9ksame name
- lingyired/status-trio★ 1.8ksame name
- GanyuanRan/Aegis★ 1.4ksame name
- pcvelz/superpowers★ 1.3ksame name
- kid-sid/claude-spellbook★ 190same name
- LayneChai/superpowers-dsh★ 150same name
- REPOZY/superpowers-optimized★ 146same name
- jh941213/ADLC-harness★ 125same name
72 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 repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-harness-settings-paritySkill
- agent-operating-contract-evolutionSkill
- ai-coding-agent-delegationSkill
- arch-improvement-planSkill
- contract-bound-deliverablesSkill
- cross-agent-repair-routingSkill
- define-goalSkill
- delegated-work-acceptanceSkill
- design-an-interfaceSkill
- design-mdSkill
- discord-rich-messageSkill
- dotnet-repo-workflowSkill
- evidence-backed-analytical-writingSkill
- evidence-boundary-disciplineSkill
- find-nearbySkill
- gddSkill
- generated-runtime-repairsSkill
- ghc-searchSkill
- git-auto-sync-pipelinesSkill
- github-code-reviewSkill
- github-repo-managementSkill
- grounded-citationsSkill
- harness-engineeringSkill
- hermes-context-file-loadingSkill
- hermes-modelsSkill
- hermes-updatesSkill
- hoa-introspect-distillSkill
- hoa-introspectSkill
- hoa-skill-reviewSkill
- hoa-skill-workSkill
- html-artifactSkill
- jupyter-live-kernelSkill
- kanban-workflowsSkill
- m365-copilot-cdpSkill
- measurement-campaign-evidenceSkill
- microsoft-officeSkill
- notes-to-prdSkill
- ocr-and-documentsSkill
- official-document-verificationSkill
- omp-headless-orchestrationSkill
- ops-claim-verificationSkill
- package-release-verificationSkill
- plan-to-issuesSkill
- project-phase-closeoutSkill
- report-claim-auditSkill
- research-stream-consolidationSkill
- review-revision-candidatesSkill
- rss-feedsSkill
- skill-library-curationSkill
- skill-porting-and-publishingSkill
- spec-convergenceSkill
- structural-validity-gatesSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- teams-cdpSkill
- tmux-agent-controlSkill
- whisperSkill
- writingSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. 0 are common, 14 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 170 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste.
- Very specific: line 45
Start from the spec, not from scratch: When spec-convergence produced a spec, the plan consumes it: implement its Scope, Acceptance and …
- Distinctive: line 61
Every step is one action:
- Distinctive: line 93
Every plan MUST start with:
- Distinctive: line 170
Use the harness's search, read and shell capabilities to understand the project:
- Distinctive: line 174
Read the entry point and the configuration that the feature will touch.
- Distinctive: line 188
Create tasks in order:
- Very specific: line 219
Write the plan wherever this project records plans — PLAN_DIR (default docs/plans), file name pattern PLAN_FILE_PATTERN (default …
- Distinctive: line 230
If the plan is tracked somewhere else (an issue, a board card, a task file), record it there and treat that surface as authoritative — the …
- Distinctive: line 242
Bad: Add "flexibility" for future requirements
- Distinctive: line 263
Every task that produces code should include the full TDD cycle:
- Distinctive: line 266
Run to verify failure
- Distinctive: line 268
Run to verify pass
- Distinctive: line 270
If the project has no test-first rule, still require a regression test at the seam the task touches.
- Distinctive: line 274
Commit after every task:
- Distinctive: line 305
After saving the plan, offer the execution approach:
- Very specific: line 310
When executing, use the subagent-driven-development skill:
“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 Implementation Plans
Overview
Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain. Assume they don't know good test design very well.
Core principle: A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.
Method adapted from the public superpowers planning flow (MIT); the plan-shape sections and
hand-off are this port's.
When to Use
Always use before:
- Implementing multi-step features
- Breaking down complex requirements
- Delegating to subagents via
subagent-driven-development
Start from the spec, not from scratch. When spec-convergence produced a spec, the plan consumes
it: implement its Scope, Acceptance and Testing seam; do not re-decide a settled boundary. If a task
would need a decision the spec never made, stop and return to spec-convergence — widening the plan is
how an unagreed boundary becomes code.
Don't skip when:
- Feature seems simple (assumptions cause bugs)
- You plan to implement it yourself (future you needs guidance)
- Working alone (documentation matters)
Bite-Sized Task Granularity
Each task = 2–5 minutes of focused work by default (PLAN_TASK_MINUTES_MIN,
PLAN_TASK_MINUTES_MAX).
Every step is one action:
- "Write the failing test" — step
- "Run it to make sure it fails" — step
- "Implement the minimal code to make the test pass" — step
- "Run the tests and make sure they pass" — step
- "Commit" — step
Too big:
### Task 1: Build authentication system
[50 lines of code across 5 files]Right size:
### Task 1: Create User model with email field
[10 lines, 1 file]
### Task 2: Add password hash field to User
[8 lines, 1 file]
### Task 3: Create password hashing utility
[15 lines, 1 file]Plan Document Structure
Header (Required)
Every plan MUST start with:
# [Feature Name] Implementation Plan
> **For the executing agent:** implement this plan task by task using the project's
> task-per-subagent method, if it has one.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---Task Structure
Each task follows this format:
### Task N: [Descriptive Name]
**Objective:** What this task accomplishes (one sentence)
**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
- Test: `tests/path/to/test_file.py`
**Step 1: Write failing test**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
**Step 2: Run test to verify failure**
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL — "function not defined"
**Step 3: Write minimal implementation**
```python
def function(input):
return expected
```
**Step 4: Run test to verify pass**
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS
**Step 5: Commit**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```Writing Process
Step 1: Understand Requirements
Read and understand:
- Feature requirements
- Design documents or user description
- Acceptance criteria
- Constraints
Step 2: Explore the Codebase
Use the harness's search, read and shell capabilities to understand the project:
- List the project's source and test layout, and find the file that owns the area you will change.
- Find a similar, already-working feature and read its implementation and tests completely.
- Read the entry point and the configuration that the feature will touch.
- Record the exact test/build commands from the project's own instructions, not from memory.
Step 3: Design Approach
Decide:
- Architecture pattern
- File organization
- Dependencies needed
- Testing strategy
Step 4: Write Tasks
Create tasks in order:
- Setup/infrastructure
- Core functionality (TDD for each)
- Edge cases
- Integration
- Cleanup/documentation
Step 5: Add Complete Details
For each task, include:
- Exact file paths (not "the config file" but
src/config/settings.py) - Complete code examples (not "add validation" but the actual code)
- Exact commands with expected output
- Verification steps that prove the task works
Step 6: Review the Plan
Check:
- Tasks are sequential and logical
- Each task is bite-sized (2–5 min by default)
- File paths are exact
- Code examples are complete (copy-pasteable)
- Commands are exact with expected output
- No missing context
- DRY, YAGNI, TDD principles applied
Step 7: Save the Plan
Write the plan wherever this project records plans — PLAN_DIR (default docs/plans), file name
pattern PLAN_FILE_PATTERN (default YYYY-MM-DD-<feature>.md) — then commit it with the project's
commit convention:
mkdir -p "${PLAN_DIR:-docs/plans}"
# save as "${PLAN_DIR:-docs/plans}/$(date +%Y-%m-%d)-<feature>.md"
git add "${PLAN_DIR:-docs/plans}/"
git commit -m "docs: add implementation plan for <feature>"If the plan is tracked somewhere else (an issue, a board card, a task file), record it there and treat that surface as authoritative — the plan does not exist twice.
Principles
DRY (Don't Repeat Yourself)
Bad: Copy-paste validation in 3 places Good: Extract validation function, use everywhere
YAGNI (You Aren't Gonna Need It)
Bad: Add "flexibility" for future requirements Good: Implement only what's needed now
# Bad — YAGNI violation
class User:
def __init__(self, name, email):
self.name = name
self.email = email
self.preferences = {} # Not needed yet!
self.metadata = {} # Not needed yet!
# Good — YAGNI
class User:
def __init__(self, name, email):
self.name = name
self.email = emailTDD (Test-Driven Development)
Every task that produces code should include the full TDD cycle:
- Write failing test
- Run to verify failure
- Write minimal code
- Run to verify pass
If the project has no test-first rule, still require a regression test at the seam the task touches.
Frequent Commits
Commit after every task:
git add [explicit paths]
git commit -m "type: description"Common Mistakes
Vague Tasks
Bad: "Add authentication" Good: "Create User model with email and password_hash fields"
Incomplete Code
Bad: "Step 1: Add validation function" Good: "Step 1: Add validation function" followed by the complete function code
Missing Verification
Bad: "Step 3: Test it works"
Good: "Step 3: Run pytest tests/test_auth.py -v, expected: 3 passed"
Missing File Paths
Bad: "Create the model file"
Good: "Create: src/models/user.py"
Execution Handoff
After saving the plan, offer the execution approach:
"Plan complete and saved. Ready to execute using subagent-driven-development — a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"
When executing, use the subagent-driven-development skill:
- Fresh subagent per task with full context
- Spec compliance review after each task
- Code quality review after spec passes
- Proceed only when both reviews approve
Configuration
| Key | Env | Default |
plan_dir | PLAN_DIR | docs/plans |
plan_file_pattern | PLAN_FILE_PATTERN | YYYY-MM-DD-<feature>.md |
task_minutes_min | PLAN_TASK_MINUTES_MIN | 2 |
task_minutes_max | PLAN_TASK_MINUTES_MAX | 5 |
test_command | PLAN_TEST_CMD | the project's documented test command |
commit_style | PLAN_COMMIT_STYLE | the repo's own commit convention |
Resolution order and the config-file path are defined once in skill-porting-and-publishing § Configuration; this skill does not restate them. A plan recorded outside the filesystem (issue, board, task file) is a project profile choice, not a second source of truth.
Remember
Bite-sized tasks (2-5 min each)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commitsA good plan makes implementation obvious.
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.

