plan-using-file

Plan Using File

Use a markdown file as mutable shared state for iterative planning. The user edits the file directly — adding questions, comments, and corrections — then invokes this skill to have Claude process all annotations and update the file in place. Works with any markdown file, not just plan.md — the default is just a convenience. This skill is designed to be invoked repeatedly within a session.

Guardrails

• Do not edit any file other than the plan file.
• Do not create new files (other than the plan file if it doesn't exist).
• Do not start implementing code — this skill is for planning only.
• Do not call EnterPlanMode or ExitPlanMode.

Resolving the Plan File

1. If a file path argument is provided, use that file and remember it as the active plan file for this session.
2. If no argument is provided, re-read the active plan file from this session.
3. If no plan file has been set yet this session, default to plan.md in the project root.
4. If the resolved file does not exist or is empty (no non-whitespace content), create it with a skeleton and ask the user what the plan is for:

# Plan: [Title]

## Goals

## Approach

## Phases

### Phase 1

### Phase 2

## Open Questions

Annotation Syntax

The user communicates through CriticMarkup comment syntax:

Marker	Meaning
{>> comment <<}	User question or comment to address
{>> @reply: response <<}	Claude's response (persisted for context, removable by user)
{>> @done <<}	Resolved thread — remove on next pass

Important: Ignore any {>> ... <<}, {>> @reply: ... <<}, or {>> @done <<} markers that appear inside fenced code blocks or inline code spans — they are examples or documentation, not actionable annotations.

Processing the File

Read the plan file, then process it following these rules:

Handle annotations

• Find every {>> ... <<} annotation. Do not skip any.
• For each annotation, decide how to handle it:
  • Questions or ambiguities → answer with a {>> @reply: ... <<} immediately after the {>> ... <<} so the user can review and mark {>> @done <<} when satisfied.
  • Concrete change requests (reword, add detail, restructure) → incorporate directly into the plan body and remove the annotation.
• For each {>> @done <<} marker, remove the entire resolved thread — the originating {>> ... <<}, any associated {>> @reply: ... <<} annotations, and the {>> @done <<} marker itself. If a {>> @done <<} appears without a preceding {>> ... <<}, remove just the {>> @done <<} and any {>> @reply: ... <<} immediately adjacent to it.

Preserve user structure

• Do not delete or rewrite sections the user has not commented on.
• Preserve the user's heading structure and organization unless an annotation explicitly requests restructuring.

Write back and summarize

• Write the updated plan back to the same file path using the Edit tool (preferred) or Write tool.
• After updating the file, summarize what changed in the chat response. For example: "Answered 2 questions, updated Phase 1 scope, removed 1 resolved thread."

After Processing — Iteration Loop

If this was the first pass (skeleton just created), ask the user to fill in the plan and return — do not output the standard summary or reminder.

Otherwise, after writing the file and summarizing changes, end your response with a brief reminder such as:

"Review the changes, add any {>> comment <<} annotations, and run /plan-using-file when ready."

When There Are No Annotations

If the file has no {>> ... <<} annotations, review the plan and report its current state without making changes. Summarize what the plan covers and note any sections that seem incomplete or worth discussing.