agent-notes 2.0.4__py3-none-any.whl

agent_notes/data/models/claude-opus-4-5.yaml

@@ -0,0 +1,16 @@
+id: claude-opus-4-5
+label: Claude Opus 4.5
+family: claude
+class: opus
+deprecated: true
+aliases:
+  anthropic:      claude-opus-4-5
+  github-copilot: github-copilot/claude-opus-4.5
+pricing:
+  input:  5.00
+  output: 25.00
+  cache:  0.50
+capabilities:
+  vision: true
+  long_context: false
+  tool_use: true

agent_notes/data/models/claude-opus-4-6.yaml

@@ -0,0 +1,16 @@
+id: claude-opus-4-6
+label: Claude Opus 4.6
+family: claude
+class: opus
+deprecated: true
+aliases:
+  anthropic:      claude-opus-4-6
+  github-copilot: github-copilot/claude-opus-4.6
+pricing:
+  input:  5.00
+  output: 25.00
+  cache:  0.50
+capabilities:
+  vision: true
+  long_context: true
+  tool_use: true

agent_notes/data/models/claude-opus-4-7.yaml

@@ -0,0 +1,15 @@
+id: claude-opus-4-7
+label: Claude Opus 4.7
+family: claude
+class: opus
+aliases:
+  anthropic:      opus
+  github-copilot: github-copilot/claude-opus-4.7
+pricing:
+  input:  5.00
+  output: 25.00
+  cache:  0.50
+capabilities:
+  vision: true
+  long_context: true
+  tool_use: true

agent_notes/data/models/claude-sonnet-4-5.yaml

@@ -0,0 +1,16 @@
+id: claude-sonnet-4-5
+label: Claude Sonnet 4.5
+family: claude
+class: sonnet
+deprecated: true
+aliases:
+  anthropic:      claude-sonnet-4-5
+  github-copilot: github-copilot/claude-sonnet-4.5
+pricing:
+  input:  3.00
+  output: 15.00
+  cache:  0.30
+capabilities:
+  vision: true
+  long_context: false
+  tool_use: true

agent_notes/data/models/claude-sonnet-4-6.yaml

@@ -0,0 +1,15 @@
+id: claude-sonnet-4-6
+label: Claude Sonnet 4.6
+family: claude
+class: sonnet
+aliases:
+  anthropic:      sonnet
+  github-copilot: github-copilot/claude-sonnet-4.6
+pricing:
+  input:  3.00
+  output: 15.00
+  cache:  0.30
+capabilities:
+  vision: true
+  long_context: true
+  tool_use: true

agent_notes/data/models/claude-sonnet-4.yaml

@@ -0,0 +1,16 @@
+id: claude-sonnet-4
+label: Claude Sonnet 4
+family: claude
+class: sonnet
+deprecated: true
+aliases:
+  anthropic:      claude-sonnet-4-20250514
+  github-copilot: github-copilot/claude-sonnet-4
+pricing:
+  input:  3.00
+  output: 15.00
+  cache:  0.30
+capabilities:
+  vision: true
+  long_context: true
+  tool_use: true

agent_notes/data/pricing.yaml

@@ -0,0 +1,33 @@
+baseline:
+  label: Claude Opus 4.7
+  price:
+    in: 5.00
+    out: 25.00
+    cache: 0.50
+
+providers:
+  - name: Anthropic
+    models:
+      - name: Claude Haiku 4.5
+        match: "*haiku*"
+        price: {in: 1.00, out: 5.00, cache: 0.10}
+        updated_at: "2026-04"
+      - name: Claude Sonnet
+        match: "*sonnet*"
+        price: {in: 3.00, out: 15.00, cache: 0.30}
+        updated_at: "2026-04"
+      - name: Claude Opus 4.7 / 4.6 / 4.5
+        match: ["*opus-4.7*", "*opus-4.6*", "*opus-4.5*"]
+        price: {in: 5.00, out: 25.00, cache: 0.50}
+        updated_at: "2026-04"
+      - name: Claude Opus (legacy)
+        match: ["*opus-4.1*", "*opus*"]
+        price: {in: 15.00, out: 75.00, cache: 1.50}
+        updated_at: "2026-04"
+
+  - name: OpenAI
+    models:
+      - name: GPT-4 / o-series
+        match: ["gpt-*", "o1*", "o3*", "o4*"]
+        price: {in: 2.50, out: 10.00, cache: 0.50}
+        updated_at: "2026-04"

agent_notes/data/roles/orchestrator.yaml

@@ -0,0 +1,5 @@
+name: orchestrator
+label: Orchestrator
+description: Plans and delegates complex multi-step tasks. Low volume, high reasoning needed.
+typical_class: opus
+color: purple

agent_notes/data/roles/reasoner.yaml

@@ -0,0 +1,5 @@
+name: reasoner
+label: Reasoner
+description: Deep debugging and architecture analysis. Low volume, max reasoning needed.
+typical_class: opus
+color: red

agent_notes/data/roles/scout.yaml

@@ -0,0 +1,5 @@
+name: scout
+label: Scout
+description: Fast file discovery, pattern search. High volume, low reasoning.
+typical_class: haiku
+color: cyan

agent_notes/data/roles/worker.yaml

@@ -0,0 +1,5 @@
+name: worker
+label: Worker
+description: Implements code, writes tests, does focused analysis. Medium volume.
+typical_class: sonnet
+color: green

agent_notes/data/rules/code-quality.md

@@ -0,0 +1,9 @@
+# Code Quality
+
+- Read existing code first. Match project indentation, naming, and file organization.
+- Small focused methods. One responsibility per method.
+- Guard clauses and early returns over deep nesting.
+- Meaningful names that describe purpose, not implementation.
+- Only build what was asked for. No speculative abstractions.
+- Validate at system boundaries (user input, external APIs). Trust internal code.
+- No comments for obvious code. Comment the "why", not the "what".

agent_notes/data/rules/safety.md

@@ -0,0 +1,10 @@
+# Safety
+
+- Confirm before destructive or irreversible operations:
+  - `git push --force`, `git reset --hard`, amending published commits
+  - `rm -rf`, deleting files or branches, dropping database tables
+  - Operations visible to others: pushing code, commenting on PRs/issues
+- Never commit secrets: `.env`, `*.pem`, credentials, API keys, tokens.
+- Never bypass safety checks (`--no-verify`, `--force`) without explicit user request.
+- Never force-push to main or master branches.
+- When encountering obstacles, do not use destructive actions as shortcuts.

agent_notes/data/scripts/cost-report

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Session cost report — prices sourced from agent_notes/data/pricing.yaml."""
+import sqlite3
+from fnmatch import fnmatch
+from pathlib import Path
+
+BOLD = "\033[1m"
+DIM = "\033[2m"
+YELLOW = "\033[0;33m"
+GREEN = "\033[0;32m"
+CYAN = "\033[0;36m"
+NC = "\033[0m"
+
+PRICING = {{PRICING}}
+
+DB = Path.home() / ".local/share/opencode/opencode.db"
+
+SQL = """
+WITH cs AS (SELECT id FROM session WHERE parent_id IS NULL ORDER BY time_created DESC LIMIT 1),
+conv_start AS (
+  SELECT COALESCE(
+    (SELECT json_extract(m2.data,'$.time.created')
+     FROM message m1 JOIN message m2 ON m1.session_id=m2.session_id
+     WHERE m1.session_id=(SELECT id FROM cs)
+       AND json_extract(m2.data,'$.time.created') > json_extract(m1.data,'$.time.created')
+       AND json_extract(m2.data,'$.time.created') - json_extract(m1.data,'$.time.created') > 1800000
+       AND NOT EXISTS (
+         SELECT 1 FROM message mx WHERE mx.session_id=m1.session_id
+           AND json_extract(mx.data,'$.time.created') > json_extract(m1.data,'$.time.created')
+           AND json_extract(mx.data,'$.time.created') < json_extract(m2.data,'$.time.created'))
+     ORDER BY json_extract(m1.data,'$.time.created') DESC LIMIT 1),
+    0) AS start_ts
+)
+SELECT
+  COALESCE(json_extract(m.data,'$.agent'), 'lead') AS agent,
+  (SELECT json_extract(m2.data,'$.modelID') FROM message m2
+   WHERE m2.session_id = s.id AND json_extract(m2.data,'$.role') = 'assistant'
+   ORDER BY json_extract(m2.data,'$.time.completed') DESC LIMIT 1) AS model,
+  SUM(json_extract(m.data,'$.tokens.input'))       AS inp,
+  SUM(json_extract(m.data,'$.tokens.output'))      AS outp,
+  SUM(json_extract(m.data,'$.tokens.cache.read'))  AS cache,
+  ROUND(SUM(
+    CASE WHEN json_extract(m.data,'$.time.completed') IS NOT NULL
+              AND json_extract(m.data,'$.time.created') IS NOT NULL
+    THEN (json_extract(m.data,'$.time.completed') - json_extract(m.data,'$.time.created')) / 1000.0
+    ELSE 0 END
+  ), 1) AS sec
+FROM session s
+JOIN message m ON m.session_id = s.id
+CROSS JOIN cs
+CROSS JOIN conv_start
+WHERE (s.parent_id = cs.id OR s.id = cs.id)
+  AND json_extract(m.data,'$.role') = 'assistant'
+  AND json_extract(m.data,'$.time.created') >= conv_start.start_ts
+  AND (s.time_created >= conv_start.start_ts OR s.id = (SELECT id FROM cs))
+GROUP BY s.id
+"""
+
+
+def _build_price_table() -> list[tuple[list[str], dict]]:
+    rows = []
+    for provider in PRICING.get("providers", []):
+        for model in provider.get("models", []):
+            patterns = model["match"] if isinstance(model["match"], list) else [model["match"]]
+            rows.append((patterns, model["price"]))
+    return rows
+
+
+_PRICE_TABLE = _build_price_table()
+_BASELINE = PRICING["baseline"]["price"]
+_BASELINE_LABEL = PRICING["baseline"]["label"]
+
+
+def get_price(model_id: str) -> dict:
+    for patterns, price in _PRICE_TABLE:
+        if any(fnmatch(model_id, p) for p in patterns):
+            return price
+    return {"in": 3.00, "out": 15.00, "cache": 0.30}
+
+
+def calculate_cost(model_id: str, inp: int, outp: int, cache: int) -> float:
+    p = get_price(model_id)
+    return (inp * p["in"] + outp * p["out"] + cache * p["cache"]) / 1_000_000
+
+
+def baseline_cost(inp: int, outp: int, cache: int) -> float:
+    p = _BASELINE
+    return (inp * p["in"] + outp * p["out"] + cache * p["cache"]) / 1_000_000
+
+
+def tier_color(model_id: str) -> str:
+    if "opus" in model_id:
+        return YELLOW
+    if "sonnet" in model_id:
+        return CYAN
+    return DIM
+
+
+def fmt_num(n: int) -> str:
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.2f}m"
+    if n >= 1_000:
+        return f"{n / 1_000:.2f}k"
+    return str(n)
+
+
+def fmt_tokens(inp, outp, cache) -> str:
+    return f"{fmt_num(inp)}/{fmt_num(outp)}/{fmt_num(cache)}"
+
+
+def fmt_time(sec: float) -> str:
+    s = int(round(sec))
+    if s < 60:
+        return f"{s}s"
+    m, s = divmod(s, 60)
+    if m < 60:
+        return f"{m}m {s}s" if s else f"{m}m"
+    h, m = divmod(m, 60)
+    return f"{h}h {m}m" if m else f"{h}h"
+
+
+def fmt_cost(c: float) -> str:
+    return f"${c:.4f}"
+
+
+def main() -> None:
+    if not DB.exists():
+        print(f"Database not found: {DB}")
+        return
+
+    rows = sqlite3.connect(DB).execute(SQL).fetchall()
+    if not rows:
+        print("No sessions found.")
+        return
+
+    records = [
+        (agent, model or "unknown", inp or 0, outp or 0, cache or 0, sec or 0)
+        for agent, model, inp, outp, cache, sec in rows
+    ]
+
+    costs = [
+        (agent, model, inp, outp, cache, sec,
+         calculate_cost(model, inp, outp, cache),
+         baseline_cost(inp, outp, cache))
+        for agent, model, inp, outp, cache, sec in records
+    ]
+
+    _total_inp  = sum(i for _, _, i, *_ in costs)
+    _total_outp = sum(o for _, _, _, o, *_ in costs)
+    _total_cache= sum(c for _, _, _, _, c, *_ in costs)
+    _max_sec    = max(s for _, _, _, _, _, s, *_ in costs)
+    _total_sec  = sum(s for _, _, _, _, _, s, *_ in costs)
+    _total_time = f"{fmt_time(_max_sec)} / {fmt_time(_total_sec)} seq"
+
+    agent_col_w = max(len(f"{a}({m})") for a, m, *_ in costs) + 2
+    tok_col_w   = max(
+        max(len(fmt_tokens(i, o, c)) for _, _, i, o, c, *_ in costs),
+        len(fmt_tokens(_total_inp, _total_outp, _total_cache))
+    ) + 2
+    time_col_w  = max(
+        max(len(fmt_time(s)) for _, _, _, _, _, s, *_ in costs),
+        len(_total_time)
+    ) + 2
+    W = (agent_col_w, tok_col_w, time_col_w, 12, 12)
+
+    header = (
+        f"{'agent(model)':<{W[0]}}"
+        f" {'in/out/cache':<{W[1]}}"
+        f" {'time':<{W[2]}}"
+        f" {'actual':<{W[3]}}"
+        f" {f'vs {_BASELINE_LABEL}':<{W[4]}}"
+    )
+    print(BOLD + header + NC)
+    print(DIM + "-" * len(header) + NC)
+
+    total_inp = total_outp = total_cache = 0
+    total_actual = total_vs = max_sec = total_sec = 0.0
+
+    for agent, model, inp, outp, cache, sec, actual, vs in costs:
+        label = f"{agent}({model})"
+        time_str = fmt_time(sec)
+        col = tier_color(model)
+        print(
+            col + f"{label:<{W[0]}}" + NC
+            + f" {fmt_tokens(inp, outp, cache):<{W[1]}}"
+            + f" {time_str:<{W[2]}}"
+            + f" {fmt_cost(actual):<{W[3]}}"
+            + f" {fmt_cost(vs):<{W[4]}}"
+        )
+        total_inp += inp; total_outp += outp; total_cache += cache
+        total_actual += actual; total_vs += vs
+        max_sec = max(max_sec, sec)
+        total_sec += sec
+
+    saved_pct = round((1 - total_actual / total_vs) * 100) if total_vs else 0
+    total_label = f"TOTAL (saved {saved_pct}%)"
+    total_time = _total_time
+    col = GREEN if total_actual <= 5 else YELLOW
+    print(
+        col + BOLD
+        + f"{total_label:<{W[0]}}"
+        + f" {fmt_tokens(total_inp, total_outp, total_cache):<{W[1]}}"
+        + f" {total_time:<{W[2]}}"
+        + f" {fmt_cost(total_actual):<{W[3]}}"
+        + f" {fmt_cost(total_vs):<{W[4]}}"
+        + NC
+    )
+
+
+if __name__ == "__main__":
+    main()

agent_notes/data/skills/brainstorming/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: brainstorming
+description: "Explore multiple approaches before committing — read context, surface tradeoffs, then decide"
+group: process
+---
+
+# Brainstorming
+
+Use when the problem has multiple valid solutions and the choice has long-term consequences: API design, data model, architecture, technology selection.
+
+## Process
+
+### 1. Read the context first
+
+Before generating options, read:
+- Existing patterns in the codebase — there may already be an established approach to follow.
+- Similar features already implemented — don't invent something the codebase already knows how to do.
+- Any stated constraints in tickets, comments, or configuration.
+
+### 2. Generate options (diverge)
+
+Produce at least three meaningfully distinct approaches. For each:
+- **Name** — one noun phrase.
+- **Summary** — two sentences max.
+- **Main advantage** — what it does best.
+- **Main cost or risk** — what you're giving up.
+
+Do not evaluate yet. Generate first. If one option is clearly dominant, still generate alternatives — the exercise surfaces the tradeoffs you'd otherwise miss.
+
+If a key technical assumption is unproven, include a **spike option**: a throwaway implementation to test the risky assumption before committing to a direction.
+
+### 3. Apply constraints (filter)
+
+Filter against the project's real constraints:
+- Performance requirements
+- Team familiarity and maintainability
+- Existing patterns and dependencies in the codebase
+- Timeline and scope
+
+Remove options that violate hard constraints. Do not remove options just because they're unfamiliar or non-obvious.
+
+### 4. Recommend (converge)
+
+Pick one option. State:
+- Which option you recommend.
+- Why it wins against the specific alternatives — not in the abstract.
+- What you are explicitly trading away — be honest, not diplomatic.
+
+Present the recommendation. Do not begin implementation until the user agrees.
+
+## Anti-patterns
+
+- Generating one real option and two obvious strawmen to make it look like a comparison.
+- Recommending the first option you thought of.
+- Listing tradeoffs without actually comparing them against each other.
+- Skipping the codebase read and inventing patterns from scratch.
+- Framing a spike as a commitment — spikes are exploratory, not production code.

agent_notes/data/skills/code-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: code-review
+description: "Systematic code review: correctness, safety, performance, clarity, consistency"
+group: process
+---
+
+# Code Review
+
+Work through these five lenses in order. Report findings grouped by lens, ranked by severity within each group.
+
+## Lens 1 — Correctness
+
+- Does the logic match the stated intent?
+- Are edge cases handled: empty input, nil/None, off-by-one, concurrent access, zero/negative values?
+- Are error paths handled and surfaced to callers correctly?
+- Do the tests cover behavior, not just the happy path?
+- Is there new code with no tests at all? That is a blocking issue.
+
+## Lens 2 — Safety
+
+- Is user input validated at the system boundary?
+- Are secrets, credentials, or PII handled safely — not logged, not exposed in responses?
+- Are SQL queries parameterized, not interpolated?
+- Are file paths sanitized before use?
+- Does this change affect authentication or authorization logic? If yes, flag for deeper scrutiny.
+
+## Lens 3 — Performance
+
+- Are there N+1 queries — loading a record, then querying for each related record in a loop?
+- Are expensive operations (network calls, disk I/O, serialization) inside hot loops?
+- Are large collections being loaded into memory when streaming or pagination would suffice?
+- Is the change reversible if it causes a production performance regression?
+
+## Lens 4 — Clarity
+
+- Are names accurate — do they describe what, not how?
+- Is control flow easy to follow? Guard clauses beat deep nesting.
+- Are comments present only where the why is non-obvious? No comments that restate what the code already says.
+- Would a new team member understand this without asking?
+
+## Lens 5 — Consistency
+
+- Does this match the existing patterns in the codebase?
+- Does it follow project naming conventions?
+- Does it introduce a new abstraction or dependency that already exists elsewhere?
+- Are the tests written in the same style as existing tests?
+
+## Output format
+
+```
+BLOCKING
+- [file:line] [finding] — [why it matters]
+
+SUGGESTIONS
+- [file:line] [finding] — [alternative if applicable]
+
+APPROVED (if no blocking issues)
+```
+
+A BLOCKING finding must be resolved before merge. A SUGGESTION is optional.
+
+## Scope discipline
+
+Do not flag cosmetic changes unless they create real ambiguity. A review that lists 20 nits trains authors to ignore reviews entirely.

agent_notes/data/skills/debugging-protocol/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: debugging-protocol
+description: "4-phase systematic debugging: instrument → evidence → hypothesis → fix"
+group: process
+---
+
+# Debugging Protocol
+
+Never guess. Never change code randomly. Follow the four phases.
+
+## Phase 1 — Instrument
+
+Before forming any hypothesis, add observability:
+- Add logging at the entry and exit of the failing code path.
+- Log inputs, intermediate values, and outputs — not just that something happened.
+- If a test is failing: read the **full stack trace** before doing anything else.
+- If a runtime error: reproduce in the smallest possible isolated case.
+
+Do not modify production logic in this phase.
+
+**For regressions:** run `git log --oneline -20` and use `git bisect` to find the commit that introduced the failure before instrumenting. Knowing when it broke tells you where to look.
+
+## Phase 2 — Gather evidence
+
+Run the instrumented version. Collect:
+- Exact error message and file:line location.
+- What values are actually present vs. what was expected.
+- The full call stack at the point of failure.
+- Whether this is a **code bug** or a **test bug** — read the test's intent before assuming the production code is wrong.
+
+Check dependency changelogs if a third-party library was recently updated and the failure is at an integration boundary.
+
+## Phase 3 — Form a hypothesis
+
+State it explicitly before touching anything:
+
+> "I believe the bug is caused by X, because the evidence shows Y."
+
+Test with the smallest possible change — one that confirms or disproves the hypothesis without being the permanent fix. If the hypothesis is wrong: return to Phase 2 with the new evidence. Do not stack changes.
+
+## Phase 4 — Fix
+
+Apply the minimal fix for the root cause:
+- Fix the root cause, not the symptom.
+- Remove all instrumentation from Phase 1.
+- Run the full test suite.
+- Confirm the original failure is gone and nothing else regressed.
+
+## Escalation rule
+
+Three failed hypothesis cycles means stop and do an architectural review. The bug likely signals that a design assumption is wrong, not just a logic error in one function.