superwiki 0.1.0 → 0.1.2

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.2",
   "license": "MIT",
   "keywords": [
     "wiki",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sw",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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

@@ -24,7 +24,7 @@ It is built to be cheap for the agent. One small index to read, one file per tas
 Measured on a real project with 165 tasks, converted from a single markdown index:
 
 | | Before | After |
-|---|---|---|
+| --- | --- | --- |
 | Read at the start of every session | 197 KB index | 94-byte catalog + 1.7 KB of rules |
 | Read to start one task | the index, then the task's section | one file, 2 KB at the median |
 | Marking a task done | a status cell, plus a ✅ at every reference to it (median 12 places) | one frontmatter line |
@@ -33,7 +33,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
 
 ## What you get
 
-```
+```text
 docs/
   index.md       catalog of the wiki, one line per page
   log.md         append-only history
@@ -57,7 +57,7 @@ npx superwiki install claude
 This copies the skills into the folder your agent reads. Name one or more targets:
 
 | Target | Installs into | For |
-|---|---|---|
+| --- | --- | --- |
 | `claude` | `~/.claude/skills` | [Claude Code](#claude-code) |
 | `codex` | `~/.agents/skills` | [Codex CLI](#codex-cli) |
 | `copilot` | `~/.copilot/skills` | [GitHub Copilot CLI](#github-copilot-cli) |
@@ -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 publishes through npm trusted publishing, so no token is stored: the package's settings on npmjs.com name this repository and `release.yml` as its trusted publisher.
+
 `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.2",
   "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,44 @@
+# Implementer
+
 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.
+
+What you read is what this task costs, and every extra step re-sends everything you have read so far. Read little, in few steps. Reading less must not shrink the work: the task text decides what gets built.
+
+## Start
+
+1. Read `docs/tasks/<ID>.md` and, if it exists, `docs/plans/<ID>-plan.md`. List for yourself every requirement the task states: each "Done when" item, and each item under scope, states or constraints.
+   - With a plan: open what it lists under "Read first", then work.
+   - Without a plan: run `node docs/.sw/sw.mjs explain <ID>`. If it names an area guide, read it.
+2. Project rules (`AGENTS.md` and the like): if they are not already in your context, list their headings and read only the sections that govern the files you will change.
+
+## How to read
+
+- **Locate, then open.** Search for the symbol, string or file name first. Open the range the search points at, not the file.
+- **Whole files only when you edit across them.** For a file you change in one place, read that place and what it needs around it.
+- **One example per pattern.** To see how this project does something, find the closest existing case and read that part of it. Do not compare several.
+- **Trust the contract.** Generated types, schemas and the task text say what an API returns. Do not read the other side's code to confirm it.
+- **Batch lookups.** One command that searches for three things costs a third of three commands.
+- **Never read twice.** If you need a file again, use what you already have.
+
+A task rarely needs more than a dozen files opened besides the ones it changes. Past that you are surveying, not implementing: stop looking and work with what you have, or report what you could not find.
+
+## Work
+
+1. 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.
+2. Build every requirement on your list. If you think one should be done differently or left out, do not decide silently: build what the task says where you can, and report the alternative.
+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 requirement cannot be met.
+
+## Report
 
-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.
-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.
+About 30 lines:
 
-Report:
-- each "Done when" item: met or not, with the command you ran and its result;
+- `Requirements:` every item from your list, one line each, marked `met` (with the command or test that shows it), `not met` (with what it needs) or `differs` (what you built instead, and why). No item may be missing from this list;
 - files changed;
-- deviations from the plan and why;
-- anything the wiki or a follow-up task should record.
+- other decisions the task or plan left open;
+- if the area has a guide, `Guide:` facts you had to find in the code that it did not state 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,52 @@
-You write the plan for one task in a Superwiki vault. You do not change any file.
-
-Input: a task id, and possibly notes from the conversation with the user.
-
-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).
-
-Return only the plan and the notes.
+# Planner
+
+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 today's date; possibly notes, or feedback on an earlier draft.
+
+What you read is what planning costs, and every extra step re-sends everything you have read so far. Read to decide, not to be thorough.
+
+## Start
+
+1. Run `node docs/.sw/sw.mjs explain <ID>` and read `docs/tasks/<ID>.md`. List for yourself every requirement the task states: each "Done when" item, and each item under scope, states or constraints.
+2. If `explain` names an area guide, read it. Read other linked pages only if the plan depends on what they say. If the plan file already exists, you are revising it.
+3. Project rules (`AGENTS.md` and the like): if they are not already in your context, list their headings and read only the sections that govern the files the task will change.
+
+## How to read
+
+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.
+
+- **Locate, then open.** Search for the symbol, string or file name first. Open the range the search points at, not the file.
+- **One example per pattern.** Find the closest existing case and read that part of it. Do not compare several.
+- **Trust what is stated.** The task, the guide, generated types and schemas say what exists. Check a stated fact in code only where the plan would be wrong if the fact were false.
+- **Batch lookups.** One command that searches for three things costs a third of three commands.
+- **Never read twice.**
+
+## Write the plan
+
+Write `docs/plans/<ID>-plan.md`. Keep it as short as the work allows; most plans fit in 40 to 60 lines.
+
+```text
+---
+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. Every requirement on your list is covered by a step. 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.
+
+## 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.
+- If the area has a guide, `Guide:` facts you had to find in the code that it did not state and the next task in this area would need. 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));