writing-plans

name	writing-plans
description	Write implementation plans that make coding obvious — exact file paths, full code examples, step-by-step commands, expected output. Use before any feature with 3+ files or when delegating to subagents.
license	MIT
source	https://github.com/NousResearch/hermes-agent

Writing Plans

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

Trigger phrases: "write a plan", "implementation plan", "plan before coding", "spec out", "break down task", "planning phase"

---

Plan Template

# Plan: [Feature Name]

## Goal
One sentence: what does this plan deliver?

## Architecture
How does this fit the existing system?

## Constraints
- Language/framework versions
- Libraries to use
- Things NOT to change

---

## Task 1: [Specific Title]

**Objective:** What this accomplishes (1-2 sentences)

**Files:**
- `src/auth/token.ts` — create (new file)
- `src/auth/verify.ts` — modify (add expiry check)
- `tests/auth/token.test.ts` — create

**Implementation:**
```typescript
// src/auth/token.ts
export function createToken(userId: string, expiresIn = '24h'): string {
  return sign({ userId }, process.env.JWT_SECRET!, { expiresIn })
}

Commands:

npm test -- --testPathPattern=auth

Expected output:

PASS tests/auth/token.test.ts
  ✓ creates valid JWT (12ms)

Acceptance criteria:

• Token signed with JWT_SECRET
• Expiry enforced on verify
• Tests pass, no regressions

---

## The 5 Rules

**1. Exact file paths** — not "the auth module" but `src/auth/token.ts`

**2. Copy-pasteable code** — not pseudocode, actual working code

**3. Real commands** — not "run the tests" but `npm test -- --testPathPattern=auth`

**4. Expected output** — what does success look like, exactly?

**5. Atomic tasks** — one task = one person, no file overlap with other tasks

---

## Task Sizing

| Size | Lines changed | Time | Action |
|------|--------------|------|--------|
| Too small | < 5 lines | < 5 min | Merge with adjacent |
| Right | 10–100 lines | 15–60 min | ✓ |
| Too large | > 200 lines | > 2h | Split into 2–3 tasks |

---

## File Conflict Check

Before finalizing — verify no two tasks touch the same file:

Task 1: src/auth/token.ts ✓ Task 2: src/auth/verify.ts ✓ Task 3: src/auth/token.ts ✗ ← conflict with Task 1 → merge or extract

---

## Dependency Map

Task 1 (no deps) ─┐ Task 2 (no deps) ─┤→ Task 4 (needs 1+2) → Task 5 (needs 4) Task 3 (no deps) ─┘

Tasks without deps run in parallel. Always declare dependencies explicitly.

---

## Anti-Fake-Pass

❌ "Update the auth logic" — no file, no code, not actionable ❌ "Add tests" — which tests? what file? what assertions? ❌ One giant task — can't parallelize or review incrementally ❌ Task touching 5+ unrelated files — split it ❌ Expected output is "it should work" — not verifiable ❌ No dependency declaration — parallel agents conflict

## See Also
- `core/rules/golden-principles.md` — Principle 9: plan before code
- `core/skills/kanban-dispatcher/SKILL.md` — execute plans with task board
- `core/agents/spec-planner.md` — planning agent