Skip to content
Skills Library
AI & agents · Planning

plan-loop

/plan-loop

Plan work with the user in a PLAN.md, then implement it step by step, with /clear once the context fills up. Use before creating a plan, when the user mentions a PLAN.md, or when resuming work after /clear.

Repository
dotfiles ↗
Licence
MIT
Last repository change
21.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Plan work with the user in a PLAN.md, then implement it step by step, with /clear once the context fills up. Use before creating a plan, when the user mentions a PLAN.md, or when resuming work after /clear.

Original author description

Plan work with the user in a PLAN.md, then implement it step by step, with /clear once the context fills up. Use before creating a plan, when the user mentions a PLAN.md, or when resuming work after /clear.

How it works

  1. Gather information
  2. PLAN.md
  3. Step loop
Original SKILL.md headings · 74 lines, 517 words
SKILL.md preview
---
name: plan-loop
description:
  Plan work with the user in a PLAN.md, then implement it step by step, with
  /clear once the context fills up. Use before creating a plan, when the user
  mentions a PLAN.md, or when resuming work after /clear.
user-invocable: true
disable-model-invocation: false
---

# Plan loop

We discuss the work, write it down in `PLAN.md`, then implement it step by
step, with `/clear` once the context fills up. This keeps the context small:
cheaper, and you stay sharper.

Recommended: Opus at high effort. If you are not running on Opus, say so and ask
whether to proceed anyway. You cannot see the effort level (no need to remind me
about it).

## Gather information

Work back and forth with me, starting with your open questions and outline
before writing the plan.

## PLAN.md

When I mention a PLAN.md, ask whether to use a git worktree or work directly.

Keep the plan in `PLAN.md` at the root of the worktree
(`./.claude/worktrees/<tree-name>/PLAN.md`), or at the repo root when working
directly. It is the source of truth that survives `/clear`:

- Goal, decisions made (with a short why), open questions.
- Steps as a checklist.
- Key files to re-read when resuming.

Update it as soon as a decision is made, not only after a step.

## Step loop

Keep the context under the limit: 200k tokens or 20% of the window, whichever
comes first, and never past 25%. The context-meter plugin
(`~/.claude/local-plugins/context-meter`) reports usage on demand through
`mcp__context-meter__usage` (load it with ToolSearch), and adds a
`Context window: ...` warning to a tool result once the context passes the
limit.

1. After `/clear`, read `PLAN.md` and the files it lists before doing anything
   else. If no `PLAN.md` is at the root of the current checkout, list
   `.claude/worktrees/*/PLAN.md` and ask which one.
2. Call `mcp__context-meter__usage` and estimate what the first unticked step
   will add. If that would take the context well past the limit, stop and ask
   me to run `/clear`, then `/plan-loop`; if the step alone would, propose
   splitting it. Otherwise implement the step.
3. Update `PLAN.md`: tick the step once its commits land, record decisions and
   findings, name the next step.
4. Re-read all of `PLAN.md` for contradictory or outdated passages and fix
   them.
5. If the step or the re-read raised a decision, a surprise or a change of
   course, discuss it with me. Otherwise continue with the next step (back to
   2).

When the warning arrives:

- If the rest of the step and steps 3–4 fit under 25%, finish them, and add an
  unticked item to `PLAN.md` ahead of the next step: `/self-review` the step,
  since it ran past the limit.
- Otherwise pause: leave the work uncommitted, and record in `PLAN.md` where
  you are in the step and what is left of it.

Then stop and ask me to run `/clear`, then `/plan-loop`.

When every step is done, ask whether to delete `PLAN.md` and, if used, the
worktree. First check its branch is in the main branch
(`git merge-base --is-ancestor HEAD main`). Then:

- From a session inside the worktree: `ExitWorktree` with `remove`. It
  counts commits against the session's starting point, not the main branch,
  so once the branch is merged and I agreed, pass `discard_changes: true`.
- Otherwise, from the main checkout: `git worktree remove <path>`, then
  `git branch -d <branch>` (the worktree removal keeps the branch).

Versions

RepositoryScoreLicence
This page · fredrikaverpil/dotfiles90MIT
gaasher/agent-loop-skills100MIT

Database snapshot: 13.11.2026 · package version ce3748bbc467 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100st-plan-loop
    Write a numbered plan with an acceptance check for each step, critique it once in a fresh pass, revise it, then execute one step at a time. Use when a task touches more than one file, has unclear scope, or failed before because steps were missed. Invoke as /st-plan-loop.
  • 98planning-with-files
    Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+…
  • 100context-management-context-restore
    Restore saved project context, architectural decisions, and work state. Use when resuming interrupted work, retrieving prior context, or merging context across sessions.
  • 100plan-orchestration
    Plan execution through coordinated subagents - delegation, review, verification, integration. Use when executing an existing plan via subagents, including resuming interrupted orchestration. Not for inline execution (plan-execution) or unrelated parallel investigations.
  • 90deep-plan
    The enforced plan → clear → execute flow — think with full context, write the plan to a file, then execute from a fresh session that reads only the plan. Use when the user says "/deep-plan", "plan this properly", "let's not burn context", "execute PLAN-<anything>.md" (that…
  • 84execute-plan
    Execute implementation plans step-by-step. Use when user says "execute the plan", "implement the plan we created", "start building based on the plan", "go ahead and implement it", "proceed with the implementation", "execute as a stack", "create a PR stack while implementing",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.