peaks-cli 1.0.2 → 1.0.4

package/skills/peaks-rd/references/refactor-workflow.md

@@ -9,13 +9,17 @@
 
 ## Hard gates
 
-- UT coverage must be >= 95% before implementation.
+- UT coverage must be >= 95% before refactor implementation.
 - Missing, unknown, unverifiable, or failing coverage blocks refactoring.
+- For non-refactor development in legacy repos with pre-existing low coverage, require focused unit-test coverage for new or changed code.
 - Coverage success only allows analysis and spec generation.
 - Broad refactors must be split into minimal functional slices.
 - Each slice needs a strict verifiable spec before implementation.
+- Existing `openspec/` repos require OpenSpec change artifacts before non-trivial implementation.
+- Each implemented slice must pass unit tests, code review, and security review before RD dry-run.
+- The post-check dry-run runs after tests, CR, and security review, not before them.
 - Each slice must pass 100% acceptance.
-- Code and intermediate artifacts must be committed before the next slice.
+- Code changes and intermediate artifacts must be traceable in local `.peaks/<session-id>/` storage before the next slice; commit or sync artifacts only when explicitly authorized.
 
 ## Required artifacts
 
@@ -27,5 +31,9 @@
 - `risk-matrix.md`
 - `rollback-plan.md`
 - `slice-spec.md`
+- `openspec-change-paths.md` when OpenSpec is required
+- `code-review-report.md`
+- `security-review-report.md`
+- `post-check-dry-run.md`
 - `validation-report.md`
-- `commit-required.md`
+- `retention-boundary.md` documenting local `.peaks/<session-id>/` traceability and any explicitly authorized commit/sync requirement

package/skills/peaks-sc/SKILL.md

@@ -11,13 +11,21 @@ Peaks SC records how product, RD, QA, code, and artifacts move together.
 
 - produce change-impact artifacts;
 - record commit boundaries;
-- ensure intermediate artifacts are retained with code changes;
-- track artifact repository pointers;
+- ensure intermediate artifacts are retained locally first;
+- track artifact repository pointers when external sync or git retention is explicitly authorized;
 - record sync state and rollback points.
 
 ## Refactor role
 
-Each refactor slice must leave a traceable commit boundary containing code changes and PRD/RD/QA/TXT intermediate artifacts.
+Each refactor slice must leave a traceable local artifact boundary in `.peaks/<session-id>/` by default. A git commit boundary containing code changes and PRD/RD/QA/TXT intermediate artifacts is required only when the user or active profile explicitly authorizes committing artifacts.
+
+## GStack integration
+
+Use gstack as a concrete source-control and release workflow reference for the `Ship → Reflect` stages:
+
+- map `/ship` and `/land-and-deploy` concepts to Peaks commit boundaries, sync state, rollback points, and artifact retention;
+- map checkpoint discipline to traceable code-plus-artifact slices;
+- do not create PRs, merge, deploy, or mutate shared state unless the active Peaks workflow and user confirmation explicitly allow it.
 
 ## Project memory backup
 

package/skills/peaks-sc/references/artifact-retention.md

@@ -1,6 +1,6 @@
 # Artifact Retention
 
-Each refactor slice must retain code and intermediate artifacts together.
+Each refactor slice must retain code and intermediate artifacts together, but the default retention target is local `.peaks/<session-id>/` storage rather than git.
 
 ## Required retained artifacts
 
@@ -9,6 +9,6 @@ Each refactor slice must retain code and intermediate artifacts together.
 - QA coverage and validation reports;
 - TXT context capsule and lessons;
 - SC change impact and sync state;
-- commit boundary report.
+- retention-boundary report, including commit details only when commits were explicitly authorized.
 
-The next slice cannot start until code and intermediate artifacts are committed or the user explicitly stops the run.
+The next slice cannot start until code changes and intermediate artifacts are traceable in local `.peaks/<session-id>/` storage. Commit or sync those artifacts only after explicit user confirmation or an active profile that clearly authorizes git/external retention.

package/skills/peaks-solo/SKILL.md

@@ -31,6 +31,53 @@ Peaks Solo must not silently:
 
 Use the Peaks CLI for runtime side effects.
 
+## GStack integration
+
+Use gstack as a concrete orchestration reference for the full `Think → Plan → Build → Review → Test → Ship → Reflect` loop:
+
+- map gstack role reviews to Peaks PRD, RD, UI, QA, SC, and TXT artifacts;
+- map `/autoplan`-style review pipelines to Peaks mode selection and role handoffs;
+- map `/retro` to Peaks TXT final context and reusable lessons;
+- preserve Peaks confirmation gates, artifact workspace boundaries, and role separation instead of delegating orchestration to gstack commands.
+
+For frontend workflows, Peaks Solo must ensure QA uses `gstack/browse/dist/browse` for real browser end-to-end validation. Prefer headed or handoff mode when visual/UI behavior matters, and verify that a visible browser actually opened when user login or visual inspection is required. If browser validation reports page, console, network, render, or visible UI errors, route the workflow back to RD for fixes before QA can pass.
+
+## Local intermediate artifact workspace
+
+Peaks Solo should establish or discover a local `.peaks/<session-id>/` workspace before role handoffs. Store PRD/RD/UI/QA/SC/TXT intermediate artifacts there by default, with role subdirectories such as `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
+
+Do not default to a git-backed local artifact repository, external artifact sync, or automatic commits for intermediate artifacts. Only include `.peaks` artifacts in git, sync them elsewhere, or create external artifact repositories after explicit user confirmation or an active profile that clearly authorizes it.
+
+## End-to-end code workflow gates
+
+When Peaks Solo coordinates development in a code repository, keep this order explicit:
+
+1. standards preflight;
+2. PRD/RD scope and spec artifacts;
+3. OpenSpec change artifacts for non-trivial work when `openspec/` already exists or the user approves adding it;
+4. RD implementation slices;
+5. unit tests for new/changed behavior, with focused new-code coverage accepted for legacy low-coverage repos;
+6. code review and security review with CRITICAL/HIGH issues fixed before progression; marked-blocked CRITICAL/HIGH issues only allow a blocked handoff, not QA or completion;
+7. RD post-check dry-run;
+8. QA validation, including API checks and `gstack/browse/dist/browse` browser E2E for frontend;
+9. QA security and performance checks plus validation report;
+10. TXT final handoff capsule, including reusable skill-usage lessons when the workflow revealed new habits or preferences.
+
+Do not close the Solo workflow as complete if RD or QA artifacts lack required test, review, security, dry-run, OpenSpec, browser, report, or performance evidence. Do not close a workflow that changed Peaks skill behavior without a `peaks-txt` capsule capturing reusable usage lessons and artifact paths.
+
+## Mode selection
+
+When the user invokes Peaks Solo without explicitly selecting an execution profile, use `AskUserQuestion` before orchestration starts. Present the recommended full-auto path as the first/default option, and give every option a practical description so users can choose quickly.
+
+Offer these profiles unless the active command narrows the valid set:
+
+1. **Full auto (Recommended, Solo profile)** — Peaks handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
+2. **Assisted** — Peaks proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
+3. **Swarm** — Peaks maximizes safe parallel role/worker execution for larger RD or QA workloads while keeping reducer validation and artifact boundaries explicit.
+4. **Strict** — Peaks uses the most conservative gates: explicit confirmations, strict slice specs, coverage evidence, QA acceptance, and commit boundaries before continuing.
+
+If the user already names a profile, do not ask again unless the request crosses a risk boundary or the named profile conflicts with required Peaks gates.
+
 ## Project standards preflight
 
 Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks CLI:
@@ -54,7 +101,13 @@ It must enforce the shared refactor red lines:
 4. split broad refactors into minimal functional slices;
 5. require strict verifiable specs before each slice;
 6. require 100% acceptance for each slice;
-7. require code and intermediate artifacts to be committed before the next slice.
+7. require code changes and intermediate artifacts to be traceable in local `.peaks/<session-id>/` storage before the next slice; commit or sync artifacts only when explicitly authorized.
+
+## Completion handoff
+
+After a Peaks Solo workflow reaches final validation, refresh the project-local standards from the current scan-backed evidence before the handoff closes. Route project-local `CLAUDE.md` and project-local `.claude/rules/**` writes through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. If write authorization exists, apply an incremental merge of scan-backed changes into existing project-local standards. Preserve existing hand-maintained content unless the user explicitly confirms deletion or rewrite. If write authorization or the CLI path is unavailable, keep the standards output as the next action instead of writing it.
+
+Use Peaks TXT for the final, blocked, or interrupted handoff capsule. Keep that capsule compact: current mode, validated decisions, artifact paths, standards deltas, open questions, and next action. Do not restate the full workflow log when a short handoff plus artifact links will do.
 
 ## Optional capabilities
 

package/skills/peaks-solo/references/artifact-contracts.md

@@ -1,3 +1,7 @@
 # artifact-contracts.md
 
 This reference documents artifact-contracts.md for peaks-solo.
+
+Default local artifact root: `.peaks/<session-id>/` with role subdirectories `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
+
+Solo coordinates artifact paths and handoff completeness. Keep artifacts local by default. Do not commit, sync, or move them to a git-backed artifact repository unless explicitly authorized.

package/skills/peaks-solo/references/refactor-mode.md

@@ -14,8 +14,8 @@
 8. Ask the user to confirm option, scope, and accepted risks.
 9. Execute one minimal functional slice at a time.
 10. Require 100% acceptance for the slice.
-11. Coordinate `peaks-sc` for artifact retention and commit boundary.
-12. Refuse the next slice until code and intermediate artifacts are committed.
+11. Coordinate `peaks-sc` for local artifact retention and the `.peaks/<session-id>/sc/retention-boundary.md` boundary.
+12. Refuse the next slice until code changes and intermediate artifacts are traceable in local `.peaks/<session-id>/` storage; commit or sync only after explicit user or profile authorization.
 
 ## Runtime resources
 

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

@@ -9,6 +9,24 @@ Peaks Solo is a facade over role skills. It keeps the workflow moving without ab
 - Swarm: multiple subagents work in parallel when the CLI-managed profile is enabled.
 - Strict: hook/profile guarded mode for high-risk work.
 
+## Required code workflow evidence
+
+A code workflow is not complete until Solo has linked or summarized:
+
+1. standards preflight;
+2. PRD/RD scope and OpenSpec artifacts when required;
+3. RD implementation evidence;
+4. unit-test evidence for new or changed behavior;
+5. code-review evidence;
+6. security-review evidence;
+7. RD post-check dry-run evidence;
+8. QA API validation when applicable;
+9. QA `gstack/browse/dist/browse` browser E2E evidence for frontend projects, preferably with headed/handoff visible-browser confirmation;
+10. QA security, performance, and validation report evidence;
+11. TXT handoff capsule.
+
+For legacy repositories with pre-existing low UT coverage, do not require historical coverage cleanup as part of an unrelated change, but do require focused coverage evidence for the new or changed code.
+
 ## Capability discovery
 
 Before using `find-skills`, explain the benefit and token cost unless the active profile permits automatic discovery.

package/skills/peaks-txt/SKILL.md

@@ -12,12 +12,39 @@ Peaks TXT compresses workflow context into portable, role-specific artifacts.
 - generate context capsules;
 - slice context for PRD, RD, QA, UI, and SC consumers;
 - record decisions, assumptions, discarded options, and staleness conditions;
-- archive lessons from refactor slices.
+- archive lessons from refactor slices;
+- capture reusable Peaks skill usage habits and workflow lessons for future sessions.
 
 ## Refactor role
 
 For refactors, create initial context before RD analysis and final context after validation and artifact retention.
 
+## Compaction-safe outputs
+
+When used alone or when a workflow needs portable artifacts that must survive session compaction, end with a short structured capsule: mode, validated decisions, artifact paths, standards deltas, open questions, and next action. Prefer links or paths over long narrative. Do not duplicate the full workflow log when a compact capsule is enough.
+
+## GStack integration
+
+Use gstack as a concrete context and reflection workflow reference for the `Reflect` stage:
+
+- map `/retro` summaries to Peaks lessons, discarded options, and staleness conditions;
+- map documentation-release ideas to compact downstream context for PRD, RD, QA, UI, and SC;
+- keep durable memory writes behind Peaks memory extraction and user-approved persistence.
+
+## Skill-usage learning capture
+
+When a Peaks workflow reveals a reusable skill usage habit, orchestration preference, artifact convention, browser/login rule, or repeated failure mode, capture it through Peaks TXT before the session ends.
+
+Default output path: `.peaks/<session-id>/txt/skill-usage-lessons.md` or the Peaks CLI-provided local artifact workspace. Keep this local by default and do not commit or sync it unless the user or active profile explicitly authorizes persistence.
+
+Each entry should include:
+
+- lesson or rule;
+- why it exists;
+- affected skills;
+- how future PRD/RD/UI/QA/SC/Solo workflows should apply it;
+- whether it is stable enough for `.claude/memory` extraction.
+
 ## Project memory guidance
 
 When a skill artifact contains reusable project facts, decisions, rules, or constraints, mark only the stable extract with:

package/skills/peaks-txt/references/artifact-contracts.md

@@ -1,3 +1,7 @@
 # artifact-contracts.md
 
 This reference documents artifact-contracts.md for peaks-txt.
+
+Default local artifact path: `.peaks/<session-id>/txt/`.
+
+TXT artifacts should include compact context capsules, reusable skill-usage lessons, stable memory extraction blocks when approved, staleness notes, and next-session pointers. Keep artifacts local by default. Do not commit or sync them unless explicitly authorized.

package/skills/peaks-txt/references/context-capsule.md

@@ -11,10 +11,11 @@ A context capsule is the smallest durable context needed by downstream roles.
 - discarded options;
 - risks;
 - role-specific slices;
+- skill-usage lessons and workflow habits worth reusing;
 - staleness conditions.
 
 Do not dump full conversations into downstream artifacts.
 
 ## Durable project memory
 
-Only stable and reusable project facts should be marked for memory extraction. Use `.claude/memory` as the project-local primary source, and let Peaks SC sync that directory to the artifact repository at checkpoints.
+Only stable and reusable project facts should be marked for memory extraction. Use `.claude/memory` as the project-local primary source. Keep TXT capsules and skill-usage lessons in local `.peaks/<session-id>/txt/` by default; let Peaks SC sync or commit them only after explicit authorization or an active profile that clearly permits it.

package/skills/peaks-ui/SKILL.md

@@ -19,10 +19,35 @@ Peaks UI handles experience, interaction, visual direction, and UI-specific refa
 
 Only engage when the refactor affects UI, interaction, styling, page structure, design system, or frontend user behavior.
 
+## GStack integration
+
+Use gstack as a concrete design-review workflow reference for the `Plan → Review → Test` UI stages:
+
+- map design review concepts to Peaks UX flow, page-state, interaction, and visual constraint artifacts;
+- map browser walkthrough concepts to UI regression seeds when runtime validation is approved;
+- keep accessibility, performance, and product-specific visual direction as Peaks UI acceptance inputs.
+
+For frontend work, especially full-auto mode, prefer `gstack/browse/dist/browse` in headed or handoff mode to inspect the running page or prototype before accepting the UI direction. Verify that a visible browser actually opened when visual review matters. Capture visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA.
+
+## Full-auto visual quality path
+
+When Peaks UI is used in full-auto frontend design, default to the curated taste path instead of generic component generation:
+
+1. use `awesome-design-md` as the visual reference source for layout, composition, rhythm, and atmosphere;
+2. use `taste-skill` or the local `design-taste-frontend` skill as the critique lens for anti-template, typography, color, density, motion, and interaction quality;
+3. choose a specific style direction before implementation, such as editorial, bento, Swiss, luxury, retro-futurist, glass, or product-specific system UI;
+4. define design dials before generating UI: design variance, motion intensity, visual density, typography pair, palette, and interaction feel;
+5. reject centered stock heroes, default card grids, unmodified shadcn/library defaults, AI purple-blue gradients, generic three-card feature rows, and safe gray-on-white pages without a point of view;
+6. require loading, empty, error, hover, focus, active, and responsive states for meaningful surfaces;
+7. browser-check the result with `gstack/browse/dist/browse` and iterate until the UI looks intentional, memorable, and product-specific.
+
+Full-auto Peaks UI output must include a short taste report: visual direction, references used, rejected generic patterns, browser observations, remaining design risks, and the next visual iteration if the page is not yet good enough.
+
 ## External capability guidance
 
 Use `peaks capabilities --json` before recommending design, browser, or UI reference resources.
 
+- In full-auto frontend mode, prefer the `awesome-design-md` + `taste-skill`/`design-taste-frontend` combination before shadcn/ui or generic component-library output.
 - shadcn/ui, React Bits, awesome-design-md, taste-skill, and ui-ux-pro-max-skill are UI references; do not treat unreviewed generated UI as finished design.
 - Chrome DevTools MCP and Agent Browser can support runtime UI inspection only after the user approves the app target.
 - Figma Context MCP and Penpot require user-authorized design access and must not persist tokens or private design data in project artifacts.

package/skills/peaks-ui/references/workflow.md

@@ -2,10 +2,26 @@
 
 Use Peaks UI only when refactor scope affects user-facing behavior, interaction, visual structure, design systems, or page states.
 
+## Full-auto frontend design path
+
+Use this path before generating or accepting frontend UI:
+
+1. Pull visual direction from `awesome-design-md` style references or equivalent curated design markdown.
+2. Apply `taste-skill`/`design-taste-frontend` critique rules to set design variance, motion intensity, visual density, typography, palette, and interaction feel.
+3. Produce a concrete visual direction, not vague “clean modern” language.
+4. Reject generic AI UI tells: centered stock hero, uniform card grids, default shadcn/library styling, purple-blue gradients, three equal feature cards, generic placeholder copy, and static-only happy states.
+5. Require meaningful loading, empty, error, hover, focus, active, and responsive states.
+6. Use `gstack/browse/dist/browse` on the running page or prototype to inspect real browser output, preferably in headed or handoff mode when visual quality matters.
+7. If the browser view looks generic, visually weak, broken, inaccessible, or has console/runtime errors, return to design/RD and iterate before handing off to QA.
+
 ## Outputs
 
 - UX flow;
 - page state map;
+- visual direction with references;
+- design dials and rejected generic patterns;
 - interaction constraints;
+- `gstack/browse/dist/browse` browser observations when frontend output exists;
 - UI regression seeds;
-- accessibility notes.
+- accessibility notes;
+- taste report.