kodelyth-ecc 2.18.0 → 2.19.0

package/.roo/skills/cost-aware-llm-pipeline/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: cost-aware-llm-pipeline
+description: Cost optimization patterns for LLM API usage — model routing by task complexity, budget tracking, retry logic, and prompt caching.
+origin: ECC
+---
+
+# Cost-Aware LLM Pipeline
+
+Patterns for controlling LLM API costs while maintaining quality. Combines model routing, budget tracking, retry logic, and prompt caching into a composable pipeline.
+
+## When to Activate
+
+- Building applications that call LLM APIs (Claude, GPT, etc.)
+- Processing batches of items with varying complexity
+- Need to stay within a budget for API spend
+- Optimizing cost without sacrificing quality on complex tasks
+
+## Core Concepts
+
+### 1. Model Routing by Task Complexity
+
+Automatically select cheaper models for simple tasks, reserving expensive models for complex ones.
+
+```python
+MODEL_SONNET = "claude-sonnet-4-6"
+MODEL_HAIKU = "claude-haiku-4-5-20251001"
+
+_SONNET_TEXT_THRESHOLD = 10_000  # chars
+_SONNET_ITEM_THRESHOLD = 30     # items
+
+def select_model(
+    text_length: int,
+    item_count: int,
+    force_model: str | None = None,
+) -> str:
+    """Select model based on task complexity."""
+    if force_model is not None:
+        return force_model
+    if text_length >= _SONNET_TEXT_THRESHOLD or item_count >= _SONNET_ITEM_THRESHOLD:
+        return MODEL_SONNET  # Complex task
+    return MODEL_HAIKU  # Simple task (3-4x cheaper)
+```
+
+### 2. Immutable Cost Tracking
+
+Track cumulative spend with frozen dataclasses. Each API call returns a new tracker — never mutates state.
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class CostRecord:
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float
+
+@dataclass(frozen=True, slots=True)
+class CostTracker:
+    budget_limit: float = 1.00
+    records: tuple[CostRecord, ...] = ()
+
+    def add(self, record: CostRecord) -> "CostTracker":
+        """Return new tracker with added record (never mutates self)."""
+        return CostTracker(
+            budget_limit=self.budget_limit,
+            records=(*self.records, record),
+        )
+
+    @property
+    def total_cost(self) -> float:
+        return sum(r.cost_usd for r in self.records)
+
+    @property
+    def over_budget(self) -> bool:
+        return self.total_cost > self.budget_limit
+```
+
+### 3. Narrow Retry Logic
+
+Retry only on transient errors. Fail fast on authentication or bad request errors.
+
+```python
+from anthropic import (
+    APIConnectionError,
+    InternalServerError,
+    RateLimitError,
+)
+
+_RETRYABLE_ERRORS = (APIConnectionError, RateLimitError, InternalServerError)
+_MAX_RETRIES = 3
+
+def call_with_retry(func, *, max_retries: int = _MAX_RETRIES):
+    """Retry only on transient errors, fail fast on others."""
+    for attempt in range(max_retries):
+        try:
+            return func()
+        except _RETRYABLE_ERRORS:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(2 ** attempt)  # Exponential backoff
+    # AuthenticationError, BadRequestError etc. → raise immediately
+```
+
+### 4. Prompt Caching
+
+Cache long system prompts to avoid resending them on every request.
+
+```python
+messages = [
+    {
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": system_prompt,
+                "cache_control": {"type": "ephemeral"},  # Cache this
+            },
+            {
+                "type": "text",
+                "text": user_input,  # Variable part
+            },
+        ],
+    }
+]
+```
+
+## Composition
+
+Combine all four techniques in a single pipeline function:
+
+```python
+def process(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
+    # 1. Route model
+    model = select_model(len(text), estimated_items, config.force_model)
+
+    # 2. Check budget
+    if tracker.over_budget:
+        raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)
+
+    # 3. Call with retry + caching
+    response = call_with_retry(lambda: client.messages.create(
+        model=model,
+        messages=build_cached_messages(system_prompt, text),
+    ))
+
+    # 4. Track cost (immutable)
+    record = CostRecord(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
+    tracker = tracker.add(record)
+
+    return parse_result(response), tracker
+```
+
+## Pricing Reference (2025-2026)
+
+| Model | Input ($/1M tokens) | Output ($/1M tokens) | Relative Cost |
+|-------|---------------------|----------------------|---------------|
+| Haiku 4.5 | $0.80 | $4.00 | 1x |
+| Sonnet 4.6 | $3.00 | $15.00 | ~4x |
+| Opus 4.5 | $15.00 | $75.00 | ~19x |
+
+## Best Practices
+
+- **Start with the cheapest model** and only route to expensive models when complexity thresholds are met
+- **Set explicit budget limits** before processing batches — fail early rather than overspend
+- **Log model selection decisions** so you can tune thresholds based on real data
+- **Use prompt caching** for system prompts over 1024 tokens — saves both cost and latency
+- **Never retry on authentication or validation errors** — only transient failures (network, rate limit, server error)
+
+## Anti-Patterns to Avoid
+
+- Using the most expensive model for all requests regardless of complexity
+- Retrying on all errors (wastes budget on permanent failures)
+- Mutating cost tracking state (makes debugging and auditing difficult)
+- Hardcoding model names throughout the codebase (use constants or config)
+- Ignoring prompt caching for repetitive system prompts
+
+## When to Use
+
+- Any application calling Claude, OpenAI, or similar LLM APIs
+- Batch processing pipelines where cost adds up quickly
+- Multi-model architectures that need intelligent routing
+- Production systems that need budget guardrails

package/.roo/skills/cost-aware-model-routing/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: cost-aware-model-routing
+description: Pick the right model tier (trivial/standard/hard) for each ECC session task. Companion to the cost-aware-model-routing rule and the token-budget safety hook. Use when the user asks "what model should I use" or when a session is burning frontier-model tokens on routine work.
+origin: ECC
+---
+
+# Cost-Aware Model Routing — Explicit Skill
+
+The companion skill to the always-on routing rule. Invoke this when the user explicitly asks "what model should I use for this task" or when you (the agent) want to surface a routing recommendation deliberately rather than via the implicit rule.
+
+> Pairs with `rules/common/cost-aware-model-routing.md` (the always-on rule), `hooks/safety/token-budget.js` (spend control), and the `cost-aware-llm-pipeline` skill (patterns for user code).
+
+---
+
+## When to invoke
+
+Trigger this skill when:
+
+- The user asks "which model should I use", "is opus overkill for this", "can haiku handle this", "what's the cheapest tier for this".
+- A session is approaching budget limits and the next task looks trivial.
+- The user is on a frontier model but the next task is mechanical (rename, format, doc).
+- You want to teach the user how to route deliberately for the next 10 turns instead of just this one.
+
+Do NOT invoke when:
+
+- The user is mid-task on something hard (architecture, incident, security audit) — keep them on the high tier.
+- The user has explicitly chosen a model in this session — respect their choice.
+
+---
+
+## Workflow
+
+### 1. Classify the current task
+
+Use the three-tier framework from the rule:
+
+| Tier | Examples |
+|---|---|
+| **trivial** | Rename, format, fix typo, add JSDoc, summarize, list files, version bump, kebab→camel |
+| **standard** | Code review of a PR, write a unit test, refactor one file, fix a non-critical bug, write a doc section |
+| **hard** | Architecture decision, debug-blitz of intermittent prod bug, security audit, multi-file refactor (3+ files), incident postmortem, devil-mode, agent harness changes |
+
+Weight signals together. Single signals are noisy; three or four together are reliable.
+
+### 2. Read the team's config
+
+Check for `.kodelythecc/router.json` at the project root and these env vars:
+
+```
+KODELYTH_ROUTER          off | (unset)
+KODELYTH_ROUTER_TRIVIAL  override trivial-tier model id
+KODELYTH_ROUTER_STANDARD override standard-tier model id
+KODELYTH_ROUTER_HARD     override hard-tier model id
+KODELYTH_ROUTER_DEFAULT  trivial | standard | hard (fallback for ambiguous tasks)
+```
+
+If `KODELYTH_ROUTER=off`, do NOT emit recommendations — the team has chosen to opt out.
+
+### 3. Emit a single, structured recommendation
+
+Use this exact format so the user can scan it instantly:
+
+```
+[model-router] task=<tier> · suggested=<model-id> · current=<active or "unknown">
+  why: <one short sentence on the dominant signals>
+  next: <how to switch — provider-specific>
+```
+
+Only emit when the active model is mismatched with the suggested tier. If the user is already on the right tier, route silently and do not interrupt.
+
+### 4. If the user wants ad-hoc routing for a future task
+
+Tell them:
+
+```
+npx kodelyth-ecc route "<task description>"            # quick CLI hint
+npx kodelyth-ecc route "<task>" --files 5 --agent debug-detective
+```
+
+Or for an in-session check, they can `use cost-aware-model-routing` and describe the task.
+
+---
+
+## Hard rules (never break these)
+
+1. **Security / incident / adversarial work never downgrades.** If the active agent is `security-reviewer`, `incident-commander`, `debug-detective`, or any devil-mode agent (`prompt-injection-hunter`, `supply-chain-auditor`, `secret-hunter`, `backdoor-hunter`, `chaos-engineer`, `jailbreak-tester`, `code-stealer-detector`, `license-violation-finder`) — recommend **hard** tier even if the surface task looks trivial.
+2. **Production framing wins.** "Down", "leaking", "outage", "incident", "P0", "P1" → hard.
+3. **Multi-file refactors (3+) never go to trivial.**
+4. **Respect explicit user choice.** If the user said "use haiku", don't override unless a new turn introduces conflicting signals.
+5. **Budget-aware:** if `token-budget` reports usage > 70% of budget, bias one tier downward when ambiguous to extend the session.
+
+---
+
+## Examples
+
+### Example 1 — clear downgrade opportunity
+
+```
+User: "rename getUserName to getUserDisplayName everywhere"
+[active model: claude-opus-4-1]
+
+Recommendation:
+[model-router] task=trivial · suggested=claude-haiku-4-5-20251001 · current=claude-opus-4-1
+  why: single mechanical rename, no behavior change, no tests need updating.
+  next: switch to /model claude-haiku for this turn — saves ~80% in tokens with no quality loss.
+```
+
+### Example 2 — never downgrade incident work
+
+```
+User: "production is down and the auth service is throwing 502s, help"
+[active model: claude-haiku-4-5-20251001]
+
+Recommendation:
+[model-router] task=hard · suggested=claude-opus-4-1 · current=claude-haiku-4-5-20251001
+  why: production incident with security-relevant subsystem.
+  next: switch to /model claude-opus before continuing — this is incident-commander territory.
+```
+
+### Example 3 — match, no recommendation
+
+```
+User: "review this 40-line PR for typos and obvious bugs"
+[active model: claude-sonnet-4-6]
+
+Recommendation: (silent — already on the right tier)
+```
+
+### Example 4 — devil-mode never downgrades
+
+```
+User: "/devil-mode --all"
+[active model: claude-haiku-4-5-20251001]
+
+Recommendation:
+[model-router] task=hard · suggested=claude-opus-4-1 · current=claude-haiku-4-5-20251001
+  why: devil-mode adversarial sweep — security/quality assertions need frontier reasoning.
+  next: switch to /model claude-opus or your equivalent frontier model.
+```
+
+---
+
+## Implementation references
+
+- Rule: `rules/common/cost-aware-model-routing.md`
+- Classifier: `scripts/router/classify.js` (pure-function, deterministic)
+- CLI: `npx kodelyth-ecc route <task>`
+- Companion safety hook: `hooks/safety/token-budget.js` (spend cap)
+- Skill for user-code patterns (different scope): `cost-aware-llm-pipeline`
+
+---
+
+Built into [Kodelyth ECC](../../README.md). MIT licensed.

package/.roo/skills/council/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: council
+description: Convene a four-voice council for ambiguous decisions, tradeoffs, and go/no-go calls. Use when multiple valid paths exist and you need structured disagreement before choosing.
+origin: ECC
+---
+
+# Council
+
+Convene four advisors for ambiguous decisions:
+- the in-context Claude voice
+- a Skeptic subagent
+- a Pragmatist subagent
+- a Critic subagent
+
+This is for **decision-making under ambiguity**, not code review, implementation planning, or architecture design.
+
+## When to Use
+
+Use council when:
+- a decision has multiple credible paths and no obvious winner
+- you need explicit tradeoff surfacing
+- the user asks for second opinions, dissent, or multiple perspectives
+- conversational anchoring is a real risk
+- a go / no-go call would benefit from adversarial challenge
+
+Examples:
+- monorepo vs polyrepo
+- ship now vs hold for polish
+- feature flag vs full rollout
+- simplify scope vs keep strategic breadth
+
+## When NOT to Use
+
+| Instead of council | Use |
+| --- | --- |
+| Verifying whether output is correct | `santa-method` |
+| Breaking a feature into implementation steps | `planner` |
+| Designing system architecture | `architect` |
+| Reviewing code for bugs or security | `code-reviewer` or `santa-method` |
+| Straight factual questions | just answer directly |
+| Obvious execution tasks | just do the task |
+
+## Roles
+
+| Voice | Lens |
+| --- | --- |
+| Architect | correctness, maintainability, long-term implications |
+| Skeptic | premise challenge, simplification, assumption breaking |
+| Pragmatist | shipping speed, user impact, operational reality |
+| Critic | edge cases, downside risk, failure modes |
+
+The three external voices should be launched as fresh subagents with **only the question and relevant context**, not the full ongoing conversation. That is the anti-anchoring mechanism.
+
+## Workflow
+
+### 1. Extract the real question
+
+Reduce the decision to one explicit prompt:
+- what are we deciding?
+- what constraints matter?
+- what counts as success?
+
+If the question is vague, ask one clarifying question before convening the council.
+
+### 2. Gather only the necessary context
+
+If the decision is codebase-specific:
+- collect the relevant files, snippets, issue text, or metrics
+- keep it compact
+- include only the context needed to make the decision
+
+If the decision is strategic/general:
+- skip repo snippets unless they materially change the answer
+
+### 3. Form the Architect position first
+
+Before reading other voices, write down:
+- your initial position
+- the three strongest reasons for it
+- the main risk in your preferred path
+
+Do this first so the synthesis does not simply mirror the external voices.
+
+### 4. Launch three independent voices in parallel
+
+Each subagent gets:
+- the decision question
+- compact context if needed
+- a strict role
+- no unnecessary conversation history
+
+Prompt shape:
+
+```text
+You are the [ROLE] on a four-voice decision council.
+
+Question:
+[decision question]
+
+Context:
+[only the relevant snippets or constraints]
+
+Respond with:
+1. Position — 1-2 sentences
+2. Reasoning — 3 concise bullets
+3. Risk — biggest risk in your recommendation
+4. Surprise — one thing the other voices may miss
+
+Be direct. No hedging. Keep it under 300 words.
+```
+
+Role emphasis:
+- Skeptic: challenge framing, question assumptions, propose the simplest credible alternative
+- Pragmatist: optimize for speed, simplicity, and real-world execution
+- Critic: surface downside risk, edge cases, and reasons the plan could fail
+
+### 5. Synthesize with bias guardrails
+
+You are both a participant and the synthesizer, so use these rules:
+- do not dismiss an external view without explaining why
+- if an external voice changed your recommendation, say so explicitly
+- always include the strongest dissent, even if you reject it
+- if two voices align against your initial position, treat that as a real signal
+- keep the raw positions visible before the verdict
+
+### 6. Present a compact verdict
+
+Use this output shape:
+
+```markdown
+## Council: [short decision title]
+
+**Architect:** [1-2 sentence position]
+[1 line on why]
+
+**Skeptic:** [1-2 sentence position]
+[1 line on why]
+
+**Pragmatist:** [1-2 sentence position]
+[1 line on why]
+
+**Critic:** [1-2 sentence position]
+[1 line on why]
+
+### Verdict
+- **Consensus:** [where they align]
+- **Strongest dissent:** [most important disagreement]
+- **Premise check:** [did the Skeptic challenge the question itself?]
+- **Recommendation:** [the synthesized path]
+```
+
+Keep it scannable on a phone screen.
+
+## Persistence Rule
+
+Do **not** write ad-hoc notes to `~/.claude/notes` or other shadow paths from this skill.
+
+If the council materially changes the recommendation:
+- use `knowledge-ops` to store the lesson in the right durable location
+- or use `/save-session` if the outcome belongs in session memory
+- or update the relevant GitHub / Linear issue directly if the decision changes active execution truth
+
+Only persist a decision when it changes something real.
+
+## Multi-Round Follow-up
+
+Default is one round.
+
+If the user wants another round:
+- keep the new question focused
+- include the previous verdict only if it is necessary
+- keep the Skeptic as clean as possible to preserve anti-anchoring value
+
+## Anti-Patterns
+
+- using council for code review
+- using council when the task is just implementation work
+- feeding the subagents the entire conversation transcript
+- hiding disagreement in the final verdict
+- persisting every decision as a note regardless of importance
+
+## Related Skills
+
+- `santa-method` — adversarial verification
+- `knowledge-ops` — persist durable decision deltas correctly
+- `search-first` — gather external reference material before the council if needed
+- `architecture-decision-records` — formalize the outcome when the decision becomes long-lived system policy
+
+## Example
+
+Question:
+
+```text
+Should we ship ECC 2.0 as alpha now, or hold until the control-plane UI is more complete?
+```
+
+Likely council shape:
+- Architect pushes for structural integrity and avoiding a confused surface
+- Skeptic questions whether the UI is actually the gating factor
+- Pragmatist asks what can be shipped now without harming trust
+- Critic focuses on support burden, expectation debt, and rollout confusion
+
+The value is not unanimity. The value is making the disagreement legible before choosing.