@rune-kit/rune 2.2.6 → 2.3.1

package/skills/plan/references/completeness-scoring.md

@@ -0,0 +1,36 @@
+# Completeness Scoring
+
+> Reference for `plan` skill — Step 5.5.
+> Load this when presenting alternative approaches from brainstorm or Step 3 decisions.
+
+## Scoring Table
+
+When presenting alternatives, rate each with **Completeness X/10**:
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | Complete — all edge cases, full coverage, production-ready |
+| 7-8 | Happy path covered, some edges skipped |
+| 4-6 | Shortcut — defers significant work |
+| 1-3 | Minimal viable, debt guaranteed |
+
+## Rules
+
+- **Always recommend the higher-completeness option.** With AI-assisted coding, the marginal cost of completeness is near-zero.
+- Show **dual effort estimates** for each approach: `(human: ~X / AI: ~Y)`
+- **Anti-pattern**: "Option B saves 70 LOC" → 70 LOC delta is meaningless with AI. Choose complete. The last 10% of coverage is where production bugs hide.
+
+
+## Example Format
+
+```
+**Option A: Full validation with Zod** — Completeness 9/10
+- Covers: schema validation, error messages, type inference
+- human: ~2h / AI: ~15min
+- Recommended ✅
+
+**Option B: Manual checks** — Completeness 5/10
+- Covers: happy path only, defers edge cases
+- human: ~30min / AI: ~5min
+- Not recommended — defers 40% of error handling
+```

package/skills/plan/references/outcome-block.md

@@ -0,0 +1,40 @@
+# Outcome Block Format
+
+> Reference for `plan` skill — mandatory output section for all plan outputs.
+> Load this when writing the final section of any master plan, phase file, or inline plan.
+
+## Format
+
+Every plan output MUST end with an **Outcome Block**:
+
+```markdown
+## Outcome Block
+
+### What Was Planned
+<1-2 sentences: what this plan delivers when all phases execute successfully>
+
+### Immediate Next Action
+<The SINGLE next action the executor should take right now — not a list, one action>
+Example: "Load phase 1 file and execute Wave 1 tasks (create types, validation schema)"
+
+### How to Measure Success
+| Metric | Target | How to Check |
+|--------|--------|-------------|
+| Tests pass | 100% green | `npm test` or `pytest -v` |
+| Type errors | 0 | `tsc --noEmit` or `mypy` |
+| Phase complete | All tasks ✅ | phase file task list |
+| <domain metric> | <value> | <command> |
+```
+
+## Rules
+
+1. Outcome Block is the LAST section in every plan output (master plan, phase file, inline plan)
+2. "Immediate Next Action" = ONE action, present tense, imperative mood. Not a list.
+3. "How to Measure" table MUST include at least one verifiable shell command
+4. For phase files: Immediate Next Action = "Execute Wave 1: [list Wave 1 task names]"
+5. For master plans: Immediate Next Action = "Await approval, then load phase 1 file"
+
+## Why This Matters
+
+Plans without a clear "what to do NOW" cause executor drift — agents re-read the plan, re-analyze, and pick arbitrary starting points. The Immediate Next Action eliminates ambiguity: there is exactly ONE right first move.
+

package/skills/plan/references/plan-templates.md

@@ -0,0 +1,193 @@
+# Plan Templates
+
+> Reference for `plan` skill — Steps 4 and 5.
+> Load this when writing master plan files or phase files.
+
+## Master Plan Template
+
+Save to `.rune/plan-<feature>.md`. Max 80 lines.
+
+```markdown
+# Feature: <name>
+
+## Overview
+<1-3 sentences: what and why>
+
+## Phases
+| # | Name | Status | Plan File | Summary |
+|---|------|--------|-----------|---------|
+| 1 | Foundation | ⬚ Pending | plan-X-phase1.md | Types, core engine, basic UI |
+| 2 | Interaction | ⬚ Pending | plan-X-phase2.md | Dialogue, combat, items |
+| 3 | Polish | ⬚ Pending | plan-X-phase3.md | Effects, sounds, game over |
+
+## Key Decisions
+- <decision 1 — chosen approach and why>
+- <decision 2>
+
+## Decision Compliance
+- Decisions (locked): [list from requirements.md — plan MUST honor these]
+- Discretion (agent): [list — agent chose X because Y]
+- Deferred: [list — explicitly excluded from this feature]
+
+## Architecture
+<brief system diagram or component list — NOT implementation detail>
+
+## Dependencies
+- <external dep>: <status>
+
+## Risks
+- <risk>: <mitigation>
+```
+
+No implementation details — that's what phase files are for.
+
+---
+
+## Phase File Template (Amateur-Proof)
+
+Save to `.rune/plan-<feature>-phase<N>.md`. Max 200 lines.
+
+Phase files follow the **Amateur-Proof Template** — designed so that even the weakest model (Haiku) can execute without guessing. Every section exists because an Amateur said "I need this to code correctly."
+
+```markdown
+# Phase N: <name>
+
+## Goal
+<What this phase delivers — 1-2 sentences>
+
+## Data Flow
+<5-line ASCII diagram showing how data moves through this phase's components>
+```
+User Input → validateInput() → calculateProfit() → formatResult() → API Response
+                                      ↓
+                                 TradeEntry[]
+```
+
+## Code Contracts
+<Function signatures, interfaces, schemas that this phase MUST implement>
+<This is the MOST IMPORTANT section — coder implements these contracts>
+
+```typescript
+interface TradeEntry {
+  side: 'long' | 'short';
+  entryPrice: number;
+  exitPrice: number;
+  quantity: number;
+}
+
+interface ProfitResult {
+  netPnL: number;
+  totalFees: number;
+  winRate: number;
+}
+
+function calculateProfit(entries: TradeEntry[]): ProfitResult;
+function validateInput(raw: unknown): TradeEntry[];  // throws ValidationError
+```
+
+## Tasks
+
+Each task MUST include: **File** (exact path), **Test** (test file or N/A), **Verify** (shell command), **Commit** (semantic message). Granularity: 2-5 min per task. If >10min, decompose.
+
+- [ ] Task 1 — Create calculateProfit function
+  - Req: REQ-001 (P&L calculation)
+  - File: `src/foo/bar.ts` (new)
+  - Test: `tests/foo/bar.test.ts` (new)
+  - Verify: `npm test -- --grep "calculateProfit"`
+  - Commit: `feat(trading): add calculateProfit with fee calculation`
+  - Logic: sum entries by side, apply fees (0.1% per trade), return net P&L
+  - Edge: empty array → return { netPnL: 0, totalFees: 0, winRate: 0 }
+- [ ] Task 2 — Add input validation
+  - Req: REQ-002 (input validation)
+  - File: `src/foo/baz.ts` (modify)
+  - Test: `tests/foo/baz.test.ts` (new)
+  - Verify: `npm test -- --grep "validateInput"`
+  - Commit: `feat(trading): add input validation for trade entries`
+  - Logic: check side is 'long'|'short', prices > 0, quantity > 0
+- [ ] Task 3 — Write integration tests
+  - Req: REQ-001, REQ-002 (integration coverage)
+  - File: `tests/foo/bar.test.ts` (modify)
+  - Test: N/A — this IS the test task
+  - Verify: `npm test -- --grep "trading" && npx tsc --noEmit`
+  - Commit: `test(trading): add integration tests for edge cases`
+  - Cases: happy path, empty input, negative values, overflow
+
+## Failure Scenarios
+<What should happen when things go wrong — coder MUST implement these>
+
+| When | Then | Error Type |
+|------|------|-----------|
+| entries is empty array | return zero-value ProfitResult | No error (valid edge case) |
+| entry has negative price | throw ValidationError("price must be positive") | ValidationError |
+| entry has quantity = 0 | throw ValidationError("quantity must be > 0") | ValidationError |
+| calculation overflows Number.MAX_SAFE_INTEGER | use BigInt or throw OverflowError | OverflowError |
+
+## Performance Constraints
+<Non-functional requirements — skip if not applicable>
+
+| Metric | Requirement | Why |
+|--------|-------------|-----|
+| Input size | Must handle 10,000 entries | Production data volume |
+| Response time | < 100ms for 10K entries | Real-time dashboard |
+| Memory | < 50MB for 10K entries | Container memory limit |
+
+## Rejection Criteria (DO NOT)
+<Anti-patterns the coder MUST avoid — things that seem right but are wrong>
+
+- ❌ DO NOT use `toFixed()` for financial calculations — use Decimal.js or integer cents
+- ❌ DO NOT mutate the input array — create new objects (immutability rule)
+- ❌ DO NOT use `any` type — full TypeScript strict
+- ❌ DO NOT import from Phase 2+ files — this phase is self-contained
+
+## Cross-Phase Context
+<What this phase assumes from previous phases / what future phases expect from this one>
+
+- **Assumes**: Phase 1 created `src/shared/types.ts` with base types
+- **Exports for Phase 3**: `calculateProfit()` will be imported by `src/dashboard/PnLCard.tsx`
+- **Interface contract**: ProfitResult shape MUST NOT change — Phase 3 depends on it
+
+## Acceptance Criteria
+- [ ] All tasks marked done
+- [ ] Tests pass with 80%+ coverage on new code
+- [ ] No TypeScript errors (`tsc --noEmit` passes)
+- [ ] Failure scenarios all handled (table above)
+- [ ] Performance: calculateProfit(10K entries) < 100ms
+- [ ] No `any` types, no mutation, no `toFixed()` for money
+
+## Traceability Matrix
+| Req ID | Requirement | Task(s) | Test(s) | Status |
+|--------|-------------|---------|---------|--------|
+| REQ-001 | P&L calculation with fees | Task 1 | `tests/foo/bar.test.ts` | ⬚ |
+| REQ-002 | Input validation | Task 2 | `tests/foo/baz.test.ts` | ⬚ |
+
+Every requirement from BA's Requirements Document MUST appear in this matrix. Missing requirement = incomplete phase. `completion-gate` checks this matrix during verification.
+
+## Files Touched
+- `src/foo/bar.ts` — new
+- `src/foo/baz.ts` — modify
+- `tests/foo/bar.test.ts` — new
+```
+
+Must be self-contained — coder should NOT need to read master plan or other phases to execute.
+
+---
+
+## Inline Plan Template (Trivial Tasks)
+
+For trivial tasks (1-2 phases, < 5 files, < 100 LOC):
+
+```
+## Plan: [Task Name]
+
+### Changes
+1. [file]: [what to change] — [function signature]
+2. [file]: [what to change]
+
+### Tests
+- [test file]: [test cases]
+
+### Risks
+- [risk]: [mitigation]
+
+Awaiting approval.
+```

package/skills/plan/references/wave-planning.md

@@ -0,0 +1,44 @@
+# Wave-Based Task Grouping
+
+> Reference for `plan` skill — Step 3 (Decompose into Phases).
+> Load this when writing wave-structured task lists inside a phase.
+
+## Wave Format
+
+Tasks inside a phase MUST be organized into **waves** based on dependency analysis. Independent tasks within the same wave can execute in parallel.
+
+```
+## Tasks
+
+### Wave 1 (parallel — no dependencies)
+- [ ] Task 1 — Create types/interfaces
+  - File: `src/types.ts` (new)
+  - ...
+- [ ] Task 2 — Create validation schema
+  - File: `src/validation.ts` (new)
+  - ...
+
+### Wave 2 (depends on Wave 1)
+- [ ] Task 3 — Implement core logic (imports types from Task 1)
+  - File: `src/core.ts` (new)
+  - depends_on: [Task 1]
+  - ...
+
+### Wave 3 (depends on Wave 2)
+- [ ] Task 4 — Wire into API endpoint (imports core from Task 3)
+  - File: `src/routes/api.ts` (modify)
+  - depends_on: [Task 3]
+  - ...
+- [ ] Task 5 — Write integration tests (tests core from Task 3)
+  - File: `tests/core.test.ts` (new)
+  - depends_on: [Task 3]
+  - ...
+```
+
+## Wave Rules
+
+- **Wave 1** = tasks with zero dependencies (types, schemas, configs) — always first
+- **Subsequent waves**: a task goes in the earliest wave where ALL its `depends_on` tasks are in prior waves
+- Tasks within the same wave have NO dependencies on each other → safe for parallel dispatch
+- `depends_on` field is MANDATORY for Wave 2+ tasks — explicit is better than implicit
+- `team` orchestrator can dispatch wave tasks as parallel subagents; solo `cook` executes sequentially within a wave but respects wave ordering

package/skills/plan/references/workflow-registry.md

@@ -0,0 +1,52 @@
+# Workflow Registry (4-View)
+
+> Reference for `plan` skill — Step 4.5.
+> Load this when building a Workflow Registry for complex features (4+ phases OR 3+ user-facing workflows).
+
+## When to Use
+
+Build this registry BEFORE writing phase files for complex features. It catches missing pieces, dead ends, and integration gaps at plan time — not implementation time.
+
+**Skip conditions**: trivial tasks, inline plans, single-workflow features.
+
+
+## 4-View Format
+
+```markdown
+## Workflow Registry
+
+### View 1: By Workflow
+| Workflow | Entry Point | Components Touched | Exit Point | Phase |
+|----------|-------------|-------------------|------------|-------|
+| User signup | POST /auth/register | AuthService, UserRepo, EmailService | 201 + email sent | Phase 1 |
+| Password reset | POST /auth/reset | AuthService, EmailService, TokenRepo | 200 + reset email | Phase 2 |
+
+### View 2: By Component
+| Component | Used By Workflows | Owner Phase | Status |
+|-----------|-------------------|-------------|--------|
+| AuthService | signup, login, reset | Phase 1 | Planned |
+| EmailService | signup, reset, invite | Phase 2 | Planned |
+| TokenRepo | reset, invite | Phase 2 | Missing ← RED FLAG |
+
+### View 3: By User Journey
+| Journey | Steps (workflow chain) | Happy Path | Error Path |
+|---------|----------------------|------------|------------|
+| New user → first action | signup → verify email → login → onboard | 4 steps | signup fail, email bounce |
+
+### View 4: By State
+| Step | User Sees | DB State | Logs | Operator Sees |
+|------|-----------|----------|------|---------------|
+| After signup | "Check your email" | user.status=pending | user.created event | New user in admin |
+| After verify | Dashboard | user.status=active | user.verified event | Active user count +1 |
+```
+
+## Validation Rules
+
+- Every component in View 2 MUST appear in at least one workflow in View 1 — orphaned components = dead code
+- Every workflow in View 1 MUST map to a phase — unphased workflows will be forgotten
+- **"Missing" status in View 2 = red flag** — component needed but not planned in any phase → add to a phase or create new phase
+- Every user journey step in View 3 MUST have a corresponding state row in View 4
+
+## Output Placement
+
+Add the registry to the master plan file (it fits within the 80-line budget when tables are compact). Phase files reference it but don't duplicate it.