peaks-cli 1.0.0

package/scripts/watch.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { watch as nodeWatch } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { installBundledSkills } from './install-skills.mjs';
+
+export const WATCHED_INPUTS = ['src', 'schemas', 'skills'];
+export const DEFAULT_BUILD_COMMAND = ['pnpm', ['run', 'build']];
+
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function getErrorCode(error) {
+  return typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+}
+
+function isAbortError(error) {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+function isMissingPathError(error) {
+  return getErrorCode(error) === 'ENOENT';
+}
+
+export function runCommand(command, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let child;
+
+    try {
+      child = spawn(command, args, { stdio: 'inherit', ...options });
+    } catch (error) {
+      rejectPromise(error);
+      return;
+    }
+
+    let settled = false;
+    const settle = (handler, value) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      handler(value);
+    };
+
+    child.once('error', (error) => {
+      if (options.signal?.aborted || isAbortError(error)) {
+        const abortError = new Error(`${command} ${args.join(' ')} was aborted`);
+        abortError.name = 'AbortError';
+        settle(rejectPromise, abortError);
+        return;
+      }
+
+      settle(rejectPromise, error);
+    });
+
+    child.once('close', (code, signal) => {
+      if (code === 0) {
+        settle(resolvePromise);
+        return;
+      }
+
+      if (options.signal?.aborted || signal) {
+        const abortError = new Error(`${command} ${args.join(' ')} was aborted`);
+        abortError.name = 'AbortError';
+        settle(rejectPromise, abortError);
+        return;
+      }
+
+      settle(rejectPromise, new Error(`${command} ${args.join(' ')} failed with exit code ${code}`));
+    });
+  });
+}
+
+export async function collectDirectories(root) {
+  const directories = [];
+  const visited = new Set();
+
+  async function visit(directory) {
+    if (visited.has(directory)) {
+      return;
+    }
+
+    visited.add(directory);
+
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (isMissingPathError(error)) {
+        return;
+      }
+
+      throw error;
+    }
+
+    directories.push(directory);
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      await visit(join(directory, entry.name));
+    }
+  }
+
+  await visit(root);
+  return directories;
+}
+
+export function createDirectoryTreeWatcher(root, options = {}) {
+  const watch = options.watch ?? nodeWatch;
+  const collect = options.collectDirectories ?? collectDirectories;
+  const onChange = options.onChange ?? (() => {});
+  const watchers = new Map();
+  let refreshPromise = null;
+  let refreshRequested = false;
+  let isClosed = false;
+
+  const syncWatchers = async () => {
+    const directories = await collect(root);
+    const nextDirectories = new Set(directories);
+
+    for (const [directory, watcher] of watchers) {
+      if (nextDirectories.has(directory)) {
+        continue;
+      }
+
+      watcher.close();
+      watchers.delete(directory);
+    }
+
+    for (const directory of directories) {
+      if (watchers.has(directory)) {
+        continue;
+      }
+
+      const watcher = watch(directory, () => {
+        onChange();
+        void requestRefresh();
+      });
+      watchers.set(directory, watcher);
+    }
+  };
+
+  const requestRefresh = async () => {
+    if (isClosed) {
+      return;
+    }
+
+    refreshRequested = true;
+    if (refreshPromise) {
+      return refreshPromise;
+    }
+
+    refreshPromise = (async () => {
+      do {
+        refreshRequested = false;
+        await syncWatchers();
+      } while (refreshRequested && !isClosed);
+    })();
+
+    try {
+      await refreshPromise;
+    } finally {
+      refreshPromise = null;
+    }
+  };
+
+  return {
+    async start() {
+      await requestRefresh();
+    },
+    async close() {
+      isClosed = true;
+
+      if (refreshPromise) {
+        await refreshPromise.catch(() => undefined);
+      }
+
+      for (const watcher of watchers.values()) {
+        watcher.close();
+      }
+
+      watchers.clear();
+    }
+  };
+}
+
+export async function rebuildOnce(options = {}) {
+  const runner = options.runner ?? runCommand;
+  const installer = options.installer ?? installBundledSkills;
+  const [command, args] = options.command ?? DEFAULT_BUILD_COMMAND;
+
+  await runner(command, args, options.runOptions);
+  return installer(options.installOptions);
+}
+
+export function createWatchMode(options = {}) {
+  const inputs = options.inputs ?? WATCHED_INPUTS;
+  const createTreeWatcher = options.createTreeWatcher ?? createDirectoryTreeWatcher;
+  const runner = options.runner ?? runCommand;
+  const installer = options.installer ?? installBundledSkills;
+  const collectDirectoriesFn = options.collectDirectories ?? collectDirectories;
+  const watch = options.watch ?? nodeWatch;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const debounceMs = options.debounceMs ?? 150;
+  const treeWatchers = [];
+  let debounceTimer;
+  let isBuilding = false;
+  let hasQueuedRebuild = false;
+  let isClosed = false;
+  let currentAbortController = null;
+  let currentBuildPromise = null;
+
+  const writeStatus = (message) => stdout.write(`[peaks watch] ${message}\n`);
+  const writeError = (message) => stderr.write(`[peaks watch] ${message}\n`);
+
+  const rebuild = async (reason) => {
+    if (isClosed) {
+      return;
+    }
+
+    if (isBuilding) {
+      hasQueuedRebuild = true;
+      return currentBuildPromise ?? undefined;
+    }
+
+    isBuilding = true;
+    currentAbortController = new AbortController();
+    writeStatus(`${reason}: rebuilding dist and relinking skills`);
+
+    const buildPromise = (async () => {
+      try {
+        const result = await rebuildOnce({
+          runner,
+          installer,
+          runOptions: { signal: currentAbortController.signal }
+        });
+        const installed = result?.installed?.length ?? 0;
+        const skipped = result?.skipped?.length ?? 0;
+        writeStatus(`ready (${installed} skills linked, ${skipped} skipped)`);
+      } catch (error) {
+        if (isAbortError(error)) {
+          return;
+        }
+
+        writeError(`rebuild failed: ${getErrorMessage(error)}`);
+      } finally {
+        isBuilding = false;
+        currentAbortController = null;
+      }
+    })();
+
+    currentBuildPromise = buildPromise;
+
+    try {
+      await buildPromise;
+    } finally {
+      currentBuildPromise = null;
+      if (!isClosed && hasQueuedRebuild) {
+        hasQueuedRebuild = false;
+        await rebuild('queued change');
+      }
+    }
+  };
+
+  const scheduleRebuild = () => {
+    if (isClosed) {
+      return;
+    }
+
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      debounceTimer = undefined;
+      void rebuild('change detected');
+    }, debounceMs);
+  };
+
+  const closeTreeWatchers = async () => {
+    for (const treeWatcher of [...treeWatchers].reverse()) {
+      await treeWatcher.close();
+    }
+
+    treeWatchers.length = 0;
+  };
+
+  return {
+    async start() {
+      await rebuild('initial');
+
+      if (isClosed) {
+        return;
+      }
+
+      let startupFailed = false;
+      try {
+        for (const input of inputs) {
+          if (isClosed) {
+            break;
+          }
+
+          const treeWatcher = createTreeWatcher(input, {
+            watch,
+            collectDirectories: collectDirectoriesFn,
+            onChange: scheduleRebuild
+          });
+          treeWatchers.push(treeWatcher);
+          await treeWatcher.start();
+
+          if (isClosed) {
+            break;
+          }
+        }
+      } catch (error) {
+        startupFailed = true;
+        throw error;
+      } finally {
+        if (startupFailed || isClosed) {
+          await closeTreeWatchers();
+        }
+      }
+
+      if (!isClosed) {
+        writeStatus(`watching ${inputs.join(', ')}`);
+      }
+    },
+    async close() {
+      isClosed = true;
+
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = undefined;
+      }
+
+      if (currentAbortController) {
+        currentAbortController.abort();
+      }
+
+      await closeTreeWatchers();
+
+      if (currentBuildPromise) {
+        await currentBuildPromise.catch(() => undefined);
+      }
+    }
+  };
+}
+
+async function main() {
+  const watchMode = createWatchMode();
+  let shuttingDown = false;
+
+  const shutdown = async () => {
+    if (shuttingDown) {
+      return;
+    }
+
+    shuttingDown = true;
+
+    try {
+      await watchMode.close();
+      process.stdout.write('[peaks watch] stopped\n');
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`[peaks watch] ${getErrorMessage(error)}\n`);
+      process.exit(1);
+    }
+  };
+
+  process.once('SIGINT', () => void shutdown());
+  process.once('SIGTERM', () => void shutdown());
+
+  await watchMode.start();
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main().catch((error) => {
+    process.stderr.write(`[peaks watch] ${getErrorMessage(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/skills/peaks-prd/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: peaks-prd
+description: Product and requirement skill for Peaks. Use when a workflow needs PRD, refactor goals, non-goals, behavior preservation, acceptance criteria, product change proposals, or user-confirmable product artifacts.
+---
+
+# Peaks PRD
+
+Peaks PRD turns user intent into verifiable product artifacts.
+
+## Responsibilities
+
+- clarify goals and non-goals;
+- define behavior that must be preserved;
+- write acceptance criteria;
+- create refactor goal artifacts;
+- produce product-side intermediate artifacts for downstream RD and QA skills.
+
+## Refactor role
+
+For refactor workflows, avoid writing a full product PRD unless needed. Produce a focused refactor product package:
+
+- refactor goal;
+- non-goals;
+- preserved behavior;
+- acceptance criteria;
+- risk notes;
+- user confirmation record.
+
+## External capability guidance
+
+Use `peaks capabilities --source mcp-server --json` before recommending product or workflow methodology resources.
+
+- OpenSpec can structure spec-first product and engineering artifacts.
+- Superpowers can inform workflow methodology and artifact sequencing.
+- gstack can inform product-stack tradeoffs, but user goals and non-goals remain authoritative.
+- External methods are inspiration and governance inputs, not automatic executors.
+
+## Boundaries
+
+Do not implement code, run tests, install hooks, or modify runtime configuration. Use Peaks CLI reports and downstream artifacts instead.
+
+Reference: `references/workflow.md`.

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

@@ -0,0 +1,3 @@
+# artifact-contracts.md
+
+This reference documents artifact-contracts.md for peaks-prd.

package/skills/peaks-prd/references/command-migration.md

@@ -0,0 +1,3 @@
+# command-migration.md
+
+This reference documents command-migration.md for peaks-prd.

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

@@ -0,0 +1,11 @@
+# Peaks PRD Workflow
+
+For refactors, produce a focused product artifact package rather than a full product PRD.
+
+## Required refactor artifacts
+
+- refactor goal;
+- non-goals;
+- behavior preservation;
+- acceptance criteria;
+- user confirmation record.

package/skills/peaks-qa/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: peaks-qa
+description: QA and verification skill for Peaks. Use when a workflow needs unit-test coverage evidence, regression matrices, baseline reports, validation reports, acceptance checks, or refactor verification gates.
+---
+
+# Peaks QA
+
+Peaks QA proves that planned changes are protected and accepted.
+
+## Responsibilities
+
+- inspect unit-test coverage evidence;
+- define regression matrices;
+- produce baseline reports;
+- define acceptance checks for refactor slices;
+- validate that implementation satisfies the spec;
+- record residual risks.
+
+## Project standards preflight
+
+Before QA verification in a code repository, call the Peaks CLI:
+
+- `peaks standards init --project <path> --dry-run`
+- `peaks standards update --project <path> --dry-run`
+
+If the repo needs a first-time standards bundle, treat `standards init` as the creation path. If `CLAUDE.md` already exists, use `standards update` to decide whether Peaks can append a managed block or should only return review suggestions. Apply only when write authorization exists; otherwise keep the CLI output as the preflight next action. Do not hand-write standards file mutations inside the skill.
+
+## Refactor role
+
+For refactors, QA must be involved before implementation. It defines the regression and acceptance surface, then verifies the same surface after implementation.
+
+## External capability guidance
+
+Use `peaks capabilities --source access-repo --json` before recommending browser or validation MCPs.
+
+- Playwright MCP can support controlled browser and E2E validation after the target app and environment are approved.
+- Chrome DevTools MCP can support console, network, accessibility, and performance inspection for QA evidence.
+- Agent Browser can support browser walkthroughs, but never submit forms, purchase, delete, or mutate authenticated state without explicit confirmation.
+- If browser automation is unavailable, fall back to local Playwright, screenshots, logs, and manual regression steps.
+
+## Boundaries
+
+Do not own product scope or implementation. Do not modify runtime configuration.
+
+Reference: `references/regression-gates.md`.

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

@@ -0,0 +1,3 @@
+# artifact-contracts.md
+
+This reference documents artifact-contracts.md for peaks-qa.

package/skills/peaks-qa/references/command-migration.md

@@ -0,0 +1,3 @@
+# command-migration.md
+
+This reference documents command-migration.md for peaks-qa.

package/skills/peaks-qa/references/regression-gates.md

@@ -0,0 +1,16 @@
+# Peaks QA Regression Gates
+
+QA must be involved before refactor implementation.
+
+## Required evidence
+
+- coverage report or reason for blocking;
+- regression matrix;
+- baseline report;
+- acceptance checks;
+- validation report;
+- residual risk report.
+
+## Refactor threshold
+
+UT coverage below 95%, missing coverage, or unverifiable coverage blocks refactor implementation.

package/skills/peaks-rd/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: peaks-rd
+description: Research and development skill for Peaks. Use for engineering analysis, refactor planning, project scanning, code standards, unit-test coverage gates, implementation contracts, task graphs, and RD handoffs. Always use this for Peaks refactor workflows.
+---
+
+# Peaks RD
+
+Peaks RD owns engineering analysis, implementation planning, and refactor execution contracts.
+
+## Responsibilities
+
+- scan the current project before changes;
+- prefer existing project standards over built-in language standards;
+- enforce the 95% UT coverage refactor gate;
+- split broad refactors by minimal functional slices;
+- generate refactor options, risk matrix, rollback plan, and task graph preview;
+- implement only after strict specs and confirmations exist.
+
+## Project standards preflight
+
+Before RD planning or implementation work in a code repository, call the Peaks CLI:
+
+- `peaks standards init --project <path> --dry-run`
+- `peaks standards update --project <path> --dry-run`
+
+If `CLAUDE.md` is missing, treat creation as the preferred path. If `CLAUDE.md` already exists, use `standards update` to decide whether to append a managed index block or surface review-only suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
+
+## Refactor hard gates
+
+If a request is refactor, cleanup, architecture adjustment, module split, or technical debt work:
+
+1. scan project structure and existing standards;
+2. locate or run UT coverage;
+3. block implementation unless coverage is >= 95%;
+4. treat missing, unknown, or unverifiable coverage as failing;
+5. generate intermediate artifacts before implementation;
+6. call or consume peaks-prd and peaks-qa artifacts even in direct RD mode;
+7. require strict slice spec before each slice;
+8. require 100% acceptance for the slice;
+9. require code and intermediate artifacts to be committed before continuing.
+
+## External capability guidance
+
+Use `peaks capabilities --source access-repo --json` and `peaks capabilities --source mcp-server --json` as the source of truth before recommending external resources.
+
+- Context7 can support current library/API documentation lookup when the map says it is available or the user authorizes MCP access.
+- SearchCode can support external code discovery only after confirming the query will not expose secrets or private code.
+- everything-claude-code, Claude Code Best Practice, mattpocock/skills, and andrej-karpathy-skills are RD guidance or review references; apply project-local conventions first.
+- OpenSpec can shape spec-first RD artifacts, but Peaks PRD/RD/QA gates remain authoritative.
+- GitNexus remains a future proxied repository-intelligence boundary; do not install or run it directly.
+
+## Boundaries
+
+Do not bypass PRD/QA artifacts. Do not install hooks, agents, MCP, or settings. Ask the Peaks CLI to handle runtime side effects.
+
+Reference: `references/refactor-workflow.md`.

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

@@ -0,0 +1,3 @@
+# artifact-contracts.md
+
+This reference documents artifact-contracts.md for peaks-rd.

package/skills/peaks-rd/references/command-migration.md

@@ -0,0 +1,3 @@
+# command-migration.md
+
+This reference documents command-migration.md for peaks-rd.

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

@@ -0,0 +1,31 @@
+# Peaks RD Refactor Workflow
+
+## Standards loading order
+
+1. Existing project standards.
+2. Peaks language standard packs.
+3. Peaks universal engineering baseline.
+4. Reviewer judgment.
+
+## Hard gates
+
+- UT coverage must be >= 95% before implementation.
+- Missing, unknown, unverifiable, or failing coverage blocks refactoring.
+- 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.
+- Each slice must pass 100% acceptance.
+- Code and intermediate artifacts must be committed before the next slice.
+
+## Required artifacts
+
+- `project-scan.md`
+- `engineering-constitution.md`
+- `coverage-report.md`
+- `feature-slice-map.md`
+- `refactor-options.md`
+- `risk-matrix.md`
+- `rollback-plan.md`
+- `slice-spec.md`
+- `validation-report.md`
+- `commit-required.md`

package/skills/peaks-sc/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: peaks-sc
+description: Source control, sync, and change-control skill for Peaks. Use when a workflow needs change impact, artifact retention, commit boundaries, GitHub artifact repository pointers, sync state, or rollback evidence.
+---
+
+# Peaks SC
+
+Peaks SC records how product, RD, QA, code, and artifacts move together.
+
+## Responsibilities
+
+- produce change-impact artifacts;
+- record commit boundaries;
+- ensure intermediate artifacts are retained with code changes;
+- track artifact repository pointers;
+- 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.
+
+## Project memory backup
+
+Project `.claude/memory` is the primary source for durable project memory. At approved checkpoints, use `peaks memory sync --project <path> --workspace <artifact-workspace> --apply` to back up the full project memory directory into the artifact repository workspace; do not treat the artifact backup as a second writable memory source.
+
+## Boundaries
+
+Do not implement code or test logic. Do not create GitHub repositories directly from the skill body. Use the Peaks CLI artifact commands.
+
+Reference: `references/artifact-retention.md`.

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

@@ -0,0 +1,3 @@
+# artifact-contracts.md
+
+This reference documents artifact-contracts.md for peaks-sc.

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

@@ -0,0 +1,14 @@
+# Artifact Retention
+
+Each refactor slice must retain code and intermediate artifacts together.
+
+## Required retained artifacts
+
+- PRD goal and acceptance artifacts;
+- RD slice spec and task graph;
+- QA coverage and validation reports;
+- TXT context capsule and lessons;
+- SC change impact and sync state;
+- commit boundary report.
+
+The next slice cannot start until code and intermediate artifacts are committed or the user explicitly stops the run.

package/skills/peaks-sc/references/command-migration.md

@@ -0,0 +1,3 @@
+# command-migration.md
+
+This reference documents command-migration.md for peaks-sc.