peaks-cli 1.2.8 → 1.3.0

package/skills/peaks-solo/references/runbook.md

@@ -0,0 +1,168 @@
+# Peaks-Cli Default Runbook (orchestrator, full-auto profile)
+
+> **Maintenance**: The numbered workflow list in `skills/peaks-solo/SKILL.md` (steps 0-11) is the canonical phase sequence. This runbook is the executable CLI transcription. When updating, keep both in lockstep — a change to one must be reflected in the other.
+>
+> **Why this is a reference, not inline**: the runbook is a stable, copy-pasteable shell (~150 lines of bash) that does not change between skill runs. Inlining it bloats the orchestrator skill body past the 800-line cap (per `common/coding-style.md`). Extracting it here keeps SKILL.md focused on flow / decisions / contracts, while the runbook stays as the canonical place for the CLI sequence.
+>
+> **How peaks-cli tooling reads this file**:
+> - `peaks skill runbook peaks-solo` (CLI) reads the `## Default runbook` section in either SKILL.md or `references/runbook.md` (whichever has the bash code).
+> - The test in `tests/unit/skill-default-runbook.test.ts` looks for `## Default runbook` in SKILL.md first, then falls back to `references/runbook.md` here.
+
+## Default runbook
+
+The end-to-end CLI sequence for the `full-auto` profile. `assisted` and `strict` profiles pause at `[CONFIRM]` markers below. `full-auto` and `swarm` auto-proceed through all gates. See Transition Gates for artifact verification at each stage.
+
+```bash
+# 0. Peaks-Cli Snapshot + 0.5 Peaks-Cli Workspace + 0.6 Peaks-Cli Project scan + 0.7 Peaks-Cli Existing-system extraction
+peaks doctor --json
+peaks project dashboard --project <repo> --json
+peaks skill runbook peaks-solo --json
+peaks workspace init --project <repo> --json
+peaks workspace reconcile --project <repo> --json
+peaks scan archetype --project <repo> --json
+# → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
+# → copy libraries[] into .peaks/<session-id>/rd/project-scan.md under `## Library versions`
+peaks scan libraries --project <repo> --json
+# → if archetype != greenfield AND archetype != unknown:
+peaks scan existing-system --project <repo> --json
+# → copy tokens, sources, conventions, inconsistencies into .peaks/<session-id>/system/existing-system.md (Peaks-Cli Gate A.5)
+
+# 1. Peaks-Cli Standards preflight + apply
+#    Run dry-run first to inspect deltas, then APPLY. In full-auto and swarm modes,
+#    --apply is the default — Standards files (CLAUDE.md, .claude/rules/**) live INSIDE
+#    the target project and are required for downstream skill preflight, so producing
+#    them is part of completing the workflow. Assisted/Strict modes pause for [CONFIRM]
+#    between dry-run and apply.
+peaks standards init   --project <repo> --dry-run --json
+# or: peaks standards update --project <repo> --dry-run --json
+peaks standards init   --project <repo> --apply --json
+# or: peaks standards update --project <repo> --apply --json
+# After apply, verify the files actually exist on disk (see Peaks-Cli Gate G).
+
+# 2. Peaks-Cli PRD (Assisted/Strict: [CONFIRM] before confirmed-by-user)
+# Classify the request type from the PRD: feature | bugfix | refactor | docs | config | chore
+# This drives RD/QA gate strictness — see "Mandatory RD QA repair loop" for the matrix.
+peaks request init --role prd --id <rid> --project <repo> --apply --type <type> --json
+# Cross-verify the chosen --type against the current git diff (only meaningful if RD has started writing code;
+# safe to run early too, just expect "no changes" rationale until code lands).
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → re-classify before continuing. consistent=true → proceed.
+# Lint the PRD artifact before transitioning out of draft.
+peaks request lint <rid> --role prd --project <repo> --json
+# → ok=false → fill in <placeholders>, then re-run.
+peaks request transition <rid> --role prd --state confirmed-by-user --project <repo> --json
+peaks request transition <rid> --role prd --state handed-off --project <repo> --json
+
+# 3. Peaks-Cli Swarm parallel — sub-agent fan-out (Task tool, NOT Skill tool)
+#    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
+#    writes it to .peaks/<sid>/sc/swarm-plan.json, then launches one
+#    Task(subagent_type="general-purpose", ...) call per sub-agent in the same message.
+#    See "Peaks-Cli Swarm parallel phase" above for the full decision table and the
+#    prompt template; the role's required artefact paths are listed there.
+#    Hard rule: do NOT call Skill(skill="peaks-rd" | "peaks-qa" | "peaks-ui") from
+#    the Swarm phase — that's the v1.x anti-pattern.
+#
+# 3a. Pre-fan-out: Solo initialises every role's request artefact slot in the main
+#     loop so sub-agents find a stable rid <-> artefact binding. Each role's
+#     sub-agent may also call peaks request init itself (idempotent on the same rid);
+#     Solo's call here is the source of truth. Only init roles that are in the
+#     swarm plan — roles not in the plan do not get a slot yet.
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-fan-out
+# for each role in swarm-plan.subAgents:
+# peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+# e.g. if plan = [ui, rd, qa]: run init for ui, rd, qa.
+# If plan = [rd, qa]: run for rd, qa only.
+# If plan = [] (config|docs|chore skip): no inits here, jump to step 4 directly.
+# 3b. Solo issues N Task(subagent_type="general-purpose", ...) calls in ONE message
+#     (N = len(swarm-plan.subAgents)). Each prompt embeds the role's body minus
+#     Step 0 / presence, plus the runtime args (rid / sid / mode / type / paths).
+# 3c. After fan-out, Solo restores presence once and runs Gate B (ls checks):
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
+ls .peaks/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
+# feature / refactor → ls .peaks/<sid>/rd/tech-doc.md
+# bugfix             → ls .peaks/<sid>/rd/bug-analysis.md
+ls .peaks/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
+# ui (only when in plan):
+ls .peaks/<sid>/ui/design-draft.md 2>&1               # non-blocking (Gate B info)
+# Apply the degradation rules in the main SKILL.md if any artefact is missing.
+# → Peaks-Cli Gate B convergence check. Assisted/Strict: [CONFIRM]
+
+# 4. Peaks-Cli RD planning artifact (the file required by the prerequisite gate)
+#    feature / refactor → write .peaks/<id>/rd/tech-doc.md
+#    bugfix             → write .peaks/<id>/rd/bug-analysis.md
+#    config             → no planning artifact required at this state
+#    docs / chore       → no planning artifact required
+peaks request transition <rid> --role rd --state implemented --project <repo> --json
+
+# 5. Peaks-Cli Code review + security review BEFORE qa-handoff transition.
+#    Produce the evidence files the CLI gate enforces:
+#      - .peaks/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
+#      - .peaks/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
+#    Then transition. If --type is docs/chore the gate is empty and the transition is unguarded.
+peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
+
+# 6. Peaks-Cli QA validation (AUTO-PROCEED from RD in full-auto)
+#    Before each QA transition, produce the evidence files the CLI gate enforces:
+#      Before qa:running        → .peaks/<id>/qa/test-cases/<rid>.md
+peaks request transition <rid> --role qa --state running --project <repo> --json
+#      Before qa:verdict-issued → .peaks/<id>/qa/test-reports/<rid>.md
+#                                 + .peaks/<id>/qa/security-findings.md
+#                                 + .peaks/<id>/qa/performance-findings.md (feature/refactor only)
+peaks request transition <rid> --role qa --state verdict-issued --project <repo> --json
+# → Peaks-Cli Gate D check. Assisted/Strict: [CONFIRM]
+
+# 7. Peaks-Cli RD↔QA repair loop — if verdict is return-to-rd, re-run 4 through 6 until QA passes or blocked TXT.
+#    Before invoking peaks-rd again, check the cycle count so you don't blow past the cap silently:
+peaks request repair-status <rid> --project <repo> --json
+# → atCap=true → STOP and emit a blocked TXT handoff. Do NOT enter another cycle.
+# → remaining > 0 → safe to continue. The next transition's --reason must include "QA return-to-rd cycle N: ..."
+#                   so this command keeps counting accurately.
+# After RD finishes the repair, re-check that the diff is still consistent with the declared --type:
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → RD scope-creeped during repair; review before re-handoff.
+
+# 8. Peaks-Cli SC phase
+peaks sc impact --change-id <cid> --module <module> --file <path> --json
+peaks sc retention --slice-id <rid> --prd <prd> --rd <rd> --qa <qa> --json
+peaks sc validate --slice-id <rid> --json
+peaks sc boundary --slice-id <rid> --artifact <artifact> --code <file> --json
+
+# 9. Peaks-Cli OpenSpec archive (exit gate; only after QA pass, when openspec/ exists)
+peaks openspec validate <cid> --project <repo> --json
+peaks openspec archive <cid> --project <repo> --apply --json
+peaks workspace reconcile --project <repo> --apply --older-than 7
+
+# 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
+#     peaks-txt writes the handoff capsule to .peaks/<id>/txt/handoff.md. Inside the
+#     capsule body, peaks-txt embeds <!-- peaks-memory:start --> blocks for every
+#     stable project fact surfaced this session.
+#
+# 10a. Skill-side scan (do this BEFORE the AskUserQuestion below):
+#      grep -n "peaks-memory:start" .peaks/<id>/txt/handoff.md
+#      Record the count. This is the skill doing the work, not a CLI command —
+#      we deliberately do not ship a `peaks memory scan` because the LLM is
+#      the only consumer and the LLM has grep.
+
+# 10b. AskUserQuestion (only if 10a returned count >= 1):
+#      "The TXT handoff has N peaks-memory:start blocks. Persist to .peaks/memory/?
+#       (a) Apply all — `peaks memory extract --project <repo>
+#                            --artifact .peaks/<id>/txt/handoff.md --apply --json`
+#       (b) Apply selectively — re-edit handoff.md first, then re-apply
+#       (c) Skip for now — blocks stay in the handoff only, no .peaks/memory/ write"
+#      If 10a returned 0 AND the session surfaced a stable project fact
+#      (decision / convention / approved refactor), STOP — peaks-txt must go
+#      back and embed at least one block before Solo can advance.
+
+# 10c. After the user picks (a) or (b), run:
+peaks memory extract --project <repo> --artifact .peaks/<id>/txt/handoff.md --apply --json
+#      --apply is REQUIRED to write .peaks/memory/; without it the command only
+#      previews. The extract regenerates index.json in the same call.
+
+# 11. Peaks-Cli Final snapshot
+peaks project dashboard --project <repo> --json
+peaks skill doctor --json
+```
+
+Repair loop details: see `## Mandatory RD QA repair loop` in SKILL.md for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.

package/skills/peaks-solo/references/workflow-gates-and-types.md

@@ -0,0 +1,177 @@
+# Peaks-Cli Workflow Order + Request Type Classification + Transition Verification Gates
+
+> **Maintenance**: This reference holds the canonical contract for (a) how Solo sequences the 11 workflow steps, (b) which `--type` to pass to `peaks request init` for which slice shape, and (c) the executable `ls` / `grep` gate commands that physically block progression. SKILL.md keeps the narrative ("what peaks-solo does"); this file keeps the contract.
+>
+> **Why extracted from SKILL.md**: this content is 165 lines of mostly-tabular + bash-block contract — reference data, not orchestration prose. Inlining it bloats SKILL.md past the 800-line cap (per `common/coding-style.md`). The numbers, gate command shapes, and type-classification rules change rarely; the SKILL.md prose around them (orchestration flow, repair-loop intent, swarm fan-out shape) changes more often.
+>
+> **How peaks-cli tooling reads this file**:
+> - `peaks skill runbook peaks-solo` (CLI) and the in-line LLM reading the SKILL.md should reference this file when the gate-machine or type-classification contract is in play.
+> - The test `tests/unit/skill-default-runbook.test.ts` does NOT check this file (it only checks the runbook). Future tests can add a similar fallback for the gates-and-types contract.
+
+## Peaks-Cli Request type classification (MANDATORY before `peaks request init`)
+
+Before initializing any role artifact, classify the request into exactly one of six types. The choice drives RD/QA gate strictness (see "Mandatory RD QA repair loop"). Pick the **primary intent** — if a request could fit two types, the higher-strictness one wins.
+
+| `--type` | Pick this when the PRD says... | Pick something else when... |
+|---|---|---|
+| `feature` | Add new capability, new page/component/route/API path, new user-facing behavior. Includes "extend X to support Y" when Y is a new code path. | The PRD is fixing an existing broken behavior → `bugfix`. The PRD is reshaping existing code without changing user-visible behavior → `refactor`. |
+| `bugfix` | Fix a specific broken behavior; PRD includes reproduction steps or a defect description; success = "the broken thing now works as it was supposed to". | The "fix" actually adds new capability (validation that didn't exist, a missing field) → `feature`. The "fix" is purely cosmetic and has zero risk → still `bugfix`; do NOT downgrade to `chore`. |
+| `refactor` | Restructure code without changing user-visible behavior. Examples: rename modules, extract shared utilities, migrate a library version with no API surface change, split a monolithic file. PRD mentions coverage targets or "no behavior change". | The refactor incidentally adds or changes user-visible behavior → split into `refactor` + `feature` or pick `feature`. The change is one-line formatting → `chore`. |
+| `config` | Modify config / infrastructure files only: `tsconfig.json`, `eslint`, CI YAML, `package.json` scripts, env defaults, CORS/CSP rules, build config, Docker, deployment manifests. No application source-code changes. | The config change is paired with code changes that consume the new config → `feature` or `refactor` (whichever the code change is). |
+| `docs` | Modify only `*.md` / docs site / inline JSDoc / README. No `.ts` / `.tsx` / `.js` / `.css` / config-file changes. | Any source code change is included → use the type matching the code change. Adding a code example to docs that requires the example to compile → still `docs` if the example is illustrative only. |
+| `chore` | Pure mechanical hygiene: formatter run, lint fix, dependency version bump with no API surface change, dead-code removal of unused files identified by tooling. | The bump changes API behavior or requires consumer migration → `refactor` (or `feature` if it adds capability). Any logic edit → `bugfix` or `refactor`. |
+
+**Self-check before locking the type**: read the PRD scope and answer "what is the smallest gate set that still protects users from regression?" — that is the right type. Picking `docs` or `chore` to skip gates when source code is actually changing is a workflow violation and the SC phase will reject it.
+
+For ambiguous cases (e.g. "improve login flow"), ask the user to clarify before initializing. The cost of one `AskUserQuestion` round is much lower than running the wrong gate matrix for the whole workflow.
+
+When Peaks-Cli Solo coordinates development in a code repository, keep this order explicit:
+
+0. **Peaks-Cli Snapshot** — `peaks doctor` + `peaks project dashboard` to capture baseline state before anything else;
+0.5. **Peaks-Cli Workspace initialization** — `.peaks/<session-id>/` created, directory structure verified;
+0.6. **Peaks-Cli Project scan** — archetype, component library, CSS framework, build tool, state management, routing, data fetching, legacy signals detected and recorded to `.peaks/<session-id>/rd/project-scan.md`;
+0.7. **Peaks-Cli Existing-system extraction** (MANDATORY when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}; SKIP for greenfield) — extract visual tokens and code conventions from the live codebase to `.peaks/<session-id>/system/existing-system.md`. The path lives under `system/` (not `ui/`) because the file also records non-UI conventions (service-layer signatures, hooks, naming) that backend-only or legacy-fullstack work consumes. See `references/existing-system-extraction.md`. UI design-draft and RD implementation MUST treat the extracted tokens and conventions as hard constraints;
+1. **Peaks-Cli Standards preflight** — `peaks standards init/update --dry-run`, must reference concrete project-scan findings (never emit generic templates);
+2. **Peaks-Cli PRD phase** — capture request as canonical artifact, extract scope and acceptance criteria:
+   - Full-auto/Swarm: auto-transition to `confirmed-by-user` once the artifact is complete;
+   - Assisted/Strict: pause with `AskUserQuestion` for explicit user confirmation before proceeding;
+3. **Peaks-Cli Swarm parallel phase** — after PRD confirmed, launch UI, RD(planning), QA(test-cases) simultaneously:
+   3a. UI design draft and visual direction (MANDATORY when request is frontend/user-visible; skipped for `--type docs|chore|config` or pure-backend requests);
+   3b. RD planning artifact — `rd/tech-doc.md` for feature/refactor, `rd/bug-analysis.md` for bugfix, skipped for docs/chore/config;
+   3c. QA test-case generation (skipped for docs/chore — no acceptance surface to validate);
+4. **Peaks-Cli RD implementation** — consumes the type-appropriate inputs: project-scan + standards + (if UI involved) UI design-draft + RD planning artifact + QA test-cases. Includes unit tests for new/changed behavior (TDD) unless `--type` is docs/chore;
+5. **Peaks-Cli Code review + security review** — CRITICAL/HIGH issues fixed before progression; marked-blocked issues only allow a blocked handoff;
+6. **Peaks-Cli QA validation** (auto-proceed from RD in full-auto) — execute test cases + API checks + Playwright MCP headed browser E2E for frontend + security/perf checks + test report;
+7. **Peaks-Cli RD↔QA repair loop** — if QA verdict is `return-to-rd`, loop back to step 4 (RD implementation) and re-run through QA; max 3 repair cycles, then emit blocked TXT regardless;
+8. **Peaks-Cli SC phase** — change-control evidence: impact, retention, validate, boundary;
+9. **Peaks-Cli OpenSpec archive** — exit gate: validate → archive only after QA verdict=pass (when `openspec/` exists);
+10. **Peaks-Cli TXT handoff capsule** — mode, validated decisions, artifact paths, standards deltas, open questions, next action;
+11. **Peaks-Cli Final snapshot** — `peaks project dashboard` + `peaks skill doctor` to confirm the workflow closed cleanly.
+
+### Peaks-Cli Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file", the phase is incomplete.
+
+**Peaks-Cli Gate A — After workspace init + project scan:**
+```bash
+ls .peaks/<id>/rd/project-scan.md
+# Expected output: .peaks/<id>/rd/project-scan.md
+# "No such file" → STOP, run project scan first
+# File present but missing `## Archetype` or `## Project mode` sections → INCOMPLETE, rerun scan
+# File present and complete → reuse (project-scan is a session-scoped singleton)
+```
+
+**Peaks-Cli Gate A.5 — Existing-system extraction (legacy projects only):**
+```bash
+# If project-scan.md `## Archetype` is greenfield → skip this gate
+# Otherwise:
+ls .peaks/<id>/system/existing-system.md
+# "No such file" → STOP, run existing-system extraction
+# (see references/existing-system-extraction.md)
+```
+
+**Peaks-Cli Gate B — After swarm convergence (UI + RD planning + QA test-cases):**
+
+Peaks-Cli Gate B has two sub-checks: a HARD gate (blocks progression) and an INFORMATIONAL check (records degradation but does not block).
+
+```bash
+# B.hard — REQUIRED before continuing to RD implementation.
+#          Missing any of these → STOP, return to the role that owns the file.
+
+# Always required (every type):
+ls .peaks/<id>/prd/requests/<rid>.md
+
+# Type-specific RD planning artifact:
+#   feature / refactor → ls .peaks/<id>/rd/tech-doc.md
+#   bugfix             → ls .peaks/<id>/rd/bug-analysis.md
+#   config / docs / chore → (no RD planning artifact required)
+
+# QA test-cases (skipped for docs/chore):
+ls .peaks/<id>/qa/test-cases/<rid>.md
+```
+
+```bash
+# B.info — NON-BLOCKING. Record degradation in TXT, then proceed.
+ls .peaks/<id>/ui/design-draft.md 2>&1
+# "No such file" + request affects user-visible UI → swarm degradation rule 1 fires:
+#   note "ui-design-missing" in TXT, RD continues with PRD visual descriptions.
+# "No such file" + pure backend / docs / chore / config → state skip reason in TXT, proceed.
+```
+
+**Peaks-Cli Gate C — After RD implementation (before QA handoff):**
+
+The CLI gate (`peaks request transition --state qa-handoff`) is the authoritative check; running this `ls` first lets you produce missing files before the CLI rejects the transition.
+
+```bash
+# Always required
+ls .peaks/<id>/rd/requests/<rid>.md
+
+# Type-specific RD evidence (must match the type recorded in the artifact body)
+#   feature / refactor → ls rd/tech-doc.md rd/code-review.md rd/security-review.md rd/perf-baseline.md qa/test-cases/<rid>.md
+#                         (qa/test-cases/<rid>.md pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004)
+#   bugfix             → ls rd/bug-analysis.md rd/code-review.md rd/security-review.md qa/test-cases/<rid>.md
+#                         (rd/perf-baseline.md only when the bug is performance-shaped)
+#   config             → ls rd/security-review.md
+#   docs / chore       → (no extra evidence required)
+# Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
+```
+
+**Peaks-Cli Gate D — After QA validation:**
+
+The CLI gate at `qa:verdict-issued` is the authoritative check; this `ls` lets you produce missing evidence before the CLI rejects the transition.
+
+```bash
+# Always required
+ls .peaks/<id>/qa/requests/<rid>.md
+
+# Type-specific QA evidence
+#   feature / refactor → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md qa/performance-findings.md
+#   bugfix             → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md
+#   config             → ls qa/security-findings.md
+#   docs / chore       → (no QA evidence files required)
+# Missing required file → QA incomplete; do not transition to verdict-issued.
+```
+
+**Peaks-Cli Gate E — Before declaring workflow complete:**
+```bash
+find .peaks/<id>/ -type f | sort
+# Verify: files from gates A-D all appear in this list.
+# Any mandatory file missing → NOT complete. Do not emit TXT.
+# Peaks-Cli Gate G (CLAUDE.md + .claude/rules/**) must ALSO pass before TXT is emitted.
+```
+
+**Peaks-Cli Gate F — Root pollution check (BLOCKING before completion):**
+```bash
+# Verify no Peaks-Cli intermediate artifacts leaked to project root.
+ls feishu-doc-*.md *-snapshot.md qa-server.js 2>&1
+# Expected: "No such file or directory" for ALL patterns.
+# Any file found → ROOT POLLUTION. Move it to .peaks/<id>/prd/source/
+# (for doc snapshots) or .peaks/<id>/qa/ (for QA artifacts).
+# Note the migration in TXT handoff. Do NOT complete the workflow
+# with intermediate artifacts in the project root.
+```
+```bash
+# Extended check for common leak patterns
+find . -maxdepth 1 -name "*.png" -o -name "*.jpg" -o -name "qa-*.js" -o -name "mock-server.*" 2>&1
+# Any Peaks-Cli QA/UI intermediate files here → ROOT POLLUTION. Move and note.
+# Legitimate project files (e.g. favicon.png) are fine — only move Peaks-Cli artifacts.
+```
+
+**Peaks-Cli Gate G — Project standards present (BLOCKING before workflow completion):**
+```bash
+# After `peaks standards init/update --apply`, verify the files actually landed
+# at the project root. The CLAUDE.md and rules files are required so that
+# subsequent peaks-rd / peaks-qa / peaks-solo runs perform the project-local
+# preflight described in CLAUDE.md (read coding-style.md, code-review.md, security.md).
+ls <repo>/CLAUDE.md
+# "No such file" → BLOCKED. Run `peaks standards init --project <repo> --apply --json`
+# (first time) or `peaks standards update --project <repo> --apply --json` (existing).
+ls <repo>/.claude/rules/common/coding-style.md \
+   <repo>/.claude/rules/common/code-review.md \
+   <repo>/.claude/rules/common/security.md
+# Any "No such file" → BLOCKED. The standards apply step did not complete; re-run
+# standards init/update with --apply and re-verify.
+# Skipping Peaks-Cli Gate G (e.g. because the user did not explicitly authorize writes) is
+# only acceptable in `assisted`/`strict` modes where the user actively declined; in
+# `full-auto`/`swarm` the absence of these files is a workflow violation.
+```

package/skills/peaks-solo-resume/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: peaks-solo-resume
+description: Resume an in-flight peaks-solo slice in the current session. Use when the user says "continue the unfinished work", "继续完成", "把刚才没做完的收尾", or invokes `/peaks-solo-resume` directly. Detects the current session's deepest completed gate (via the Step 0.7 detection script at `tests/fixtures/skill-resume-mode-detect.sh`) and surfaces a resume option via `AskUserQuestion`. Triggers on `/peaks-solo-resume`, "继续完成刚才的", "resume the unfinished slice", "把刚才没做完的收尾".
+---
+
+# Peaks-Cli Solo Resume (wrapper)
+
+Peaks-Cli Solo Resume is a thin wrapper that handles the **most common high-frequency request shape**: "I was in the middle of something, continue it." It detects the current session's deepest completed gate, surfaces a resume option, then yields to the main `peaks-solo` skill (which runs the actual workflow from the matching gate onwards).
+
+**This is a transparent wrapper.** The user does not stay in this skill — once the resume option is confirmed, control hands off to `peaks-solo`. The wrapper exists only to (a) detect the in-flight slice without the LLM re-reading 3-5 artifact files, and (b) surface the resume option as a `AskUserQuestion` before the main loop skips ahead.
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-resume --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Detect the current session's in-flight slice
+
+Use the Step 0.7 detection script (added in slice 003) to classify the current session:
+
+```bash
+# 1. Confirm the current session id
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+
+# 2. Run the detection script
+bash tests/fixtures/skill-resume-mode-detect.sh "$sid" .peaks
+# Possible outputs: fresh | complete | resume:rd-planning | resume:qa-validation
+#                  | resume:txt-handoff | in-flight:<state>
+```
+
+## Step 2: Branch on the detection
+
+**If `fresh`**: no in-flight slice. Tell the user "No in-flight slice in this session." Then hand off to `peaks-solo` for a fresh start (set presence back, then run `peaks workspace init --project <repo> --json` and continue with Step 1 of `peaks-solo`).
+
+**If `complete`**: the workflow is already done. Tell the user "This session is complete — your previous slice already shipped." Then suggest a fresh start (`peaks-solo`) or close-out.
+
+**If `resume:<gate>`**: surface a resume option via `AskUserQuestion`:
+
+| Option | What it does |
+|---|---|
+| Resume from `<gate>` (Recommended) | Hand off to `peaks-solo` with the gate already at the matching point. The main loop skips ahead; the existing artifacts are preserved as-is. |
+| Start a fresh slice | Treat the current request as a new slice (new `rid`). Existing artifacts are preserved but not auto-resumed. |
+| Abandon the in-flight slice | Mark the in-flight slice as `deferred` (`peaks request transition <rid> --role rd --state deferred --reason "user abandoned"`) and start fresh. |
+
+**If `in-flight:<state>`**: the slice is mid-implementation. Surface a CONFIRM (not a resume):
+
+> "The slice is mid-implementation (state: `<state>`). The only valid option is to resume the in-flight gate. Continue?"
+
+Use `AskUserQuestion` with a single option (Confirm and resume from `<state>`). Do NOT auto-resume mid-implementation.
+
+## Step 3: Hand off to peaks-solo
+
+After the user confirms, **re-assert `peaks-solo` presence** so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <matching-gate>
+```
+
+Then tell the user: "Resuming from `<gate>`. The main peaks-solo skill will take over from there." and yield control. The user's next message will land in the `peaks-solo` main loop, which will pick up the workflow from the matching gate.
+
+## Hard rules (do NOT skip)
+
+- **Never silently auto-resume.** Always use `AskUserQuestion` first. The detection is a discovery; the user's confirmation is the gate.
+- **Never auto-resume mid-implementation.** For `in-flight:<state>`, the only valid option is "Confirm and resume from `<state>`" — never "Start a fresh slice" or "Abandon" without the user's explicit choice.
+- **Never write code or modify files in this skill.** This is a wrapper. The actual work (PRD, RD, QA, SC, TXT) is the main `peaks-solo` skill's job.
+- **Never add a new `peaks <cmd>`.** Use the existing CLI primitives: `peaks workspace init`, `peaks project dashboard`, `peaks session list`, `peaks skill runbook`, `peaks skill doctor`, `peaks scan archetype`, `peaks request transition`. The detection script (`tests/fixtures/skill-resume-mode-detect.sh`) is the only executable this skill invokes.
+
+## Anti-patterns (do NOT do)
+
+- Do NOT re-read 3-5 artifact files to determine the workflow state. The detection script does this in <1ms; re-reading is the bug Step 0.7 was added to prevent.
+- Do NOT skip the `AskUserQuestion` even if the user says "just continue". The user might have changed their mind, or there might be multiple in-flight slices.
+- Do NOT write to `.peaks/<sid>/` files. This skill is read-only on the workspace; it only reads `.peaks/.session.json` + runs the detection script.
+- Do NOT run `peaks workspace init` on a real session (would bind a new session id). Only run it on a fresh detection where no session exists.
+
+## Cross-references
+
+- The detection logic is canonical at `tests/fixtures/skill-resume-mode-detect.sh` (added in slice 003). The 8 vitest cases in `tests/unit/skill-resume-mode.test.ts` cover all classification outcomes.
+- The SKILL.md prose at `skills/peaks-solo/SKILL.md` Step 0.7 (added in slice 003) is the same logic, written for LLM consumption. This wrapper reuses the same script — there is no parallel implementation.
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent for this wrapper.

package/skills/peaks-solo-status/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: peaks-solo-status
+description: Show the current state of the peaks-solo orchestrator in a compact summary. Use when the user says "what's the current state", "现在到哪了", "where are we", or invokes `/peaks-solo-status` directly. Reads the existing CLI primitives (`peaks skill presence`, `peaks session list`, `peaks project dashboard`, `peaks request show`) and renders a 1-screen status table. Triggers on `/peaks-solo-status`, "现在到哪了", "what is the current state", "show me the dashboard", "where are we".
+---
+
+# Peaks-Cli Solo Status (wrapper)
+
+Peaks-Cli Solo Status is a thin wrapper that renders a compact status table for the current peaks-solo orchestrator state. It is the answer to "I just want to know where we are" — no PRD, no RD, no QA, no full peaks-solo orchestration. Just read the existing CLI state and render a 1-screen summary.
+
+**This is a transparent wrapper.** The user does not stay in this skill — the status table is rendered, and control hands off (back to the user, or to `peaks-solo` if the user wants to act on the status).
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-status --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Read the current state
+
+Use only existing CLI primitives (no new commands). **Important contract note**: `peaks session list` does NOT support `--project` (verified by dogfood 2026-06-04); it returns all sessions globally. To scope to the current project, read `.peaks/.session.json` for the bound `sessionId`, then use `peaks session info <sid>` for the bound session's full state, and filter `peaks session list` output by `projectRoot` to find other sessions in the same project.
+
+```bash
+# 1. Active skill presence
+peaks skill presence --json
+
+# 2. The bound session id (from .peaks/.session.json — local read, no CLI)
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+
+# 3. The bound session's full state
+peaks session info "$sid" --json
+
+# 4. All sessions globally (then post-filter to current project)
+peaks session list --json
+# Note: this returns all sessions across all projects; the wrapper filters by
+# matching `projectRoot` against the bound session's `projectRoot` to show only
+# the sessions for THIS project. Sessions from other projects are ignored.
+
+# 5. Per-request role state (PRD / RD / QA / TXT for the bound project)
+peaks project dashboard --project <repo> --json
+
+# 6. Per-request detail (if a specific rid is in flight)
+peaks request show <rid> --role rd --project <repo> --json
+peaks request show <rid> --role qa --project <repo> --json
+```
+
+All 6 calls are read-only. Total cost: sub-second. (The original draft said "5 calls"; the corrected count is 6 because the post-filter step is now explicit.)
+
+## Step 2: Render the status table
+
+Compact 1-screen format:
+
+```
+=== peaks-solo status ===
+Session:   2026-06-04-session-b60252
+Active:    peaks-solo (mode: full-auto, gate: qa-validation)
+Workspace: /Users/yuanyuan/.../peaks-cli/.peaks/2026-06-04-session-b60252
+
+| Role | State          | Artifact                |
+|------|----------------|-------------------------|
+| PRD  | handed-off     | prd/requests/003.md     |
+| RD   | qa-handoff     | rd/requests/003.md      |
+| QA   | running        | qa/requests/003.md      |
+| TXT  | (not started)  | -                       |
+
+QA verdict: pending
+Last activity: 2026-06-04T17:00:00.000Z (12 min ago)
+Standards: 5/5 existing (no delta)
+Health: skill-doctor 35/35 pass
+```
+
+If the session is fresh (no in-flight slice), render a different layout:
+
+```
+=== peaks-solo status ===
+Session: 2026-06-04-session-b60252
+Active:  peaks-solo (mode: full-auto, gate: startup)
+Workspace: /Users/yuanyuan/.../peaks-cli/.peaks/2026-06-04-session-b60252
+
+No in-flight slice. Ready for a new request.
+Health: skill-doctor 35/35 pass
+```
+
+## Step 3: Ask the user what to do next
+
+| Option | What it does |
+|---|---|
+| Continue from the current gate | Hand off to `peaks-solo` with the gate already at the current state. Existing artifacts are preserved. |
+| Open a new slice in this session | Keep the workspace, treat the current request as a new slice (new `rid`). |
+| Just summarize and exit | No further action; the user will decide later. |
+
+## Step 4: Hand off (if user picked option 1 or 2)
+
+Re-assert `peaks-solo` presence so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <matching-gate>
+```
+
+Then yield control.
+
+## Hard rules (do NOT skip)
+
+- **Never write to `.peaks/<sid>/`.** This skill is read-only on the workspace; it only reads existing CLI state.
+- **Never add a new `peaks <cmd>`.** Use only the existing read-only CLI primitives: `peaks skill presence`, `peaks session list`, `peaks session info`, `peaks project dashboard`, `peaks request show`. **Note**: `peaks session list` does not support `--project`; filter its output by `projectRoot` post-hoc.
+- **Never auto-progress the workflow.** The status table is informational only. The user chooses what to do via `AskUserQuestion`. Never silent about what comes next — always present the 3 options.
+- **Never expose sensitive data in the table.** Do NOT include full PRD bodies, full tech-doc bodies, or any test code in the table. Just state names, paths, and counts.
+
+## Anti-patterns (do NOT do)
+
+- Do NOT run `peaks workspace init` on the real session. The wrapper is read-only.
+- Do NOT run `peaks request transition` (would change state). The wrapper is informational only.
+- Do NOT write the status to a file (e.g. `.peaks/<sid>/status.md`). The user can see it in the chat; persisting it adds noise to the workspace.
+- Do NOT block on slow CLI calls. The 5 read-only calls are sub-second each. If any takes >5s, fail fast and report the slow command.
+
+## Cross-references
+
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent.
+- `peaks-solo-resume` (P2.1) and `peaks-solo-test` (P2.2) are the sibling wrappers. `peaks-solo-resume` focuses on workflow-state introspection + resume decision; `peaks-solo-status` is the broader 5-CLI snapshot. The two are complementary, not redundant.
+- The "read 5 CLI primitives, render 1 table" pattern is intentionally minimal — the wrapper does NOT add a new status-introspection CLI command (would violate the dev-preference.md "default-no on new CLI" rule).

package/skills/peaks-solo-test/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: peaks-solo-test
+description: Run the project's test suite on the current repo and report results. Use when the user says "run the tests", "跑一下 test", "跑测试", or invokes `/peaks-solo-test` directly. Runs `pnpm vitest run` (or the project's equivalent test command), captures pass/fail counts and any failures, and surfaces a compact summary. Triggers on `/peaks-solo-test`, "跑一下 test", "跑测试", "run the tests", "test now".
+---
+
+# Peaks-Cli Solo Test (wrapper)
+
+Peaks-Cli Solo Test is a thin wrapper that runs the project's test suite on the current repo and reports results. It is the answer to "I just want to see if the tests pass" — no PRD, no RD, no QA, no full peaks-solo orchestration. Just `pnpm vitest run` and a compact summary.
+
+**This is a transparent wrapper.** The user does not stay in this skill — the test command runs, the result is summarized, and control hands off (back to the user, or to `peaks-solo` if the user wants to act on the result).
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-test --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Detect the project's test command
+
+The Peaks-Cli project standard is `pnpm vitest run` (per `vitest.config.ts` + `package.json` scripts). For other project types, check the package.json scripts first. If the user explicitly named a different command (e.g. "跑 `pnpm test` not vitest"), use that.
+
+```bash
+# Default for peaks-cli itself + most TS projects with vitest
+pnpm vitest run
+```
+
+For non-vitest projects (jest, mocha, pytest, etc.), the wrapper respects the project's existing test command. If the user says "run jest" or "run pytest", use that. Do NOT silently default to vitest.
+
+## Step 2: Run the test suite
+
+```bash
+# Run with a reasonable timeout (5 min default; override for slow suites)
+timeout 300 pnpm vitest run 2>&1 | tail -100
+```
+
+Capture both stdout and stderr. If the exit code is 0, tests passed. If non-zero, tests failed or the command errored out.
+
+## Step 3: Summarize the result
+
+Render a compact summary:
+
+- **Test files**: `X passed, Y failed, Z skipped` (from the `Test Files  X passed (Y)` line)
+- **Tests**: `A passed, B failed, C skipped` (from the `Tests  A passed | B skipped (C)` line)
+- **Wall-clock**: the `Duration` line
+- **Failures (if any)**: the first 5-10 failing test names + their failure messages, in priority order (the `FAIL` lines in the test output)
+
+Then ask the user what they want to do next via `AskUserQuestion`:
+
+| Option | What it does |
+|---|---|
+| Show the full failure list | Print all failing test names + messages (not just the first 5-10) |
+| Open a slice to fix the failures | Hand off to `peaks-solo` with the failing tests as the slice's "acceptance criteria" |
+| Just summarize and exit | No further action; the user will decide later |
+
+## Step 4: Hand off (if user picked option 2)
+
+Re-assert `peaks-solo` presence so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate qa-validation
+```
+
+Then yield control. The user's next message will land in `peaks-solo` (in QA validation phase, since the failing tests are the validation surface).
+
+## Hard rules (do NOT skip)
+
+- **Never silently fix test failures.** The user must choose what to do via `AskUserQuestion`. Silently "auto-fix"ing a failing test would mask the failure.
+- **Never modify source code in this skill.** This is a wrapper. The actual fix (if the user wants one) is `peaks-solo`'s job.
+- **Never add a new `peaks <cmd>`.** Use only existing primitives: `peaks skill presence:set`, `peaks project memories`, `peaks workspace init` (for the handoff), `peaks request transition` (if going to QA-validation). The actual test command is the project's existing test runner, not a `peaks <cmd>`.
+- **Never trust the test runner's exit code as the only signal.** Some failures print partial success (e.g. 100 passed + 1 failed); the wrapper must show the failures, not just say "exit 0".
+
+## Anti-patterns (do NOT do)
+
+- Do NOT run `peaks workspace init` on the real session. The wrapper is read-only on the workspace; it only reads the test results, not the workflow state.
+- Do NOT write to `.peaks/<sid>/`. This skill is read-only on the workspace.
+- Do NOT auto-fail the workflow if the tests fail. The user gets a summary + 3 options; the workflow state is unchanged.
+- Do NOT run `pnpm vitest run --watch` or any interactive mode. The wrapper captures the output as a one-shot run; interactive mode would block the orchestrator.
+
+## Cross-references
+
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent.
+- `peaks-solo-resume` (sibling wrapper, P2.1) is the workflow-state introspection variant; `peaks-solo-test` is the test-execution variant.
+- The "harness a project-native test runner" pattern is intentionally minimal — the wrapper should NOT add a new CLI for running tests (would violate the dev-preference.md "default-no on new CLI" rule + the user's explicit ask for "skill-first, CLI-auxiliary").