git:20260907.b55581b to git:20260907.caab477

---

name: plan-cycle

description: >-

Draft, critique and merge a plan in one loop, then stop for approval. Use when the user runs /plan-cycle or

asks for the full plan, critique and merge loop in a single pass.

license: MIT

disable-model-invocation: true

---

You are running the whole planning loop in one pass: research the codebase, draft the plan only when the user has

not written one, critique it, merge the findings, repeat, then stop and wait for approval.

This skill never executes the plan. It ends at the approval gate.

Fixed rules:

Read the working agreement at [working-agreement.md](../../../working-agreement.md) before step 1 and follow it for

the whole run. If that path does not resolve, look for `working-agreement.md` in the project root, then in

`.github/`. If it cannot be found anywhere, tell the user it is missing and apply the rules listed below.

These rules bind this phase and override any step below that conflicts with them:

1. Never execute the plan, and never write, edit or refactor project code during this run. This phase produces a

plan folder, a `plan.md`, a `critique.md` and a `cycle-log.md` and nothing else. The user approves before

anything is built.

2. The user owns the plan. Draft `plan.md` only when it is empty or still the unedited template. When it holds

text the user wrote, never overwrite it, and never drop the user's requirements, wording or constraints while

merging.

3. Never assume, ask. Change `plan.md` on your own only when the change a finding asks for is obvious. Stop and

ask the user whenever it is not: the finding is ambiguous, it touches a requirement or a constraint the user

wrote, it changes the scope or the intent of a chapter, it rewrites more than the finding covers, or two

findings pull in different directions. Show the finding, the exact edit you propose and the alternatives, then

apply the answer. A doubt is a question, never a guess.

4. Be adversarial in every iteration. Try to refute each finding before you write it down, and report only what

survives the attempt.

5. Grade confidence per finding. Report a finding as CONFIRMED only when you verified it against the codebase.

Label everything else UNVERIFIED and state what you could not check and why. Prove every finding with a

`file:line` reference, a command output, or a failing test.

6. Re-read `plan.md` from disk at the start of every iteration and cite line numbers only from that copy. Merging

shifts every line below the merge point, so numbers carried over from an earlier iteration are wrong.

you asked about with the answer you got, and every skipped finding with its reason, in `cycle-log.md`, and

print the same summary after each iteration.

In this skill, "project instructions" means the first of these files that exists in the project root:

`.github/copilot-instructions.md`, `AGENTS.md`, or `CLAUDE.md`.

To do this, follow these steps precisely:

1. Display the following banner before doing anything else:

```

+-------------------------------------------------+

+-------------------------------------------------+

```

2. Read `.copilot/plan-critique-config.json` and get `plansFolder` path from settings.

If that file does not exist, read `.claude/plan-critique-config.json` instead, so a project already using the

Claude Code plugin keeps the same plans folder.

- Ask the user: "Where would you like to store your plans? Provide a folder path (default `.planning`):".

By default, the user should be presented with the option `.planning`.

- Save the path as `plansFolder` in `.copilot/plan-critique-config.json`

- Create the folder if it doesn't exist

- Create an `archived/` subfolder inside it

3. Read the optional `cycleIterations` value from the same config file. It is the maximum number of critique and

merge iterations for this run. Default to `3` when it is missing, and clamp any value outside the range 1 to 5.

4. Get the Copilot CLI session id from the `COPILOT_AGENT_SESSION_ID` environment variable. Read it with

`echo $COPILOT_AGENT_SESSION_ID` on macOS or Linux, or `$env:COPILOT_AGENT_SESSION_ID` on Windows.

If the variable is empty, use the literal value `default` instead. Store this as `sessionId`.

5. Clean up stale sessions: scan `[plansFolder]/.sessions/` for files and delete every file that has not been

modified in the last 7 days. This is non-blocking cleanup, never abort the run because of it.

6. Read the current session's plan from `[plansFolder]/.sessions/[sessionId]` if it exists. Store as `sessionPlan`.

7. Scan `[plansFolder]/` for subdirectories (each subdirectory is a plan). Exclude `archived/` and `.sessions/`

folders and any files, only list plan directories.

8. Select the plan for this cycle:

- If the user passed a name in the prompt that invoked this skill and it is a slug that matches an existing

plan folder, select that plan.

- Else if the user passed a name in the prompt, treat it as the name of a new plan and create it by following

the plan naming and folder creation steps of [../plan-create/SKILL.md](../plan-create/SKILL.md): the slug

rules, the name collision check, the folder creation and the `plan.md` template from

[plan-template.md](../plan-create/plan-template.md). Do not display the create banner.

- Else if `sessionPlan` exists and matches a plan folder, auto-select it and inform the user:

"Using current session plan: [sessionPlan]"

- Else if exactly one plan exists, auto-select it and inform the user.

- Else if plans exist, ask the user to select one from the list, and offer creating a new plan as the last

option.

- Else ask the user for a name for the new plan and create it as described above.

9. Update the session file `[plansFolder]/.sessions/[sessionId]` with the selected plan slug (create if needed).

10. Read `[plansFolder]/[selected-plan]/plan.md` and classify it:

- Empty, or still the unedited template from [plan-template.md](../plan-create/plan-template.md), which is

recognised by the placeholder chapter heading and the bracketed placeholder lines: the plan needs a draft.

- Anything else: the user wrote it. Inform the user "Using the existing plan.md, no draft written." and go to

step 13.

11. Prepare the draft. Tell the user "plan.md is still the template. Drafting a first pass." and get the goal:

- Use the text the user passed in the prompt as the goal when it describes what to build.

- Otherwise ask the user: "Describe what this plan must achieve:". Do not guess the goal.

12. Research the codebase, then write the draft:

- Read the project instructions and `README.md`, and the existing files the goal touches.

- List every file that the plan will create, modify or delete, and verify each path exists with Glob before

writing it down. Show this list to the user before writing the plan.

- Ask the user whenever the research leaves a real choice open, such as which module owns the change or which

of two approaches the plan should take. Do not pick one and write it down as if it were settled.

- Write `[plansFolder]/[selected-plan]/plan.md` using [plan-template.md](../plan-create/plan-template.md): one

numbered chapter per unit of work, in dependency order, each with its own `Affected files` and

`Verification` sections. Every chapter names the test to write or the command to run.

- Where the project has no test infrastructure, say so in the chapter instead of inventing a test harness.

13. Check prerequisites once, before the loop:

- If `plan.md` is empty after step 12: respond with "Plan file is empty. Edit

`[plansFolder]/[selected-plan]/plan.md`" and stop.

- If no project instructions file exists: respond with "Create a `.github/copilot-instructions.md` file in

the root of your project." and stop.

- Detect the project languages and probe the language server as described in the language server

availability step of [../plan-critique/SKILL.md](../plan-critique/SKILL.md). Record whether a language

server is available, and reuse that answer for every iteration instead of probing again.

14. Run the cycle. Repeat the following until you have run `cycleIterations` iterations or an iteration surfaces

no new findings:

- Re-read `plan.md` from disk.

- Critique it by following the fixed rules and the analysis steps of

[../plan-critique/SKILL.md](../plan-critique/SKILL.md), including the split evaluation. Skip its config,

session and plan selection steps, which this run already did. Its rule against editing `plan.md` binds the

critique step only, because merging is a separate step below.

- Write the critique to `[plansFolder]/[selected-plan]/critique.md` using

[critique-format.md](../plan-critique/critique-format.md), with the iteration number incremented from the

previous critique.

- If the critique found nothing, respond with "No new findings." and leave the loop.

- Merge the findings into `plan.md`:

- Apply a CONFIRMED finding to the chapter it belongs to when the edit it asks for is obvious.

- Ask the user before making any change that is not obvious, and apply the answer. This covers an

ambiguous finding, a finding that touches a requirement or a constraint the user wrote, a finding that

changes the scope or the intent of a chapter, and two findings that pull in different directions. Show

the finding, the exact edit you propose and the alternatives. Ask once per change, and group the

questions of one iteration together so the loop stops as little as possible.

- Apply an UNVERIFIED finding only when it clarifies the plan and cannot lose information. Ask about it

otherwise.

- Skip any finding whose evidence is missing.

- Keep the `Affected files` and `Verification` sections in every chapter.

- When the critique recommends splitting the plan, do not split it. Record the recommendation as an open

item for the approval gate.

- Append an entry to `[plansFolder]/[selected-plan]/cycle-log.md` using [cycle-log-format.md](cycle-log-format.md),

and print the same merged and skipped summary to the user.

15. Print the final `plan.md` in full, followed by the open items: every skipped finding and every split

recommendation.

16. Stop at the approval gate and respond:

```

Cycle complete after [N] iteration(s): [plansFolder]/[selected-plan]/plan.md

Merged: [X] findings. Asked about: [Z]. Not merged: [Y], listed in cycle-log.md.

Nothing has been executed and no project code was changed.

Review the plan. When you approve it, run `/plan-execute`.

```

Notes:

- Never execute the plan from this skill, not even when the user approves it in the same session. Point the user

at `/plan-execute`, which carries its own rules, its own confirmation and its own execution log.

- Each iteration is a full adversarial pass over the plan and the codebase, so a three iteration run on a large

plan is expensive. Set `cycleIterations` to 1 or 2 in `.copilot/plan-critique-config.json` for small plans.

- The cycle is resumable. Run it again on the same plan and it continues from the current `plan.md` and from the

iteration number recorded in `critique.md`.

- `critique.md` holds the latest iteration only, because each critique overwrites it. `cycle-log.md` holds the

history of what was merged and what was skipped.

- The plan folder, the session file and the config file are the same ones used by `/plan-create`,

`/plan-critique`, `/plan-execute` and `/plan-archive`. The cycle is a shortcut through the first two, not a

separate workflow.