Dave
b9d30c8e6f
PocketBase treats `max: 0` on a text field as "use the default 5000-char cap", not unlimited. A Redpath reply with a 5029-char body 400'd on every 2-minute poll for hours on 2026-09-08, wedging every RFQ behind it because the failed email stayed UNSEEN. Added clampEmailBody (with a truncation marker) and routed email_body writes through it so oversized replies still become quotes instead of blocking the queue. The untruncated body remains in the mailbox, and attachments carry the detail. Raise this cap in lockstep with any PB admin change to the field's max. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
40 lines
No EOL
2.7 KiB
Markdown
40 lines
No EOL
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`). |