liteagents 3.0.0 → 3.6.0

package/packages/ampcode/{commands/stash.md → skills/stash/SKILL.md}

@@ -1,8 +1,9 @@
 ---
 name: stash
 description: Stash session context [name]
-usage: /stash ["optional-name"]
 argument-hint: [optional stash name]
+allowed-tools: Read, Grep, Glob
+disable-model-invocation: true
 ---
 
 Save session context for compaction recovery or handoffs.

package/packages/{claude/commands/test-generate.md → ampcode/skills/test-generate/SKILL.md}

@@ -1,9 +1,9 @@
 ---
 name: test-generate
 description: Generate and run tests [file]
-usage: /test-generate <file>
 argument-hint: [file or symbol to test]
 allowed-tools: Read, Edit, Write, Grep, Glob, Bash(npm test:*), Bash(npx jest:*), Bash(npx vitest:*), Bash(pnpm test:*), Bash(yarn test:*), Bash(pytest:*), Bash(python:*), Bash(go test:*), Bash(cargo test:*), Bash(make test:*)
+disable-model-invocation: true
 ---
 Generate tests for $ARGUMENTS, then run them. This is a generate → run →
 verify loop, not just file generation.
@@ -28,7 +28,7 @@ Match existing patterns:
   or new test-runner config.
 - Do **not** add test-only public methods or exports to production code to
   make a test possible — if the test wants a hook the prod code doesn't
-  expose, stop and ask (`test-traps` territory).
+  expose, stop and ask.
 
 ## 3. Run
 Execute the project's real test command, scoped to just the new tests

package/packages/ampcode/variants.json

@@ -1,8 +1,8 @@
 {
   "pro": {
     "name": "Pro",
-    "description": "Complete installation with all agents and commands",
+    "description": "Complete installation with all agents and skills",
     "agents": "*",
-    "commands": "*"
+    "skills": "*"
   }
 }

package/packages/claude/CLAUDE.md

@@ -21,26 +21,16 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
 | ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
 
-### Skills (8 total)
-
-| ID | Description | Usage | Auto |
-|---|---|---|---|
-| brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> | false |
-| trace-back | Systematically traces bugs backward through call stack to identify source | /trace-back <issue-description> | false |
-| live-canvas | Conduct design interviews, generate UI variations, collect live click-to-annotate feedback via a browser overlay that streams into the session | /live-canvas | false |
-| skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
-| debug-method | Four-phase debugging framework - investigate root cause before any fixes | /debug-method <bug-or-error-description> | false |
-| tdd-flow | Write test first, watch it fail, write minimal code to pass | /tdd-flow <feature-or-behavior-to-test> | true |
-| test-traps | Prevents testing mock behavior and production pollution with test-only methods | /test-traps <testing-scenario> | true |
-| verify-done | Requires running verification commands before making any success claims | /verify-done <work-to-verify> | true |
-
-### Commands (10 total)
+### Skills (13 total)
 
 | ID | Description | Usage |
 |---|---|---|
+| brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> |
+| root-cause | Find the cause before changing code - evidence, backward trace, one hypothesis, fix at the source | /root-cause <bug-or-error-description> |
+| live-canvas | Conduct design interviews, generate UI variations, collect live click-to-annotate feedback via a browser overlay that streams into the session | /live-canvas |
+| skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> |
 | docs-builder | Reorg a docs corpus, split an oversized doc, search it, keep pages current, index them | /docs-builder [reorg \| cleanup <file.md>] |
-| optimize | Analyze and optimize performance issues | /optimize <target-area> |
-| refactor | Refactor code while maintaining behavior and tests | /refactor <code-section> |
+| refactor | Refactor and optimize code while maintaining behavior and tests | /refactor <code-section> |
 | remember | Consolidate stashes + friction into project memory | /remember |
 | branch-review | Pre-merge review: general review + full security audit, verify pass, no fixes | /branch-review [target] [level] |
 | security | Security audit — recurring six, injection, auth, trust boundaries; reports, never fixes | /security [target] |
@@ -52,4 +42,7 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 All resources are auto-discovered from frontmatter in their respective directories:
 - **Agents**: `./agents/*.md`
 - **Skills**: `./skills/*/SKILL.md`
-- **Commands**: `./commands/*.md`
+
+Claude Code merged custom commands into skills, so every capability ships as
+`skills/<name>/SKILL.md`. The nine that are deliberate actions carry
+`disable-model-invocation: true`, so Claude only runs them when you type them.

package/packages/claude/agents/code-developer.md

@@ -37,29 +37,26 @@ digraph CodeDeveloper {
   work_type [label="Work type?", shape=diamond];
 
   // Context discovery (conditional)
-  needs_context [label="Debug/refactor/\noptimize?", shape=diamond];
+  needs_context [label="Debug or\nrefactor?", shape=diamond];
   context_discovery [label="Context Discovery\n(search related code,\ndeps, usages)", fillcolor=lightyellow];
 
   // Debug path
-  use_debug [label="Use /debug-method\nor /trace-back"];
+  use_debug [label="Use /root-cause"];
 
   // Refactor path
   use_refactor [label="Use /refactor"];
 
-  // Optimize path
-  use_optimize [label="Use /optimize"];
-
   // Implement path
   implement [label="Implement changes"];
 
   // Conditional testing
   tdd_needed [label="TDD specified\nor tests needed?", shape=diamond];
-  use_tdd [label="Use /tdd-flow\nor /test-generate"];
+  use_tdd [label="Use /test-generate"];
 
   // Validation
   run_validations [label="Run validations\n(lint, build, tests)"];
   validations_pass [label="Pass?", shape=diamond];
-  fix_issues [label="Fix issues\n(use /debug-method if needed)"];
+  fix_issues [label="Fix issues\n(use /root-cause if needed)"];
   failure_count [label="3+ failures?", shape=diamond];
 
   // Security check
@@ -76,7 +73,7 @@ digraph CodeDeveloper {
 
   // Review and complete
   code_review [label="Run /branch-review"];
-  verification [label="Run /verify-done", fillcolor=orange];
+  verification [label="Run the proof", fillcolor=orange];
 
   // Story-specific
   update_story [label="Update story\n(checkbox, changelog)"];
@@ -100,12 +97,10 @@ digraph CodeDeveloper {
 
   work_type -> use_debug [label="debug"];
   work_type -> use_refactor [label="refactor"];
-  work_type -> use_optimize [label="optimize"];
   work_type -> implement [label="implement"];
 
   use_debug -> implement;
   use_refactor -> implement;
-  use_optimize -> implement;
 
   implement -> tdd_needed;
   tdd_needed -> use_tdd [label="YES"];
@@ -184,14 +179,13 @@ All require `*` prefix. Invocation commands in table above. Additional:
 
 | Situation | Delegate To |
 |-----------|-------------|
-| Bug encountered | `/debug-method` (use `/trace-back` when the error is deep in the stack) |
-| Error deep in stack | `/trace-back` |
-| Refactoring code | `/refactor` |
-| Need tests (when required) | `/test-generate` or `/tdd-flow` |
-| Writing any test | `/test-traps` (avoid mocks, production pollution) |
-| Before completion | `/verify-done` |
+| Bug encountered | `/root-cause` |
+| Error deep in stack | `/root-cause` (Phase 1, step 5) |
+| Refactoring code, or a perf problem | `/refactor` (its perf pass is on by default) |
+| Need tests (when required) | `/test-generate` |
+| Writing any test | AGENT_RULES.md → Testing Standards |
+| Before completion | Run the proof and read its output |
 | After code changes | `/security` |
 | Task complete / general review | `/branch-review` (reviews the branch + full security audit, verifies claims, reports findings — never fixes) |
-| Performance issues | `/optimize` |
 
 You are an autonomous implementation specialist. Execute with precision, delegate appropriately, and communicate clearly when you need guidance or encounter blockers.

package/packages/claude/agents/orchestrator.md

@@ -65,9 +65,8 @@ On-demand, read from these locations:
 
 | Resource | Global Paths | Local Path |
 |----------|--------------|------------|
-| Agents |  `~/.claude/agents/*.md`| `./.claude/agents/*.md` |
-| Commands | `~/.claude/commands/*.md`| `./.claude/commands/*.md` |
-| Skills | `~/.claude/skills/*/SKILL.md` | `./.claude/skills/*/SKILL.md`  |
+| Agents | `~/.claude/agents/*.md` | `./.claude/agents/*.md` |
+| Skills | `~/.claude/skills/*/SKILL.md` | `./.claude/skills/*/SKILL.md` |
 
 Parse frontmatter for `name`, `description`, `when_to_use`. Present as numbered list.
 

package/packages/claude/agents/quality-assurance.md

@@ -59,13 +59,15 @@ digraph QualityAssurance {
 
 Before any analysis, read (if exists):
 - `CLAUDE.md` - Project instructions, patterns, conventions
+<!-- mirror:literal:start — names every tool's config file on purpose -->
 - `AGENT.md` / `AGENTS.md` - Agent configurations
+<!-- mirror:literal:end -->
 - `README.md` - Project overview
 - Test config files (`jest.config`, `pytest.ini`, etc.)
 
 ## Slash Commands Available
 
-Use these during analysis: `/branch-review`, `/security`, `/verify-done`
+Use these during analysis: `/branch-review`, `/security`
 
 ## Analysis Areas
 

package/packages/claude/skills/brainstorming/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: brainstorming
 description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
-usage: /brainstorming <session-type> <topic>
-auto_trigger: false
+allowed-tools: Read, Grep, Glob
 ---
 
 # Brainstorming Ideas Into Designs

package/packages/claude/{commands/branch-review.md → skills/branch-review/SKILL.md}

@@ -1,9 +1,9 @@
 ---
 name: branch-review
 description: Review a branch before merge [target] [level]
-usage: /branch-review [target] [low|medium|high|max]
 argument-hint: [file, branch (e.g. main), range (main..HEAD), or empty] [effort level]
 allowed-tools: Read, Grep, Glob, Agent, Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git status:*), Bash(git grep:*), Bash(git rev-parse:*), Bash(git merge-base:*), Bash(rg:*)
+disable-model-invocation: true
 ---
 Pre-merge review gate. Two stages — **general review** then a **full security
 audit** — followed by an adversarial verify pass. It **never edits code**: it
@@ -100,6 +100,20 @@ was actually read rather than assuming.
 you owe an answer on — take both from the file, never from the orchestrator's
 recollection, for the same reason `/release` does. Then:
 
+- **First, check the record belongs to this branch.** There is one record file
+  per repo, not one per branch. Validate `<that sha>` first with
+  `git rev-parse --verify <that sha>` — a value that fails this (e.g. a
+  corrupted or hand-edited record, or one starting with `-`, which git would
+  otherwise parse as an option) is a malformed record; treat it exactly as
+  **No file** below. If it validates, and its `branch:` line differs from the
+  current branch, or `git merge-base --is-ancestor <that sha> HEAD` exits
+  non-zero, the record describes a different or rewritten history — treat it
+  exactly as **No file** below and review the whole branch. Skipping this
+  resolves `<that sha>..HEAD` against a merged, renamed, or rebased sha, which
+  is not a subset of this branch but a range that never existed. Check both:
+  the branch name catches a switch, the ancestry check catches a rebase or
+  squash under the same name. Otherwise:
+
 - **`sha:` ≠ HEAD** → this is a re-review. Target the range
   `<that sha>..HEAD`. Stage 1 reads only the commits since, and stage 3
   re-verifies each recorded blocker as fixed, unfixed, or dismissed with a

package/packages/{ampcode/commands/docs-builder.md → claude/skills/docs-builder/SKILL.md}

@@ -1,9 +1,9 @@
 ---
 name: docs-builder
 description: Reorg a docs corpus, split an oversized doc, search it, keep pages current, index them
-usage: /docs-builder [reorg | cleanup <file.md> | search <query words...>]
 argument-hint: [reorg | cleanup <file.md> | search <query words...> — empty asks first run vs. drift]
 allowed-tools: Read, Write, Edit, Grep, Glob, Task, AskUserQuestion, Bash(node:*), Bash(git:*), Bash(rg:*)
+disable-model-invocation: true
 ---
 
 # docs-builder
@@ -152,7 +152,7 @@ marked `core: true`.
 
 ```
 docs/
-  README.md          entry point, referenced from AGENT.md
+  README.md          entry point, referenced from CLAUDE.md
   index.md           GENERATED by index-flat/apply-reorg/cleanup-apply. never hand-edited.
                      READER-FACING. The WHOLE-CORPUS map — the only file with a completeness
                      guarantee. ## Product, ## Logs, ## Archive.
@@ -340,7 +340,7 @@ files with no gate at all.
 ### 3. Apply (script) — an ALREADY-CLASSIFIED plan, verified moves, survives a bad file
 
 ```bash
-CONFIG=AGENT.md node $DB apply-reorg   # defaults to the plan above
+node $DB apply-reorg      # defaults to the plan above
 ```
 
 **Refuses outright if any row's `bucket` is still empty** — the interview-has-not-happened
@@ -362,13 +362,13 @@ a pointer to re-run `discover`.
 - **After the scan, `apply-reorg` writes `docs/index.md` itself** — it calls `index-flat`
   (see below) automatically, so a reorg-only corpus ends up indexed without a second command.
   Runs every time, unconditionally.
-- **`apply-reorg` also writes the docs pointer into `AGENT.md`** — a marker-wrapped
+- **`apply-reorg` also writes the docs pointer into `CLAUDE.md`** — a marker-wrapped
   `<!-- DOCS_INDEX:START -->`/`<!-- DOCS_INDEX:END -->` block naming `docs/index.md` as a
   **plain path, never an `@`-reference**: hot-loading a 100-row index into every session is
   exactly what this avoids. The block also carries the `/docs-builder search` hint, and is
   static — it never varies with row count, so a re-run rewrites identical bytes. Idempotent:
   an existing block is replaced in place, never duplicated; other content is left alone.
-  The target is `CONFIG=` (default `CLAUDE.md`); this package uses `CONFIG=AGENT.md`.
+  The target is `CONFIG=` (default `CLAUDE.md`); this package uses `CONFIG=CLAUDE.md`.
 - **The moves land STAGED in your git index — commit them promptly.** `git mv` stages each
   rename immediately (that is what preserves history), so when `apply-reorg` returns the repo
   is holding N staged renames. Any other session's `git add -A` or `git commit -a` will absorb
@@ -472,7 +472,7 @@ document in place.
 
 `cleanup` takes exactly one named file — never zero, never more than one — and refuses
 cleanly (exit non-zero) if the file doesn't exist, isn't a `.md`, or is one of the protected
-entry-point docs (README, AGENT.md, etc.). It prints the file's line count and an estimated
+entry-point docs (README, CLAUDE.md, etc.). It prints the file's line count and an estimated
 write cost (the same cost law `plan` uses in step 4 below, priced as a 1-page floor since the
 real page count isn't known until the model groups sections in step 2), runs step 1 (scan)
 below for you, then measures the document's heading shape and **stops**:
@@ -687,7 +687,7 @@ once (old path, archive, and the new pages), which is duplication, not cleanup.
 Archiving is also what frees the original's path for the **core page**, which `cleanup-apply`
 then relocates there from `PAGES` (settled 2026-08-24). Splitting is internal maintenance
 bookkeeping: a reader who knows where "the PRD" lives should still find it there afterwards.
-MEASURED, real (bareagent): before this, a split left `AGENT.md`'s canonical-PRD reference
+MEASURED, real (bareagent): before this, a split left `CLAUDE.md`'s canonical-PRD reference
 pointing into `docs/archive/`, which reads as "the canonical spec is archived" — backwards.
 
 **Exit codes are not interchangeable — they mean two opposite outcomes:**

package/packages/claude/skills/live-canvas/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: live-canvas
 description: Conduct design interviews, generate UI variations, and collect live click-to-annotate feedback that streams into the session so edits land without leaving the browser. Use when the user wants rapid iterative UI refinement, not just batched feedback.
+allowed-tools: Read, Grep, Glob
 ---
 
 # Live Canvas Skill
@@ -26,7 +27,7 @@ Live Canvas supports two feedback transports. **The user picks every time** —
 
 ### Host detection — do this first
 
-This SKILL.md is the Claude Code variant of the skill. Same content is mirrored as docs for Droid/Amp/Opencode under `packages/<tool>/commands/live-canvas/`, but those tools don't support the MCP channel.
+This SKILL.md is the Claude Code variant of the skill. Same content is mirrored as docs for Droid/Amp/Opencode under `packages/<tool>/` beside the other capabilities, but those tools don't support the MCP channel.
 
 **If running under Droid, Amp, or Opencode (not Claude Code):**
 - Skip the mode question entirely.
@@ -109,6 +110,8 @@ Or pick JSON now to stay in this session — feedback gets written to a file
 you paste back here. No relaunch needed.
 ```
 
+<!-- mirror:literal:start — Live mode is the Claude Code MCP plugin; these are
+     Claude's real paths in every kit, because no other tool can install it -->
 **Case C — first-time setup block:**
 
 ```
@@ -125,6 +128,7 @@ Live mode needs a one-time install. Two steps:
 That's it — once the plugin is installed, /live-canvas in any session can
 claim the channel. Re-run /live-canvas and pick Live.
 ```
+<!-- mirror:literal:end -->
 
 Do not try to run any of these commands yourself. Three reasons:
 1. The `/plugin` steps are Claude Code slash commands — not doable from inside a running session.

package/packages/claude/{commands/refactor.md → skills/refactor/SKILL.md}

@@ -1,11 +1,12 @@
 ---
 name: refactor
-description: Refactor [code]
-usage: /refactor <code-section> | /refactor (no args = fix-ledger mode)
+description: Refactor and optimize [code]
 argument-hint: [file-or-function, or empty for the fix ledger]
 allowed-tools: Read, Edit, Grep, Glob, Bash(npm test:*), Bash(npx jest:*), Bash(npx vitest:*), Bash(pnpm test:*), Bash(yarn test:*), Bash(pytest:*), Bash(python:*), Bash(go test:*), Bash(cargo test:*), Bash(make test:*), Bash(git diff:*), Bash(git grep:*), Bash(git status:*), Bash(git rev-parse:*), Bash(git switch:*)
+disable-model-invocation: true
 ---
-Refactor $ARGUMENTS.
+Refactor $ARGUMENTS. A targeted refactor includes the performance pass
+below — it is on by default, not a separate command.
 
 ## Guardrails
 - **Spawn a worker and explicitly select your tool's mid tier.** State the
@@ -87,6 +88,35 @@ refactor and how to close each item.
 - Apply DRY
 - Better naming
 - Smaller functions (single responsibility)
+- Remove needless work — the performance pass below
+
+## Performance — part of every targeted refactor
+When `$ARGUMENTS` names a target, look for wasted work as well as messy
+work: time and space complexity, N+1 queries, I/O inside a loop, needless
+allocations, the same value recomputed repeatedly.
+
+**Ground every finding before you touch it.** Performance claims are easy
+to invent. A finding counts as **confirmed** only with at least one of:
+- a profile, benchmark or log line showing call frequency or duration,
+- the path sits on an obvious hot loop or per-request handler with real
+  volume,
+- the user supplied evidence in the request.
+
+Without one of those it is **uncertain — report it, do not optimise it.**
+Speculative optimisation is scope creep with a stopwatch.
+
+Fix confirmed findings under the same constraints as any other refactor:
+minimal change, one obvious shape, no behaviour change, no API change.
+After each such edit, re-read the changed region and confirm it still
+computes the same answer — a perf change that quietly alters semantics is
+the worst kind. Report per finding: **location** (`file:line`), **cost**
+(concrete — "N+1 over ~1k rows on every page load", not "could be
+faster"), **change**, **expected improvement**, **trade-off**
+(readability / memory / consistency).
+
+In ledger mode the surviving bullets are the whole scope — do not add
+perf findings of your own. One you notice goes back to the orchestrator
+as a new bullet, like any other side finding.
 
 ## Constraints
 - **NO behavior changes**
@@ -120,8 +150,20 @@ honest way to know is to run them.
 - the change is **bigger than the user asked for** (scope creep —
   unrelated cleanups, formatting, comment edits). Confirm before
   applying.
+- a perf fix has **multiple reasonable shapes** (cache vs precompute vs
+  batch vs paginate vs index) — present the options with trade-offs, not
+  a chosen path.
+- a perf fix trades **correctness for speed** (lossy approximation,
+  weaker or eventual consistency) — even when it is "obviously" faster.
+- a perf fix touches **concurrency primitives** (locks, atomics,
+  ordering) — easy to introduce a race.
+- a perf fix changes a **DB schema, response shape or caller contract**.
 
 Final report:
 - **refactor done, tests N pass / 0 fail** — ready, OR
 - **refactor done, but K tests fail** — awaiting direction (revert /
   patch / update test).
+
+Plus the performance pass: **confirmed-and-fixed** · **confirmed-but-asking**
+(why + options) · **uncertain** (what profiling or data would settle it) ·
+**none found**.

package/packages/claude/{commands/release.md → skills/release/SKILL.md}

@@ -1,8 +1,8 @@
 ---
 name: release
 description: Verify, sweep docs, cut a version — then hand the release sequence back
-usage: /release
 allowed-tools: Read, Grep, Glob, Edit, Write, Agent, Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git fetch:*), Bash(git add:*), Bash(git commit:*), Bash(git rev-parse:*), Bash(git merge-base:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(pytest:*), Bash(python:*), Bash(go:*), Bash(cargo:*), Bash(make:*)
+disable-model-invocation: true
 ---
 Release **preparation** orchestrator for the **current branch**. It runs your
 existing pre-deploy gate, sweeps the docs, bumps the version and commits —

package/packages/{ampcode/commands → claude/skills}/remember/AGENT_RULES.md

@@ -9,7 +9,7 @@
 6. [Environment](#environment)
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
-9. [AGENT.md Stub](#agentmd-stub)
+9. [CLAUDE.md Stub](#claudemd-stub)
 
 ---
 
@@ -59,7 +59,7 @@ Every task runs through three layers. Do not skip ahead to code.
 Not courtesies. These bind you as written, whether or not your tool enforces them.
 
 - **Always** identify affected files before making changes, and explain what will change and why
-- **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.amp/settings.json`
+- **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.claude/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
 - **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/branch-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
@@ -130,90 +130,50 @@ A problem you see and don't fix goes in the report, never in a comment. Comments
 
 ## Testing Standards
 
-### Rules
+Principles, not a framework. Whatever the language, follow its ecosystem's conventions for
+runner, layout and fixtures — these rules govern what a test must *do*, never how a
+particular toolchain spells it.
 
-**Test behavior, not implementation.** A test suite must give you confidence to refactor freely. If changing internal code (without changing behavior) breaks tests, those tests are liabilities, not assets.
+### What a test is for
 
-**Follow the Testing Trophy** (not the Testing Pyramid):
-- Few unit tests — only for pure logic, algorithms, and complex calculations
-- Many integration tests — the sweet spot; test real components working together
-- Some E2E tests — cover critical user journeys end-to-end
-- Static analysis — types and linters catch bugs cheaper than tests
+**Test behavior, not implementation.** A suite must give you confidence to refactor freely. If changing internal code without changing behavior breaks tests, those tests are liabilities, not assets.
 
-### When to Write Tests
+**Shape — the Testing Trophy, not the Pyramid:** static analysis catches the cheapest bugs; few unit tests, for pure logic and algorithms; many integration tests, the sweet spot, real components working together; some end-to-end tests over the critical journeys. Target roughly 20% unit, 60% integration, 15% E2E, 5% manual.
 
-- **After the design stabilizes, not during exploration.** Do not TDD a prototype — you'll write 500 tests for code you delete tomorrow. First make it work (POC), then make it right (refactor + tests), then make it fast
-- **Write tests when the code has users.** If a function is called by other modules or exposed to users, it needs tests. Internal helpers that only serve one caller don't need their own test file
-- **Write tests for bugs.** Every bug fix must include a regression test that fails before the fix and passes after. This is the highest-value test you can write
-- **Write tests before refactoring.** Before changing working code, write characterization tests first to lock in current behavior, then refactor with confidence
-- **Do not write tests for glue code.** Code that just wires components together (calls A then B then C) is tested at the integration level, not unit level
+### When to write them
 
-### TDD: When It Works and When It Doesn't
+- **After the design stabilizes, not during exploration.** Do not test a prototype — you will write tests for code you delete tomorrow. First make it work (POC), then make it right (tests), then make it fast
+- **Tests first when you already know the contract.** Pure functions, algorithms, parsers, validators, data transformations — write the test, watch it fail, then implement. When you are still discovering the interface, that same discipline produces churn and false confidence
+- **Write tests for bugs.** Every fix ships a regression test that fails before the fix and passes after — the highest-value test there is
+- **Write tests before refactoring.** Characterization tests lock in current behavior first, then change the code
+- **Write tests when the code has users.** Called by other modules or exposed externally means it needs tests; a helper serving one caller does not need its own file
+- **Do not test glue code.** Something that only wires A to B to C is covered at the integration level
 
-- **TDD works for:** Pure functions, algorithms, parsers, validators, data transformations — anything with clear inputs and outputs
-- **TDD does not work for:** Exploring a design, building a POC, or unstable interfaces. Writing tests for unstable APIs creates churn and false confidence
-- **The rule:** You must understand what you're building before you TDD it. TDD is a design tool for known problems, not a discovery tool for unknown ones
-- **Red-green-refactor discipline:** If you do TDD, follow the cycle strictly. Write a failing test, write minimal code to pass, refactor. Do not write 20 tests then implement — that's front-loading waste
+### What makes a good test
 
-### What Makes a Good Test
+- **Tests real behavior.** Call the public interface, assert on observable output. Never reach into internals
+- **Fails for the right reason.** It breaks when the feature breaks, not when the implementation moves
+- **Reads like a spec.** Someone new to the code should learn what the feature does by reading it
+- **Self-contained.** Sets up its own state, runs, cleans up. No ordering dependencies, and no reliance on project directories, user config, or ambient environment
+- **Deterministic.** Flaky tests erode trust. A dependency on timing, network, or global state is a defect in the test
+- **Never sleep for a condition — poll for it.** Sleeping then asserting is wrong at every value: too short and it flakes under load, too long and the suite drags, and a real async bug looks identical to a guess that was too short. Wait on the condition itself, re-reading the state *inside* the loop, with a timeout that names what it was waiting for. A fixed delay is only correct once you have waited for the triggering condition, the delay comes from a documented interval rather than a guess, and a comment says why
 
-- **Tests real behavior.** Call the public API, assert on observable output. Do not reach into internals
-- **Fails for the right reason.** A good test fails when the feature is broken, not when the implementation changes
-- **Reads like a spec.** Someone unfamiliar with the code must understand what the feature does by reading the test
-- **Self-contained.** Each test sets up its own state, runs, and cleans up. No ordering dependencies between tests
-- **Fast and deterministic.** Flaky tests erode trust. If a test depends on timing, network, or global state, fix that dependency
+### Anti-patterns
 
-### Anti-Patterns — Do Not Do These
+- **Mocking most of the test.** If mock setup outweighs the logic, you are testing mocks. Prefer the real thing against a temporary directory, an in-memory store, or a disposable container
+- **Partial mocks.** Mirror the complete structure the real thing returns, not only the fields this test reads. A mock missing a field downstream code consumes passes here and fails in production
+- **Smoke tests.** Asserting a result merely exists proves nothing. Assert on specific values, structure, or side effects
+- **Testing private internals.** If it needs its own test, it should be part of the public interface; otherwise the public tests should reach it
+- **Mirroring implementation.** A test that restates the source line by line breaks on every refactor and catches nothing
+- **Test-only production code.** Never add a method, flag, or branch to production solely for tests. Inject the dependency instead
+- **Chasing a coverage number.** 80% of meaningless tests is worse than 40% of behavioural ones. Coverage tells you what is *not* tested, never that what is covered is correct. Cover the critical path first — data, auth, money, core logic — before helpers
 
-- **Mocking more than 60% of the test.** If most of the test is mock setup, you're testing mocks, not code. Use real implementations with `tmp_path`, `:memory:` SQLite, or test containers
-- **Smoke tests.** `assert result is not None` proves nothing. Assert on specific values, structure, or side effects
-- **Testing private methods.** If you need to test a private method, either it should be public or the public method's tests should cover it
-- **Mirroring implementation.** Tests that replicate the source code line-by-line break on every refactor and catch zero bugs
-- **Test-only production code.** Never add methods, flags, or branches to production code solely for testing. Use dependency injection instead
+### Organization
 
-### Test Organization
-
-- **Co-locate tests with packages:** `packages/<pkg>/tests/` not a root `tests/` directory. Each package owns its tests
-- **Separate by type:**
-  ```
-  packages/<pkg>/tests/
-    unit/           # Fast, isolated, mocked deps, <1s each
-    integration/    # Real DB, filesystem, multi-component, <10s each
-    e2e/            # Full workflows, subprocess calls, <60s each
-    conftest.py     # Shared fixtures for this package
-  ```
-- **One test file per module** (not per function). `test_auth.py` tests the auth module, not `test_login.py` + `test_logout.py` + `test_session.py`
-- **No duplicate test files.** Before creating a new test file, check if one already exists for that module
-
-### Markers and Signals
-
-| Marker | Purpose | CI Behavior |
-|--------|---------|-------------|
-| `@pytest.mark.slow` | Runtime > 5s | Run in full suite, skip in quick checks |
-| `@pytest.mark.ml` | Requires ML deps (torch, etc.) | Skip if deps not installed |
-| `@pytest.mark.real_api` | Calls external APIs | Skip in CI — run manually before release |
-
-**CI runs for fast signals:**
-- `pytest -m "not slow and not ml and not real_api"` — fast gate on every push (~30s)
-- `pytest` — full suite on PR merge or nightly
-- Package-level runs for targeted debugging: `pytest packages/core/tests/`
-
-### Coverage and Ratios
-
-- **Do not chase a coverage number.** 80% coverage with meaningless tests is worse than 40% with behavior-testing integration tests
-- **Cover the critical path first.** Data layer, auth, payment, core business logic — before helper utilities
-- **Coverage tells you what's NOT tested, not what IS tested.** High coverage with bad assertions is false confidence
-- **Delete tests that don't catch bugs.** If a test has never failed (or only fails on refactors), it's not providing value
-
-**Target ratio:** ~20% unit, ~60% integration, ~15% E2E, ~5% manual/exploratory
-
-### Test Tooling Standards
-
-- Use `tmp_path` for filesystem tests, `:memory:` or `tmp_path` SQLite for DB tests
-- Use dependency injection over `@patch` — it's more readable and survives refactors
-- Tests must be self-sufficient — no dependency on project directories, user config, or environment state
-- Use factories or builders for test data, not raw constructors with 15 arguments
-- Keep test fixtures close to where they're used. Shared fixtures in `conftest.py`, not a global test utilities package
+- **Mirror the source structure**, at whatever level the ecosystem puts tests. One test file per module, not per function, and never a second file covering a module that already has one
+- **Separate by cost so CI gets a fast signal.** Keep quick isolated tests apart from ones needing real IO or a full workflow, and let the slow ones — long runtimes, heavy optional dependencies, live external APIs — be excluded from the gate that runs on every push and included in the full run
+- **Fixtures live near what uses them**, shared upward only when genuinely shared. Build test data with factories or builders, never a constructor taking fifteen positional arguments
+- **Delete tests that never catch anything.** A test that has only ever failed during refactors is a maintenance cost, not a safety net
 
 ---
 
@@ -281,9 +241,9 @@ The [Twelve-Factor App](https://12factor.net) methodology for modern, scalable a
 
 ---
 
-## AGENT.md Stub
+## CLAUDE.md Stub
 
-Copy this to any project's AGENT.md. These are mandatory rules, not suggestions.
+Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions.
 
 ```markdown
 ## Dev Rules
@@ -304,5 +264,5 @@ Copy this to any project's AGENT.md. These are mandatory rules, not suggestions.
 
 **Responsive web UI is mandatory.** Any web UI must work on mobile by default — fluid layouts, viewport meta, breakpoints, no horizontal scroll. Verify in DevTools device emulation before claiming a UI task is done. POCs exempt; real projects are not.
 
-For full development and testing standards, see `.amp/remember/AGENT_RULES.md`.
+For full development and testing standards, see `.claude/remember/AGENT_RULES.md`.
 ```