| name | planning-with-files |
| description | Use when any non-trivial task (>20 LOC or >1 file) would otherwise be done without a persistent plan. Produces and maintains a markdown plan file that survives session compaction and restarts. Based on the Manus-style planning pattern popularized by OthmanAdi/planning-with-files (18.4k⭐). |
| version | 1.0.0 |
| trigger | Intent matches planning, implementing, refactoring, or shipping a non-trivial feature. Also triggers when user explicitly mentions "plan", "planning", "plan file", "plans/", "PRD", "spec", or when @architect is invoked.
|
Planning With Files
You are the planning layer for this project. You turn vague intents into file-based plans that survive the session.
When to Run
- Any task > 20 lines of code or spanning > 1 file
- Any refactor, migration, or multi-step shipping task
- User mentions "plan", "planning", "plan file", "plans/", "PRD", or "spec"
@architect is invoked- A prior session's plan file exists for this task (resume from it, don't re-plan from scratch)
When NOT to Run
- One-liner bug fixes
- Docs-only typo fixes or wording changes
- Mechanical renames (
s/foo/bar/g across the repo)
- Reading / explaining code (no code changes → no plan needed)
Why File-Based Plans
- Survive
/compact — in-memory plans get dropped when context compresses
- Survive session restarts — agent reads the file on the next session and resumes
- Survive worktrees — every parallel Cascade sees the same plan
- Reviewable — humans can read, diff, and edit the plan before you write code
- Git-tracked — PR reviewers see what was planned vs what shipped
Plan File Location & Naming
All plan files live in plans/ at the repo root:
plans/
├── 2026-04-17-stripe-webhooks.md
├── 2026-04-16-postgres-migration.md
└── README.md # index of active plans
Filename convention: <YYYY-MM-DD>-<slug>.md. One plan = one PR = one merged commit.
Plan File Template
Every plan file MUST have these sections, in this order:
# <Title>
Status: draft | approved | in-progress | blocked | done
Owner: <human name>
Started: <YYYY-MM-DD>
## Goal
One paragraph. What changes for a user or operator when this ships?
## Non-Goals
Bulleted list of what this deliberately does NOT do. The biggest source of
scope drift is an unwritten non-goal.
## Constraints
- From AGENTS.md invariants: ...
- From user context: ...
- Hard deadlines: ...
## Approach
One or two paragraphs explaining the chosen approach. Cite 2-3 alternatives
considered with trade-offs.
## Task Breakdown
- [ ] 1. <one verb, one file-scope, one acceptance criterion>
- [ ] 2. ...
- [ ] 3. ...
## Risks & Mitigations
- **Risk:** ... **Mitigation:** ...
## Rollback Plan
If this ships and breaks production, how do we back out in <10 minutes?
## Session Log
<!-- Append a line per session. No prose. -->
- 2026-04-17 14:02 — plan drafted, reviewer feedback pending
- 2026-04-17 15:45 — @reviewer LGTM, starting task 1
Operating Rules
- Never start coding without a plan file for tasks > 20 LOC or spanning > 1 file.
- Work one checkbox at a time. After each checkbox, update the plan file with
[x] and a one-line note in the Session Log. Run tests before moving to the next.
- If a checkbox turns red, stop. Do not move to the next. Add a
## Blocker section, message the human, wait.
- If you discover the plan is wrong mid-implementation, stop coding, update the plan, re-review with @reviewer before continuing.
- At session start, ALWAYS read the latest plan file in
plans/ before opening any source file. The plan is the source of truth for intent.
- Commit the empty plan first. The plan is the contract. Code that doesn't match the plan is a bug in one of them.
Integration With Cascade Modes
- Plan Mode produces an in-memory plan. Your job: persist it to a file before handing off.
- Code Mode with
@implementer: pass the plan file path. The implementer works checkbox-by-checkbox.
- Ask Mode: never creates plans; only reads them.
Never
- Never start coding on a task > 20 LOC or spanning > 1 file without a plan file committed first
- Never mark a checkbox
[x] when tests are red, the lint is broken, or the build fails
- Never skip the plan "just for this one" — that's how scope drift starts
- Never let a plan file exceed 800 lines — if it's that big, split it into multiple plans
- Never write a task without an acceptance criterion — "refactor auth" is not a task; "add
rotateToken() with tests" is
- Never silently abandon a plan mid-implementation — update the plan, flag the pivot, re-review
Hand-Off
When the plan is drafted, hand to @reviewer for a plan-review pass before any implementation. Only @implementer touches code, and only after the plan is approved.
Credits
Inspired by OthmanAdi/planning-with-files (18.4k⭐) and Andrew Shu's markdown-plan-files pattern.
