Plan Mode

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

Which Planning Pattern?

Planning tasks come in 4 shapes on a lightness scale. This skill (/plan) is the lightest. Pick the lightest pattern that fits; escalate only when the lighter one proves insufficient.

Decision rule:

1. Is the design space OPEN or CLOSED?
   • CLOSED → /plan
   • OPEN → continue
2. For OPEN — is the decision small (1-2 turns) or big (plan file)?
   • SMALL → /pulse
   • BIG → continue
3. For BIG open design — is it multi-domain, multi-worker, fuzzy goal, or >1 day?
   • YES → /deepthink (full)
   • NO → /shape

If a user explicitly invokes "deepthink" but the task fits /plan scope, surface the choice in one sentence before proceeding: "You asked for deepthink; this task is borderline /plan. I'll run the shape pattern and skip the ceremony that doesn't fit. Speak up if you want the full 9-phase." This respects the explicit ask while still exercising judgment on the parts that don't fit.

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

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.

If the runtime provides a specific target path, use that exact path. If not, create a sensible timestamped filename yourself under .hermes/plans/.

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.
• 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 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: Pre-Finalize External Review (for non-trivial plans)

The internal review checklist above catches internal consistency, but a plan that reads cleanly can still be wrong about the codebase (see "Plan References Code That Doesn't Exist" below) or over-scoped (every multi-task plan in this codebase so far has been). For plans with 5+ tasks, multi-file edits, or architectural decisions, run an external review pass before declaring the plan done:

1. Code audit — read the actual code files the plan touches. Grep for every identifier, data field, and function name the plan references. Confirm line numbers. If the plan says line 318 but the function moved, fix the plan before the implementer hits the wall at execution time.
2. Multi-model review — load the multi-model-review skill and run a 2-seat huddle with the plan + audit findings as context. The naysayer seat will surface concerns you missed. See that skill's "Pitfalls" and "Single-Voice Limitation" sections.
3. Measure the constraints — get real numbers (file sizes, build time, headroom under limits), not estimates. A 30-line Python one-liner that loads the existing JSON and reports len(json.dumps(d)) / 1024 / 1024 is usually enough.
4. Synthesize — combine the audit, the huddle, and the measurements into actionable revisions. If the user asked for a v(N) plan, the diff since v(N-1) should be the first thing in the new file's header.
5. Update the plan — either create v(N+1) as a new timestamped file (preferred, keeps iteration trail) or patch the current file in place if the user explicitly asked for a targeted edit.

When the user says "review the plan with the huddle" or "check the plan against the code" or anything similar, this is the workflow they want. Don't skip the code audit — the huddle without ground-truth from the actual codebase produces recommendations that sound right but cite fields that don't exist.

When the plan is for a static-site-cdn-deploy architecture, the pre-finalize review is non-negotiable: small data field additions add up against the 25MB Cloudflare file limit, and a plan that promises "8 new charts" without measuring the JSON size impact will deploy something that breaks.

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"

Plan References Code That Doesn't Exist

Plans that read logically can still be wrong if their concrete references don't match the codebase. Always verify every identifier, function name, data field, and class member against the actual source before finalizing.

Common symptoms found in real audits:

Mandatory pre-finalize audit (2-5 min, often the most valuable step in the whole plan):

1. For every Modify: entry, read the actual file and confirm the target identifier exists at the stated line. If your plan says line 318 but the function moved, cite the new line — or your first implementation attempt will fail.
2. For every JS function/variable mentioned by name, grep for it. If you wrote escHtml(text) and the codebase has esc(txt), fix it.
3. For every data field mentioned (e.g. _data.daily_counts, user.max_streak), grep the build script for it. If the field doesn't exist, either add a "compute it" pre-step or change the plan to derive it client-side.
4. For every UI render call, identify ALL the render paths for that data. Profile cards, modals, lookup sidebars, and the leaderboard often have independent copies of the same render logic. List every callsite in the plan so the implementer updates all of them, not just the one they spotted.

Doing this audit catches 80% of the bugs that would otherwise surface only at "Step 1: Run it to make sure it fails" of the first task — when the implementer discovers the plan was wrong about the codebase.

When the Plan Is for a Static-Site-CDN Architecture

If the project matches static-site-cdn-deploy (build step generates JSON, frontend is vanilla JS, deploys to Cloudflare Pages/Netlify/Vercel, scheduled CI rebuild):

• Add an ## Architecture Cross-Check subsection to the plan that names the JSON files, their size limits, the rebuild cadence, and the deploy hook URL. The implementer needs all four to verify their changes end-to-end.
• Size headroom: every additive change to search-data.json should be measured in advance, not at deploy. A 30-line Python one-liner that loads the existing JSON and reports len(json.dumps(d)) / 1024 / 1024 is sufficient.
• Verify the build command in Cloudflare Pages settings matches what the plan assumes. If the plan expects the build to run python3 build_index.py /tmp/chunks.jsonl, the CF build command MUST produce that file path. Drift here causes deploys to silently generate stale data.
• Add a tiny QA script (qa.py) as Task 0 in the plan. It loads the generated JSON and asserts expected fields are present. Every subsequent task's verification step runs it.

Plan Iteration Trail

When a plan is revised (user feedback, audit findings, new requirements), keep the old plan file with a fresh timestamped copy of the new version rather than overwriting in place.

Why:

• Reviewers and future sessions can see what was learned between versions (audit trail).
• Reverting or referencing a prior version is trivial.
• The user can see the diff path: "I want v3" or "show me what changed between v1 and v2."

Naming convention:

.hermes/plans/
  2026-06-08_234500-feature-next-version.md    # v1, 834 lines
  2026-06-09_121500-feature-v2.md              # v2, 1016 lines
  2026-06-09_125000-feature-v3.md              # v3, 1370 lines

When asked "apply as v3 or patch in place?", prefer v3 (new file) unless the user explicitly asks for a patch. v3 keeps the iteration trail; patch loses it. Only patch in place when the user wants a small targeted edit to a specific section (e.g. "just add a verification step to Task 4").

In the new version's header, briefly cite what changed since the previous version — a 3-bullet diff summary. This is what reviewers read first.

Execution Handoff

After saving the plan, the user will usually respond with one of:

• "ok run it" / "execute the plan" / "ok lets run our plans on the codebase" — they want direct execution in this same session
• "dispatch to subagents" / explicit mention of subagent-driven-development — they want fresh-context-per-task
• Silence — they may want to review the plan more, or test something else first. Don't start executing on your own.

The two modes are different in setup, observability, and what survives a session crash. Pick the right one and be explicit about which you're doing.

Direct Execution Mode (default when the user says "run it")

Execute the plan in this same session using your existing tools (patch, write_file, terminal, read_file, etc.). Pattern that works:

1. Set up a todo list with one item per plan task (plus a final "push + verify deploy" item). Mark in_progress as you start each, completed as you commit. The user can see progress and the order is preserved across interruptions.
2. One commit per task. git add <specific files> (not -A) + git commit -m "<task's planned message>". Specific paths make the safety filter happier than wildcards and make the commit history readable.
3. Run the task's verification step BEFORE the commit. If the plan said python3 qa.py runs green, confirm it does. If the plan said "browser shows X," take a screenshot or curl the rendered output. The commit should be the LAST step of a task, not the first.
4. Push at milestone gates, not after every task. The plan should have explicit "Milestone Gate" tasks (e.g. "push + verify before T8"). Push at those, not in between. This keeps git push noise low and gives the user natural check-in points.
5. Trigger the deploy at the final milestone. If the project deploys via CI (Cloudflare Pages, Netlify, etc.), trigger the workflow after the final push. Don't wait for a cron.
6. Verify on the live site. curl the deployed URL and check that the rendered output matches what the plan promised. The workflow "succeeded" log is not proof — the build could have used a stale data file or a typo'd selector.

Pattern for the git push step at a milestone:

git push origin main
gh workflow run "<your-deploy-workflow-name>" --repo <org>/<repo>
# Wait for workflow to complete
sleep 60 && gh run view <run-id> --repo <org>/<repo> --json status,conclusion
# Verify live site
curl -s https://<project>.pages.dev/ | grep -c "<expected-element>"

Replace <your-deploy-workflow-name> with the actual CI/CD trigger for the project — this example assumes Cloudflare Pages but the pattern generalizes to any push-triggered deploy.

When to Dispatch to a Subagent Instead

The subagent-driven-development pattern is right when:

• The plan has 10+ tasks and the user wants parallel execution
• Each task is independent enough that fresh context per task is valuable
• The user explicitly asks for it
• A previous direct-execution attempt got stuck on context limits (the plan was so big that you started forgetting earlier task context)

For smaller plans (≤10 tasks) where the user just said "run it," direct execution is faster, more observable, and easier to debug if something goes wrong mid-stream.

Pitfalls

• "Do not implement" is for the planning pass, not after approval. The Core Behavior rule against implementation applies to the turn you were asked to plan. Once the user has approved the plan and asked you to run it, the rule no longer binds.
• Composite shell commands get blocked. cmd1 && cmd2 && cmd3 is one safety filter hit. Break into separate terminal calls. If a multi-step pipeline keeps getting denied, separate each command: one for git add, one for git commit, one for git push.
• Wildcard git add -A is fine, git add build_index.py search-data.json is better. Specific paths keep the safety filter happy AND make the commit history self-documenting.
• Skip the verification step at your peril. Every plan I have shipped has had at least one bug caught only by running the verification. If the plan said "browser shows trending tags" and the curl response doesn't include the trending HTML, that means the deploy didn't actually pick up your changes — and you want to find that before telling the user it's done.
• Subagent dispatch may be blocked by the safety filter (e.g. hermes chat -q "..." or opencode run). If you can't dispatch, default to direct execution — the user wants the work done, not the orchestration pattern.

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.

References

• references/research-design-plan-structure.md — for "figure out what to build" tasks (research/design/architect) rather than "build this exact thing." The 7-section structure (Goal → Reusable → New → Architecture → Phased → Decisions → Anti-patterns → Appendices). Use when the user asks for a plan on a NEW project, a pivot, or an investigation — not for feature implementation.