@rune-kit/rune 2.2.3 → 2.2.6

package/skills/skill-forge/SKILL.md

@@ -3,7 +3,7 @@ name: skill-forge
 description: Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship.
 metadata:
   author: runedev
-  version: "1.2.0"
+  version: "1.4.0"
   layer: L2
   model: opus
   group: creation
@@ -97,11 +97,13 @@ Follow `docs/SKILL-TEMPLATE.md` format. Required sections:
 | Frontmatter | YES | Name, description, metadata |
 | Purpose | YES | One paragraph, ecosystem role |
 | Triggers | YES | When to invoke |
-| Calls / Called By | YES | Mesh connections |
+| Calls / Called By | YES | Mesh connections (control flow) |
+| Data Flow | YES | Feeds Into / Fed By / Feedback Loops (data flow) |
 | Workflow | YES | Step-by-step execution |
 | Output Format | YES | Structured, parseable output |
 | Constraints | YES | 3-7 MUST/MUST NOT rules |
 | Sharp Edges | YES | Known failure modes |
+| Self-Validation | YES | Domain-specific QA checklist (per-skill, not centralized) |
 | Done When | YES | Verifiable completion criteria |
 | Cost Profile | YES | Token estimate |
 | Mesh Gates | L1/L2 only | Progression guards |
@@ -277,7 +279,72 @@ Wire the skill into the mesh:
 1. **Update `docs/ARCHITECTURE.md`** — add to correct layer/group table
 2. **Update `CLAUDE.md`** — increment skill count, add to layer list
 3. **Add mesh connections** — update SKILL.md of skills that should call/be called by this one
-4. **Verify no conflicts** — new skill's output format compatible with consumers?
+4. **Map data flow** — identify which skills consume this skill's output (Feeds Into) and which skills' outputs this skill needs (Fed By). Look for feedback loops where two skills refine each other's work
+5. **Write Self-Validation** — 3-5 domain-specific checks unique to this skill's output. Ask: "What quality issues can ONLY this skill catch?"
+6. **Verify no conflicts** — new skill's output format compatible with consumers?
+
+### Phase 6.5 — EXTENSION AUTHORING (if building an extension, not a skill)
+
+Extensions augment existing skills with optional capabilities. Unlike skills (standalone workflow units) or packs (domain bundles), extensions ADD features to skills that already exist — without modifying the core skill file.
+
+#### Extension vs Skill vs Pack
+
+| Concept | Purpose | Modifies Core? | Self-contained? |
+|---------|---------|----------------|-----------------|
+| **Skill** | Standalone workflow unit (SKILL.md) | N/A — IS core | Yes |
+| **Pack** | Domain bundle of skills (PACK.md) | No — bundles existing | Yes |
+| **Extension** | Augments existing skill with new capability | No — additive only | Yes — own dir with install/uninstall |
+
+#### Extension Directory Structure
+
+```
+extensions/<extension-name>/
+├── EXTENSION.md           # Manifest: what it extends, how, dependencies
+├── install.sh             # Unix installer (non-destructive MCP merge)
+├── install.ps1            # Windows installer
+├── uninstall.sh           # Clean removal
+├── uninstall.ps1          # Clean removal (Windows)
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md       # New skill added by extension
+├── agents/                # Optional subagent definitions
+│   └── <agent-name>.md
+├── references/            # Domain knowledge loaded by extension skills
+│   └── <topic>.md
+├── scripts/               # Executable utilities
+│   └── <script>.py|.sh
+└── docs/
+    └── SETUP.md           # Extension-specific configuration guide
+```
+
+#### EXTENSION.md Manifest
+
+```yaml
+---
+name: "<extension-name>"
+extends: "<target-skill-or-pack>"
+description: "What capability this extension adds"
+requires:
+  - mcp: "<mcp-server-name>"        # Optional: MCP server dependency
+  - skill: "<required-skill-name>"   # Required core skill
+install_method: "non-destructive"    # MUST be non-destructive
+---
+```
+
+#### Extension Rules
+
+1. **Non-destructive install** — extension MUST NOT modify existing skill files. It adds new files alongside.
+2. **Self-contained** — removing the extension directory restores the system to its pre-install state.
+3. **MCP merge** — if the extension adds MCP tools, install script MUST merge into settings.json without overwriting existing entries.
+4. **Fallback graceful** — if the MCP server or external dependency is unavailable, the extension skill MUST degrade gracefully (report unavailability, don't crash).
+5. **Cost awareness** — if the extension calls paid APIs, the extension skill MUST warn before expensive operations and track usage.
+6. **Pre-flight check** — extension skill Step 1 MUST verify dependencies are available before executing.
+
+#### When to Build an Extension (vs a Skill or Pack)
+
+- Build an **extension** when: the capability requires an external API/MCP, is optional, and augments an existing skill
+- Build a **skill** when: the capability is self-contained and fits a layer in the mesh
+- Build a **pack** when: you're bundling multiple related skills for a domain
 
 ### Phase 7 — SHIP
 
@@ -302,6 +369,8 @@ git commit -m "feat: add [skill-name] — [one-line purpose]"
 - [ ] At least one observed failure documented
 - [ ] Anti-rationalization table from real test failures
 - [ ] Mesh connections bidirectional (calls AND called-by both updated)
+- [ ] Data flow mapped (Feeds Into / Fed By / Feedback Loops)
+- [ ] Self-Validation has 3-5 domain-specific checks (not generic)
 - [ ] Output format is structured and parseable by other skills
 
 **Architecture:**
@@ -311,6 +380,14 @@ git commit -m "feat: add [skill-name] — [one-line purpose]"
 - [ ] ARCHITECTURE.md updated
 - [ ] CLAUDE.md updated
 
+**Extension-specific (if building an extension):**
+- [ ] EXTENSION.md manifest present with extends, requires, install_method
+- [ ] install.sh + install.ps1 tested (non-destructive merge)
+- [ ] uninstall.sh + uninstall.ps1 tested (clean removal)
+- [ ] Extension skill has dependency pre-flight check (Step 1)
+- [ ] Fallback behavior documented when external dependency unavailable
+- [ ] Cost warning present if extension calls paid APIs
+
 ## Adapting Existing Skills
 
 When editing, not creating:
@@ -368,6 +445,8 @@ Techniques:
 ### Mesh Impact
 - New connections: [count] ([list of skills])
 - Bidirectional check: PASS | FAIL
+- Data flow mapped: [count] feeds-into, [count] fed-by, [count] feedback loops
+- Self-Validation: [count] domain-specific checks written
 ```
 
 ## Constraints
@@ -393,6 +472,9 @@ Techniques:
 | Code blocks in SKILL.md bloat every invocation | HIGH | WHY vs HOW split: SKILL.md ≤10-line code blocks, extract rest to references/ |
 | Writing skill without TDD (no observed failures first) | CRITICAL | Skill TDD: RED (run scenario WITHOUT skill → document failures) → GREEN (write skill targeting failures) → REFACTOR (find bypasses → add blocks) |
 | Description leaks workflow → agent skips full content | HIGH | CSO Discipline: description = triggers only. Test: can you execute from description alone? If yes, it leaks too much |
+| Self-Validation copies completion-gate checks | HIGH | Self-Validation is DOMAIN-specific: "assertions per test", "dependency ordering". NOT generic: "tests pass", "build succeeds" — those belong to completion-gate |
+| Data Flow confused with Calls | MEDIUM | Calls = runtime invocation (skill A calls skill B). Feeds Into = artifact persistence (skill A writes .rune/X.md, skill B reads it later). If it's a direct function call → Calls. If it's via files/context → Data Flow |
+| Feedback Loop missing one direction | MEDIUM | Every Feedback Loop ↻ must document BOTH directions: what A sends to B AND what B sends back to A. One-way = Feeds Into, not a loop |
 
 ## Done When
 

package/skills/team/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.5.0"
   layer: L1
   model: opus
   group: orchestrator
@@ -152,7 +152,11 @@ Mark todo[1] `in_progress`.
 
 **2a. Launch parallel streams.**
 
-Launch independent streams (depends_on: []) in parallel using Task tool with worktree isolation:
+Launch independent streams (depends_on: []) in parallel using Task tool with worktree isolation.
+
+> From agency-agents (msitarzewski/agency-agents, 50.8k★): "Structured handoff docs prevent the #1 multi-agent failure: context loss between agents."
+
+Each stream receives a **NEXUS Handoff Template** — not a bare prompt:
 
 ```
 For each stream where depends_on == []:
@@ -160,22 +164,54 @@ For each stream where depends_on == []:
     subagent_type: "general-purpose",
     model: "sonnet",
     isolation: "worktree",
-    prompt: "Cook task: [stream.task]. Files in scope: [stream.files]. Return cook report on completion."
+    prompt: <NEXUS Handoff below>
   )
 ```
 
+**NEXUS Handoff Template** (sent to each cook instance):
+
+```markdown
+## NEXUS Handoff: Stream [id]
+
+### Metadata
+- Stream: [id] of [total]
+- Depends on: [none | stream ids]
+- File ownership: [list — ONLY these files may be modified]
+- Model: sonnet
+
+### Context
+- Project: [project name and type]
+- Overall goal: [1-line feature description]
+- This stream's goal: [specific sub-task]
+- Conventions: [key patterns from scout — naming, file structure, test framework]
+
+### Deliverable
+- [ ] [specific outcome 1 — e.g., "AuthService with login/register/reset methods"]
+- [ ] [specific outcome 2 — e.g., "Unit tests covering happy path + 3 error cases"]
+- [ ] [specific outcome 3 — e.g., "Types exported for Phase 2 consumers"]
+
+### Quality Expectations
+- Tests: must pass with evidence (stdout captured)
+- Types: no `any`, strict mode
+- Security: no hardcoded secrets, parameterized queries
+- Conventions: [project-specific — from scout output]
+
+### Evidence Required
+Return a Cook Report with:
+- Exact files modified (git diff --stat)
+- Test output (stdout — not just "tests pass")
+- Any CONCERNS discovered during implementation
+```
+
 **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."
-  )
+  Then launch with NEXUS Handoff that includes:
+  - Completed stream's deliverables as "Available Context"
+  - Exported interfaces/types from prior streams in "Code Contracts" section
+  - Any CONCERNS from prior streams in "Known Issues" section
 ```
 
 **2b.5. Pre-merge scope verification.**
@@ -367,16 +403,24 @@ Mark todo[4] `completed`.
 - **Duration**: [time across streams]
 
 ### Streams
-| Stream | Task | Status | Cook Report |
-|--------|------|--------|-------------|
-| A | [task] | complete | [summary] |
-| B | [task] | complete | [summary] |
-| C | [task] | complete | [summary] |
+| Stream | Task | Status | Deliverables | Concerns |
+|--------|------|--------|-------------|----------|
+| A | [task] | DONE | 3/3 delivered | None |
+| B | [task] | DONE_WITH_CONCERNS | 2/2 delivered | Perf regression on large input |
+| C | [task] | DONE | 2/2 delivered | None |
+
+### Acceptance Criteria
+| # | Criterion | Stream | Evidence | Verdict |
+|---|-----------|--------|----------|---------|
+| 1 | Auth endpoints return JWT | A | Test stdout: "3 passed" | PASS |
+| 2 | No SQL injection | A | Sentinel: PASS | PASS |
+| 3 | Dashboard loads < 2s | B | No perf test run | UNVERIFIED |
 
 ### Integration
 - Merge conflicts: [count]
 - Integration tests: [passed]/[total]
 - Coverage: [%]
+- Unresolved concerns: [count — from DONE_WITH_CONCERNS streams]
 ```
 
 ---
@@ -405,6 +449,8 @@ Known failure modes for this skill. Check these before declaring done.
 | 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 |
+| Bare prompt to cook instance — no context, conventions, or scope boundary | HIGH | NEXUS Handoff Template: structured handoff with metadata, deliverables, quality expectations, and evidence requirements |
+| Cook returns "done" with no acceptance criteria tracking | MEDIUM | Team Report includes Acceptance Criteria table with per-criterion evidence and PASS/FAIL/UNVERIFIED verdict |
 
 ## Done When
 

package/skills/test/SKILL.md

@@ -3,7 +3,7 @@ name: test
 description: "TDD test writer. Writes failing tests FIRST (red), then verifies they pass after implementation (green). Covers unit, integration, and e2e tests."
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.7.0"
   layer: L2
   model: sonnet
   group: development
@@ -168,15 +168,79 @@ Input:  git diff main --name-only
 Output: Prioritized test plan targeting only affected paths
 ```
 
-## Test Types
+## Test Types — 4-Layer Methodology
 
-| Type | When | Framework | Speed |
-|------|------|-----------|-------|
-| Unit | Individual functions, pure logic | jest/vitest/pytest/cargo test | Fast |
-| Integration | API endpoints, DB operations | supertest/httpx/reqwest | Medium |
-| E2E | Critical user flows | Playwright/Cypress via browser-pilot | Slow |
-| Regression | After bug fixes | Same as unit | Fast |
-| Diff-aware | After implementation, large codebases | Same as unit + integration | Fast (targeted) |
+Tests are organized in 4 layers. Each layer catches a different failure class. Higher layers are slower but catch integration issues lower layers miss.
+
+| Layer | Type | What It Catches | Framework | Speed |
+|-------|------|-----------------|-----------|-------|
+| L1 | **Unit** | Logic bugs, boundary violations, pure function errors | jest/vitest/pytest/cargo test | Fast |
+| L2 | **Integration** | API contract breaks, DB query errors, service interaction failures | supertest/httpx/reqwest | Medium |
+| L3 | **True Backend** | Real tool/service output correctness (not just exit 0) | Same + real software invocation | Medium-Slow |
+| L4 | **E2E / Subprocess** | Full workflow from user/agent perspective, installed app works | Playwright/Cypress/subprocess | Slow |
+
+**Layer rules:**
+- **L1 (Unit)**: Synthetic data, no external deps. Every function tested in isolation. Fast, deterministic, CI-friendly
+- **L2 (Integration)**: Tests service boundaries — API endpoints, DB operations, message queues. May need test DB or mock server
+- **L3 (True Backend)**: **Invokes the REAL tool/service** and verifies output programmatically. No graceful degradation — if the dependency isn't installed, tests FAIL (not skip). Verify: magic bytes, file size > 0, content structure. Print artifact paths for manual inspection
+- **L4 (E2E/Subprocess)**: Tests the installed command/app via subprocess or browser automation. Full user workflow: input → process → output → verify
+
+**"No graceful degradation" rule** (L3/L4): Hard dependencies MUST be installed. Tests MUST NOT skip or produce fake results when the dependency is missing. A silently skipping test is worse than a loudly failing test.
+
+Additional modes:
+
+| Type | When | Speed |
+|------|------|-------|
+| Regression | After bug fixes | Fast |
+| Diff-aware | After implementation, large codebases (Phase 6.5) | Fast (targeted) |
+
+## TEST.md — Test Plan + Results Document
+
+For non-trivial features (3+ test files or 20+ test cases), create a `TEST.md` in the test directory. This is BOTH a planning doc (written BEFORE tests) and results doc (appended AFTER tests pass).
+
+### Before writing tests — write the plan:
+```markdown
+# Test Plan: [Feature Name]
+
+## Test Inventory
+- `test_core.py`: ~XX unit tests planned (L1)
+- `test_integration.py`: ~XX integration tests planned (L2)
+- `test_e2e.py`: ~XX E2E tests planned (L3/L4)
+
+## Unit Test Plan (L1)
+| Module | Functions | Edge Cases | Est. Tests | Req IDs |
+|--------|-----------|------------|------------|---------|
+| `core/auth.py` | login, register, refresh | expired token, invalid creds, rate limit | 12 | REQ-001, REQ-003 |
+
+## E2E Scenarios (L3/L4)
+| Workflow | Simulates | Operations | Verified | Req IDs |
+|----------|-----------|------------|----------|---------|
+| User signup | New user onboarding | register → verify → login | Token valid, profile created | REQ-005 |
+
+## Realistic Workflow Scenarios
+- **[Name]**: [Step 1] → [Step 2] → verify [output properties]
+```
+
+### After tests pass — append results:
+```markdown
+## Test Results
+[Paste full `pytest -v --tb=no` or `npm test` output]
+
+## Summary
+- Total: XX | Passed: XX | Failed: 0
+- Execution time: X.Xs | Coverage: XX%
+
+## Requirement Coverage
+| Req ID | Test File(s) | Status |
+|--------|-------------|--------|
+| REQ-001 | `test_auth.py::test_login` | ✅ Covered |
+| REQ-002 | — | ❌ Not covered |
+
+## Gaps
+- [Areas not covered and why]
+```
+
+**Why TEST.md**: Planning tests before code catches missing edge cases early. Appending results creates permanent evidence. One document = complete testing story.
 
 ## Error Recovery
 
@@ -203,6 +267,25 @@ Output: Prioritized test plan targeting only affected paths
 - `browser-pilot` (L3): Phase 4 — e2e and visual testing for UI flows
 - `debug` (L2): Phase 5 — when existing test regresses unexpectedly
 
+## Data Flow
+
+### Feeds Into →
+
+- `cook` (L1): test results (pass/fail/coverage) → cook's Phase 5 quality gate evidence
+- `completion-gate` (L3): test runner stdout → evidence for "tests pass" claims
+- `fix` (L2): failing test output → fix's target (what to make green)
+
+### Fed By ←
+
+- `plan` (L2): phase file test tasks → test's RED phase targets (what to test)
+- `review` (L2): untested edge cases found during review → new test targets
+- `fix` (L2): implemented code → test's GREEN phase verification target
+
+### Feedback Loops ↻
+
+- `test` ↔ `fix`: test writes failing tests (RED) → fix implements to pass → test verifies (GREEN) → if new failures emerge, loop continues
+- `test` ↔ `debug`: test discovers regression → debug diagnoses root cause → test writes regression test to prevent recurrence
+
 ## Anti-Rationalization Table
 
 | Excuse | Reality |
@@ -317,6 +400,18 @@ Known failure modes for this skill. Check these before declaring done.
 | Modifying source files to make tests work | HIGH | Role boundary: test writes test files ONLY — source changes go to rune:fix |
 | Test-only methods leaking into production code | MEDIUM | Anti-Pattern 2 gate: if method only called by tests → move to test utilities |
 
+## Self-Validation
+
+```
+SELF-VALIDATION (run before emitting Test Report):
+- [ ] Every test file has at least one assertion — no empty test bodies
+- [ ] RED phase output shows actual failures (not "0 tests") — tests were real, not stubs
+- [ ] No test modifies source code — test files only, source changes belong to fix
+- [ ] Test names describe behavior, not implementation ("should reject expired token" not "test function X")
+- [ ] No mocks of the thing being tested — only mock external dependencies
+- [ ] If BA requirements exist (REQ-xxx), every requirement has at least one test — check plan's Traceability Matrix
+```
+
 ## Done When
 
 - Test framework detected from project config files
@@ -325,6 +420,7 @@ Known failure modes for this skill. Check these before declaring done.
 - After implementation: all tests PASS (GREEN phase — actual pass output shown)
 - Coverage ≥80% verified via verification
 - Test Report emitted with framework, test count, RED/GREEN status, and coverage
+- Self-Validation: all checks passed
 
 ## Cost Profile
 

package/skills/verification/SKILL.md

@@ -3,7 +3,7 @@ name: verification
 description: "Universal verification runner. Runs lint, type-check, tests, and build. Use after any code change to verify nothing is broken."
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.5.0"
   layer: L3
   model: haiku
   group: validation
@@ -233,6 +233,33 @@ Overall:   [PASS/FAIL]
 - Unwired: [files that failed Level 3 with 0 consumers]
 ```
 
+## Output Completion Enforcement
+
+> From taste-skill (Leonxlnx/taste-skill, 3.4k★): Truncated code is worse than no code — it passes reviews but breaks at runtime.
+
+When verifying code files (Level 2 SUBSTANTIVE check), also scan for **truncation patterns** — signs that the agent generated partial output and stopped:
+
+| Banned Pattern | Language | What It Means |
+|---|---|---|
+| `// ...` or `/* ... */` as a statement | JS/TS | Agent truncated remaining code |
+| `# ...` as a statement (not comment) | Python | Agent truncated |
+| `// rest of code` / `// remaining implementation` | Any | Explicit truncation admission |
+| `// TODO: implement` as sole function body | Any | Placeholder, not implementation |
+| `{ /* same as above */ }` | JS/TS | Copy-paste truncation |
+| `...` (bare ellipsis, not spread operator) | JS/TS/Python | Truncation marker |
+| `[PAUSED]` / `[CONTINUED]` in source | Any | Agent session marker leaked into code |
+
+**Action on detection:**
+- Mark file as TRUNCATED (distinct from STUB) in Verification Report
+- TRUNCATED files are Level 2 FAIL — they CANNOT pass verification
+- Report the specific line number and pattern detected
+- If agent claims "done" with truncated files → REJECTED by Evidence-Before-Claims gate
+
+**Continuation protocol** — if the agent hit output limits mid-file:
+- Agent MUST log: `[PAUSED — X of Y functions complete]` in its response (NOT in the code file)
+- Agent MUST resume and complete the file in the next turn
+- Verification re-runs after completion to clear the TRUNCATED flag
+
 ## Evidence-Before-Claims Gate
 
 <HARD-GATE>
@@ -284,6 +311,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Trusting exit code 0 without output verification | CRITICAL | Artifact Verification HARD-GATE: always confirm success indicator in stdout (pass count, "0 errors", output file exists) |
 | Existence Theater — file exists but is a stub | HIGH | 3-Level check: Level 2 scans for stub patterns (`<div>Placeholder</div>`, `return null`, `NotImplementedError`) |
 | Dead code — file created but never imported/used | MEDIUM | 3-Level check: Level 3 greps for consumers. 0 importers = UNWIRED |
+| Truncated code — agent hit output limit mid-file | HIGH | Output Completion Enforcement: scan for `// ...`, `// rest of code`, bare ellipsis patterns. TRUNCATED = Level 2 FAIL |
 
 ## Done When