wavework 0.0.0-stage → 0.1.0

package/templates/skills/next-task-code/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: next-task-code
+description: Implement a beads task until its (already written) tests pass, within the assigned file set and the CLAUDE.md architecture and security rules. Used by implementer sub-agents in /next-task.
+---
+
+# next-task-code
+
+Write the production code that makes the tests from `next-task-write-tests` pass.
+
+- **Stay in your file set.** If you need to change a file outside it, stop and report why. Don't just change it.
+- **Follow CLAUDE.md:** its architecture, security and code-style rules apply to every line you write. If a rule and the bead disagree, stop and report. Don't guess.
+{{#if uiSkill}}
+- **UI changes** (under {{uiPaths}}): read `.claude/skills/{{uiSkill.name}}/SKILL.md` first and apply it. Add no new UI library unless the bead names it.
+{{/if}}
+- **Match the surrounding code style**, naming and comment density. No speculative abstractions, flags or configuration the bead doesn't ask for.
+- **Don't weaken tests to get green.** If a test turns out to be wrong, fix it and say why in the report.
+- **Out-of-scope work** you discover goes into a new bead (`bd create`, then `bd dep add`). Don't do it.
+{{#if codeMap}}
+- **Update the Code Map** in `{{codeMap.path}}`, only your own files' lines, one short line each: `path: what it is`.
+{{/if}}
+
+**Done when** the new tests and the existing tests in the area pass (`next-task-test`, focused). If they still fail after 3 failed focused runs, stop and report BLOCKED (see `next-task-implement`).

package/templates/skills/next-task-deps/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: next-task-deps
+description: Step 3 of /next-task. Installs the dependencies of every area and applies safe (non-major) updates as a separate, verified commit. Normally invoked by the next-task skill, not directly.
+---
+
+# next-task-deps
+
+The goal is a working install with current patch and minor versions, without mixing dependency churn into feature commits or taking on breaking upgrades unannounced.
+
+## Areas
+
+{{depsSection}}
+
+CLAUDE.md gives the project's dependency-update commands and what to leave alone; follow it.
+
+For each area that exists, with the project's own package manager:
+
+1. Install exactly what the lockfile says (frozen or locked mode where the tool has one).
+   - If the lockfile is out of date, run a normal install and include the lockfile in the update commit.
+2. Update within the version ranges the manifest already declares. Never use a "latest" or major-bumping flag.
+3. List what is still outdated: major versions not taken.
+   - Apply only patch and minor bumps of versions pinned directly in the project's manifests.
+   - Leave versions managed by a framework parent or BOM alone. Bumping that itself, including a minor bump, is a separate decision.
+
+## Verify and commit
+
+- If anything changed, run the full checks once:
+  {{fullChecksList}}
+- If they pass, commit only the dependency files (manifests and lockfiles) as `Update dependencies (patch/minor)`.
+- If they fail, revert the updates (`git checkout -- <files>`), keep the plain install, and mention it in the report.
+- **Major updates** and framework parent bumps are listed in the report, never applied here. Offer to file a bead for them.

package/templates/skills/next-task-e2e/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: next-task-e2e
+description: Add or extend browser e2e tests for the user-visible flow of a beads task and run them. Used by implementer sub-agents in /next-task; also usable on its own.
+---
+
+# next-task-e2e
+
+**Applies when** the task changes something a user can see or do in the UI. Backend-only and tooling tasks report `e2e: n/a (<reason>)`.
+
+{{#if hasE2e}}
+**If the e2e setup doesn't exist yet** (the area's e2e command can't run because the framework isn't set up), report `e2e: n/a (no e2e setup)`. Never set up the framework as part of another task.
+
+## Conventions
+
+The project's e2e conventions (fixtures, API mocking helper, ports) are in CLAUDE.md; follow them.
+
+- **Tool:** the e2e framework the area already uses (see the commands below). Specs live next to the existing ones, one spec per feature flow: `<feature>.spec.ts`, e.g. `containers.spec.ts`.
+- **Target:** the frontend with the backend API mocked at the network level, using the project's shared fixtures. An API call without a mock fails the test.
+- **Scope:** test the user journey (open the page, act, see the result), including at least one error path. Leave edge cases to unit tests.
+- **Selectors:** use roles, labels and text (`getByRole`, `getByLabel`). Use `data-testid` only when nothing semantic exists. Never use CSS or XPath structure.
+- **No sleeps.** Rely on the framework's auto-waiting and web-first assertions (`await expect(...)`).
+
+## Run
+
+Commands per area:
+
+{{e2eList}}
+
+- Focused: the area's e2e command followed by the spec file
+- Full: the area's e2e command as listed
+
+Report the spec files added or changed and the pass/fail counts.
+{{else}}
+No area configures an e2e command, so there is no e2e setup. Report `e2e: n/a (no e2e setup)`. Never set up a framework as part of another task.
+{{/if}}

package/templates/skills/next-task-findings/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: next-task-findings
+description: Writes problems found outside the scope of the current task into the shared backlog as beads labelled `finding`, deduplicated and grouped under a few standing findings epics so each epic can be run with /next-task. Used by the /next-task orchestrators after each child and before finishing; also usable on its own.
+---
+
+# next-task-findings
+
+The shared backlog for findings is **beads with the label `finding`** (synced via Dolt, so every session and machine sees them). Not a markdown file: findings are tracked in beads like all other work.
+
+Findings are not loose beads. Each one is a **child of a category epic**, with a `model:` label and acceptance criteria, so `/next-task <findings-epic>` can run the whole group without further planning.
+
+**Input:** the findings to record, each with a file/line, what is wrong and why it matters, and the bead it was discovered in (`<source-id>`). Sources:
+- the "Findings" section of an implementer report
+- the reviewer's "Out-of-scope" list
+- your own review of the child's diff (`git diff` in the worktree) during verification
+
+## What counts
+
+- Something wrong or worth improving that is **outside the current bead's acceptance criteria**. A defect in the bead's own scope is not a finding: send it back to the implementer.
+- Concrete and verifiable: a file, a scenario, a reason. No vague "could be cleaner".
+- There is no per-run limit. The grouping into epics keeps the backlog workable.
+
+## Categories
+
+Two classes, {{findingsEpicCount}} category epics. Pick exactly one category per finding.
+
+| Class | Category epic title | Slug | Typical content |
+|---|---|---|---|
+{{findingsEpics}}
+
+**Category epics are standing and never closed**, even when all children are done (no `bd close`, no `bd epic close-eligible` on them). One open epic per category.
+
+Class "Real" = a bug, security issue, data-loss risk or CLAUDE.md rule violation. Everything else is "Quality". Quality items are never priority 1 or 2.
+
+## Steps
+
+1. **Deduplicate:** `bd search "<key words>"` and `bd list --label finding --status open`. If an open bead already covers it, add a note instead: `bd update <id> --notes "Seen again in <source-id>: <one line>"`.
+2. **Find or create the category epic.** `bd list --type epic --status open --label fcat:<slug>`. Always use that one, even while it is being run: never create a second epic for the same category. If there is none at all, create it:
+
+   ```bash
+   bd create --type=epic --priority=<2 for Real categories, 3 for Quality> \
+     --title="<epic title from the table>" --labels fcat:<slug> \
+     --description="Standing backlog of <category> findings. Run with /next-task <id>." \
+     --acceptance="All child findings closed or consciously dropped."
+   ```
+3. **File the finding under it:**
+
+   ```bash
+   bd create --title="<short claim>" --type=<bug|chore> --priority=<0-4> \
+     --labels finding,model:<{{modelLabelPipe}}> \
+     --parent <epic-id> \
+     --deps discovered-from:<source-id> \
+     --description="<file:line>. <what happens, concrete scenario>. <why it matters>." \
+     --acceptance="<testable: how we know it's fixed, including the test that proves it>"
+   ```
+
+   - `bug` for wrong behaviour, `chore` for quality. Priority: 1 security or data loss, 2 user-visible bug, 3 quality, 4 nice to have.
+   - `model:` by the Model Policy in CLAUDE.md. When unsure, `{{models.implementers.default}}`:
+     {{modelRules}}
+   - The description and criteria must be enough to run without a planning session. If a finding needs a design decision (an open question), don't file a runnable child: say so in the description and leave out the `model:` label so `next-task-plan` stops on it.
+4. **Don't fix it here** and don't widen the running task. Findings never block the run, except priority 1: report those to the user at once.
+
+## Report
+
+One line per finding: bead ID (or the existing one it was added to), epic, priority, title.

package/templates/skills/next-task-finish/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: next-task-finish
+description: Final step of /next-task and /next-task-beads once all sub-agents are finished. Rebases onto origin/{{baseBranch}}, runs the full test gate, records findings, closes the beads, writes short documentation, pushes to {{baseBranch}} from the worktree and removes the worktree and branch. Normally invoked by those skills, not directly.
+---
+
+# next-task-finish
+
+Only run this when no child is blocked (see `next-task` step 6). Worktree and branch are removed only after a successful push (step 7); any earlier stop keeps both for resuming.
+
+Everything runs **inside the worktree** (`cd <WT> && ...`). The main checkout is never switched: the branch is pushed to `{{baseBranch}}` directly, so other sessions keep their checkout.
+
+Docs and bead closing happen **before** the push, so they're included in it.
+
+{{#if dashboard}}
+Record: `step-start --step finish` at the start. The full gate in step 2 records its `tests` (see `next-task-test`) and the branch review its `review` and `step-start/step-end --step review`. `step-start --step push` before step 6 and `step-end --step push --sha $(git rev-parse HEAD)` after it (the pushed commit), then, still in `<WT>` right before step 7 removes it, `step-end --step finish` and `run-end --status done` (record from `<WT>` while it exists, never after it is removed). Under `next-task-batch`, for the last epic that runs: also `run-end --run <BATCH-RUN> --status done|blocked` right before removing `<WT>`, or, if that epic stopped, from its kept `<WT>` at the stop (`blocked` if any epic stopped or was skipped). Every stop in this skill: `run-end --status blocked` (failed gate, conflict, rejected push, open must-fix).
+
+{{/if}}
+1. **Rebase onto the latest {{baseBranch}}.** `git fetch origin` then `git rebase origin/{{baseBranch}}`. If there are conflicts, stop and report. Don't resolve them by guessing.
+2. **Full test gate.** Run `next-task-test full` on the rebased branch. If anything fails, **stop**: don't close beads, don't push, and report the failure.
+   **Branch review** (always): run the branch mode of `next-task-review` over `origin/{{baseBranch}}..HEAD`, giving the reviewer the output of `.claude/scripts/red-green-check.sh <WT> origin/{{baseBranch}}`.
+   - PASS: continue. Out-of-scope items go to `next-task-findings` (step 3).
+   - Must-fix: one fix round by an implementer (SendMessage, or a new one), verify and commit as `Fix branch review findings (<id>)`, rerun `next-task-test full`, then review once more.
+   - Still Must-fix: **stop before the push**: no push, no bead closing, keep worktree and branch, report the open findings.
+3. **Findings.** Run `next-task-findings` for anything collected during the run that isn't filed yet, plus anything the full gate or the overall diff (`git diff origin/{{baseBranch}}...HEAD`) shows outside the scope.
+4. **Close the beads.**
+   - Each child (or each bead given to `/next-task-beads`): `bd close <id> "<one line: what was done> (<commit hash>)"`. Only close beads whose acceptance criteria were verified.
+   - Epic runs only: `bd close <epic> "<one line summary>"`, but only once every child is closed.
+   - Beads that aren't done stay open, and the epic stays open too. Say so in the report.
+5. **Write documentation.** Keep it short, following the CLAUDE.md rule:
+   {{#if codeMap}}
+   - Code Map (`{{codeMap.path}}`): check that every added, moved or removed file has a correct one-line entry.
+   {{/if}}
+   - README.md: update only if setup, commands or features visible to users changed.
+   - CLAUDE.md: update Build & Test or the rules only if they changed.
+   - Commit as `Document <epic title> (<epic-id>)` (bead runs: `Document <short summary> (<id>, <id>)`), including `.beads/issues.jsonl`.
+6. **Push to {{baseBranch}}.**
+   - `git fetch origin` and check `git merge-base --is-ancestor origin/{{baseBranch}} HEAD`. If {{baseBranch}} moved in the meantime, go back to step 1 (rebase and run the gate again).
+   - `git push origin HEAD:{{baseBranch}}`. This is a fast-forward push; never use `--force` or `--force-with-lease`. If it is rejected, stop and report.
+7. **Clean up** after a successful push, from the main repo (`MAIN`, see `next-task-branch`):
+   - `git -C "$MAIN" worktree remove <WT>`. Without `--force`: it refuses if anything is uncommitted; then stop and report.
+   - Check `git -C "$MAIN" merge-base --is-ancestor <branch> origin/{{baseBranch}}`, then `git -C "$MAIN" branch -D <branch>`. The ancestor check is what makes `-D` safe; never skip it.
+   - Update the local `{{baseBranch}}` only if no worktree has it checked out: `git -C "$MAIN" fetch origin {{baseBranch}}:{{baseBranch}}` (git refuses on its own otherwise; that's fine, mention it).
+8. **CI** is not part of this skill. The optional `watch-ci` step belongs to the calling skill.

package/templates/skills/next-task-implement/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: next-task-implement
+description: The sequence an implementer sub-agent follows for one beads child task during /next-task. Check worktree, understand, write tests, code, e2e, run focused tests, report. Each step is its own skill. Read by {{implementerAgentsPlain}}.
+---
+
+# next-task-implement
+
+You implement exactly one child bead. You don't plan, redesign or widen the scope. Read each step's skill (`.claude/skills/<name>/SKILL.md`) and follow it in order.
+
+0. **Check the worktree.** Your prompt names a worktree path and a branch. Work only there: start every Bash command with `cd <worktree> &&`, use absolute paths under it for Read/Edit/Write, and never run `git switch`/`checkout`.
+   - Run `cd <worktree> && git rev-parse --show-toplevel && git branch --show-current`. If either doesn't match the prompt, **stop** and report it. Don't write anything.
+   - Repeat this check right before reporting back.
+1. **Understand.**
+   - `bd show <id>`, then `bd update <id> --claim`.
+   {{#if codeMap}}
+   - Grep `{{codeMap.path}}` to find the files (don't read it whole). Only read code where the map isn't enough.
+   {{else}}
+   - Search the code for the files the bead names or implies. Read only what you need.
+   {{/if}}
+   - If the acceptance criteria are unclear or contradict CLAUDE.md, stop and report. Don't guess.
+2. **Write tests:** `next-task-write-tests`. The tests must fail first.
+3. **Implement:** `next-task-code`. Makes the tests pass{{#if codeMap}} and updates your `{{codeMap.path}}` lines{{/if}}.
+4. **E2E:** `next-task-e2e`. Adds or extends specs for the user-visible flow, or reports n/a.
+5. **Run focused tests:** `next-task-test`. The checks of your area, plus lint, type checks and e2e where configured. Everything must pass.
+   - **Retry cap:** count every focused run (`next-task-test`) of this bead that fails after you changed code. After the **3rd failed run**, stop. Don't weaken tests, don't try a 4th time. Step 6 then reports BLOCKED.
+6. **Report back. You're finished.** Don't commit, push or close the bead. Leave your changes uncommitted in the worktree. If blocked (retry cap, or a stop from steps 0–3), report **BLOCKED** instead of the success report: the reason, the failing command and the last ~40 lines of its failing output, the files changed so far, and findings. Otherwise report:
+   - the worktree check result (path and branch)
+   - the files changed
+   - the criterion → test mapping
+   - **Red before green:** the failing run captured in step 2 (test name + assertion line per test), or the stated exception (pure refactor, docs, config; with reason). A report without this section is incomplete. The orchestrator re-checks it with `.claude/scripts/red-green-check.sh`; a test that passes on the old code must be justified here (e.g. deliberate regression guard)
+   - the exact test commands and results
+   - the e2e status
+   - each acceptance criterion: met or not
+   - **Findings:** bugs or code-quality problems you noticed outside your bead's scope (file:line, what, why). Don't fix them and don't file beads; the orchestrator records them via `next-task-findings`. "None" if none.

package/templates/skills/next-task-plan/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: next-task-plan
+description: Steps 2 and 4 of /next-task and /next-task-beads. Validates the beads of a work set (an epic's children or a list of beads), then plans the implementation as parallel waves with a model and file set per child task, plus the hand-off prompt for implementer sub-agents. Normally invoked by the next-task skill, not directly.
+---
+
+# next-task-plan
+
+The **work set** is either an epic's children (`/next-task`) or the beads passed to `/next-task-beads`. Below, "child" means a bead of the work set and "inside the set" replaces "inside the epic".
+
+## Part 1: Check the beads tasks
+
+1. Epic run: `bd show <epic>` must be an epic that's `open` or `in_progress`, and `bd list --parent <epic>` lists the children. Bead run: each given ID must exist and must not be an epic (point to `/next-task` for those).
+2. Ignore beads that are already `closed`. On a rerun, `blocked` children count as open: re-plan them and reclaim each with `bd update <id> --status in_progress` before handing it off.
+3. For each open child, `bd show <child>` must have:
+   - a clear description and testable acceptance criteria
+   - a {{modelLabelsOr}} label
+   - no unresolved open decision
+
+   If any child fails this, **stop** and tell the user which child and what's missing. Suggest `/text-to-task` to fix it. Don't patch the beads yourself.
+4. Blockers outside the set, from `bd dep list <child>`: if a child depends on an issue outside the set that's still open, **stop** and report it.
+5. If no open children are left, skip straight to `next-task-finish`. Its job is then only to close the epic (bead run: report that nothing is left and remove the empty worktree).
+
+## Part 2: Plan the implementation
+
+{{#if codeMap}}
+Grep `{{codeMap.path}}` (read only the parts you need), plus the paths named in each child, to work out the **file set** each child will touch. Only read code where the map isn't enough.
+{{else}}
+Search the code for the paths named in each child to work out the **file set** each child will touch. Read only what you need.
+{{/if}}
+
+Build **waves**:
+- Wave 1 holds the children with no open dependencies inside the epic. The next wave holds the children whose dependencies are all in earlier waves. Continue the same way.
+- Children in the same wave run in parallel only if their file sets don't overlap. Shared files count as overlapping: build and dependency manifests (lockfiles included), shared configuration, `CLAUDE.md`, `README.md`. If two overlap, move one into the next wave.
+  {{#if codeMap}}
+  - Exception: Code Map lines in `{{codeMap.path}}`. Tell parallel agents to edit only their own lines; you resolve conflicts while committing.
+  {{/if}}
+
+Show the plan to the user as a short table: wave, child, model, file set, plus the worktree path. Then continue without waiting, unless the plan surfaced a problem.
+
+## Hand-off prompt (one per child)
+
+Use the agent matching the label ({{implementerAgentsOr}}) and send this prompt:
+
+```
+Implement bead <child-id> in worktree <absolute worktree path> on branch <branch>. Work only there: start every Bash command with `cd <worktree> &&`, use absolute paths under it, never switch branches. Follow .claude/skills/next-task-implement/SKILL.md exactly.
+Your file set: <paths>. Other agents are working in parallel on: <other children's paths>. Don't touch those.
+Do not commit, push or close the bead. Report back as that skill describes, including out-of-scope findings.
+```
+
+{{#if dashboard}}
+Record: `child-start` (see `next-task` step 5) is written by the orchestrator when it sends this prompt.
+{{/if}}

package/templates/skills/next-task-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: next-task-review
+description: Review step after each child bead in /next-task, /next-task-beads and /next-task-batch. A fresh read-only implementer-{{models.implementers.default}} sub-agent (never the implementer) reviews the child's diff against the bead's acceptance criteria and the CLAUDE.md rules, and returns must-fix vs out-of-scope findings. Normally invoked by those skills, not directly.
+---
+
+# next-task-review
+
+Independent review of one child's work before it is committed. The reviewer is a **fresh** `implementer-{{models.implementers.default}}` agent, never the one that implemented the child. It only reads and reports.
+
+## Input
+
+- bead ID, worktree path `<WT>`, branch name
+- the output of `.claude/scripts/red-green-check.sh <WT>` (run by the orchestrator; for the branch review: `... <WT> origin/{{baseBranch}}`)
+- diff range: the child's uncommitted changes (`git diff HEAD` plus untracked files from `git status --short`) in `<WT>`; if already committed, `<base>..HEAD`
+
+## Reviewer prompt
+
+Give the agent: the input above and these instructions.
+
+0. Check `<WT>` and branch as in `next-task-implement` step 0. Start every Bash command with `cd <WT> &&`.
+1. `bd show <id>` for the acceptance criteria. **Don't** claim or update the bead.
+2. Read the diff and the changed files. Check:
+   - every acceptance criterion is met and covered by a meaningful test
+   - would it pass on the old code: use the red-green script output (you can't run it read-only). Every `GREEN-ON-OLD` test is must-fix unless the bead is a stated exception (pure refactor/docs/config) or the implementer's report justifies it as a deliberate regression guard. `RED-COMPILE` is accepted. Exit code 2 or no output: ask the orchestrator for a rerun. `UNCHANGED` rows are untouched tests, ignore them. E2E specs are not covered; judge those from the diff (e.g. asserting only on mocks with no real outcome).
+   - CLAUDE.md Working Rules, Security, Architecture and Testing rules{{#if uiSkill}} (and the `{{uiSkill.name}}` skill for UI under {{uiPaths}}){{/if}}
+   {{#if codeMap}}
+   - Code Map entries in `{{codeMap.path}}` match the added, moved or removed files
+   {{/if}}
+   - no scope creep, no secrets in code, logs or tests
+3. **Read-only:** no Edit/Write, no commits, no `git add`/`stash`/`checkout`, no `bd` writes, no test or build runs that change files. Re-checking with read-only commands is fine.
+
+## Output
+
+```
+Worktree: <path> / <branch>
+Verdict: PASS | FIX
+Must-fix:
+- <file:line> <what is wrong> / <why> / <expected fix>
+Out-of-scope:
+- <file:line> <what> / <why>
+```
+
+- **Must-fix** = a criterion not met, a rule violation, a bug or a missing or meaningless test **within the child's scope**, including a test that would also pass on the pre-change code (step 2). Be concrete; no style nitpicks.
+- **Out-of-scope** = problems outside the child's scope. The orchestrator records them via `next-task-findings`.
+- `Verdict: PASS` only when Must-fix is empty. "None" for empty lists.
+
+## Branch review (always)
+
+Run by `next-task-finish` before the push, once per run. Same reviewer, but the input is the whole branch: diff `origin/{{baseBranch}}..HEAD` in `<WT>`, checked against the epic's (or all given beads') description and acceptance criteria as a whole: gaps between children, inconsistent behaviour, missing wiring{{#if codeMap}} or `{{codeMap.path}}` lines{{/if}}. Same checklist (including the red-green script output) and same output format. One fix round only, no 3-round loop (see `next-task-finish`).
+
+## Loop (the orchestrator's side)
+
+1. After the implementer reports and you verified its result, start the reviewer.
+2. Out-of-scope items: `next-task-findings`.
+3. Must-fix items: send them to the **same implementer** (SendMessage; if it can't be reached, start a new implementer with the findings), then re-verify and review again.
+4. **Max 3 review rounds** per child. If the third review still has Must-fix items, stop that child: don't commit, report the open findings with the worktree path and let the user decide.
+5. Commit the child only after a PASS.
+
+{{#if dashboard}}
+Record: `review --bead <id> --verdict <PASS|FIX> --mustFix <n> --round <n>` after each review (branch review: `--bead branch`, with `step-start/step-end --step review` around it).
+{{/if}}

package/templates/skills/next-task-test/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: next-task-test
+description: Runs the checks of the area that changed (or the full suite of every area with "full"). Used by implementer sub-agents and the next-task orchestrator.
+---
+
+# next-task-test
+
+Work out the changed area with `git status --porcelain` plus `git diff --name-only origin/{{baseBranch}}...HEAD`, run inside the worktree you were given. An area counts as changed when a changed path starts with one of its path prefixes below. Run only what that area needs. If the argument is `full`, run the **Full** command of every area.
+
+{{checksSection}}
+
+{{#if hasLint}}
+When an area lists a **Lint** command, also run its **Lint** command with the focused command.
+
+{{/if}}
+Run the **Full** command of an area instead of the focused one if its build or dependency manifests, shared configuration or shared test infrastructure changed. CLAUDE.md may list more files whose change should force the **Full** command; follow it.
+
+If a check needs a service that isn't running (a container runtime, a database), report that. Don't skip the tests.
+
+{{#if hasE2e}}
+E2E commands run as part of their area. Run the focused e2e spec for the changed feature, and the whole e2e command if shared code or fixtures changed. See `next-task-e2e` for the conventions.
+
+{{/if}}
+{{#if dashboard}}
+Record: after each run, `node .claude/wavework/dashboard/record.mjs tests --scope <{{areaNamesPipe}}|e2e|full> --passed <n> --failed <n> --duration <seconds>` (no `--run` needed inside the worktree; append `2>/dev/null || true`, it must never fail a standalone run).
+
+{{/if}}
+## Report
+
+For each command: the command, pass or fail, and the test counts. On failure, give the first relevant error lines, not the whole log, and keep the last ~40 lines of the failing output so a BLOCKED report can quote it. Implementers count failed runs for the retry cap in `next-task-implement`.

package/templates/skills/next-task-write-tests/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: next-task-write-tests
+description: Write failing tests from a beads task's acceptance criteria before implementing (test-first). Follows each area's existing test framework. Used by implementer sub-agents in /next-task; also usable on its own for any bead.
+---
+
+# next-task-write-tests
+
+Turn every acceptance criterion of the bead into at least one test that **fails now**. Don't write production code in this step. The only exception is the minimum stub needed to compile, such as an empty method or class.
+
+The project's test conventions (frameworks, fixtures, mocking boundaries) are in CLAUDE.md; follow them.
+
+**Backend and library code:**
+- Use the area's existing test framework and layout; read neighbouring tests first. One test class or file per unit under test, named after it.
+- Anything touching a database or other external service uses the project's shared test setup. Don't start ad-hoc infrastructure.
+- Mock only at module boundaries. Don't mock the unit under test or the persistence layer.
+- Security-relevant code always gets tests for the malicious cases:
+  - path traversal: `../`, absolute paths, symlinks, URL-encoded variants
+  - command or argument injection
+  - missing or insufficient permissions
+
+**UI code** (test file next to the code):
+- Test behavior as a user sees it: roles, labels, text. Don't test implementation details.
+- Mock the network at the API boundary. Don't mock the data-fetching library.
+
+**Naming:** test names state the behavior, e.g. `rejectsPathOutsideBaseDirectory` or `shows error when start fails`.
+
+**Done when:**
+- every acceptance criterion maps to at least one test
+- the new tests compile
+- running them (`next-task-test`) shows them **failing for the expected reason**: an assertion or a missing behavior, not a typo or a setup error
+
+**Red before green:** capture that failing run before coding: per new/changed test the test name and the failing assertion line (or error message). Only exception: pure refactor, docs-only or config-only beads, where the report states the exception and why no test can fail first. No silent skipping. The orchestrator verifies this mechanically with `.claude/scripts/red-green-check.sh` (runs your tests against the pre-change code), so a test that is green before the change will be flagged.
+
+List the criterion → test mapping and the red evidence in your report.

package/templates/skills/text-to-task/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: text-to-task
+description: Turn a free-text feature request, idea or bug description into beads tasks — one epic per request with child tasks that carry the implementation. First checks whether the text is scoped well enough; if not, asks the user targeted questions instead of creating vague tasks. Use when the user wants to plan work, create tasks/beads/issues from a description, or says "text-to-task".
+---
+
+# text-to-task
+
+Turn the user's text into an epic with implementable child tasks in beads (`bd`). This is planning work: per the Model Policy in CLAUDE.md it belongs on the `{{models.planning}}` model. If the session isn't on `{{models.planning}}`, say so and suggest `/model {{models.planning}}` before continuing. Never implement anything here.
+
+Input: the text after the command (`$ARGUMENTS`), or the user's latest message if that's empty.
+
+## 1. Gather context (cheap, targeted)
+
+- Read CLAUDE.md: the working rules, model policy, architecture and security sections. {{#if codeMap}}Grep `{{codeMap.path}}` to find affected files; only open code if the map isn't enough.{{else}}Find the affected files with grep; only open what you need.{{/if}}
+- Read the project's list of open decisions, if it has one (CLAUDE.md says where).
+- Run `bd list --status open` and check for existing epics/tasks that already cover the request. Extend or reference them instead of creating duplicates.
+
+## 2. Scope check — decide before creating anything
+
+The text is **scoped enough** only if you can answer all of these without guessing:
+
+1. **Goal:** what observable outcome is wanted, and for whom (which kind of user or role)?
+2. **Boundaries:** what is in and out of this request?
+3. **Placement:** which area of the codebase ({{areaNamesPipe}}) and which modules inside it?
+4. **Acceptance:** can you write concrete, testable acceptance criteria for every child task?
+5. **Decisions:** does it depend on an open decision or on something CLAUDE.md doesn't settle? Open decisions are never guessed.
+6. **Conflicts:** does it contradict CLAUDE.md (out-of-scope items, security rules, architecture rules)?
+
+If any answer is missing:
+- **Do not create beads** for the unclear parts.
+- Ask the user with AskUserQuestion: at most 4 specific questions, each with concrete options and your recommendation first. Never ask what CLAUDE.md or the code already answers.
+- If parts of the text are clear and independent of the open questions, say which ones and offer to create those now.
+- If the text conflicts with CLAUDE.md, name the conflict and ask; don't silently adapt it.
+
+Once the answers are in, re-run the check, then continue.
+
+## 3. Break it down
+
+**One epic per request** (`-t epic`): the "what and why". Description holds the goal, scope (in/out) and any decisions made during the scope check. Acceptance criteria describe the user-visible result. The epic carries no implementation itself.
+
+**Child tasks** (`--parent <epic>`, `-t task`, or `-t bug` for defects) carry all the implementation. Each child must:
+- Be completable by one implementer agent in one session: one coherent change, typically one module and layer. Split work in different areas into separate children.
+- Include its own tests in the acceptance criteria. No separate "write tests" tasks.
+- Name the files or packages to touch, taken from the {{#if codeMap}}code map{{else}}codebase{{/if}} (for new files: the intended path).
+- Have testable acceptance criteria as a bullet list.
+- Carry a model label per the model policy ({{modelLabelsOr}}):
+  {{modelRules}}
+{{#if uiSkill}}
+- For UI children (files under {{uiPaths}}): name `{{uiSkill.name}}` in the description and add an acceptance criterion that the UI follows the {{uiSkill.name}} skill. If the work needs a new library, say so explicitly in the child.
+{{/if}}
+- Respect the build order and the architecture rules in CLAUDE.md (for example a schema migration is its own child, ahead of the code that needs it).
+
+Wire ordering with dependencies between children (`bd dep add <later> <earlier>`) only where one truly needs the other first, so independent children stay parallelizable in `bd ready`.
+
+Priority: inherit from the request (default P2). Use P1 only when the user says it's urgent or it blocks other work.
+
+## 4. Create
+
+Create the epic first, then the children, capturing IDs with `--silent`:
+
+```bash
+EPIC=$(bd create "<epic title>" -t epic -p 2 --silent \
+  -d "<goal, scope in/out, decisions>" \
+  --acceptance "<user-visible result>")
+
+T1=$(bd create "<child title>" -t task -p 2 --parent "$EPIC" -l model:{{models.implementers.default}} --silent \
+  -d "<what and where: files/packages>" \
+  --acceptance "- <criterion>
+- <tests that must exist and pass>")
+
+bd dep add "$T2" "$T1"   # only if T2 really needs T1 first
+```
+
+Titles: imperative and specific ("Add a migration that creates the hosts table", not "Hosts DB stuff").
+
+## 5. Report
+
+Keep it short. Show the tree (`bd list --parent <epic> --pretty`), mention any assumptions you made, list anything you deliberately left out or deferred, and name which children are ready to start. Do not commit; `.beads/issues.jsonl` is exported automatically.

package/templates/skills/watch-ci/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: watch-ci
+description: Watch the GitHub Actions run(s) for the current commit, branch or a given run ID and report the result, with the failing job, step and error tail on failure. Read-only. Use when the user says "watch ci", "check ci", "did the build pass" or /watch-ci.
+---
+
+# watch-ci
+
+Argument (optional): a numeric run ID or a branch name. Default: the runs for `HEAD` on the current branch.
+
+**Read-only.** Only `gh auth status`, `gh run list`, `gh run view` and `gh run watch` are used. Never re-run or cancel runs, edit code, commit or push. A bead is filed only after the user says yes.
+
+## 1. Preflight
+
+- `command -v gh`. If missing, stop: "gh is not installed. Install the GitHub CLI (https://cli.github.com), then `! gh auth login`."
+- `gh auth status`. If not authenticated, stop: "gh is not logged in. Run `! gh auth login`."
+
+## 2. Resolve the target
+
+- Numeric argument: that run ID.
+- Branch name argument: `gh run list --branch <name> --limit 5 --json databaseId,workflowName,status,conclusion,url,headSha`, take the newest run(s).
+- No argument: `sha=$(git rev-parse HEAD)`, then `gh run list --commit "$sha" --json databaseId,workflowName,status,conclusion,url`.
+  - No runs yet (just pushed): retry up to 5 times, ~10 seconds apart, using a background command or Monitor, not a foreground `sleep`.
+  - Still none: say so. Also check whether HEAD is pushed (`git branch -r --contains "$sha"`); if not, say "HEAD is not pushed, so no run exists." Pull requests only start runs on the PR head commit.
+
+## 3. Watch
+
+- Completed runs need no waiting.
+- For every `queued` or `in_progress` run (matrix jobs and several workflows included), run `gh run watch <id> --exit-status` in the background (`run_in_background`) or via Monitor, so the session is not blocked. Never use a foreground `sleep`. Wait for all runs.
+
+## 4. Report
+
+Per run: workflow, conclusion, duration (`gh run view <id> --json workflowName,conclusion,startedAt,updatedAt,url,jobs`), URL.
+
+On failure: `gh run view <id> --log-failed`, then show only the failing job, the failing step and the relevant error lines (the tail, not the full log). Redact anything that looks like a secret, token or password.
+
+## 5. On failure: offer a bug bead
+
+Ask the user (AskUserQuestion) whether to file a bug bead. Only on yes:
+
+`bd create -t bug` with the run URL, failing job and step, and the log excerpt in the description.
+
+Then stop. Do not fix, re-run or push.