liteagents 2.24.1 → 3.5.0

package/installer/installation-engine.js

@@ -7,6 +7,11 @@
 const fs = require('fs');
 const path = require('path');
 
+// Same single source of truth as installer/cli.js: UPDATE_VERSION.sh bumps
+// only package.json. Stamped into every manifest so version-check.cjs can read
+// the installed version without shelling out to `npm ls -g` (~500ms per run).
+const LITEAGENTS_VERSION = require('../package.json').version;
+
 class InstallationEngine {
   constructor(pathManager, packageManager) {
     this.pathManager = pathManager;
@@ -448,7 +453,10 @@ class InstallationEngine {
     const manifest = {
       ...template,
       variant,
+      // `version` is the MANIFEST SCHEMA version and always has been; the
+      // liteagents release that wrote it is a separate field. Do not merge them.
       version: '1.1.0',
+      liteagents_version: LITEAGENTS_VERSION,
       installed_at: new Date().toISOString(),
       variantInfo: {
         name: variantMetadata.name,

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "liteagents",
-  "version": "2.24.1",
-  "description": "AI development toolkit with 11 specialized agents and 18 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
+  "version": "3.5.0",
+  "description": "AI development toolkit with 10 specialized agents and 13 capabilities including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
   "main": "index.js",
   "bin": {
     "liteagents": "./installer/cli.js",
     "liteag": "./cli.js"
   },
   "scripts": {
-    "test": "node tests/run-all-tests.js",
+    "test": "node scripts/mirror.cjs check && node tests/run-all-tests.js && node ./scripts/validate-package.js",
+    "mirror": "node scripts/mirror.cjs",
     "test-installer": "node tests/installer/integration.test.js",
     "install-interactive": "node installer/cli.js",
     "uninstall-tool": "node installer/cli.js --uninstall",

package/packages/ampcode/AGENT.md

@@ -6,7 +6,7 @@ Ampcode is a lightweight CLI tool that provides workflow automation commands.
 
 These subagents are available when using Ampcode CLI.
 
-### Subagents (11 total)
+### Subagents (10 total)
 
 | ID | Title | When To Use |
 |---|---|---|
@@ -14,7 +14,6 @@ These subagents are available when using Ampcode CLI.
 | 2-generate-tasks | 2-Generate Tasks | Detailed Planning - use to break down the PRD into a granular, actionable task list |
 | 3-process-task-list | 3-Process Task List | Iterative Implementation - use to guide the AI to tackle one task at a time, allowing you to review and approve each change |
 | code-developer | Full Stack Developer | Use for code implementation, debugging, refactoring, and development best practices |
-| context-builder | Context Initializer | Use to initialize project context for new/existing projects, discover and organize documentation, create AGENT.md and KNOWLEDGE_BASE.md for optimal token-efficient memory |
 | feature-planner | Product Manager | Use for creating epics and user stories, prioritization, backlog navigation, story refinement, and retrospectives |
 | market-researcher | Business Analyst | Use for market research, brainstorming, competitive analysis, project briefs, and initial project discovery |
 | orchestrator | Master Orchestrator | Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult |
@@ -22,26 +21,16 @@ These subagents are available when using Ampcode CLI.
 | 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 (9 total)
-
-| ID | Description | Usage | Auto |
-|---|---|---|---|
-| brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> | false |
-| docs-builder | Reorg a docs corpus, split an oversized doc, search it, keep pages current, index them | /docs-builder [reorg \| cleanup <file.md>] | false |
-| live-canvas | Design UI variations and collect click-to-annotate feedback from the browser (batch mode only on Amp) | /live-canvas | false |
-| trace-back | Systematically traces bugs backward through call stack to identify source | /trace-back <issue-description> | 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 (9 total)
+### Skills (13 total)
 
 | ID | Description | Usage |
 |---|---|---|
-| optimize | Analyze and optimize performance issues | /optimize <target-area> |
-| refactor | Refactor code while maintaining behavior and tests | /refactor <code-section> |
+| brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> |
+| live-canvas | Design UI variations and collect click-to-annotate feedback from the browser (batch mode only on Amp) | /live-canvas |
+| root-cause | Find the cause before changing code - evidence, backward trace, one hypothesis, fix at the source | /root-cause <bug-or-error-description> |
+| 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>] |
+| 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] |
@@ -53,4 +42,6 @@ These subagents are available when using Ampcode CLI.
 All resources are auto-discovered from frontmatter in their respective directories:
 - **Agents**: `./agents/*.md`
 - **Skills**: `./skills/*/SKILL.md`
-- **Commands**: `./commands/*.md`
+
+Amp removed custom commands in favour of skills, so every capability ships as
+`skills/<name>/SKILL.md` here — the same shape Claude Code uses.

package/packages/ampcode/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/ampcode/agents/orchestrator.md

@@ -66,7 +66,7 @@ On-demand, read from these locations:
 | Resource | Global Paths | Local Path |
 |----------|--------------|------------|
 | Agents | `~/.config/amp/agents/*.md`, | `./.amp/agents/*.md` |
-| Commands | `~/.config/amp/commands/*.md` |`./.amp/commands/*.md` |
+| Skills | `~/.config/amp/skills/*/SKILL.md` | `./.amp/skills/*/SKILL.md` |
 
 Parse frontmatter for `name`, `description`, `when_to_use`. Present as numbered list.
 
@@ -77,7 +77,7 @@ Predefined multi-agent sequences:
 | Workflow | Sequence | When |
 |----------|----------|------|
 | **Greenfield** | market-researcher → feature-planner → 1-create-prd → 2-generate-tasks → 3-process-task-list | New product/feature from scratch |
-| **Brownfield** | context-builder → system-architect → feature-planner | Understand existing codebase |
+| **Brownfield** | system-architect → feature-planner | Understand existing codebase |
 | **Feature** | feature-planner → 1-create-prd → 2-generate-tasks → 3-process-task-list | Add feature to existing product |
 | **Bug Fix** | code-developer → quality-assurance | Fix and verify |
 | **Sprint** | feature-planner (*sprint-plan) → 2-generate-tasks | Plan sprint from backlog |
@@ -96,7 +96,7 @@ Quick routing when user has clear intent:
 | review, quality, test | quality-assurance |
 | design, UI, wireframe | ui-designer |
 | architecture, tech, design doc | system-architect |
-| understand, document, brownfield | context-builder |
+| understand, brownfield, existing codebase | system-architect |
 
 ## Commands
 

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

@@ -59,13 +59,15 @@ digraph QualityAssurance {
 
 Before any analysis, read (if exists):
 - `AGENT.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/ampcode/{commands/brainstorming.md → 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
@@ -43,7 +42,7 @@ Start by understanding the current project context, then ask questions one at a
 
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
-- Create isolated workspace (use git worktrees if needed)
+- Create isolated workspace for implementation
 - Create detailed implementation plan
 
 ## Key Principles

package/packages/ampcode/{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 *)
+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
@@ -11,7 +11,7 @@ reports findings and hands them back. Fixing is a separate, separately
 authorized action.
 
 Only **Critical** and **High** findings block the merge. Everything else is
-appended to the **fix ledger** (`.claude/remember/fix-ledger.md`) — a local,
+appended to the **fix ledger** (`.amp/remember/fix-ledger.md`) — a local,
 cumulative list, living beside `MEMORY.md`, that `/refactor` (no arguments)
 works through between features. Like its neighbours it is a private working
 artifact, usually gitignored; it persists across reviews, it is not a
@@ -44,17 +44,17 @@ at the current HEAD SHA.
   review of a report. (Same rule `/security` carries inside stage 2.)
 - **No edits — two exceptions.** You have no authorization to change code,
   even for a finding you are certain about. Report it. The only files you may
-  write are `.claude/remember/fix-ledger.md` (append bullets; never rewrite or
-  delete) and `.claude/remember/last-review.md` (overwrite; the review record
+  write are `.amp/remember/fix-ledger.md` (append bullets; never rewrite or
+  delete) and `.amp/remember/last-review.md` (overwrite; the review record
   described at the end of this file).
 - **Prove it with two checks, because neither sees what the other does.**
   `git status --porcelain`, at start and again before you report, proves no
   **tracked** file changed — that is the "never edits code" guarantee, and it
-  is the one that matters. It cannot police your own two writes: `.claude/`
+  is the one that matters. It cannot police your own two writes: `.amp/`
   is normally gitignored, so porcelain stays empty whether you wrote the
   allowed files, wrote nothing, or overwrote `MEMORY.md`. `git status
-  --ignored` does not close it either — it collapses to `!! .claude/`, the
-  directory, not the files. So also take `md5sum .claude/remember/*` before
+  --ignored` does not close it either — it collapses to `!! .amp/`, the
+  directory, not the files. So also take `md5sum .amp/remember/*` before
   you start and again before you report, and show the comparison: only
   `fix-ledger.md` and `last-review.md` may differ.
 
@@ -95,7 +95,7 @@ Record the **HEAD SHA** you reviewed, and **report the target you resolved**
 (the literal range or path) in your output, so the orchestrator can see what
 was actually read rather than assuming.
 
-**Re-review after fixes: read `.claude/remember/last-review.md` first.** Its
+**Re-review after fixes: read `.amp/remember/last-review.md` first.** Its
 `sha:` line is the previously-reviewed commit and its `blockers:` list is what
 you owe an answer on — take both from the file, never from the orchestrator's
 recollection, for the same reason `/release` does. Then:
@@ -231,7 +231,7 @@ check before escalating.
 
 ### Ledger (non-blocking — medium / low)
 Not in the report. **Append** each one as a single bullet to
-`.claude/remember/fix-ledger.md` (create the file with the header below if
+`.amp/remember/fix-ledger.md` (create the file with the header below if
 missing):
 
 ```
@@ -256,7 +256,7 @@ with `UNVERIFIED:` so `/refactor` retests before acting.
 The **snippet is the anchor**: 20–60 verbatim characters from the line,
 unique enough for `git grep -F` to find it after lines shift. No line
 numbers, no TODO comments in code — the ledger is the single writer. Before
-appending, dedupe with **plain `grep -F "<snippet>" .claude/remember/fix-ledger.md`**;
+appending, dedupe with **plain `grep -F "<snippet>" .amp/remember/fix-ledger.md`**;
 if it is already there, skip it. Do not touch existing bullets.
 
 **A bullet you disprove is deleted, not annotated.** If you establish that an
@@ -280,7 +280,7 @@ Then a coverage line: stage 1 at level `<level>`, stage 2 full, stage 3 —
 each `ran ✓/✗` with its evidence. A stage you did not actually run is a **✗**, never an
 assumed pass.
 
-**Write the review record** to `.claude/remember/last-review.md`, overwriting
+**Write the review record** to `.amp/remember/last-review.md`, overwriting
 it. `/release` reads this file; a SHA that lives only in a chat message is
 gone after a compaction or a handover, and the only remaining source is the
 orchestrator — the one party this command already refuses to take a review's
@@ -326,7 +326,7 @@ does not move — which means nothing was fixed, which is the correct outcome.
 
 End with:
 - **Reviewed at HEAD `<sha>` on `<branch>`, target `<resolved range or path>`,
-  tree clean at start; at exit clean or the two `.claude/remember/` paths
+  tree clean at start; at exit clean or the two `.amp/remember/` paths
   only.**
 - **Fix ledger: N open, M added this run** (N = bullet count). When N > 0,
   add: "N fixes waiting — run `/refactor` between features." The ledger is a

package/packages/{claude/commands/docs-builder.md → ampcode/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

package/packages/ampcode/{commands/live-canvas.md → 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.
@@ -418,7 +422,7 @@ Create all files under `.claude-design/`:
 
 ### The overlay
 
-**One template, every framework:** `~/.claude/skills/live-canvas/templates/overlay-vanilla.js`. Single file, zero dependencies, plain DOM. Works in vanilla JS, Vue, Svelte, Rails, Django, Phoenix, plain HTML, Next.js, Vite-React, Remix — anywhere a `<script>` tag runs.
+**One template, every framework:** `~/.config/amp/skills/live-canvas/templates/overlay-vanilla.js`. Single file, zero dependencies, plain DOM. Works in vanilla JS, Vue, Svelte, Rails, Django, Phoenix, plain HTML, Next.js, Vite-React, Remix — anywhere a `<script>` tag runs.
 
 Copy it into a directory served by the dev server (e.g. `public/overlay-vanilla.js` for Next.js, `static/overlay-vanilla.js` for Vite, the public dir for Rails/Django). Reference it from the lab page.
 
@@ -545,7 +549,7 @@ The Live Canvas page must include:
 1. **Header** with:
    - Design Brief summary (target, scope, key requirements)
    - Instructions for reviewing
-   - **Lab banner (REQUIRED)** — paste `~/.claude/skills/live-canvas/templates/lab-banner.html` at the top of the lab page. Same text in any mode. For React/TSX labs, translate the inline style to a JS object: camelCase keys, string values. E.g. `style="border-radius:8px; padding:10px 14px; font-size:13px"` → `style={{ borderRadius: '8px', padding: '10px 14px', fontSize: '13px' }}`. Keep the text and `role="note"`.
+   - **Lab banner (REQUIRED)** — paste `~/.config/amp/skills/live-canvas/templates/lab-banner.html` at the top of the lab page. Same text in any mode. For React/TSX labs, translate the inline style to a JS object: camelCase keys, string values. E.g. `style="border-radius:8px; padding:10px 14px; font-size:13px"` → `style={{ borderRadius: '8px', padding: '10px 14px', fontSize: '13px' }}`. Keep the text and `role="note"`.
 
 2. **Variant Grid** with:
    - Clear labels (A, B, C, D, E)
@@ -568,7 +572,7 @@ The Live Canvas page must include:
 
    The overlay (`overlay-vanilla.js`) enables users to click on elements and leave comments. Without it, the Live Canvas is just a static page with no way to collect structured feedback.
 
-   - Copy `~/.claude/skills/live-canvas/templates/overlay-vanilla.js` into a directory served by the dev server (e.g. `public/`, `static/`, or wherever the framework serves static assets).
+   - Copy `~/.config/amp/skills/live-canvas/templates/overlay-vanilla.js` into a directory served by the dev server (e.g. `public/`, `static/`, or wherever the framework serves static assets).
    - Reference it from the lab page via `<script>` tag and call `LiveCanvas.init({...})` once with `target`, `channelUrl` (Live mode), and optional `batchEndpoint`. See "Wiring the overlay" above for the exact snippets per framework.
    - Every variant container in the lab page MUST have a `data-variant="X"` attribute (A, B, C, D, E, or F). The overlay uses this to route comments to the right variant file.
 

package/packages/ampcode/{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 *)
+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
@@ -44,15 +45,15 @@ Refactor $ARGUMENTS.
   other does.** `git status --porcelain` at exit must list only files a
   surviving bullet named — that is this command's scope guarantee, and unlike
   `/branch-review` it is not expected to be empty. It cannot police the
-  memory directory: `.claude/` is normally gitignored, so porcelain stays
+  memory directory: `.amp/` is normally gitignored, so porcelain stays
   empty whether you deleted a fixed bullet, wrote nothing, or overwrote
-  `MEMORY.md`. So also take `md5sum .claude/remember/*` before you start and
+  `MEMORY.md`. So also take `md5sum .amp/remember/*` before you start and
   again before you report, and show the comparison: only `fix-ledger.md` may
   differ. `last-review.md` in particular is `/branch-review`'s to write —
   a fixer that touches it forges the gate that judges its own work.
 
 ## Ledger mode — `$ARGUMENTS` empty
-Work through `.claude/remember/fix-ledger.md`, the non-blocking findings
+Work through `.amp/remember/fix-ledger.md`, the non-blocking findings
 `/branch-review` has accumulated. Everything below (goals, constraints,
 verification, HITL gates) still applies; this section only says what to
 refactor and how to close each item.
@@ -72,8 +73,14 @@ refactor and how to close each item.
    behaviour change is not a refactor — leave the bullet, note it in the report.
 5. Run the tests as described below. Then report: **fixed / dropped / left**
    with the reason per left item, and the remaining bullet count.
-6. Say plainly: **commit, then run `/branch-review`** on this branch — ledger
-   mode is a fixer, not a review, and its diff gets the ordinary gate.
+6. **Hand it back; do not chain it.** Say plainly: **commit, then run
+   `/branch-review`** on this branch — ledger mode is a fixer, not a review,
+   and its diff gets the ordinary gate. That is a sentence you *say*, not a
+   sequence you *run*. They are two separate calls and both are the user's:
+   an answer of "commit", "yes" or "go" authorizes the commit and nothing
+   after it. Never start `/branch-review` off the back of it. Observed in the
+   field: a run chained the review onto the owner's "commit" and the owner
+   objected.
 
 ## Goals
 - Reduce complexity
@@ -81,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**
@@ -114,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/ampcode/{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 *)
+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 —
@@ -57,7 +57,7 @@ A review must have run on this branch **at the current HEAD SHA**.
 
 **Compare the SHAs yourself; do not settle for an answer.** Run `git rev-parse
 HEAD` and compare it against the `sha:` line in
-`.claude/remember/last-review.md`, which `/branch-review` writes. Asking the
+`.amp/remember/last-review.md`, which `/branch-review` writes. Asking the
 orchestrator "did a review run?" puts the question to the one party with an
 incentive to say yes, so its word is not evidence — and neither is a SHA
 quoted from a chat message, which is the same claim in another costume and is
@@ -72,7 +72,7 @@ that predates this file's introduction has no record, so it does not count.
   is what makes "all findings fixed" checkable instead of promised.
   **No exceptions — including the fix ledger.** It is normally gitignored, so
   appending to it moves nothing and this never comes up. A repo that tracks
-  `.claude/` instead will see a ledger commit land after the review and make
+  `.amp/` instead will see a ledger commit land after the review and make
   it stale. That is the rule working, not a case to carve out: re-review, or
   leave the ledger uncommitted until after the release.
 - **`coverage:` naming any stage `NOT RUN`** → **stop**. A `ready` from a run