---
name: planning
description: "Write actionable, bite-sized implementation plans before coding — merged from plan + writing-plans. Plan-only mode, subagent handoff, TDD workflow."
version: 2.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [planning, plan-mode, implementation, workflow, design, documentation]
    related_skills: [subagent-driven-development, test-driven-development, requesting-code-review]
---

# Planning

Use this skill when the user wants a plan instead of execution, or when creating detailed implementation plans for complex features.

## Core behavior

### Plan Mode
When invoked as a plan-only request:
- 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/`.

### Implementation Plan Mode
When writing a full implementation plan (for delegation or reference):

**Core principle:** A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.

**Each task = 2-5 minutes of focused work.**
- "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 Structure

### Header (Required)
```markdown
# [Feature Name] Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this 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:

```markdown
### 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`
- Test: `tests/path/to/test_file.py`

**Step 1: Write failing test** — [full code]
**Step 2: Run test to verify failure** — [exact command, expected FAIL]
**Step 3: Write minimal implementation** — [full code]
**Step 4: Run test to verify pass** — [exact command, expected PASS]
**Step 5: Commit** — [git add + commit command]
```

## Rules

- Prefer bite-sized, independently testable steps over a single giant plan
- Each step should have a clear "done" signal (builds, passes test, visible change)
- Flag blocking dependencies explicitly
- Estimate complexity: Easy, Moderate, Difficult
- Keep the plan in `.hermes/plans/<date>-<topic>.md`
- Update the plan as you go — don't let it go stale
- When the plan is approved, execute step by step, not all at once
- Include exact file paths, complete code examples, exact commands with expected output
- Apply DRY, YAGNI, TDD principles
- Specify exact API signatures for third-party libraries (subagents will guess differently)

## Save Location

Save plan with `write_file` under `.hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md`

## Execution Handoff

After saving the plan, offer: "Plan complete. Execute via subagent-driven-development with two-stage review?"

When the user says "Complete all phases" or "execute all phases", do NOT ask for confirmation between phases — execute the entire plan autonomously.

## Session Reset / Continuity Handoff

When the user says they are resetting, starting a new session, or asks to "document everything":
1. Create/update `SESSION_HANDOFF.md` — current phase, verified state, architecture rules
2. Create/update `docs/PROJECT_CONTEXT.md` — stable product purpose, standards
3. Create `docs/NEXT_SESSION_START.md` — exact first commands/files to read after reset
4. Create/update `docs/plans/<NEXT_PHASE>_PLAN.md` — continuation plan
5. Verify README is not stale
6. Check all handoff surfaces agree with each other
7. Commit with appropriate message

## Pitfalls

- Vague tasks ("Add authentication") — always decompose into specific, sequential steps
- Incomplete code — include exact copy-pasteable code blocks
- Missing verification — include exact commands with expected output
- Missing file paths — never say "create the model file", say "Create: `src/models/user.py`"
- Missing API signatures — include exact import paths and constructor syntax for third-party libraries
- Stale handoff docs — actively hunt for old phase names, commit SHAs, test counts across ALL handoff surfaces
- **Web scraping / API integration plans must be spike-validated.** Do NOT assume a site is scrapable because web_extract or a proxy returned data — web_extract uses residential proxies that your local server doesn't have. Before writing a plan that includes scrapers, run the spike skill's `references/live-site-validation.md` escalation ladder against every target site. A plan with broken scrapers wastes hours of implementation. In 2026-07, a plan claimed Zillow was scrapable via aiohttp+BS4 because web_extract returned listing data; live spike testing proved PerimeterX blocks every approach (aiohttp, Playwright headless, Playwright non-headless, FlareSolverr, mobile UA, internal APIs all 403).

## Principles
- DRY — extract repeated logic, don't copy-paste
- YAGNI — implement only what's needed now
- TDD — write failing test first, then minimal implementation
- Frequent commits — commit after every task

## References
- `subagent-driven-development` — for delegation
- `test-driven-development` — for TDD workflow
- `requesting-code-review` — for pre-commit verification