/plan
Produce a rigorous, implementation-ready plan for a feature — one a fresh-context agent can implement without guessing.
When to reach for it
Use it when you know what you want and need a plan a fresh agent could implement without guessing. It interviews you, drafts, grills the draft for edge cases, and grades the result before anyone writes code.
How to run it
lightsout plan workspacelightsout plan verify-factslightsout plan draftlightsout plan sync-decisionslightsout plan lintlightsout plan deduplightsout plan grade--phase grades only those phases, and always marks the result incompletelightsout plan publish| flag | meaning | left out |
|---|---|---|
| --name <name> | The plan to work in, under .lightsout/work-orders/<work-order-name>/plans/ — a plan address <work-order-name>/<NNN-slug>, or a legacy folder name. | required |
| --notes <path> | Rough notes to start from — a /brainstorm file, or anything you wrote yourself. | The workspace starts from the request alone. |
| --legacy | Draft with the previous drafting implementation rather than the focused one. | The focused drafting implementation. |
| --scope single|phased | Whether to write one plan or an overview with a file per phase. | Chosen from the size of the work. |
| --phase <n[,n]> | Grade only these phases of a phased plan. | Every phase is graded, and the result may be complete. |
| --cwd <path> | The checkout the command is launched from; the plan’s worktree is resolved from it. | The process working directory. |
| --worktree | Plan in a fresh git worktree of this repository, on a branch named after the plan’s ticket folder. | The `plan.worktree` config key, which defaults to on. |
| --no-worktree | Plan in the checkout this was launched from rather than a worktree of its own. | off |
What happens
1. CREATE THE PLAN WORKSPACE
- Start from a direct request or existing `/brainstorm` notes
- Create a name for the plan
- Preserve any existing notes as the plan’s starting context
Gives the plan a stable home without making `/brainstorm` a prerequisite
SAVED WHEN NOTES EXIST.lightsout/work-orders/<work-order-name>/plans/<plan-id>/brainstorm-notes.md
2. RECORD THE FACTS
- Inspect the code and files relevant to the plan request
- Record the repository facts the plan will rely on
- Verify every referenced file and path before moving forward
Ensures the plan reflects the repository’s current state, not assumptions
writes.lightsout/work-orders/<work-order-name>/plans/<plan-id>/facts.json
3. SETTLE THE SCOPE AND CONSTRAINTS
- Decide whether the request needs one plan or multiple phases
- Record the requirements and constraints the plan must follow
- Planning agent asks questions until you are both aligned
Prevents scope and project constraints from being decided during implementation
writes.lightsout/work-orders/<work-order-name>/plans/<plan-id>/decisions.json
4. CHOOSE THE APPROACH
- Planning agent presents 2–3 distinct options with trade-offs
- You choose the approach the plan will follow
- Skip this step only when the approach is already settled
Ensures the design is chosen before implementation begins
writes.lightsout/work-orders/<work-order-name>/plans/<plan-id>/decisions.json
5. WRITE THE IMPLEMENTATION PLAN
- Turn the verified facts and decisions into a complete plan
- Validate the plan’s structure and revise it until it passes
- Use one plan or split larger work into clear phases
Creates the specification the implementation agent will follow
writes.lightsout/work-orders/<work-order-name>/plans/<plan-id>/plan.md.lightsout/work-orders/<work-order-name>/plans/<plan-id>/overview.md.lightsout/work-orders/<work-order-name>/plans/<plan-id>/phase<N>-<slug>.md
6. STRESS-TEST THE PLAN
- The planning agent questions you about edge cases and unresolved choices
- You answer every decision that could change implementation
- Every answer is added to the plan immediately
Prevents the implementation agent from filling gaps on its own
writes.lightsout/work-orders/<work-order-name>/plans/<plan-id>/decisions.json
7. CATCH DUPLICATION BEFORE CODING
- The planning agent searches for existing code related to the plan request
- Decide whether to reuse, extend, extract, defer, or keep the code separate
- Update the plan before implementation begins
Prevents duplicate logic and competing abstractions
writes.lightsout/work-orders/<work-order-name>/plans/<plan-id>/dedup.json
8. GET THE PLAN TO AN A GRADE
- The engine grades the plan and identifies every gap
- The planning agent updates the plan to address each finding
- Re-grade until it earns an A with no unresolved gaps
Proves the plan is complete enough for an implementation agent with no prior context
writes.lightsout/work-orders/<work-order-name>/plans/<plan-id>/grade.json