superwiki 0.1.0 → 0.1.2

package/skills/sw-init/assets/templates/plan.md

@@ -1,6 +1,7 @@
 ---
 type: plan
 task: T-01
+status: draft
 updated: YYYY-MM-DD
 ---
 
@@ -8,18 +9,24 @@ updated: YYYY-MM-DD
 
 ## Approach
 
-The chosen approach in a few sentences, and what was ruled out.
+The chosen approach and the assumptions it rests on, in a few lines.
+
+## Read first
+
+- path/to/file: the function, section or lines that matter.
 
 ## Steps
 
-1. Step with the files it touches and how to verify it.
+1. Files, the change in a sentence or two, and how to check it.
 
 ## Verification
 
-Commands or checks that prove the task's "Done when" list.
+- "Done when" item: the command or check that proves it.
 
 <!--
-File: docs/plans/<ID>-plan.md, one plan per task. Rewrite in place; git keeps old versions.
+File: docs/plans/<ID>-plan.md, one plan per task, 40 to 60 lines for most tasks.
+status: draft until the user approves it, then approved. Rewrite in place; git keeps old versions.
+Mark a check "needs: running stack" or "needs: data change" when it cannot run from a clean checkout.
 Design shared by several tasks is a `type: decision` wiki page that the plans link to.
 Delete this comment.
 -->

package/skills/sw-init/assets/viewer.html

@@ -579,8 +579,8 @@ function lint(vault) {
       if (!p.data.type) add('error', 'missing-field', p.path, 'frontmatter `type` is missing');
       if (!p.data.summary) add('warn', 'missing-field', p.path, 'frontmatter `summary` is missing');
       if (vault.index && !vault.index.links.some(l => resolve(vault, l.target) === p)) add('warn', 'not-in-index', p.path, 'page is not listed in index.md');
-      // A source summary is reachable from the index and need not be cited yet; ingest stays a three-file change.
-      if (p.data.type !== 'source' && !p.inbound.some(q => q !== vault.index && q !== vault.log)) add('warn', 'orphan-page', p.path, 'no page links here');
+      // A source summary is reachable from the index and need not be cited yet; an area guide is found by its area, not by links.
+      if (p.data.type !== 'source' && p.data.type !== 'guide' && !p.inbound.some(q => q !== vault.index && q !== vault.log)) add('warn', 'orphan-page', p.path, 'no page links here');
     }
     if (p.folder === 'plans') {
       const id = /-plan$/i.test(p.name) ? p.name.replace(/-plan$/i, '') : null;
@@ -688,6 +688,11 @@ function search(vault, query, limit = 8) {
   return out.sort((a, b) => b.matched - a.matched || lesson(b) - lesson(a) || b.score - a.score || a.page.path.localeCompare(b.page.path)).slice(0, limit);
 }
 
+// The wiki page that tells agents how to work in a task area: `type: guide`, `area: <AREA>`.
+function guideFor(vault, area) {
+  return vault.pages.find(p => p.folder === 'wiki' && p.data.type === 'guide' && key(p.data.area ?? '') === key(area)) || null;
+}
+
 
 // ---------- App. Everything about the vault (frontmatter, links, task state, waves, lint) comes from the core above. ----------
 (() => {

package/skills/sw-init/scripts/init.mjs

@@ -79,7 +79,7 @@ keep(join(docs, 'log.md'), `# Log\n\nAppend-only. Entry format: \`## [YYYY-MM-DD
 write(join(dotdir, '.gitignore'), 'data.js\nserver.json\n');
 refresh(join(assets, 'sw.mjs'), join(dotdir, 'sw.mjs'));
 refresh(join(assets, 'viewer.html'), join(docs, 'viewer.html'));
-for (const t of ['page.md', ...(tasks ? ['task.md', 'plan.md'] : [])]) refresh(join(assets, 'templates', t), join(dotdir, 'templates', t));
+for (const t of ['page.md', ...(tasks ? ['task.md', 'plan.md', 'guide.md'] : [])]) refresh(join(assets, 'templates', t), join(dotdir, 'templates', t));
 
 const config = {
   version: 1,

package/skills/sw-migrate/SKILL.md

@@ -13,8 +13,8 @@ Run everything from the project root. `<skill-dir>` is this skill's directory; `
 
 Stop and tell the user if any of these fails; do not work around them.
 
-- The project is a git repository and `git status --porcelain` is empty.
-- `docs/.sw/` does not exist (already a vault).
+- The project is a git repository, and `git status --porcelain -- docs AGENTS.md CLAUDE.md` is empty: the files this skill rewrites have no uncommitted changes. Uncommitted changes elsewhere do not block; mention them in the report so the user does not mistake them for the migration's.
+- `docs/.sw/config.json` does not exist (already a vault). Empty folders left by an earlier, undone attempt are not a vault; ignore them.
 - Node 18 or newer.
 
 ## Steps

package/skills/sw-plan/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user wants to plan a task or a piece of work in a Supe
 
 # 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. Nothing but task and plan files changes during planning.
+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.
 
@@ -15,32 +15,34 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
    - Id given: `node docs/.sw/sw.mjs check <ID>`, then read `docs/tasks/<ID>.md`. Status `done` or `cancelled`: 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, get the id from `node docs/.sw/sw.mjs next-id <AREA>`, and write `docs/tasks/<ID>.md` from `docs/.sw/templates/task.md` with `status: todo`, a "Goal" and a "Done when" list. Append `## [date] task | <ID> created` to `docs/log.md`.
-2. **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 in step 5. Skip this when nothing is open.
-3. **Enter plan mode** if this tool gives you a way to (Claude Code: `EnterPlanMode`). Otherwise continue. From here on you change no file until step 6.
-4. **Dispatch the planner.** Its prompt is: the task id, today's date, the project root if it is not your working directory, and any feedback from an earlier round. Do not read the code yourself; that is the planner's job and its context, not yours.
+2. **Does it need a plan?** Judge from the task file alone. A task is small when all of these hold: one area, three "Done when" items or fewer, nothing left open in its notes, and the change it describes is confined to a few files. 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.
+3. **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.
+4. **Dispatch the planner.** Its prompt is: the task id, today's date, the project root if it is not your working directory, and any feedback from an earlier round. It writes the plan file as a draft and returns a short message.
 
    | Tool | How |
-   |---|---|
-   | Claude Code | agent `sw-planner`. If it is not among your agent types, use the read-only `Plan` agent, put the content of `<skill-dir>/../sw-config/assets/planner.md` at the top of its prompt, and pass the model from `models.plan.claude` in `docs/.sw/config.json` if set |
+   | --- | --- |
+   | Claude Code | agent `sw-planner`. If it is not among your agent types, use a general-purpose agent, tell it to read `<skill-dir>/../sw-config/assets/planner.md` first and follow it, and pass the model from `models.plan.claude` in `docs/.sw/config.json` if set |
    | Codex | spawn the custom agent `sw_planner` |
    | Copilot CLI | `task` tool with agent `sw-planner` |
    | No subagents available, or the agent is not defined | follow `planner.md` yourself, in this session, and tell the user the configured model was not used |
 
-5. **Show the plan and get approval.** Present the approach, the steps and the planner's notes (Claude Code: through `ExitPlanMode`; anywhere else, as a normal message). The planner returns the plan, then a line `=== notes ===`, then its notes.
-   - Open questions in the notes: ask them, each with the planner's assumed answer as your recommendation. If an answer differs from what the plan assumed, dispatch the planner again with the answers.
-   - The user wants changes: dispatch the planner again with their feedback.
-   - The planner says the work needs splitting: propose the tasks; create them (step 1, "New work") only when the user agrees.
-6. **Write**, after approval:
-   - `docs/plans/<ID>-plan.md`: the text before `=== notes ===`, unchanged. If something in it is wrong, send it back to the planner; do not edit it yourself.
-   - answers given in step 5: add to the task's "Notes".
-   - `docs/log.md`: append `## [date] plan | <ID>`, in the layout the log's last entries use.
+5. **Get approval.** Show the user the planner's `Approach`, its `Questions` (each with the assumed answer as your recommendation) and its `Split`, and name the plan file so they can read it. Do not read the plan file into your own context unless the user asks you about its content. (Claude Code: enter plan mode with `EnterPlanMode` now and present through `ExitPlanMode`, if those tools are available; anywhere else, a normal message.)
+   - An answer differs from what the plan assumed, or the user wants changes: dispatch the planner again with the answers or feedback; it revises the file.
+   - The planner proposes a split: create the tasks (step 1, "New work") only when the user agrees.
+   - The user drops the plan: delete the draft file.
+6. **Record**, after approval:
+   - in the plan file, change `status: draft` to `status: approved`;
+   - in the task's "Notes", the answers given in step 5;
+   - in the area guide, if `node docs/.sw/sw.mjs explain <ID>` names one, the planner's `Guide:` lines, one line per fact;
+   - in `docs/log.md`, a new entry `## [date] plan | <ID>`, in the layout the log's last entries use.
 
    Then run `node docs/.sw/sw.mjs lint`.
-7. **Stop.** Do not start implementing. Tell the user the plan is saved and that sw-implement `<ID>` runs it.
+7. **Stop.** Do not start implementing. Tell the user the plan is approved and that sw-implement `<ID>` runs it.
 
 ## Common mistakes
 
-- Exploring the codebase before dispatching. You pay for it twice.
-- Writing the plan file before approval.
+- Planning a small task. The plan costs more than the work.
+- Exploring the codebase before dispatching, or reading the plan back. You pay for it twice.
+- Editing the plan yourself. If something in it is wrong, send it back to the planner.
 - Setting the task to `in-progress`. Planning does not change status.
 - Planning several tasks in one plan file. One task, one plan; shared design goes to a `type: decision` wiki page that the plans link.