kodelyth-ecc 2.19.0 → 2.20.0

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

@@ -1,183 +0,0 @@
----
-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/.kimi/skills/cost-aware-model-routing/SKILL.md

@@ -1,153 +0,0 @@
----
-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/.kimi/skills/council/SKILL.md

@@ -1,203 +0,0 @@
----
-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.