superwiki 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "superwiki",
+  "owner": {
+    "name": "Mehmet Serefoglu"
+  },
+  "plugins": [
+    {
+      "name": "sw",
+      "source": "./",
+      "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer."
+    }
+  ],
+  "metadata": {
+    "description": "Superwiki: agent skills for an LLM-maintained wiki and task tracker"
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "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",
+  "license": "MIT",
+  "keywords": [
+    "wiki",
+    "second-brain",
+    "obsidian",
+    "tasks",
+    "planning",
+    "skills"
+  ],
+  "author": {
+    "name": "Mehmet Serefoglu"
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "sw",
+  "version": "0.1.0",
+  "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
+  "license": "MIT",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Superwiki",
+    "shortDescription": "LLM-maintained wiki and task tracker in docs/",
+    "category": "Developer Tools"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Serefoglu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# Superwiki
+
+Agent skills that turn a project's `docs/` folder into an **LLM-maintained wiki and task tracker**. Your coding agent writes it and keeps it current; you read it as an **Obsidian vault** or in a built-in viewer. Works with **Claude Code, Codex CLI and GitHub Copilot CLI**.
+
+**[Live demo](https://mhmtsrfglu.github.io/superwiki/)** · [Install](#install) · [Commands](#use) · [Design notes](DESIGN.md)
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/viewer-waves-dark.png">
+  <img alt="The Superwiki viewer: task counts per area, filters, and the dependency board with one task's chain highlighted" src="assets/viewer-waves-light.png">
+</picture>
+
+```bash
+npx superwiki install claude        # or: codex, copilot, global, all
+```
+
+Then, in a project: `/sw-init`.
+
+## Why
+
+Superwiki follows the LLM Wiki pattern described by Andrej Karpathy: raw sources you curate, a wiki the agent owns, and a short schema that tells the agent how to maintain it. On top of that it adds what a software project needs: tasks with dependencies, plans, and a record of decisions and lessons.
+
+It is built to be cheap for the agent. One small index to read, one file per task, and a script that answers "what is ready?", "what blocks this?" or "is anything broken?" without the agent reading the vault.
+
+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 |
+
+> Status: early. The CLI, the viewer, `sw-init` and the migration script are tested, and the planning flow has been run in all three agents; some skills have only been exercised once. [DESIGN.md](DESIGN.md) lists what has and has not been proven.
+
+## What you get
+
+```
+docs/
+  index.md       catalog of the wiki, one line per page
+  log.md         append-only history
+  raw/           your sources, never modified
+  wiki/          pages the agent writes
+  tasks/         one file per task (optional)
+  plans/         one plan per task
+  viewer.html    opened by sw-visualize, in any browser
+```
+
+`AGENTS.md` gets a short block of rules so the agent maintains the vault in every session, with or without a command.
+
+## Install
+
+Requires Node 18 or newer.
+
+```bash
+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) |
+| `global` | `~/.agents/skills` | the shared folder: Codex, Copilot CLI and [other agents](#other-agents) that read it. Claude Code does not |
+| `all` | all of the above | |
+
+```bash
+npx superwiki install claude codex                   # several agents at once
+npx superwiki install --project ~/code/my-app all    # one project only, not your home folder
+npx superwiki uninstall claude                       # remove
+npx superwiki --help
+```
+
+Start a new agent session after installing: a running session does not pick up new skills.
+
+### From a clone
+
+If you would rather read the code first, or want to change it:
+
+```bash
+git clone https://github.com/mhmtsrfglu/superwiki ~/.superwiki
+~/.superwiki/install.sh claude            # same targets and options; links instead of copying
+```
+
+A linked install follows the clone: `git pull` updates every agent. `install.sh --copy` copies instead, `--uninstall` removes.
+
+All three agents below were checked the same way: the agent found the skills, refused to start a task with an unfinished dependency, and ran `sw-plan` end to end with the planner subagent.
+
+### Claude Code
+
+```bash
+npx superwiki install claude
+```
+
+Invoke with a slash: `/sw-init`, `/sw-plan T-01`.
+
+Claude Code reads `~/.claude/skills/` (and a project's `.claude/skills/`); it does not read `~/.agents/skills/`, so `global` is not enough for it.
+
+`sw-plan` enters plan mode when the session offers it. A model set with `sw-config` for `claude` applies to the planner and implementer subagents, written to `.claude/agents/`; if those agents are not loaded, the skills fall back to built-in agents with the same model.
+
+### Codex CLI
+
+```bash
+npx superwiki install codex
+```
+
+Invoke with a dollar sign, or by name in a sentence: `$sw-init`, `$sw-plan T-01`, "use the sw-plan skill for T-01". Checked with CLI 0.153.
+
+A skill cannot switch Codex into plan mode; start planning yourself with `/plan` if you want the mode, or let `sw-plan` proceed without it (it changes no file before you approve). A model set with `sw-config` for `codex` is written to `.codex/agents/sw-planner.toml` and `sw-implementer.toml`, and the skills spawn those agents by name. Subagents must be enabled (they are by default in current releases).
+
+### GitHub Copilot CLI
+
+```bash
+npx superwiki install copilot
+```
+
+Invoke with a slash, or by name in a sentence: `/sw-init`, "use the sw-plan skill for T-01". Checked with CLI 1.0.31.
+
+Copilot CLI also reads `~/.agents/skills/`, so if you installed `codex` or `global` it already has the skills.
+
+A skill cannot switch Copilot into plan mode; start with `copilot --mode plan` or `/plan` if you want it. A model set with `sw-config` for `copilot` is written to `.github/agents/sw-planner.agent.md` and `sw-implementer.agent.md`; the skills dispatch them with the `task` tool. Whether Copilot honours the `model:` field of those files has not been checked.
+
+### Other agents
+
+```bash
+npx superwiki install global
+```
+
+Agents that load `SKILL.md` folders from `~/.agents/skills` pick the skills up from there. For an agent with its own skills folder (Cursor, Gemini CLI, OpenCode and others), copy the `skills/sw-*` folders from a clone into it by hand. Nothing has been run in these agents. What will differ:
+
+- the skills name Claude Code, Codex and Copilot tools when they dispatch subagents; elsewhere they fall back to doing the planning or implementing in the main session, and say so;
+- `sw-config` writes agent files only for `claude`, `codex` and `copilot`, so a per-role model cannot be set.
+
+Everything else (the vault, the CLI, the viewer, ingest, lint, explain, triage) depends only on Node and on the agent following the skill text.
+
+### With other skill sets
+
+Superwiki works next to planning skill sets such as Superpowers. Two things to know:
+
+- Their bootstrap may claim a bare `/sw-...` prompt before Superwiki's skill loads. Naming the skill in a sentence ("use the sw-implement skill for T-02") avoids that.
+- Folders they create under `docs/` are left alone: Superwiki only reads and writes `index.md`, `log.md`, `raw/`, `wiki/`, `tasks/` and `plans/`.
+
+### Update and uninstall
+
+```bash
+npx superwiki@latest install claude      # update: same command, newest release
+npx superwiki uninstall all
+```
+
+After an update, run `sw-init` again in each project: it replaces `docs/.sw/sw.mjs`, the templates and `docs/viewer.html` with the new version and keeps your content.
+
+A project's `docs/` folder is plain markdown and keeps working as an Obsidian vault without Superwiki.
+
+## Use
+
+```
+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
+```
+
+A filled-in example vault is in [examples/demo/docs](examples/demo/docs).
+
+After that, 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
+```
+
+## Develop
+
+```bash
+npm test       # builds skills/sw-init/assets/sw.mjs, then runs the tests
+```
+
+`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.
+
+## License
+
+MIT

package/bin/superwiki.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Installs the Superwiki skills into the folder each coding agent reads.
+// Run from npm (`npx superwiki install claude`) it copies them; `--link` links them to this
+// checkout instead, which is what install.sh does for a git clone.
+import { existsSync, lstatSync, readlinkSync, realpathSync, mkdirSync, readdirSync, rmSync, cpSync, symlinkSync, writeFileSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const skillsDir = join(root, 'skills');
+const TARGETS = ['claude', 'codex', 'copilot', 'global'];
+const MARKER = '.sw-installed';
+
+const HELP = `Usage: superwiki install [options] <target>...
+       superwiki uninstall [options] <target>...
+
+Targets:
+  claude     ~/.claude/skills    Claude Code
+  codex      ~/.agents/skills    Codex CLI
+  copilot    ~/.copilot/skills   GitHub Copilot CLI
+  global     ~/.agents/skills    the shared folder: Codex, Copilot CLI and other agents that read it
+                                 (Claude Code does not)
+  all        claude + codex + copilot
+
+Options:
+  --project <dir>  install into that project instead of your home folder
+                   (.claude/skills for claude, .agents/skills for the others)
+  --link           link the skills to this copy of Superwiki instead of copying them
+                   (for a git clone: updating the clone then updates every agent)
+  --force          replace or remove a skill folder that Superwiki did not install
+  -v, --version    print the version
+  -h, --help       show this help
+
+Examples:
+  npx superwiki install claude
+  npx superwiki install claude codex
+  npx superwiki install --project ~/code/my-app all
+  npx superwiki uninstall copilot
+
+Run the same command again after a new release to update. Then start a new agent session
+and run sw-init in a project.`;
+
+const argv = process.argv.slice(2);
+const fail = (msg, code = 2) => { console.error(msg); process.exit(code); };
+if (argv.includes('-h') || argv.includes('--help') || !argv.length) { console.log(HELP); process.exit(argv.length ? 0 : 2); }
+if (argv.includes('-v') || argv.includes('--version')) { console.log(JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version); process.exit(0); }
+
+const command = argv[0];
+if (command !== 'install' && command !== 'uninstall') fail(`unknown command: ${command}\n\n${HELP}`);
+let project = '';
+let link = false;
+let force = false;
+const targets = [];
+for (let i = 1; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--project') { project = argv[++i] || fail('--project needs a folder'); }
+  else if (a === '--link') link = true;
+  else if (a === '--force') force = true;
+  else if (a === 'all') targets.push('claude', 'codex', 'copilot');
+  else if (TARGETS.includes(a)) targets.push(a);
+  else fail(`unknown argument: ${a}\n\n${HELP}`);
+}
+if (!targets.length) fail(`name at least one target: ${TARGETS.join(', ')}, all`);
+if (!existsSync(skillsDir)) fail(`no skills/ folder in ${root}`, 1);
+if (project) {
+  if (!existsSync(project) || !statSync(project).isDirectory()) fail(`no such project folder: ${project}`, 1);
+  project = realpathSync(project);
+}
+
+const destFor = t => (project
+  ? join(project, t === 'claude' ? '.claude/skills' : '.agents/skills')
+  : join(homedir(), t === 'claude' ? '.claude/skills' : t === 'copilot' ? '.copilot/skills' : '.agents/skills'));
+
+const exists = p => { try { lstatSync(p); return true; } catch { return false; } };
+// Ours: a link that ends up in this copy's skills folder, or a copy carrying the marker file.
+function isOurs(p, name) {
+  if (lstatSync(p).isSymbolicLink()) {
+    if (readlinkSync(p).startsWith(skillsDir + '/')) return true;
+    try { return realpathSync(p) === realpathSync(join(skillsDir, name)); } catch { return false; }
+  }
+  return existsSync(join(p, MARKER));
+}
+
+const skills = readdirSync(skillsDir).filter(n => n.startsWith('sw-') && statSync(join(skillsDir, n)).isDirectory()).sort();
+const seen = new Set();
+let status = 0;
+for (const target of targets) {
+  const dest = destFor(target);
+  if (seen.has(dest)) continue;   // codex and global share a folder
+  seen.add(dest);
+  console.log(`${target}: ${dest}`);
+  if (command === 'install') mkdirSync(dest, { recursive: true });
+  for (const name of skills) {
+    const path = join(dest, name);
+    if (exists(path)) {
+      if (!isOurs(path, name) && !force) {
+        if (command === 'install') { console.log(`  skipped  ${name} (a different ${name} is already there; --force replaces it)`); status = 1; }
+        else console.log(`  kept     ${name} (not installed by Superwiki; --force removes it)`);
+        continue;
+      }
+      rmSync(path, { recursive: true, force: true });
+      if (command === 'uninstall') console.log(`  removed  ${name}`);
+    }
+    if (command === 'uninstall') continue;
+    if (link) { symlinkSync(join(skillsDir, name), path); console.log(`  linked   ${name}`); }
+    else { cpSync(join(skillsDir, name), path, { recursive: true }); writeFileSync(join(path, MARKER), ''); console.log(`  copied   ${name}`); }
+  }
+}
+
+if (command === 'install') {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < 18) console.error(`warning: Node ${major} found; the Superwiki scripts need Node 18 or newer`);
+  console.log('\nStart a new agent session, then run sw-init in a project.');
+}
+process.exit(status);

package/commands/config.md

@@ -0,0 +1,5 @@
+---
+description: Set models for planning and implementing, and task areas
+---
+
+Use the sw-config skill. User arguments: $ARGUMENTS

package/commands/explain.md

@@ -0,0 +1,5 @@
+---
+description: Explain a task: what, why, dependencies, what it unblocks, what changes when done
+---
+
+Use the sw-explain skill. User arguments: $ARGUMENTS

package/commands/implement.md

@@ -0,0 +1,5 @@
+---
+description: Implement one task with the implementer subagent and record the result
+---
+
+Use the sw-implement skill. User arguments: $ARGUMENTS

package/commands/ingest.md

@@ -0,0 +1,5 @@
+---
+description: File a source into Superwiki
+---
+
+Use the sw-ingest skill. User arguments: $ARGUMENTS

package/commands/init.md

@@ -0,0 +1,5 @@
+---
+description: Set up docs/ as a Superwiki vault (wiki, optional tasks, viewer)
+---
+
+Use the sw-init skill. User arguments: $ARGUMENTS

package/commands/lint.md

@@ -0,0 +1,5 @@
+---
+description: Check the Superwiki vault: structure by script, meaning on request
+---
+
+Use the sw-lint skill. User arguments: $ARGUMENTS

package/commands/migrate.md

@@ -0,0 +1,5 @@
+---
+description: Convert an existing table-based docs/task structure into a Superwiki vault, on a new git branch
+---
+
+Use the sw-migrate skill. User arguments: $ARGUMENTS

package/commands/plan.md

@@ -0,0 +1,5 @@
+---
+description: Plan one task with the planner subagent, then save the approved plan
+---
+
+Use the sw-plan skill. User arguments: $ARGUMENTS

package/commands/triage.md

@@ -0,0 +1,5 @@
+---
+description: Search the brain for earlier occurrences, lessons and likely causes of a problem
+---
+
+Use the sw-triage skill. User arguments: $ARGUMENTS

package/commands/visualize.md

@@ -0,0 +1,5 @@
+---
+description: Open the Superwiki viewer in the browser
+---
+
+Use the sw-visualize skill. User arguments: $ARGUMENTS

package/install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Installs the Superwiki skills from this checkout by linking them into the folder each agent reads.
+# A thin wrapper around bin/superwiki.mjs, for people who cloned the repository.
+#
+#   ./install.sh claude                 link the skills for Claude Code
+#   ./install.sh --copy all             copy instead of link
+#   ./install.sh --uninstall codex      remove them
+#   ./install.sh --help
+set -euo pipefail
+
+SUPERWIKI_HOME="${SUPERWIKI_HOME:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
+command -v node >/dev/null 2>&1 || { echo "node not found; Superwiki needs Node 18 or newer" >&2; exit 1; }
+[ -f "$SUPERWIKI_HOME/bin/superwiki.mjs" ] || { echo "no bin/superwiki.mjs in $SUPERWIKI_HOME; set SUPERWIKI_HOME to the Superwiki repository" >&2; exit 1; }
+
+command="install"
+link="--link"
+args=()
+for a in "$@"; do
+  case "$a" in
+    --uninstall) command="uninstall"; link="" ;;
+    --copy) link="" ;;
+    *) args+=("$a") ;;
+  esac
+done
+
+# ${args[@]+...} keeps bash 3.2 (macOS) from failing on an empty array under `set -u`.
+exec node "$SUPERWIKI_HOME/bin/superwiki.mjs" "$command" ${link:+"$link"} ${args[@]+"${args[@]}"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "superwiki",
+  "version": "0.1.0",
+  "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",
+    "agent-skills",
+    "codex",
+    "github-copilot",
+    "obsidian",
+    "llm-wiki",
+    "knowledge-base",
+    "ai-agents",
+    "task-management",
+    "wiki"
+  ],
+  "homepage": "https://github.com/mhmtsrfglu/superwiki#readme",
+  "bugs": "https://github.com/mhmtsrfglu/superwiki/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mhmtsrfglu/superwiki.git"
+  },
+  "license": "MIT",
+  "author": "Mehmet Şerefoğlu",
+  "type": "module",
+  "bin": {
+    "superwiki": "bin/superwiki.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "commands",
+    ".claude-plugin",
+    ".codex-plugin",
+    "install.sh"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node scripts/build.mjs && node --test",
+    "prepublishOnly": "npm test"
+  }
+}

package/skills/sw-config/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: sw-config
+description: Use when the user wants to choose or change which model plans or implements Superwiki tasks (opus, sonnet, gpt and so on), add task areas, see the Superwiki configuration, or invokes sw-config or sw:config.
+---
+
+# sw-config
+
+Settings live in `docs/.sw/config.json`. Change them with the script, from the project root; it also writes the agent files that make a model choice take effect. `<skill-dir>` is this skill's directory.
+
+```bash
+node <skill-dir>/scripts/config.mjs show
+node <skill-dir>/scripts/config.mjs model plan claude opus
+node <skill-dir>/scripts/config.mjs model implement codex gpt-6
+node <skill-dir>/scripts/config.mjs model plan copilot --unset
+node <skill-dir>/scripts/config.mjs areas "M=Mobile,B=Backend"
+node <skill-dir>/scripts/config.mjs sync --tools claude,codex,copilot
+```
+
+## Models
+
+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 |
+
+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.
+
+Do not edit the generated agent files or `config.json` by hand; the next `sync` overwrites agent files.
+
+## Areas
+
+`areas` adds prefixes or renames them. It never removes one: tasks keep their ids forever.

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

@@ -0,0 +1,15 @@
+You implement one task in a Superwiki vault.
+
+Input: a task id.
+
+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.
+
+Report:
+- 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.

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

@@ -0,0 +1,17 @@
+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.