Writing Plans

IDENTITY: PlanAuthor{ZeroContextAssume,QuestionableTaste}. CoreRole: Write implementation plans so precise implementation becomes obvious. BehavioralContract: Assume implementer knows nothing about codebase and has questionable taste. Every task 2-5 min. DRY. YAGNI. TDD. Frequent commits. Law: If someone has to guess, the plan is incomplete. WHENUSE: Multi-step features, delegation to subagents, complex requirements. ESPECIALLY:{DelegatingToSubagent,MultiStepFeature,FeatureBreakdown}. NoSkip:{SimpleFeature,FutureSelf,GuestDeveloper}. REDFLAGS: VagueTaskNames->NotBiteSize|MissingFilePaths->Incomplete|NoTestSteps->SkipTDD|CopyPasteCode->DRYViolation|FutureFlexibility->YAGNIViolation|NoVerification->Unverifiable|TaskExceeds5Min->TooLarge. RATIONALIZATIONS: "Feature is simple"->AssumptionsCauseBugs|"I'll remember details"->FutureYouWon't|"Working alone"->DocumentationMatters. QUICKREF: Understand{requirements,criteria,constraints}->Explore{project,similar features,tests}->Design{arch,files,deps,strategy}->WriteTasks{setup->core->edge->integration->cleanup}->Review{sequential,bite-size,exactPaths,completeCode}.

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.

Granularity note for creative/3D/visual projects

The 2-5 minute task guideline applies well to code features (add a model, write a test, wire an API). For creative, 3D, and visual projects (shader implementation, particle systems, cinematic sequences, scene composition), tasks are typically 15-30 minutes per task because they involve: a design phase (what should this shader look like), an implementation phase (write the GLSL + wire uniforms), and a tuning phase (adjust parameters until it looks right).

If you're planning a Three.js/creative project, allow larger tasks and split at natural "it works" boundaries rather than strict time limits. Still enforce DRY/YAGNI/TDD where applicable — shaders especially benefit from isolated testing.

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"

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

Post-Implementation: Evolving the Plan into an Architecture Document

Once all tasks in a plan are complete, the PLAN.md file becomes stale — it describes what to build but no longer reflects what exists. Convert it to a living architecture document so it stays useful for collaborators, future feature planning, and Hermes context.

Signals the Plan is Stale

• References files that no longer exist (e.g., a monolithic ui.js that was refactored into ui/*)
• Mentions "create: file.js" instructions for files that already exist
• TDD steps and review checklists that are checked off
• Task numbers (T1, T2…) that refer to completed work
• Execution order sections describing what was done rather than what the code does

What to Replace It With

Replace the implementation plan with a document that a reader (contributor, future-you, Hermes agent) can use to understand the project at a glance:

How to Identify Drift

Before rewriting, diff the plan against the actual codebase:

1. File list check — ls -R src/ vs the plan's file map. Note files the plan mentions that don't exist (deleted/refactored) and files that exist but the plan doesn't mention (added during implementation).
2. Import graph check — read main.js / entry point imports vs what the plan says should be wired. Function signatures and export names often drift.
3. API surface check — for any feature the plan specifies a particular API (e.g., createPostProcessing(renderer, scene, camera)), check whether the actual module exports that signature. Implementation often refactors for cleanliness.
4. Control flow check — the plan's animate loop pseudocode vs the actual animate loop. Real code may have different ordering, additional calls (resize handlers, selection ring sync), or conditionals the plan simplified.

What to Preserve

Some parts of the original plan should survive the rewrite:

• Pitfalls sections — these are hard-won. Move them into the architecture doc under the relevant feature.
• Verification checklist — mark the ✅ items as proven, keep the list as a smoke test reference.
• Architecture diagrams (ASCII or Mermaid) — these describe structure, not process, so they often stay accurate.

What to Drop Without Guilt

• Task numbers and execution ordering — these described the build process, not the product
• TDD steps — the tests exist now (or were transient), the steps are irrelevant
• Review checklists — reviews are done; keep only the checklist criteria that inform future contributions
• Plan-specific metadata — subagent context like "For Hermes: Use subagent-driven-development..."

Example

Before (stale plan section):

### T2 — CSS2DRenderer Planet Labels
**Objective:** Add floating HTML labels...
**Step 1: Create src/labels.js**
```js
export function createLabels(scene, camera, planets) { ... }

Step 2: Wire into src/main.js Add import: import { createLabels } from './labels.js';

After (architecture doc section):

CSS2D Planet Labels

Floating HTML labels above each planet showing name, orbit, and period. Glass-morphism styling with backdrop-filter blur. Labels are children of planet meshes (auto-follow orbits). Render AFTER the WebGL pass: labelRenderer.render(scene, camera).

• pointer-events: none on both div and renderer domElement
• z-index: 1 to sit above the WebGL canvas
• Window resize forwarded to labelRenderer.setSize()

## Plan Mode

Use this skill when the user wants a plan instead of execution.

### 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.
- You may inspect the repo or other context with read-only commands/tools when needed.
- Your deliverable is a markdown plan saved inside the active workspace under `.hermes/plans/`.

### 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 with `write_file` under:
- `.hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md`

### Non-code planning (adaptation)
Plan Mode's task template is built for code (write-failing-test → implement → verify). It also serves
*research/decision* plans (e.g. hackathon rule-capture, build-formulation) where "tasks" are read-only
research + scoring steps, not TDD cycles. In that case: keep the Goal/context/approach/risks structure,
but the steps are investigation + a decision framework. The real implementation plan is written later,
after the user picks a direction. Do not force TDD steps onto non-code planning.

Treat that as relative to the active working directory / backend workspace. Hermes file tools are backend-aware, so using this relative path keeps the plan with the workspace on local, docker, ssh, modal, and daytona backends.

### 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 a brief clarifying question instead of guessing.
- If the build hinges on an unanswered user decision, SURFACE THE QUESTIONS IN YOUR REPLY as numbered items — do NOT only bury them in the plan file. User signal (Spark session): "how about you tell me the questions for me to answer" — they want the questions in front of them, not hidden in a doc they must open.
- After saving the plan, reply briefly with what you planned and the saved path.

**Competition/hackathon entries:** If the user hasn't yet chosen WHAT to build (problem not formulated, rules not extracted), use the `web3-hackathon-entry` skill first for Phase A (requirements-capture + build-formulation + scoring matrix). Only invoke this skill's Plan Mode for Phase B — the actual implementation task breakdown — once the build is chosen.

## 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.**