peaks-cli 1.4.2 → 2.0.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,51 @@
+{
+  "metadata": {
+    "pluginRoot": ".",
+    "version": "2.0.1"
+  },
+  "plugins": [
+    {
+      "name": "peaks-cli",
+      "description": "Cross-AI-IDE workflow-gating CLI + 11-skill family. Turns LLM improvisation into auditable engineering process. Skills cover PRD / R&D / UI / QA / change-control / context / SOP definition / orchestration. Soft-fail gates block irreversible actions mid-conversation (even under --dangerously-skip-permissions).",
+      "version": "2.0.1",
+      "author": {
+        "name": "SquabbyZ"
+      },
+      "homepage": "https://github.com/SquabbyZ/peaks-cli",
+      "repository": "https://github.com/SquabbyZ/peaks-cli",
+      "license": "MIT",
+      "tags": [
+        "workflow",
+        "gating",
+        "sop",
+        "code-review",
+        "agent-team",
+        "cross-ide",
+        "claude-code",
+        "memory",
+        "second-opinion"
+      ],
+      "keywords": [
+        "AI IDE",
+        "agent guardrails",
+        "SOP engine",
+        "cross-IDE",
+        "developer workflow",
+        "irreversible-action gates"
+      ],
+      "skills": [
+        "./skills/peaks-solo",
+        "./skills/peaks-solo-resume",
+        "./skills/peaks-solo-status",
+        "./skills/peaks-solo-test",
+        "./skills/peaks-prd",
+        "./skills/peaks-rd",
+        "./skills/peaks-qa",
+        "./skills/peaks-ui",
+        "./skills/peaks-sc",
+        "./skills/peaks-txt",
+        "./skills/peaks-sop"
+      ]
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,279 @@
+# Changelog
+
+All notable changes to peaks-cli are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.0.0] — 2026-06-12
+
+### 🎯 Headline
+
+**One-key 1.x → 2.0 upgrade.** `npm i -g peaks-cli@2.0` runs the full
+upgrade umbrella in the consuming project automatically (gated by the
+1.x detector). The manual fallback is `peaks upgrade --to 2.0 --auto`.
+
+The architecture moves to **skill-first / CLI-auxiliary**: skill SKILL.md
+files are the primary surface the LLM consumes; CLI commands are
+machine-enforced gates, structured-JSON probes, or side-effect primitives.
+See `.claude/rules/common/dev-preference.md` (project-local) for the
+operating tenet.
+
+**ocr second-opinion code review (soft-optional).** Alibaba's
+`@alibaba-group/open-code-review` is now an `optionalDependency`; when
+installed + configured against a user-owned LLM endpoint, peaks-rd's
+Gate B3 merges its findings into `code-review.md` as a second opinion
+alongside the LLM-only review. Soft-fails so missing ocr never blocks
+a slice. New CLI: `peaks code-review detect-ocr` / `run-ocr`. See
+`skills/peaks-rd/references/ocr-integration.md` for the contract.
+
+### Breaking Changes
+
+- **`.claude/rules/` is no longer the source of truth for project standards.**
+  The 2.0 canonical location is `.peaks/standards/{common,typescript}/*.md`.
+  The 1.x `.claude/rules/` tree is thinned to 2-line pointers during upgrade,
+  preserving the original under `.claude/rules/.peaks-2.0-backup-<ISO>/`.
+
+- **`.gitignore` requires a granular `.peaks/` block**, not a wholesale
+  `/.peaks/` ignore. The upgrade umbrella migrates the consumer's
+  `.gitignore` automatically (with a timestamped backup); without it, 2.0
+  tracked artifacts (`.peaks/standards/`, durable `.peaks/memory/*.md`,
+  `.peaks/PROJECT.md`, opt-in markers) would be silently hidden from git.
+
+- **Per-project config moved from `~/.peaks/config.json` to `<project>/.peaks/preferences.json`.**
+  `~/.peaks/config.json` retains only `{ "version": "2.0.0" }`. Fields
+  `economyMode`, `swarmMode`, headroom settings, etc. are now per-project.
+  The upgrade umbrella runs `peaks config migrate --apply` automatically.
+
+- **Postinstall behavior changed.** `npm i -g peaks-cli@2.0` now:
+  1. Symlinks bundled skills to **all 8 supported IDE platforms**
+     (Claude Code, Trae, Cursor, Qoder, Codex, Tongyi Lingma, Aider, Roo Code),
+     not just the auto-detected one. Per real Trae user feedback 2026-06-11.
+  2. Installs bundled output styles.
+  3. If `cwd` contains a 1.x peaks-cli project, fire-and-forgets
+     `peaks upgrade --to 2.0 --auto`. Opt out with `PEAKS_SKIP_AUTO_UPGRADE=1`.
+
+### Changed — ocr source-of-truth moved into peaks-cli's config
+
+Following the same-release user feedback that the original 2.0.0 ocr
+config lived in `~/.opencodereview/config.json` (a file outside
+peaks-cli's reach) and was set via the `ocr config set` CLI from the
+upstream package, the ocr LLM endpoint config now lives under
+`peaksConfig.ocr.llm` in `~/.peaks/config.json`. This makes the
+user-managed LLM endpoint discoverable from a single, peaks-cli-owned
+config surface.
+
+- **`@alibaba-group/open-code-review` is now a hard `dependency`** (was
+  `optionalDependency`). The user no longer has to remember to install
+  it; `npm i -g peaks-cli` pulls it. Network-blocked installs that fail
+  to download the platform binary still soft-fail at runtime
+  (`binary-missing` state) — the install-time failure risk is the
+  trade-off.
+- **`detectOcr` / `runOcrReview` no longer read `~/.opencodereview/config.json`.**
+  The source of truth is `peaksConfig.ocr.llm` (parsed by
+  `getOcrLlmConfig()` in `config-service.ts`). Missing fields surface
+  in `data.missingKeys`; the `config-missing` state's `nextActions`
+  payload embeds the JSON template to paste.
+- **Env-var injection replaces file writes.** `runOcrReview` injects
+  `OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL` /
+  `OCR_USE_ANTHROPIC` / `OCR_LLM_AUTH_HEADER` from `peaksConfig.ocr.llm`
+  when spawning the ocr subprocess — the ocr package's highest-priority
+  config path. peaks-cli never has to materialise
+  `~/.opencodereview/config.json`, and does NOT auto-configure the
+  endpoint — the user is the only party that touches the LLM
+  token / URL.
+- **New CLI: `peaks code-review config-template`.** Prints the JSON
+  snippet the user pastes into `~/.peaks/config.json`. It does NOT
+  write anything. No `peaks ocr config set`, no `ocr config set` — just
+  edit peaks-cli's config.json (or use
+  `peaks config set --key ocr.llm.url --value '...'` if preferred).
+- **JSON envelope contract change:** `OcrDetectResult.configPath` now
+  points at the peaks-cli config (e.g. `~/.peaks/config.json`) instead
+  of the OCR package's legacy file. A new `missingKeys` field lists the
+  required `ocr.llm.*` keys the user has not yet populated. The
+  five-state contract and the soft-fail policy are unchanged.
+
+### Migration (ocr source-of-truth)
+
+Users who already configured `~/.opencodereview/config.json` for the
+soft-optional 2.0.0 release should:
+
+1. Run `peaks code-review config-template --json` to see the JSON
+   snippet.
+2. Paste the equivalent values into `~/.peaks/config.json` under
+   `ocr.llm` (peaks-cli handles the camelCase conversion; the
+   template shows the canonical shape).
+3. Re-run `peaks code-review detect-ocr --json` to verify
+   `state == "ready"`.
+
+The old `~/.opencodereview/config.json` is no longer consulted by
+peaks-cli. The user may delete it at their discretion (the ocr
+subprocess ignores it when peaks-cli's env vars are present).
+
+### Added
+
+- **`peaks upgrade --to 2.0`** — umbrella that orchestrates the 1.x → 2.0
+  migration: config migrate, standards migrate (`--from-claude-rules`),
+  memory extract (with disk-based glob expansion for the consumer's
+  artifact tree), hooks install, skill sync, audit verify, plus
+  in-process preferences-ensure, gitignore-migrate, and upgrade-record
+  write. Soft-fail per sub-step; never blocks the whole upgrade.
+
+- **`peaks upgrade --detect-1x`** — read-only probe returning a JSON
+  envelope the peaks-solo skill consumes to gate the AskUserQuestion
+  in Step 0.55.
+
+- **`peaks standards migrate --from-claude-rules`** — thins `.claude/rules/`
+  to 2-line pointers and scaffolds `.peaks/standards/{common,typescript}/`.
+
+- **`peaks skill sync`** — distributes the skill family across all 8
+  supported IDE platforms in one command.
+
+- **`peaks audit red-lines`** — L2 catalog audit (P0/P1/P2-a/P2-b
+  enforcers) for skills/SKILL.md, references/*.md, and the agent shield.
+
+- **`peaks agent run`** — ECC 64 agents soft-optional integration
+  (spec §7.2). When the L3 stack is installed, peaks delegates to it;
+  otherwise degrades to peaks-cli's own core diagnostics.
+
+- **`peaks memory search` / `peaks retrospective search`** — new search
+  subcommands for the durable memory / retrospective stores.
+
+- **`peaks workspace init / clean / archive`** — workspace lifecycle
+  primitives with `--dry-run` default + `--apply` opt-in.
+
+- **`peaks preferences set / get / reset`** — per-project preferences
+  read/write CLI.
+
+- **Two paired tenets** captured in `.peaks/memory/peaks-cli-tenet-one-key-completion.md`:
+  - **One-key completion** — actions that can be done in one step
+    should not be designed as two-step operations.
+  - **Minimal user operation** — features can be powerful, but the
+    user-facing surface should be minimal; the CLI/LLM figures it out.
+
+### Fixed
+
+- **(2026-06-12) `upgrade-service.ts` was missing from develop HEAD**,
+  causing fresh clones to fail TS2307. Repaired in commit ec6f674.
+
+- **(2026-06-12) `peaks standards migrate --from-claude-rules`** rejected
+  as `unknown option`. CLI flag wiring fixed in core-artifact-commands.ts.
+
+- **(2026-06-12) `peaks memory extract`** failed with
+  `Artifact path must stay inside the project root` when the umbrella
+  passed literal glob strings (`skills/**/SKILL.md`). The umbrella now
+  expands globs on disk before spawning.
+
+- **(2026-06-12) Three bugs surfaced by real-world ice-cola dogfood:**
+  - memory-extract was called without `--apply` → always dry-ran, never
+    actually wrote.
+  - `.claude/skills/**/SKILL.md` (the standard Claude-Code consumer
+    convention) was not walked; only `<root>/skills/` was scanned.
+  - `.peaks/preferences.json` was never created after upgrade, so the
+    1.x detector kept returning `isOneX=true` and the user got stuck
+    in a re-prompt loop. Violated the one-key completion tenet.
+
+- **(2026-06-12) `.gitignore` 1.x wholesale `/.peaks/` rule** silently
+  hid every 2.0 tracked artifact. New `gitignore-migrate-service.ts`
+  detects 4 wholesale forms (`.peaks`, `.peaks/`, `/.peaks`, `/.peaks/`),
+  removes them, and appends the canonical 2.0 granular block with a
+  sentinel comment. Idempotent; creates timestamped backup before write.
+
+- **(2026-06-11) Windows: `peaks slice check`** was using `npx tsc` /
+  `npx vitest` which spawned `cmd.exe` indirectly via the npx shim and
+  failed with ENOENT. Now resolves local `node_modules/.bin/` binaries
+  directly via `runCommand(shell: true)`.
+
+### Deprecated
+
+- **`peaks workspace migrate-1-4-1`** — retained for 1.4.1 → 1.4.2
+  legacy session-layout backward compatibility. Will be removed in 2.1.
+  Use `peaks upgrade --to 2.0` for the canonical migration path.
+
+### Removed
+
+- `~/.peaks/config.json` schema is now `{ "version": "2.0.0" }` only.
+  All other fields are migrated to per-project `.peaks/preferences.json`
+  by `peaks config migrate`.
+
+### Architecture
+
+- **Skill-first / CLI-auxiliary.** SKILL.md is the primary surface;
+  CLI earns its keep only when (a) hook/script/CI-invokable, (b) the
+  consumer needs a structured JSON envelope to gate a decision, or
+  (c) destructive side-effect needs explicit `--apply`. See the
+  decision template in `.claude/rules/common/dev-preference.md`.
+
+- **Two-axis naming convention** for `.peaks/` workspace:
+  `<changeId>` for reviewable artifacts under `.peaks/<changeId>/...`;
+  `<sessionId>` for ephemeral state under `.peaks/_runtime/<sessionId>/...`.
+  Regression test pins zero use of ambiguous `<sid>`.
+
+- **`.peaks/_runtime/`** replaces `.peaks/runtime/` (defensive wrong-path
+  pattern still in .gitignore).
+
+### Verified
+
+- 223 test files / 2768 tests pass / 16 skipped.
+- `npx tsc --noEmit` clean.
+- `npm run build` clean.
+- End-to-end dogfood on real 1.x consumer project (ice-cola): 6/6
+  upgrade sub-steps pass; `.gitignore` migrated with backup; detector
+  returns `isOneX: false` after upgrade; all 2.0 tracked artifacts
+  surface in `git status`.
+
+### Migration Guide
+
+See `docs/UPGRADING-2.0.md` for the manual fallback if the auto-upgrade
+is skipped (`PEAKS_SKIP_AUTO_UPGRADE=1` or `npm i --ignore-scripts`).
+
+---
+
+## [2.0.1] — 2026-06-12
+
+### Fixed
+
+- **Bug 1 — `~/.peaks/config.json` was bloated to 9 top-level fields.**
+  The 2.0.0 release moved per-project fields (`language`, `model`,
+  `economyMode`, `swarmMode`) to `<project>/.peaks/preferences.json`
+  per spec §10.4, but the runtime `DEFAULT_CONFIG` still shipped
+  `language` / `model` / `economyMode` / `swarmMode` / `tokens` /
+  `providers` / `proxy` / `progress` placeholders. The slim migration
+  (`executeMigration`) wrote `{ version: "2.0.0" }` only, but any
+  code path that went through `readConfig` and re-serialised
+  re-bloated the file. The 2.0.1 fix:
+
+  1. **Slim `DEFAULT_CONFIG`** to `{ version, ocr: { llm: { url, authToken, model, useAnthropic, authHeader } } }`
+     (placeholders for the OCR LLM endpoint only).
+  2. **Slim migration write** to the same 2-key form, so a fresh
+     `peaks config migrate --apply` produces a discoverable
+     `ocr.llm` block the user can paste their endpoint into.
+  3. **Tolerant loader.** Legacy 1.x files with extra fields
+     (`language`, `model`, `tokens`, `providers`, `proxy`, etc.)
+     still load without throwing; the legacy fields are exposed
+     via `getConfig` for backward compatibility, and
+     `setConfig` rejects writes to `language` / `model` /
+     `economyMode` / `swarmMode` with a pointer to
+     `<project>/.peaks/preferences.json` (do not silently migrate).
+
+  The net effect: a freshly-installed peaks-cli writes a 2-key
+  `~/.peaks/config.json`; legacy 1.x files migrate to the same
+  2-key form; the ocr second-opinion config is now the only
+  discoverable surface the user needs to populate to make
+  `peaks code-review detect-ocr` report `state: "ready"`.
+
+### Verification
+
+- 70 config tests pass (`tests/unit/config-*`).
+- `pnpm tsc -p tsconfig.json --noEmit` clean (excluding pre-existing
+  sync-service test scaffold for Bug 2).
+
+---
+
+## [1.4.2] — 2026-06-08
+
+Last 1.x release. See git history pre-2.0.0 for details.
+
+[2.0.0]: https://github.com/SquabbyZ/peaks-cli/releases/tag/v2.0.0

package/README-en.md

@@ -0,0 +1,226 @@
+<div align="center">
+
+# ⛰️ Peaks
+
+**Make your AI IDE work like a disciplined engineering team**
+
+**English** | [简体中文](./README.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)
+
+**One CLI + 11 workflow skills. Turn LLM improvisation into auditable engineering process.**
+
+[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)
+
+</div>
+
+---
+
+## 🤔 Why Peaks
+
+> 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.**
+
+Peaks models the "engineering team" inside your AI IDE as 11 workflow skills + a set of **executable gates**:
+
+- 🧭 **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 11 skills are also published to [skills.sh](https://skills.sh); `npx skills add` to install on demand
+
+## 🚀 30 seconds to running
+
+```bash
+# 1. Install the CLI
+npm install -g peaks-cli
+
+# 2. Open Claude Code in your project
+cd /path/to/your-project && claude
+
+# 3. Tell the AI what to do
+> peaks-solo add OAuth callback to the login page
+```
+
+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.**
+
+## ⏱️ 5-minute onboarding
+
+In an adapted AI IDE conversation, just ask the AI to use a skill by name:
+
+```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
+```
+
+**Two ways to use Peaks**:
+
+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
+
+Quick status check? Ask the AI to run:
+
+```bash
+peaks -V                       # version
+peaks doctor --json            # environment / skills / config one-shot check
+peaks project dashboard --project . --json   # one-shot project view
+```
+
+## 🧰 11 skills in the family
+
+| 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" |
+
+**3 solo wrappers + 7 role skills + 1 orchestrator = 11 skills.** In daily use, 1 skill (`peaks-solo`) covers ≥ 90% of needs.
+
+## 🚧 Killer feature: un-bypassable gates
+
+> 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.**
+
+```jsonc
+// sop.json
+"guards": [ { "phase": "publish", "bash": "git +push" } ]
+```
+
+```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:
+
+| 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` |
+
+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
+
+**Scenario 1: ad-hoc refactor decision**
+
+```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.**
+
+**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**.
+
+**Scenario 3: browser E2E regression**
+
+```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**
+
+```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.**
+
+## 📦 Discover peaks on skills.sh
+
+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:
+
+- 11 `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 11 public skills (internal `peaks-doctor` / `peaks-ide` are hidden via `metadata.internal: true`)
+
+Any environment with `npx skills` installed (Claude Code, Cursor, Codex, ...) can pull them directly:
+
+```bash
+# Install all 11:
+npx skills add SquabbyZ/peaks-cli
+
+# Or just one:
+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
+```
+
+Browse [skills.sh/SquabbyZ/peaks-cli](https://skills.sh/SquabbyZ/peaks-cli) for the full catalog. The skills shipped here and the skills shipped via `npm install -g peaks-cli` are the same artifact — both paths deliver the same content.
+
+## 🛠️ How it works: skills first, CLI as gates
+
+The `peaks <cmd>` CLI is **not your daily driver**. It exists for three machine-level reasons only:
+
+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
+
+One line: **SKILL = the workflow's brain; CLI = the workflow's joints**.
+
+### CLI commands you'll *see* skills call
+
+```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
+```
+
+Full list: `peaks --help`.
+
+## 🌐 Supported IDEs
+
+| IDE | Status |
+|---|---|
+| ✅ **Claude Code** | 11 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 |
+
+## 🏗️ Project status
+
+- ✅ **11 skills** + cross-IDE CLI + 2,800+ tests
+- ✅ **Gate mechanism** dogfooded on real projects
+- 📋 Roadmap: real Trae / Codex / Cursor integration, `peaks-doc` / `peaks-i18n`, SOP template marketplace
+
+See [`CHANGELOG.md`](./CHANGELOG.md) and [`docs/`](./docs/) for details.
+
+## 📄 License
+
+[MIT](LICENSE) — commercial use, modification, private forks all welcome; keep the copyright notice.
+
+---
+
+<div align="center">
+
+**Find it useful?**
+
+⭐ [Star peaks-cli on GitHub](https://github.com/SquabbyZ/peaks-cli) · 🔍 [Browse on skills.sh](https://skills.sh/SquabbyZ/peaks-cli)
+
+Make your AI IDE work like a disciplined engineering team.
+
+</div>