@rubix0270/arboris 1.0.1 → 1.0.3

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

@@ -1,184 +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.
-metadata:
-  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/prisma/skills/cost-tracking/SKILL.md

@@ -1,97 +0,0 @@
----
-name: cost-tracking
-description: Track and report Claude Code token usage, spending, and budgets from the local ECC cost-tracker metrics log. Use when the user asks about costs, spending, usage, tokens, budgets, or cost breakdowns by model, session, or date.
-metadata:
-  origin: community
----
-
-# Cost Tracking
-
-Use this skill to analyze Claude Code cost and usage history from the metrics log
-that ECC's `stop:cost-tracker` hook writes.
-
-## Where the data lives
-
-The tracker appends one JSON object per session-stop to
-`~/.claude/metrics/costs.jsonl`. Each row is a **cumulative snapshot for that
-session**, so to total spend you take the **latest row per `session_id`** and
-sum across sessions — summing every row multiply-counts.
-
-Row schema:
-
-| Field | Meaning |
-| --- | --- |
-| `timestamp` | ISO timestamp of the snapshot |
-| `session_id` | Claude Code session identifier |
-| `transcript_path` | Path to the session transcript |
-| `model` | Model used |
-| `input_tokens` / `output_tokens` | Token counts |
-| `cache_write_tokens` / `cache_read_tokens` | Prompt-cache token counts |
-| `estimated_cost_usd` | Precomputed cumulative cost in USD for the session |
-
-Prefer `estimated_cost_usd` over hand-calculating pricing — model and cache
-prices change, and the tracker is the source of truth.
-
-## When to Use
-
-- The user asks "how much have I spent?", "what did this session cost?", or
-  "what is my token usage?"
-- The user mentions budgets, spending limits, overruns, or cost controls.
-- The user wants a cost breakdown by model, session, or date, or a CSV export.
-
-## How It Works
-
-First verify the log exists (use `node`, not `sqlite3` — the tracker writes
-JSONL, and `node` is cross-platform):
-
-```bash
-node -e 'const fs=require("fs"),os=require("os"),p=require("path");const f=p.join(os.homedir(),".claude","metrics","costs.jsonl");console.log(fs.existsSync(f)?"cost log found":"cost log not found: "+f)'
-```
-
-If the log is missing, do not fabricate usage data. Tell the user that cost
-tracking populates after the first session ends with the `stop:cost-tracker`
-hook enabled.
-
-## Example — summary, by model, last 7 days
-
-```bash
-node -e '
-const fs=require("fs"),os=require("os"),path=require("path");
-const f=path.join(os.homedir(),".claude","metrics","costs.jsonl");
-if(!fs.existsSync(f)){console.log("cost log not found: "+f);process.exit(0);}
-const rows=fs.readFileSync(f,"utf8").split(/\r?\n/).filter(Boolean).map(l=>{try{return JSON.parse(l)}catch{return null}}).filter(Boolean);
-const bySession=new Map();
-for(const r of rows){const k=r.session_id||r.transcript_path||r.timestamp;const p=bySession.get(k);if(!p||String(r.timestamp)>String(p.timestamp))bySession.set(k,r);}
-const latest=[...bySession.values()];
-const cost=r=>Number(r.estimated_cost_usd)||0, day=r=>String(r.timestamp||"").slice(0,10), sum=a=>a.reduce((s,r)=>s+cost(r),0), f4=n=>"$"+n.toFixed(4);
-const today=new Date().toISOString().slice(0,10), yest=new Date(Date.now()-864e5).toISOString().slice(0,10);
-console.log("today: "+f4(sum(latest.filter(r=>day(r)===today)))+" | yesterday: "+f4(sum(latest.filter(r=>day(r)===yest)))+" | total: "+f4(sum(latest))+" ("+latest.length+" sessions)");
-const m=new Map();for(const r of latest){const k=r.model||"(unknown)";m.set(k,(m.get(k)||0)+cost(r));}
-console.log("by model:");[...m.entries()].sort((a,b)=>b[1]-a[1]).forEach(([k,v])=>console.log("  "+f4(v)+"  "+k));
-'
-```
-
-For a session drilldown or CSV export, iterate the same `latest` set (or the raw
-rows for CSV) and print the fields you need.
-
-## Reporting Guidance
-
-When presenting cost data, include today's spend vs yesterday, total across all
-sessions, a by-model breakdown, and session count. Format sub-dollar amounts
-with four decimals, larger amounts with two.
-
-## Anti-Patterns
-
-- Do not sum every row — they are cumulative per session; reduce to the latest
-  row per `session_id` first.
-- Do not estimate costs from raw token counts when `estimated_cost_usd` is present.
-- Do not assume the log exists without checking.
-- Do not hard-code current model pricing in user-facing answers.
-- Do not recommend installing unreviewed hooks or plugins that execute arbitrary code.
-
-## Related
-
-- `/cost-report` - Command-form report over the same metrics log.
-- `cost-aware-llm-pipeline` - Model-routing and budget-design patterns.
-- `token-budget-advisor` - Context and token-budget planning.
-- `strategic-compact` - Context compaction to reduce repeated token spend.

package/prisma/skills/council/SKILL.md

@@ -1,204 +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.
-metadata:
-  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.