claude-cost-tracker 0.1.0__tar.gz

claude_cost_tracker-0.1.0/.claude/commands/end-session.md

@@ -0,0 +1,49 @@
+---
+description: End-of-session wind-down. Runs reconcile-docs → next-steps decomposition (PLAN-ONLY) → shift-handoff, in that fixed order, so the next session can resume correctly with zero re-derivation. Reconciles the living docs to reality, defines the next session's steps as a persisted plan (without executing anything), then writes the next-agent handoff prompt.
+argument-hint: [optional: notes/focus for the next session, e.g. "next: finish the carry-cost model"]
+---
+
+You are ending a work session. This command runs the wind-down ritual as a **fixed, ordered sequence** whose single goal is to leave the project in a state where the next session — human or agent — resumes correctly **without re-deriving anything from this conversation** (which will not exist next session).
+
+It answers three questions, in order. Do not reorder them; each step depends on the previous one's output:
+
+1. **Where are we now?** → `reconcile-docs` (make the on-disk docs equal reality)
+2. **Where do we go next?** → next-steps decomposition, **plan-only**
+3. **How does the next agent pick this up?** → `shift-handoff` (write the resume prompt)
+
+**Optional notes for the next session:** $ARGUMENTS
+
+---
+
+## Preflight — is a wind-down even warranted?
+
+Honestly check: did this session move **durable project state** (decisions made, code/config changed, state advanced, something to reconcile)? If it was trivial or throwaway (a quick question, a one-line fix, nothing a future reader needs), **stop and tell the user the wind-down isn't needed** — running it would write empty ceremony into the docs. Otherwise proceed.
+
+## Step 1 — `reconcile-docs` (capture reality first)
+
+Invoke the **reconcile-docs** skill. Bring `HANDOFF.md`, `PITFALLS.md` (and any `docs/` or `specs/` the session touched or invalidated) into **full agreement with the current system state**. The bar is the skill's read-through contract: an operator reading each document top to bottom, executing as they go, lands in the correct final state having hit **zero contradictions** — so resolve stale/contradicting passages at the source, don't just append.
+
+This runs **first** on purpose: steps 2 and 3 must build on accurate docs, not stale ones.
+
+## Step 2 — Next steps, PLAN-ONLY (define, do NOT execute)
+
+Define the **next** session's work as a persisted plan:
+
+- Slice the remaining / next work into **ordered, independently-verifiable sub-tasks**, each with a named done-check or oracle — a build tree with gating checks, not a vague to-do list.
+- Fold in anything from **$ARGUMENTS** above.
+- **Persist the plan where the next session will find it.** If the work belongs to an active spec-kit feature, that is the feature's `specs/<feature>/tasks.md`. Otherwise, a clearly-marked **"Next steps"** section in `HANDOFF.md`.
+
+**HARD GUARD — this is session close, not a launch.** Do **NOT** begin execution, do **NOT** dispatch subagents, do **NOT** start any long-horizon/unattended/"keep going overnight" run. You are *writing the plan the next session will execute*, not executing it. The deliverable is the persisted, dependency-ordered next-steps plan, full stop.
+
+## Step 3 — `shift-handoff` (write the resume prompt last)
+
+Invoke the **shift-handoff** skill to produce the warm compaction prompt for the next agent. Because it runs last, it can — and must — point at both prior outputs:
+
+- "The on-disk docs (`HANDOFF.md` / `PITFALLS.md`) are **current as of this session** — read them first."
+- "The **next steps** are defined in [`specs/<feature>/tasks.md` / `HANDOFF.md`] — start there."
+
+**Boundary note (intended, not duplication):** `reconcile-docs` makes the *file* `HANDOFF.md` correct for a **human operator**; `shift-handoff` writes a *chat prompt* for the **next agent**. Different artifacts, different consumers — both are wanted.
+
+## Close
+
+End with a tight state-check: what was reconciled (which docs, which contradictions resolved), where the next-steps plan now lives, and confirmation the handoff prompt is ready. Then it's safe to take the break.

claude_cost_tracker-0.1.0/.claude/commands/shift-handoff.md

@@ -0,0 +1,81 @@
+---
+description: Generate a warm, complete compaction prompt for the next agent taking over this session — covers project state, decisions locked, pitfalls, open work, and attitude. Use at the end of a productive session before taking a break.
+argument-hint: [optional: specific area to emphasize, e.g. "focus on the auth refactor" or "we stopped mid-migration"]
+---
+
+# Compaction Prompt
+
+We've had a great session together and we're wrapping up for now. Your job is to write a **compaction prompt** — a warm, self-contained briefing that the next agent (a fresh session with no memory of today) can paste as their very first message to pick up exactly where we left off.
+
+**Optional emphasis:** $ARGUMENTS
+
+---
+
+## What to gather before writing
+
+Read every one of these before producing a single word of the briefing. Do not skip any that exist:
+
+1. `HANDOFF.md` — handoff notes and in-progress context
+2. `PITFALLS.md` — hard-won lessons and known traps
+3. `git log --oneline -20` — the last 20 commits (what actually shipped today)
+4. Any open TODO/FIXME markers in recently touched files if you can identify them quickly
+
+If none of these files exist, synthesize from the current conversation context instead and note that the memory files are absent.
+
+---
+
+## Required sections in the compaction prompt
+
+Write the compaction prompt as a single cohesive message the next agent pastes verbatim. Structure it with these sections, in order:
+
+### 1. Welcome & project identity (2–4 sentences)
+
+Greet the incoming agent warmly. Name the project, its purpose, and why it matters. Set the tone: collaborative, no tribal knowledge, every assumption explained.
+
+### 2. What we accomplished this session (bullet list)
+
+Concrete, specific. Reference file names, function names, commit messages. Not vague like "made progress on auth" — specific like "extracted `useAuthToken` hook in `src/hooks/auth.ts` and wired it into the login form".
+
+### 3. Current state of the codebase (2–5 sentences + key file map)
+
+Where does the code stand right now? What's working, what's partial, what's intentionally left rough? List the 3–7 most important files/directories the incoming agent will need to touch or understand.
+
+### 4. The open work — next tasks in priority order (numbered list)
+
+What remains? Number them by priority. For each: one sentence of what, one sentence of why it matters, one sentence of where to start (file + line if possible).
+
+### 5. Decisions already locked — do not re-litigate (bullet list)
+
+Choices that were weighed and made. The incoming agent must not re-open these without the human's explicit instruction. For each: the decision + the reason it was made.
+
+### 6. Pitfalls and gotchas (bullet list)
+
+Everything in `PITFALLS.md` plus anything that burned us today. Format: **"The trap:"** what it looks like vs. **"The rule:"** what to do instead.
+
+### 7. Project conventions and attitude (short paragraph)
+
+How does this project work? Key naming conventions, file layout, commit style, push-back policy from `CLAUDE.md`. What attitude does the human want from their agent partner — when to push back vs. when to just execute?
+
+### 8. First action for the incoming agent
+
+One concrete instruction: the exact first thing they should do when they arrive. Not "get oriented" — something like "Run `npm test` to verify the baseline, then open `src/api/auth.ts:142` where the incomplete token refresh logic lives."
+
+---
+
+## Tone requirements
+
+- Warm and collegial — you are briefing a capable colleague, not writing documentation.
+- No tribal knowledge withheld. Explain every abbreviation, every convention, every "we always do X because…"
+- Honest about what is incomplete or uncertain — false confidence is a trap.
+- Concise within each section. Dense, not padded. The incoming agent is smart; they need facts and pointers, not re-explanations of basics.
+- End the compaction prompt with a short motivational note: acknowledge the work done, express confidence in the incoming agent, and wish them a productive shift.
+
+---
+
+## Output format
+
+Produce exactly two things:
+
+**First:** A brief note to the human (2–3 sentences) saying what you drew from and any gaps you noticed (e.g. "HANDOFF.md is missing — I synthesized from conversation context").
+
+**Second:** The full compaction prompt, fenced in a markdown code block so it can be copied cleanly. Label it clearly: `# Compaction Prompt — paste this as your first message in the new session`.

claude_cost_tracker-0.1.0/.claude/rules/git-conventions.md

@@ -0,0 +1,74 @@
+# Git Conventions
+
+## Branch Naming
+
+Land **big or possibly-breaking changes on a side branch first**, verify everything is
+stable there, and only then merge to `main` — keep `main` always working. (Small, safe
+changes may still go straight to `main`.) Side branches are named:
+
+```
+usr/<username>/<short-description>
+```
+
+- `<username>` is your git handle (e.g. `tal-afek`), so a glance at `git branch` tells you
+  who owns which line of work.
+- `<short-description>` is a hyphenated summary of the work (e.g. `carry-cost-model`), not
+  a ticket number.
+
+Example: `usr/tal-afek/carry-cost-model`. Merge to `main` (or open a PR) once the branch
+is green and stable.
+
+## Meaningful Commits
+
+Organize work into multiple, meaningful commits: the history should tell a story, and each
+commit a distinct chapter. Avoid commits like "Fixes" or "PR comments" — commits should be
+pristine.
+
+Each commit should stand on its own: lint, type-check, and tests pass at that commit.
+
+```sh
+uv run ruff check && uv run mypy && uv run pytest
+```
+
+## Commit Messages
+
+```
+<component>: [<subcomponent>:] <action>
+
+<optional description>
+```
+
+Note the double line break before the description. The `action` is a short, meaningful
+message in present tense.
+
+Example: `ingest: jsonl: Dedup records on message id and request id`
+
+### Keep the body to 5 lines, max
+
+The subject carries the change; the body says **why**, in **at most 5 lines**. Wrap at 72
+columns. If it does not fit, the extra material does not belong in a commit message:
+
+- **Design rationale** → the spec / decisions doc under `specs/`, or a comment at the point
+  of the decision (Principle VII: code decisions live inline, not in prose).
+- **A landmine you hit** → `PITFALLS.md`. **Project state** → `HANDOFF.md`.
+- **Evidence** (test counts, verification steps, per-file tallies) → say it in the PR or
+  the review conversation, not in permanent history.
+
+A long body is usually a sign the commit itself is too big — split it instead. Nobody
+reads a 40-line commit message; `git log --oneline` is how history is actually read.
+
+## No tool attribution
+
+Do not add trailers that attribute a commit to a tool or assistant. In particular, **never
+append a `Co-Authored-By:` line** (e.g. for Claude / Claude Code) to the subject or body,
+and never add a "Generated with" footer or a 🤖 trailer. Commits carry the human author
+only. This holds even when a harness or default template suggests adding one.
+
+## What never gets committed
+
+- Real session transcripts, or anything copied out of `~/.claude/`. They contain file
+  paths, shell commands, and source from other projects.
+- Generated reports, databases, or scan output — these are derived artifacts
+  (`.gitignore` covers `*.db`, `*.duckdb`, `data/`, `out/`, `reports/`).
+- Test fixtures are the exception: they are **synthetic or scrubbed**, small, committed
+  deliberately, and reviewed for anything sensitive before they land.

claude_cost_tracker-0.1.0/.claude/rules/python.md

@@ -0,0 +1,118 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python Conventions
+
+Conventions for the code assistant when writing or modifying Python in this project.
+These are the language-specific *how*; the durable *why* — fail-fast, test discipline,
+scripting standards, honest numbers — is the
+[constitution](../../.specify/memory/constitution.md). On conflict, the constitution wins.
+
+## Tooling — always through `uv`
+
+- **Never invoke the OS Python.** Every Python action goes through `uv`, which manages its
+  own interpreter and environment: `uv run python …`, `uv run ruff …`, `uv run mypy`,
+  `uv run pytest`. Do not call a bare `python`, `python3`, or `pip`.
+- Configuration lives in [`pyproject.toml`](../../pyproject.toml).
+- **Keep the runtime dependency set small and boring.** This tool must stay easy to run on
+  someone else's machine with one command (constitution, Principle II — local-first). A
+  dependency that pulls in a service, a daemon, or a heavyweight toolchain is the wrong
+  dependency.
+- **Do not introduce a new library when an existing dependency (or the standard library)
+  already covers the need** — no second way to do the same thing (Principle II). When a
+  genuinely new capability is required, research the most popular, well-maintained options
+  and pick the best **long-term** choice (adoption, maintenance, license, fit), not the
+  first hit.
+- Standalone scripts use [PEP 723](https://peps.python.org/pep-0723/) inline metadata so
+  they run via `uv run` with no project install.
+
+## Formatting & linting — `ruff`
+
+- `ruff` is both formatter and linter. Format with `uv run ruff format`; lint with
+  `uv run ruff check` (add `--fix` to auto-apply safe fixes).
+- **Line length 100.**
+- Code MUST be clean under `ruff check` before a change is done.
+
+## Type checking — `mypy` (non-strict)
+
+- **Type hints are required** on every function/method signature (parameters and return)
+  and on module-level constants where the type is not obvious.
+- `uv run mypy` MUST pass. It runs **non-strict** by decision — do not enable `--strict`
+  or `strict = true`.
+
+## Suppressions need human approval
+
+- Adding a `# noqa`, a `# type: ignore`, or any typing escape hatch (`cast`, `Any` to
+  dodge a checker) is a **deliberate deviation** and requires **explicit human approval
+  before it is added**. Fix the underlying issue first; suppress only when there is no
+  correct alternative, and justify it inline at the point of use.
+
+## Naming
+
+- **Functions, variables, module names:** `snake_case`.
+- **Classes:** `PascalCase`. **Constants:** `UPPER_SNAKE_CASE`.
+- **Internal helpers:** prefix with a single underscore (`_helper`).
+- Names are descriptive, not compressed — `cache_read_tokens`, not `crtok`.
+- **Domain terms match the central vocabulary.** Cost components, attribution policies,
+  and file categories use the names defined in the single authoritative config
+  (Principle IX) — never a local synonym invented at the call site.
+
+## Structure & style
+
+- Prefer small, single-purpose functions; validate arguments early and return early.
+- Prefer standard-library primitives and existing helpers before writing new ones
+  (KISS / reuse — Principle II). No second way to do the same thing.
+- Use `pathlib` over manual string path joining; use f-strings over `%` / `.format`.
+- Group imports stdlib → third-party → local; `ruff`'s import sorting enforces this.
+- **All imports and module-level globals/constants at the top of the file** — imports right
+  after the module docstring, then module constants and shared state (before any `def` /
+  `class` that uses them). **No imports inside functions or other scopes** (no lazy/local
+  imports); if a heavy or circular import tempts you into a function, fix the dependency
+  instead. Mutable module state is declared once, at the top, and mutated via `global`.
+- **Avoid unnecessary module-level globals.** Give state and constants the narrowest scope
+  that works; a value used by a single function belongs inside it. Mutable module state
+  must be justified.
+
+## Numeric handling
+
+- **Money is never a float in a stored or compared value.** Use integer minor units
+  (micro-dollars) or `Decimal` for anything persisted, summed, or asserted on; floats are
+  for display only. Rounding happens at the presentation edge, once.
+- **Sums must reconcile** (Principle X). When splitting a total across buckets, allocate
+  the remainder explicitly rather than letting rounding silently lose or invent value; a
+  breakdown that does not add up to its total is a show-stopper defect.
+- Token counts are integers. Never estimate one where an exact count is available in the
+  source data.
+
+## Fail-fast
+
+- Mirror the constitution's Scripting Standards: **exit immediately on error with a clear
+  message**; validate required tools/paths *before* mutating any state; keep scripts
+  **idempotent** (safe to re-run after a mid-run failure).
+- Raise on broken invariants rather than limping on — do not silently swallow exceptions.
+  Catch only where you can genuinely recover, and narrow the `except`.
+- **Malformed input records are named, not skipped in silence.** A transcript record that
+  cannot be parsed is counted and surfaced in the run summary.
+
+## Docstrings & comments
+
+- Public functions/classes get a one-line docstring stating contract (inputs, outputs,
+  side effects) when not obvious from the signature.
+- Comment **why**, not **what**. Keep comments current with the code.
+- **Attribution arithmetic carries its rationale inline** — the formula, the policy it
+  implements, and what the number means. This is the code a reader will most need to
+  audit (Principle X).
+
+## Tests
+
+- Definition of done for Python: `uv run ruff format`, `uv run ruff check`, `uv run mypy`,
+  and `uv run pytest` all clean.
+- **Prefer `pytest` fixtures for reusable setup/teardown** — any setup, resource, or
+  helper state that can and should be shared belongs in a fixture, not copy-pasted across
+  tests. Always choose the **correct scope** for each fixture (`function`, `class`,
+  `module`, `session`): the narrowest scope that still shares the work, balancing
+  isolation against setup cost.
+- Fixture transcripts live in the test tree and are committed. Never point a test at the
+  developer's real `~/.claude/` data — it is not reproducible and it is not shareable.

claude_cost_tracker-0.1.0/.claude/skills/claude-md-standards/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: claude-md-standards
+description: >-
+  Create, lint, edit, or review CLAUDE.md files (and AGENTS.md — near-identical
+  format, lessons transfer) against industry-wide best practices. Use whenever
+  the user wants to write, audit, clean up, shrink, split, refactor, or
+  "improve" a CLAUDE.md / AGENTS.md / agent-instruction / agent-memory file, set
+  up `.claude/rules/`, bootstrap agent context for a repo that has none, or asks
+  whether their CLAUDE.md is any good — even if they just say "my CLAUDE.md is
+  too long", "check my agent instructions", or "how should I structure this".
+  Ships a real linter script, so also use it to mechanically check a file for
+  secrets, dangerous example commands, broken @imports, size/budget, and vague
+  instructions.
+---
+
+# Authoring and linting CLAUDE.md files
+
+A `CLAUDE.md` (and its cross-tool cousin `AGENTS.md`) is persistent context fed
+to a coding agent at the *start of every session*. That framing drives every
+rule here: a line in this file is not documentation a human reads once — it is
+re-transmitted to a model on every run and spends part of a finite attention and
+token budget each time. So the goal is never "write down everything true about
+the repo"; it is **the smallest set of high-signal, checkable instructions the
+agent genuinely cannot infer on its own.** Less is more, but *specific* less.
+
+The same file is read as context by other tools too, so the advice below is
+Claude-Code-first but calls out where behavior is tool-specific.
+
+## Which job is this?
+
+Route to the matching section; each points at the deeper reference file.
+
+| The user wants to…                                   | Go to        |
+|------------------------------------------------------|--------------|
+| Check / audit / "is this good?" an existing file     | **Lint**     |
+| Shrink, split, dedupe, de-stale a bloated file       | **Edit/refactor** |
+| Write one for a repo that has none                   | **Create**   |
+
+More than one can apply (create → then lint the draft; lint → then refactor what
+it found). Do them in that order.
+
+## Core principles (the "why" behind every rule)
+
+Internalize these five; the specific rules are downstream of them.
+
+1. **Context, not configuration.** Claude *reads* CLAUDE.md as guidance — it does
+   not *enforce* it. Anything that must be guaranteed (tests run before commit,
+   formatting) belongs in a **hook** or CI check, not in prose here. Telling the
+   file to do a linter's job is the single most common wasted instruction.
+2. **Specific and checkable beats general and true.** "Use React 18 with the App
+   Router" and one real code snippet beat "follow front-end best practices."
+   Anything the model already knows, or can't verify, is noise.
+3. **Every line costs budget every session.** Frontier models track on the order
+   of a couple hundred discrete instructions reliably and degrade past that; the
+   tool's own system prompt already spends some of that before your file loads.
+   Short is not aesthetic — it is functional.
+4. **Put detail where it loads only when needed.** Root CLAUDE.md loads every
+   session; a **nested** `CLAUDE.md` loads only when a file in its directory is
+   touched; a `.claude/rules/*.md` with a `paths:` glob loads only for matching
+   files. Scope detail down the tree instead of piling it into the root.
+5. **It rots.** An unowned file that only grows is the default failure mode. Give
+   it an owner, review changes to it like code, and re-lint periodically.
+
+## Lint
+
+Run the bundled linter — it does the mechanical checks deterministically so you
+can spend judgment on the rest:
+
+```sh
+python .claude/skills/claude-md-standards/scripts/lint_claude_md.py <file-or-dir> --opinionated
+```
+
+- Pass a **directory** to scan the whole repo (root + nested CLAUDE.md +
+  `.claude/rules/*.md`) and get cross-file duplicate-content detection. It prunes
+  `.git`, `node_modules`, `obj`, `build`, etc., so it is safe to point at a repo
+  root — but do **not** point it above the repo (see the devpod filesystem rules).
+- `--opinionated` adds the lower-confidence checks (hedging, filler,
+  instruction-count). Drop it for only the high-confidence findings.
+- `--json` for machine-readable output; `--strict` to make warnings fail the exit
+  code; `--no-strong` for hard rules only. Thresholds (`--max-lines`,
+  `--error-lines`, `--import-depth`, …) are all configurable per project.
+
+**Interpreting results — respect the confidence tiers** (this is deliberate; do
+not "fix" everything with equal force):
+
+- **`error` / `[hard]`** — mechanical and near-certain (secrets, dangerous
+  example commands, broken/circular `@import`s). Fix these first and always.
+- **`warning` / `[strong]`** — multi-source consensus (size budget, vague
+  instructions, unscoped rule files, content placement). Act on them by default,
+  but the *thresholds* are project preferences — a team may legitimately set
+  `--max-lines 300`.
+- **`info` / `[opinionated]`** — one credible source, or genuinely unsolved
+  (hedging, filler, staleness). Raise them as suggestions; never present them as
+  hard rules.
+
+Two important things the script **cannot** judge and you must, by reading the
+file: **staleness** (does an inline snippet still match the real source? prefer a
+`file:line` pointer over a copy) and **whether "necessary" content is truly
+necessary** (could the model infer it from the code?). The full rule catalog,
+with the source and confidence behind each rule, is in
+[`references/lint-checklist.md`](references/lint-checklist.md) — read it when you
+need to explain or justify a finding, or tune what runs.
+
+## Edit / refactor
+
+For a bloated or stale file, follow the measure → decide → dedupe → re-measure
+loop. The key decision is **why** it's oversized, which picks the fix — and the
+traps (especially that `@import` is *not* lazy loading) are easy to get wrong.
+The full decision tree lives in
+[`references/workflows.md`](references/workflows.md#editrefactor); the short form:
+
+1. **Lint first** to get numbers and clear all `error`s before touching structure.
+2. **Route each oversized chunk by cause:**
+   - Generic / inferable content → **delete** it (highest leverage, zero loss).
+   - Necessary but *directory-specific* detail → move to a **nested `CLAUDE.md`**
+     (loads on demand).
+   - Necessary, *cross-cutting*, topic-coherent detail → move to
+     **`.claude/rules/<topic>.md` with a `paths:` glob** (loads only for matching
+     files).
+   - Deep reference rarely needed in full → move to a docs file and leave a
+     **one-line pointer** (progressive disclosure).
+   - **Trap:** `@import` still loads the imported file into context at launch — it
+     organizes *source text*, it does **not** reduce what loads. Only nested files
+     and path-scoped rules are truly lazy.
+3. **Dedupe across the hierarchy** — delete anything a child restates from an
+   ancestor; inheritance is automatic (root-to-cwd concatenation).
+4. **Re-lint** to confirm you actually reduced size, not just moved bulk around.
+
+## Create
+
+**There is a real, unresolved disagreement here — surface it, don't silently pick
+a side.** Anthropic's docs say run `/init` and refine the output; a credible
+practitioner camp argues *against* auto-generation because a bad line in this
+file compounds across every future session, unlike a bad line of ordinary code.
+
+Reconcile the two by treating any generated draft as **raw material that must pass
+the same review + lint gate a hand-authored file would**:
+
+1. **Inspect, don't assume** — build/test commands, stack + versions, and
+   directory layout are discoverable from manifests, CI config, and `README.md`
+   (this is what `/init` already reads; make it explicit). Also fold in any
+   existing `.cursorrules`, `AGENTS.md`, or `.github/copilot-instructions.md`.
+2. **Ask the user, don't infer** — repository etiquette (branch/commit/PR
+   conventions), deliberate boundaries ("never touch X", "ask before Y"), and
+   whether smaller/non-frontier models will run against this file (it changes the
+   instruction budget).
+3. **Draft from the template** in
+   [`references/templates.md`](references/templates.md), using the copyable
+   starters in [`assets/`](assets/). Keep only what survives the "can the agent
+   infer this?" filter.
+4. **Lint the draft before calling it done** — this is the mechanism that
+   resolves the tension: a generated draft that passes the same gate has already
+   had its generic and vague content flagged out.
+
+Full workflow, including exactly what to inspect/ask/infer, is in
+[`references/workflows.md`](references/workflows.md#create-from-scratch).
+
+## Structure & templates
+
+Section order and the include/exclude line for a root file, how a nested file
+differs, and the ready-to-paste "✅ Always / ⚠️ Ask first / 🚫 Never" boundaries
+block are all in [`references/templates.md`](references/templates.md). Copyable
+skeletons: [`assets/root-CLAUDE.md`](assets/root-CLAUDE.md) and
+[`assets/nested-CLAUDE.md`](assets/nested-CLAUDE.md).
+
+## Anti-patterns
+
+Ten common failure modes with their fixes (treating the file as enforced config;
+unowned append-only growth; stuffing everything in "just in case"; using it as a
+linter; `@import`-as-lazy-loading; secrets; cross-file duplication; auto-generate-
+and-forget; assuming precedence is identical across tools) are tabulated in
+[`references/workflows.md`](references/workflows.md#anti-patterns). Recognize these
+proactively when reviewing a file, not only when asked.

claude_cost_tracker-0.1.0/.claude/skills/claude-md-standards/assets/nested-CLAUDE.md

@@ -0,0 +1,26 @@
+<!--
+  Nested (per-directory) CLAUDE.md starter. Place inside the subdirectory it
+  governs, e.g. src/infra/lock/CLAUDE.md. It loads ONLY when the agent touches a
+  file in this subtree, so it can be denser than the root file.
+  RULE: include only what is specific to THIS directory. Do NOT restate project-
+  wide conventions — they are inherited from the root file automatically.
+-->
+
+# [submodule name]
+
+This file governs `[path/to/this/dir/]` only.
+
+[One or two sentences: what this component is and the one non-obvious thing an
+agent must know before editing it.]
+
+## Local conventions & invariants
+
+[Directory-specific rules, gotchas, and invariants that are NOT true elsewhere in
+the repo. Example: "Everything reachable from the signal handler must be
+async-signal-safe — no malloc/printf/locks." Include a concrete example where it
+helps.]
+
+## Adding to this component
+
+[If there's a specific procedure for extending this module — a list to append to,
+a test to register — state it step by step.]

claude_cost_tracker-0.1.0/.claude/skills/claude-md-standards/assets/root-CLAUDE.md

@@ -0,0 +1,49 @@
+<!--
+  Root CLAUDE.md starter. Copy to the repo root as CLAUDE.md, fill the brackets,
+  DELETE any section that doesn't earn its place, then run the linter:
+    python .claude/skills/claude-md-standards/scripts/lint_claude_md.py CLAUDE.md --opinionated
+  Keep it short: aim under ~200 lines. Delete anything the agent can infer from code.
+  (This HTML comment is stripped before the file enters context — zero token cost.)
+-->
+
+# [Project name]
+
+[One or two sentences: what this project is and its purpose, in plain language.]
+
+## Stack & layout
+
+- **Stack:** [languages + frameworks WITH versions, e.g. "Python 3.12, FastAPI, Postgres 16"]
+- **Layout:** [top-level dirs that matter, e.g. "`src/` app, `tests/` pytest, `infra/` terraform"]
+- [For a monorepo: name the apps and shared packages.]
+
+## Commands
+
+```sh
+[build command]        # e.g. make build
+[test command]         # e.g. pytest -q  (and: how to run ONE test)
+[run/dev command]      # e.g. npm run dev -- --port 3000
+[lint/format command]  # e.g. make fmt
+```
+
+## Conventions
+
+[ONLY conventions that differ from language/framework defaults. One real example
+beats a paragraph. Let a formatter/linter own the rest.]
+
+## Testing
+
+[Preferred runner, how to run a single test, coverage expectation.]
+
+## Git workflow
+
+[Branch naming, commit message format, PR/review expectations.]
+
+## Boundaries
+
+- ✅ **Always**: [e.g. run the formatter before committing; add a test with each fix]
+- ⚠️ **Ask first**: [e.g. adding a dependency; changing the public API; a DB migration]
+- 🚫 **Never**: [e.g. commit secrets; edit generated files; force-push main]
+
+## Deeper docs (read when relevant)
+
+- `[docs/foo.md]` — [one line: what it covers and when to read it]

claude_cost_tracker-0.1.0/.claude/skills/claude-md-standards/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "skill_name": "claude-md",
+  "evals": [
+    {
+      "id": 0,
+      "name": "lint-bad-file",
+      "prompt": "Can you review my CLAUDE.md and tell me what's wrong with it? Path: <FIX>/lint/CLAUDE.md. Write your review to review.md in the output dir.",
+      "expected_output": "A review that flags the hardcoded AWS + GitHub secrets, the rm -rf / and curl|bash example commands, the broken @import, the vague instructions, and the oversized/no-real-content problems; severity-ranked.",
+      "files": ["fixtures/lint/CLAUDE.md"]
+    },
+    {
+      "id": 1,
+      "name": "refactor-bloated",
+      "prompt": "My CLAUDE.md has grown huge and messy. Refactor it to follow best practices. Path: <FIX>/refactor/CLAUDE.md. Put the rewritten CLAUDE.md (and any split-out files) in the output dir.",
+      "expected_output": "A much shorter root CLAUDE.md; generic best-practice bloat deleted; language-specific rules moved to path-scoped .claude/rules/ files; the huge SQL schema replaced by a pointer; stale 2021 deploy notes flagged/removed.",
+      "files": ["fixtures/refactor/CLAUDE.md"]
+    },
+    {
+      "id": 2,
+      "name": "create-from-scratch",
+      "prompt": "This repo has no CLAUDE.md. Create a good one. The repo is at <FIX>/create/ (a Next.js + TypeScript storefront).",
+      "expected_output": "A concise root CLAUDE.md with real commands (dev/build/test/lint from package.json), stack+versions, a boundaries section, no invented facts, under ~200 lines; ideally notes what it had to assume vs. would ask the user.",
+      "files": ["fixtures/create/"]
+    }
+  ]
+}