liteagents 2.24.1 → 3.5.0

package/CHANGELOG.md

@@ -7,6 +7,212 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.5.0] - 2026-09-05
+
+### Breaking
+- **Every capability is a skill on Claude Code and Amp.** Claude Code merged
+  custom commands into skills (`.claude/commands/deploy.md` and
+  `.claude/skills/deploy/SKILL.md` both create `/deploy`, and skills are the
+  recommended form), and Amp removed custom commands outright. So
+  `packages/claude/commands/` and `packages/ampcode/commands/` are gone, and
+  all 13 capabilities ship as `skills/<name>/SKILL.md` in both. The nine that
+  are deliberate actions — branch-review, docs-builder, refactor, release,
+  remember, security, ship, stash, test-generate — carry
+  `disable-model-invocation: true`, so Claude runs them only when you type
+  them; the four advisory ones stay auto-loadable. Bundled scripts move with
+  their skill. Droid and opencode are unchanged and still use flat commands;
+  the mirror converts for them. **Migration:** reinstall; the installer already
+  handles a `skills/` directory, and `variants.json` drops its `commands` key
+  for those two packages.
+- **The ampcode package ships skills, not commands.** Amp removed custom slash
+  commands in favour of skills, so all 13 capabilities now live at
+  `packages/ampcode/skills/<name>/SKILL.md` — the same shape Claude Code uses.
+  `packages/ampcode/commands/` is gone. **Migration:** reinstall the ampcode
+  package; the installer already handles a `skills/` directory.
+- **`/optimize` is removed; `/refactor` absorbs it — catalog goes 14 -> 13.**
+  It duplicated `/refactor`'s job shape (a named target, changed in place, no
+  behaviour change) and this repo's history shows it was never once used. A
+  targeted `/refactor` now runs a performance pass by default: complexity, N+1
+  queries, I/O in a loop, repeated recomputation. The grounding rule survives
+  the move — findings are always reported, but only *fixed* with real evidence
+  (a profile, a log line, or an obviously hot path); everything else is
+  reported as "uncertain, needs profiling data" and the code is left alone.
+  `/optimize`'s HITL gates move across too: multiple fix shapes, correctness
+  traded for speed, concurrency primitives, schema or response-shape changes.
+  **Migration:** use `/refactor <target>`; no flag needed.
+- **`trace-back` is merged into `debug-method`, renamed `/root-cause` —
+  15 -> 14.** The backward walk is now Phase 1 step 5 of one skill rather than
+  a second skill you had to know to reach for. 468 lines across two files
+  became 220 in one. `find-polluter.sh` still ships.
+- **`tdd-flow`, `test-traps` and `verify-done` are removed — 18 -> 15.** The
+  repo's own history showed the rules they carried were already being followed
+  without them; they cost context on every session to restate it.
+
+### Added
+- **`scripts/mirror.cjs` — the kit packages are generated, not hand-copied.**
+  `packages/claude` owns every body; each target file keeps its own
+  frontmatter byte-for-byte (that is where the per-kit shape lives — `tools`
+  arrays vs permission maps, `Bash(x:*)` vs `Bash(x *)`); the script owns the
+  path substitutions between them. `check` runs first in `npm test`, so a
+  partial sync can no longer ship. Modes: `check`, `diff`, `sync`, `shapes`.
+- **`scripts/frontmatter.json` — the recorded per-kit frontmatter shape.**
+  Frontmatter is meant to differ per kit, so it cannot be verified by diffing.
+  It is checked against this file instead: required keys, allowed keys, and
+  the kit's `Bash()` style. Generated from the real files by `mirror.cjs
+  shapes`, never hand-written.
+- **`docs/product/INSTALLER_GUIDE.md` gained the order of operations** for
+  changing a command, skill or subagent, from validating the bug through the
+  mirror, the three checks, the docs sweep and the release calls. Root
+  `CLAUDE.md` points at it.
+
+### Fixed
+
+- **Amp installs delivered no capabilities.** This release moved ampcode from
+  `commands/` to `skills/`, but `packages/ampcode/variants.json` was left
+  declaring only `agents`. The installer selects content by that field, so
+  `selectVariantContent()` returned an empty skills list and an Amp install
+  carried 10 agents and zero of the 13 capabilities. Added `"skills": "*"`.
+  Caught by `prepublishOnly`'s package validator, which is why the first cut never
+  reached the registry.
+- `scripts/validate-package.js` still mapped ampcode's capability directory to
+  `commands`; it is `skills`.
+- **Test-count floors realigned.** The Multi-Tool Installation floor moved
+  36 -> 41 (33 to match the capability cut, then +8 for the new
+  variant-selection assertions; Claude has no `commands/`
+  directory now, so the suite counts three categories per scenario, not four),
+  and four floors that had drifted below their suites' actual counts were
+  raised to match: docs-builder 497 -> 538, friction 254 -> 323, sync-rules
+  15 -> 25, stub-check 19 -> 24. Each floor was verified to still fail when
+  set one above actual.
+- **Command frontmatter was largely invented.** Checked against each tool's own
+  docs: `usage:` is not a field in any of the four. Droid commands support only
+  `description` and `argument-hint` (tool scoping is explicitly unavailable for
+  commands); opencode commands support only `description`, `agent`, `model` and
+  `subtask`, and take their name from the filename; Claude Code command files
+  ignore `name`. Every unsupported key is removed, so the `allowed-tools` those
+  files carried — which did nothing on droid or opencode — is gone. Droid
+  subagents lose `when_to_use`, which is not a Factory field; its text is
+  folded into `description`, which is what Factory reads for routing.
+  `scripts/frontmatter.json` now records the real per-kit schemas and
+  `mirror.cjs check` enforces them.
+- **Three kits were sending users to the wrong memory directory.**
+  `/branch-review`, `/refactor` and `/release` told droid, ampcode and
+  opencode users to look in `.claude/remember/` instead of their own
+  `.factory/`, `.amp/` or `.opencode/`. Found by the new mirror check.
+- **`1-create-prd.md` had silently lost five checklist lines in droid only**,
+  from an earlier partial hand-mirror. 22 drifted or missing files were
+  restored in total, including `skill-creator/LICENSE.txt`, which its own
+  frontmatter cites and which was absent from all three kits.
+- **`docs-builder.md` carried claude's `Bash(node:*)` syntax in all three
+  other kits**, where the correct form is `Bash(node *)`.
+- **Only a symlink that actually leaves the repo counts as an escape.** The
+  previous check flagged in-repo links too; mirrored to all four kits.
+
+### Changed
+
+- `npm test` now runs `scripts/validate-package.js` as its last step, so the
+  publish-time validator runs locally instead of only inside `publish.yml`.
+  The first cut's gate went green on a package publish then rejected.
+- New `testVariantSelectionDelivers` in the multi-tool suite asserts what the
+  installer actually *selects* per tool, not what the package tree contains.
+  The existing scenarios copy the whole tree and read `variants.json` only to
+  check the variant key exists, so they could not see a missing content field.
+- Six commands and skills that had no `allowed-tools` at all — `remember`,
+  `stash`, `brainstorming`, `live-canvas`, `root-cause`, `skill-creator` — now
+  declare a `Read, Grep, Glob` floor, so those calls stop prompting. Subagents
+  are deliberately untouched: claude and ampcode omit `tools` and so inherit
+  everything, droid already lists all three, and opencode's `tools` is a
+  write/edit/bash permission map where they are not expressible.
+- README and `packages/subagentic-manual.md` rewritten to lead with the
+  catalog rather than a pitch.
+- Command READMEs live in `docs/product/` and no longer ship inside the
+  packages; the live-canvas-channel README moved out too.
+- `AGENT_RULES.md` testing standards are stated as principles rather than as
+  pytest specifics.
+
+## [3.0.0] - 2026-09-04
+
+### Breaking
+- **The `context-builder` subagent is removed — catalog goes 11 -> 10 agents.**
+  `docs-builder` supersedes its Tier 2/3 work (creating/splitting `docs/*.md`,
+  validated on real corpora; `docs/index.md` via `index-flat` is the sole index,
+  same reason `docs/wiki-index.md` was already deleted). Tier 1 (author
+  `CLAUDE.md`) was the only unique part, and its one load-bearing invariant —
+  `CLAUDE.md` must `@`-include `.claude/remember/MEMORY.md` and nothing else —
+  is now a mechanical gate in `stub-check.cjs`, run every `/remember`; a prose
+  rule inside a subagent was always the weaker enforcement. **Migration:** for
+  the doc-authoring work `context-builder` did, use `/docs-builder`; for a
+  cold-start `CLAUDE.md` on a brand-new project, use Claude Code's own `/init`.
+  Orchestrator routing's Brownfield workflow now starts at `system-architect`.
+
+### Security
+- **`sync-rules.cjs` and `stub-check.cjs` no longer write through a symlink out
+  of the repo they were invoked on.** `/remember` runs across a fleet of sibling
+  checkouts, so a relative link only has to reach a neighbor. Three routes were
+  reproduced and closed: a dangling link at the write target (followed by
+  `writeFileSync` as if the file were merely absent), a symlinked parent
+  directory (invisible to a leaf-only `lstat` guard), and a symlinked
+  `CLAUDE.md` that `stub-check.cjs` rewrote in place with no rename-away step.
+  `escapesRepo()` resolves the deepest existing ancestor with `realpath` and
+  confirms the write still lands inside the repo, `lstat`-ing the leaf for the
+  dangling case; refusal is loud (an `escapes` action / a skip message), never
+  silent. Mirrored to all four kits.
+
+### Added
+- **`AGENT_RULES.md` is now kept current in every repo, instead of written once and
+  forgotten.** `remember/sync-rules.cjs` byte-compares the repo copy against the
+  template shipped beside it on every `/remember` run: identical does nothing at all,
+  absent copies it in, and a differing body is moved to a single `AGENT_RULES.md.bak`
+  before the new one lands. The `.bak` is one file, deliberately — a customised body
+  survives exactly one release, so fold your changes in before the next update. This
+  replaced a bootstrap-once rule that had left a measured 35 local repos many releases
+  behind, after three hand sweeps failed to hold.
+- **`remember/stub-check.cjs` asserts the config stub's SHAPE and repairs it.** v2.19
+  demoted `AGENT_RULES.md` from an `@`-include to a plain pointer — an `@`-include
+  hot-loads ~300 lines into every session — but nothing enforced it, and 21 of 37
+  measured repos had drifted back. It also repairs a MEMORY include that is not
+  `@<dir>/remember/MEMORY.md`, since a bare `@MEMORY.md` resolves to a nonexistent
+  root file and hot memory then silently never loads. It edits only *inside* the
+  marker pairs and only the mechanism; the prose in those blocks stays user-owned.
+  It will **not** repoint a MEMORY include at a file that does not exist — a repo
+  still on the pre-rename `.claude/memory/` layout has a live file at the old path,
+  and breaking a working include to satisfy a naming convention is worse than saying
+  so.
+- **`remember/version-check.cjs` nudges when the installed liteagents is behind.**
+  One line in `/remember` step 0, advice only — it never installs. Any failure
+  (offline, DNS, timeout) is a silent skip, because a memory command that hangs on a
+  network call is worse than one that misses a nudge. The installer now stamps
+  `liteagents_version` into its manifest so the check does not shell out to
+  `npm ls -g` on every run (measured 502ms -> 113ms warm).
+- **The installer says where your backup went.** On a reinstall it now closes with the
+  path of every install it moved aside, and notes that an edited `AGENT_RULES.md` is
+  preserved in the backup's `remember/` folder. A fresh install's output is unchanged.
+
+### Changed
+- **`/remember` reports every write verbatim.** Step 8 relays exactly what
+  `version-check.cjs`, `sync-rules.cjs` and `stub-check.cjs` printed, and nothing when
+  they printed nothing. Paraphrasing could drop the `AGENT_RULES.md.bak` filename,
+  which is the one thing someone who just lost their edits needs.
+- **The stub check survives a quiet run.** Step 1's guard stops the run when there are
+  no unprocessed stashes and no friction output — which is exactly the state of a
+  stale, unattended repo. `stub-check.cjs` now runs before that stop; skipping it on
+  quiet runs is how a repo with nothing to remember stayed broken forever.
+- **`/refactor` hands the review back instead of chaining it.** Step 6's "commit, then
+  run `/branch-review`" read as a sequence to execute; a field run started the review
+  off the owner's "commit" and the owner objected. It now states that this is a
+  sentence to say, that both are the user's separate calls, and that "commit"/"yes"/"go"
+  authorizes the commit and nothing after it.
+
+### Fixed
+- Four places stated the memory-include mechanism using the broken bare `@MEMORY.md`
+  form, including an anti-pattern table an agent reads before writing the config.
+- `poc/friction-file-referents/README.md` claimed everything needed to audit it was in
+  the directory. `score.py` reproduces only the LLM-experiment table (Findings 4-6);
+  the mechanical-study numbers (Findings 2-3) come from a run whose script was never
+  committed. Now stated precisely.
+
+---
+
 ## [2.24.1] - 2026-09-03
 
 ### Changed

package/README.md

@@ -9,201 +9,169 @@
          ╚══════╝╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
 ```
 
-**AI development toolkit with 11 specialized agents and 18 commands per tool**
+**10 specialized agents · 13 commands & skills · Claude · Opencode · Ampcode · Droid**
 
 <p align="center">
-  <img src="https://img.shields.io/github/package-json/v/hamr0/liteagents?label=version&color=2a4f8c" alt="version (auto from package.json)">
+  <img src="https://img.shields.io/github/package-json/v/hamr0/liteagents?label=version&color=2a4f8c" alt="version">
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
 </p>
 
-**Supported Tools:**
-[![Claude](https://img.shields.io/badge/Claude-Supported-blue?logo=anthropic)](https://claude.ai)
-[![Opencode](https://img.shields.io/badge/Opencode-Supported-green)](https://github.com/hamr0/opencode)
-[![Ampcode](https://img.shields.io/badge/Ampcode-Supported-orange)](https://github.com/hamr0/ampcode)
-[![Droid](https://img.shields.io/badge/Droid-Supported-red)](https://github.com/hamr0/droid)
-
 </div>
 
-Specialized AI agents and workflow commands for product management, agile development, and software engineering. Simple installer supports Claude, Opencode, Ampcode, and Droid.
-
----
+Liteagents started as scaffolding for early LLMs that needed to be told everything.
+It isn't that anymore. Models got smarter, so the toolkit got thinner: specialists you
+call by name or that trigger themselves on domain, wide lanes instead of tight rails,
+constraints on *what* rather than scripts for *how*.
 
-## Quick Start
+It is actively challenged, pruned and rewritten — things get renamed, added, and
+deleted as models improve. That churn is the point.
 
 ```bash
-# Option 1: NPX (recommended)
-npx liteagents
-
-# Option 2: Global install (never use sudo)
-npm install -g liteagents
-liteagents
-
-# If permission errors:
-# mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'
-# echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
+npx liteagents          # recommended
+# or: npm install -g liteagents && liteagents   (never sudo)
 ```
 
-### Supported Tools
+<sub>Permission errors? `mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'`, then add `~/.npm-global/bin` to your `PATH`.</sub>
 
-- **Claude Code** - 11 subagents + 8 skills + 10 commands (+ optional live-canvas channel plugin)
-- **Opencode** - 11 agent references + 18 commands
-- **Ampcode** - 11 subagents + 18 commands
-- **Droid** - 11 agent references + 18 commands
+---
 
-**Key Difference:**
-- **Claude Code**: Full subagent system with orchestrator + skills (auto-triggering)
-- **Opencode / Droid / Ampcode**: Commands only + agent reference documentation
+## The catalog
+
+**Agents** — invoke with `@name` (Claude Code) or `/name`.
+
+| Agent | What it's for |
+|---|---|
+| `1-create-prd` | Define scope as a PRD — a portal into the work, not a spec to obey |
+| `2-generate-tasks` | Break a PRD into granular, actionable tasks |
+| `3-process-task-list` | Execute tasks one at a time with review checkpoints |
+| `orchestrator` | Read intent, route to the right agent sequence |
+| `code-developer` | Implementation, debugging, refactoring |
+| `quality-assurance` | Test architecture, quality gates, risk assessment |
+| `feature-planner` | Epics, user stories, prioritization, backlog |
+| `market-researcher` | Market and competitive analysis, project discovery |
+| `system-architect` | System design, tech selection, API design, scale |
+| `ui-designer` | UI/UX, wireframes, prototypes, design systems |
+
+**Commands & skills** — `/name`.
+
+| Command | What it's for |
+|---|---|
+| `/stash` | Snapshot this session's context before compaction or handoff |
+| `/remember` | Fold stashes + friction into hot project memory |
+| `/docs-builder` | Reorg, index, and split a docs corpus so search actually finds things |
+| `/branch-review` | Full pre-merge review — blockers reported, nits to the fix ledger |
+| `/refactor` | Clear the fix ledger; with args, refactor and optimize a named area |
+| `/release` | Docs sweep, version bump, local commit, then hand back the merge sequence |
+| `/security` | Standalone vulnerability audit (also stage 2 of `/branch-review`) |
+| `/ship` | Mechanical pre-deploy gate — tests, build, tree state, pass/fail only |
+| `/test-generate` | Generate a test suite and verify each test exercises real code |
+| `/brainstorming` | Turn a rough idea into a formed design by questioning |
+| `/root-cause` | Find the cause before changing code — evidence, backward trace, one hypothesis, fix at the source |
+| `/live-canvas` | UI variations with click-to-annotate feedback in the browser |
+| `/skill-creator` | Build a new skill |
+
+<sub>Claude Code and Amp ship all 13 as skills; Opencode and Droid expose all 13 as commands. All four also ship agent reference docs.</sub>
 
-### Start Using
+---
 
-```bash
-# Claude Code examples
-@orchestrator help
-@1-create-prd Create a PRD for a task management app
-/brainstorming Explore authentication approaches
-/tdd-flow Implement user login
-
-# Opencode/Ampcode/Droid examples
-/1-create-prd Create a PRD for a task management app
-/brainstorming Explore authentication approaches
-/tdd-flow Implement user login
-```
+## The ones that carry the load
 
----
+### `AGENT_RULES.md` — the architect behind every project
 
-## Hot Memory — project-local learning from your own sessions
+One lightweight, generic, model-agnostic rules doc. It sets **what** matters and leaves
+wide room on **how**: simple over clever, every line has a purpose, surgical changes,
+exhaust the stdlib before reaching for a dependency, POC before you design.
 
-Liteagents ships a two-command pipeline that turns Claude Code's session logs into project-local memory. No databases, no external services, just markdown files the assistant reads via `@MEMORY.md`.
+With smarter models a PRD is a **portal, not a deliverable** — the start of a
+conversation. You discover it module by module, reviewing, changing and deleting as
+experience arrives, instead of pinning everything down up front.
 
-```
-/stash  →  /remember
-capture    analyze + consolidate
-```
+It is loaded every session, linked from `CLAUDE.md`, and `/remember` keeps it fresh —
+each run byte-compares your copy against the template that shipped with your install.
 
-- **`/stash`** — snapshot the current session's context before compaction or handoff; nudges you to consolidate once a few stashes pile up. The write-up runs on a mid-tier model, dispatched as a background subagent where your tool supports it, so the session isn't blocked on formatting/file I/O
-- **`/remember`** — runs friction analysis automatically (mining JSONL session logs across *all* your projects for frustration signals, failed flows, and abandonment patterns, clustered into antigen candidates), then consolidates stashes + friction antigens into `.claude/remember/MEMORY.md`; auto-injected into `CLAUDE.md` via `@MEMORY.md` so every future session benefits. Per-stash extraction runs as concurrent subagent calls on a mid-tier model — no model name hardcoded, so it works with whatever your tool has configured
+| your copy | what happens |
+|---|---|
+| identical | nothing — no write, no output |
+| missing | copied in |
+| different | moved to `AGENT_RULES.md.bak`, template copied in, both reported |
 
-`/remember` also bootstraps a one-time `AGENT_RULES.md` coding-standards template into `.claude/remember/` on first run (never overwritten again after that), referenced separately in `CLAUDE.md` for the assistant to consult when building something new — a static guide, not something the pipeline learns or extracts.
+Edits are never destroyed, but they aren't preserved in place either. `.bak` is a
+*single* file the next update overwrites — a customised body survives one release, not two.
 
-What you get is a memory that *learns from your own mistakes and interventions*, grows quietly in your repo, and works anywhere Claude Code runs. The friction pass inside `/remember` scans all your projects and gives you a per-repo reliability verdict:
+### `/stash` → `/remember` — the daily driver
 
 ```
-Per-Project:
-  my-app         56% BAD (40/72)  median: 16.0  🔴
-  api-service    40% BAD (2/5)    median:  0.5  🟡
-  web-client      0% BAD (0/1)    median:  0.0  ✅
+/stash  ──►  /remember
+capture      consolidate
+```
 
-WORST: my-app/0203-1630-11eb903a  peak=225  turns=127
-BEST:  web-client/0202-2121-8d8608e1  peak=0  turns=4
+**`/stash`** is project-local: one session, one feature or scope or goal. Start fresh
+on delivery, or when context hits ~30% (never past 40%). The stash is the clean handoff
+to the next session.
 
-Verdict: USEFUL    Intervention predictability: 93%
-```
+**`/remember`** fires on the nudge every 5 stashes. It folds those 5 in — and it also
+reads across *all* your projects, mining session logs for where you and the model
+actually collided: corrections, dead ends, abandoned flows. Those become rules, so the
+next session is less wrong than this one.
 
-Results land in `.claude/remember/friction/antigen_review.md` with projects, error patterns, and offending tool sequences called out per cluster — which `/remember` then encodes as rules the next session sees.
+Markdown files, no database, no RAG, always hot in context, and it keeps the nuances of
+each project separate. Runs on a mid-tier model.
 
-> This is the thing in liteagents that nothing else ships. Normal skill bundles give you instructions. The hot-memory pipeline gives you instructions the assistant wrote for itself, from your own logs.
+### `/docs-builder` — the other daily driver
 
----
+Markdown gets out of hand. A token-hungry agent then can't find the knowledge that
+matters. (Its own PRD grew from 500 lines to 3k+ as findings piled in — exactly the
+problem it exists to solve.)
 
-## What's Included
-
-### 11 Agents
-
-**Workflow Agents (3):**
-- **1-create-prd** - Define scope with structured Product Requirement Documents
-- **2-generate-tasks** - Break PRDs into granular, actionable task lists
-- **3-process-task-list** - Execute tasks iteratively with progress tracking and review checkpoints
-
-**Specialist Agents (8):**
-- **orchestrator** - Analyze intent, coordinate workflows, route to optimal agent sequences
-- **code-developer** - Implementation, debugging, refactoring, code best practices
-- **quality-assurance** - Test architecture, quality gates, requirements traceability, risk assessment
-- **context-builder** - Initialize project context, discover documentation, create knowledge bases
-- **feature-planner** - Epics, user stories, prioritization, backlog management, retrospectives
-- **market-researcher** - Market analysis, competitive research, project discovery, brainstorming
-- **system-architect** - System design, technology selection, API design, scalability planning
-- **ui-designer** - UI/UX design, wireframes, prototypes, accessibility, design systems
-
-### 18 Commands/Skills
-
-**Auto-Triggering Skills (3)** - Claude Code only:
-- **tdd-flow** - Write test first, watch fail, minimal passing code
-- **test-traps** - Prevent mocking anti-patterns
-- **verify-done** - Verify before claiming done
-
-**Manual Skills/Commands (15):**
-
-*Hot Memory Pipeline (2)* — see the [Hot Memory](#hot-memory--project-local-learning-from-your-own-sessions) section above for the full walkthrough:
-- **stash** - Snapshot session context to `.claude/stash/` before compaction, handoff, or ending complex work
-- **remember** - Consolidate stashes + friction antigens into `.claude/remember/MEMORY.md`; auto-injected via `@.claude/remember/MEMORY.md`
-
-*Design*:
-- **live-canvas** - Design UI variations with click-to-annotate feedback in the browser; ships a companion MCP channel plugin for Claude Code so Saves stream into the session in real time. Other tools use batch mode.
-
-*Workflow & analysis*:
-- **brainstorming** - Structured brainstorming sessions
-- **docs-builder** - Reorg a docs corpus, split an oversized doc, search it, keep pages current, index them
-- **trace-back** - Trace bugs backward through call stack
-- **skill-creator** - Guide for creating new skills
-- **debug-method** - Four-phase debugging framework
-- **optimize** - Performance analysis
-- **refactor** - Safe refactoring with behavior preservation; with no arguments, works through the fix ledger `/branch-review` accumulated
-- **branch-review** - Pre-merge gate that reports and never fixes: general review at a chosen effort level, a full security audit that runs at full depth regardless of level, then an adversarial verify pass. Needs a clean tree. Only reproduced Critical/High failures block; everything else lands in the fix ledger for `/refactor`
-- **security** - Standalone vulnerability scan; also runs as stage 2 of `/branch-review`
-- **ship** - Mechanical pre-deploy gate: every item is answerable by running a command and reading its exit code, recorded as pass/fail/N/A. A check not run is a fail, and N/A needs a stated reason
-- **release** - Prepare a release on the current branch: verify → docs sweep → version bump → local commit, then hand back the merge/tag/publish sequence (never pushes). Refuses without a review recorded at the current HEAD SHA
-- **test-generate** - Generate test suites
-
-> **Claude-only plugin:** `live-canvas-channel` is a bundled Claude Code MCP channel plugin that ships under `~/.claude/plugins/live-canvas-marketplace/`. One-time `/plugin install` + a session started with `--dangerously-load-development-channels` unlocks live mode. Skill probes for the channel on each invocation and handholds setup when missing. See [`packages/claude/skills/live-canvas/README.md`](packages/claude/skills/live-canvas/README.md) for the full walkthrough.
+It indexes everything under `/docs` in four buckets — `product/`, `logs/`, `wiki/`,
+`archive/` — reorganizes, indexes, and splits oversized docs so you don't have to.
+Mid-tier model.
 
----
+### `/live-canvas` — the UI every agent CLI was missing
 
-## Documentation
+A terminal agent can't see your screen, and you can't describe "that padding, on that
+card, but only on mobile" in words without burning ten minutes.
 
-| Document | Description |
-|----------|-------------|
-| **[INSTALLER_GUIDE.md](docs/product/INSTALLER_GUIDE.md)** | Complete installation guide, troubleshooting, and FAQ |
-| **[subagentic-manual.md](packages/subagentic-manual.md)** | Detailed agent/command reference |
-| **[remember-README.md](docs/product/remember-README.md)** | How hot memory works — the `/stash` → `/remember` pipeline, the friction sensor, and the antigen ledger |
-| **[docs-builder-README.md](docs/product/docs-builder-README.md)** | How `/docs-builder` works — the reorg/cleanup modes, what it measurably costs, and the ledger that tracks doc drift |
-| **[branch-review-README.md](docs/product/branch-review-README.md)** | How the pre-merge gate works — the three stages, what blocks a merge, and the `/branch-review` → fix ledger → `/refactor` loop |
+`/live-canvas` spins up one lightweight localhost page with your UI on it. You **click
+the thing that needs changing**, type what you want, and submit. Comment on as many
+elements as you like, all in one pass, then send the batch to the agent.
 
----
+Two ways it comes back:
 
-## Example Workflows
+- **JSON mode** — feedback lands in a file, you tell the agent to read it. Works in any tool.
+- **Live mode** — an MCP channel streams each comment straight into the session, so edits
+  land while you're still in the browser. Claude Code only.
 
-**Feature Development:**
-```
-@orchestrator I need to add user authentication
-# Orchestrator routes to:
-# → market-researcher (research approaches)
-# → 1-create-prd (requirements)
-# → 2-generate-tasks (implementation tasks)
-# → 3-process-task-list (execution)
-```
+It also ships with real UI direction baked in, so it can generate variations of a screen
+for you to pick from — no more hours spent nudging divs to find out what you actually wanted.
 
-**Code Quality:**
-```
-@quality-assurance Review this PR before merge
-/branch-review main medium  # review + security audit; blockers reported, the rest to the fix ledger
-/refactor                   # no args: work through the fix ledger branch-review accumulated, between features
-/debug-method Investigate this race condition
-```
+### `/branch-review` → `/release` → `/refactor`
 
-**Architecture & Design:**
-```
-@system-architect Design microservices architecture
-@ui-designer Create wireframes for mobile checkout
-```
+- **`/branch-review`** — the powerhouse. Reviews every change on a branch, medium depth
+  by default. Surfaces confirmed blockers only: real bugs, dead and unused code,
+  state-ownership breaks, plus a full OWASP-shaped security pass (no leaked keys, no
+  injection, trust boundaries checked) that runs at full depth regardless of level.
+  Everything non-blocking goes to the fix ledger.
+- **`/release`** — does the pre-release chores you'd otherwise do by hand: README,
+  CHANGELOG, PRD, findings, version bump, local commit. Then it tells you you're ready
+  to merge, and hands the sequence back. It never pushes.
+- **`/refactor`** — with no arguments, works the fix ledger. Cumulative by design: nits
+  pile up until you choose to clear them, so review and release never drown in them.
 
 ---
 
-## Stats
+## Deeper docs
 
-- **11** Specialized Agents
-- **18** Workflow Commands & Skills
-- **4** Supported Tools (Claude, Opencode, Ampcode, Droid)
-- **Apache-2.0** License
+| Document | What's in it |
+|---|---|
+| [`/remember`](docs/product/remember-README.md) | The `/stash` → `/remember` pipeline, friction sensor, antigen ledger |
+| [`/docs-builder`](docs/product/docs-builder-README.md) | Reorg and cleanup modes, measured cost, the drift ledger |
+| [`/branch-review`](docs/product/branch-review-README.md) | The three stages, what blocks, the fix-ledger loop |
+| [`/live-canvas`](docs/product/live-canvas-README.md) | Both modes, the click-to-annotate overlay, and setup |
+| [live-canvas-channel](docs/product/live-canvas-channel-README.md) | The Claude Code MCP channel plugin — install, protocol, debugging |
+| [Installer guide](docs/product/INSTALLER_GUIDE.md) | Install, custom paths, uninstall, troubleshooting, FAQ — and how to change a command, skill or subagent |
+| [All agents & commands](packages/subagentic-manual.md) | Full agent and command reference |
+| [Doc index](docs/index.md) | Generated index of every doc, rebuilt on each reorg |
 
 ---
 
@@ -213,12 +181,4 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 - **GitHub:** https://github.com/hamr0/liteagents
 - **Issues:** https://github.com/hamr0/liteagents/issues
 
----
-
-## License
-
 Apache-2.0 © 2026 hamr0 — see [LICENSE](LICENSE).
-
----
-
-**Need help?** See the [Installer Guide](docs/product/INSTALLER_GUIDE.md) or [open an issue](https://github.com/hamr0/liteagents/issues)

package/installer/cli.js

@@ -13,13 +13,16 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const os = require('os');
 
 // Single source of truth for version; UPDATE_VERSION.sh bumps only package.json.
 const PACKAGE_JSON = require('../package.json');
 const PACKAGE_VERSION = PACKAGE_JSON.version;
 // Banner counts derived from the description field — same source as README.
-const AGENT_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+specialized agents/) || [, '11'])[1];
-const COMMAND_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+commands/) || [, '18'])[1];
+const AGENT_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+specialized agents/) || [, '10'])[1];
+// Claude Code and Amp ship these as skills, Droid and opencode as commands,
+// so the banner counts capabilities rather than naming one shape.
+const CAPABILITY_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+capabilities/) || [, '13'])[1];
 
 // ANSI color codes
 const colors = {
@@ -30,9 +33,35 @@ const colors = {
   yellow: '\x1b[33m',
   cyan: '\x1b[36m',
   magenta: '\x1b[35m',
-  red: '\x1b[31m'
+  red: '\x1b[31m',
+  dim: '\x1b[2m'
 };
 
+/**
+ * Render the closing note about backed-up installs, printed after `Done!`.
+ * Returns '' when backupLog is empty so a fresh install's output is
+ * unchanged. Never names `commands/` vs `command/` (opencode uses the
+ * singular form) — the note points at the shared `remember/` folder inside
+ * the backup, which is the same for every tool.
+ *
+ * @param {Array<{original: string, backup: string}>} backupLog
+ * @returns {string} Text to print (includes its own leading newline), or ''.
+ */
+function formatBackupClosingNote(backupLog) {
+  if (!backupLog || backupLog.length === 0) {
+    return '';
+  }
+
+  const lines = [`${colors.yellow}Previous install(s) backed up:${colors.reset}`];
+  for (const entry of backupLog) {
+    lines.push(`  ${entry.backup.replace(os.homedir(), '~')}`);
+  }
+  lines.push(`${colors.dim}If you had edited AGENT_RULES.md, your copy is preserved in`);
+  lines.push(`each backup's remember/ folder.${colors.reset}`);
+
+  return `\n${lines.join('\n')}`;
+}
+
 class InteractiveInstaller {
   constructor() {
     this.rl = readline.createInterface({
@@ -463,7 +492,7 @@ ${colors.bright}${colors.cyan}██╔══██║██║   ██║█
 ${colors.bright}${colors.cyan}██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██║╚██████╗    ██║  ██╗██║   ██║${colors.reset}
 ${colors.bright}${colors.cyan}╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚═════╝    ╚═╝  ╚═╝╚═╝   ╚═╝${colors.reset}
 
-${colors.bright}v${PACKAGE_VERSION} | ${AGENT_COUNT} agents + ${COMMAND_COUNT} commands per tool${colors.reset}
+${colors.bright}v${PACKAGE_VERSION} | ${AGENT_COUNT} agents + ${CAPABILITY_COUNT} capabilities per tool${colors.reset}
     `);
   }
 
@@ -701,6 +730,11 @@ ${colors.bright}v${PACKAGE_VERSION} | ${AGENT_COUNT} agents + ${COMMAND_COUNT} c
     }
 
     console.log(`\n${colors.bright}${colors.green}Done!${colors.reset}`);
+
+    const closingNote = formatBackupClosingNote(installationEngine.backupLog);
+    if (closingNote) {
+      console.log(closingNote);
+    }
   }
 
   /**
@@ -765,4 +799,5 @@ if (require.main === module) {
   installer.run().catch(console.error);
 }
 
-module.exports = InteractiveInstaller;
+module.exports = InteractiveInstaller;
+module.exports.formatBackupClosingNote = formatBackupClosingNote;