Skill: pieterjanliekens/plan-mode (version 3.0.4)

--- name: plan description: "Think-first execution with approval gating. Use when work is complex, ambiguous, irreversible, multi-step, worth comparing before choosing, interrupted and needs recovery, or long-running enough to need a living plan. Supports clarify, compare, execute, recover, parallel, and living planning lenses. Not for simple edits or quick questions." --- # Plan Use this skill to stop execution-first behavior on meaningful work. Default pattern: **clarify → plan → approve → execute → close**. Treat `/plan` as a **read-only planning stance** until approval. Safe reads are allowed: reading files, listing files, searching, inspecting docs, checking status, and other non-destructive exploration. Do not edit files, delete data, push commits, deploy, or run destructive or irreversible commands until the user approves a plan or explicitly says to skip planning. Prefer the **core lenses** first. Use `parallel` and `living` only when the work is clearly big enough to justify the extra structure. ## When to stay out of the way Do not force planning for: - trivial single-file edits - simple factual questions - obvious follow-up micro-actions - work where the user explicitly says to skip planning ## Command model Use `/plan` as an auto-router. Pick the lens that matches the real problem. ### Core lenses | Command | Use for | Output | |---|---|---| | `/plan` | Auto-pick the right lens | Short diagnosis + recommended plan | | `/plan clarify` | Vague or political requests | Scope, assumptions, open questions, success criteria | | `/plan compare` | Choosing between options | Option matrix, tradeoffs, recommendation | | `/plan execute` | Clear multi-step work | Ordered plan, risks, checkpoints, definition of done | | `/plan recover` | Interrupted or messy work | Current state, what is done, what is blocked, safest next step | ### Advanced lenses | Command | Use for | Output | |---|---|---| | `/plan parallel` | Work that should split across subagents or lanes | Solo lane, parallel lanes, merge points | | `/plan living` | Multi-session or strategic work | Persistent plan with decisions, next actions, open loops | ### Auto-router heuristics When the user just says `/plan`, pick the simplest fitting lens: - unclear request, fuzzy scope, or political ambiguity → `clarify` - explicit choice between 2+ viable paths → `compare` - clear multi-step task with real execution work → `execute` - interrupted, messy, or half-finished work → `recover` - only escalate to `parallel` if there are clearly separable lanes with owners and a merge point - only escalate to `living` if the work is likely to span multiple sessions, days, or major checkpoints If two lenses could fit, prefer the simpler one. ### Depth modifiers Use these as optional modifiers, not separate lenses: - `light` — use for small work, usually <= 5 steps, no lasting state needed - `standard` — default for normal complex work - `deep` — use for risky, irreversible, multi-day, or file-backed work ### Format guidance #### Light Use for short tasks. Keep output inline: - Goal - Approach - 2-5 steps - Main risk #### Standard Use for most work. Include: - Goal - Recommended lens - Approach - Using - Steps - Risks - Approval ask Keep it short enough that the user can approve it quickly. #### Deep Use for large or risky work. Include: - Goal - Context / current state - Option or approach rationale - Detailed steps - Checkpoints - Risks and reversibility - Definition of done - Optional persistent file only after explicit approval if the plan should survive compaction Examples: - `/plan compare` - `/plan recover light` - `/plan living deep` - `/plan off` Use `/plan off` to disable auto-activation for the current session. ## What to do in each lens ### Clarify Use when the request is still fuzzy. Do this: - Define the actual problem - Surface assumptions - List open questions only if they materially affect the plan - State success criteria and non-goals Do not jump into solution design too early. ### Compare Use when multiple routes are plausible. Do this: - Compare 2-4 realistic options - Show tradeoffs: speed, risk, reversibility, cost, maintenance, politics - Recommend one path and explain why Prefer recommendation over fence-sitting. ### Execute Use for normal complex work. Do this: - State goal and approach - List concrete steps - Flag irreversible or high-risk actions with `⚠️` - State dependencies, checkpoints, and definition of done - Ask for approval before acting ### Recover Use when work already exists and the problem is continuity, not invention. Do this: - Summarize current state - Distinguish completed / partial / blocked / unknown - Give the safest next step - Say what should be discarded, preserved, or verified Prefer stabilization over cleverness. ### Parallel Use only when splitting work clearly improves speed or clarity. Do this: - Separate solo work from delegable work - Define lanes with owners - Define merge points and shared assumptions - Keep parallelism minimal and purposeful Do not parallelize tiny tasks just because you can. ### Living Use for long-running projects. Do this: - Before creating a new living plan, first check whether one already exists for the project - Do not write or update a living-plan file until the user explicitly approves persistent storage - Once approved, persist the plan to file when useful - If the project has no existing convention, default to a simple plan file under `docs/plans/` or another clearly named project folder - Keep these sections updated: - current focus - next actions - decisions - open loops - risks - On session start, resume, or after compaction, reload the latest approved living plan before continuing - If the living plan is stale enough to be doubtful, say so and refresh it before acting Prefer living plans for strategy, negotiations, and multi-day builds. ## Approval contract Until approval: - Stay read-only - Inspect files, docs, and current state - Audit available tools and skills using local/project context first - Do not create or update plan files - Do not make external network lookups for toolbox audit unless the user explicitly approves that broader search - Compare approaches - Ask only the minimum blocking questions After approval: - Execute only the approved scope - Respect partial approvals like “do 1-3, hold on 4” - If reality changes materially, stop and re-plan Recognize these approval patterns: - `go` - `do it` - `do steps 1-3` - `hold on 4` - `skip plan` - `cancel` - similar clearly positive approval language such as "sounds good" or "yes, proceed" Control semantics: - `/plan off` = stop auto-activating this skill for the current session - `cancel` before execution = abort the plan and do nothing - `cancel` during partial execution = stop immediately, report what has already been done, and do not assume rollback unless explicitly asked ## Surprise policy Pause and report when: - a required tool, file, or dependency was missing from the plan - risk becomes meaningfully higher than planned - destructive action becomes necessary unexpectedly - new information changes the recommendation Do not silently widen scope. ## Toolbox audit Before presenting an execute-oriented plan: - Check relevant installed skills first - Prefer local/project-available capabilities over reinvention - Only check external registries such as ClawHub when it materially changes the recommendation and the user has approved that broader search - Do not send plan contents, secrets, or private project details to external services during toolbox audit Show this briefly in a `Using:` section when it materially changes the approach. ## Likely failure modes to avoid - Using `parallel` for work that is still unclear - Using `living` for tasks that are actually small and one-shot - Presenting too many lenses at once instead of recommending one - Turning `/plan` into ceremony on obvious work ## Example patterns ### Example: compare User: “Should we launch in market A or market B first?” Output: - Option A: Market A first - Option B: Market B first - Tradeoffs - Recommendation ### Example: execute User: “Migrate auth from sessions to JWT.” Output: - Goal - Approach - Using - Ordered steps - `⚠️` irreversible cleanup step - Approval ask ### Example: recover User: “Everything is all over the place. Pick this back up.” Output: - Current state - What is done - What is blocked - Safest next step ### Example: parallel User: “Review the repo, draft migration steps, and prep the rollout note.” Output: - Solo lane - Parallel lanes with owners - Merge point - Approval ask ### Example: living User: “Track this negotiation through 14 April.” Output: - Current focus - Next actions - Decisions - Open loops - Resume instruction

path: references/patterns.md
content: # Plan Mode Patterns Across AI Tools

Reference material on planning implementations. Load only when comparing approaches.

## Claude Code (Anthropic)

- **Activation:** `Shift+Tab` cycle or `/plan` prefix or `--permission-mode plan`
- **Behavior:** Read-only. Reads files, runs shell commands to explore, asks questions, writes plan. No source edits
- **Approval flow:** Approve + auto mode, approve + accept edits, approve + manual review, or keep planning. Can clear planning context
- **Key design:** Permission mode (structural tool restriction), not just a prompt

## Aider

- **Modes:** `/ask` (no changes), `/code` (execute), `/architect` (two-model)
- **Architect mode:** Reasoning model proposes → Editor model formats edits. Two LLM calls
  - Architect/Editor pairs significantly outperform solo models on editing benchmarks
  - Even same model as both architect and editor improves over solo baseline
- **Key insight:** Separating reasoning from editing lets each model focus on its strength

## OpenAI Codex CLI

- **Modes:** `suggest` (show diffs, per-change approval) vs `auto-apply`
- **AGENTS.md:** Repo-level instructions guide agent behavior
- **Key insight:** Granular per-change approval at diff level

## Cursor

- **Modes:** Agent (full autonomy) vs Ask (read-only)
- **Key insight:** Binary simplicity — no intermediate modes

## Windsurf (Cascade)

- **Modes:** Code (modify) vs Chat (questions, can propose insertable code)
- **Background planning agent:** Runs alongside execution, continuously refines long-term plan
- **Todo lists:** Visible in conversation, user-modifiable, auto-updating
- **Checkpoints:** Named project snapshots, revertible
- **Key insight:** Planning as background process, not mode switch. Living document

## Roo Code

- **5 modes:** Code, Ask, Architect (read + markdown-only edit), Debug, Orchestrator
- **Orchestrator:** No tools — delegates to other modes via `new_task`. Strategic coordinator
- **Per-mode model binding:** Each mode remembers its model
- **Custom modes:** Define tool access + persona + file permissions
- **Key insight:** Mode = tool restrictions + persona + model. Orchestrator = plan → delegate

## ExecPlan (tiann/execplan-skill)

- **Philosophy:** Plan as living document. Self-contained — reader needs zero prior context
- **Required sections:** Progress (checkboxes), Surprises & Discoveries, Decision Log, Outcomes & Retrospective
- **Plan to file:** Saved to `execplan/` directory, survives context resets
- **Milestones:** Each independently verifiable with observable outcomes
- **Key insight:** Plan is not a conversation artifact — it's a persistent file that tracks state across sessions. "Resolve ambiguities autonomously" during execution but document all decisions

## claw-superpowers (cutd)

- **7-step workflow:** Brainstorm → Plan → Execute → Test → Debug → Review → Finish
- **Hard gates:** "Do NOT write code until design approved" — non-negotiable
- **Plan format:** Saved to `docs/plans/YYYY-MM-DD-*.md`, includes exact file paths, complete code, exact commands
- **Subagent-driven execution:** Fresh subagent per task + two-stage review (spec then quality)
- **Execution handoff:** Plan offers two paths: subagent-driven (this session) or parallel session
- **Key insight:** Plans contain complete code (not "add validation"), assume implementer has zero context. Mandatory brainstorm before plan. Review after every task

## Universal Pattern

All tools converge on: Understand → Propose → Gate → Execute → Verify

**Gate placement differentiates:**
- **Plan-level:** Claude Code, Aider ask, Roo Architect, claw-superpowers
- **Change-level:** Codex suggest (per-diff)
- **Background:** Windsurf (concurrent plan + execute)
- **Delegation:** Roo Orchestrator, claw-superpowers subagents
- **Living document:** ExecPlan (file-persisted, session-independent)

**For conversational agents (OpenClaw):** Plan-level gating is most natural. Living-document pattern valuable for complex multi-session work. Subagent delegation useful for parallel independent tasks.

## Unique to this skill: Toolbox Audit

None of the tools above include a "what do I already have?" step in their planning phase. This skill adds:
- Scan installed skills before planning approach
- Search skill registries (ClawHub, GitHub) for relevant existing skills
- Surface "already installed" vs "available to install" in the plan

This prevents the common anti-pattern of agents reinventing capabilities that already exist in their skill library. Example: an agent asked to "make a PDF report" that writes raw Python instead of loading the installed `pdf-generator` skill.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)