superwiki 0.1.0

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

@@ -0,0 +1,104 @@
+#!/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';
+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 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.' },
+};
+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
+  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`);
+    }
+  }
+}
+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('  ')}`);
+  }
+  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;
+  }
+  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}`);

package/skills/sw-explain/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: sw-explain
+description: Use when the user asks what a Superwiki task is, why it exists, what it depends on, what it blocks or what changes once it is done, or invokes sw-explain or sw:explain with a task id.
+---
+
+# sw-explain
+
+Explains one task so that someone who has not followed the project understands it. Changes no file.
+
+Run commands from the project root.
+
+## Steps
+
+1. `node docs/.sw/sw.mjs explain <ID>`. It prints the task's state, what it depends on, what it blocks, what becomes ready when it is done, its plan and the wiki pages it links, each with a one-line summary. No id given: ask which task, offering the ones from `node docs/.sw/sw.mjs ready`.
+
+   The state is derived: `ready` is a `todo` task whose dependencies are done, `blocked` is a `todo` task still waiting on one, `progress` is `in-progress`. Say it in words, not as a label.
+2. Read `docs/tasks/<ID>.md`.
+3. Read more only when the answer needs it:
+   - the plan's `## Approach` section, if the user will want to know how it is to be done;
+   - one linked page, if the task's "Goal" does not itself say why the task exists: a `decision` page if there is one, otherwise the page whose summary is closest to the goal;
+   - nothing else. Summaries from step 1 stand in for the other pages.
+4. **Answer in the user's language**, in this order, one to a few sentences each:
+   - **What**: the task in plain words, without restating its title.
+   - **Why**: the reason it exists and the decision or source behind it, as `[[page]]`. If neither the task nor the page you read gives a reason, say the brain does not record one.
+   - **Depends on**: each dependency with its state. A dependency listed under "depends on" must be done before the task can start; one under "soft depends on" lets it start but must be done before it can finish.
+   - **Blocks**: the tasks waiting on it, and which of them become ready the moment it is done.
+   - **What changes when it is done**: for the product or the user, from "Done when", and for the project, from what it unblocks.
+   - **Where it stands**: state, dates, whether a plan exists, and the next step. Ready or in progress: `sw-implement <ID>` (or `sw-plan <ID>` first if there is no plan and the task is not small). Blocked: name the tasks to finish first; planning it meanwhile with `sw-plan <ID>` is allowed.
+
+Leave out a heading that has nothing to say rather than writing "none" under each. If the task file is thin (no "Goal", no "Done when"), say that this is all the brain records; do not fill the gap with guesses from the code.

package/skills/sw-implement/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: sw-implement
+description: Use when the user wants to implement, build, execute, start or continue a Superwiki task or its plan, or invokes sw-implement or sw:implement, with or without a task id.
+---
+
+# sw-implement
+
+Runs one task. You keep the task's status true and judge the result; an implementer subagent, running the model set in sw-config, does the work from the task and plan files.
+
+Run commands from the project root. `<skill-dir>` is the directory this SKILL.md is in.
+
+## Steps
+
+1. **Pick the task.** Id given: use it. Otherwise `node docs/.sw/sw.mjs ready` and let the user choose; tasks already in progress come first.
+2. **Gate**: `node docs/.sw/sw.mjs check <ID>`.
+   - `can start: no  open deps: ...`: stop. Tell the user which tasks block it and offer to run the first blocker instead; do not run it unasked. Do not start the task anyway, and do not edit `deps` to get past this.
+   - `can start: n/a, status is in-progress`: this is a continuation; skip step 3.
+   - `can start: n/a, status is done` or `cancelled`: stop and ask what the user wants.
+   - `plan: none`: say so. Small tasks can run from "Goal" and "Done when"; for anything larger, recommend sw-plan first and let the user choose.
+3. **Mark it started** before any work: in the frontmatter of `docs/tasks/<ID>.md` set `status: in-progress` and `started:` today. Append `## [date] task | <ID> started` to `docs/log.md`, in the layout its last entries use.
+4. **Dispatch the implementer.** Its prompt is the task id, plus the project root if it is not your working directory. Do not paste the plan into the prompt; it reads the files.
+
+   | Tool | How |
+   |---|---|
+   | Claude Code | agent `sw-implementer`. If it is not among your agent types, use a general-purpose agent, put the content of `<skill-dir>/../sw-config/assets/implementer.md` at the top of its prompt, and pass the model from `models.implement.claude` in `docs/.sw/config.json` if set |
+   | Codex | spawn the custom agent `sw_implementer` |
+   | Copilot CLI | `task` tool with agent `sw-implementer` |
+   | No subagents available, or the agent is not defined | follow `implementer.md` yourself, in this session, and tell the user the configured model was not used |
+
+5. **Judge the report** against the task's "Done when" list. Every item needs evidence: a command and its result. Re-run a verification command yourself when the report is vague. An item without evidence is not met.
+6. **Record the outcome.**
+
+   | Outcome | Task file | Log entry |
+   |---|---|---|
+   | Every item met, and `check <ID>` says `can finish: yes` | `status: done`, `finished:` today | `task \| <ID> done`, then one body line on what was verified |
+   | Items met but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
+   | Blocked or partly done | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |
+
+7. **File what was learned.** If the implementer reported a decision or constraint the wiki should hold, offer to save it as a wiki page (`type: decision` or `concept`) and add it to `index.md`. If the task fixed a problem whose cause is now known, offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later. If it reported follow-up work, offer to create the tasks. These are separate offers: act on each only when the user says yes to that one.
+8. **Report** to the user: outcome, evidence per "Done when" item, files changed, deviations from the plan, and which tasks this unblocked (`node docs/.sw/sw.mjs ready`). Commit only if the user asks.
+
+## Common mistakes
+
+- Marking `done` because the implementer said so. Done means every "Done when" item has evidence.
+- Starting work before the task file says `in-progress`. If the session dies, nobody knows the task was touched.
+- Letting the implementer edit the task file or the log. One writer for status: you.

package/skills/sw-ingest/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: sw-ingest
+description: Use when the user adds or points to a source (article, paper, transcript, notes, meeting record, PDF, URL, data file) to be filed, processed or ingested into Superwiki, or invokes sw-ingest or sw:ingest.
+---
+
+# sw-ingest
+
+Turns one source into wiki knowledge. A source touches few files by default: its summary page, `index.md` and `log.md`. Wider cross-updates are recorded as follow-ups and done in sw-lint, so an ingest stays cheap.
+
+## Steps
+
+1. **Put the source in `docs/raw/`** as `<yyyy-mm-dd>-<slug>.<ext>` (date of the source if known, else today):
+   - a file outside `docs/`: copy it in under that name and leave the original where it is;
+   - a file already in `docs/raw/`: use it as it is;
+   - a URL or pasted text: save it as markdown, with the URL on the first line.
+
+   After this, never edit anything in `raw/`.
+2. **Read the source.** Read `docs/index.md` (not the wiki pages) to see what already exists.
+3. **Tell the user the three to five points worth keeping** and which existing pages they bear on, judged from the index lines. Wait for their steer unless they asked for a batch or unattended ingest.
+4. **Write the summary page** `docs/wiki/<slug>.md` from `docs/.sw/templates/page.md`. The slug is lowercase words joined by hyphens, says what the source is, and is not used by any other file in the vault.
+   - Frontmatter: `type: source`, a one-line `summary:`, `sources: [<raw file name>]`, `updated:` today.
+   - Body: the points, each traceable to the source; a normal markdown link to the raw file; `[[links]]` to the existing pages it relates to.
+5. **Check at most three existing pages** whose index line says they make a claim on the same subject. Open each, and edit it only if the source contradicts, corrects or dates what it says; add a `[[link]]` to the summary page where you edit. Everything else you noticed goes to the follow-up line in step 7. If the source introduces a concept or entity that several of its points depend on and no page covers, create that page; one or two per source at most.
+6. **Add the page to `index.md`**: `- [[slug]]: summary`, under its type.
+7. **Append to `docs/log.md`**, in the layout the log's last entries use (`tail -5 docs/log.md`):
+
+   ```
+   ## [YYYY-MM-DD] ingest | <source title>
+   Added [[slug]]. Updated [[page-a]]. Follow-up: [[page-b]] may need the new figures; no page yet for "<concept>".
+   ```
+
+   The `Follow-up` part is where everything you noticed but did not do goes. sw-lint reads it.
+8. **Run** `node docs/.sw/sw.mjs lint` and fix errors in the pages you wrote or edited.
+
+## Several sources at once
+
+Do steps 1 to 8 per source, in order. Skip step 3's wait after the first source if the user said to continue. Do not read all sources before writing: each one is read, filed and left.
+
+## Common mistakes
+
+- Reading wiki pages "for context" before writing. The index line is the context; step 5 is the only reading of existing pages.
+- Rewriting many pages because the source mentions them. Mention is not change; log a follow-up.
+- Copying the source into the wiki. The summary page holds what matters and links to the rest.

package/skills/sw-init/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sw-init
+description: Use when the user asks to set up, initialize, scaffold or upgrade a second brain, LLM wiki or Superwiki vault in a project's docs folder, or invokes sw-init or sw:init.
+---
+
+# sw-init
+
+Turns `docs/` into a Superwiki vault: an LLM-maintained wiki that is also an Obsidian vault, with an optional task module. A script does the scaffolding; do not create the files by hand.
+
+The vault is always `<project root>/docs`. Run every command below from the project root. `<skill-dir>` is the directory this SKILL.md is in.
+
+## Steps
+
+1. **Check Node**: `node --version` must be 18 or newer. If not, go to "Without Node".
+2. **Upgrade or new?** If `docs/.sw/config.json` exists this is an upgrade: skip step 3 and run the script with no flags; it reuses the saved choices.
+3. **Ask the user, in one message** (new vault only):
+   - Task module on or off. Recommend on when the project is mainly code, off for a pure knowledge base.
+   - If on, the area prefixes for task ids (`M-01`, `B-01`). Recommend the single default area `T` unless the project already has separately named parts. Area names are optional labels; do not ask for them separately.
+4. **Run the script**, with the flags that match the answer:
+
+   ```bash
+   node <skill-dir>/scripts/init.mjs --tasks                               # tasks on, default area T
+   node <skill-dir>/scripts/init.mjs --tasks --areas "M=Mobile,B=Backend"  # tasks on, named areas
+   node <skill-dir>/scripts/init.mjs --no-tasks                            # wiki only
+   node <skill-dir>/scripts/init.mjs                                       # upgrade
+   ```
+
+5. **Check**: run `node docs/.sw/sw.mjs lint`. A new vault reports `0 errors, 0 warnings`. On an upgrade, findings are about the user's existing pages: show them, do not fix them unasked.
+6. **Report** to the user from the script's output. Each line starts with a status:
+
+   | Status | Say |
+   |---|---|
+   | `created`, `updated` | what is new or changed |
+   | `kept`, `unchanged` | that user content and settings were not touched (one sentence, no list) |
+   | `missing` | that this Superwiki build lacks the file; name it, and do not point the user at it |
+   | `note` about `CLAUDE.md` | offer to add the `@AGENTS.md` line. Add it only after the user agrees to that specific change |
+   | "docs/ already had content" | that content is untouched and outside the vault; sw-migrate converts it |
+
+   End with how to look at the result: open `docs/` as an Obsidian vault, or open `docs/viewer.html` in Chrome or Edge and pick the project folder (only if the viewer was not reported `missing`).
+
+## What the script guarantees
+
+| File | On re-run |
+|---|---|
+| `docs/index.md`, `docs/log.md`, everything in `raw/`, `wiki/`, `tasks/`, `plans/` | kept |
+| `docs/.sw/sw.mjs`, `docs/.sw/templates/`, `docs/viewer.html` | replaced with this version |
+| `AGENTS.md` | only the Superwiki block (from the `sw:start` comment to the `sw:end` comment) is replaced |
+| `docs/.sw/config.json` | areas and models kept unless new flags are passed |
+
+## Without Node
+
+The script and `docs/.sw/sw.mjs` need Node 18 or newer. If `node` is missing or older, say so and stop; continue by hand only if the user asks for that. By hand: create `docs/{raw/assets,wiki}` (plus `tasks`, `plans`), copy `assets/templates/` to `docs/.sw/templates/` and `assets/viewer.html` to `docs/`, write `index.md` and `log.md` as the script would, and paste `assets/agents-block.md` into `AGENTS.md` with the `{{...}}` lines resolved. Tell the user the `sw.mjs` commands in that block will not work until Node is installed.

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

@@ -0,0 +1,29 @@
+<!-- sw:start (managed by sw-init; write your own rules outside these markers) -->
+## Superwiki (`docs/`)
+
+`docs/` is a wiki you write and keep current, and an Obsidian vault the user reads.
+
+- `docs/index.md`: catalog, one line per wiki page. Read it first, then open only the pages you need.
+- `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:`.
+{{#tasks}}
+- `docs/tasks/<ID>.md`: one task per file. `docs/plans/<ID>-plan.md`: its plan, if any.
+{{/tasks}}
+- Anything else under `docs/` belongs to other tools. Leave it alone.
+
+Rules:
+
+- Link vault pages as `[[file-name]]`; file names are unique across the vault. Use normal markdown links for `raw/` files and URLs, and plain paths for code.
+- When you add or rename a wiki page, update its line in `index.md`.
+- Answer questions from the wiki, index first. Offer to save an answer worth keeping as a wiki page.
+{{#tasks}}
+- A task's status lives only in its frontmatter. Before you start: `status: in-progress` and `started:`. When its "Done when" list is met: `status: done` and `finished:`. Each change gets a `task` entry in `log.md`.
+- Do not start a task while any of its `deps` is not done.
+- `node docs/.sw/sw.mjs status|ready|check <ID>|explain <ID>|search <words>|next-id <AREA>|lint` answers overview, startable tasks, blockers, a task's place in the chain, where something is mentioned, new ids and structural checks without reading files. Run `lint` after you add, rename or relink pages.
+{{/tasks}}
+{{^tasks}}
+- `node docs/.sw/sw.mjs search <words>` finds where something is mentioned; `lint` checks links and frontmatter. Neither needs you to read files. Run `lint` after you add, rename or relink pages.
+{{/tasks}}
+- File formats: `docs/.sw/templates/`.
+<!-- sw:end -->