writing-plans

name	writing-plans
description	UMBRELLA: Write implementation plans AND execute them via subagents — bite-sized tasks, TDD, two-stage review. Covers planning methodology and subagent-driven execution workflow.
version	1.2.0
author	Hermes Agent (adapted from obra/superpowers)
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["planning","design","implementation","workflow","documentation","subagent","delegation"],"related_skills":["test-driven-development","requesting-code-review"]}}

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.

When to Use

Always use before:

• Implementing multi-step features
• Breaking down complex requirements
• Delegating to subagents via subagent-driven-development

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
• "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 Hermes:** Use subagent-driven-development skill 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

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 Hermes tools to understand the project:

# Understand project structure
search_files("*.py", target="files", path="src/")

# Look at similar features
search_files("similar_pattern", path="src/", file_glob="*.py")

# Check existing tests
search_files("*.py", target="files", path="tests/")

# Read key files
read_file("src/app.py")

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

Step 7: Save the Plan

mkdir -p docs/plans
# Save plan to docs/plans/YYYY-MM-DD-feature-name.md
git add docs/plans/
git commit -m "docs: add implementation plan for [feature]"

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 test-driven-development skill for details.

Frequent Commits

Commit after every task:

git add [files]
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"

Hidden Runtime Dependencies Between Steps

Problem: A step that "just removes config" appears safe on paper but breaks a later step that still depends on that config at runtime.

Example: A plan that puts "Remove AI model bindings from wrangler.toml" in Step 1 and "Deploy client-side RAG" in Step 4. The removal breaks production server-side RAG that still needs those bindings until Step 4 is deployed. If the plan is followed linearly, production degrades silently between Step 1 and Step 4.

Fix: Before reordering steps:

• Check what production services still depend on the resource being removed
• Check for overlap periods where both old and new systems need the resource
• Defer removal until the last step that no longer needs it

Symlink-before-remove pattern: When converging duplicate config files:

1. Create the symlink/alias from canonical source first
2. Verify the deployment pipeline works with the symlink
3. Then remove the old file

This prevents the "this file is dead code except for the one CI job I forgot about" failure mode.

Execution Handoff

Execution Handoff

After saving the plan, offer the execution approach: "Plan complete and saved. Ready to execute using subagent-driven-development — I'll dispatch 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 delegate_task per task with full context
• Spec compliance review after each task
• Code quality review after spec passes
• Proceed only when both reviews approve

Execution Path Decision

I (Hermes) execute directly when:

• Tasks are standard file creation, script running, or git ops (no complex multi-step reasoning)
• Context window is still fresh — I can handle 10-20 file writes without degradation
• Token budget is comfortable — I avoid polluting my context with implementation churn

Delegate to Claude Code (-p print mode) when:

• Plan has 20+ tasks and the context window will get long
• CC is better suited to the task (complex refactoring, CC-specific features)
• User explicitly asks to "交给 CC 执行"

Delegate to Claude Code (interactive tmux relay) when:

• Multi-turn exploratory session needed (CC reads files, reasons, asks questions)
• User needs real-time visibility into CC's work
• Only for exploratory sessions — never for sequential implementation plans

Relay mode anti-pattern: OMC brainstorming/plan skills are NOT relay-compatible. Use superpowers-brainstorming instead (I act as facilitator, ask the user questions one-by-one, record answers into the spec).

Plan Mode (absorbed from plan skill)

When the user explicitly asks for a plan instead of execution (/plan or "write a plan first"):

• Do not implement code or edit project files (except the plan file)
• Do not run mutating terminal commands, commit, push, or perform external actions
• Inspect the repo with read-only tools only
• Deliverable is a markdown plan under .hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md
• Include: Goal, context/assumptions, approach, step-by-step, files likely to change, tests/validation, risks/open questions
• After saving, reply briefly with what you planned and the saved path

Archived Sub-Skills

Subagent-Driven Development (absorbed subagent-driven-development)

The execution counterpart to planning — dispatch fresh subagents per task with systematic two-stage review (spec compliance → code quality). The full original SKILL.md is archived under ~/.hermes/skills/.archive/subagent-driven-development/.

Preserved reference files in references/:

• references/gates-taxonomy.md — Four canonical gate types (Pre-flight, Revision, Escalation, Abort) with behavior, recovery, and examples
• references/context-budget-discipline.md — Four-tier context degradation model (PEAK / GOOD / DEGRADING / POOR) and read-depth rules

Core process (summary):

1. Parse plan → create todo list from all tasks
2. For each task: dispatch implementer → spec review → quality review → mark done
3. After all tasks: final integration review → verify → commit

Red flags: No execution without a plan. Never skip reviews. Spec compliance FIRST, quality SECOND. Never let implementer self-review replace actual review. Subagent self-reports are not verification — always verify file existence and test results with your own terminal() calls.

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 commits

A good plan makes implementation obvious.