liteagents 3.0.0 → 3.5.0

package/CHANGELOG.md

@@ -7,7 +7,128 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [Unreleased]
+## [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
 

package/README.md

@@ -9,217 +9,169 @@
          ╚══════╝╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
 ```
 
-**AI development toolkit with 10 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** - 10 subagents + 8 skills + 10 commands (+ optional live-canvas channel plugin)
-- **Opencode** - 10 agent references + 18 commands
-- **Ampcode** - 10 subagents + 18 commands
-- **Droid** - 10 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
 
-### Start Using
+**Agents** — invoke with `@name` (Claude Code) or `/name`.
 
-```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
-```
+| 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>
 
 ---
 
-## Hot Memory — project-local learning from your own sessions
+## The ones that carry the load
 
-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 an `@.claude/remember/MEMORY.md` include.
+### `AGENT_RULES.md` — the architect behind every project
 
-```
-/stash  →  /remember
-capture    analyze + consolidate
-```
-
-- **`/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 an explicit `@.claude/remember/MEMORY.md` include 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
-
-### `AGENT_RULES.md` — the standards doc that primes every session
+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.
 
-`/remember` installs an `AGENT_RULES.md` coding-standards template into `.claude/remember/` (`.factory/`, `.amp/`, `.opencode/` for the other tools) and references it from `CLAUDE.md` (`AGENT.md` / `AGENTS.md`) as a plain pointer, so the assistant consults it when building something new. It is a static guide — not something the pipeline learns or extracts.
+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.
 
-**It is kept current on every `/remember` run**, because a shipped standards doc that never updates is a stale one: 35 local repos were measured drifting many releases behind before this existed. Each run compares your copy against the template that came with your installed liteagents:
+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.
 
 | your copy | what happens |
 |---|---|
-| identical to the template | nothing at all — no write, no output |
+| identical | nothing — no write, no output |
 | missing | copied in |
-| **different** | moved to `AGENT_RULES.md.bak`, new template copied in, both reported |
+| different | moved to `AGENT_RULES.md.bak`, template copied in, both reported |
 
-So **edits are never destroyed, but they are not preserved in place either.** If you have customised your rules, fold your changes into the new `AGENT_RULES.md` after an update — `AGENT_RULES.md.bak` is a *single* file that the next update overwrites, so a customised body survives one release, not two.
+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.
 
-To get a newer template in the first place, update the package: `/remember` tells you when your install is behind, and `npm i -g liteagents@latest && liteagents` refreshes it (your previous install is backed up automatically).
-
-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  ✅
-
-WORST: my-app/0203-1630-11eb903a  peak=225  turns=127
-BEST:  web-client/0202-2121-8d8608e1  peak=0  turns=4
-
-Verdict: USEFUL    Intervention predictability: 93%
+/stash  ──►  /remember
+capture      consolidate
 ```
 
-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.
+**`/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.
 
-> 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.
+**`/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.
 
----
+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.
 
-## What's Included
+### `/docs-builder` — the other daily driver
 
-### 10 Agents
+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.)
 
-**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
+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.
 
-**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
-- **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
+### `/live-canvas` — the UI every agent CLI was missing
 
-### 18 Commands/Skills
+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.
 
-**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
+`/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.
 
-**Manual Skills/Commands (15):**
+Two ways it comes back:
 
-*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`
+- **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.
 
-*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.
+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.
 
-*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
+### `/branch-review` → `/release` → `/refactor`
 
-> **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.
+- **`/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.
 
 ---
 
-## Documentation
-
-| 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/README.md](packages/claude/skills/live-canvas/README.md)** | How `/live-canvas` works — the two modes, the click-to-annotate channel, and the Claude Code plugin setup |
-| **[docs/README.md](docs/README.md)** | Entry point for this repo’s own docs — what lives in `product/`, `archive/` and the operation log |
-| **[docs/index.md](docs/index.md)** | The generated index of every doc, with heading ranges. Rebuilt by `/docs-builder` on every reorg or split |
-
----
+## Deeper docs
 
-## Example Workflows
-
-**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)
-```
-
-**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
-```
-
-**Architecture & Design:**
-```
-@system-architect Design microservices architecture
-@ui-designer Create wireframes for mobile checkout
-```
-
----
-
-## Stats
-
-- **10** 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 |
 
 ---
 
@@ -229,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

@@ -20,7 +20,9 @@ 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/) || [, '10'])[1];
-const COMMAND_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+commands/) || [, '18'])[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 = {
@@ -490,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}
     `);
   }
 

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "liteagents",
-  "version": "3.0.0",
-  "description": "AI development toolkit with 10 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

@@ -21,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] |
@@ -52,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.