loop-plan

loop-plan turns a large request into a phased plan file. Each phase names the files, symbols, tests and commands it depends on, and each acceptance criterion can be checked by a command or a real run. The skill plans only. It does not change application code.

When to use it

Use it for large work:

• several features, or one feature that touches many files or components
• work that spans sessions and needs phase boundaries you can resume from

Do not use it for a small fix or a single-feature change. Make the change directly with tests, then run /review-impl (Claude Code) or $review-impl (Codex) if you want a review. The skill tells you this when the request is small, and plans it only if you still ask.

Invoke it

Claude Code

/loop-plan move the tag storage in atlas-notes from one column to a join table

Codex

$loop-plan move the tag storage in atlas-notes from one column to a join table

Name the target and anything that must not change. You do not need a full specification: the skill asks for corrections at three points (see Talking with the skill).

What it works out by itself

• The repository instructions (CLAUDE.md or AGENTS.md), git status, recent history, and the files, symbols, callers and tests the change touches.
• Whether a library or platform behavior has been seen to work in this repository. When it has not, it runs a small spike under .cross-review/spikes/<plan-name>/ and records the result in Feasibility evidence.
• The design that fits the existing patterns, reusing helpers by name. When the existing pattern is itself the problem, it gives you two options (patch within the pattern, or move to the standard) and waits for your choice.
• Where the plan goes. It runs the plans command, which creates .cross-review/plans/ and prints the folder, then writes <kebab-case-summary>-plan.md there. The name describes the work, for example migrate-tags-plan.md, never a generic plan.md.

It asks you only for material decisions: product behavior, API, schema, dependencies, compatibility, or operations. Hard stops in a plan are reserved for data loss, security, and irreversible actions. Anything else that cannot be verified becomes a recorded assumption with a default and a fallback.

What the plan contains

The plan has these sections, in this order:

Section	What it holds
Target, Scope, Invariants, Fixed decisions	What the work achieves, what it leaves out, and choices the implementation must not change on its own
Baseline	Completed work, and the real duration of each gate command
Design and project patterns	The pattern each change follows, with its path or symbol
Feasibility evidence	Assumption, spike or source, result, date
Capacity	Limits the plan sets, or N/A
Global Gates	Commands run once on the final commit
Review checkpoints	Which phases end with a review, and a final review of the whole diff
Plan Review	pending until a review or you approve the plan
Phase 1 to N	The phase blocks described below
Completion Criteria	The whole-plan outcome, with at least one end-to-end scenario and its expected output
Progress Log	Written during implementation: one line per phase, dated Decision: and Discovery: lines

Each phase has: Goal, Current behavior and gap, Evidence, Pattern, Dependencies, Files and symbols, Behavioral contract, Documentation, Tests first, Anti-shortcut coverage, Implementation obligations, Acceptance criteria, Focused verification, Phase gates, Review, and Commit. Acceptance criteria are checkboxes that must be binary, each with the proof that shows it (a test, a real run, or an inspection):

- [ ] AC-1: a tag added to a note is returned with that note — proven by a test in the notes store suite

Talking with the skill

The skill stops three times so you can correct it:

1. After discovery. It restates the target, what is out of scope, and its assumptions.
2. After the spikes. It shows the main design decisions, especially a patch versus a standard, and any breaking change.
3. At handoff. It gives the plan path, whether git keeps the plan, the dashboard link when one is open, the phase count, and the review status. You then choose whether to run /review-plan or approve the plan yourself.

Each decision comes on its own, in five parts: context, problem, options with cost and risk, recommendation, and what happens next if you agree. A generic “ok” approves nothing that was not presented.

After the plan

1. Run /review-plan (or $review-plan) on the plan file. See review-plan.
2. When the reviewer approves, Plan Review reads APPROVE (review-plan <session id>, <date>). If you approve directly, it reads APPROVE (user, <date>).
3. Run /loop-implement (or $loop-implement). It starts only from an approved plan. See loop-implement.

What you can say in chat

You say	What happens
A correction to the target or scope	The skill updates the plan and continues
“Use option 2” (or any named option)	The skill records the decision and changes the affected sections
“Approve it”	The skill writes APPROVE (user, <date>) after showing what it is approving
“Run the review first”	The skill hands over to /review-plan

Example

Project: atlas-notes. Tags are stored as one comma-separated column on the notes table.

Request: /loop-plan move the tag storage in atlas-notes from one column to a join table

The skill writes .cross-review/plans/move-tags-to-join-table-plan.md with three phases:

1. Schema and migration. It includes a retry path for a partial run and says that rerunning is safe.
2. Read path: notes return their tags from the join table.
3. Write path and removal of the old column.

Review checkpoints are after phase 1 (the migration changes state) and a final review of the cumulative diff. The plan review is still pending until it is approved.

See Plans for where plans live, how git treats them, and how the dashboard shows them.