sw-plan
Use when the user wants to plan a task or a piece of work in a Superwiki project before building it, asks what to work on next, or invokes sw-plan, with or without a task id.
mhmtsrfglu · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add mhmtsrfglu/superwiki --skill sw-planAbout this skill
name: sw-plan description: Use when the user wants to plan a task or a piece of work in a Superwiki project before building it, asks what to work on next, or invokes sw-plan, with or without a task id.
sw-plan
Produces docs/plans/<ID>-plan.md for one task. You clarify with the user and get approval; a planner subagent, running the model set in sw-config, reads the code and writes the plan file. You never read the code and never hold the plan text: that is what keeps planning cheap.
Needs the task module (docs/tasks/). If it is missing, say so and offer sw-init with --tasks. Run commands from the project root. <skill-dir> is the directory this SKILL.md is in; the planner's role file, planner.md, is <skill-dir>/assets/planner.md.
The plan is a file under docs/plans/, and a task is a file under docs/tasks/. When the host's plan mode, a memory tool or a rule of the host keeps this session from writing under docs/ or from running the shell (a plan mode that holds its plan in the host's own memory or session folder is such a case), stop before the first write: name the obstacle to the user, ask them to lift it (leave plan mode, allow the writes, give the session a shell), and wait. A plan kept anywhere but docs/plans/<ID>-plan.md is not the plan: do not present it as one and do not record an approval of it.
Steps
-
Pick the task.
- Id given:
node docs/.sw/sw.mjs check <ID>, then readdocs/tasks/<ID>.md. Statusdoneorcancelled: stop and ask what the user wants. A plan already exists: this run revises it; say so. Open deps do not prevent planning. - No id, existing work:
node docs/.sw/sw.mjs ready, and let the user choose. - New work: agree on title, area and dependencies with the user, and get the id from
node docs/.sw/sw.mjs next-id <AREA>. Then:- write
docs/tasks/<ID>.mdfromdocs/.sw/templates/task.mdwithstatus: todo, a "Goal" and a "Done when" list; - append
## [date] task | <ID> createdtodocs/log.md; - run
node docs/.sw/sw.mjs index, so the task list inindex.mdshows it.
- write
- Id given:
-
Does it need a plan? Called from sw-plan-implement: the route is already chosen; skip this step. Otherwise judge by this rule, word for word as sw-plan-implement and sw-implement state it:
A task is small when its task file alone shows all four: one area, meaning its work belongs to the configured area its id prefix names and to no other (
areasindocs/.sw/config.json; with one configured area, every task is in one area); three "Done when" items or fewer, as thedone when:line ofnode docs/.sw/sw.mjs check <ID>counts them; nothing left open in its "Notes"; and the files that change, named in the task file, three or fewer. A task whose file does not show how many files change is medium at least, never small.A small task needs no plan: say so and offer
sw-implement <ID>directly. Go on with planning only if the user wants a plan anyway, or the task is not small. -
Clarify. Ask the user only what the task file leaves open about scope or intent, one question at a time, each with your recommendation. Add the answers to the task's "Notes" now. Do not read code to find questions; the planner surfaces the technical ones. Skip this when nothing is open.
-
Dispatch the planner. Its prompt is: the task id, today's date, the project root if it is not your working directory, and, from the second round on, what the user's reply changed: the answers that differ from the ones the plan assumed, the feedback, the ids of the tasks a split created, or
split declined. It writes the plan file as a draft and returns a short message.A second round goes to the planner that wrote the draft where the tool can continue it (a further message to that agent), otherwise to a fresh one.
The agent is the one sw-config wrote for the host, named
sw-planner(sw_plannerin Codex), carryingplanner.mdand the model set undermodels.plan. Where the host's documentation does not say how a session runs a named custom agent, the row says so: ask for the agent by name, and if nothing runs it, take the last row.Tool How Claude Code agent sw-planner. If it is not among your agent types, use a general-purpose agent, tell it to readplanner.mdfirst and follow it, and pass the model frommodels.plan.claudeindocs/.sw/config.jsonif setCodex the custom agent sw_planner, from.codex/agents/sw-planner.toml. Codex spawns agents with its multi-agent tools (spawn_agentand the rest, on by default); whether a spawn can name a custom agent is not documented, so ask forsw_plannerby name in the spawn, and if the spawned agent is not it, the last rowCopilot CLI the custom agent sw-planner, from.github/agents/sw-planner.agent.md. The CLI delegates to a subagent that runs a custom agent when the model chooses to; the tool it delegates with is not documented, so ask for thesw-planneragent by name in the prompt, and if no subagent runs it, the last rowVS Code Copilot Chat the same file, .github/agents/sw-planner.agent.md. An agent delegates with theagenttool to the agents itsagentslist names; how a plain chat session names one is not documented, so ask for thesw-planneragent by name, and if the delegation does not run it, the last rowNo subagents available, or the agent is not defined follow planner.mdyourself, in this session, and tell the user the configured model was not used -
Present the plan and get approval. Show the user, in a normal message, the planner's
Approach, itsQuestions(each with the assumed answer as your recommendation), itsSplit, and the path of the plan file so they can read it. Plan mode is not used: a reply can need files written before the plan is shown again. Read the plan file into your own context only if the user asks you about its content.Handle the reply in th