Back to Workflow & Productivity
writing-plans
planningworkflowimplementation plantask breakdowndeveloper documentationcoding strategysoftware engineeringproject management
Install this skill
npx skills add obra/superpowersWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
The writing-plans skill standardizes how technical tasks are broken down within the obra/superpowers ecosystem. It generates highly granular, test-driven implementation roadmaps for developers who may lack specific codebase knowledge. By enforcing a strict structure that mandates file paths, exact code snippets, and TDD steps, it minimizes ambiguity and prevents scope creep. Every plan follows a mandated header format and includes specific verification commands for each action, ensuring the logic remains verifiable at every stage. The skill serves as a bridge between high-level feature requirements and concrete execution, facilitating a workflow where developers can rely on predefined, bite-sized tasks to reach completion without guessing the internal architecture or testing expectations. It prioritizes clarity and repeatability, demanding that every modification is validated through an immediate test cycle and git commit.
When to Use This Skill
- β’Implementing a new feature in an unfamiliar codebase
- β’Breaking down complex refactoring into manageable units
- β’Onboarding a developer to a specific subsystem via a guided plan
- β’Standardizing PR-ready development cycles for large team tasks
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- βCreate an implementation plan for this new feature
- βWrite a development roadmap for the refactoring task
- βI need a step-by-step plan for the module changes
- βBreak this down into bite-sized tasks with TDD
- βGenerate a plan document for the login system rewrite
Pro Tips
- π‘For complex features, always use the `brainstorming` skill first to gather all requirements and potential edge cases before generating the implementation plan.
- π‘Integrate the 'Bite-Sized Task Granularity' principle diligently; ensure each step is genuinely a small, actionable item (2-5 minutes) to maintain momentum.
- π‘Regularly review the generated plans with team members to ensure alignment, catch any overlooked details, and improve the overall development strategy.
What this skill does
- β’Generates detailed step-by-step implementation roadmaps in Markdown
- β’Forces Test-Driven Development (TDD) by mandating failing-to-passing test cycles
- β’Provides precise file paths and code blocks for every task step
- β’Integrates execution handoffs for subagent or parallel session workflows
- β’Enforces strict YAGNI and DRY principles within the generated plan
When not to use it
- βTasks that are highly exploratory or lack a clear, deterministic output
- βRapid prototyping where strict TDD cycles would hinder velocity
- βOperations that do not involve code modification or testing
Example workflow
- Create a dedicated worktree using the brainstorming skill
- Trigger the writing-plans skill to initialize the plan document
- Review the generated plan for file paths and test coverage
- Save the output to the docs/plans directory
- Select an execution mode (Subagent-Driven or Parallel Session)
- Execute the tasks sequentially using the verified roadmap
Prerequisites
- βA dedicated worktree created via the brainstorming skill
- βExisting test infrastructure within the project
Pitfalls & limitations
- !Over-specifying tasks that require significant architectural iteration
- !Assuming the agent knows deep, undocumented domain context
- !Failing to adapt the plan if early tests reveal unforeseen logic errors
FAQ
Do I need to be in a specific folder?
Yes, always run this skill within a dedicated worktree initialized by the brainstorming skill.
Can I deviate from the generated task structure?
The structure is mandatory to ensure compatibility with subagent-driven development; modifying it may break the execution handoff.
What happens if a test is hard to write?
If you cannot write a failing test, the plan is likely too broad; break it down into smaller, verifiable chunks.
How does this differ from standard LLM coding?
Standard coding prompts often hallucinate paths or skip tests; this skill mandates an explicit, documented verification cycle before any code is committed.
How it compares
Unlike generic prompting, which often leads to 'write this feature' results, this skill enforces an immutable architectural contract and verification protocol that minimizes human intervention.
π Full skill instructions β original source: obra/superpowers
# Writing Plans
## Overview
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
**Save plans to:**
## Bite-Sized Task Granularity
**Each step is one action (2-5 minutes):**
- "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
## Plan Document Header
**Every plan MUST start with this header:**
## Task Structure
def test_specific_behavior():
result = function(input)
assert result == expected
def function(input):
return expected
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Reference relevant skills with @ syntax
- DRY, YAGNI, TDD, frequent commits
## Execution Handoff
After saving the plan, offer execution choice:
**"Plan complete and saved to
**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
**Which approach?"**
**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Stay in this session
- Fresh subagent per task + code review
**If Parallel Session chosen:**
- Guide them to open new session in worktree
- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans
## Overview
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
**Save plans to:**
docs/plans/YYYY-MM-DD-<feature-name>.md## Bite-Sized Task Granularity
**Each step is one action (2-5 minutes):**
- "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
## Plan Document Header
**Every plan MUST start with this header:**
# [Feature Name] Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---## Task Structure
### Task N: [Component Name]
**Files:**
- Create: exact/path/to/file.py
- Modify: exact/path/to/existing.py:123-145
- Test: tests/exact/path/to/test.py
**Step 1: Write the failing test**def test_specific_behavior():
result = function(input)
assert result == expected
**Step 2: Run test to verify it fails**
Run: pytest tests/path/test.py::test_name -v
Expected: FAIL with "function not defined"
**Step 3: Write minimal implementation**def function(input):
return expected
**Step 4: Run test to verify it passes**
Run: pytest tests/path/test.py::test_name -v
Expected: PASS
**Step 5: Commit**git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Reference relevant skills with @ syntax
- DRY, YAGNI, TDD, frequent commits
## Execution Handoff
After saving the plan, offer execution choice:
**"Plan complete and saved to
docs/plans/<filename>.md. Two execution options:****1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
**Which approach?"**
**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Stay in this session
- Fresh subagent per task + code review
**If Parallel Session chosen:**
- Guide them to open new session in worktree
- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/writing-plans/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/obra/superpowers/writing-plans/SKILL.md - Cursor:
~/.cursor/skills/obra/superpowers/writing-plans/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/obra/superpowers/writing-plans/SKILL.md
π Install with CLI:npx skills add obra/superpowers
Recommended Rules
View more rules βStrong Reasoner & Planner Agent (Official Google Template)
Agentic AIReasoningPlanning
You are a very strong reasoner and planner. Use these critical instructions to structure your plans, thoughts, and responses. π Source: Google Gemin...
Advanced AWS Integration (EventBridge, Step Functions)
AWSIntegrationServerless
You are an expert in advanced AWS integration services and patterns. Key Principles: - Choreography (Events) vs Orchestration (Workflows) - Decouplin...
Antigravity Workflow Fundamentals
WorkflowsAutomationBest Practices
You are an expert in creating Antigravity Workflows. Key Principles: - Workflows are step-by-step recipes for complex tasks - Must be in .agent/workf...
Recommended Workflows
View more workflows βDebug Module Not Found Errors
Node.jsDebuggingDependencies
--- description: Systematically resolve "Cannot find module" errors --- 1. **Check the Import Path**: - β `import { foo } from '../components/Foo'...
Debug API Issues with Network Tab
APIDebuggingDevTools
--- description: Master Chrome DevTools Network tab for API debugging --- 1. **Open Network Tab**: - Press F12 β Network tab. - Reload the page...
Debug Slow API Routes (Performance Profiling)
PerformanceAPIProfiling
--- description: Profile and optimize slow API endpoints --- 1. **Add Timing Logs**: - Measure execution time. ```ts export async function G...
