peaks-cli 1.4.2 → 2.0.0

package/README.md

@@ -1,35 +1,60 @@
-# Peaks
+<div align="center">
+
+# ⛰️ Peaks
+
+**让 AI IDE 像一支训练有素的工程团队一样工作**
 
 [English](./README-en.md) | **简体中文**
 
 [![npm version](https://img.shields.io/npm/v/peaks-cli.svg)](https://www.npmjs.com/package/peaks-cli)
+[![GitHub stars](https://img.shields.io/github/stars/SquabbyZ/peaks-cli?style=social)](https://github.com/SquabbyZ/peaks-cli/stargazers)
 [![GitHub repo](https://img.shields.io/badge/GitHub-SquabbyZ%2Fpeaks--cli-181717?logo=github)](https://github.com/SquabbyZ/peaks-cli)
+[![Skills.sh](https://img.shields.io/badge/discover%20on-skills.sh-181717)](https://skills.sh/SquabbyZ/peaks-cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**一个 CLI + 11 个工作流技能，把 LLM 的随意发挥变成可审计的工程流程。**
+
+[安装](#-30-秒跑起来) · [5 分钟上手](#-5-分钟上手) · [技能家族](#-11-个技能家族) · [杀手锏：不可绕过的门禁](#-杀手锏不可绕过的门禁)
+
+</div>
+
+---
+
+## 🤔 为什么是 Peaks
 
-Peaks 是一个**跨 AI IDE 的工作流门禁 CLI + 技能家族**——把项目治理、工作流规划、受控执行、QA 验证、变更追踪组织成可复用的工程流程。CLI 是跨 IDE 稳定的核心（门禁 + JSON 契约 + 不可逆动作），技能 / 钩子 / 配置按各 IDE 的原生格式承载。
+> 你把 `git push --force`、`rm -rf`、`npm publish`、`DROP TABLE` 这类不可逆动作**写进 CLAUDE.md** 吗？
+> LLM 不会真听。它有 99% 的概率会"尊重你的偏好"，然后在下一次对话里忘掉。
+> **CI 只能在合并时拦；规则只能靠自觉；只有门禁（gates）能在 agent 拔刀的瞬间摁住它。**
 
-> **支持的 IDE**：
-> - ✅ **Claude Code**（shipped, 当前主用）：11 个 `peaks-*` 技能 + `.claude/settings.json` PreToolUse hook；agent team 在本 IDE 已 dogfood
-> - ⚠️ **Trae**（adapter shipped, real-Trae unverified）：slim `IdeAdapter` 已注册到 slice #1 registry（`hookEvent` / `toolMatcher` / `envVar` 是 1.x 假设，**未在真实 Trae 上验证**）；真实 Trae 集成 dogfood 留到后续切片
-> - 📋 **Codex / Cursor / Qoder / 通义灵码 等**（路线图）
+Peaks 把 AI IDE 里的"工程团队"建模成 11 个工作流技能 + 一组**可执行的门禁**：
 
-> **产品定位**：你**用技能工作**，CLI 是跨 IDE 的质量保障层。
->
-> 我们的目标：让 LLM 在每个环节里自由判断与决策；peaks 在流程边界上提供可审计的 SOP 护栏，把项目级记忆和使用经验沉淀下来——AI IDE 和 LLM 在你的项目上用得越久就越懂它。
+- 🧭 **技能（skills）**——`peaks-solo` 编排，`peaks-prd/rd/qa/ui/sc/txt/sop` 各管一段；LLM 按任务自动选对的人
+- 🚧 **门禁（gates）**——SOP 在每个 phase 上挂"可检查条件"（文件存在 / grep 命中 / 命令退出码），不满足就把 `git push` 在 agent 自己面前拦下——**连 `--dangerously-skip-permissions` 都绕不过**
+- 🧠 **项目记忆（memory）**——`.peaks/memory/` 把决策、踩坑、约定落盘到 git 一起被 commit；下个 session 接手不用问"为什么这么写"
+- 🌐 **跨 IDE**——一个 CLI 适配 Claude Code / Trae / Cursor / Codex / Qoder；技能注册到 IDE 原生格式
+- 📦 **生态可发现**——11 个技能同样发布到 [skills.sh](https://skills.sh)，按需 `npx skills add` 单点装
 
-## 安装
+## 🚀 30 秒跑起来
 
 ```bash
+# 1. 装 CLI
 npm install -g peaks-cli
+
+# 2. 在你的项目里打开 Claude Code
+cd /path/to/your-project && claude
+
+# 3. 让 AI 干活
+> peaks-solo 帮我给登录页加 OAuth 回调
 ```
 
-安装后，Peaks 会把内置的 11 个 `peaks-*` 技能注册到已适配的 AI IDE（当前：Claude Code），会话里直接通过技能名调用即可。
+完了。第一次跑 peaks 会自动建 `.peaks/` 工作区 + 扫一次项目原型 + 把任务分给对的技能（PRD → 工程切片 → UI → QA → 变更控制 → 知识压缩），中间产物全部落盘。**日常使用 1 个技能（`peaks-solo`）覆盖 ≥ 90% 的需求**。
 
-## 5 分钟上手
+## ⏱️ 5 分钟上手
 
-在已适配的 AI IDE 对话里，**直接对 AI 说「用 X 技能做 Y」** 即可，技能会接管剩下的所有流程：
+在 IDE 对话里直接对 AI 说：
 
 ```text
-peaks-solo 帮我给登录页加 OAuth 回调      # 第一次显性用 peaks-solo；项目根 = IDE 当前 cwd
+peaks-solo 帮我给登录页加 OAuth 回调      # 端到端编排（最常用）
 peaks-prd  为会员邀请功能整理产品目标、非目标和验收标准
 peaks-rd   分析这次重构的最小实现切片和风险
 peaks-qa   为这次改动设计测试和回归验证清单
@@ -39,158 +64,163 @@ peaks-txt  为当前模块生成上下文胶囊，保留关键决策
 peaks-sop  帮我把"内容发布"流程变成带门禁的 SOP
 ```
 
-第一次使用？分两层：**你做 2 步，peaks 接管剩下**。
+**两种基本用法**：
+
+1. **让 `peaks-solo` 编排**（绝大多数情况）——告诉它做什么，剩下 PRD → RD → UI → QA → SC → TXT 的链路它自己协调
+2. **直接调单个角色技能**（进阶）——只想做工作流的某一段时，跳过整 pipeline
+
+随时确认状态？让 AI 跑一下：
+
+```bash
+peaks -V                       # 版本
+peaks doctor --json            # 环境/技能/配置一键体检
+peaks project dashboard --project . --json   # 当前项目一眼看完
+```
+
+## 🧰 11 个技能家族
 
-**你需要做的（2 步）**：
+| 技能 | 你用它做什么 | 典型场景 |
+|------|------------|----------|
+| `peaks-solo` | **端到端编排入口**，自动协调 prd/rd/ui/qa/sc/txt | 全流程开发、PRD-to-ship、跨子任务批量迭代 |
+| `peaks-prd` | 模糊意图 → **可验收 PRD**（目标/非目标/行为保留/验收） | 需求整理、PRD 撰写、重构目标 |
+| `peaks-rd` | 工程分析 + 切片规划 + 风险 + 执行契约 | 架构分析、最小切片、风险评估 |
+| `peaks-qa` | 测试设计 + 覆盖率 + 回归矩阵 + 验收证据 | 测试用例、回归、浏览器 E2E |
+| `peaks-ui` | 视觉方向 + 交互方案 + 设计系统约束 | 页面设计、交互、原型、UI 回归 |
+| `peaks-sc` | 变更追踪 + commit 边界 + 留存策略 + 回滚证据 | 影响范围、变更控制、审计 |
+| `peaks-txt` | 上下文胶囊 + 决策记录 + 知识压缩 | 模块理解、决策留存、复盘 |
+| `peaks-sop` | **把你的工作流变成带门禁的 SOP**（不只研发） | 内容发布、合规清单、数据 pipeline、运维 runbook |
+| `peaks-solo-resume` | 继续刚才没做完的切片 | 「继续完成刚才未完成的」 |
+| `peaks-solo-status` | 一眼看到现在到哪了 | 「现在到哪了」 |
+| `peaks-solo-test` | 跑项目测试（自动探测 vitest/jest/pytest/...） | 「跑测试」 |
 
-1. 在项目目录里打开已适配的 AI IDE：`cd /path/to/your-project && <你的 IDE 命令，如 claude>`——让 IDE 知道项目根在哪
-2. 在 IDE 里对 AI 说：**`peaks-solo 帮我做 X`**（X = 需求描述，如"给登录页加 OAuth 回调"）
-   - LLM 会按任务和项目推荐模式；想直接定可以写 `peaks-solo 全自动做 X` / `peaks-solo swarm X` / `peaks-solo strict X`
+**3 solo 包装 + 7 角色技能 + 1 编排器 = 11 个。日常 1 个 `peaks-solo` 覆盖 ≥ 90%。**
 
-**之后 peaks 会自动**：
+## 🚧 杀手锏：不可绕过的门禁
 
-- 跑 `peaks workspace init`（首次会创建 `.peaks/`）→ `peaks scan archetype` → 生成 `.peaks/<session-id>/rd/project-scan.md`
-- 复杂任务按 PRD → RD → UI → QA → SC → TXT 协调；简单任务直接走 solo 全自动，无需分阶段
-- 工作流进行中可用 `peaks-solo-status` 看看当前到哪了；中断后用 `peaks-solo-resume` 继续
-- 工作流结束时把所有中间产物留在 `.peaks/<session-id>/`，并把"该记住的事实"写进 `.peaks/memory/`
+> CI 只能在**合并时**拦；`CLAUDE.md` 规则靠 agent **自觉**。**SOP 能做到 CI 和提示词都做不到的事——在 agent 拔刀的瞬间把它摁住。**
 
-想要随时确认状态？让 AI 跑一下：
+```jsonc
+// sop.json
+"guards": [ { "phase": "publish", "bash": "git +push" } ]
+```
 
 ```bash
-peaks -V                # 版本号
-peaks                   # 当前 quickstart + 已安装技能数
-peaks doctor --json     # 环境/技能/配置一键体检
-peaks skill doctor --json
-peaks project dashboard --project . --json   # 当前项目 dashboard
+peaks hooks install --project <repo>   # 显式 opt-in：装一条 PreToolUse 规则
 ```
 
-## 技能家族速查
+之后 agent 在 `publish` 阶段的门禁没全过就想 `git push`，Claude Code 会收到 `permissionDecision: "deny"`，**在任何权限检查之前就被拦下——连 `--dangerously-skip-permissions` 都绕不过**。门禁三种类型：
 
-| 技能 | 你用它做什么 | 典型场景 |
-|------|------|----------|
-| `peaks-solo` | **端到端编排入口**。从需求到上线的全流程，自动协调 `prd/rd/ui/qa/sc/txt` | 全流程开发、从产品文档/PRD 开始到上线、跨多个子任务的批量迭代 |
-| `peaks-prd` | 把模糊的产品意图变成**可验收的 PRD**：目标、非目标、行为保留、验收标准 | 需求整理、PRD 撰写、重构目标定义 |
-| `peaks-rd` | 工程分析 + 重构规划 + 执行契约（覆盖门、规格、风险） | 工程分析、最小实现切片、风险评估、重构规划 |
-| `peaks-ui` | UI/UX 交互和视觉约束、视觉方向、设计系统约束 | 页面设计、交互方案、原型、UI 回归 |
-| `peaks-qa` | 测试设计 + 覆盖率 + 回归验证 + 验收证据 | 测试用例、回归矩阵、验收检查、浏览器 E2E |
-| `peaks-sc` | 变更追踪、commit 边界、artifact 留存、回滚证据 | 影响范围记录、回滚证据、变更控制 |
-| `peaks-txt` | 上下文胶囊、决策记录、知识压缩 | 模块理解、关键决策留存、复盘 |
-| `peaks-sop` | **把你的工作流变成带门禁的 SOP**（不是研发专属） | 内容发布、合规清单、数据 pipeline、运维 runbook、个人流程 |
-| `peaks-solo-resume` | **继续刚才没做完的切片**——一键检测 in-flight slice 的最深已完成 gate，省 3-5k token | 「继续完成刚才为完成的」「resume the unfinished slice」 |
-| `peaks-solo-status` | **看一眼现在到哪了**——5-CLI snapshot 表格（presence + session + dashboard + request + memory） | 「现在到哪了」「show me the dashboard」 |
-| `peaks-solo-test` | **跑项目测试**——从 `package.json` 探测测试工具（vitest / jest / mocha / pytest / ...），用项目原生命令跑并汇总 pass/fail | 「跑测试」「run the tests」 |
+| 类型 | 含义 | 例子 |
+|------|------|------|
+| `file-exists` | 文件存在 → pass | `CHANGELOG.md` 存在 |
+| `grep`（含 `absent`） | 文件内正则匹配 → pass；`absent: true` 反转 | "正文里没有 `TODO`" |
+| `command` | 跑命令并按退出码判定（默认拒绝，需 `--allow-commands`） | 跑 `npm test` |
 
-### 两种基本用法
+定义层（`sop.json` + `SKILL.md`）可以放**全局** `~/.peaks/sops/`（个人跨项目）或**仓库** `<repo>/.peaks/sops/`（随 git 提交、团队共享，仓库层优先）。**紧急放行**用 `peaks gate bypass --sop <id> --phase <phase> --reason "<原因>"`（一次性、记原因、有上限）。
 
-**1. 让 `peaks-solo` 编排（最常用）**
+## 🌍 真实场景
 
-`peaks-solo` 是产品入口，**绝大多数场景都用它**——告诉它做什么，剩下 PRD / UI / RD / QA / SC / TXT 的链路它自己协调。**默认模式不写死**：LLM 根据任务复杂度和项目状态主动推荐 assisted / full-auto / swarm / strict 中的一种；想自己指定时再显式标注：
+**场景 1：临时决定重构鉴权模块**
 
 ```text
-peaks-solo 帮我做 X              # 默认（不写死，LLM 按任务和项目推荐）；X = 需求描述；项目路径走 IDE 当前 cwd
-peaks-solo 全自动做 X            # 显式 full-auto：端到端跑完
-peaks-solo swarm 模式做 X        # 显式 swarm：最大化子代理并行（适合大任务）
-peaks-solo strict 模式做 X       # 显式 strict：最严格门禁
+> peaks-rd 分析 src/auth/ 的现状，给我一份最小切片方案
 ```
+`peaks-rd` 出：3 阶段切片、风险评估、回归点、可执行契约。**写不写代码你定**。
 
-3 个 `peaks-solo-*` 包装技能是 solo 的轻量变体（不算单独角色）：
+**场景 2：把"内容发布"变成受控流程**
 
-- `peaks-solo-resume` —— 继续刚才没做完的切片
-- `peaks-solo-status` —— 看看现在到哪了
-- `peaks-solo-test` —— 跑项目测试
+```text
+> peaks-sop 帮我把"博客发布"做成带门禁的 SOP：草稿写完 → 自检（无 TODO/字数 ≥ 800） → 人工 review → 才允许发布
+```
+`peaks-sop` 生成 `sop.json` + `SKILL.md`，注册到全局，**从此 agent 跳过任何一步都发不出文章**。
 
-**2. 直接调用单个角色技能（进阶）**
+**场景 3：浏览器 E2E 回归**
 
-只有当你只想做工作流的**一个阶段**（比如只写 PRD、只做架构分析、只跑回归），不想走 full pipeline 时，才单独调这些：
+```text
+> peaks-qa 用浏览器跑一次完整注册 → 登录 → 看板的核心流，把卡点列出来
+```
+`peaks-qa` 出：测试矩阵、回归清单、`code-review.md` 风格的证据文档。
 
-| 技能 | 你用它做什么 | 什么时候才需要 |
-|---|---|---|
-| `peaks-prd` | 写 / 改 PRD（目标、非目标、行为保留、验收标准） | 想自己定义需求，不走 solo 整流程 |
-| `peaks-rd` | 架构分析 + 最小切片规划 + 风险 | 只想拿一份技术分析，不要写代码 |
-| `peaks-qa` | 测试用例 + 回归矩阵 + 验收证据 | 只想补测试，不走完整 solo |
-| `peaks-ui` | 视觉方向 + 交互方案 + 设计系统约束 | 只做 UI 设计，不带实现 |
-| `peaks-sc` | 影响范围 + commit 边界 + 留存策略 | 只想记录变更，不触发整流程 |
-| `peaks-txt` | 上下文胶囊 + 决策记录 | 只想压缩知识，不走整流程 |
-| `peaks-sop` | 把任意工作流（不只是开发）变成带门禁的 SOP | 想定义 / 注册自己的 SOP |
+**场景 4：第二天回来继续昨天的切片**
 
-**3 个 solo 包装 + 7 个角色技能 + 1 个 solo 编排 = 11 个技能家族。** 日常使用中，1 个（`peaks-solo`）覆盖 ≥90% 的需求。
+```text
+> peaks-solo-resume
+```
+检测 in-flight slice 的最深已完成 gate，省 3-5k token 重新读 artifact。**会话断了不丢上下文**。
 
-## Agent team
+## 📦 在 skills.sh 上发现 peaks 技能
 
-`peaks` 帮你调度一个 agent team——`peaks-solo` / `peaks-rd` / `peaks-qa` / `peaks-ui` 把 peer sub-agent 派到隔离沙箱里写 PRD / 做架构分析 / 跑测试 / 设计 UI，主 LLM 只看每个 sub-agent 的元数据（路径 + 大小 + 摘要）。
+peaks 的 11 个 `peaks-*` 技能自动收录到 [skills.sh](https://skills.sh) 注册表——**不需要单独去 skills.sh 网站注册**。收录靠仓库里**自带配置**：
 
-## 怎么用：技能优先，CLI 是门禁
+- 11 个 `skills/<name>/SKILL.md`（每个都有 `name` + `description` YAML frontmatter）—— skills.sh 的标准发现约定
+- `.claude-plugin/marketplace.json` —— 显式列出 11 个公开技能（隐藏的内部 `peaks-doctor` / `peaks-ide` 通过 `metadata.internal: true` 屏蔽）
 
-Peaks 里的 `peaks <cmd>` CLI **不是日常使用的主要入口**。它的存在有三个理由，全都是机器层保障：
+任何装了 `npx skills` 的环境（Claude Code、Cursor、Codex 等）都能直接拉取：
 
-1. **不可逆动作的显式 opt-in**（例如 `peaks sop init --apply`、`peaks openspec archive --apply`）—— 这一刀不能靠 LLM"自觉"挥下。
-2. **结构化 JSON 契约**（`peaks request show ... --json`、`peaks scan archetype ... --json`）—— 让技能读回一个可机读的判决，作为下游决策的输入。
-3. **hook / CI / 脚本场景下能被程序化调用**（`peaks hooks install`、`peaks gate enforce`）—— 这层机器保障在对话里你看不到，但它把"必须满足门禁才能做 X"这件事从纸面规则变成可执行规则。
+```bash
+# 装全部 11 个：
+npx skills add SquabbyZ/peaks-cli
 
-技能和 CLI 的关系可以记成一句话：**技能 = 流程的大脑**；**CLI = 流程的骨节**。
+# 或只装一个：
+npx skills add SquabbyZ/peaks-cli --skill peaks-solo
+npx skills add SquabbyZ/peaks-cli --skill peaks-rd
+npx skills add SquabbyZ/peaks-cli --skill peaks-sop
+```
 
-### 你**会**用到的几条 CLI 命令
+浏览 [skills.sh/SquabbyZ/peaks-cli](https://skills.sh/SquabbyZ/peaks-cli) 看完整目录。技能和 `npm install -g peaks-cli` 是同一份内容——两条路径产物一致。
 
-虽然主要工作在技能里完成，但这些 CLI 命令在技能驱动下你也会经常看到被调用，概念上知道有它们就够了：
+## 🛠️ 怎么用：技能优先，CLI 是门禁
 
-```bash
-peaks workspace init --project <repo> --json       # 创建 .peaks/ 工作区（每个 session 一次）
-peaks workspace reconcile --project <repo> --json  # 4-tier heuristic 重新指向 canonical session，干掉孤儿 dir（默认 dry-run，--apply 才删）
-peaks scan archetype --project <repo> --json       # 探测项目原型（greenfield/legacy-frontend/...）
-peaks scan libraries --project <repo> --json       # 枚举依赖 + 解析 major，支持 monorepo
-peaks request init/show/transition                 # PRD/RD/QA/SC 的请求状态机
-peaks session list/info/title/rotate               # session 元数据；rotate 丢弃绑定让下次 peaks 自动重生成
-peaks sop init/lint/check/advance/register         # 你的自定义 SOP 生命周期
-peaks hooks install --project <repo>               # 装门禁的 PreToolUse hook
-peaks project dashboard --project <repo> --json    # 整个项目一眼看完
-peaks project memories --project <repo> --json     # 读取 .peaks/memory/ 里的历史决策
-```
+`peaks <cmd>` CLI **不是日常使用的主要入口**。它存在有三个理由，全是机器层保障：
 
-完整命令列表跑 `peaks --help` 即可。
+1. **不可逆动作的显式 opt-in**（`peaks sop init --apply`、`peaks openspec archive --apply`）—— 不能靠 LLM"自觉"挥下
+2. **结构化 JSON 契约**（`peaks request show ... --json`、`peaks scan archetype ... --json`）—— 让技能读回可机读判决作为下游决策
+3. **hook / CI / 脚本场景下能被程序化调用**（`peaks hooks install`、`peaks gate enforce`）—— 把"必须满足门禁才能做 X"从纸面规则变成可执行规则
 
-## 自定义 SOP（把你的流程变成带门禁的工作流）
+一句话：**技能 = 流程的大脑；CLI = 流程的骨节**。
 
-> **技能入口**：`peaks-sop` 技能
-> 告诉 Claude "帮我把『内容发布』做成一个 SOP"，它会引导你定义阶段、设定门禁、调试、注册，全程不用手写 JSON。
+### 你**会**看到的 CLI 命令
 
-内置的 `peaks-*` 技能家族解决"开箱即用"的需求。但很多工作流是**领域特定的、有先后阶段、进入下一步前必须满足某些可检查条件**的——这种流程用 SOP（Standard Operating Procedure）来表达。
+```bash
+peaks workspace init / reconcile / scan archetype / scan libraries
+peaks request init / show / transition          # PRD/RD/QA/SC 请求状态机
+peaks session list / info / title / rotate
+peaks sop init / lint / check / advance / register
+peaks code-review detect-ocr / config-template / run-ocr   # 阿里 Open Code Review 第二意见
+peaks hooks install / gate enforce / gate bypass
+peaks project dashboard / memories
+```
 
-`peaks-sop` 技能可以把任何这样的流程变成**带门禁的工作流**：
+完整列表跑 `peaks --help`。
 
-| 领域 | 阶段举例 | 门禁思路 |
-|------|---------|---------|
-| 内容 / 发布 | draft → edit → publish | `file-exists` 草稿；`grep` 没有 `TODO`/`TKTK`；`command` 跑字数/拼写检查 |
-| 合规 / 审批 | prepare → review → sign-off | `file-exists` `approval.md`；`grep` 包含 "Approved" |
-| 数据 pipeline | raw → cleaned → validated | `command` 跑校验脚本，退出码 0 |
-| 运维 / 入职 | request → provision → done | `file-exists` 每个清单产物；`command` 校验配置 |
-| 研发发布（典型但非唯一） | draft → review → ship | `file-exists` CHANGELOG；`grep` 源码里没有 `FIXME`；`command` 跑测试 |
-| 个人流程 | 任何"不要忘步骤 X"的流程 | 把"判断"重新物化成一个文件/文本/退出码 |
+## 🌐 支持的 IDE
 
-### 门禁类型
+| IDE | 状态 |
+|---|---|
+| ✅ **Claude Code** | 11 技能 + PreToolUse hook，agent team dogfood 通过 |
+| ⚠️ **Trae** | slim `IdeAdapter` 已注册，真实 Trae 集成留到后续切片 |
+| 📋 **Codex / Cursor / Qoder / 通义灵码 等** | 路线图 |
 
-| 类型 | 含义 | 例子 |
-|------|------|------|
-| `file-exists` | 文件存在 → pass | `CHANGELOG.md` 存在 |
-| `grep`（含 `absent`） | 文件内正则匹配 → pass；加 `absent: true` 反转（"不准有 X"） | "正文里没有 `TODO`" |
-| `command` | 跑命令并按退出码判定（默认拒绝，需 `--allow-commands`） | 跑 `npm test` |
+## 🏗️ 项目状态
 
-### 杀手锏：不可绕过的门禁
+- ✅ **11 技能** + 跨 IDE CLI + 2800+ 测试
+- ✅ **门禁机制** 已在真实项目 dogfood
+- 📋 路线图：Trae / Codex / Cursor 真实集成、`peaks-doc` / `peaks-i18n`、SOP 模板市场
 
-CI 只能在**合并时**拦，`CLAUDE.md` 里的规则靠 agent **自觉**。SOP 能做到 CI 和提示词都做不到的事：**在对话中途、面向 agent 本身**把不可逆动作摁住。
+详细看 [`CHANGELOG.md`](./CHANGELOG.md) 和 [`docs/`](./docs/)。
 
-```jsonc
-// sop.json
-"guards": [ { "phase": "publish", "bash": "git +push" } ]
-```
+## 📄 许可
 
-```bash
-peaks hooks install --project <repo>   # 显式 opt-in：装一条 PreToolUse 规则
-```
+[MIT](LICENSE) — 商用、改、私有 fork 都欢迎，保留版权即可。
+
+---
+
+<div align="center">
 
-之后 agent 在 `publish` 阶段的门禁没全过时还想 `git push`，Claude Code 会收到 `permissionDecision: "deny"`，**在任何权限检查之前就被拦下——连 `--dangerously-skip-permissions` 都绕不过**。满足门禁后自动放行；紧急情况用 `peaks gate bypass --sop <id> --phase <phase> --reason "<原因>"` 一次性放行（每个项目每个 SOP 有上限、记原因）。
+**觉得有用？**
 
-> **两层定义、执行按项目**：SOP 定义（`sop.json` + `SKILL.md`）可以放在**全局** `~/.peaks/sops/`（个人跨项目复用）或**仓库** `<repo>/.peaks/sops/`（随仓库提交、团队共享；`peaks sop init/register --project <repo>`）。**仓库层优先**于全局层。运行态（当前阶段、历史）按项目落在 `<project>/.peaks/sop-state/<sop-id>/`。
+⭐ [Star peaks-cli on GitHub](https://github.com/SquabbyZ/peaks-cli) · 🔍 [Browse on skills.sh](https://skills.sh/SquabbyZ/peaks-cli)
 
-## 许可
+让你的 AI IDE 像一支训练有素的工程团队。
 
-MIT License，详见 [LICENSE](LICENSE)。
+</div>

package/dist/src/cli/commands/agent-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * peaks agent * CLI surface — Slice: ECC 64 agents soft-optional
+ * integration (per spec §7.2 line 818).
+ *
+ * Registers the new `peaks agent` top-level command with two
+ * subcommands:
+ *   - `peaks agent run <name> [--target <path>]`  — shell out to
+ *     `npx ecc agent run <name> --target <path> --json` when ECC
+ *     is installed; soft-fail with the 4-option install prompt
+ *     when it isn't.
+ *   - `peaks agent list`                          — emit the 12
+ *     canonical ECC agents (the wrapper hardcodes the
+ *     most-used subset; the full 64-agent list is
+ *     discoverable at runtime via `npx ecc agent list`).
+ *
+ * The wrapper service is `src/services/agent/ecc-agent-service.ts`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerAgentCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/agent-commands.js

@@ -0,0 +1,48 @@
+import { runEccAgent, validateEccAgent, CANONICAL_ECC_AGENTS, } from '../../services/agent/ecc-agent-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerAgentCommands(program, io) {
+    const agent = program
+        .command('agent')
+        .description('Run an ECC agent (soft-optional per spec §7.2). 64 agents are npm-installable via npx ecc; peaks-cli shells out when ECC is installed and soft-fails with a 4-option install prompt when it is not. Native peaks-cli diagnostics still run via `peaks doctor scan`.');
+    addJsonOption(agent
+        .command('run <name>')
+        .description(`Run an ECC agent by name (e.g. 'security-reviewer', 'code-reviewer'). The canonical subprocess is \`npx ecc agent run <name> --target <path> --json\`.`)
+        .option('--target <path>', 'project root or file to analyze (default: cwd)')
+        .option('--enable', 'enable the ECC subprocess for this call (overrides default-off; soft-fails with the 4-option install prompt when ECC is missing)')).action(async (name, options) => {
+        const validationError = validateEccAgent(name);
+        if (validationError !== null) {
+            printResult(io, fail('agent.run', 'INVALID_AGENT_NAME', validationError, { agent: name }, [
+                'Use `peaks agent list` to see the canonical 12 agents',
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const projectRoot = options.target ?? process.cwd();
+        try {
+            const result = runEccAgent({
+                agent: name,
+                projectRoot,
+                enableAgent: options.enable === true,
+            });
+            const data = { ...result, projectRoot };
+            const nextActions = [];
+            if (result.reason === 'flag-enabled-but-ecc-missing') {
+                nextActions.push('ECC not installed. Pick one of the four options below:', '  a) Install: run `npx ecc --help` to install, then re-run `peaks agent run`.', '  b) Skip this run: use the peaks-cli native diagnostic via `peaks doctor scan`.', '  c) Skip forever: run `peaks preferences set agentShieldEnabled false`.', '  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §7.2.');
+            }
+            const envelope = ok('agent.run', data, [...result.warnings], nextActions);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('agent.run', 'AGENT_RUN_FAILED', message, { agent: name, projectRoot, spawned: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(agent
+        .command('list')
+        .description(`List the 12 canonical ECC agents (peaks-cli ships a static subset; the full 64 are ECC-discovered).`)).action((options) => {
+        const envelope = ok('agent.list', { agents: CANONICAL_ECC_AGENTS.map((a) => ({ name: a.name, description: a.description })) }, [], ['Run any agent with: `peaks agent run <name> --target <path>`']);
+        printResult(io, envelope, options.json);
+    });
+}

package/dist/src/cli/commands/audit-commands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * peaks audit * CLI surface — Slice L2.1 + L2.3 P2-a.
+ *
+ * Registers the new `peaks audit` top-level command with the
+ * `red-lines` (L2.1) and `static` (L2.3 P2-a) subcommands.
+ * Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
+ * we verified that no `peaks audit` top-level exists; this is the only
+ * file that owns the registration.
+ */
+import { Command } from 'commander';
+import { type AgentShieldState } from '../../services/audit/static-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+import type { RedLineAudit } from '../../services/audit/types.js';
+export interface StaticAuditData {
+    readonly audit: RedLineAudit;
+    readonly agentShield: AgentShieldState;
+}
+export declare function registerAuditCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/audit-commands.js

@@ -0,0 +1,138 @@
+/**
+ * peaks audit * CLI surface — Slice L2.1 + L2.3 P2-a.
+ *
+ * Registers the new `peaks audit` top-level command with the
+ * `red-lines` (L2.1) and `static` (L2.3 P2-a) subcommands.
+ * Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
+ * we verified that no `peaks audit` top-level exists; this is the only
+ * file that owns the registration.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runRedLinesAudit } from '../../services/audit/red-lines-service.js';
+import { runStaticAudit } from '../../services/audit/static-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+function validateProjectRoot(projectArg) {
+    const projectRoot = resolve(projectArg);
+    if (!existsSync(projectRoot)) {
+        return { ok: false, code: 'PROJECT_NOT_FOUND', message: `project path does not exist: ${projectArg}` };
+    }
+    let stat;
+    try {
+        stat = statSync(projectRoot);
+    }
+    catch (error) {
+        return { ok: false, code: 'INVALID_PROJECT', message: getErrorMessage(error) };
+    }
+    if (!stat.isDirectory()) {
+        return { ok: false, code: 'INVALID_PROJECT', message: `project path is not a directory: ${projectArg}` };
+    }
+    return { ok: true, projectRoot };
+}
+export function registerAuditCommands(program, io) {
+    const audit = program
+        .command('audit')
+        .description('Audit a project for compliance with peaks-cli red lines (P0 / P1 / P2 tiers)');
+    addJsonOption(audit
+        .command('red-lines')
+        .description('Scan skills/, .claude/rules/, and openspec/changes/ for MANDATORY / BLOCKING / MUST NOT / RED LINE markers; classify each as cli-backed / partial / prose-only')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        const validation = validateProjectRoot(options.project);
+        if (!validation.ok) {
+            printResult(io, fail('audit.red-lines', validation.code, validation.message, { totalRedLines: 0, cliBacked: 0, partial: 0, proseOnly: 0, audit: [], enforcerFindings: [] }, ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = runRedLinesAudit({ projectRoot: validation.projectRoot });
+            const nextActions = [];
+            if (result.audit.proseOnly > 0) {
+                nextActions.push(`${result.audit.proseOnly} prose-only red lines remain. Plan P1/P2 enforcers in L2.2-L2.4.`);
+            }
+            if (result.audit.cliBacked > 0) {
+                nextActions.push(`${result.audit.cliBacked} red lines are now cli-backed. Re-run after each enforcer lands to track the prose-only ratio.`);
+            }
+            const envelope = ok('audit.red-lines', result.audit, result.warnings.map((w) => `${w.file}: ${w.message}`), nextActions);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            printResult(io, fail('audit.red-lines', 'SCANNER_FAILED', getErrorMessage(error), { totalRedLines: 0, cliBacked: 0, partial: 0, proseOnly: 0, audit: [], enforcerFindings: [] }, ['Inspect scanner logs and re-run with the same --project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // Slice #6 L2.3 P2-a: peaks audit static — soft-optional ECC
+    // AgentShell integration. Reads `.peaks/preferences.json`'s
+    // `agentShieldEnabled` flag (default false). The CLI flags
+    // `--enable-agent-shield` / `--disable-agent-shield` override
+    // the preference for a single call.
+    addJsonOption(audit
+        .command('static')
+        .description('Run the static audit (peaks-cli lint + optional ECC AgentShield subprocess). Per spec §5.3.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--enable-agent-shield', 'force-enable ECC AgentShield subprocess for this call (overrides preference)')
+        .option('--disable-agent-shield', 'force-disable ECC AgentShield subprocess for this call (overrides preference)')).action(async (options) => {
+        const validation = validateProjectRoot(options.project);
+        if (!validation.ok) {
+            printResult(io, fail('audit.static', validation.code, validation.message, emptyStaticAuditData(), ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // Resolve the flag override. `--enable-agent-shield` and
+        // `--disable-agent-shield` are mutually exclusive; we surface
+        // a 422 if both are passed.
+        if (options.enableAgentShield && options.disableAgentShield) {
+            printResult(io, fail('audit.static', 'FLAGS_CONFLICT', '`--enable-agent-shield` and `--disable-agent-shield` are mutually exclusive', emptyStaticAuditData(), ['Pass at most one of the two flags']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = runStaticAudit({
+                projectRoot: validation.projectRoot,
+                ...(options.enableAgentShield
+                    ? { enableAgentShield: true }
+                    : options.disableAgentShield
+                        ? { enableAgentShield: false }
+                        : {}),
+            });
+            const data = {
+                audit: result.audit,
+                agentShield: result.agentShield,
+            };
+            const nextActions = [];
+            // Per spec §5.3 + §7.2: when ECC is not installed, surface
+            // the canonical 4-option user opt-in UX (a/b/c/d) via
+            // nextActions. The peaks-cli `peaks audit static` CLI is
+            // non-interactive (JSON envelope by default), so the 4
+            // options are surfaced as machine-readable action strings
+            // — same pattern as understand-commands.ts `INSTALL_HINT`.
+            if (!result.agentShield.installed) {
+                nextActions.push('ECC AgentShield not installed. Pick one of the four options below:');
+                nextActions.push('  a) Install: run `npx ecc-agentshield --help` to install, then re-run `peaks audit static`.');
+                nextActions.push('  b) Skip this run: pass `--disable-agent-shield` to suppress the subprocess for this call.');
+                nextActions.push('  c) Skip forever: run `peaks preferences set agentShieldEnabled false` (writes to `.peaks/preferences.json`).');
+                nextActions.push('  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.3 + §7.2.');
+            }
+            if (result.agentShield.spawned && result.agentShield.findings.length > 0) {
+                nextActions.push(`${result.agentShield.findings.length} ECC findings merged into the audit. Review with \`peaks audit static --json\`.`);
+            }
+            const envelope = ok('audit.static', data, [...result.warnings], nextActions);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            printResult(io, fail('audit.static', 'SCANNER_FAILED', getErrorMessage(error), emptyStaticAuditData(), ['Inspect scanner logs and re-run with the same --project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+function emptyStaticAuditData() {
+    return {
+        audit: { totalRedLines: 0, cliBacked: 0, partial: 0, proseOnly: 0, audit: [], enforcerFindings: [] },
+        agentShield: {
+            spawned: false,
+            installed: false,
+            reason: 'flag-disabled',
+            findings: [],
+        },
+    };
+}

package/dist/src/cli/commands/classify-classify-commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * peaks classify CLI (Slice L1a + L1b).
+ *
+ * Subcommands:
+ *   - peaks classify run --project <path> [--override <level> --reason "<text>"]
+ *     Classify the current diff via the heuristic + return a JSON envelope
+ *     with the chosen level, gate set, and audit log.
+ *   - peaks classify override --level <level> --reason "<text>" --project <path>
+ *     Force a level; writes the override to the audit log.
+ *   - peaks classify upgrade --level <level> --reason "<text>" --project <path>
+ *     Same as override but explicitly framed as an upgrade (audit log
+ *     records the upgrade event separately from override).
+ *
+ * Downgrade is REFUSED (per spec §4: "peaks classify downgrade" always
+ * errors out). LLM may ask; the CLI never grants.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerClassifyCommands(program: Command, io: ProgramIO): void;