writing-plans
Skill1 starsChanged 3 days agoMITView on GitHub
Creates detailed implementation plans for multi-step tasks with exact file paths, code examples, and test commands.
189 other projects use a version of this.
Adopted by
Most recently taken up by
- Badhon-00/MDCPtheir own version, first seen Nov 16, 2026
- b-mendoza/agent-skillstheir own version, first seen Nov 16, 2026
- 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
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 versions189 projects use a version of this.
Word for word · 1
- LucasCooperBey/claude-skills★ 1100% same
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 repository53 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/deep-recon/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-researchSkill
- algorithmic-artSkill
- api-integrationSkill
- breakdownSkill
- c4-architectSkill
- canvas-designSkill
- coding-agentsSkill
- compound-engineeringSkill
- context-budgetSkill
- counterfactualSkill
- critiqueSkill
- d3js-visualizationSkill
- data-analyst-agentSkill
- database-migrationsSkill
- deep-reconSkill
- design-tasteSkill
- e2b-sandboxSkill
- ecosystem-auditSkill
- executing-plansSkill
- frontend-designSkill
- fullstack-agentSkill
- grillSkill
- kickoffSkill
- mcp-builderSkill
- model-migrationSkill
- naming-the-machineSkill
- full-output-enforcementSkill
- package-researchSkill
- pdf-generationSkill
- pp2pSkill
- pp3pSkill
- prompt-engineerSkill
- prompt-groundingSkill
- redesignSkill
- requesting-code-reviewSkill
- reverse-engineer-to-learnSkill
- review-changesSkill
- scratchpadSkill
- shipSkill
- slack-gif-creatorSkill
- sprint-architectSkill
- techdebtSkill
- test-and-fixSkill
- threat-modelSkill
- verification-before-completionSkill
- visual-verdictSkill
- webapp-testingSkill
- web-asset-generatorSkill
- whatdidimissSkill
- wiki-writeSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 5 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 170 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 7
Create comprehensive plans for multi-step tasks, designed for engineers with limited codebase familiarity.
- Distinctive: line 97
After plan completion, offer two paths:
- Distinctive: line 124
Every code block must be:
- Distinctive: line 168
Every plan in deliberation mode includes these additional sections BEFORE the task list:
- Distinctive: line 244
Every plan (deliberation or not) must meet:
“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
Create comprehensive plans for multi-step tasks, designed for engineers with limited codebase familiarity.
Plan Structure
# Implementation Plan: [Feature Name]
## Goal
[One sentence describing the outcome]
## Architecture Context
[Relevant tech stack and patterns]
## Prerequisites
- [ ] Dependency installed
- [ ] Config in place
---
## Task 1: [Descriptive Name]
**Files:** `src/path/to/file.ts`
**Time:** 2-5 minutes
### Test First
```typescript
// src/path/to/file.test.ts
test('description of expected behavior', () => {
// Test code
});Verify failure:
bun test src/path/to/file.test.ts
# Expected: FAIL - function not implementedImplementation
// src/path/to/file.ts
export function featureName() {
// Implementation
}Verify success:
bun test src/path/to/file.test.ts
# Expected: PASSCommit
git add src/path/to/file.ts src/path/to/file.test.ts
git commit -m "Add [feature] with tests"Task 2: ...
## Core Principles
| Principle | Application |
|-----------|-------------|
| DRY | Don't repeat logic; extract helpers |
| YAGNI | Only build what's needed now |
| TDD | Write test → verify fail → implement → verify pass |
| Frequent commits | Commit after each task |
## Task Granularity
Each task should:
- Take 2-5 minutes to complete
- Have a clear, verifiable outcome
- Be completable by someone unfamiliar with codebase
- Include exact file paths
- Include complete code examples
- Include verification commands with expected output
## Output Location
Save plans to:docs/plans/YYYY-MM-DD-feature-name.md
## Execution Handoff
After plan completion, offer two paths:
### Option 1: Subagent-Driven (Same Session)
Fresh subagent per task, maintains plan context."Would you like me to execute this plan using subagent-driven development?"
### Option 2: Parallel Session (Worktree)
Separate worktree for isolated development."Would you like to execute this in a separate worktree session?"
## Plan Components Checklist
- [ ] Clear goal statement
- [ ] Architecture/tech stack context
- [ ] Prerequisites listed
- [ ] Tasks with exact file paths
- [ ] Test code for each task
- [ ] Verification commands with expected output
- [ ] Commit messages for each task
- [ ] No ambiguous instructions
## Code Example Requirements
Every code block must be:
- Complete (not pseudocode)
- Copy-pasteable
- Include imports
- Include types (for TypeScript)
Bad:
```typescript
// Add validation logic hereGood:
import { z } from 'zod';
const UserSchema = z.object({
email: z.string().email(),
name: z.string().min(1),
});
export function validateUser(input: unknown) {
return UserSchema.parse(input);
}Deliberation Mode (RALPLAN-DR)
Activates automatically when the plan touches high-risk areas, or when the user requests "deliberate" or "consensus" planning.
Auto-triggers
| Trigger | Why |
| Auth/security changes | Mistakes are hard to reverse |
| Database migrations | Data loss risk |
| Destructive/irreversible operations | No undo |
| Production deployment changes | User-facing impact |
| Compliance/PII handling | Legal risk |
| Public API changes | Breaking changes for consumers |
What Deliberation Adds
Every plan in deliberation mode includes these additional sections BEFORE the task list:
1. Principles (3-5)
Guiding principles specific to THIS plan, not generic platitudes.
## Principles
1. **Zero-downtime migration** — users must not experience service interruption
2. **Rollback within 5 minutes** — every step must be reversible
3. **Data integrity over speed** — validate before and after each migration step2. Decision Drivers (top 3)
The factors that most influence the architecture choice.
## Decision Drivers
1. **Existing Drizzle ORM patterns** — must stay consistent with schema.ts conventions
2. **Neon's branching capability** — can test migrations on branch before prod
3. **Vercel's 60s function timeout** — constrains migration batch sizes3. Viable Options (>= 2)
At least two options with bounded pros/cons. If only one option is viable, explain why alternatives were rejected.
## Options
### Option A: Incremental migration with dual-write
**Pros:** Zero downtime, reversible, proven pattern
**Cons:** Temporary code complexity, 2-week dual-write period
### Option B: Blue-green schema swap
**Pros:** Clean cutover, no dual-write
**Cons:** Requires Neon branch, brief read-only window (~30s)
### Rejected: Big-bang migration
**Why rejected:** 60s Vercel timeout makes single-shot migration impossible for 50K+ rows4. ADR (Architecture Decision Record)
## ADR
**Decision:** Option A — incremental migration with dual-write
**Drivers:** Neon timeout limits, zero-downtime requirement, team familiarity
**Alternatives considered:** Blue-green swap (viable but higher operational risk), big-bang (rejected — timeout)
**Why chosen:** Lowest risk, most reversible, matches existing patterns in drizzle/migrations/
**Consequences:** 2-week dual-write period, temporary ~15% write latency increase
**Follow-ups:** Remove dual-write code after migration verified (deadline: 2 weeks post-deploy)5. Pre-mortem (high-risk only, 3 scenarios)
## Pre-mortem
1. **Migration times out mid-batch** → Mitigation: batch size < 1000 rows, idempotent batches, checkpoint table
2. **Dual-write divergence** → Mitigation: reconciliation query runs hourly, alerts on mismatch > 0
3. **Rollback needed after partial migration** → Mitigation: old column retained for 2 weeks, reads still work from either6. Expanded Test Plan (high-risk only)
## Test Plan
- **Unit:** Schema validation, migration function logic, batch size handling
- **Integration:** Full migration on Neon branch with production-like data
- **E2E:** User workflow before/during/after migration
- **Observability:** Migration progress dashboard, error rate alerts, latency monitoringQuality Gates
Every plan (deliberation or not) must meet:
| Gate | Standard |
| Evidence grounding | 80%+ claims cite file:line |
| Testability | 90%+ acceptance criteria are concrete (no "fast" — use "p99 < 200ms") |
| Risk coverage | All identified risks have mitigations |
| Specificity | No vague terms without metrics |
| Step sizing | Steps sized to actual scope (not always exactly 5) |
Source
Adapted from https://github.com/obra/superpowers (MIT, Copyright (c) 2025 Jesse Vincent). Changed for this repo by Lucas Cooper-Bey in 2026: wording rewritten, keeping the same plan premise, task size, and output path.
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.

