@rune-kit/rune 2.1.1

package/skills/surgeon/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: surgeon
+description: Incremental refactorer. Refactors ONE module per session using proven patterns — Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract.
+metadata:
+  author: runedev
+  version: "0.2.0"
+  layer: L2
+  model: sonnet
+  group: rescue
+  tools: "Read, Write, Edit, Bash, Glob, Grep"
+---
+
+# surgeon
+
+## Purpose
+
+Incremental refactorer that operates on ONE module per session using proven refactoring patterns. Surgeon is precise and safe — it applies small, tested changes with strict blast radius limits. Each surgery session ends with working, tested code committed.
+
+<HARD-GATE>
+- Blast radius MUST be checked before starting (max 5 files)
+- Safeguard MUST have run before any edit is made
+- Tests MUST pass after every single edit — never accumulate failing tests
+- Never refactor two coupled modules in the same session
+</HARD-GATE>
+
+## Called By (inbound)
+
+- `rescue` (L1): Phase 2-N SURGERY — one surgery session per module
+
+## Calls (outbound)
+
+- `scout` (L2): understand module dependencies, consumers, and blast radius
+- `safeguard` (L2): if untested module found, build safety net first
+- `debug` (L2): when refactoring reveals hidden bugs
+- `fix` (L2): apply refactoring changes
+- `test` (L2): verify after each change
+- `review` (L2): quality check on refactored code
+- `journal` (L3): update rescue progress
+
+## Execution Steps
+
+### Step 1 — Pre-surgery scan
+
+Call `rune:scout` targeting the module to refactor. Ask scout to return:
+- All files the module imports (dependencies)
+- All files that import the module (consumers)
+- Total file count touched (blast radius check)
+
+```
+Count the unique files that would be modified in this surgery session.
+If count > 5 → STOP. Split surgery into smaller sessions.
+Report which files are in scope and which must wait for a later session.
+```
+
+Confirm that `rune:safeguard` has already run for this module (check for `tests/char/<module>.test.ts` and `rune-safeguard-<module>` git tag).
+
+If safeguard has NOT run, call `rune:safeguard` now before continuing. Do not skip this.
+
+### Step 2 — Select refactoring pattern
+
+Based on module characteristics from scout, choose ONE pattern:
+
+| Pattern | When to use |
+|---|---|
+| **Strangler Fig** | Module > 500 LOC with many consumers. New code grows alongside legacy, consumers migrate one by one. |
+| **Branch by Abstraction** | Tightly coupled module. Create interface → wrap legacy behind it → build new impl → flip the switch. |
+| **Expand-Migrate-Contract** | Changing a function signature or data shape. Expand (add new), migrate callers, contract (remove old). Each phase = one commit. |
+| **Extract & Simplify** | Specific function with cyclomatic complexity > 10. Extract sub-functions, simplify conditionals. |
+
+State the chosen pattern explicitly before starting.
+
+### Step 3 — Refactor
+
+Use `Edit` for all code changes. Rules:
+- One logical change per `Edit` call — do not batch unrelated changes
+- Changes MUST be small and reversible
+- Never rewrite a file from scratch — use targeted edits
+- Never change more than 5 files total in this session
+- If a change reveals a hidden bug, stop and call `rune:debug` before continuing
+
+For **Strangler Fig**: Create the new module file first, then update one consumer at a time.
+
+For **Branch by Abstraction**: Create the interface first (commit), wrap legacy (commit), build new impl (commit), switch (commit). Four commits minimum.
+
+For **Expand-Migrate-Contract**: Expand (add new API alongside old), migrate each caller (one commit per caller if possible), contract (remove old API last).
+
+For **Extract & Simplify**: Extract sub-functions one at a time. Each extraction = one commit.
+
+### Step 4 — Test after each change
+
+After every `Edit`, call `rune:test` targeting:
+1. The characterization tests from `tests/char/<module>.test.ts`
+2. Any existing unit tests for the module
+3. Any consumer tests affected by this change
+
+```
+If any test fails → STOP. Do NOT continue with more edits.
+Call rune:debug to investigate. Fix before next edit.
+The code MUST stay in a working state after every single change.
+```
+
+### Step 5 — Review
+
+After all edits for this session are complete and tests pass, call `rune:review` on the changed files.
+
+Address any CRITICAL or HIGH issues raised by review before committing.
+
+### Step 6 — Commit
+
+Use `Bash` to commit this surgery step:
+
+```bash
+git add <changed files>
+git commit -m "refactor(<module>): [pattern] — [what was done]"
+```
+
+The commit message MUST describe which pattern was used and what changed. Each commit must leave the codebase in a fully working state.
+
+### Step 7 — Update journal
+
+Call `rune:journal` to record:
+- Module operated on
+- Pattern used
+- Files changed
+- Health score delta (estimated)
+- What remains for next session (if partial)
+
+## Refactoring Patterns
+
+```
+STRANGLER FIG           — New code grows around legacy (module > 500 LOC, many consumers)
+BRANCH BY ABSTRACTION   — Interface → wrap legacy → build new → switch
+EXPAND-MIGRATE-CONTRACT — Each step is one safe commit
+EXTRACT & SIMPLIFY      — For complex functions (cyclomatic > 10)
+```
+
+## Safety Rules
+
+```
+- NEVER refactor 2 coupled modules in same session
+- ALWAYS run tests after each change
+- Max blast radius: 5 files per session
+- If context low → STOP, save state, commit partial work
+- Each commit must leave code in working state
+- Never skip safeguard, even for "simple" changes
+```
+
+## Output Format
+
+```
+## Surgery Report: [Module Name]
+- **Pattern**: [chosen pattern]
+- **Status**: complete | partial (safe stopping point reached)
+- **Health**: [before] → [after estimated]
+- **Files Changed**: [list, max 5]
+- **Commits**: [count]
+
+### Steps Taken
+1. [step] — [result] — [test status]
+
+### Remaining (if partial)
+- [what's left for next surgery session]
+- Recommended: re-run rune:surgeon targeting [module] — session 2
+
+### Next Step
+[if complete]: Run rune:autopsy to update health scores
+[if partial]: Commit this checkpoint, then start new surgeon session for remaining work
+```
+
+## Constraints
+
+1. MUST verify safeguard tests pass before making any edit
+2. MUST check blast radius before starting — max 5 files per session
+3. MUST run tests after EVERY individual edit — never accumulate untested changes
+4. MUST NOT change function signatures without updating all callers
+5. MUST preserve external behavior — refactoring changes structure, not behavior
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Editing without confirming safeguard ran first | CRITICAL | HARD-GATE: check for `tests/char/<module>.test.*` AND `rune-safeguard-<module>` tag before first edit |
+| Exceeding 5-file blast radius without splitting | HIGH | HARD-GATE: count files in scope before starting — stop and split if > 5 |
+| Batching multiple edits before running tests | HIGH | HARD-GATE: run tests after every single Edit call — never accumulate untested changes |
+| Wrong pattern chosen for module size/type | MEDIUM | Match pattern explicitly: Strangler Fig = large/many-consumers, Extract = high cyclomatic complexity |
+| Not committing at safe stopping points when context runs low | MEDIUM | Every commit = working state — stop before context limit, not after losing partial work |
+
+## Done When
+
+- Safeguard confirmed (char tests + rollback tag exist)
+- Blast radius checked and within 5 files
+- Refactoring pattern selected and stated explicitly
+- All edits applied with tests passing after each individual edit
+- Characterization tests still pass after all changes
+- review passed on changed files
+- Surgery committed with message format `refactor(<module>): <pattern> — <description>`
+- journal updated with module health delta and remaining work
+
+## Cost Profile
+
+~3000-6000 tokens input, ~1000-2000 tokens output. Sonnet. One module per session.

package/skills/team/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: team
+description: "Multi-agent meta-orchestrator. Use when task spans 5+ files or 3+ modules, or when user says 'parallel', 'split this up', 'do all of these'. Decomposes large tasks into parallel workstreams, assigns to isolated cook instances, coordinates merging."
+context: fork
+agent: general-purpose
+metadata:
+  author: runedev
+  version: "0.3.0"
+  layer: L1
+  model: opus
+  group: orchestrator
+  tools: "Read, Write, Edit, Bash, Glob, Grep"
+---
+
+# team
+
+## Purpose
+
+Meta-orchestrator for complex tasks requiring parallel workstreams. Team decomposes large features into independent subtasks, assigns each to an isolated cook instance (using git worktrees), coordinates progress, and merges results. Uses opus for strategic decomposition and conflict resolution.
+
+<HARD-GATE>
+- MAX 3 PARALLEL AGENTS: Never launch more than 3 Task calls simultaneously. If more than 3 streams exist, batch them.
+- No merge without conflict resolution complete (Phase 3 clean).
+- Full integration tests MUST run before reporting success.
+</HARD-GATE>
+
+## Triggers
+
+- `/rune team <task>` — manual invocation for large features
+- Auto-trigger: when task affects 5+ files or spans 3+ modules
+
+## Mode Selection (Auto-Detect)
+
+```
+IF streams ≤ 2 AND total files ≤ 5:
+  → LITE MODE (lightweight parallel, no worktrees)
+ELSE:
+  → FULL MODE (worktree isolation, opus coordination)
+```
+
+### Lite Mode
+
+For small parallel tasks that don't warrant full worktree isolation:
+
+```
+Lite Mode Rules:
+  - Max 2 parallel agents (haiku coordination, sonnet workers)
+  - NO worktree creation — agents work on same branch
+  - File ownership still enforced (disjoint file sets)
+  - Simplified merge: sequential git add (no merge conflicts possible with disjoint files)
+  - Skip Phase 3 (COORDINATE) — no conflicts with disjoint files
+  - Skip integrity-check — small scope, direct output review
+  - Coordinator model: haiku (not opus) — saves cost
+
+Lite Mode Phases:
+  Phase 1: DECOMPOSE (haiku) — identify 2 streams with disjoint files
+  Phase 2: ASSIGN — launch 2 parallel Task agents (sonnet, no worktree)
+  Phase 4: MERGE — sequential git add (no merge needed)
+  Phase 5: VERIFY — integration tests on result
+```
+
+**Announce mode**: "Team lite mode: 2 streams, ≤5 files, no worktrees needed."
+**Override**: User can say "full mode" to force worktree isolation.
+
+### Full Mode
+
+Standard team workflow with worktree isolation (Phases 1-5 as documented below).
+
+## Calls (outbound)
+
+- `plan` (L2): high-level task decomposition into independent workstreams
+- `scout` (L2): understand full project scope and module boundaries
+# Exception: L1→L1 meta-orchestration (team is the only L1 that calls other L1s)
+- `cook` (L1): delegate feature tasks to parallel instances (worktree isolation)
+- `launch` (L1): delegate deployment/marketing when build is complete
+- `rescue` (L1): delegate legacy refactoring when rescue work detected
+- `integrity-check` (L3): verify cook report integrity before merge
+- `completion-gate` (L3): validate workstream completion claims against evidence
+- `constraint-check` (L3): audit HARD-GATE compliance across parallel streams
+- `worktree` (L3): create isolated worktrees for parallel cook instances
+- L4 extension packs: domain-specific patterns when context matches (e.g., @rune/mobile when porting web to mobile)
+
+## Called By (inbound)
+
+- User: `/rune team <task>` direct invocation only
+
+---
+
+## Execution
+
+### Step 0 — Initialize TodoWrite
+
+```
+TodoWrite([
+  { content: "DECOMPOSE: Scout modules and plan workstreams", status: "pending", activeForm: "Decomposing task into workstreams" },
+  { content: "ASSIGN: Launch parallel cook agents in worktrees", status: "pending", activeForm: "Assigning streams to cook agents" },
+  { content: "COORDINATE: Monitor streams, resolve conflicts", status: "pending", activeForm: "Coordinating parallel streams" },
+  { content: "MERGE: Merge worktrees back to main", status: "pending", activeForm: "Merging worktrees to main" },
+  { content: "VERIFY: Run integration tests on merged result", status: "pending", activeForm: "Verifying integration" }
+])
+```
+
+---
+
+### Phase 1 — DECOMPOSE
+
+Mark todo[0] `in_progress`.
+
+**1a. Map module boundaries.**
+
+```
+REQUIRED SUB-SKILL: rune:scout
+→ Invoke `scout` with the full task description.
+→ Scout returns: module list, file ownership map, dependency graph.
+→ Capture: which modules are independent vs. coupled.
+```
+
+**1b. Break into workstreams.**
+
+```
+REQUIRED SUB-SKILL: rune:plan
+→ Invoke `plan` with scout output + task description.
+→ Plan returns: ordered list of workstreams, each with:
+    - stream_id: "A" | "B" | "C" (max 3)
+    - task: specific sub-task description
+    - files: list of files this stream owns
+    - depends_on: [] | ["B"] (empty = parallel-safe)
+```
+
+**1c. Validate decomposition.**
+
+```
+GATE CHECK — before proceeding:
+  [ ] Each stream owns disjoint file sets (no overlap)
+  [ ] No coupled modules across streams:
+      → Use Grep to find import/require statements in each stream's owned files
+      → If stream A files import from stream B files → flag as COUPLED
+      → COUPLED modules MUST be moved to same stream OR stream B added to A's depends_on
+  [ ] Dependent streams have explicit depends_on declared
+  [ ] Total streams ≤ 3
+
+If any check fails → re-invoke plan with conflict notes.
+```
+
+Mark todo[0] `completed`.
+
+---
+
+### Phase 2 — ASSIGN
+
+Mark todo[1] `in_progress`.
+
+**2a. Launch parallel streams.**
+
+Launch independent streams (depends_on: []) in parallel using Task tool with worktree isolation:
+
+```
+For each stream where depends_on == []:
+  Task(
+    subagent_type: "general-purpose",
+    model: "sonnet",
+    isolation: "worktree",
+    prompt: "Cook task: [stream.task]. Files in scope: [stream.files]. Return cook report on completion."
+  )
+```
+
+**2b. Launch dependent streams sequentially.**
+
+```
+For each stream where depends_on != []:
+  WAIT for all depends_on streams to complete.
+  Then launch:
+  Task(
+    subagent_type: "general-purpose",
+    model: "sonnet",
+    isolation: "worktree",
+    prompt: "Cook task: [stream.task]. Files in scope: [stream.files]. Patterns from stream [depends_on] are available in worktree. Return cook report."
+  )
+```
+
+**2b.5. Pre-merge scope verification.**
+
+After each stream completes (before collecting final report):
+
+```
+Bash: git diff --name-only main...[worktree-branch]
+→ Compare actual modified files vs stream's planned file ownership list.
+→ If agent modified files OUTSIDE its declared scope:
+    FLAG: "Stream [id] modified [file] outside its scope."
+    Present to user for approval before proceeding to merge.
+→ If all files within scope: proceed normally.
+```
+
+This catches scope creep BEFORE merge — much cheaper to fix than after.
+
+**2c. Collect cook reports.**
+
+Wait for all Task calls to return. Store each cook report keyed by stream_id.
+
+```
+Error recovery:
+  If a Task fails or returns error report:
+    → Log failure: "Stream [id] failed: [error]"
+    → If stream is non-blocking: continue with other streams
+    → If stream is blocking (others depend on it): STOP, report to user with partial results
+```
+
+Mark todo[1] `completed`.
+
+---
+
+### Phase 3 — COORDINATE
+
+Mark todo[2] `in_progress`.
+
+**3a. Check for file conflicts.**
+
+```
+Bash: git diff --name-only [worktree-a-branch] [worktree-b-branch]
+```
+
+If overlapping files detected between completed worktrees:
+- Identify the conflict source from cook reports
+- Determine which stream's version takes precedence (later stream wins by default)
+- Flag for manual resolution if ambiguous — present to user before merge
+
+**3a.5. Verify cook report integrity.**
+
+```
+REQUIRED SUB-SKILL: rune:integrity-check
+→ Invoke integrity-check on each cook report text.
+→ If any report returns TAINTED:
+    BLOCK this stream from merge.
+    Report: "Stream [id] cook report contains adversarial content."
+→ If SUSPICIOUS: warn user, ask for confirmation before merge.
+```
+
+**3b. Review cook report summaries.**
+
+For each completed stream, verify cook report contains:
+- Files modified
+- Tests passing
+- No unresolved TODOs or sentinel CRITICAL flags
+
+```
+Error recovery:
+  If cook report contains sentinel CRITICAL:
+    → BLOCK this stream from merge
+    → Report: "Stream [id] blocked: CRITICAL issue in [file] — [details]"
+    → Present to user for decision before continuing
+```
+
+Mark todo[2] `completed`.
+
+---
+
+### Phase 4 — MERGE
+
+Mark todo[3] `in_progress`.
+
+**4a. Merge each worktree sequentially.**
+
+```
+# Bookmark before any merge
+Bash: git tag pre-team-merge
+
+For each stream in dependency order (independent first, dependent last):
+
+  Bash: git checkout main
+  Bash: git merge --no-ff [worktree-branch] -m "merge: stream [id] — [stream.task]"
+
+  If merge conflict:
+    Bash: git status  (identify conflicting files)
+    If ≤3 conflicting files:
+      → Resolve using cook report guidance (stream's intended change wins)
+      Bash: git add [resolved-files]
+      Bash: git merge --continue
+    If >3 conflicting files OR ambiguous ownership:
+      → STOP merge
+      Bash: git merge --abort
+      → Present to user: "Stream [id] has [N] conflicts. Manual resolution required."
+```
+
+**4b. Cleanup worktrees.**
+
+```
+Bash: git worktree remove [worktree-path] --force
+```
+
+(Repeat for each worktree after its branch is merged.)
+
+Mark todo[3] `completed`.
+
+---
+
+### Phase 5 — VERIFY
+
+Mark todo[4] `in_progress`.
+
+```
+REQUIRED SUB-SKILL: rune:verification
+→ Invoke `verification` on the merged main branch.
+→ verification runs: type check, lint, unit tests, integration tests.
+→ Capture: passed count, failed count, coverage %.
+```
+
+```
+Error recovery:
+  If verification fails after merge:
+    → Rollback all merges:
+    Bash: git reset --hard pre-team-merge
+    Bash: git tag -d pre-team-merge
+    Report: "Integration tests failed. All merges reverted to pre-team-merge state."
+    → Present fix options to user
+```
+
+Mark todo[4] `completed`.
+
+---
+
+## Constraints
+
+1. MUST NOT launch more than 3 parallel agents — batch if more streams exist
+2. MUST define clear scope boundaries per agent before dispatch — no overlapping file ownership
+3. MUST resolve all merge conflicts before declaring completion — no "fix later"
+4. MUST NOT let agents modify the same file — split by file ownership
+5. MUST collect and review all agent outputs before merging — no blind merge
+6. MUST NOT skip the integration verification after merge
+
+## Mesh Gates
+
+| Gate | Requires | If Missing |
+|------|----------|------------|
+| Scope Gate | Each agent has explicit file ownership list | Define boundaries before dispatch |
+| Conflict Gate | Zero merge conflicts after integration | Resolve all conflicts, re-verify |
+| Verification Gate | All tests pass after merge | Fix regressions before completion |
+
+## Output Format
+
+```
+## Team Report: [Task Name]
+- **Streams**: [count]
+- **Status**: complete | partial | blocked
+- **Duration**: [time across streams]
+
+### Streams
+| Stream | Task | Status | Cook Report |
+|--------|------|--------|-------------|
+| A | [task] | complete | [summary] |
+| B | [task] | complete | [summary] |
+| C | [task] | complete | [summary] |
+
+### Integration
+- Merge conflicts: [count]
+- Integration tests: [passed]/[total]
+- Coverage: [%]
+```
+
+---
+
+## Parallel Execution Rules
+
+```
+Independent streams  → PARALLEL (max 3 sonnet agents)
+Dependent streams    → SEQUENTIAL (respecting dependency order)
+All streams done     → MERGE sequentially (avoid conflicts)
+```
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Launching more than 3 parallel agents (full mode) / 2 (lite mode) | CRITICAL | HARD-GATE blocks this — batch into ≤3 streams (full) or ≤2 (lite) |
+| Using full mode with worktrees for ≤2 streams, ≤5 files | MEDIUM | Auto-detect triggers lite mode — saves opus cost and worktree overhead |
+| Agents with overlapping file ownership | HIGH | Scope Gate: define disjoint file sets before dispatch — never leave overlap unresolved |
+| Merging without running integration tests | HIGH | Verification Gate: integration tests on merged result are mandatory |
+| Ignoring sentinel CRITICAL flag in agent cook report | HIGH | Stream blocked from merge — present to user before any merge action |
+| Launching dependent streams before their dependencies complete | MEDIUM | Respect depends_on ordering — sequential after parallel, not parallel throughout |
+| Coupled modules split across streams | HIGH | Dependency graph check in Phase 1c — move coupled files to same stream or add depends_on |
+| Agent modified files outside declared scope | HIGH | Pre-merge scope verification in Phase 2b.5 — flag before merge, not after |
+| Merge failure with no rollback path | HIGH | pre-team-merge tag created before merges — git reset --hard on failure |
+| Poisoned cook report merged blindly | HIGH | Phase 3a.5 integrity-check on all cook reports before merge |
+
+## Done When
+
+- Task decomposed into ≤3 workstreams each with disjoint file ownership
+- All cook agents completed and returned reports
+- All merge conflicts resolved (zero unresolved before merge commit)
+- Integration tests pass on merged main branch
+- All worktrees cleaned up
+- Team Report emitted with stream statuses and integration results
+
+## Cost Profile
+
+~$0.20-0.50 per session. Opus for coordination. Most expensive orchestrator but handles largest tasks.