anthropic-plan

name	anthropic-plan
description	Workflow-backed implementation planning that creates a deep repo-local packet under docs/plans/<slug>/ before any code changes. Use for /anthropic-plan, /plan, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial implementation requests that need source-grounded design, TDD steps, and validator approval before build work.

Anthropic Plan

Create a source-grounded plan packet through the Claude Code Workflow runtime. First draft a short starting plan and get it approved in plan mode; then the workflow builds the full repo-local docs/plans/<slug>/ packet — context, spec, implementation, validation, and handoff docs. Stop before implementation.

Plan first (plan mode)

Before any worktree or workflow, build a short starting plan in plan mode and get the user's approval. This is a cheap gate: it confirms the direction before the workflow spends tokens building the full packet.

1. Enter plan mode with EnterPlanMode if the session is not already in it.
2. Read the handful of files closest to the request — the entry points, the modules the change touches, the tests that cover them — enough to ground the approach in real source.
3. Write a short plan: the goal in a sentence or two, the approach, the files the build will touch, and the main risks or open choices. Use AskUserQuestion for any product choice that local context cannot settle.
4. Call ExitPlanMode to hand the plan to the user for approval.

On approval, fold the approved scope and direction into the task payload at launch, then continue with the steps below. If the user revises the plan, fold the changes in and present it again. Do not isolate a worktree or launch the workflow until the starting plan is approved.

Isolate the session

The workflow's background subagents write the packet into the working tree. A background session that has not isolated into a worktree cannot write a shared checkout — the background-isolation guard rejects the write. So put the session in a worktree before launching the workflow:

If the working directory is not already inside a worktree — its path does not contain .claude/worktrees/ — call EnterWorktree to create one. The session switches into the worktree, the packet is written under docs/plans/<slug>/ there, and the build then proceeds in the same worktree. A session already inside a worktree skips this step.

Launch

Call the workflow with the user request and current working directory. The payload goes in args — the Workflow tool exposes args to the script as its global args, and substitutes the user's full request for $ARGUMENTS:

Workflow({
  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
  args: {
    task: "$ARGUMENTS",
    cwd: "<current working directory>"
  }
})

The task string carries the user request together with the approved starting plan, so the packet reflects the direction the user signed off on.

If the Workflow tool is unavailable, say anthropic-plan requires the Workflow tool; aborting and stop.

Self-healing writes

The workflow writes the packet into the live checkout under docs/plans/<slug>/. When a session isolates writes into a worktree and blocks a direct write, the workflow stages each packet file through the Write tool — so the plain-language and historical-clutter checks still run — then copies the staged tree into the checkout. The packet lands under docs/plans/<slug>/ in either session mode.

Workflow Contract

Phases run inside workflow/plan-packet.mjs (Discover → Write packet under docs/plans/<slug>/ → Validate with validate_packet.py and plan-packet-validator → Reuse audit → Visualize → Approval). The workflow returns the packet path and validation state, then stop before implementation. Phase detail lives in that script's phases list.

Packet Shape

Required root: docs/plans/<slug>/

Required top-level files and folders:

• README.md
• packet.json
• context/
• spec/
• implementation/
• validation/
• handoff/

The packet depth rule is strict: README.md is a thin hub, first-level folders group purpose, and second-level files carry detail. Add context/subsystems/<name>.md only when the planner finds more than twelve source files or more than three subsystems.

Validation

The deterministic validator checks required files, placeholders, Open Questions, source-map strength, TDD coverage, standalone handoff prompts, and packet.json consistency.

The plan-packet-validator agent checks source accuracy, scope, enough implementation detail for a blind build agent, real TDD order, invented APIs or commands, and end-to-end acceptance criteria.

The reuse audit writes validation/reuse-audit.md with a per-item verdict for every new file or symbol the packet introduces and gates approval on any unjustified reproduction of existing behavior.

Visualize

After validation and before approval, the workflow builds a single-file offline visual HTML of the finished packet from templates/visual-plan.template.html and writes it beside the packet as visual-plan.html. The file inlines all CSS and JavaScript and references no external assets, so it opens offline. It renders the packet as diagrams and compact cards — a stat hero, scenario strips, is/isn't cards, edit-recipe step sequences for the file-by-file change, reuse-audit verdict badges, and a checklist — rather than reproducing the markdown. Every label is written for the reviewer: the diagram says what each step does in plain words and leaves out code symbols (function names, selectors, test names), while each touched file keeps its repo-relative path dimmed for the build agent. Because it is generated after validation, visual-plan.html is not a required packet file.

Rules

• Write docs only.
• Do not edit production code.
• Do not run implementation commands.
• Ask the user only for product choices that cannot be derived from local context.
• Fold resolved answers into the packet. Never leave an Open Questions section.