superwiki 0.1.0 → 0.1.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sw",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "keywords": [
     "wiki",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sw",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
   "license": "MIT",
   "skills": "./skills/",

package/README.md

@@ -153,33 +153,71 @@ A project's `docs/` folder is plain markdown and keeps working as an Obsidian va
 
 ## Use
 
+| Skill | What it does |
+| --- | --- |
+| `sw-init` | set up `docs/` in the current project, or upgrade it |
+| `sw-migrate` | convert an existing table-based task index, on a new git branch |
+| `sw-ingest` | file a source into the wiki |
+| `sw-plan` | plan a task with the planner subagent and get your approval |
+| `sw-implement` | run a task with the implementer subagent and record the result |
+| `sw-explain` | explain a task: what, why, dependencies, what it unblocks |
+| `sw-triage` | for a problem: seen before? lessons, likely causes |
+| `sw-lint` | structural checks by script, semantic review on request |
+| `sw-visualize` | open the viewer |
+| `sw-config` | the model each tool uses for planning and implementing; task areas |
+
+### Examples
+
+Shown as typed in Claude Code. In Codex, write `$sw-plan` instead of `/sw-plan`. Task ids are an area prefix and a number, such as `P-15`.
+
+```text
+/sw-init                          set up the vault; asks whether you want tasks
+/sw-migrate                       convert the task tables this project already has
+
+/sw-plan                          what can start now? pick one and plan it
+/sw-plan P-15                     plan task P-15 (a small task is sent straight to sw-implement)
+/sw-plan add CSV export to the sources page
+                                  new work: creates the task, then plans it
+
+/sw-implement P-15                run P-15; refuses if a dependency is not done
+/sw-implement                     continue what is in progress, or pick a ready task
+
+/sw-explain M-06                  what M-06 is, why it exists, what it waits on and unblocks
+/sw-triage photo uploads hang at 100% on mobile since yesterday
+                                  has this happened before? lessons and likely causes
+/sw-ingest ~/Downloads/interview-notes.md
+                                  file a source and summarise it into the wiki
+
+/sw-config plan with opus, implement with sonnet
+/sw-lint                          check links, frontmatter and task dependencies
+/sw-visualize                     open the task board and the wiki in the browser
 ```
-sw-init        set up docs/ in the current project
-sw-migrate     convert an existing table-based task index, on a new git branch
-sw-ingest      file a source from docs/raw/ into the wiki
-sw-plan        plan a task with a planner subagent, save the approved plan
-sw-implement   run a task with an implementer subagent, record the result
-sw-explain     explain a task: what, why, dependencies, what it unblocks
-sw-triage      for a problem: seen before? lessons, likely causes
-sw-lint        structural checks by script, semantic review on request
-sw-visualize   open the viewer
-sw-config      models per role and tool, task areas
+
+You do not have to type a command. The rules `sw-init` adds to `AGENTS.md` tell the agent which skill fits, so a plain request should reach the same skill:
+
+```text
+What should I work on next?
+Implement P-15.
+Why does M-06 exist, and what is it blocked by?
+Users get the magic-link email twice. Have we seen this before?
 ```
 
 A filled-in example vault is in [examples/demo/docs](examples/demo/docs).
 
-After that, from the project root:
+### The CLI
+
+The skills call a small script that answers questions without the agent reading the vault. You can run it yourself, from the project root:
 
 ```bash
-node docs/.sw/sw.mjs status        # counts per area
-node docs/.sw/sw.mjs ready         # tasks that can start now
-node docs/.sw/sw.mjs check M-01    # what blocks this task
-node docs/.sw/sw.mjs explain M-01  # its place in the dependency chain
-node docs/.sw/sw.mjs search sync timeout   # where something is mentioned
-node docs/.sw/sw.mjs next-id M     # next free id
-node docs/.sw/sw.mjs lint          # broken links, bad frontmatter, dependency errors
-node docs/.sw/sw.mjs serve --open  # the viewer, reading files live
-node docs/.sw/sw.mjs snapshot      # or: freeze the vault into docs/viewer.html, no server
+node docs/.sw/sw.mjs status                 # counts per area
+node docs/.sw/sw.mjs ready                  # tasks that can start now
+node docs/.sw/sw.mjs check P-15             # can it start or finish, and what is open
+node docs/.sw/sw.mjs explain P-15           # dependencies, what it unblocks, plan, area guide
+node docs/.sw/sw.mjs search sync timeout    # where something is mentioned
+node docs/.sw/sw.mjs next-id P              # next free id in an area
+node docs/.sw/sw.mjs lint                   # broken links, bad frontmatter, dependency errors
+node docs/.sw/sw.mjs serve --open           # the viewer, reading files live
+node docs/.sw/sw.mjs snapshot               # or: freeze the vault into docs/viewer.html, no server
 ```
 
 ## Develop
@@ -188,6 +226,8 @@ node docs/.sw/sw.mjs snapshot      # or: freeze the vault into docs/viewer.html,
 npm test       # builds skills/sw-init/assets/sw.mjs, then runs the tests
 ```
 
+Releases are cut by the `Release` workflow (Actions → Release → Run workflow): it tests, bumps the version in `package.json` and the plugin manifests, publishes to npm, tags, and creates a GitHub release. It needs the repository secret `NPM_TOKEN`.
+
 `node scripts/build-demo.mjs` builds the public demo into `site/` (the viewer with the example vault baked in); the Pages workflow deploys it on every push to `main`.
 
 `src/core.js` is shared by the CLI and the viewer. Edit sources in `src/`; the files in `skills/sw-init/assets/` named `sw.mjs` and `viewer.html` are generated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superwiki",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Agent skills that turn docs/ into an LLM-maintained wiki and task tracker. Obsidian-friendly. Works with Claude Code, Codex and Copilot CLI.",
   "keywords": [
     "claude-code",

package/skills/sw-config/SKILL.md

@@ -20,11 +20,11 @@ node <skill-dir>/scripts/config.mjs sync --tools claude,codex,copilot
 
 A model is chosen per role (`plan`, `implement`) and per tool (`claude`, `codex`, `copilot`), because each tool can only run its own models. No tool lets a skill change the model of the running session, so sw-plan and sw-implement hand the work to a subagent, and the subagent's file carries the model.
 
-| Tool | File the script writes | Read-only planner by |
-|---|---|---|
-| Claude Code | `.claude/agents/sw-planner.md`, `sw-implementer.md` | `tools:` list |
-| Codex | `.codex/agents/sw-planner.toml`, `sw-implementer.toml` | `sandbox_mode` |
-| Copilot CLI | `.github/agents/sw-planner.agent.md`, `sw-implementer.agent.md` | `tools:` list |
+| Tool | Files the script writes |
+|---|---|
+| Claude Code | `.claude/agents/sw-planner.md`, `sw-implementer.md` |
+| Codex | `.codex/agents/sw-planner.toml`, `sw-implementer.toml` |
+| Copilot CLI | `.github/agents/sw-planner.agent.md`, `sw-implementer.agent.md` |
 
 When the user asks to set a model:
 

package/skills/sw-config/assets/implementer.md

@@ -1,15 +1,20 @@
 You implement one task in a Superwiki vault.
 
-Input: a task id.
+Input: a task id; possibly which checks you may run that need services or data.
 
-1. Read `docs/tasks/<ID>.md` and, if it exists, `docs/plans/<ID>-plan.md`. Read linked pages only when a step needs them.
-2. Do the work. Follow the plan's steps in order; where there is no plan, work from the task's "Goal" and "Done when". Follow the repository's own rules (`AGENTS.md`).
-3. Verify each "Done when" item with the plan's verification commands. Run them; do not assume.
-4. Do not edit `docs/tasks/<ID>.md`, `docs/log.md` or `docs/index.md`: the session that dispatched you records status. If you learned something the wiki should hold (a decision made, a constraint found), say so in your report instead of writing it.
+1. Read `docs/tasks/<ID>.md` and, if it exists, `docs/plans/<ID>-plan.md`.
+   - With a plan: open the files under its "Read first", then work. Do not explore beyond what a step turns out to need.
+   - Without a plan: run `node docs/.sw/sw.mjs explain <ID>`, read the area guide it names if any, then find the files to change.
+   - Do not re-read instruction files that are already in your context. Read linked pages only when a step needs them.
+2. Do the work. Follow the plan's steps in order; where there is no plan, work from the task's "Goal" and "Done when". Follow the repository's own rules.
+3. Verify. After a step, run the narrowest check that covers it. Run the full verification list once, at the end, after the last edit.
+   - A check marked `needs: ...` in the plan runs only if your input says it may. Otherwise report it as not verified, with what it needs.
+4. Do not edit `docs/tasks/<ID>.md`, `docs/log.md`, `docs/index.md` or the plan: the session that dispatched you records status.
 5. Stop and report, without guessing, if the plan cannot be followed as written, a dependency is missing, or a "Done when" item cannot be met.
 
-Report:
+Report, in about 25 lines:
 - each "Done when" item: met or not, with the command you ran and its result;
 - files changed;
-- deviations from the plan and why;
-- anything the wiki or a follow-up task should record.
+- deviations from the plan, and why;
+- `Guide:` facts you had to find in the code that neither the plan nor the area guide stated and the next task in this area would need. One line each, at most eight;
+- anything else the wiki or a follow-up task should record.

package/skills/sw-config/assets/planner.md

@@ -1,17 +1,32 @@
-You write the plan for one task in a Superwiki vault. You do not change any file.
+You write the plan for one task in a Superwiki vault. The only file you create or change is `docs/plans/<ID>-plan.md`.
 
-Input: a task id, and possibly notes from the conversation with the user.
+Input: a task id and today's date; possibly notes, or feedback on an earlier draft.
 
-1. Read `docs/tasks/<ID>.md`. Read the pages it links only if the task depends on what they say. Read `docs/plans/<ID>-plan.md` if it exists: you are revising it.
-2. Read the code the task touches. Find the existing patterns the work must follow and the commands that verify it.
-3. Return the plan as the complete content of `docs/plans/<ID>-plan.md`, in the format of `docs/.sw/templates/plan.md`: frontmatter (`type: plan`, `task: <ID>`, `updated:` today), then `## Approach`, `## Steps`, `## Verification`.
-   - Steps are ordered, each names the files it touches and how to check it. Someone with no other context must be able to follow them.
-   - Verification maps every "Done when" item of the task to a command or check.
-   - Link vault pages as `[[file-name]]`; refer to code by plain path.
-   - The plan is saved without the notes and read by someone who has only the task file and the plan. Do not refer to the notes, to these instructions or to agent files from inside it. Where you had to assume an answer to an open question, state the assumption in `## Approach`.
-   - Check every example output you quote by running or tracing the code; do not guess what the current code returns.
-4. After the plan, under a line `=== notes ===`, list:
-   - open questions that only the user can answer;
-   - if the work does not fit one working session: how to split it into tasks (title and dependencies for each).
+Planning is paid for in what you read. Read to decide, not to be thorough.
 
-Return only the plan and the notes.
+1. Run `node docs/.sw/sw.mjs explain <ID>` and read `docs/tasks/<ID>.md`. If `explain` names an area guide, read it: it records where things are, the patterns to follow and how to verify, so you need not rediscover them. Read other linked pages only if the plan depends on what they say. If the plan file already exists, you are revising it.
+2. Read code to answer three questions: which files change, which existing pattern to copy, how the result is verified. Stop when you can answer them.
+   - Search first, then open the part you need; open a whole file only when you must edit across it.
+   - Do not re-read instruction files that are already in your context.
+   - Trust what the task and the guide state. Check a stated fact in code only where the plan would be wrong if the fact were false.
+3. Write `docs/plans/<ID>-plan.md`. Keep it as short as the work allows; most plans fit in 40 to 60 lines.
+
+   ```
+   ---
+   type: plan
+   task: <ID>
+   status: draft
+   updated: <today>
+   ---
+   ```
+
+   - `## Approach`: the chosen approach and every assumption you made, in a few lines. Mention a rejected option only if someone would otherwise try it.
+   - `## Read first`: the files the implementer must open, each with the part that matters (function, section or line range). After these, nothing should need exploring.
+   - `## Steps`: in order. Each step names its files, says the change in one or two sentences, and gives its check. Write exact text only where exactness matters: keys, user-facing strings, signatures, test cases (as a table). Leave out code the implementer can write from the description, and leave out status bookkeeping (task file, log): the dispatching session does that.
+   - `## Verification`: each "Done when" item with the command or check that proves it. Put `needs: running stack` or `needs: data change` on a check that cannot run from a clean checkout without starting services or altering data.
+   - Link vault pages as `[[file-name]]`; refer to code by plain path. Verify any current output you quote by running or tracing the code.
+4. Return a short message, not the plan:
+   - `Approach:` three lines at most.
+   - `Questions:` what only the user can answer, each with the answer the plan assumes. Leave out if none.
+   - `Split:` if the work does not fit one session, the tasks to split it into (title, dependencies). Leave out if not needed.
+   - `Guide:` facts you had to find in the code that the area guide did not state and the next task in this area would need (where something lives, a convention, a verification command). One line each, at most eight.

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

@@ -1,104 +1,179 @@
 #!/usr/bin/env node
-// Reads and changes docs/.sw/config.json, and writes the planner and implementer agent
-// definitions each tool needs. In all three tools a model is bound to an agent file, not chosen at run time.
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+// Reads and changes docs/.sw/config.json, and writes the planner and implementer agent files.
+// A coding tool binds a model to an agent definition, not to a running session, so choosing a
+// model for a role means writing that role's agent file for that tool.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const assets = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
-const TOOLS = ['claude', 'codex', 'copilot'];
+const ASSETS = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
+const GENERATED = 'Generated by sw-config from docs/.sw/config.json. Change models with sw-config, not here.';
+const AREA_ID = /^[A-Za-z][A-Za-z0-9]*$/;
+
 const ROLES = {
-  plan: { name: 'sw-planner', file: 'planner.md', readOnly: true, description: 'Writes the plan for one Superwiki task. Read-only. Use from sw-plan.' },
-  implement: { name: 'sw-implementer', file: 'implementer.md', readOnly: false, description: 'Implements one Superwiki task from its task and plan files. Use from sw-implement.' },
+  plan: {
+    name: 'sw-planner',
+    instructions: 'planner.md',
+    description: 'Writes the plan file for one Superwiki task. Use from sw-plan.',
+  },
+  implement: {
+    name: 'sw-implementer',
+    instructions: 'implementer.md',
+    description: 'Implements one Superwiki task from its task and plan files. Use from sw-implement.',
+  },
+};
+
+// How each tool wants an agent defined: where the file goes and what it looks like.
+const TOOLS = {
+  claude: {
+    path: role => `.claude/agents/${role.name}.md`,
+    render: (role, body, model) => markdownAgent(role, body, model),
+  },
+  codex: {
+    path: role => `.codex/agents/${role.name}.toml`,
+    render: (role, body, model) => [
+      `# ${GENERATED}`,
+      `name = "${role.name.replace(/-/g, '_')}"`,
+      `description = ${JSON.stringify(role.description)}`,
+      ...(model ? [`model = ${JSON.stringify(model)}`] : []),
+      // TOML literal strings cannot contain three single quotes in a row.
+      `developer_instructions = '''\n${body.replace(/'''/g, "' ' '")}\n'''`,
+      '',
+    ].join('\n'),
+  },
+  copilot: {
+    path: role => `.github/agents/${role.name}.agent.md`,
+    render: (role, body, model) => markdownAgent(role, body, model),
+  },
 };
+
+function markdownAgent(role, body, model) {
+  const frontmatter = [`name: ${role.name}`, `description: ${role.description}`, ...(model ? [`model: ${model}`] : [])];
+  return `---\n${frontmatter.join('\n')}\n---\n\n<!-- ${GENERATED} -->\n\n${body}\n`;
+}
+
+const TOOL_NAMES = Object.keys(TOOLS);
+const ROLE_NAMES = Object.keys(ROLES);
+
 const HELP = `config.mjs <command> [--root <dir>]
 
   show                                   print the configuration
-  model <plan|implement> <tool> <model>  set the model a tool uses for a role (tool: ${TOOLS.join(', ')})
-  model <plan|implement> <tool> --unset  go back to the tool's default model
+  model <${ROLE_NAMES.join('|')}> <tool> <model>  set the model a tool uses for a role (tool: ${TOOL_NAMES.join(', ')})
+  model <${ROLE_NAMES.join('|')}> <tool> --unset  go back to the tool's default model
   areas "M=Mobile,B=Backend"             add or rename task areas (existing areas are never removed)
   sync [--tools claude,codex]            (re)write agent files for the given tools, or for every configured tool`;
 
-const argv = process.argv.slice(2);
-const ri = argv.indexOf('--root');
-const root = resolve(ri >= 0 ? argv[ri + 1] : '.');
-if (ri >= 0) argv.splice(ri, 2);
-const [cmd, ...rest] = argv;
-const fail = msg => { console.error(msg); process.exit(2); };
-if (!cmd || cmd === '--help' || cmd === 'help') { console.log(HELP); process.exit(0); }
-
-const configPath = join(root, 'docs/.sw/config.json');
-if (!existsSync(configPath)) fail('no docs/.sw/config.json here; run sw-init first');
-const config = JSON.parse(readFileSync(configPath, 'utf8'));
-config.models = { plan: {}, implement: {}, ...config.models };
-config.tools = config.tools || [];
-
-const put = (rel, content) => {
-  const p = join(root, rel);
-  const before = existsSync(p) ? readFileSync(p, 'utf8') : null;
-  if (before !== content) { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, content); }
-  console.log(`${before === null ? 'created  ' : before === content ? 'unchanged' : 'updated  '} ${rel}`);
-};
-const header = 'Generated by sw-config from docs/.sw/config.json. Change models with sw-config, not here.';
-
-function sync(tools) {
-  for (const [role, r] of Object.entries(ROLES)) {
-    const body = readFileSync(join(assets, r.file), 'utf8').trim();
-    const model = tool => config.models[role]?.[tool];
-    if (tools.includes('claude')) {
-      const fm = ['---', `name: ${r.name}`, `description: ${r.description}`];
-      if (r.readOnly) fm.push('tools: Read, Grep, Glob');
-      if (model('claude')) fm.push(`model: ${model('claude')}`);
-      put(`.claude/agents/${r.name}.md`, `${fm.join('\n')}\n---\n\n<!-- ${header} -->\n\n${body}\n`);
-    }
-    if (tools.includes('codex')) {
-      const lines = [`# ${header}`, `name = "${r.name.replace(/-/g, '_')}"`, `description = ${JSON.stringify(r.description)}`];
-      if (model('codex')) lines.push(`model = ${JSON.stringify(model('codex'))}`);
-      if (r.readOnly) lines.push('sandbox_mode = "read-only"');
-      lines.push(`developer_instructions = '''\n${body.replace(/'''/g, "' ' '")}\n'''`);
-      put(`.codex/agents/${r.name}.toml`, lines.join('\n') + '\n');
-    }
-    if (tools.includes('copilot')) {
-      const fm = ['---', `name: ${r.name}`, `description: ${r.description}`];
-      if (r.readOnly) fm.push('tools: ["read", "search"]');
-      if (model('copilot')) fm.push(`model: ${model('copilot')}`);
-      put(`.github/agents/${r.name}.agent.md`, `${fm.join('\n')}\n---\n\n<!-- ${header} -->\n\n${body}\n`);
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  const args = [];
+  let root = '.';
+  let tools = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') root = argv[++i] ?? '.';
+    else if (argv[i] === '--tools') tools = (argv[++i] ?? '').split(',').map(s => s.trim()).filter(Boolean);
+    else args.push(argv[i]);
+  }
+  return { command: args[0], args: args.slice(1), root: resolve(root), tools };
+}
+
+function loadConfig(root) {
+  const path = join(root, 'docs/.sw/config.json');
+  if (!existsSync(path)) throw new UsageError('no docs/.sw/config.json here; run sw-init first');
+  const config = JSON.parse(readFileSync(path, 'utf8'));
+  config.models = { plan: {}, implement: {}, ...config.models };
+  config.tools ??= [];
+  return { config, save: () => writeFileSync(path, JSON.stringify(config, null, 2) + '\n') };
+}
+
+const formatAreas = areas => Object.entries(areas).map(([id, name]) => `${id}=${name}`).join(', ');
+
+// Writes a generated file and says what happened to it, judged by content.
+function writeGenerated(root, relPath, content) {
+  const path = join(root, relPath);
+  const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  if (before !== content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+  }
+  const state = before === null ? 'created  ' : before === content ? 'unchanged' : 'updated  ';
+  console.log(`${state} ${relPath}`);
+}
+
+function writeAgentFiles(root, config, toolNames) {
+  for (const [roleName, role] of Object.entries(ROLES)) {
+    const body = readFileSync(join(ASSETS, role.instructions), 'utf8').trim();
+    for (const toolName of toolNames) {
+      const tool = TOOLS[toolName];
+      writeGenerated(root, tool.path(role), tool.render(role, body, config.models[roleName][toolName]));
     }
   }
 }
-const save = () => writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 
-if (cmd === 'show') {
-  console.log(`tasks: ${config.tasks ? 'on' : 'off'}`);
-  if (config.tasks) console.log(`areas: ${Object.entries(config.areas).map(([k, v]) => `${k}=${v}`).join(', ')}`);
-  for (const role of Object.keys(ROLES)) {
-    console.log(`${role}: ${TOOLS.map(t => `${t}=${config.models[role][t] || 'default'}`).join('  ')}`);
+function rememberTools(config, toolNames) {
+  for (const name of toolNames) if (!config.tools.includes(name)) config.tools.push(name);
+}
+
+const COMMANDS = {
+  show({ config }) {
+    console.log(`tasks: ${config.tasks ? 'on' : 'off'}`);
+    if (config.tasks) console.log(`areas: ${formatAreas(config.areas)}`);
+    for (const role of ROLE_NAMES) {
+      console.log(`${role}: ${TOOL_NAMES.map(tool => `${tool}=${config.models[role][tool] || 'default'}`).join('  ')}`);
+    }
+    console.log(`agent files for: ${config.tools.join(', ') || 'none'}`);
+  },
+
+  model({ root, config, save, args }) {
+    const [role, tool, model] = args;
+    if (!ROLES[role] || !TOOLS[tool] || !model) {
+      throw new UsageError(`usage: config.mjs model <${ROLE_NAMES.join('|')}> <${TOOL_NAMES.join('|')}> <model|--unset>`);
+    }
+    if (model === '--unset') delete config.models[role][tool];
+    else config.models[role][tool] = model;
+    rememberTools(config, [tool]);
+    save();
+    writeAgentFiles(root, config, [tool]);
+  },
+
+  areas({ config, save, args }) {
+    if (!config.tasks) throw new UsageError('the task module is off; run sw-init with --tasks first');
+    for (const pair of (args[0] || '').split(',').map(s => s.trim()).filter(Boolean)) {
+      const [id, ...nameParts] = pair.split('=');
+      if (!AREA_ID.test(id)) throw new UsageError(`bad area id "${id}"`);
+      config.areas[id] = nameParts.join('=').trim() || config.areas[id] || id;
+    }
+    save();
+    console.log(`areas: ${formatAreas(config.areas)}`);
+  },
+
+  sync({ root, config, save, tools }) {
+    const toolNames = tools ?? config.tools;
+    const unknown = toolNames.filter(name => !TOOLS[name]);
+    if (unknown.length) throw new UsageError(`unknown tool: ${unknown.join(', ')}`);
+    if (!toolNames.length) throw new UsageError(`no tools configured; pass --tools ${TOOL_NAMES.join(',')}`);
+    rememberTools(config, toolNames);
+    save();
+    writeAgentFiles(root, config, toolNames);
+  },
+};
+
+function main(argv) {
+  const { command, args, root, tools } = parseArgs(argv);
+  if (!command || command === 'help' || command === '--help') {
+    console.log(HELP);
+    return 0;
   }
-  console.log(`agent files for: ${config.tools.join(', ') || 'none'}`);
-} else if (cmd === 'model') {
-  const [role, tool, model] = rest;
-  if (!ROLES[role] || !TOOLS.includes(tool) || !model) fail(`usage: config.mjs model <plan|implement> <${TOOLS.join('|')}> <model|--unset>`);
-  if (model === '--unset') delete config.models[role][tool];
-  else config.models[role][tool] = model;
-  if (!config.tools.includes(tool)) config.tools.push(tool);
-  save();
-  sync([tool]);
-} else if (cmd === 'areas') {
-  if (!config.tasks) fail('the task module is off; run sw-init with --tasks first');
-  for (const pair of (rest[0] || '').split(',').map(s => s.trim()).filter(Boolean)) {
-    const [id, ...name] = pair.split('=');
-    if (!/^[A-Za-z][A-Za-z0-9]*$/.test(id)) fail(`bad area id "${id}"`);
-    config.areas[id] = name.join('=').trim() || config.areas[id] || id;
+  try {
+    const run = COMMANDS[command];
+    if (!run) throw new UsageError(`unknown command ${command}\n\n${HELP}`);
+    run({ root, args, tools, ...loadConfig(root) });
+    return 0;
+  } catch (error) {
+    if (!(error instanceof UsageError)) throw error;
+    console.error(error.message);
+    return 2;
   }
-  save();
-  console.log(`areas: ${Object.entries(config.areas).map(([k, v]) => `${k}=${v}`).join(', ')}`);
-} else if (cmd === 'sync') {
-  const ti = rest.indexOf('--tools');
-  const tools = ti >= 0 ? rest[ti + 1].split(',').map(s => s.trim()) : config.tools;
-  const bad = tools.filter(t => !TOOLS.includes(t));
-  if (bad.length) fail(`unknown tool: ${bad.join(', ')}`);
-  if (!tools.length) fail('no tools configured; pass --tools claude,codex,copilot');
-  for (const t of tools) if (!config.tools.includes(t)) config.tools.push(t);
-  save();
-  sync(tools);
-} else fail(`unknown command ${cmd}\n\n${HELP}`);
+}
+
+process.exitCode = main(process.argv.slice(2));

package/skills/sw-implement/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user wants to implement, build, execute, start or cont
 
 # sw-implement
 
-Runs one task. You keep the task's status true and judge the result; an implementer subagent, running the model set in sw-config, does the work from the task and plan files.
+Runs one task. You keep the task's status true and judge the result; an implementer subagent, running the model set in sw-config, does the work from the task and plan files. You do not read the code or the plan: the report is your input.
 
 Run commands from the project root. `<skill-dir>` is the directory this SKILL.md is in.
 
@@ -16,9 +16,11 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    - `can start: no  open deps: ...`: stop. Tell the user which tasks block it and offer to run the first blocker instead; do not run it unasked. Do not start the task anyway, and do not edit `deps` to get past this.
    - `can start: n/a, status is in-progress`: this is a continuation; skip step 3.
    - `can start: n/a, status is done` or `cancelled`: stop and ask what the user wants.
-   - `plan: none`: say so. Small tasks can run from "Goal" and "Done when"; for anything larger, recommend sw-plan first and let the user choose.
+   - `plan: ... (draft, not approved)`: stop; the plan needs the user's approval (sw-plan).
+   - `plan: none`: fine for a small task (one area, three "Done when" items or fewer, nothing open in its notes, a few files). For anything larger, recommend sw-plan first and let the user choose.
 3. **Mark it started** before any work: in the frontmatter of `docs/tasks/<ID>.md` set `status: in-progress` and `started:` today. Append `## [date] task | <ID> started` to `docs/log.md`, in the layout its last entries use.
-4. **Dispatch the implementer.** Its prompt is the task id, plus the project root if it is not your working directory. Do not paste the plan into the prompt; it reads the files.
+4. **Checks that need the environment.** If the task has a plan, look for `needs:` in it: `grep -n 'needs:' docs/plans/<ID>-plan.md`. Each hit is a check that starts services or changes data. Ask the user which of them the implementer may run; without a yes, none.
+5. **Dispatch the implementer.** Its prompt is the task id, the project root if it is not your working directory, and which `needs:` checks it may run. Do not paste the plan into the prompt; it reads the files.
 
    | Tool | How |
    |---|---|
@@ -27,8 +29,8 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    | Copilot CLI | `task` tool with agent `sw-implementer` |
    | No subagents available, or the agent is not defined | follow `implementer.md` yourself, in this session, and tell the user the configured model was not used |
 
-5. **Judge the report** against the task's "Done when" list. Every item needs evidence: a command and its result. Re-run a verification command yourself when the report is vague. An item without evidence is not met.
-6. **Record the outcome.**
+6. **Judge the report** against the task's "Done when" list. Every item needs evidence: a command and its result. Re-run one verification command yourself when the report is vague. An item without evidence is not met.
+7. **Record the outcome.**
 
    | Outcome | Task file | Log entry |
    |---|---|---|
@@ -36,11 +38,14 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    | Items met but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
    | Blocked or partly done | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |
 
-7. **File what was learned.** If the implementer reported a decision or constraint the wiki should hold, offer to save it as a wiki page (`type: decision` or `concept`) and add it to `index.md`. If the task fixed a problem whose cause is now known, offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later. If it reported follow-up work, offer to create the tasks. These are separate offers: act on each only when the user says yes to that one.
-8. **Report** to the user: outcome, evidence per "Done when" item, files changed, deviations from the plan, and which tasks this unblocked (`node docs/.sw/sw.mjs ready`). Commit only if the user asks.
+8. **Keep the area guide.** Add the report's `Guide:` lines to the guide of the task's area, `docs/wiki/guide-<area, lowercase>.md` (`type: guide`, `area: <AREA>`; `node docs/.sw/sw.mjs explain <ID>` prints its path). No guide yet: create it from `docs/.sw/templates/guide.md` and list it in `index.md`. One line per fact under Layout, Patterns, Verify or Gotchas; replace a line the new fact corrects; keep the page under 60 lines. Do this without asking: the guide is what makes the next task in this area cheaper, because planners and implementers read it instead of exploring.
+9. **File what else was learned.** If the implementer reported a decision or constraint the wiki should hold, offer to save it as a wiki page (`type: decision` or `concept`) and add it to `index.md`. If the task fixed a problem whose cause is now known, offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later. If it reported follow-up work, offer to create the tasks. These are separate offers: act on each only when the user says yes to that one.
+10. **Report** to the user: outcome, evidence per "Done when" item, files changed, deviations from the plan, and which tasks this unblocked (`node docs/.sw/sw.mjs ready`). Commit only if the user asks.
 
 ## Common mistakes
 
 - Marking `done` because the implementer said so. Done means every "Done when" item has evidence.
 - Starting work before the task file says `in-progress`. If the session dies, nobody knows the task was touched.
 - Letting the implementer edit the task file or the log. One writer for status: you.
+- Reading the plan or the code "to follow along". The implementer already paid for that.
+- Skipping the guide update. Every fact left out is explored again by the next task.

package/skills/sw-init/assets/agents-block.md

@@ -11,19 +11,36 @@
 - `docs/tasks/<ID>.md`: one task per file. `docs/plans/<ID>-plan.md`: its plan, if any.
 {{/tasks}}
 - Anything else under `docs/` belongs to other tools. Leave it alone.
+- File formats: `docs/.sw/templates/`.
 
-Rules:
+Wiki:
 
 - Link vault pages as `[[file-name]]`; file names are unique across the vault. Use normal markdown links for `raw/` files and URLs, and plain paths for code.
 - When you add or rename a wiki page, update its line in `index.md`.
 - Answer questions from the wiki, index first. Offer to save an answer worth keeping as a wiki page.
+{{^tasks}}
+- When you change the project, append one `change` entry to `log.md`: what changed and why, in a line.
+- `node docs/.sw/sw.mjs search <words>` finds where something is mentioned; `lint` checks links and frontmatter. Neither needs you to read files. Run `lint` after you add, rename or relink pages.
+{{/tasks}}
 {{#tasks}}
-- A task's status lives only in its frontmatter. Before you start: `status: in-progress` and `started:`. When its "Done when" list is met: `status: done` and `finished:`. Each change gets a `task` entry in `log.md`.
+
+Tasks:
+
+- A task's status lives only in its frontmatter. Before you start: `status: in-progress` and `started:`. When its "Done when" list is met: `status: done` and `finished:`. Each change of status gets a `task` entry in `log.md`.
 - Do not start a task while any of its `deps` is not done.
+- Before you change code for a task, read the area guide that `explain <ID>` names (`docs/wiki/guide-<area>.md`): where things are, patterns, how to verify. Afterwards add the facts it was missing, one line each.
+- Work that belongs to no task (a quick fix, a small request) needs no task file. Append one `change` entry to `log.md` instead: what changed and why, in a line.
 - `node docs/.sw/sw.mjs status|ready|check <ID>|explain <ID>|search <words>|next-id <AREA>|lint` answers overview, startable tasks, blockers, a task's place in the chain, where something is mentioned, new ids and structural checks without reading files. Run `lint` after you add, rename or relink pages.
 {{/tasks}}
-{{^tasks}}
-- `node docs/.sw/sw.mjs search <words>` finds where something is mentioned; `lint` checks links and frontmatter. Neither needs you to read files. Run `lint` after you add, rename or relink pages.
+
+Skills. Use these without being asked. For work in this vault they come before any other planning, implementing or debugging skill:
+
+{{#tasks}}
+- Planning a task, or the user asks what to work on next: `sw-plan`.
+- Implementing a task: `sw-implement`. A change that needs no plan and touches one or two files may be done directly, under the task rules above.
+- A question about a task (what, why, what it blocks): `sw-explain`.
 {{/tasks}}
-- File formats: `docs/.sw/templates/`.
+- A bug, failure or unexpected behavior is reported: `sw-triage` first, before any debugging.
+- A source to file (article, notes, transcript, URL): `sw-ingest`.
+- If a skill is not installed, follow the rules above by hand.
 <!-- sw:end -->