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

package/.codex-plugin/plugin.json

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

@@ -195,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 |
@@ -218,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
@@ -226,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

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.6",
+  "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-init/assets/agents-block.md

@@ -44,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-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.