Caveman Plan

Large project = Epic → Plans → Hunts → Inventory. Load `caveman` skill — speak caveman to Boss during workflow (lite OK for checkpoints). Load `superpowers-plan` — each plan_*.md task uses its step format (files, change, verify).

Claude /goal mode

When: agent is Claude and /goal is available and enabled → drive workflow with /goal. Otherwise use manual Boss checkpoints below.

Set goal once at workflow start (after Boss gives project prompt):

/goal Epic file created. All plan files created. Every checkbox in epic and every plan checked off.

Work toward that goal across phases. Do not mark goal done until Inventory passes.

Between hunts (goal mode): After STOP 1 (Follow Ups), end turn. Boss advances with:

NEXT HUNT!

Treat NEXT HUNT! like Boss approval for STOP 2 — set next plan current in manifest, begin that hunt only. Until Boss says it, do not open next plan_*.md.

Goal mode vs manual checkpoints:

Hunt turn limit (mandatory)

Track turns per hunt — one turn = one agent response while plan_*.md is current in manifest.

1. At hunt start, set in plans-manifest.md under hunt status: turns: 0 / 3 for current plan (or append column).
2. Each agent response on that plan before hunt complete: increment. Example: turns: 2 / 3.
3. Turn 3 reached and plan not fully killed (open tasks or unresolved Follow Ups) → STOP hunt immediately. No more tasks this hunt. Report blockers. Ask Boss: split plan, clarify Follow Ups, or reset hunt.

## Hunt complete: `plan_<name>.md` (turn limit)

**Turns:** 3/3 — hunt stopped (limit).
**Open tasks:** (list unchecked)
**Follow Ups:** (list)
Boss: split plan / answer Follow Ups / say NEXT HUNT! after fix?

Do not start next plan until Boss responds. After Boss fixes scope, reset that plan to turns: 0 / 3 when re-hunting same file.

When to use

• Multi-file or multi-session work
• Behavior, auth, billing, or production impact
• Boss wants phased approval before code

Phase 1 — Epic

1. Read Boss prompt. Load caveman skill for voice.
2. Ensure .plans/ is in .gitignore at repo root (create or append line .plans/ if missing). Planning artifacts stay local — do not commit.
3. Create .plans/epic_<short-slug>.md (slug = kebab-case topic, no spaces).

File shape:

# Epic: <title>

## Goal

<verbatim Boss prompt — copy exact wording, do not paraphrase>

## Steps

- [ ] Step 1 — <one line: what + rough complexity hint (S/M/L)>
- [ ] Step 2 — ...

Epic rules:

• Steps = top-level checklist only. Enough for another caveman to gauge complexity; no file paths, no sub-tasks yet.
• Token-tight: one line per step.
• STOP. Ask Boss: want changes to Epic before planning begins? Do not create Plans until Boss OK (or Boss edits Epic).

Phase 2 — Plans

After Boss approves Epic:

1. Create folder .plans/epic_<short-slug>/ (same basename as epic file, minus .md).
2. Split rule (mandatory): Create multiple plan_<topic>.md files — one hunt file per Epic Steps line item minimum.

• Epic has N steps → you need ≥ N plan files before Boss checkpoint (usually exactly N).
• Step marked L → split into 2–3 plans (e.g. data / API / UI) — counts toward ≥ N.
• Step marked S and truly trivial → may stay one plan for that step only.
• Forbidden: one plan_*.md covering 2+ Epic steps unless Boss explicitly asked to combine.

1. Write plans-manifest.md in the epic folder before asking Boss to hunt:

# Plans manifest

| Epic step | Plan file(s) |
|-----------|--------------|
| <copy epic step line> | `plan_<topic>.md` |

## Hunt status

| Plan file | Status | Turns |
|-----------|--------|-------|
| `plan_<first>.md` | **current** | 0/3 |
| `plan_<other>.md` | pending | — |

Every Epic step row must appear exactly once. If manifest rows < Epic steps, Phase 2 not done — split plans. Exactly one `current` plan before first hunt.
4. Each plan = one focused hunt. Header must name its Epic step. Use superpowers-plan rules inside:

Plan: <title>

Epic step: <which Epic Step line(s) this plan serves>

Assumptions

(only if non-obvious)

Hunt checklist

• [ ] Task name
• Files: path/to/file
• Change: (1–2 bullets)
• Verify: exact command or check

Risks & mitigations

(brief, if any)

Rollback

(one line if risky)

5. **Self-check before STOP:** Count `plan_*.md` in epic folder (exclude `plans-manifest.md`). If count < Epic step count → split; do not proceed.
6. **STOP.** Show Boss: manifest table + plan filenames. Ask: time to go hunting?

Templates: [reference.md](reference.md)

## Phase 3 — Hunts

**One hunt** = exactly **one** `plan_*.md` file, then **end turn**. Boss must reply before next hunt starts.

### Hunt boundaries (mandatory)

| Allowed in one hunt | Forbidden until Boss replies |
|---------------------|------------------------------|
| Tasks inside **current** `plan_*.md` only | Open or edit next `plan_*.md` |
| Code/files for current plan tasks | "While I'm here" work on other plans |
| Update current plan checkboxes + Follow Ups | Start Inventory (Phase 4) |
| Update `plans-manifest.md` hunt status | Batch multiple plans in one response |

**Hard stop:** After hunt ends, **stop all tool use and implementation**. End message to Boss. **Wait for Boss reply.** Next hunt only when Boss says go (e.g. "next hunt", "continue", "yes").

### Hunt status (track in `plans-manifest.md`)

Keep a `## Hunt status` section. Exactly one plan `current` at a time; rest `pending` or `done`.

Hunt status

Before first hunt: set first plan to `current` with `0/3`, others `pending`. Bump Turns each agent response on current plan. After Boss approves next hunt: mark finished plan `done`, next `pending` → `current`.

### Per hunt workflow

1. Confirm Boss approved this hunt (first hunt: approval from Phase 2; later hunts: Boss said yes after prior stop).
2. Set that file to `current` in manifest. Open **only** that `plan_*.md`.
3. Work tasks in order. **Kill** = implement + verify per Verify line.
4. Mark `- [x]` **only** when task truly dead — zero doubt.
5. If **any** doubt: do **not** check off. Append to same plan:

Follow Ups

• [ ] <question for Boss — specific, actionable>

Then next task **in same plan only**.
6. All tasks in this plan addressed (killed or Follow Ups logged) → mark plan `done` in manifest.

### Two stops — never skip, never merge

**STOP 1 — Follow Ups (end turn):** Report what killed, list Follow Ups from this plan. Ask Boss to answer Follow Ups. **Do not** open next plan. **Do not** start next hunt.

**STOP 2 — Next hunt (separate turn after STOP 1):** After Boss handles Follow Ups (or says none needed):
- **Manual mode:** ask **time to start next hunt?** End turn. Wait for Boss yes.
- **`/goal` mode:** wait for Boss **`NEXT HUNT!`** (exact phrase preferred; close variants OK if obvious).

Only when Boss approves → set next plan `current`, reset `turns: 0 / 3` → begin new hunt at step 1.

If Epic has more `pending` plans and Boss has not replied since STOP 2 → **you are done for this turn.**

### End-of-hunt message (required format)

Hunt complete: plan_<name>.md

Killed: (bullets) Follow Ups: (list or "none") Next plan waiting: plan_<next>.md (or "none — ready for inventory")

Boss: answer Follow Ups above. Boss: time for next hunt? (yes/no)

**During hunt:** caveman voice to Boss; code/commits/PR text stay normal (per caveman skill).

## Phase 4 — Inventory kills

All plans hunted → inventory pass:

1. Re-read Epic `## Goal` and `## Steps`.
2. Compare actual work (commits, files, behavior) to Goal — gaps?
3. Walk each Epic step — fully done? If not, either hunt more or add Follow Up to relevant plan / new `plan_*.md`.
4. Check all Epic `Steps` boxes only when truly complete.
5. Tell Boss Man hunting complete **only** when Epic fully satisfied.

## Checkpoints (mandatory)

| After | Action | Ask Boss | End turn? |
|-------|--------|----------|-----------|
| Epic written | — | Changes before planning? | **Yes** |
| Plans written | — | Time to go hunting? | **Yes** |
| Each plan hunted | STOP 1 | Answer Follow Ups? | **Yes** |
| Boss replied to Follow Ups | STOP 2 | Time for next hunt? / **`NEXT HUNT!`** (goal mode) | **Yes** |
| Boss approved next hunt | start next plan only; `turns: 0/3` | — | No (hunt begins) |
| Hunt hit 3 turns, plan open | STOP (limit) | Blockers / split plan? | **Yes** |
| All plans `done` | Inventory | (report when done) | **Yes** after inventory |

**Between hunts = always end turn.** Two Boss replies minimum between plan files (Follow Ups, then next-hunt approval) unless Boss message answers both in one reply.

## Rules

- Never skip Boss checkpoints.
- **Never chain hunts** — one `plan_*.md` per hunt, then stop; no next plan same turn.
- **Never** skip STOP 1 or STOP 2 between plans (goal mode: STOP 2 = wait for **`NEXT HUNT!`**).
- **Never** exceed **3 turns** on one hunt without stopping and escalating to Boss.
- **Never** collapse a multi-step Epic into one plan file — default is **one plan per Epic step**.
- Never mark task complete on uncertainty — Follow Ups instead.
- Epic stays high-level; detail lives in `plan_*.md`.
- New scope from Boss mid-hunt → update Epic + Plans first, then resume hunt.
- `.plans/` lives at repo root unless Boss says otherwise. Always gitignore `.plans/` before first Epic file.

## Dependencies

| Skill | Role |
|-------|------|
| `caveman` | Terse Boss communication during workflow |
| `superpowers-plan` | Small steps, files, verify commands inside each plan |

Read dependency skills at hunt/plan time if not already loaded.

## Quick commands

- `/caveman-plan` — start Epic phase from current Boss prompt
- `/caveman-plan hunt` — resume hunts (pick next incomplete `plan_*.md`)
- `/caveman-plan inventory` — run Phase 4 only
- `/goal Epic file created. All plan files created. Every checkbox in epic and every plan checked off.` — Claude goal mode (set at start)
- **`NEXT HUNT!`** — Boss advances to next plan (goal mode, after Follow Ups)