peaks-loop 4.0.0-beta → 4.0.0-beta.11

package/README-en.md

@@ -1,99 +1,227 @@
-# Peaks Loop
+<div align="center">
 
-**English** | [简体中文](./README.md)
+# peaks-loop
 
-[![npm](https://img.shields.io/npm/v/peaks-loop?style=flat-square&logo=npm)](https://www.npmjs.com/package/peaks-loop)
-[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
-[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+### You talk. It runs the entire engineering chain for you — beyond just code, twice-run flows sediment into local tactics.
+
+[![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)
+
+**English** · [简体中文](./README.md)
+
+</div>
 
 <p align="center">
-  <video src="./examples/video-demo/preview/peaks-loop-demo-en.mp4" controls muted playsinline preload="metadata" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);"></video>
+  <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>
 
+---
+
 ## What it is
 
-### Loop engineering, engineered
+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).
 
-### peaks-loop is your AI tactical squad — on call 24/7, summon them
+| 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 |
 
-It packs engineering gates, orchestration, replay into your local AI CLI. Install it, say one sentence, it runs the whole flow end-to-end and hands it back.
+- **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.
 
-Summon them, they handle the work. Stand them down when it's done. **No skipped steps. No half-finished hand-offs.** No new AI CLI to learn — it sits on top of Claude Code, Codex, or Copilot you already run.
+---
 
-**Every gate has a hard exit.** Audit fails = stop. QA fails = stop. Any gate fails = full stop. You don't chase it, you don't patch it. You decide, it runs the next gate.
+## Up and running in 30 seconds
 
-#### Gates aren't decoration — 5,439 tests passed · 19 skipped · 0 failed
+```bash
+npm i -g peaks-loop
+```
 
-Every line of code goes through our own gates. The test suite — 5,420 cases — actually blocks. Gates aren't written for users to admire; they're written for us to obey.
+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):
 
-#### One person built this, an engineer's taste:
+```
+/peaks-code walk me through this codebase
+```
 
-- **Geek ethos.**
-- **Natural language only — no CLI surface for the user.**
-- **Tests and gates that actually block, not decorate.**
-- **Strict with self, lenient with users — our own code goes through our own gates; users say whatever they want, the system catches it.**
-- **AI fluency floor is flat — no prompt-engineering chops, no CLI muscle memory; you talk like a person.**
+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.
 
-Those project-level red lines live in `~/.peaks/memory/`. They aren't slogans. They are red lines the toolchain enforces.
+Other slash commands you'll reach for:
 
-## What's in the box
+```
+/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
+```
 
-First tactician on the roster: `peaks-code`. The lead.
+<sub>📦 Adapters for other AI coding tools are coming — contributions welcome → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).</sub>
 
-It runs the long chain — PRD, RD, QA, UI, SC, TXT — and it's the role you'll talk to most.
+No CLI to memorize. No manifest to hand-author. No second terminal to open. **Send the slash, the rest is on it.**
 
-What it does:
-- Long-task development (end-to-end requirement → PRD → implementation → QA), gate by gate, stops where it breaks
-- Fix a bug and ship the same day — fix goes through review + tests, not just out the door
-- Take on, break down, or hand off a long-running requirement — from fuzzy ask to landed code
+---
 
-One sentence from you, and a long task is done. No second terminal needed.
-Coverage, audit, hard-stop — it treats every gate the same: under the bar = not delivered, off the rail = re-run.
+## What it does for you
 
-It's the entry the moment you install, and the dispatcher for every role that grows in later.
-Audit, QA gate, review sign-off — on by default. You only speak to turn one off.
+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".
 
-More loop-engineering roles coming.
+| 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 |
 
-## Sediment your own loop engineering
+Every lane opens with **one slash command**.
 
-When a flow has run twice, it can stay. One sentence and it's grounded into your box.
+---
 
-What you sediment is loop-engineering — a tactical play, not just a skill spell.
-Next time you say "run that", the whole playbook slots back in.
+## Why people pick it
 
-It lands in a pool on your machine, scoped to you alone.
-Name it, reuse it, iterate it — your call.
-A flow that ran clean twice gets promoted.
-A flow that broke gets sent back to you to redefine.
-When a decision touches your assets, you decide.
+- **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.**
 
-The point isn't how many bees the tool ships.
-The point is your few bees keep growing with your taste — you say one line, they grow one notch.
+---
 
-## Get it running
+## What gates ship by default
 
-```bash
-npm i -g peaks-loop
-```
+| 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 |
+
+**All gates on by default. You only speak to turn one off.**
 
-One sentence after install, and the squad is on the job.
+---
 
-## One more thing
+## Status · shipping 4.x
 
-This repo used to be [`peaks-cli`](https://github.com/SquabbyZ/peaks-cli). It's called `peaks-loop` now.
+| | |
+| --- | --- |
+| **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 |
 
-Inside the box, the skills evolved from `peaks-solo` (single-role) to `peaks-code` (gate-bearing, code-domain) — both still here, both with their own lane: `peaks-solo` is the older single-task flow entry, and `peaks-code` runs the end-to-end main path.
+---
+
+## Strongly recommended · compose these four
+
+> **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.
+
+<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 job didn't change: you say it, the engineering gates get laid out — fail where it fails, you decide.
+| 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 |
 
-Install this one repo and every new requirement after has a roster waiting for your call.
+**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.
+
+### Tribute
+
+peaks-loop's two engineering spines come straight from these projects:
+
+- [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.
+
+---
+
+## FAQ
+
+<details>
+<summary><b>How does it relate to Claude Code / Z Code?</b></summary>
+
+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).
+
+</details>
+
+<details>
+<summary><b>Do I need to learn CLI commands?</b></summary>
+
+No. You speak or pick; the LLM runs the commands. **All CLI verbs are hidden from you, open to the LLM.**
+
+</details>
+
+<details>
+<summary><b>Do sedimented tactics stay on my machine?</b></summary>
+
+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.
+
+</details>
+
+<details>
+<summary><b>Will it change my code without me knowing?</b></summary>
+
+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.
+
+</details>
+
+<details>
+<summary><b>What's new in 4.x vs 3.x?</b></summary>
+
+**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).
+
+</details>
 
 ---
 
-MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ)
+## Links
 
 - All skills → [`skills/`](./skills/)
-- Design docs → [`docs/`](./docs/)
 - Changelog → [`CHANGELOG.md`](./CHANGELOG.md)
-- Questions → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- 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">
+
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · English · [简体中文](./README.md)
+
+</div>

package/README.md

@@ -1,89 +1,227 @@
-# Peaks Loop
+<div align="center">
 
-[English](./README-en.md) | **简体中文**
+# peaks-loop
 
-[![npm](https://img.shields.io/npm/v/peaks-loop?style=flat-square&logo=npm)](https://www.npmjs.com/package/peaks-loop)
-[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
-[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+### 你说话,它替你跑完一整条工程流水线 —— 不止写代码,跑两次就沉淀成本地战术。
+
+[![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)
+
+[English](./README-en.md) · **简体中文**
+
+</div>
 
 <p align="center">
-  <video src="./examples/video-demo/preview/peaks-loop-demo.mp4" controls muted playsinline preload="metadata" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);"></video>
+  <img
+    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.gif"
+    alt="peaks-loop 30 秒演示(前 18 秒 · install + 斜杠命令 + 5 域 + 沉淀成 bee)"
+    width="92%"
+    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
+  />
+  <br>
+  <sub>👆 18s 循环 GIF(<a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">完整 30s mp4 下载</a> · 13MB · 480p)</sub>
 </p>
 
+---
+
 ## 它是什么
 
-### loop engineering 的工程实现
+peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —— 你跑过的工作里,沉淀下来的不是「流程」,是一套**可被 karpathy 风格工程化、又被 darwin 风格独立验证**的 Loop Engineering 方法资产。**Loop engineering 结晶系统** 的工程实现见 [`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)。
 
-### peaks-loop 就是你的 AI 战术小队,24 小时待命,随时接活
+| 资产层 | 角色 | 一句话 |
+| --- | --- | --- |
+| **Loop Engineering 资产** | 方法系统,一等公民 | 回答「为什么有这条 loop、何时触发、怎样算成功、如何改进」 |
+| **Bee 资产** | 可执行体,一等公民 | Loop Engineering 资产的可执行体,蜂群里的每只 bee |
+| **Workflow Trace (执行轨迹)** | 证据,**不是**主资产 | 不可变的单次执行记录,供结晶与评估反查,不是用户对外的产品 |
+| **Evolution Evaluation (反漂移)** | 反漂移闸门,强制项 | 每次改进都要有独立上下文的评估者 + 反方怀疑者,过了才留,不过就回滚 |
 
-它把一套工程门禁、编排、回放都装进你本地的 AI CLI 里,装好之后,你说一句话,它替你把整套流程跑完再交还给你。
+- **工程化每条规则 = karpathy 风格 · 验证每次改进 = darwin 风格** —— 两条缺一不可。砍掉 karpathy,原则没人写清;砍掉 darwin,改得对不对没人验。这一对是 co-equal 的双层结构,不是先后两步。
+- `/peaks-code` 是 **code-domain** 长任务 Loop Engineering 编排器,不是通用编排器;非代码域(`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`)都是独立的 `peaks-*` 蜂,不是 `peaks-code` 的子类。
+- 跑两次稳定就沉淀成本地战术(bee);跑翻车的会让你重定义。bee 跟着你的口味长。
 
-召之即来,事完收队,**不跳步,不半截扔给你**。它不是新发明一个 AI CLI,而是架在你已有的 Claude Code / Codex / Copilot 之上,把它们都调成同一支团队,只对你这一个开发者的口味。
+---
 
-**每一步都有强退出条件**:审计不通过就停,QA 没过就停,任何一道门失败 = 全流程停。你不必追着它催、也不必替它补,它跑完一道再交你拍板,拍完再走下一道。
+## 30 秒上手
 
-#### 门禁不是装饰 —— 5439 tests passed · 19 skipped · 0 failed
+```bash
+npm i -g peaks-loop
+```
 
-每一行代码都过自己的门:测试套件 5,420 个用例真挡得住事,不是装饰。门禁不是写给用户看的,是写给自己看的。
+装好之后,在你已经用的 **Claude Code** 或 **Z Code** 对话框里发一条**显式命令**(必须以斜杠开头,才会触发 peaks-loop):
 
-#### 做这个项目的只有一个人,工程师口味:
+```
+/peaks-code 帮我熟悉下当前的项目
+```
 
-- **极客精神。**
-- **你跟 AI 之间只该用自然语言讲话,没有 CLI 表面给你。**
-- **单测覆盖率和门禁审计真挡得住事,不是装饰。**
-- **严于律己,宽以待人 —— 自己写的代码过自己的门,使用者随便怎么说都能跑通。**
-- **AI 使用水平的下限平权:你不需要懂 prompt engineering,就跟说话一样用。**
+剩下的就交给 peaks-loop —— 它会按这条命令的语义判断该走哪一域,用对应的编排器拆工序,一道门一道门跑,**坏在哪道停在哪道**,中间不会扔半截给你。
 
-这套项目级硬规则也写进了 `~/.peaks/memory/`,不是口号,是被工具链守住的红线。
+其他常用的显式命令:
 
-## 装了你有什么战术角色
+```
+/peaks-content                 帮我把今天这篇推文写完发出
+/peaks-doctor                  帮我体检一下这个仓库
+/peaks-issue-fix-orchestrator  帮我把 upstream 的 30 个 open issue 修一批
+/peaks-sop                     帮我把团队的发布流程沉淀成 SOP
+/peaks-solo                    这套打法以后还会用,沉淀成本地战术
+/peaks-solo                    按上次那样再跑一次
+```
 
-先给你上的是 `peaks-code`,主官。它是 peaks-loop 默认入口,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。
+<sub>📦 其他 AI 编程工具适配中,欢迎共建 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues) 提适配请求 / PR。</sub>
 
-它能做的:
-- 写长任务代码(端到端需求 → PRD → 实现 → QA),一道门一道门跑,坏在哪道停在哪道
-- 修 bug 当天发,改完顺手过审 + 测试,不是改完就完
-- 帮你做 / 接 / 拆长跑的需求,把一个模糊需求一路剥到能落地的实现
+不需要记 CLI、不需要写 manifest、不需要切到第二个终端。**斜杠命令一发,后面的活它替你跑完。**
 
-它一句话能扛完的活,你都不必开第二个终端。它对测试覆盖率、审计门、卡点阻断一视同仁:跑不到位的活不交付,跑歪的活直接退回重跑。
+---
 
-它既是装好就立刻能用的那个入口,也是后面要长出来的内建角色的调度口;它内部有一套连续审计、QA 闸口、review 验收,默认打开,你想关哪一道才需要单独说。
+## 它能为你做什么
 
-其他内置 loop engineering,敬请期待。
+代码、内容、项目健康、issue 修复、自定义工作流 —— **4.x 已经覆盖五条域**,每条域都有专门编排器,按"门禁不通过就停"的纪律一条一条跑。
 
-## 你也能沉淀自己的 loop engineering
+| 域 | 你发这条命令 | 它会做什么 |
+| --- | --- | --- |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 帮我实现这个功能` | PRD → RD → 实现 → QA → UI → 切片,跑完交你拍板 |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 这个 bug 帮我修一下` | 复现 → 改 → review → 测试,同日 ship |
+| 📝 **内容** | `/peaks-content 帮我把这篇推文写出来再发` | 草稿 → 编辑 → 调性检查 → 发布 → 归档,中间不跳步 |
+| 🩺 **项目健康** | `/peaks-doctor 帮我体检一下这个仓库` | 红线审计 + L3 doctor 检查 + 转 OpenSpec,坏在哪道停在哪道 |
+| 🐛 **批量修 issue** | `/peaks-issue-fix-orchestrator 帮我把 upstream 的 30 个 open issue 修一批` | 调研 → 分类 → 参考 PR → 逐个修复 + commit + PR 草稿 |
+| 📋 **自定义工作流** | `/peaks-sop 帮我把团队的发布流程沉淀成 SOP` | 自然语言描述 → 自动生成 + 校验 + 注册成可执行的 SOP |
+| 🔁 **跑过一次再来** | `/peaks-solo 按上次那样再跑一次` | 调出你已经沉淀好的战术,自动复跑 |
+| 🆕 **接手陌生仓库** | `/peaks-code 这是新仓库,先带我过一遍` | 摸清结构、识别风险点、给一个上手顺序 |
+| 🧠 **沉淀自己的打法** | `/peaks-solo 这套打法以后还会用,沉淀一下` | 变成你本地常驻的战术,下次说"跑那只"就行 |
 
-跑过一次还想跑,说一句话让它永久驻场。
+每一条路,**一条斜杠命令**就能开跑。
 
-你沉淀的是 loop engineering(战术套路),不是简单的 skill(动作招式)。下次说"跑那只",整套流程自动就位。
+---
 
-它落到你本地的一个池子里,只对你生效。命名、复用、迭代都是你说了算:跑过两遍稳定的会被抬高,跑翻车的会让你重新定。决策影响资产的,你拍板。
+## 为什么大家会选它
 
-这套机制关键不是"工具给你造了多少只 bee",而是你那几只 bee 一直在跟着你的口味长 —— 你提一句,它长一点。
+- **自然语言即界面** —— 你不学 CLI、不背命令。**用一条斜杠命令(比如 `/peaks-code xxx`)** 显式触发到对应编排器,后面说什么都行。LLM 替你跟 peaks-loop 跑命令。
+- **门禁真挡事,不是装饰** —— 5,439 个测试用例、QA 闸口、review 验收默认全开。**审计不通过就停,QA 没过就停**。
+- **跑过的事会变成本地战术(bee)** —— 沉淀下来的 loop engineering 落到你本地的 `~/.peaks/` 池子里,跑两次稳定就自动晋升;跑翻车的会让你重新定义。**下次说"跑那只"整套流程自动就位**,你那几只战术会跟着你的口味长。
+- **搭在你已经用的工具上** —— 不是新发明一个 AI CLI,而是架在 **Claude Code** 和 **Z Code** 之上。不抢你的 shell、不抢你的 prompt、不抢你的 IDE。其他工具适配中,欢迎共建。
+- **你拍板,它执行** —— 影响资产的决策都给你选;其余的它自己跑。**0 学习成本,1 分钟上手。**
 
-## 上号
+---
 
-```bash
-npm i -g peaks-loop
-```
+## 装上以后的几道闸门
+
+| 闸门 | 默认状态 | 用来挡什么 |
+| --- | --- | --- |
+| 单元测试 / 集成测试 | ✅ 开 | 代码层面的回归 |
+| 代码审计 (lint / prose / type) | ✅ 开 | 写法与意图漂移 |
+| 安全扫描 | ✅ 开 | 凭据、SSRF、注入、危险 IO |
+| QA 复核 | ✅ 开 | 任务级闸门,坏在哪道停在哪道 |
+| review 验收 | ✅ 开 | 改完不立刻出门,review 通过才出门 |
+
+**所有闸门默认开,你想关哪一道才需要单独说。**
+
+---
+
+## 当前状态 · 4.x 正式版
+
+| | |
+| --- | --- |
+| **最新版本** | [`4.0.0-beta.7`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x 正式版筹备中 |
+| **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测) |
+| **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
+| **测试套件** | 5,439 passed · 19 skipped · 0 failed |
+| **适配 IDE** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder(适配中,欢迎共建) |
+| **依赖运行时** | Node ≥ 20 |
+| **License** | MIT |
+
+---
 
-装完一句话接活。
+## 强烈推荐 · 四个项目组合起来用
 
-## 顺便说一句
+> **0 学习成本。** 这是组合起来用最大的好处 —— 不只是效果俱佳,更是因为这四个项目的**接口对齐到了"自然语言"**,你只需要说一句话,谁替你跑命令、按什么闸门、按什么战术手册,完全不用你记。
 
-这个仓库以前叫 [`peaks-cli`](https://github.com/SquabbyZ/peaks-cli),现在叫 `peaks-loop`。
+<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>
+
+| 角色 | 项目 | 一句话 |
+| --- | --- | --- |
+| **结晶与门禁** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← 你在这里 | loop engineering 结晶系统,装上就有 PRD/RD/QA/UI/SC/TXT 一整条工程链 + 沉淀 |
+| **战术手册** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | everything-claude-code:Claude Code 上能拿到的最好用的战术、技能、SOP 集合 |
+| **代码理解** | [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) | 任意仓库,一句话读懂 —— 让 LLM 真正"理解"项目,而不是猜 |
+| **流程与纪律** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review 等流程纪律,每条都自带硬退出条件 |
+
+**用起来就一句话**:把上面三个仓库都 clone 到本地,peaks-loop 装上,剩下的交给 LLM —— 它会按需取用、按纪律守门、按战术落地、按需求沉淀。
 
-里面的技能从 `peaks-solo`(单角色)演化到 `peaks-code`(带门禁的代码域).两边都还在,只是分工不同:`peaks-solo` 如今是给单任务跑流程用的那个老入口,`peaks-code` 接管了端到端的主路径。
+### 致敬
 
-事情一直没换过:你说话,它替你排工程门禁,坏哪道停哪道,你来拍板。
+peaks-loop 的两条工程脊柱直接来自这两个项目:
 
-你只需要把这一个仓库装好,后面每次跑新需求,都有现成的战术角色等你点。
+- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — 把"工程化每一条规则"刻进我们的方法层。
+- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — 把"演化校验每一次改进"刻进我们的反漂移闸门。
 
 ---
 
-MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ)
+## FAQ
+
+<details>
+<summary><b>它跟 Claude Code / Z Code 是什么关系?</b></summary>
+
+它是**搭在上面**,不是替换。peaks-loop 不抢你的 shell、不抢你的 prompt、不抢你的 IDE。它在 Claude Code / Z Code 这两个一等公民适配里跑,你照常用。**其他 AI 编程工具适配中,欢迎共建** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)。
+
+</details>
+
+<details>
+<summary><b>我需要记 CLI 命令吗?</b></summary>
+
+不需要。你只用自然语言或选选项,LLM 替你跑命令。**所有 CLI 命令对外隐藏,对 LLM 开放**。
+
+</details>
+
+<details>
+<summary><b>沉淀下来的战术会一直留在本地吗?</b></summary>
+
+会。沉淀落在你本地的池子里,只对你生效。命名、复用、迭代都是你说了算;跑翻车的会让你重新定义。
+
+</details>
+
+<details>
+<summary><b>它会自己改我的代码吗?</b></summary>
+
+改,但过门禁。**审计不通过 = 不出门**,**QA 没过 = 不出门**,**review 不通过 = 不出门**。它替你跑,但每道门都给你审。
+
+</details>
+
+<details>
+<summary><b>跟 3.x 比,4.x 有什么不同?</b></summary>
+
+**最大的不同:从"代码专用"扩成"多域编排系统"。** 4.x 不再只是写代码 —— 新增了 `peaks-content`(内容生产)、`peaks-doctor`(项目健康)、`peaks-issue-fix-orchestrator`(批量修 issue)、`peaks-sop`(自定义 SOP)四条域编排链,加上 `peaks-solo` 分诊员按你说话自动判断该走哪一域。再加 9 个 IDE 适配、结晶系统重命名、post-run crystallization 机制、5,439 tests 通过。完整变更 → [`CHANGELOG.md`](./CHANGELOG.md)。
+
+</details>
+
+---
+
+## 链接
 
 - 全部技能清单 → [`skills/`](./skills/)
-- 设计文档 → [`docs/`](./docs/)
 - 更新日志 → [`CHANGELOG.md`](./CHANGELOG.md)
 - 提问 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- 致敬: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
+- 组合推荐: [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)
+- 沉淀设计 → [`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 结晶设计 → [`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">
+
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · 中文版 · [English version](./README-en.md)
+
+</div>

package/bin/peaks.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import '../dist/src/cli/index.js';
+import '../dist/cli/index.js';

package/dist/cli/cli-helpers.d.ts

@@ -0,0 +1,38 @@
+import { Command } from 'commander';
+import { getErrorMessage, ok, redactSensitiveErrorMessage, type ResultEnvelope } from '../shared/result.js';
+import type { ArtifactProvider, GuidedArtifactSetup } from '../services/artifacts/artifact-service.js';
+import type { ConfigLayer } from '../services/config/config-service.js';
+import type { RecommendationWorkflow } from '../services/recommendations/recommendation-service.js';
+export type ProgramIO = {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+};
+export declare function printResult<T>(io: ProgramIO, result: ResultEnvelope<T>, asJson?: boolean): void;
+export declare function addJsonOption(command: Command): Command;
+export declare function failUnsupportedNonDryRun(io: ProgramIO, command: string, asJson?: boolean): void;
+/** CLI shim helper: render a `{ ok: boolean, error?, data? }` envelope
+ *  and set `process.exitCode = 1` on failure.
+ *
+ *  Library functions MUST return envelopes like `{ ok, error?, data? }`
+ *  and MUST NOT mutate `process.exitCode` themselves. The shim (the
+ *  Commander `.action()` callback in `register*Commands`) owns the
+ *  process-exit side-effect so the library can be re-used from non-CLI
+ *  contexts (vitest, programmatic dispatch, plugin loading).
+ *
+ *  Output format mirrors the existing `registerSedimentCommands` shim:
+ *  a JSON envelope on stdout (one line, parseable), nothing else.
+ */
+export interface CliEnvelope {
+    ok: boolean;
+    error?: string;
+    data?: unknown;
+}
+export declare function printCliEnvelope(io: ProgramIO, r: CliEnvelope): void;
+export declare function isRecommendationWorkflow(value: string): value is RecommendationWorkflow;
+export declare function isArtifactProvider(value: string): value is ArtifactProvider;
+export declare function isArtifactSetupStep(value: string): value is GuidedArtifactSetup['step'];
+export declare function isArtifactRepoSegment(value: string): boolean;
+export declare function parseConfigLayer(value: string | undefined): ConfigLayer | undefined | null;
+export declare function printInvalidConfigLayer(io: ProgramIO, command: string, asJson?: boolean): void;
+export declare function multipleOption(value: string, previous: string[]): string[];
+export { getErrorMessage, ok, redactSensitiveErrorMessage };