superwiki 0.1.5 → 0.1.7

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.5",
+  "version": "0.1.7",
   "license": "MIT",
   "keywords": [
     "wiki",

package/.codex-plugin/plugin.json

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

@@ -29,7 +29,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
 
 | | Before | After |
 | --- | --- | --- |
-| Read at the start of every session | 197 KB index | 94-byte catalog + 2.7 KB of rules |
+| Read at the start of every session | 197 KB index | 7.7 KB index (the 97 open tasks, a line each) + 2.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 |
 
@@ -39,7 +39,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
 
 ```text
 docs/
-  index.md       catalog of the wiki, one line per page
+  index.md       the open tasks, then the catalog of the wiki, one line per page
   log.md         append-only history
   raw/           your sources, never modified
   wiki/          pages the agent writes
@@ -50,6 +50,31 @@ docs/
 
 `AGENTS.md` gets a short block of rules so the agent maintains the vault in every session, with or without a command.
 
+You can follow the work without the viewer: `index.md` opens with the task list, written from the task files. Each open task is a line that links to its file; finished ones are listed by id.
+
+```markdown
+## Tasks
+
+ready 9 · in progress 1 · blocked 18 · done 20
+
+**In progress**
+
+- [[B-20]] Portfolio sync · M5
+
+**Ready**
+
+- [[F-01]] Frontend skeleton and guards · M0
+- [[B-18]] Valuation · M4
+
+**Blocked**
+
+- [[B-21]] Journal and thesis gates · M5 · waits on B-20
+
+**Done (20)** [[B-01]] [[B-02]] [[B-03]] ...
+```
+
+A task's status still lives only in its own file. The list is a view: the agent rewrites it with `sw.mjs board` whenever a task changes, and `lint` says when it has fallen behind.
+
 ## Install
 
 Requires Node 18 or newer.
@@ -170,8 +195,10 @@ A project's `docs/` folder is plain markdown and keeps working as an Obsidian va
 | `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, have it reviewed if the task asks for that, and record the result |
+| `sw-run` | work through several tasks in a row, unattended: plan, implement, review and record each, and stop when one needs you |
 | `sw-explain` | explain a task: what, why, dependencies, what it unblocks |
 | `sw-triage` | for a problem: seen before? lessons, likely causes |
+| `sw-board` | refresh the task list in `index.md` from the task files |
 | `sw-lint` | structural checks by script, semantic review on request |
 | `sw-visualize` | open the viewer |
 | `sw-stats` | what the current session has cost: tokens, context, steps and tool calls, per agent |
@@ -193,6 +220,9 @@ Shown as typed in Claude Code. In Codex, write `$sw-plan` instead of `/sw-plan`.
 
 /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-run the backend tasks, commit after each
+                                  one task after another without asking at each step;
+                                  stops when a task needs you, and reports what it decided
 
 /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
@@ -201,6 +231,7 @@ Shown as typed in Claude Code. In Codex, write `$sw-plan` instead of `/sw-plan`.
                                   file a source and summarise it into the wiki
 
 /sw-config plan with opus, implement with sonnet, review with opus
+/sw-board                         refresh the task list in index.md after you edited tasks by hand
 /sw-lint                          check links, frontmatter and task dependencies
 /sw-visualize                     open the task board and the wiki in the browser
 /sw-stats                         what this session has cost so far, per agent
@@ -263,7 +294,8 @@ node docs/.sw/sw.mjs check P-15             # can it start or finish, what is op
 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 board                  # rewrite the task list in index.md from the task files
+node docs/.sw/sw.mjs lint                   # broken links, bad frontmatter, dependency errors, a stale task list
 node docs/.sw/sw.mjs stats                  # tokens, context and steps of the agent session here
 node docs/.sw/sw.mjs doctor                 # what that session carried before it read anything
 node docs/.sw/sw.mjs serve --open           # the viewer, reading files live
@@ -281,6 +313,7 @@ Edit sources in `src/`:
 | File | What it is |
 | --- | --- |
 | `src/core.js` | the vault model, derived task state, lint and search; shared by the CLI and the viewer |
+| `src/board.js` | the task list in `index.md` |
 | `src/sessions.js` | finds the record an agent keeps of a session |
 | `src/stats.js` | reduces a session record to cost per agent |
 | `src/doctor.js` | reduces a session record to what the session started with |

package/commands/board.md

@@ -0,0 +1,5 @@
+---
+description: Refresh the task list in docs/index.md from the task files
+---
+
+Use the sw-board skill. User arguments: $ARGUMENTS

package/commands/run.md

@@ -0,0 +1,5 @@
+---
+description: Work through several tasks one after another, unattended: plan, implement, review and record each
+---
+
+Use the sw-run skill. User arguments: $ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superwiki",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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-board/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sw-board
+description: Use when the user wants the task list in docs/index.md refreshed, updated or rebuilt, says the index is out of date after editing tasks by hand, or invokes sw-board or sw:board.
+---
+
+# sw-board
+
+Rewrites the task list at the top of `docs/index.md` from the task files. One command; do not read the task files or write the list yourself.
+
+Run from the project root:
+
+```bash
+node docs/.sw/sw.mjs board
+```
+
+It prints whether the list changed and the counts. Tell the user that, in one line. Only its own section of `index.md` is rewritten; what the user wrote around it stays.
+
+The list is a view. A task's status lives in the frontmatter of `docs/tasks/<ID>.md`: to change what the list shows, change the task file and run the command again. Never edit the list by hand.
+
+## If it fails
+
+| Output | Do |
+| --- | --- |
+| `unknown command board` | the project's `docs/.sw/sw.mjs` is older than this skill; offer to run sw-init, which updates it and writes the list |
+| `this vault has no task module` | say so; sw-init with `--tasks` adds it |
+| `docs/index.md is missing` | offer to run sw-init |
+
+If the user asks what is ready, what blocks a task or how many are done, answer with `node docs/.sw/sw.mjs ready|check <ID>|status` instead of reading the list.

package/skills/sw-config/SKILL.md

@@ -37,9 +37,11 @@ No tool lets a skill change the model of the running session, so the skills hand
 
 When the user asks to set a model:
 
-1. Ask only for what is missing: role, tool, model. If they name a model without a tool, infer the tool from the model family and say which you chose. Use the model name exactly as that tool spells it; do not translate names between tools.
-2. Run the `model` command. Show its output.
-3. Say that a tool picks up new agent files when its next session starts.
+1. **See what is set**: `show`.
+2. **Settle role, tool and model.** Ask only for what is missing. If they name a model without a tool, infer the tool from the model family and say which you chose. Use the model name exactly as that tool spells it; do not translate names between tools.
+3. **Change only what differs.** If the role already runs that model, change nothing and say so. A tool's short name and the full name of its current version (`opus` and the newest Opus) are the same model: do not rewrite one into the other.
+4. **Run the `model` command** and show its output.
+5. **Say when it takes effect**: a tool picks up new agent files when its next session starts.
 
 After Superwiki itself is updated, run `sync` once: the roles' instructions are part of the agent files.
 

package/skills/sw-implement/SKILL.md

@@ -25,7 +25,10 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    | `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 |
    | `review: required (...)` | remember it for step 7 |
 
-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.
+3. **Mark it started** before any work:
+   - in the frontmatter of `docs/tasks/<ID>.md`, `status: in-progress` and `started:` today;
+   - in `docs/log.md`, a new entry `## [date] task | <ID> started`, in the layout its last entries use;
+   - `node docs/.sw/sw.mjs board`, so the task list in `index.md` shows it.
 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 may run; without a yes, none.
 5. **Dispatch the implementer** (how: "Dispatching" below). 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.
 6. **Judge the report.** Its `Requirements:` list must name every "Done when" item and every scope, state or constraint item of the task; compare it with the task file.
@@ -36,7 +39,7 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    - `Verdict: pass`: go on. Pass `important` and `minor` findings to the user in your report; they do not block.
    - `Verdict: changes needed`: dispatch the implementer again with the blocking findings, word for word, then the reviewer again with the files changed since. After two rounds that still end in `changes needed`, stop and put the findings to the user.
    - Do not review the change yourself in place of the reviewer, and do not argue a blocking finding away. If you think a finding is wrong, say so to the user and let them decide.
-8. **Record the outcome.**
+8. **Record the outcome**, then run `node docs/.sw/sw.mjs board`.
 
    | Outcome | Task file | Log entry |
    | --- | --- | --- |
@@ -50,7 +53,7 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
 10. **File what else was learned.** These are separate offers: act on each only when the user says yes to that one.
     - A report held a decision or constraint the wiki should keep: offer a wiki page (`type: decision` or `concept`), added to `index.md`.
     - The task fixed a problem whose cause is now known, or the review caught a defect worth remembering: offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later.
-    - A report named follow-up work: offer to create the tasks.
+    - A report named follow-up work, or the review left `important` findings open: offer to create the tasks. A finding that lives only in the log is forgotten.
 11. **Report** to the user, in this order. Commit only if the user asks.
     - the outcome;
     - each requirement with its evidence, and anything that differs from the task;
@@ -77,6 +80,7 @@ The same table serves both roles: `sw-implementer` with `implementer.md`, `sw-re
 - Accepting a `differs` item on the user's behalf. A sensible alternative is still not what the task asked for.
 - Skipping the review on a task that requires it, or doing it yourself in the same context that judged the implementation.
 - Starting work before the task file says `in-progress`. If the session dies, nobody knows the task was touched.
-- Letting a subagent edit the task file or the log. One writer for status: you.
+- Letting a subagent edit the task file, the log or the task list. One writer for status: you.
+- Editing the task list in `index.md` by hand. It is written from the task files; change the task file and run `board`.
 - Reading the plan or the code "to follow along". The subagents already paid for that.
 - Running the next task in the same session out of momentum.

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

@@ -3,7 +3,12 @@
 
 `docs/` is a wiki you write and keep current, and an Obsidian vault the user reads.
 
+{{#tasks}}
+- `docs/index.md`: the open tasks, then the catalog, one line per wiki page. Read it first, then open only the pages you need.
+{{/tasks}}
+{{^tasks}}
 - `docs/index.md`: catalog, one line per wiki page. Read it first, then open only the pages you need.
+{{/tasks}}
 - `docs/log.md`: append-only. Add `## [YYYY-MM-DD] <kind> | <title>` at the end; read it with `tail`, never whole.
 - `docs/raw/`: sources. Read, never modify.
 - `docs/wiki/`: flat, one page per topic, frontmatter `type:` and one-line `summary:`.
@@ -27,6 +32,7 @@ Wiki:
 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`.
+- The task list in `index.md` is written from the task files. After you add a task or change a task's status, title, milestone or dependencies, run `node docs/.sw/sw.mjs board`. Never edit that list by hand.
 - Do not start a task while any of its `deps` is not done.
 - If `explain <ID>` names an area guide (`docs/wiki/guide-<area>.md`), read it before you change code for the task: 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.
@@ -38,6 +44,7 @@ Skills. Use these without being asked. For work in this vault they come before a
 {{#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.
+- Several tasks in a row without the user at each step: `sw-run`.
 - A question about a task (what, why, what it blocks): `sw-explain`.
 {{/tasks}}
 - A bug, failure or unexpected behavior is reported: `sw-triage` first, before any debugging.

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Generated by scripts/build.mjs from src/core.js, src/sessions.js, src/stats.js, src/doctor.js, src/cli.js. Do not edit.
+// Generated by scripts/build.mjs from src/core.js, src/board.js, src/sessions.js, src/stats.js, src/doctor.js, src/cli.js. Do not edit.
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve as resolvePath, sep } from 'node:path';
@@ -322,6 +322,75 @@ export function guideFor(vault, area) {
   return vault.pages.find(p => p.folder === 'wiki' && p.data.type === 'guide' && key(p.data.area ?? '') === key(area)) || null;
 }
 
+// The task board: the open tasks as a section of index.md, so a person can follow the work in the
+// vault itself, without the viewer. It is a view, written from the task files by `sw.mjs board`
+// and never edited by hand; a task's status still lives only in its own frontmatter.
+// Open tasks get a line each. Finished ones are listed by id only, so the section stays small as
+// a project grows: index.md is the one file every session reads.
+
+const BOARD_START = '<!-- sw:board:start (written by `sw.mjs board`; do not edit) -->';
+const BOARD_END = '<!-- sw:board:end -->';
+const BOARD_BLOCK = /<!-- sw:board:start[^\n]*-->\n[\s\S]*?<!-- sw:board:end -->/;
+const REFRESH = 'run `node docs/.sw/sw.mjs board`';
+
+// Sections in reading order: what is being worked on, what can start, what waits.
+const OPEN_STATES = [['progress', 'In progress'], ['ready', 'Ready'], ['blocked', 'Blocked']];
+
+function openLine(vault, task) {
+  // A dependency that does not exist is lint's finding, not something a task waits on.
+  const waiting = task.openDeps.filter(id => taskOf(vault, id));
+  return [
+    `- [[${task.id}]] ${task.title}`,
+    ...(task.milestone ? [task.milestone] : []),
+    ...(task.state === 'blocked' && waiting.length ? [`waits on ${waiting.join(', ')}`] : []),
+  ].join(' · ');
+}
+
+// The board for this vault, markers included.
+export function taskBoard(vault) {
+  const { total } = summary(vault);
+  const counts = [
+    `ready ${total.ready}`, `in progress ${total.progress}`, `blocked ${total.blocked}`, `done ${total.done}`,
+    ...(total.cancelled ? [`cancelled ${total.cancelled}`] : []),
+  ];
+  const sections = OPEN_STATES
+    .map(([state, heading]) => [heading, tasksIn(vault, state)])
+    .filter(([, tasks]) => tasks.length)
+    .map(([heading, tasks]) => `**${heading}**\n\n${tasks.map(task => openLine(vault, task)).join('\n')}`);
+  // Finished tasks are looked up, not worked through: by id, not in running order.
+  const done = tasksIn(vault, 'done').map(task => task.id).sort((a, b) => a.localeCompare(b, 'en', { numeric: true })).map(id => `[[${id}]]`);
+  const paragraphs = [
+    '## Tasks',
+    total.total ? counts.join(' · ') : 'No tasks yet.',
+    ...sections,
+    ...(done.length ? [`**Done (${done.length})** ${done.join(' ')}`] : []),
+  ];
+  return `${BOARD_START}\n${paragraphs.join('\n\n')}\n${BOARD_END}`;
+}
+
+export const boardIn = indexText => (String(indexText).match(BOARD_BLOCK) || [null])[0];
+
+// index.md with this board in it: in place of the one it has, otherwise right under the title.
+export function indexWithBoard(indexText, board) {
+  const text = String(indexText);
+  if (BOARD_BLOCK.test(text)) return text.replace(BOARD_BLOCK, () => board);
+  const title = text.match(/^# .*\n?/);
+  if (!title) return `${board}\n\n${text}`;
+  const rest = text.slice(title[0].length).replace(/^\n+/, '');
+  return `${title[0].trimEnd()}\n\n${board}\n${rest ? `\n${rest}` : ''}`;
+}
+
+// A lint finding when index.md does not show the tasks as they are now, else null.
+export function boardFinding(vault) {
+  if (!vault.index) return null; // a missing index is reported on its own
+  const current = boardIn(vault.index.body);
+  if (!current && !vault.tasks.size) return null; // a vault without tasks needs no board
+  if (current === taskBoard(vault)) return null;
+  return current
+    ? { level: 'warn', code: 'stale-board', path: 'index.md', message: `the task list is out of date; ${REFRESH}` }
+    : { level: 'warn', code: 'missing-board', path: 'index.md', message: `the tasks are not listed; ${REFRESH}` };
+}
+
 // Finds the record an agent tool keeps of the session working in a project.
 // Claude Code, Codex and Copilot CLI each write every session to disk in their own layout; this
 // lists a project's sessions as { tool, id, modified, current, source } and picks one. What a
@@ -913,6 +982,7 @@ const HELP = `sw <command> [--docs <dir>] [--json]
   explain <ID>    a task's dependencies, what it blocks and unblocks, its plan and linked pages
   search <words>  pages and log entries that mention the words, best match first
   next-id <AREA>  next free task id for an area (numbers are never reused)
+  board           rewrite the task list in docs/index.md from the task files
   lint            structural checks; exit code 1 on errors
   stats           what the agent session here has cost so far: steps, context and tokens per agent
   doctor          what that session carried before it read anything: rule files, skill and tool lists
@@ -1128,8 +1198,25 @@ function nextIdCommand({ vault, args }) {
   return { data: { id }, text: id };
 }
 
+// The task list in index.md is a view of the task files; this writes it again from them.
+function boardCommand({ docs, vault }) {
+  if (!existsSync(join(docs, 'tasks'))) return { error: 'this vault has no task module (docs/tasks); sw-init --tasks adds it', code: 1 };
+  const path = join(docs, 'index.md');
+  if (!existsSync(path)) return { error: 'docs/index.md is missing; run sw-init', code: 1 };
+  const before = readFileSync(path, 'utf8');
+  const after = indexWithBoard(before, taskBoard(vault));
+  const changed = after !== before;
+  if (changed) writeFileSync(path, after);
+  const { total } = summary(vault);
+  return {
+    data: { changed, ready: total.ready, inProgress: total.progress, blocked: total.blocked, done: total.done },
+    text: `board: docs/index.md ${changed ? 'updated' : 'unchanged'}  ready ${total.ready}  in-progress ${total.progress}  blocked ${total.blocked}  done ${total.done}`,
+  };
+}
+
 function lintCommand({ vault }) {
-  const findings = lint(vault);
+  const board = boardFinding(vault);
+  const findings = [...lint(vault), ...(board ? [board] : [])];
   const errors = findings.filter(f => f.level === 'error').length;
   return {
     data: findings,
@@ -1272,6 +1359,7 @@ const COMMANDS = {
   explain: { run: explain, needsVault: true },
   search: { run: searchCommand, needsVault: true },
   'next-id': { run: nextIdCommand, needsVault: true },
+  board: { run: boardCommand, needsVault: true },
   lint: { run: lintCommand, needsVault: true },
   stats: { run: statsCommand, needsVault: false },
   doctor: { run: doctorCommand, needsVault: false },

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Scaffolds docs/ as a Superwiki vault. Safe to re-run: user content is kept, tool files are
 // replaced with this version, and the report says which was which.
+import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +12,7 @@ const MANAGED_BLOCK = /<!-- sw:start[\s\S]*?<!-- sw:end -->/;
 // What a vault consists of at the top of docs/. Anything else there belongs to someone else.
 const VAULT_ENTRIES = ['index.md', 'log.md', 'raw', 'wiki', 'tasks', 'plans', 'viewer.html'];
 const ROLES = ['plan', 'implement', 'review'];
+const NEW_INDEX = '# Index\n\n## Wiki\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n';
 
 const HELP = `init.mjs [--root <dir>] [--tasks | --no-tasks] [--areas "M=Mobile,B=Backend"]
 
@@ -116,7 +118,7 @@ function writeVault(docs, tasks, report) {
   }
 
   const today = new Date().toISOString().slice(0, 10);
-  report.keep(join(docs, 'index.md'), '# Index\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n');
+  report.keep(join(docs, 'index.md'), NEW_INDEX);
   report.keep(join(docs, 'log.md'), `# Log\n\nAppend-only. Entry format: \`## [YYYY-MM-DD] kind | title\`.\n\n## [${today}] init | Superwiki vault created\n`);
 
   // The viewer snapshot and the local server's address are per-machine and regenerated on demand.
@@ -128,6 +130,18 @@ function writeVault(docs, tasks, report) {
   }
 }
 
+// The task list in index.md is the one part of that file the tool owns. The vault's own CLI
+// writes it, so an upgraded vault gets the list in the format of the version just installed.
+function writeTaskBoard(docs, report) {
+  const index = join(docs, 'index.md');
+  const cli = join(docs, '.sw', 'sw.mjs');
+  if (!existsSync(cli)) return; // already reported as missing
+  const before = readFileSync(index, 'utf8');
+  const run = spawnSync(process.execPath, [cli, 'board', '--docs', docs], { encoding: 'utf8' });
+  if (run.status !== 0) return report.line('note', `the task list in docs/index.md was not written: ${run.stderr.trim()}`);
+  report.line(readFileSync(index, 'utf8') === before ? 'unchanged' : 'updated', 'docs/index.md (task list)');
+}
+
 function writeAgentRules(root, tasks, report) {
   const block = schemaBlock(tasks);
   const agentsPath = join(root, 'AGENTS.md');
@@ -174,6 +188,7 @@ function main(argv) {
   const hadTaskFiles = !previous && existsSync(join(docs, 'tasks'));
   const report = createReport(root);
   writeVault(docs, tasks, report);
+  if (tasks) writeTaskBoard(docs, report);
   const config = buildConfig(previous, { root, tasks, areas: options.areas });
   report.write(configPath, JSON.stringify(config, null, 2) + '\n');
   writeAgentRules(root, tasks, report);

package/skills/sw-lint/SKILL.md

@@ -17,6 +17,7 @@ Two passes. The first is a script and costs almost nothing. The second reads pag
 
    | Finding | Fix |
    |---|---|
+   | `stale-board`, `missing-board` | `node docs/.sw/sw.mjs board`: it rewrites the task list in `index.md` from the task files. Never edit that list by hand |
    | `not-in-index` | add `- [[page]]: summary` to `index.md`, using the page's `summary:` |
    | `missing-field` `summary` | copy it from the page's line in `index.md`; if there is none, read the page and write it |
    | `missing-field` `type` | read that page, write the field |

package/skills/sw-plan/SKILL.md

@@ -14,7 +14,10 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
 1. **Pick the task.**
    - 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`.
+   - 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>.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`;
+     - run `node docs/.sw/sw.mjs board`, so the task list in `index.md` shows it.
 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.
@@ -36,7 +39,7 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
    - 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`.
+   Then run `node docs/.sw/sw.mjs lint`. If it reports `stale-board`, a task's title, milestone or dependencies changed along the way: run `node docs/.sw/sw.mjs board`.
 7. **Stop.** Do not start implementing. Tell the user the plan is approved and that sw-implement `<ID>` runs it.
 
 ## Common mistakes
@@ -46,3 +49,4 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
 - 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.
+- Adding the new task to the list in `index.md` by hand. `board` writes that list from the task files.

package/skills/sw-run/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: sw-run
+description: Use when the user wants several Superwiki tasks worked through one after another without being asked at each step (run the backlog, do all tasks of an area, keep going until done or blocked, act as orchestrator), or invokes sw-run or sw:run.
+---
+
+# sw-run
+
+Works through tasks in order, unattended: for each one, plan it if it needs a plan, implement it, have it reviewed if it requires that, record it, and go on to the next. You are the orchestrator. Every piece of work goes to a subagent with a clean context; your session holds only the queue, the reports and the decisions.
+
+Each task is run exactly as sw-implement runs it. This skill adds what a run of many needs: answers agreed once at the start, decisions you make in the user's place and write down, and rules for when to stop.
+
+Run commands from the project root.
+
+## Before the first task
+
+1. **Scope.** Which tasks: an area, a list of ids, or everything that becomes ready. Take it from the user's message. Default order is the order of `node docs/.sw/sw.mjs ready`.
+2. **Standing answers.** The user will not be asked again, so these are settled now. Ask only for the ones their message leaves open, in one question:
+
+   | Question | If the user does not say |
+   | --- | --- |
+   | May plans be approved without them? | yes; that is what unattended means |
+   | Which `needs:` checks (starting services, changing data) may run? | none |
+   | Commit after each task? Push? | no commit, no push |
+   | Go on with other tasks when one stops? | no; stop the run |
+
+3. **Check that the run can do what was agreed**, before any task is touched:
+   - `node docs/.sw/sw.mjs lint`: errors are fixed or reported first.
+   - Commits were agreed: run one harmless git command. If the project's settings or the tool refuse git, say so now. Do not start a run whose terms cannot be met, and do not look for another way to run the refused command.
+   - The working tree holds changes that belong to no task of this run: say what they are and ask once whether to leave them or commit them first.
+4. **A clean session per task.** You cannot open a new session; a fresh subagent per role is the clean context. If the user asked for sessions, say this is how it is done.
+
+## Each task
+
+1. **Next task**: `node docs/.sw/sw.mjs ready`. A task in progress comes first, then the first ready task in scope. None left: go to "The report".
+2. **Run it as sw-implement does**: gate, mark it started, checks that need the environment, implementer, judge the report, review if required, record, task list. Load sw-implement once and follow it for every task. What differs in a run:
+
+   | In sw-implement or sw-plan | In a run |
+   | --- | --- |
+   | a task that is not small: "recommend sw-plan and let the user choose" | plan it. Mark the task started first, then dispatch the planner as sw-plan step 4 says |
+   | the planner's `Questions` go to the user | answer each with the planner's assumed answer, unless the task file, a wiki page or a recorded lesson says otherwise (`node docs/.sw/sw.mjs search <words>`). Write every answer into the task's "Notes" as `decided without the user: ...` |
+   | the plan waits for approval | approve it, if that was agreed, with a log entry that says it was approved under the run's standing answer |
+   | a `differs` item is the user's call | send it back to the implementer once with the task's wording. Still differs: stop |
+   | offers after a task (wiki pages, lessons, follow-up tasks) | do not ask and do not act. List them in the report |
+
+3. **Close the task.** Commit, if agreed: only the files this task changed, message `<ID>: <title>`. Push only if agreed. A refused commit or push stops the run.
+4. **Check your own size**: `node docs/.sw/sw.mjs stats`, row `main`. If its `peak` is above 200k tokens, stop here, between tasks: every further step would pay for all of it. Tell the user to start a new session and run sw-run again; the queue is in the files, so nothing is lost.
+
+## When to stop
+
+Stop the run, leave the task `in-progress` with what is open in its "Notes", and report. Do not skip the task and take the next one unless that was agreed and the next task does not depend on it.
+
+- A requirement is `not met` or still `differs` after one more round with the implementer.
+- The review still says `changes needed` after two rounds.
+- The task cannot be verified without a `needs:` check that was not allowed.
+- A commit or push that was agreed is refused.
+- `lint` reports an error after the task was recorded.
+- Your `peak` is above 200k (this one is between tasks, with nothing left open).
+
+## Keeping the run cheap
+
+A run pays for the orchestrator's context once per step, for every task. What keeps it small:
+
+- **A fresh subagent for every task and every role.** Never continue the agent that planned or implemented the previous task.
+- **Prompts as the role files ask**: task id, date, project root, the checks it may run, the standing answers that concern it. No reading lists and no project summary; each role knows what to read.
+- **Reports, not files.** Do not read code, plans or the other tasks' files. `ready`, `check` and `explain` answer what you need about the queue.
+- **One load of each skill.** Do not load a skill again to re-read it.
+- **Edit frontmatter with your edit tool**, not with `sed` or another text substitution: a pattern that does not match fails silently and the status is then wrong without an error.
+
+## The report
+
+At the end, or when the run stops:
+
+1. A table: task, outcome, review verdict, commit.
+2. **Decisions made without the user**, one line each with the task id. This is the list the user must read.
+3. What stopped the run, if it stopped, and what would let it continue.
+4. Offers and open findings collected along the way.
+5. `node docs/.sw/sw.mjs stats`, as printed.
+6. What is ready next.
+
+## Common mistakes
+
+- Asking the user mid-run something the standing answers cover, or not asking at the start something they do not.
+- Deciding a `needs:` check may run because the run is unattended. Unattended means fewer questions, not more permission.
+- Piling several tasks into one uncommitted tree after a commit was refused.
+- Running one long subagent that plans, implements and reviews a task. Measured on a real project, such an agent reached a context of almost a million tokens and sent over ten times what the three separate roles sent on another task of the same project.
+- Carrying on past 200k because the next task looks small.