40 lines
2.7 KiB
Markdown
40 lines
2.7 KiB
Markdown
|
# 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`).
|