peaks-loop 3.1.2 → 4.0.0-beta.10

package/README-en.md

@@ -1,281 +1,227 @@
 <div align="center">
 
-# ⛰️ Peaks
-
-<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=700&size=22&duration=3000&pause=800&color=6366F1&center=true&vCenter=true&multiline=true&width=720&height=110&lines=peaks-loop%3A%20cross-AI-IDE%20engineering%20gates%20%26%20orchestration;11%20%E2%9A%99%EF%B8%8F%20workflow%20skills%20%2B%20%E2%9A%96%EF%B8%8F%20executable%20gates;%E2%9C%89%EF%B8%8F%20%E2%9A%96%EF%B8%8F%20%E2%9C%89%EF%B8%8F%20%E2%9A%91%EF%B8%8F%20%E2%9A%96%EF%B8%8F%20%E2%9C%89%EF%B8%8F%20%E2%9A%91%EF%B8%8F%20gates%20%2B%20audit%20%2B%20cross-IDE%20adaptation" alt="peaks-loop tagline typing animation" />
-
-**English** | [简体中文](./README.md)
-
-<table>
-<tr>
-<td align="center" width="180"><b>🔥 PROJECT</b></td>
-<td align="center" width="180"><b>⚡ BASED ON</b></td>
-<td align="center" width="180"><b>📚 SKILLS.SH</b></td>
-</tr>
-<tr>
-<td align="center"><a href="https://github.com/SquabbyZ/peaks-loop">peaks-loop / Homepage</a></td>
-<td align="center">13 Skills + Cross-IDE</td>
-<td align="center"><a href="https://skills.sh/SquabbyZ/peaks-loop">Listed on skills.sh</a></td>
-</tr>
-<tr><td colspan="3">&nbsp;</td></tr>
-<tr>
-<td align="center" width="180"><b>⭐ STARS</b></td>
-<td align="center" width="180"><b>📦 VERSION</b></td>
-<td align="center" width="180"><b>📄 LICENSE</b></td>
-</tr>
-<tr>
-<td align="center"><a href="https://github.com/SquabbyZ/peaks-loop/stargazers"><img src="https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&logoColor=white" alt="stars" /></a></td>
-<td align="center"><a href="https://www.npmjs.com/package/peaks-loop"><img src="https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="npm version" /></a></td>
-<td align="center"><a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="license" /></a></td>
-</tr>
-<tr><td colspan="3">&nbsp;</td></tr>
-<tr>
-<td align="center" width="180"><b>🧪 TESTS</b></td>
-<td align="center" width="180"><b>🔧 LANG</b></td>
-<td align="center" width="180"><b>📥 DOWNLOADS</b></td>
-</tr>
-<tr>
-<td align="center"><b>2,800+</b></td>
-<td align="center"><b>TypeScript</b></td>
-<td align="center"><a href="https://www.npmjs.com/package/peaks-loop"><img src="https://img.shields.io/npm/dm/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="downloads" /></a></td>
-</tr>
-<tr><td colspan="3">&nbsp;</td></tr>
-<tr>
-<td align="center" width="180"><b>🌐 中文</b></td>
-<td align="center" width="180"><b>🚀 QUICK START</b></td>
-<td align="center" width="180"><b>👁️ VISITORS</b></td>
-</tr>
-<tr>
-<td align="center"><a href="./README.md">简体中文</a></td>
-<td align="center"><a href="#-30-seconds-to-running">30s to running →</a></td>
-<td align="center"><img src="https://komarev.com/ghpvc/?username=SquabbyZ&repo=peaks-loop&label=views&color=blue&style=for-the-badge" alt="visitors" /></td>
-</tr>
-</table>
-
-<img src="https://github-readme-streak-stats.herokuapp.com?user=SquabbyZ&repo=peaks-loop&theme=radical&hide_border=true&date_format=j%20M%5B%20Y%5D" alt="GitHub Streak Stats" />
-
-[Install](#-30-seconds-to-running) · [5-min onboarding](#-5-minute-onboarding) · [Skill family](#-11-skills-in-the-family) · [Killer feature: un-bypassable gates](#-killer-feature-un-bypassable-gates)
+# peaks-loop
 
-</div>
-
----
+### You talk. It runs the entire engineering chain for you — beyond just code, twice-run flows sediment into local tactics.
 
-## 🤔 Why Peaks
+[![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
+[![tests](https://img.shields.io/badge/tests-5%2C439%20passed-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
+[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
 
-> Do you put `git push --force`, `rm -rf`, `npm publish`, `DROP TABLE` into your `CLAUDE.md`?
-> The LLM won't really listen. It has a 99% chance of "respecting your preference" — then forgetting it in the next session.
-> **CI can only block at merge time; prose rules rely on goodwill; only gates can stop the agent mid-swing.**
+**English** · [简体中文](./README.md)
 
-Peaks models the "engineering team" inside your AI IDE as 13 workflow skills + a set of **executable gates**:
+</div>
 
-- 🧭 **Skills** — `peaks-solo` orchestrates; `peaks-prd / rd / qa / ui / sc / txt / sop` each own a phase; the LLM picks the right role for the task
-- 🚧 **Gates** — SOP attaches checkable conditions (file-exists / grep / command exit code) to each phase; unmet gates block `git push` **in front of the agent itself** — even under `--dangerously-skip-permissions`
-- 🧠 **Project memory** — `.peaks/memory/` captures decisions, gotchas, conventions into git; next session picks up where you left off
-- 🌐 **Cross-IDE** — one CLI, native-skill rendering for Claude Code / Trae / Cursor / Codex / Qoder
-- 📦 **Discoverable** — the 13 skills are also published to [skills.sh](https://skills.sh); `npx skills add` to install on demand
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo-en.gif"
+    alt="peaks-loop 30-second demo (first 18s · install + slash command + 5 domains + sediment into bee)"
+    width="92%"
+    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
+  />
+  <br>
+  <sub>👆 18s looping GIF (<a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo-en.mp4">full 30s mp4 download</a> · 13MB · 480p)</sub>
+</p>
 
-## 🚀 30 seconds to running
+---
 
-```bash
-# 1. Install the CLI
-npm install -g peaks-loop
+## What it is
 
-# 2. Open Claude Code in your project
-cd /path/to/your-project && claude
+peaks-loop is a **Loop Engineering crystallization system**, not a workflow tool — what sediments from the runs you do is **not** a procedure, it's a set of **Loop Engineering** method assets that are karpathy-engineered at the rule level and darwin-verified at the change level. The **Loop engineering, engineered** crystallization design lives at [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md).
 
-# 3. Tell the AI what to do
-> peaks-solo add OAuth callback to the login page
-```
+| Asset layer | Role | One-liner |
+| --- | --- | --- |
+| **Loop Engineering Asset** | Method system, first-class | Answers "why this loop exists, when it fires, what counts as success, how it improves" |
+| **Bee Asset** | Executable body, first-class | The runnable body of a Loop Engineering Asset — every bee in the swarm |
+| **Workflow Trace** | Evidence, **NOT** the durable product | Immutable per-run record; feeds crystallization + evaluation, not the user-facing asset |
+| **Evolution Evaluation** | Anti-drift gate, mandatory | Every improvement needs an independent-context scorer + a regression skeptic; keep only if it passes, otherwise revert |
 
-That's it. First run bootstraps the `.peaks/` workspace, scans the project archetype, and dispatches the task to the right skills (PRD → RD → UI → QA → SC → TXT). All intermediate artifacts stay on disk. **In daily use, 1 skill (`peaks-solo`) covers ≥ 90% of needs.** As of v2.13.1, 5 heterogeneous signals (security-audit / perf-audit / karpathy / mut / qa) converge into a single verdict via `block > return-to-rd > warn > pass` precedence; the repair loop prints a `re-run reason: { source, signal, file, line, hint }` payload for every re-dispatch. As of v2.13.2, `peaks verdict aggregate --from-rid <rid>` exposes the aggregator as a CLI subcommand, and a v2.13.1 cross-source dedup bug is fixed: identical (file, line, hint) from security + perf now collapses to a single reason with both sources in a `sources[]` field.
+- **Engineering principles = karpathy-style · Verify every improvement = darwin-style** — both are required, not optional. Drop karpathy and your principles are never written down; drop darwin and your changes are never verified. They are co-equal layers, not sequential steps.
+- `/peaks-code` is the **code-domain** long-task Loop Engineering orchestrator, not a general orchestrator; non-code lanes (`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`) ship as independent `peaks-*` bees, **not** as subclasses of `peaks-code`.
+- Twice-clean runs sediment into your local tactic pool (bee); broken runs come back for you to redefine. Your few bees grow with your taste.
 
-## ⏱️ 5-minute onboarding
+---
 
-In an adapted AI IDE conversation, just ask the AI to use a skill by name:
+## Up and running in 30 seconds
 
-```text
-peaks-solo add OAuth callback to the login page    # end-to-end orchestrator (the common case)
-peaks-prd  define goals, non-goals, acceptance for the invitation feature
-peaks-rd   analyze the smallest refactor slice and risks
-peaks-qa   design tests and regression checks for this change
-peaks-ui   design the login page interaction and visual approach
-peaks-sc   record change impact, artifact retention, commit boundaries
-peaks-txt  generate a context capsule with key decisions
-peaks-sop  turn my "publish a post" flow into a gated SOP
+```bash
+npm i -g peaks-loop
 ```
 
-**Two ways to use Peaks**:
+Then, in the **Claude Code** or **Z Code** chat you already use, send an **explicit slash command** (the leading slash is what triggers peaks-loop — a plain sentence won't always route here):
 
-1. **Let `peaks-solo` orchestrate** (the common case) — tell it what to do and it coordinates the PRD → RD → UI → QA → SC → TXT chain
-2. **Invoke a single role skill directly** (advanced) — when you only want one phase of the workflow
+```
+/peaks-code walk me through this codebase
+```
 
-Quick status check? Ask the AI to run:
+The rest is peaks-loop's job — it picks the domain from the slash, routes to the right orchestrator, splits the work gate by gate, **stops where it breaks**, never hands you a half-finished slice.
+
+Other slash commands you'll reach for:
 
-```bash
-peaks -V                       # version
-peaks doctor --json            # environment / skills / config one-shot check
-peaks project dashboard --project . --json   # one-shot project view
+```
+/peaks-content                 draft and publish today's post
+/peaks-doctor                  run a health check on this repo
+/peaks-issue-fix-orchestrator  fix the next 30 open issues upstream
+/peaks-sop                     author the team's release SOP
+/peaks-solo                    I'll do this again — sediment it as a local tactic
+/peaks-solo                    run it like last time
 ```
 
-## 🧰 13 skills in the family
+<sub>📦 Adapters for other AI coding tools are coming — contributions welcome → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).</sub>
 
-| Skill | What you use it for | Typical scenario |
-|------|--------------------|------------------|
-| `peaks-solo` | **End-to-end orchestrator** — coordinates prd/rd/ui/qa/sc/txt | Full-cycle dev, PRD-to-ship, batched cross-slice iterations |
-| `peaks-prd` | Fuzzy intent → **verifiable PRD** (goals / non-goals / preserved behavior / acceptance) | Requirements, PRD authoring, refactor goal definition |
-| `peaks-rd` | Engineering analysis + slice planning + risk + execution contracts | Architecture analysis, minimum slices, risk review |
-| `peaks-qa` | Test design + coverage + regression matrix + acceptance evidence | Test cases, regression, browser E2E |
-| `peaks-ui` | Visual direction + interaction design + design-system constraints | Page design, interaction, prototypes, UI regression |
-| `peaks-sc` | Change control + commit boundaries + retention + rollback evidence | Impact records, change control, audit |
-| `peaks-txt` | Context capsules + decision records + knowledge compression | Module understanding, decision capture, retros |
-| `peaks-sop` | **Turn any workflow into a gated SOP** (not just dev) | Content publishing, compliance checklists, data pipelines, ops runbooks |
-| `peaks-solo-resume` | Continue the unfinished slice | "resume the unfinished slice" |
-| `peaks-solo-status` | One-shot snapshot of where you are | "where are we now" |
-| `peaks-solo-test` | Run the project test suite (auto-detects vitest / jest / pytest / ...) | "run the tests" |
-| `peaks-security-audit` | **Independent security audit** (OWASP Top-10 + 8-dim threat model) | Slices introducing authn/authz, secrets, input validation, SQL injection, external API surface |
-| `peaks-perf-audit` | **Independent perf audit** (6-dim perf impact) | Hot loops, I/O throughput, concurrency model, bundle size, cold-start changes |
+No CLI to memorize. No manifest to hand-author. No second terminal to open. **Send the slash, the rest is on it.**
 
-**3 solo wrappers + 7 role skills + 2 standalone audits + 1 orchestrator = 13 skills.** In daily use, 1 skill (`peaks-solo`) covers ≥ 90% of needs.
+---
 
-> **v2.13.0**: zero-human-intervention **auto-compact** (`peaks solo context-now` + `peaks solo auto-compact`) — peaks-loop probes context-fill % autonomously. ≥85% writes a pre-compact checkpoint + convergence plan + dispatches IDE compact. ≥95% forces a synchronous RED-LINE compact. The LLM-runner stays alive with context < 95% without human intervention. **v2.13.4 fix**: auto-compact now targets the **main-session** context (not a sub-agent shell). **3.0.3 new `ide-native` pathway**: installs a PreToolUse hook into `.claude/settings.local.json` (`Bash|Task` matcher → `peaks session auto-compact-hook`); the runner's next Bash/Task tool call in-band spawns `claude --compact`, no longer relying on the LLM to remember to fire `/compact`. Hook is ENOENT-safe (exits 0 + stderr hint if `claude` is not on PATH; runner is never interrupted).
+## What it does for you
 
-## 🚧 Killer feature: un-bypassable gates
+Code, content, project health, issue sweeps, custom workflows — **4.x ships five first-class domains**, each with its own orchestrator. Same discipline on every lane: "gate fails = stop, run the next gate".
 
-> CI only blocks at **merge time**; `CLAUDE.md` rules rely on agent **goodwill**. **SOPs do what neither can: stop an irreversible action mid-conversation, against the agent itself.**
+| Domain | Send this slash command | It will… |
+| --- | --- | --- |
+| 💻 **Code (code-domain) only** | `/peaks-code build this feature` | PRD → RD → code → QA → UI → slice, ready for your sign-off |
+| 💻 **Code (code-domain) only** | `/peaks-code fix this bug` | reproduce → patch → review → tests, ship same day |
+| 📝 **Content** | `/peaks-content draft and publish this post` | draft → edit → tone check → publish → archive, no skipped steps |
+| 🩺 **Project health** | `/peaks-doctor run a health check on this repo` | red-line audit + L3 doctor + convert to OpenSpec, stops where it breaks |
+| 🐛 **Issue sweep** | `/peaks-issue-fix-orchestrator fix the next 30 open issues upstream` | survey → classify → reference PRs → fix + commit + PR draft |
+| 📋 **Custom workflow** | `/peaks-sop author the team's release SOP` | describe in plain language → auto-generate + validate + register |
+| 🔁 **Replay** | `/peaks-solo run it like last time` | pull up your sedimented tactic, replay it |
+| 🆕 **Onboard** | `/peaks-code this is a new repo, walk me through it` | map structure, flag risks, hand you a learning order |
+| 🧠 **Sediment** | `/peaks-solo I'll do this again — save it` | ground it locally as a reusable tactic |
 
-```jsonc
-// sop.json
-"guards": [ { "phase": "publish", "bash": "git +push" } ]
-```
+Every lane opens with **one slash command**.
 
-```bash
-peaks hooks install --project <repo>   # explicit opt-in: writes one PreToolUse entry
-```
+---
 
-After that, when the agent tries `git push` while a publish gate is failing, Claude Code receives `permissionDecision: "deny"` — the command is blocked **before any permission check, even under `--dangerously-skip-permissions`**. Three gate types:
+## Why people pick it
 
-| Type | Meaning | Example |
-|------|---------|---------|
-| `file-exists` | File exists → pass | `CHANGELOG.md` exists |
-| `grep` (+ `absent`) | Regex matches in file → pass; `absent: true` inverts ("must not contain X") | "post body has no `TODO`" |
-| `command` | Run a command, judge by exit code (refused by default; needs `--allow-commands`) | run `npm test` |
+- **Natural language is the interface.** No CLI to learn, no commands to memorize. **Use an explicit slash command (e.g. `/peaks-code xxx`)** to route to the right orchestrator; everything after the slash is plain language. The LLM runs the commands on your behalf.
+- **Gates that actually block, not decorate.** 5,439 test cases, QA gate, review sign-off — all on by default. **Audit fails = stop. QA fails = stop.**
+- **Run-once flows become local tactics (bees).** Sedimented loop engineering lands in your local `~/.peaks/` pool — twice-clean runs auto-promote to standing tactics, broken runs come back for you to redefine. **Next time, just say "run that one" and the whole playbook slots back in.** Your few tactics grow with your taste.
+- **Sits on top of what you already run.** Not a new AI CLI to learn — it rides on **Claude Code** and **Z Code**. No shell grab, no prompt grab, no IDE grab. Other tools: adapters in progress, contributions welcome.
+- **You decide, it executes.** Decisions that touch your assets are yours; everything else it runs on its own. **Zero learning cost. One minute to first task.**
 
-Definitions (`sop.json` + `SKILL.md`) can live in the **global** layer `~/.peaks/sops/` (your personal cross-project SOPs) or the **project** layer `<repo>/.peaks/sops/` (committed into the repo, team-shared — wins over global). **Emergency bypass**: `peaks gate bypass --sop <id> --phase <phase> --reason "<why>"` (one-shot, capped per project per SOP, reason audited).
+---
 
-## 🌍 Real-world scenarios
+## What gates ship by default
 
-**Scenario 1: ad-hoc refactor decision**
+| Gate | Default | What it catches |
+| --- | --- | --- |
+| Unit + integration tests | ✅ on | regressions at the code level |
+| Code audit (lint / prose / type) | ✅ on | drift in style and intent |
+| Security scan | ✅ on | secrets, SSRF, injection, dangerous IO |
+| QA review | ✅ on | task-level gate — fails loud, stops clean |
+| Review sign-off | ✅ on | nothing ships without eyes on it |
 
-```text
-> peaks-rd analyze src/auth/ current state and give me the smallest-slice plan
-```
-`peaks-rd` outputs: 3-phase slices, risk assessment, regression points, executable contracts. **Whether to actually code is your call.**
+**All gates on by default. You only speak to turn one off.**
 
-**Scenario 2: turn "blog publishing" into a controlled flow**
+---
 
-```text
-> peaks-sop turn "blog publishing" into a gated SOP: draft → self-check (no TODO / ≥ 800 words) → human review → publish
-```
-`peaks-sop` generates `sop.json` + `SKILL.md`, registers globally, **the agent cannot publish if any step is skipped**.
+## Status · shipping 4.x
 
-**Scenario 3: browser E2E regression**
+| | |
+| --- | --- |
+| **Latest** | [`4.0.0-beta.7`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x GA is in the works |
+| **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test`) |
+| **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
+| **Test suite** | 5,439 passed · 19 skipped · 0 failed |
+| **IDE adapters** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder (adapters in progress — contributions welcome) |
+| **Runtime** | Node ≥ 20 |
+| **License** | MIT |
 
-```text
-> peaks-qa run a browser over the full register → login → dashboard flow and list the blockers
-```
-`peaks-qa` outputs: test matrix, regression checklist, `code-review.md`-style evidence document.
+---
 
-**Scenario 4: resume the slice from yesterday**
+## Strongly recommended · compose these four
 
-```text
-> peaks-solo-resume
-```
-Detects the in-flight slice's deepest-completed gate, saves 3-5k tokens vs re-reading artifacts. **Sessions break, context survives.**
+> **Zero learning cost.** That's the biggest reason to use them together — not just that the effect is excellent, but that **all four projects speak the same interface: natural language + a choice.** You say one sentence; the LLM runs the commands, applies the gates, and follows the playbook.
 
-## 📦 Discover peaks on skills.sh
+<p align="center">
+  <a href="https://github.com/affaan-m/ECC">
+    <img src="https://img.shields.io/badge/ECC-affaan--m-6366f1?style=for-the-badge&logo=github&logoColor=white" alt="affaan-m/ECC" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/Egonex-AI/Understand-Anything">
+    <img src="https://img.shields.io/badge/Understand--Anything-Egonex--AI-22c55e?style=for-the-badge&logo=github&logoColor=white" alt="Egonex-AI/Understand-Anything" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/obra/superpowers">
+    <img src="https://img.shields.io/badge/superpowers-obra-f59e0b?style=for-the-badge&logo=github&logoColor=white" alt="obra/superpowers" />
+  </a>
+</p>
 
-The 11 `peaks-*` skills auto-index on the [skills.sh](https://skills.sh) registry — **no separate registration needed**. Indexing is driven by the config in this repo:
+| Role | Project | One-liner |
+| --- | --- | --- |
+| **Sediment + gates** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← you are here | loop-engineering crystallization system; install → PRD/RD/QA/UI/SC/TXT as one chain + sediment |
+| **Tactical handbook** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | everything-claude-code: the best tactics, skills, and SOPs you can put on top of Claude Code |
+| **Code understanding** | [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) | any repo, one sentence to grok it — let the LLM actually *understand* the project, not guess |
+| **Process & discipline** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review as flow disciplines, every one with a hard exit |
 
-- 13 `skills/<name>/SKILL.md` files (each with `name` + `description` YAML frontmatter) — the standard skills.sh discovery convention
-- `.claude-plugin/marketplace.json` — explicit manifest listing the 13 public skills (internal `peaks-doctor` / `peaks-ide` are hidden via `metadata.internal: true`)
+**One sentence to use them all**: clone the three repos above, install peaks-loop, hand the rest to your LLM — it pulls what it needs, holds the gates, lands the tactics, sediments the flow.
 
-Any environment with `npx skills` installed (Claude Code, Cursor, Codex, ...) can pull them directly:
+### Tribute
 
-```bash
-# Install all 13:
-npx skills add SquabbyZ/peaks-loop
+peaks-loop's two engineering spines come straight from these projects:
 
-# Or just one:
-npx skills add SquabbyZ/peaks-loop --skill peaks-solo
-npx skills add SquabbyZ/peaks-loop --skill peaks-rd
-npx skills add SquabbyZ/peaks-loop --skill peaks-sop
-```
+- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — "engineer every rule" is etched into our method layer.
+- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — "verify every improvement" is etched into our anti-drift gate.
 
-Browse [skills.sh/SquabbyZ/peaks-loop](https://skills.sh/SquabbyZ/peaks-loop) for the full catalog. The skills shipped here and the skills shipped via `npm install -g peaks-loop` are the same artifact — both paths deliver the same content.
+---
 
-## 🛠️ How it works: skills first, CLI as gates
+## FAQ
 
-The `peaks <cmd>` CLI is **not your daily driver**. It exists for three machine-level reasons only:
+<details>
+<summary><b>How does it relate to Claude Code / Z Code?</b></summary>
 
-1. **Explicit opt-in for irreversible side effects** (`peaks sop init --apply`, `peaks openspec archive --apply`) — actions that must not happen on the LLM's discretion
-2. **Structured JSON contracts** (`peaks request show ... --json`, `peaks scan archetype ... --json`) — let a skill read a machine verdict to gate its next decision
-3. **Invokable from hooks / CI / scripts** (`peaks hooks install`, `peaks gate enforce`) — turn "satisfy these gates before X" from prose into enforcement
+It **sits on top of** them, not in place of. peaks-loop doesn't grab your shell, your prompt, or your IDE. It runs as a first-class adapter on Claude Code and Z Code. **Adapters for other tools are in progress — contributions welcome** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).
 
-One line: **SKILL = the workflow's brain; CLI = the workflow's joints**.
+</details>
 
-### CLI commands you'll *see* skills call
+<details>
+<summary><b>Do I need to learn CLI commands?</b></summary>
 
-```bash
-peaks workspace init / reconcile / scan archetype / scan libraries
-peaks request init / show / transition          # PRD/RD/QA/SC state machine
-peaks session list / info / title / rotate
-peaks sop init / lint / check / advance / register
-peaks code-review detect-ocr / config-template / run-ocr   # Alibaba Open Code Review second opinion
-peaks hooks install / gate enforce / gate bypass
-peaks project dashboard / memories
-```
+No. You speak or pick; the LLM runs the commands. **All CLI verbs are hidden from you, open to the LLM.**
 
-Full list: `peaks --help`.
+</details>
 
-## 🌐 Supported IDEs
+<details>
+<summary><b>Do sedimented tactics stay on my machine?</b></summary>
 
-| IDE | Status |
-|---|---|
-| ✅ **Claude Code** | 13 skills + PreToolUse hook, agent team dogfooded |
-| ⚠️ **Trae** | slim `IdeAdapter` registered, real-Trae dogfood is a follow-up slice |
-| 📋 **Codex / Cursor / Qoder / Tongyi Lingma, and more** | On the roadmap |
+Yes. Sediment lands in a local pool, scoped to you alone. Naming, reuse, iteration — your call. Flows that broke get sent back for you to redefine.
 
-## 🏗️ Project status
+</details>
 
-- ✅ **13 skills** + cross-IDE CLI + 2,800+ tests (v2.12.0 adds `peaks-security-audit` + `peaks-perf-audit`)
-- ✅ **Gate mechanism** dogfooded on real projects
-- ✅ **v2.12.0 RD fan-out collapse** (3-way: code-reviewer + qa-test-cases-writer + karpathy-reviewer) shipped 2026-06-27
-- ✅ **v2.13.0 zero-human-intervention auto-compact** (peaks-loop drives context compression on any AI CLI; context stays < 95% autonomously) shipped 2026-06-27
-- ✅ **v2.13.4 four solo bug fixes**: Step 1 AskUserQuestion no longer auto-defaults to `full-auto`; `peaks workflow verify-pipeline` resolves the canonical `.peaks/_runtime/<sessionId>/<role>/` path; misplaced change-id dirs are tolerated by `peaks workspace init`'s `LegacyChangeIdSiblingError` guard; auto-compact now genuinely compresses the main-session context (not a sub-agent shell)
-- 📋 Roadmap: real Trae / Codex / Cursor integration, `peaks-doc` / `peaks-i18n`, SOP template marketplace
+<details>
+<summary><b>Will it change my code without me knowing?</b></summary>
 
-See [`CHANGELOG.md`](./CHANGELOG.md) and [`docs/`](./docs/) for details.
+It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = nothing ships. Review fails = nothing ships. It runs; each gate stops for your eyes.
 
-## 📄 License
+</details>
 
-[MIT](LICENSE) — commercial use, modification, private forks all welcome; keep the copyright notice.
+<details>
+<summary><b>What's new in 4.x vs 3.x?</b></summary>
 
-## 💬 Join the WeChat community
+**The biggest shift: from "code-only tool" to multi-domain orchestration system.** 4.x no longer just writes code — it ships four new domain orchestrators: `peaks-content` (content production), `peaks-doctor` (project health), `peaks-issue-fix-orchestrator` (batch issue fix), `peaks-sop` (custom SOPs). On top of that, `peaks-solo` auto-routes to the right domain from plain language. Plus 9 IDE adapters, crystallization-system renaming, post-run crystallization, 5,439 tests passing. Full list → [`CHANGELOG.md`](./CHANGELOG.md).
 
-Got usage questions, feature requests, or want to chat with the team and other peaks-loop users? Scan to join the **Peaks-Loop** WeChat group:
+</details>
 
-<div align="center">
-  <img src="./docs/images/wechat-group-qr.png" alt="Peaks-Loop WeChat group QR code" width="240" />
-</div>
+---
+
+## Links
 
-> When the QR code expires, feel free to open a GitHub Issue / Discussion instead.
+- All skills → [`skills/`](./skills/)
+- Changelog → [`CHANGELOG.md`](./CHANGELOG.md)
+- Questions → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- Tribute: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
+- Recommended combo: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) · [obra/superpowers](https://github.com/obra/superpowers)
+- Sediment design → [`docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`](./docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md)
+- Loop Engineering crystallization design → [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)
 
 ---
 
 <div align="center">
 
-**Find it useful?**
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · English · [简体中文](./README.md)
 
-⭐ [Star peaks-loop on GitHub](https://github.com/SquabbyZ/peaks-loop) · 🔍 [Browse on skills.sh](https://skills.sh/SquabbyZ/peaks-loop)
-
-</div>
+</div>