claws-code 0.8.0

package/.claude/skills/claws-wave-lead/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: claws-wave-lead
+description: LEAD orchestration playbook for Claws Wave Army. Covers registration, sub-worker dispatch, PIAFEUR loop, and wave completion.
+type: skill
+---
+
+# Skill: claws-wave-lead
+
+You are the **LEAD** of a Claws Wave Army. You own the diff, the commits, the PIAFEUR loop, and the final wave lifecycle call.
+
+## MANDATORY — Monitor arming after every dispatch
+
+**After every `claws_dispatch_subworker` call, your VERY NEXT tool call MUST be `Monitor(...)` with the `monitor_arm_command` from the response. Any tool call that intervenes between `claws_dispatch_subworker` and `Monitor(...)` is a sequencing bug.**
+
+Arm per-worker, not per-wave. Dispatch one, arm immediately, then dispatch the next:
+
+```
+1. claws_dispatch_subworker({ waveId, role:'tester', mission:'...' })   → r1
+2. Monitor(command=r1.monitor_arm_command, ...)                          ← MUST be step 2
+3. claws_dispatch_subworker({ waveId, role:'reviewer', mission:'...' }) → r2
+4. Monitor(command=r2.monitor_arm_command, ...)                          ← MUST be step 4
+```
+
+Skipping or deferring Monitor leaves the sub-worker flying blind — no completion signal reaches the LEAD and the wave stalls.
+
+## Boot sequence
+
+```
+0. (Sidecar is already running — started by the SessionStart hook. No action needed.)
+1. claws_hello({ role:'orchestrator', peerName:'<waveId>-lead', waveId, subWorkerRole:'lead' })
+   // capabilities:['push'] is auto-granted as of v0.7.13 — passing it is optional, harmless
+2. claws_wave_create({ waveId, layers:[...], manifest:['tester','reviewer','auditor','doc'] })
+3. Publish wave.<waveId>.lead.boot
+4. Dispatch sub-workers via claws_dispatch_subworker (handles boot internally)
+5. Begin PIAFEUR loop
+```
+
+> **Critical:** the global `.claws/events.log` sidecar is already running — do NOT spawn a
+> second sidecar via Bash, do NOT `tail -F .claws/events.log` in any background process.
+> The only acceptable per-worker watcher is the `Monitor()` tool armed with the
+> `monitor_arm_command` returned in each `claws_dispatch_subworker` response. Any
+> `Bash(run_in_background=true)` invocation for event observation is a wave-discipline
+> violation and will be detected by the per-worker arming enforcement layer.
+
+## Sub-worker dispatch
+
+Use `claws_dispatch_subworker` — it handles boot internally. Do NOT sequence manual claws_create + claws_send chains.
+
+Dispatch and arm in lock-step — one dispatch, one Monitor, then the next:
+
+```
+// Step 1: dispatch first sub-worker
+const r1 = claws_dispatch_subworker({ waveId, role:'tester', mission:'...print MARK_TESTER_OK when done. go.' })
+// Step 2: arm Monitor IMMEDIATELY — MUST be your very next tool call after step 1
+Monitor(command=r1.monitor_arm_command,
+        description="claws monitor | term=" + r1.terminal_id,
+        timeout_ms=3600000, persistent=false)
+
+// Step 3: dispatch next sub-worker
+const r2 = claws_dispatch_subworker({ waveId, role:'reviewer', mission:'...' })
+// Step 4: arm Monitor IMMEDIATELY — MUST be your very next tool call after step 3
+Monitor(command=r2.monitor_arm_command,
+        description="claws monitor | term=" + r2.terminal_id,
+        timeout_ms=3600000, persistent=false)
+```
+
+`monitor_arm_command` is in every dispatch response. Arming it is **mandatory** — not a suggestion, not optional. The PIAFEUR loop starts only after all sub-workers are dispatched **and** their Monitors are armed.
+
+## PIAFEUR loop
+
+```
+Plan      — outline the exact diff in file/function terms
+Implement — write the code; npx tsc --noEmit after every .ts edit
+Audit     — read the diff as a reviewer; fix issues immediately
+Fix       — address reviewer/auditor findings
+Evaluate  — npm test; assert zero failures
+Update    — git commit (conventional message, no --no-verify)
+Repeat    — next iteration or advance to harvest
+```
+
+## Heartbeat discipline
+
+Publish `worker.<peerId>.heartbeat` every 20 s. Server violation timer fires at 25 s.
+
+## Wave completion sequence
+
+```
+// Loop on claws_drain_events until all sub-workers publish their .complete event
+const EXPECTED = new Set(['tester','reviewer','auditor','doc']);
+const completed = new Set();
+const HARD_TIMEOUT_MS = 20 * 60 * 1000;
+let cursor = 0;
+
+while (completed.size < EXPECTED.size) {
+  if (Date.now() - startedAt > HARD_TIMEOUT_MS) {
+    // log missing roles, break
+    break;
+  }
+  const { events, cursor: next } = claws_drain_events({ since_index: cursor, wait_ms: 15000 });
+  cursor = next;
+  for (const evt of events) {
+    const m = evt.topic?.match(/^wave\.[^.]+\.(\w+)\.complete$/);
+    if (m && EXPECTED.has(m[1])) completed.add(m[1]);
+  }
+}
+
+// Final gates: npm test green, git commit passes hooks
+claws_publish({ topic:`wave.${waveId}.lead.complete`, payload:{...} })
+claws_wave_complete({ waveId, summary:'...', commits:[...], regressionClean:true })
+// Print sentinel ONLY AFTER wave_complete returns
+// LEAD_COMPLETE_<waveId>
+```
+
+## Schemas used
+
+- `WaveLeadBootV1` — on boot
+- `WaveLeadCompleteV1` — on wave complete
+- `WorkerHeartbeatV1` — every 20 s
+- `WorkerPhaseV1` — phase transitions
+- `WorkerEventV1` kind=ERROR — blocking failures
+
+## References
+
+- `extension/src/wave-registry.ts`
+- `extension/src/event-schemas.ts`
+- `.claude/skills/claws-wave-subworker/SKILL.md`

package/.claude/skills/claws-wave-subworker/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: claws-wave-subworker
+description: Sub-worker discipline contract for Claws Wave Army. Covers registration, heartbeat, phase events, and completion sequence.
+type: skill
+---
+
+# Skill: claws-wave-subworker
+
+You are a **sub-worker** in a Claws Wave Army. Your role is one of: `tester` | `reviewer` | `auditor` | `bench` | `doc`.
+
+## Universal contract
+
+| Rule | Requirement |
+|---|---|
+| Register | `claws_hello` with `waveId` + `subWorkerRole` + `capabilities:['push']` within 60 s |
+| Boot event | Publish `wave.<waveId>.<role>.boot` immediately after hello |
+| Heartbeat | Publish `worker.<peerId>.heartbeat` every 20 s — server violation at 25 s |
+| Phase events | Publish `worker.<peerId>.phase` on every lifecycle transition |
+| Error events | Publish `worker.<peerId>.event` kind=ERROR for any blocking failure |
+| No --no-verify | Every commit must pass pre-commit hooks |
+| Full suite | `npm test` before every commit — zero failures required |
+| Type gate | `npx tsc --noEmit` after every `.ts` edit |
+| Complete event | Publish `wave.<waveId>.<role>.complete` as **absolute final act** before sentinel |
+| Sentinel order | Print role sentinel ONLY AFTER the complete event is published |
+
+> **capabilities:['push'] is mandatory** — without it `claws_publish` is silently rejected (BUG-03). Pass it in the initial `claws_hello`.
+
+## Boot sequence
+
+```
+0. (Sidecar already running via SessionStart hook — do NOT spawn another or tail events.log; the LEAD arms Monitor for you)
+1. claws_hello({ role:'worker', peerName:'<waveId>-<role>', waveId, subWorkerRole:'<role>', capabilities:['push'] })
+   // Save returned peerId — use it for all subsequent publish topics (worker.<peerId>.*)
+2. Publish wave.<waveId>.<role>.boot
+3. Start heartbeat: publish worker.<peerId>.heartbeat every 20 s
+4. Begin role-specific work; publish worker.<peerId>.phase on every lifecycle transition
+5. Publish wave.<waveId>.<role>.complete  ← FINAL act before sentinel
+6. Print role sentinel (e.g. ROLE_COMPLETE_<slug>)  ← ONLY after complete event published
+7. Stop heartbeat
+8. Close terminal
+```
+
+## Role-specific contracts
+
+**TESTER**: write failing tests first (RED phase), then re-run after LEAD commits (GREEN).
+**REVIEWER**: read-only. Publish `wave.<waveId>.review.finding` per issue. CRITICAL/HIGH must be addressed.
+**AUDITOR**: read-only. Sweep for race conditions, schema mismatches, error gaps, security issues.
+**BENCH**: run performance benchmarks after GREEN. Compare against baseline.
+**DOC**: update CHANGELOG, gap docs, template files. Never modify source `.ts` files.
+
+## Schemas used
+
+- `WorkerHeartbeatV1`, `WorkerPhaseV1`, `WorkerEventV1`
+- `WaveTesterRedCompleteV1`, `WaveReviewFindingV1`, `WaveAuditFindingV1`, `WaveBenchMetricV1`, `WaveDocCompleteV1`
+
+## References
+
+- `extension/src/event-schemas.ts`
+- `extension/src/wave-registry.ts`
+- `.claude/skills/claws-wave-lead/SKILL.md`