superwiki 0.1.0 → 0.1.2

package/skills/sw-implement/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user wants to implement, build, execute, start or cont
 
 # 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.
+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. You do not read the code or the plan: the report is your input.
 
 Run commands from the project root. `<skill-dir>` is the directory this SKILL.md is in.
 
@@ -16,31 +16,41 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    - `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.
+   - `plan: ... (draft, not approved)`: stop; the plan needs the user's approval (sw-plan).
+   - `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.
 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.
+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 the implementer may run; without a yes, none.
+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.
 
    | 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 |
+   | --- | --- |
+   | 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 |
    | 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.**
+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.
+   - `met` needs evidence: a command or test and its result. Re-run one verification command yourself when the evidence is vague.
+   - `not met`, or missing from the list: the task is not done.
+   - `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.
+7. **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>` |
+   | --- | --- | --- |
+   | 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 |
+   | Requirements met but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
+   | Anything not met, unverified or awaiting the user's call | 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.
+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`.
+   - 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.
+   - 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`.
+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.
+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.
 
 ## Common mistakes
 
-- Marking `done` because the implementer said so. Done means every "Done when" item has evidence.
+- Marking `done` because the implementer said so. Done means every requirement has evidence.
+- Accepting a `differs` item on the user's behalf. A sensible alternative is still not what the task asked for.
 - 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.
+- Reading the plan or the code "to follow along". The implementer already paid for that.

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

@@ -11,19 +11,36 @@
 - `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.
+- File formats: `docs/.sw/templates/`.
 
-Rules:
+Wiki:
 
 - 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}}
+- When you change the project, append one `change` entry to `log.md`: what changed and why, in a line.
+- `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}}
 {{#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`.
+
+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`.
 - 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.
 - `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.
+
+Skills. Use these without being asked. For work in this vault they come before any other planning, implementing or debugging skill:
+
+{{#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.
+- A question about a task (what, why, what it blocks): `sw-explain`.
 {{/tasks}}
-- File formats: `docs/.sw/templates/`.
+- A bug, failure or unexpected behavior is reported: `sw-triage` first, before any debugging.
+- A source to file (article, notes, transcript, URL): `sw-ingest`.
+- If a skill is not installed, follow the rules above by hand.
 <!-- sw:end -->