@rune-kit/rune 2.2.6 → 2.3.1

package/skills/context-engine/SKILL.md

@@ -4,7 +4,7 @@ description: "Context window management. Auto-triggered when context is filling
 user-invocable: false
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.6.0"
   layer: L3
   model: haiku
   group: state
@@ -130,6 +130,21 @@ In addition to tool-call counting, monitor context window percentage when availa
 Debounce: emit advisory max once per 5 tool calls to avoid noise.
 Tool-call thresholds (Steps 1-2) remain the primary signal. Percentage advisory is supplementary — use when CLI status bar data is available.
 
+## Iterative Retrieval (Context-Loading Strategy)
+
+When loading context for a task (Phase 1 of cook, or onboard), use a 4-phase retrieval loop instead of loading everything at once:
+
+```
+1. DISPATCH (broad): Search with initial task keywords → get 5-10 candidate files
+2. EVALUATE: Score each file's relevance (0-1). Note codebase-specific terminology discovered
+3. REFINE: Use discovered terms to search again with better keywords
+4. LOOP: Repeat max 3 cycles. STOP when 3 high-relevance files found (not 10 mediocre ones)
+```
+
+**Why**: The first search cycle reveals codebase-specific terms (custom class names, project conventions, internal APIs) that produce much better results in cycle 2. Loading 3 deeply relevant files beats loading 10 surface-level matches.
+
+**Key rule**: Stop at 3 high-relevance files, not 10 mediocre ones. Quality > quantity for context loading.
+
 ## Context Health Levels
 
 ```
@@ -158,6 +173,67 @@ Note: These are tool call counts, NOT token percentages. Claude Code does not ex
 - Blockers: [if any]
 ```
 
+## Strategic Compact Decision Table
+
+When ORANGE or RED is reached, use this table to determine whether compaction is safe at the current boundary:
+
+| Transition | Compact? | Reason |
+|-----------|----------|--------|
+| Research → Planning | YES | Research findings summarize well; key decisions survive |
+| Planning → Implementation | YES | Plan is in files (.rune/plan-*.md); context can reload from artifacts |
+| Debug → Next feature | YES | Debug findings are in Debug Report; fix has the diagnosis |
+| Mid-implementation (Phase 4) | **NO** | Losing file paths, partial changes, and test state is catastrophic |
+| After failed approach → Pivot | YES | Failed approach should be discarded; fresh context helps |
+| Quality (Phase 5) → Verify | **NO** | Quality findings reference specific file:line in current context |
+| After commit (Phase 7) | YES | Work is persisted in git; safe boundary |
+
+**What survives compaction**: Task description, file paths mentioned, key decisions, plan reference, current phase.
+**What is lost**: Full file contents read, intermediate reasoning, exact error messages, tool output details.
+
+## Context Budget Audit (Baseline Cost Awareness)
+
+MCP tool schemas and agent descriptions consume significant baseline context before any work begins. This section helps identify and reduce invisible context waste.
+
+### Token Cost Reference
+
+| Source | Approx. Cost | Loaded When |
+|--------|-------------|-------------|
+| Each MCP tool schema | ~500 tokens | Session start (always) |
+| Each agent description | ~200-400 tokens | Every `Task()` invocation |
+| CLAUDE.md | ~100-2000 tokens | Session start (always) |
+| Skill SKILL.md (full load) | ~500-3000 tokens | When skill is invoked |
+
+### Budget Rules
+
+| Rule | Threshold | Action |
+|------|-----------|--------|
+| Max MCP servers | <10 active | Disable unused MCP servers in settings |
+| Max MCP tools | <80 total | Remove or consolidate bloated MCP servers |
+| Agent descriptions | Only load needed | Use specific `subagent_type` to avoid loading all descriptions |
+| CLAUDE.md size | <150 lines | Move detailed docs to `.rune/` files, keep CLAUDE.md as index |
+
+### Audit Procedure
+
+When context health is YELLOW or worse, or when onboard detects >80 MCP tools:
+
+1. Count total MCP tool schemas loaded (from session start messages)
+2. Count agent descriptions available
+3. Estimate baseline cost: `(tools × 500) + (agents × 300) + CLAUDE.md tokens`
+4. If baseline >15% of estimated context window → flag as **Context Budget Warning**
+5. Rank MCP servers by tool count — suggest disabling servers with most tools and least usage
+
+### Report Addition
+
+When Context Budget Warning fires, append to Context Health report:
+
+```
+### Context Budget
+- **Baseline cost**: ~[N]k tokens ([X]% of estimated window)
+- **MCP tools loaded**: [count] across [N] servers
+- **Top consumers**: [server1] ([N] tools), [server2] ([N] tools)
+- **Recommendation**: Disable [server] to save ~[N]k tokens
+```
+
 ## Constraints
 
 1. MUST preserve context fidelity — no summarizing away critical details

package/skills/context-pack/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: context-pack
+description: "Creates structured handoff briefings between agents. Packages task context, constraints, and progress into a compact packet that subagents can consume without re-reading the full conversation. Prevents the 'lost context' problem in multi-agent delegation."
+user-invocable: false
+metadata:
+  author: runedev
+  version: "0.1.0"
+  layer: L3
+  model: haiku
+  group: state
+  tools: "Read, Glob, Grep"
+---
+
+# context-pack
+
+## Purpose
+
+When a parent agent delegates work to a subagent, critical context gets lost — the subagent starts fresh without knowing what was tried, what failed, what constraints apply, or what the parent already decided. Context-pack solves this by creating structured handoff briefings (context packets) that compress the essential information into a compact, parseable format. The packet is small enough to fit in a subagent's system prompt but complete enough to prevent redundant work and constraint violations.
+
+## Triggers
+
+- Called by `cook`, `team`, `rescue` before spawning subagents
+- Called by any L1/L2 skill that delegates work to another skill
+- Manual: when user says "hand off", "delegate", "split this task"
+
+## Calls (outbound)
+
+- `session-bridge` (L3): read persisted state for inclusion in packet
+- `context-engine` (L3): check current context budget before deciding packet size
+
+## Called By (inbound)
+
+- `cook` (L1): before Phase 2-5 subagent spawning
+- `team` (L1): before dispatching parallel workstreams
+- `rescue` (L1): before delegating module-level refactoring
+- `scaffold` (L1): before delegating component generation
+- Any L2 skill that spawns subagents
+
+## Data Flow
+
+### Feeds Into →
+
+- All subagent invocations: context packet → subagent system prompt
+- `completion-gate` (L3): packet's success criteria → claim validation baseline
+
+### Fed By ←
+
+- Parent agent conversation: decisions, constraints, failed attempts
+- `session-bridge` (L3): persisted state from prior sessions
+- `plan` (L2): phase files with task breakdowns
+
+## Workflow
+
+1. **COLLECT** — Gather context from the current conversation:
+   - Task description and user intent
+   - Decisions already made (and WHY)
+   - Constraints and hard-stops
+   - Failed attempts (what NOT to do)
+   - Files already read or modified
+   - Current progress state
+
+2. **COMPRESS** — Reduce to essential information:
+   - Strip conversational noise
+   - Deduplicate repeated context
+   - Prioritize by relevance to the delegated task
+   - Target: <500 tokens for simple tasks, <1500 tokens for complex
+
+3. **STRUCTURE** — Format as a context packet (see Output Format)
+
+4. **VALIDATE** — Check packet completeness:
+   - Does it include the task goal?
+   - Does it include constraints that could cause failure?
+   - Does it include what was already tried?
+   - Is it small enough for the target agent's context budget?
+
+## Output Format
+
+```markdown
+## Context Packet
+
+**Task**: [One-line description of what the subagent must do]
+**Parent**: [Which skill/agent is delegating]
+**Scope**: [Specific files, modules, or boundaries]
+
+### Decisions Made
+- [Decision 1]: [choice] — because [reason]
+- [Decision 2]: [choice] — because [reason]
+
+### Constraints
+- MUST: [requirement 1]
+- MUST NOT: [prohibition 1]
+- BLOCKED BY: [dependency, if any]
+
+### Already Tried
+- [Approach that failed] — [why it failed]
+
+### Files Touched
+- `path/to/file.ts` — [what was done / what needs doing]
+
+### Success Criteria
+- [ ] [Verifiable criterion 1]
+- [ ] [Verifiable criterion 2]
+
+### Progress
+- [What's done so far, if partial handoff]
+```
+
+## Returns
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `packet` | markdown | Structured context packet ready for subagent injection |
+| `token_estimate` | number | Estimated token count of the packet |
+| `completeness` | enum | `full` / `partial` / `minimal` — how much context was captured |
+| `warnings` | string[] | Missing context that could cause subagent failure |
+
+## Constraints
+
+1. MUST include task goal and success criteria — subagent needs to know when it's done
+2. MUST include failed attempts — prevents subagent from repeating mistakes
+3. MUST include hard-stop constraints — prevents constraint violations in delegated work
+4. MUST NOT exceed 2000 tokens — context packets that are too large defeat the purpose
+5. MUST NOT include full file contents — use file paths and summaries instead
+6. MUST NOT fabricate context — only include information from the actual conversation
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Packet too large (>2000 tokens) | HIGH | Compress aggressively — file paths not contents, decisions not discussions |
+| Missing constraint causes subagent violation | CRITICAL | Always scan for MUST/MUST NOT in parent conversation |
+| Stale context from prior session included | MEDIUM | Cross-check session-bridge state with current files |
+| Over-constraining subagent with parent's approach | MEDIUM | Include constraints and goals, not implementation approach (unless approach is the constraint) |
+
+## Self-Validation
+
+```
+SELF-VALIDATION (run before emitting output):
+- [ ] Packet includes a clear task goal
+- [ ] Packet includes success criteria (verifiable, not vague)
+- [ ] All MUST/MUST NOT constraints from parent are present
+- [ ] Failed attempts are listed (if any exist)
+- [ ] Token estimate is under 2000
+- [ ] No full file contents embedded (paths only)
+IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
+```
+
+## Done When
+
+- Context packet emitted in structured format
+- Token estimate calculated and within budget
+- All constraints from parent conversation captured
+- Completeness level assessed honestly
+- Self-Validation checklist: all checks passed
+
+## Cost Profile
+
+~200-500 input tokens (scanning conversation) + ~300-800 output tokens (generating packet). Haiku model — minimal cost per invocation.
+
+**Scope guardrail**: Do not implement code changes, run tests, or modify files. Only produce context packets for handoff. If asked to do more, defer to the delegated skill.