plan

name	plan
description	Use when the user wants a plan instead of execution, or before any non-trivial implementation (multi-file, architectural choice, > 15 min). Writes a concrete actionable markdown plan with bite-sized tasks (2-5 min each), exact file paths, complete code, and verification steps. Adapted from Hermes Agent / obra/superpowers.
lastReviewed	2026-08-15T00:00:00.000Z

Plan Mode

Use this skill when the user asks for a plan, says "design before building", types /plan, or when the work obviously spans multiple files / requires architectural choice / will take more than ~15 minutes.

Core behavior

For this turn, you are planning only.

• Do not implement code
• Do not edit project files except the plan markdown file
• Do not run mutating terminal commands, commit, push, or perform external actions without explicit user approval in a separate execution turn
• You may inspect the repo or other context with read-only commands when needed
• Your deliverable is a markdown plan saved to a project-appropriate docs location

Output requirements

Write a markdown plan that is concrete and actionable.

Include, when relevant:

• Goal
• Current context / assumptions
• Proposed approach
• Step-by-step plan
• Files likely to change
• Tests / validation
• Risks, tradeoffs, and open questions

If the task is code-related, include exact file paths, likely test targets, and verification steps.

Save location

Save the plan under the repo's docs/ directory:

• docs/plans/YYYY-MM-DD-<slug>.md for plans tied to a specific date
• docs/plans/PLAN-<feature>.md for living plans that get re-edited as the work progresses
• docs/history/YYYY-MM-DD-<slug>.md if the repo uses docs/history/ as its archive convention

If the repo has no docs/ folder, create one. If the user names a different target path, use that exactly.

Interaction style

• If the request is clear enough, write the plan directly
• If no explicit instruction accompanies /plan, infer the task from the current conversation context
• If it is genuinely underspecified, ask one brief clarifying question instead of guessing
• After saving the plan, reply briefly with what you planned and the saved path

---

Writing the Plan Well

The rest of this skill is the craft of authoring a good implementation plan — the content that goes inside the markdown file above.

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.

When a Full Implementation Plan Helps

Always use before:

• Implementing multi-step features
• Breaking down complex requirements
• Delegating work to a worker subagent

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.

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
• "Propose a commit boundary" — step, only after explicit user approval

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

**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: Propose a commit boundary**

```bash
git status --short
git diff --check
```

State the suggested commit scope and message. Run `git add` or `git commit` only
after the user explicitly authorizes that action.

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 workspace's search and read tools to understand the project:

• Understand project structure — list/glob files under relevant directories
• Look at similar features — search for related patterns
• Check existing tests — find the test directory and conventions
• Read key files — open the main entry points

Step 3: Design Approach

Decide:

• Architecture pattern
• File organization
• Dependencies needed
• Testing strategy

Step 4: Write Tasks

Create tasks in order:

1. Setup/infrastructure
2. Core functionality (TDD for each)
3. Edge cases
4. Integration
5. 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)
• File paths are exact
• Code examples are complete (copy-pasteable)
• Commands are exact with expected output
• No missing context
• DRY, YAGNI, TDD principles applied

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 = email

TDD (Test-Driven Development)

Every task that produces code should include the full TDD cycle:

1. Write failing test
2. Run to verify failure
3. Write minimal code
4. Run to verify pass

(See the test-driven-development skill for details.)

Commit Boundaries

After a cohesive implementation unit, propose a commit boundary. Do not commit from plan mode or assume permission carries from code-edit approval to Git write approval.

git status --short
git diff --check

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 to docs/plans/<slug>.md. Ready to execute task by task with TDD and verification. I will propose a commit boundary after each cohesive unit if you want one."

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

Would Revise If

Revisit by 2026-11-15 if plans still cause unauthorized mutations, task granularity makes verification impractical, or users repeatedly need a different planning format for multi-repository work.