xtrm-tools 0.7.9 → 0.7.11

package/.xtrm/skills/default/update-xt/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: update-xt
+description: >
+  Update an xtrm-initialized project to match the current canonical install state.
+  Use this skill whenever the user asks to update, upgrade, repair, or re-sync xtrm
+  in a project — or when they say something like "xt is out of date", "skills aren't
+  loading", "hooks aren't firing", "the install looks wrong", or "I just pulled new
+  xtrm changes". Also triggers when the agent detects stale paths like
+  .claude/skills → active/claude (old structure) or .pi/settings.json pointing to
+  active/pi (old structure). Proactively suggest running this skill after any
+  xtrm-tools upgrade.
+---
+
+# update-xt
+
+Reconcile a project's xtrm installation against the current canonical state. Detect
+drift, apply targeted fixes, verify everything is wired correctly.
+
+## Canonical State (current)
+
+This is what a correctly installed project looks like. Check each item.
+
+### Skills wiring
+
+| Check | Expected value |
+|-------|----------------|
+| `.claude/skills` symlink target | `../.xtrm/skills/active` |
+| `.xtrm/skills/active/` | Flat directory of symlinks to `../default/<skill>` |
+| `active/pi/` subdirectory | Must NOT exist (stale — old runtime split) |
+| `active/claude/` subdirectory | Must NOT exist (stale — old runtime split) |
+| `.pi/settings.json` `.skills` array | Must include `"../.xtrm/skills/active"` |
+| `.pi/settings.json` `.skills` array | Must NOT include `"../.xtrm/skills/active/pi"` (old path) |
+
+### Hooks wiring
+
+| Check | Expected value |
+|-------|----------------|
+| `.claude/settings.json` or `~/.claude/settings.json` | Has `hooks` block with commands containing `/.xtrm/hooks/` paths |
+| Hooks events covered | At minimum: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop` |
+
+### Project bootstrap
+
+| Check | Expected value |
+|-------|----------------|
+| `.beads/` exists | Yes |
+| `CLAUDE.md` or `AGENTS.md` exists | Yes |
+
+## Detection
+
+Run these in order. Report what passes and what drifts.
+
+```bash
+# 1. High-level status — shows pending syncs
+xt status
+
+# 2. Claude hook wiring
+xt claude status
+
+# 3. Skills symlink
+readlink .claude/skills
+# Expected: ../.xtrm/skills/active
+# Stale: ../.xtrm/skills/active/claude
+
+# 4. Stale runtime subdirs (should return nothing)
+ls .xtrm/skills/active/pi 2>/dev/null && echo "STALE: active/pi exists"
+ls .xtrm/skills/active/claude 2>/dev/null && echo "STALE: active/claude exists"
+
+# 5. Pi settings skills entry
+node -e "const s=require('./.pi/settings.json'); console.log(s.skills)" 2>/dev/null
+# Expected to include: ../.xtrm/skills/active
+# Stale if includes: ../.xtrm/skills/active/pi
+
+# 6. Active view integrity (all entries must be valid symlinks)
+for f in .xtrm/skills/active/*; do [ -L "$f" ] || echo "NOT A SYMLINK: $f"; done
+```
+
+## Remediation
+
+Two commands cover almost all drift. Know which fixes what:
+
+| Command | Fixes |
+|---------|-------|
+| `xt claude install` | Hooks wiring only (settings.json hooks block) |
+| `xt init -y` | Skills symlink, active/ view rebuild, Pi settings, all phases |
+
+### Fix: Skills symlink stale or active/ view wrong
+
+`xt claude install` does NOT rebuild skills. Only `xt init` does (Phase 6b).
+
+```bash
+xt init -y
+```
+
+### Fix: Stale active/pi or active/claude subdirs
+
+`xt init` rebuilds `active/` atomically — it does NOT remove old subdirs left over
+from a previous layout. After `xt init -y` confirms the flat view is working, remove
+the stale dirs manually:
+
+```bash
+rm -rf .xtrm/skills/active/pi
+rm -rf .xtrm/skills/active/claude
+```
+
+Verify flat active/ is intact:
+```bash
+ls .xtrm/skills/active/
+# Should show skill dirs directly (clean-code, deepwiki, ...) — NOT pi/ or claude/ subdirs
+```
+
+### Fix: Hooks not wired
+
+```bash
+xt claude install
+```
+
+Rewires from `.xtrm/config/hooks.json` into `.claude/settings.json`.
+
+### Fix: Pi settings stale path
+
+Covered by `xt init -y`. If you need to target it alone:
+```bash
+xt pi install
+```
+
+### Fix: beads not initialized
+
+```bash
+bd init
+```
+
+## If updating xtrm-tools itself (not a consumer project)
+
+After merging changes to `cli/src/`, the dist must be rebuilt before `xt` picks up
+the new logic. Skipping this causes verification to report stale errors even after
+`xt init` runs.
+
+```bash
+cd cli && npm run build
+xt init -y   # now runs with updated code
+```
+
+## Verification
+
+After all fixes, confirm canonical state is restored:
+
+```bash
+xt claude status
+# Should show: ✓ Claude hooks wired
+# Should show: ✓ claude CLI available
+
+xt status
+# Should show no pending changes (or only optional ones)
+
+readlink .claude/skills
+# Must output: ../.xtrm/skills/active
+
+node -e "const s=require('./.pi/settings.json'); console.log(s.skills.includes('../.xtrm/skills/active'))" 2>/dev/null
+# Must output: true
+```
+
+If `xt status` still shows drift after targeted fixes, run the full sync:
+```bash
+xt init
+```
+
+## Reporting to the user
+
+After completing detection + remediation + verification, give the user a concise
+summary:
+
+```
+## xtrm update complete
+
+✓ .claude/skills → ../.xtrm/skills/active
+✓ active/ view: N skills (flat, all valid symlinks)
+✓ active/pi and active/claude stale dirs: removed
+✓ Hooks wired (X events, Y commands)
+✓ .pi/settings.json skills entry: current
+
+[Any items that could not be auto-fixed, with manual instructions]
+```
+
+If anything could not be fixed automatically (e.g. missing `.pi/settings.json`,
+no beads config), explain the manual step clearly — don't just report failure.

package/.xtrm/skills/default/using-nodes/SKILL.md

@@ -18,7 +18,7 @@ Think CEO: a CEO routes work to specialists, reads their reports, and makes deci
 
 The coordinator is **CLI-native**:
 - reason about the node objective,
-- call `sp node` commands via bash,
+- call `sp node` plus `sp ps`/`sp result` commands via bash,
 - read JSON command responses,
 - synthesize member evidence at phase boundaries,
 - decide the next command,
@@ -34,23 +34,26 @@ NodeSupervisor owns side effects and lifecycle transitions.
 
 ```bash
 # CORRECT — always use the env var or the exact ID from your first-turn context header
-sp node status --node $SPECIALISTS_NODE_ID --json
+sp ps --node $SPECIALISTS_NODE_ID --json
 
 # WRONG — never hardcode a node ID you saw in memory or a previous run
-sp node status --node research-XXXXXXXX --json
+sp ps --node research-XXXXXXXX --json
 ```
 
+Node refs accept any unique prefix (for operators), such as `research`, `research-5eaf`, or the full node ID.
+Coordinator commands should still use `$SPECIALISTS_NODE_ID` directly.
+
 ---
 
 ## Hard constraints
 
 1. **You coordinate only — you never do the work yourself**
-   - If you want to read a file or explore the codebase: STOP. Spawn an explorer member and read its result via `sp node result`.
+   - If you want to read a file or explore the codebase: STOP. Spawn an explorer member and read its result via `sp result $SPECIALISTS_NODE_ID:<member-key> --wait --json`.
    - If you want to write code: STOP. Spawn an executor member.
-   - Your only tool is `bash`. Your only bash commands are `sp node` subcommands.
+   - Your only tool is `bash`. Your only bash commands are `sp node` plus `sp ps`/`sp result`.
    - Do not call `read`, `ls`, `find`, `grep`, or any file inspection tool. You have none.
 
-2. **Use only `sp node` command surface for orchestration**
+2. **Use only `sp node` + `sp ps` + `sp result` + `sp steer` + `sp resume` command surface for orchestration**
    - Do not emit legacy contract JSON plans as the primary control mechanism.
    - Do not call deprecated node action channels.
 
@@ -67,9 +70,9 @@ sp node status --node research-XXXXXXXX --json
    - After each completed barrier, read the participating member results before deciding the next step.
 
 6. **Do not steer yourself**
-   - `sp node steer` is OPERATOR-ONLY.
+   - `sp steer <coordinator-job-id> ...` is OPERATOR-ONLY.
    - It steers the coordinator job itself, not member jobs.
-   - The coordinator must never call `sp node steer` on its own node id.
+   - The coordinator must never steer its own coordinator job.
 
 ---
 
@@ -77,26 +80,25 @@ sp node status --node research-XXXXXXXX --json
 
 | Command | Audience | Purpose |
 | --- | --- | --- |
-| `sp node status --node $SPECIALISTS_NODE_ID --json` | Coordinator | Read node state, registry, and readiness. |
+| `sp ps --node $SPECIALISTS_NODE_ID --json` | Coordinator | Read node state, registry, and readiness. |
 | `sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key <key> --specialist <name> [--bead <id>] [--phase <id>] [--json]` | Coordinator | Launch a member for the current phase. |
 | `sp node wait-phase --node $SPECIALISTS_NODE_ID --phase <id> --members <k1,k2,...> [--json]` | Coordinator | Block until the named phase members reach terminal state. |
-| `sp node result --node $SPECIALISTS_NODE_ID --member <key> --full --json` | Coordinator | Read the persisted output for a specific member after a phase barrier. |
+| `sp result $SPECIALISTS_NODE_ID:<member-key> --wait --json` | Coordinator | Read the persisted output for a specific member after a phase barrier. |
+| `sp steer <job-id> 'direction'` | Coordinator | Steer a running member with new context mid-flight. |
+| `sp resume <job-id> 'next task'` | Coordinator | Resume a waiting member with new task instructions. |
 | `sp node create-bead --node $SPECIALISTS_NODE_ID --title '...' [--type task] [--priority 2] [--depends-on <id>] [--json]` | Coordinator | Create follow-up tracked work discovered during orchestration. |
 | `sp node complete --node <node-id> --strategy <pr\|manual> [--json]` | Operator-only | Force-close node lifecycle when coordinator has reached waiting and operator decides to finalize. |
-| `sp node feed <node-id>` | Operator | Inspect node event history. |
 | `sp node members <node-id> [--json]` | Operator | Inspect member registry and lineage. |
 | `sp node memory <node-id> [--json]` | Operator | Inspect persisted node memory entries. |
-| `sp node attach <node-id>` | Operator | Attach to the coordinator tmux session. |
 | `sp node stop <node-id>` | Operator | Stop the coordinator process. |
 | `sp node promote <node-id> <finding-id> --to-bead <bead-id> [--json]` | Operator | Promote a finding into a bead note. |
-| `sp node steer <node-id> <message> [--json]` | Operator-only | Steer the coordinator externally. Never call this from the coordinator. |
 
 ---
 
 ## Core loop
 
 1. **Read status**
-   - `sp node status --node $SPECIALISTS_NODE_ID --json`
+   - `sp ps --node $SPECIALISTS_NODE_ID --json`
    - identify current phase, member registry, blockers, and completion readiness.
 
 2. **Issue orchestration commands**
@@ -105,16 +107,24 @@ sp node status --node research-XXXXXXXX --json
    - wait on the phase barrier before advancing.
 
 3. **Read member evidence**
-   - after `wait-phase` succeeds, call `sp node result --node $SPECIALISTS_NODE_ID --member <key> --full --json` for each participating member,
+   - after `wait-phase` succeeds, call `sp result $SPECIALISTS_NODE_ID:<member-key> --wait --json` for each participating member,
    - synthesize the outputs into the next decision.
 
-4. **Re-check status**
+4. **Steer members dynamically**
+   - after reading a member's result, if other members need updated context, steer them with `sp steer <job-id> 'specific direction from findings'`.
+   - only steer with concrete, evidence-based direction — never speculative.
+   - example: explorer finds X → steer researcher to 'investigate X patterns in external docs'.
+
+5. **Re-check status**
    - re-read node status after each command sequence,
    - adjust the plan from actual runtime state.
 
-5. **Coordinator terminal behavior**
+6. **Coordinator terminal behavior**
    - once goals are satisfied (or terminally blocked with explicit reason),
-   - synthesize evidence and enter/remain in `waiting`.
+   - synthesize ALL member evidence into a unified report,
+   - this report is your final output — it MUST integrate all member findings,
+   - 'Node completed. ok:true.' is NOT acceptable synthesis,
+   - enter/remain in `waiting` after producing synthesis.
    - do not issue a completion command; operator decides lifecycle closure via `sp node stop` (or force-close via `sp node complete`).
 
 ---
@@ -127,25 +137,70 @@ Use this exact loop:
 
 1. `status`
 2. decide the next phase/member set
-3. launch members
+3. spawn members for THIS phase only (not all phases)
 4. `wait-phase`
-5. `result --full`
+5. `result --wait` for each member
 6. synthesize evidence
-7. choose next action or enter waiting after synthesis
+7. steer or spawn members for next phase based on synthesis
+8. repeat until all phases complete
+9. produce final synthesis report
+10. enter waiting for operator closure
+
+### Multi-phase coordination pattern
+
+The coordinator MUST use at least 2 distinct phases:
+
+**Phase 1 — Explore:**
+- Spawn explorer to gather initial evidence
+- wait-phase → read result → synthesize findings
+- Decide: what needs deeper investigation?
+
+**Phase 2 — Deep-dive (conditional):**
+- Based on explore findings, spawn researcher/overthinker with specific context
+- Steer running members with evidence from phase 1
+- wait-phase → read results → synthesize
+
+**Phase 3 — Synthesis:**
+- Read ALL member results from all phases
+- Produce unified report integrating all findings
+- Enter waiting
 
 ### Synthesis mandate
 
+Before declaring synthesis complete, the coordinator **MUST** read the persisted results for ALL members across ALL phases.
+
+The synthesis report MUST:
+- Integrate findings from every member
+- Highlight agreements, contradictions, and gaps
+- Provide actionable conclusions
+- Be the coordinator's own substantive output
+
+'Node completed. ok:true.' is NEVER acceptable as synthesis output.
+
+### Synthesis mandate (repeated for emphasis)
+
 Before declaring synthesis complete, the coordinator **MUST** read the persisted results for the members that produced the evidence.
 
-Do not rely only on status transitions. `wait-phase` tells you the members are terminal; `sp node result` tells you what they actually found or changed. After synthesis, coordinator should remain in `waiting` for operator action.
+Do not rely only on status transitions. `wait-phase` tells you the members are terminal; `sp result $SPECIALISTS_NODE_ID:<member-key> --wait --json` tells you what they actually found or changed. After synthesis, coordinator should remain in `waiting` for operator action.
 
 ### Steering guidance
 
-Only steer when concrete result evidence shows a gap, contradiction, or missed requirement.
+Steer when concrete result evidence shows a gap, contradiction, or missed requirement.
 
-Do **not** steer speculatively.
-- Good: result evidence shows a reviewer found a missing acceptance criterion.
-- Bad: steering a member before reading its completed output.
+**Steering commands:**
+- `sp steer <job-id> 'new direction based on evidence'` — for running members
+- `sp resume <job-id> 'next task with context from phase N'` — for waiting members
+- `sp node spawn-member ... --phase <next-phase>` — for new members with specific context
+
+**Good steering patterns:**
+- Explorer finds module X handles auth → steer researcher: 'Investigate how other frameworks handle auth patterns similar to module X'
+- Researcher finds tradeoff A vs B → spawn overthinker: 'Analyze tradeoff between A and B. Explorer found that X uses A, researcher found Y uses B. Consider: performance, complexity, ecosystem support.'
+- Reviewer finds missing test coverage → spawn executor: 'Add tests for the paths reviewer identified: ...'
+
+**Bad steering patterns:**
+- Steering a member before reading its completed output
+- Steering with generic instructions ('do better', 'investigate more')
+- Steering speculatively without evidence from a prior member result
 
 ---
 
@@ -161,7 +216,7 @@ Use it when:
 Pattern:
 1. spawn phase members,
 2. call `wait-phase` with the exact member keys for that phase,
-3. read each member result with `sp node result ... --full --json`,
+3. read each member result with `sp result $SPECIALISTS_NODE_ID:<member-key> --wait --json`,
 4. only then move to the next phase or completion decision.
 
 ---
@@ -187,32 +242,59 @@ When a command fails:
 
 ## Example command sequences
 
-### Sequence A: explore -> synthesis -> impl -> waiting
+### Sequence A: multi-phase explore → deep-dive → synthesis
+
+```bash
+# Phase 1: explore
+sp ps --node $SPECIALISTS_NODE_ID --json
+sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key explore-1 --specialist explorer --phase explore-1 --json
+sp node wait-phase --node $SPECIALISTS_NODE_ID --phase explore-1 --members explore-1 --json
+sp result $SPECIALISTS_NODE_ID:explore-1 --wait --json
+# Synthesize explore-1 findings. Decide what needs deeper investigation.
+
+# Phase 2: deep-dive (spawned based on explore findings)
+sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key researcher-1 --specialist researcher --phase deep-dive-1 --json
+sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key overthinker-1 --specialist overthinker --phase deep-dive-1 --json
+sp node wait-phase --node $SPECIALISTS_NODE_ID --phase deep-dive-1 --members researcher-1,overthinker-1 --json
+sp result $SPECIALISTS_NODE_ID:researcher-1 --wait --json
+sp result $SPECIALISTS_NODE_ID:overthinker-1 --wait --json
+# Synthesize all phase 2 evidence.
+
+# Phase 3: final synthesis
+# Read all member results, produce unified report, enter waiting.
+sp ps --node $SPECIALISTS_NODE_ID --json
+```
+
+### Sequence B: explore → steer → synthesis
 
 ```bash
-sp node status --node $SPECIALISTS_NODE_ID --json
+# Phase 1: explore
+sp ps --node $SPECIALISTS_NODE_ID --json
 sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key explore-1 --specialist explorer --phase explore-1 --json
 sp node wait-phase --node $SPECIALISTS_NODE_ID --phase explore-1 --members explore-1 --json
-sp node result --node $SPECIALISTS_NODE_ID --member explore-1 --full --json
-# Synthesize the explore findings and decide whether impl is required.
-sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key impl-1 --specialist executor --phase impl-1 --json
-sp node wait-phase --node $SPECIALISTS_NODE_ID --phase impl-1 --members impl-1 --json
-sp node result --node $SPECIALISTS_NODE_ID --member impl-1 --full --json
-# Synthesize impl evidence, then stay in waiting for operator closure.
-sp node status --node $SPECIALISTS_NODE_ID --json
+sp result $SPECIALISTS_NODE_ID:explore-1 --wait --json
+# Explorer found X. Researcher is running — steer it.
+
+# Steer researcher with explorer findings
+sp steer <researcher-job-id> 'Based on explorer findings about X, investigate Y patterns in external docs'
+sp node wait-phase --node $SPECIALISTS_NODE_ID --phase deep-dive-1 --members researcher-1 --json
+sp result $SPECIALISTS_NODE_ID:researcher-1 --wait --json
+
+# Final synthesis — produce unified report integrating ALL findings
+sp ps --node $SPECIALISTS_NODE_ID --json
 ```
 
-### Sequence B: discovered work + review synthesis + operator closure
+### Sequence C: discovered work + review synthesis + operator closure
 
 ```bash
-sp node status --node $SPECIALISTS_NODE_ID --json
+sp ps --node $SPECIALISTS_NODE_ID --json
 sp node create-bead --node $SPECIALISTS_NODE_ID --title 'Follow-up: tighten node retry policy' --type task --priority 2 --json
 sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key review-1 --specialist reviewer --phase review-1 --json
 sp node wait-phase --node $SPECIALISTS_NODE_ID --phase review-1 --members review-1 --json
-sp node result --node $SPECIALISTS_NODE_ID --member review-1 --full --json
+sp result $SPECIALISTS_NODE_ID:review-1 --wait --json
 # Synthesize the review evidence, then decide whether a fix phase is needed.
 # If no more phases are needed, remain waiting and let operator close/stop the node.
-sp node status --node $SPECIALISTS_NODE_ID --json
+sp ps --node $SPECIALISTS_NODE_ID --json
 ```
 
 ---
@@ -235,15 +317,17 @@ sp node status --node $SPECIALISTS_NODE_ID --json
 - `sp node spawn-member --node $SPECIALISTS_NODE_ID --member-key <key> --specialist <name> [--bead <id>] [--phase <id>] [--json]`
 - `sp node create-bead --node $SPECIALISTS_NODE_ID --title "..." [--type task] [--priority 2] [--depends-on <id>] [--json]`
 - `sp node wait-phase --node $SPECIALISTS_NODE_ID --phase <id> --members <k1,k2,...> [--json]`
-- `sp node result --node $SPECIALISTS_NODE_ID --member <key> --full --json`
-- `sp node status --node $SPECIALISTS_NODE_ID [--json]`
+- `sp result $SPECIALISTS_NODE_ID:<member-key> --wait --json`
+- `sp ps --node $SPECIALISTS_NODE_ID --json`
+- `sp steer <job-id> 'new direction or context'` — steer a running member mid-flight
+- `sp resume <job-id> 'next task'` — resume a waiting member with new instructions
 
 ### Operator-only closure commands
 - `sp node stop <node-id>`
 - `sp node complete --node <node-id> --strategy <pr|manual> [--json]`
 
 ### Phase-boundary synthesis rule
-- After `wait-phase` completes, read every participating member result with `sp node result ... --full --json`, synthesize the evidence, then decide the next phase or stay waiting for operator closure.
+- After `wait-phase` completes, read every participating member result with `sp result $SPECIALISTS_NODE_ID:<member-key> --wait --json`, synthesize the evidence, then decide the next phase or stay waiting for operator closure.
 
 ### Phase kinds
 - `explore`: Discovery and evidence gathering.