# Plans folder

Cross-session handoff between the **planner** (Claude on cloud) and the **implementer** (any model — usually Minimax in a separate session). The plan file is the contract — chat history doesn't transfer, so the plan has to be self-contained.

## Workflow

1. **Planner** writes a plan to `.claude/plans/<slug>.md` from the [`TEMPLATE.md`](./TEMPLATE.md) shape.
   - Use the `superpowers:writing-plans` skill if available.
   - The plan must be self-contained — anything the implementer can't infer from the working tree goes in the **Background** section.
   - The **Background** section is where the planner summarises the conversation that led to the plan: decisions, dead ends, "we tried X but Y", links to prior commits, the operator's actual intent. This is the tribal-knowledge handoff.
   - Set frontmatter `status: ready` when ready to hand off.

2. **Hand off** — pick one:
   - **File**: tell the implementer session "read `.claude/plans/<slug>.md` and execute".
   - **Git**: commit the plan on a branch, switch the implementer session to that branch.
   - **Orca**: `orca handoff --plan .claude/plans/<slug>.md` (see the `orca-cli` skill).

3. **Implementer** boots from [`RUN-PLAN.md`](./RUN-PLAN.md) — paste it as the opening prompt of the new session, or load it via skill if the harness supports it.
   - Reads the plan + the repo's `CLAUDE.md` / `AGENTS.md`.
   - Follows the plan, surfaces disagreements rather than improvising.
   - Flips `status: in_progress` → `complete` (or `blocked`) and writes a short report in the plan's **Status (filled by implementer)** section.

4. **Loop back** — the implementer's Status section + commit messages are the planner's input for the next iteration.

## File layout

| File | Purpose |
|---|---|
| `README.md` | This file — orientation |
| `TEMPLATE.md` | Copy this to start a new plan |
| `RUN-PLAN.md` | Paste this into the implementer session as its opening prompt |
| `<slug>.md` | An individual plan. Slug is short-kebab-case, matches the feature / branch name |
| `<slug>.status.md` | Optional. Implementer writes one of these if it needs to report back without flipping the plan's `status` frontmatter (e.g. mid-run questions) |

## Conventions

- **Commit plans** with the work. They're version-controlled documentation of intent, not scratch.
- **One plan per feature / branch.** Split if the scope grows.
- **Status lifecycle**: `draft` → `ready` → `in_progress` → `complete` (or `blocked` / `abandoned`).
- **Don't bypass MCP.** If the implementer needs a tool that doesn't exist, surface the gap in the status file — don't fall back to direct REST calls (Hermes / n8n drops `AGENT_API_KEY` on direct calls; see `.claude/memory/mcp-only-no-direct-api.md`).