superwiki 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/README.md +4 -4
- package/package.json +1 -1
- package/skills/sw-config/assets/implementer.md +34 -10
- package/skills/sw-config/assets/planner.md +48 -28
- package/skills/sw-implement/SKILL.md +17 -12
- package/skills/sw-init/assets/agents-block.md +1 -1
- package/skills/sw-init/assets/templates/guide.md +5 -4
- package/skills/sw-plan/SKILL.md +5 -5
package/README.md
CHANGED
|
@@ -24,7 +24,7 @@ It is built to be cheap for the agent. One small index to read, one file per tas
|
|
|
24
24
|
Measured on a real project with 165 tasks, converted from a single markdown index:
|
|
25
25
|
|
|
26
26
|
| | Before | After |
|
|
27
|
-
|
|
27
|
+
| --- | --- | --- |
|
|
28
28
|
| Read at the start of every session | 197 KB index | 94-byte catalog + 1.7 KB of rules |
|
|
29
29
|
| Read to start one task | the index, then the task's section | one file, 2 KB at the median |
|
|
30
30
|
| Marking a task done | a status cell, plus a ✅ at every reference to it (median 12 places) | one frontmatter line |
|
|
@@ -33,7 +33,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
|
|
|
33
33
|
|
|
34
34
|
## What you get
|
|
35
35
|
|
|
36
|
-
```
|
|
36
|
+
```text
|
|
37
37
|
docs/
|
|
38
38
|
index.md catalog of the wiki, one line per page
|
|
39
39
|
log.md append-only history
|
|
@@ -57,7 +57,7 @@ npx superwiki install claude
|
|
|
57
57
|
This copies the skills into the folder your agent reads. Name one or more targets:
|
|
58
58
|
|
|
59
59
|
| Target | Installs into | For |
|
|
60
|
-
|
|
60
|
+
| --- | --- | --- |
|
|
61
61
|
| `claude` | `~/.claude/skills` | [Claude Code](#claude-code) |
|
|
62
62
|
| `codex` | `~/.agents/skills` | [Codex CLI](#codex-cli) |
|
|
63
63
|
| `copilot` | `~/.copilot/skills` | [GitHub Copilot CLI](#github-copilot-cli) |
|
|
@@ -226,7 +226,7 @@ node docs/.sw/sw.mjs snapshot # or: freeze the vault into docs/vie
|
|
|
226
226
|
npm test # builds skills/sw-init/assets/sw.mjs, then runs the tests
|
|
227
227
|
```
|
|
228
228
|
|
|
229
|
-
Releases are cut by the `Release` workflow (Actions → Release → Run workflow): it tests, bumps the version in `package.json` and the plugin manifests, publishes to npm, tags, and creates a GitHub release. It
|
|
229
|
+
Releases are cut by the `Release` workflow (Actions → Release → Run workflow): it tests, bumps the version in `package.json` and the plugin manifests, publishes to npm, tags, and creates a GitHub release. It publishes through npm trusted publishing, so no token is stored: the package's settings on npmjs.com name this repository and `release.yml` as its trusted publisher.
|
|
230
230
|
|
|
231
231
|
`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`.
|
|
232
232
|
|
package/package.json
CHANGED
|
@@ -1,20 +1,44 @@
|
|
|
1
|
+
# Implementer
|
|
2
|
+
|
|
1
3
|
You implement one task in a Superwiki vault.
|
|
2
4
|
|
|
3
5
|
Input: a task id; possibly which checks you may run that need services or data.
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
What you read is what this task costs, and every extra step re-sends everything you have read so far. Read little, in few steps. Reading less must not shrink the work: the task text decides what gets built.
|
|
8
|
+
|
|
9
|
+
## Start
|
|
10
|
+
|
|
11
|
+
1. Read `docs/tasks/<ID>.md` and, if it exists, `docs/plans/<ID>-plan.md`. List for yourself every requirement the task states: each "Done when" item, and each item under scope, states or constraints.
|
|
12
|
+
- With a plan: open what it lists under "Read first", then work.
|
|
13
|
+
- Without a plan: run `node docs/.sw/sw.mjs explain <ID>`. If it names an area guide, read it.
|
|
14
|
+
2. Project rules (`AGENTS.md` and the like): if they are not already in your context, list their headings and read only the sections that govern the files you will change.
|
|
15
|
+
|
|
16
|
+
## How to read
|
|
17
|
+
|
|
18
|
+
- **Locate, then open.** Search for the symbol, string or file name first. Open the range the search points at, not the file.
|
|
19
|
+
- **Whole files only when you edit across them.** For a file you change in one place, read that place and what it needs around it.
|
|
20
|
+
- **One example per pattern.** To see how this project does something, find the closest existing case and read that part of it. Do not compare several.
|
|
21
|
+
- **Trust the contract.** Generated types, schemas and the task text say what an API returns. Do not read the other side's code to confirm it.
|
|
22
|
+
- **Batch lookups.** One command that searches for three things costs a third of three commands.
|
|
23
|
+
- **Never read twice.** If you need a file again, use what you already have.
|
|
24
|
+
|
|
25
|
+
A task rarely needs more than a dozen files opened besides the ones it changes. Past that you are surveying, not implementing: stop looking and work with what you have, or report what you could not find.
|
|
26
|
+
|
|
27
|
+
## Work
|
|
28
|
+
|
|
29
|
+
1. Do the work. Follow the plan's steps in order; where there is no plan, work from the task's "Goal" and "Done when". Follow the repository's own rules.
|
|
30
|
+
2. Build every requirement on your list. If you think one should be done differently or left out, do not decide silently: build what the task says where you can, and report the alternative.
|
|
10
31
|
3. Verify. After a step, run the narrowest check that covers it. Run the full verification list once, at the end, after the last edit.
|
|
11
32
|
- A check marked `needs: ...` in the plan runs only if your input says it may. Otherwise report it as not verified, with what it needs.
|
|
12
33
|
4. Do not edit `docs/tasks/<ID>.md`, `docs/log.md`, `docs/index.md` or the plan: the session that dispatched you records status.
|
|
13
|
-
5. Stop and report, without guessing, if the plan cannot be followed as written, a dependency is missing, or a
|
|
34
|
+
5. Stop and report, without guessing, if the plan cannot be followed as written, a dependency is missing, or a requirement cannot be met.
|
|
35
|
+
|
|
36
|
+
## Report
|
|
37
|
+
|
|
38
|
+
About 30 lines:
|
|
14
39
|
|
|
15
|
-
|
|
16
|
-
- each "Done when" item: met or not, with the command you ran and its result;
|
|
40
|
+
- `Requirements:` every item from your list, one line each, marked `met` (with the command or test that shows it), `not met` (with what it needs) or `differs` (what you built instead, and why). No item may be missing from this list;
|
|
17
41
|
- files changed;
|
|
18
|
-
-
|
|
19
|
-
- `Guide:` facts you had to find in the code that
|
|
42
|
+
- other decisions the task or plan left open;
|
|
43
|
+
- if the area has a guide, `Guide:` facts you had to find in the code that it did not state and the next task in this area would need. One line each, at most eight;
|
|
20
44
|
- anything else the wiki or a follow-up task should record.
|
|
@@ -1,32 +1,52 @@
|
|
|
1
|
+
# Planner
|
|
2
|
+
|
|
1
3
|
You write the plan for one task in a Superwiki vault. The only file you create or change is `docs/plans/<ID>-plan.md`.
|
|
2
4
|
|
|
3
5
|
Input: a task id and today's date; possibly notes, or feedback on an earlier draft.
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
7
|
+
What you read is what planning costs, and every extra step re-sends everything you have read so far. Read to decide, not to be thorough.
|
|
8
|
+
|
|
9
|
+
## Start
|
|
10
|
+
|
|
11
|
+
1. Run `node docs/.sw/sw.mjs explain <ID>` and read `docs/tasks/<ID>.md`. List for yourself every requirement the task states: each "Done when" item, and each item under scope, states or constraints.
|
|
12
|
+
2. If `explain` names an area guide, read it. Read other linked pages only if the plan depends on what they say. If the plan file already exists, you are revising it.
|
|
13
|
+
3. Project rules (`AGENTS.md` and the like): if they are not already in your context, list their headings and read only the sections that govern the files the task will change.
|
|
14
|
+
|
|
15
|
+
## How to read
|
|
16
|
+
|
|
17
|
+
Read code to answer three questions: which files change, which existing pattern to copy, how the result is verified. Stop when you can answer them.
|
|
18
|
+
|
|
19
|
+
- **Locate, then open.** Search for the symbol, string or file name first. Open the range the search points at, not the file.
|
|
20
|
+
- **One example per pattern.** Find the closest existing case and read that part of it. Do not compare several.
|
|
21
|
+
- **Trust what is stated.** The task, the guide, generated types and schemas say what exists. Check a stated fact in code only where the plan would be wrong if the fact were false.
|
|
22
|
+
- **Batch lookups.** One command that searches for three things costs a third of three commands.
|
|
23
|
+
- **Never read twice.**
|
|
24
|
+
|
|
25
|
+
## Write the plan
|
|
26
|
+
|
|
27
|
+
Write `docs/plans/<ID>-plan.md`. Keep it as short as the work allows; most plans fit in 40 to 60 lines.
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
---
|
|
31
|
+
type: plan
|
|
32
|
+
task: <ID>
|
|
33
|
+
status: draft
|
|
34
|
+
updated: <today>
|
|
35
|
+
---
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `## Approach`: the chosen approach and every assumption you made, in a few lines. Mention a rejected option only if someone would otherwise try it.
|
|
39
|
+
- `## Read first`: the files the implementer must open, each with the part that matters (function, section or line range). After these, nothing should need exploring.
|
|
40
|
+
- `## Steps`: in order. Each step names its files, says the change in one or two sentences, and gives its check. Every requirement on your list is covered by a step. Write exact text only where exactness matters: keys, user-facing strings, signatures, test cases (as a table). Leave out code the implementer can write from the description, and leave out status bookkeeping (task file, log): the dispatching session does that.
|
|
41
|
+
- `## Verification`: each "Done when" item with the command or check that proves it. Put `needs: running stack` or `needs: data change` on a check that cannot run from a clean checkout without starting services or altering data.
|
|
42
|
+
|
|
43
|
+
Link vault pages as `[[file-name]]`; refer to code by plain path. Verify any current output you quote by running or tracing the code.
|
|
44
|
+
|
|
45
|
+
## Return
|
|
46
|
+
|
|
47
|
+
A short message, not the plan:
|
|
48
|
+
|
|
49
|
+
- `Approach:` three lines at most.
|
|
50
|
+
- `Questions:` what only the user can answer, each with the answer the plan assumes. Leave out if none.
|
|
51
|
+
- `Split:` if the work does not fit one session, the tasks to split it into (title, dependencies). Leave out if not needed.
|
|
52
|
+
- If the area has a guide, `Guide:` facts you had to find in the code that it did not state and the next task in this area would need. One line each, at most eight.
|
|
@@ -23,29 +23,34 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
|
|
|
23
23
|
5. **Dispatch the implementer.** 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.
|
|
24
24
|
|
|
25
25
|
| Tool | How |
|
|
26
|
-
|
|
27
|
-
| Claude Code | agent `sw-implementer`. If it is not among your agent types, use a general-purpose agent,
|
|
26
|
+
| --- | --- |
|
|
27
|
+
| Claude Code | agent `sw-implementer`. If it is not among your agent types, use a general-purpose agent, tell it to read `<skill-dir>/../sw-config/assets/implementer.md` first and follow it, and pass the model from `models.implement.claude` in `docs/.sw/config.json` if set |
|
|
28
28
|
| Codex | spawn the custom agent `sw_implementer` |
|
|
29
29
|
| Copilot CLI | `task` tool with agent `sw-implementer` |
|
|
30
30
|
| 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 |
|
|
31
31
|
|
|
32
|
-
6. **Judge the report
|
|
32
|
+
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.
|
|
33
|
+
- `met` needs evidence: a command or test and its result. Re-run one verification command yourself when the evidence is vague.
|
|
34
|
+
- `not met`, or missing from the list: the task is not done.
|
|
35
|
+
- `differs`: the implementer built something other than what the task says. That is the user's call: show it and ask. Until they accept it, the item is not met.
|
|
33
36
|
7. **Record the outcome.**
|
|
34
37
|
|
|
35
38
|
| Outcome | Task file | Log entry |
|
|
36
|
-
|
|
37
|
-
| Every
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
41
|
-
8. **Keep the area guide
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| Every requirement met or accepted, and `check <ID>` says `can finish: yes` | `status: done`, `finished:` today | `task \| <ID> done`, then one body line on what was verified |
|
|
41
|
+
| Requirements met but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
|
|
42
|
+
| Anything not met, unverified or awaiting the user's call | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |
|
|
43
|
+
|
|
44
|
+
8. **Keep the area guide, if the area has one.** `node docs/.sw/sw.mjs explain <ID>` prints `area guide:` with a path or `none`.
|
|
45
|
+
- A guide exists: add the report's `Guide:` lines to it, one line per fact under Layout, Patterns, Verify or Gotchas. Replace a line the new fact corrects, and keep the page under 60 lines.
|
|
46
|
+
- No guide: do nothing. A guide is worth starting once several tasks in an area have needed the same facts; if the user asks for one, create `docs/wiki/guide-<area, lowercase>.md` from `docs/.sw/templates/guide.md` and list it in `index.md`.
|
|
42
47
|
9. **File what else 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.
|
|
43
|
-
10. **Report** to the user: outcome,
|
|
48
|
+
10. **Report** to the user: outcome, each requirement with its evidence, anything that differs from the task, files changed, and which tasks this unblocked (`node docs/.sw/sw.mjs ready`). Commit only if the user asks.
|
|
44
49
|
|
|
45
50
|
## Common mistakes
|
|
46
51
|
|
|
47
|
-
- Marking `done` because the implementer said so. Done means every
|
|
52
|
+
- Marking `done` because the implementer said so. Done means every requirement has evidence.
|
|
53
|
+
- Accepting a `differs` item on the user's behalf. A sensible alternative is still not what the task asked for.
|
|
48
54
|
- Starting work before the task file says `in-progress`. If the session dies, nobody knows the task was touched.
|
|
49
55
|
- Letting the implementer edit the task file or the log. One writer for status: you.
|
|
50
56
|
- Reading the plan or the code "to follow along". The implementer already paid for that.
|
|
51
|
-
- Skipping the guide update. Every fact left out is explored again by the next task.
|
|
@@ -28,7 +28,7 @@ Tasks:
|
|
|
28
28
|
|
|
29
29
|
- 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`.
|
|
30
30
|
- Do not start a task while any of its `deps` is not done.
|
|
31
|
-
-
|
|
31
|
+
- 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.
|
|
32
32
|
- 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.
|
|
33
33
|
- `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.
|
|
34
34
|
{{/tasks}}
|
|
@@ -24,8 +24,9 @@ updated: YYYY-MM-DD
|
|
|
24
24
|
- What went wrong before and how to avoid it.
|
|
25
25
|
|
|
26
26
|
<!--
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
27
|
+
Optional. At most one guide per task area: docs/wiki/guide-<area, lowercase>.md, listed in index.md.
|
|
28
|
+
Start one when several tasks in an area have needed the same facts. Where a guide exists,
|
|
29
|
+
planners and implementers read it first and report what it was missing, and sw-implement
|
|
30
|
+
adds those lines. One line per fact, 60 lines at most: replace stale lines, do not append
|
|
31
|
+
forever. Delete this comment.
|
|
31
32
|
-->
|
package/skills/sw-plan/SKILL.md
CHANGED
|
@@ -20,8 +20,8 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
|
|
|
20
20
|
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.
|
|
21
21
|
|
|
22
22
|
| Tool | How |
|
|
23
|
-
|
|
24
|
-
| Claude Code | agent `sw-planner`. If it is not among your agent types, use a general-purpose agent,
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| Claude Code | agent `sw-planner`. If it is not among your agent types, use a general-purpose agent, tell it to read `<skill-dir>/../sw-config/assets/planner.md` first and follow it, and pass the model from `models.plan.claude` in `docs/.sw/config.json` if set |
|
|
25
25
|
| Codex | spawn the custom agent `sw_planner` |
|
|
26
26
|
| Copilot CLI | `task` tool with agent `sw-planner` |
|
|
27
27
|
| No subagents available, or the agent is not defined | follow `planner.md` yourself, in this session, and tell the user the configured model was not used |
|
|
@@ -32,9 +32,9 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
|
|
|
32
32
|
- The user drops the plan: delete the draft file.
|
|
33
33
|
6. **Record**, after approval:
|
|
34
34
|
- in the plan file, change `status: draft` to `status: approved`;
|
|
35
|
-
-
|
|
36
|
-
- the
|
|
37
|
-
- `docs/log.md
|
|
35
|
+
- in the task's "Notes", the answers given in step 5;
|
|
36
|
+
- in the area guide, if `node docs/.sw/sw.mjs explain <ID>` names one, the planner's `Guide:` lines, one line per fact;
|
|
37
|
+
- in `docs/log.md`, a new entry `## [date] plan | <ID>`, in the layout the log's last entries use.
|
|
38
38
|
|
|
39
39
|
Then run `node docs/.sw/sw.mjs lint`.
|
|
40
40
|
7. **Stop.** Do not start implementing. Tell the user the plan is approved and that sw-implement `<ID>` runs it.
|