bcbeidel/plan-work

Plan Work

Convert approved designs or requirements into structured implementation plans. The output is a plan document — not code, not a design.

Workflow

1. Gather Context

• Read the design doc (if invoked from scope-work, check the related field).
• Explore the codebase: identify files to create, modify, or delete.
• Check .plans/ for overlapping or related plans.
• If no design doc exists, gather requirements from the user before proceeding.

2. Scope Check

If the plan would require >20 tasks or span >3 independent subsystems, suggest splitting into separate plans. Each plan should produce working, testable software on its own.

"This looks like [N] independent pieces: [list]. I'd suggest separate plans — they can be built in any order. Which should we start with?"

3. Write the Plan

Save location depends on the project's layout hint (read from AGENTS.md <!-- wiki:layout: ... --> comment):

• separated: .plans/YYYY-MM-DD-<feature-name>.plan.md
• co-located: same directory as the related design doc
• flat: docs/YYYY-MM-DD-<feature-name>.plan.md
• none or missing: ask the user where to save
• User can always override the suggested location.

Use the Plan Document Format.

See Format Guide for how to write each section effectively. Use the Plan Template as a starting skeleton.

All 6 required sections: Goal, Scope, Approach, File Changes, Tasks, Validation. At least one concrete validation criterion — not "verify it works" but a specific command with expected output.

4. Infeasibility Check

If plan creation reveals the design cannot be implemented as specified, do not silently modify scope. Instead, produce structured feedback:

## Feedback

**Infeasible:** [specific design element that cannot be implemented]
**Why:** [files checked, APIs tested, dependencies missing]
**Impact:** [which plan tasks are affected and how]
**Alternatives:** [suggested modifications, if any]

See Feedback Loop for the full format, user options, and revision-vs-supersede decision tree.

Present the user with three options:

1. Return to scope-work — invoke /work:scope-work with this feedback to revise the design. Follow the "supersede, don't edit" pattern.
2. Proceed with modified scope — revise the plan in-place: update Must/Won't boundaries, adjust or remove affected tasks, and document what changed and why in the Approach section. Appropriate when the design is sound but a specific task or constraint is impractical.
3. Abandon — set status: abandoned with a reason in the plan.

5. Review with User

Before presenting, confirm all required sections are present:

bash <plugin-skills-dir>/start-work/scripts/validate_plan.sh <plan-file>

If the script exits 1, fix the missing sections before presenting.

Present a summary:

• Goal (1 sentence)
• Task count and estimated file changes
• Key scope boundaries (Must/Won't highlights)
• Validation criteria

Do not proceed until the user approves.

6. Update Status

When the user approves, set status: approved in the plan's frontmatter.

7. Hand Off

Present to user: "Plan approved. Ready to invoke /work:start-work to begin implementation — proceed?"

Wait for user confirmation before invoking the skill. The plan should be ready for execution by an agent with zero prior context.

Key Instructions

• Plans are files, not chat. Save to disk with frontmatter. Plans that exist only in conversation are lost on context reset.
• Plans survive context resets. A new session resumes by reading the plan file — completed tasks are [x], remaining are [ ]. Write each task so it can be started from the current git state without requiring conversation history.
• Every task gets a verification command. If you can't verify it, you can't know it's done.
• Commit per task creates rollback boundaries. Each completed task gets its own git commit. On failure, the agent can diff against the last passing commit and roll back cleanly. This is why every task ends with a commit step.
• Middle altitude. Observable outcomes, not implementation prescriptions. Too abstract: "Implement auth." Too granular: "Write if-statement on line 47." Right: "Add login endpoint. Verify: curl POST /login returns 200 with token."
• One plan per feature. Multi-system changes get separate plans.
• Link to design docs. Use the related field to connect plans to their design specs, establishing traceability.
• Scope boundaries are load-bearing. Won't-have items prevent scope creep during execution. Be explicit about what's excluded.
• Dependencies between tasks are explicit. If task B requires task A, state the dependency. Default is sequential execution.
• Intermediates go to disk, not just context. During execution, write discovered information (decisions, edge cases, API findings) to the plan file or a companion notes file. Context resets; files persist.
• Chunk large plans. Use ## Chunk N: <name> headers for plans with 10+ tasks, grouping by logical dependency.

Anti-Pattern Guards

1. Vague validation — "verify it works" is not a criterion. Every validation item needs a concrete command or observable check.
2. Task granularity extremes — tasks should be independently verifiable outcomes. Neither "implement the feature" nor "add import statement."
3. Scope creep during planning — if the plan grows beyond the design, something is wrong. Check whether the design needs revision (step 4) or the plan needs splitting (step 2).
4. Session-dependent task descriptions — tasks that reference conversation context ("as discussed", "the approach we agreed on") cannot be resumed in a new session. Plans are procedural memory, not session notes. Every task must be startable with zero conversation history and no access to this chat.
5. Missing branch in frontmatter — the branch: field is load-bearing for multi-session execution. An executor resuming in a new session cannot determine where to work without it. Always set it before handing off to start-work.

Output Format

Plan documents use the standard frontmatter format:

---
name: Feature Name
description: One-sentence summary
type: plan
status: draft
related:
  - .designs/YYYY-MM-DD-<name>.design.md
---

Save location follows the project's layout hint (see step 3 above). The related field links to design docs, context files, or other plans.

Handoff

Chainable to: start-work