peaks-cli 1.3.2 → 1.3.4

package/dist/src/services/workspace/reconcile-service.d.ts

@@ -144,6 +144,42 @@ export declare function migrateOldRuntimeState(projectRoot: string): {
         message: string;
     }>;
 };
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/<sid>/system/subagent-progress.json`
+ *   - `.peaks/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export declare function migrateSubAgentState(projectRoot: string): {
+    migratedFiles: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+};
 /**
  * Top-level orchestrator. Wires migration (added in slice
  * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,

package/dist/src/services/workspace/reconcile-service.js

@@ -16,11 +16,20 @@
  * Pure hand-rolled; uses only node:fs, node:path, and the existing
  * session-manager helper for writing the binding. No new dependencies.
  */
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { getSessionIdCanonical, setCurrentSessionBinding } from '../session/session-manager.js';
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
 const META_FILE = 'session.json';
+// Sub-agent state file basenames (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+// The legacy location was `.peaks/<sid>/system/<filename>`; the canonical new
+// location is `.peaks/_sub_agents/<sid>/<filename>`. `migrateSubAgentState`
+// moves the two files between these homes on every `reconcileWorkspace` run.
+const SUB_AGENT_MIGRATION_FILES = [
+    'subagent-progress.json',
+    'progress-spawn.json'
+];
+const SUB_AGENTS_DIR = '_sub_agents';
 // As of slice 2026-06-05-peaks-runtime-layer these old paths are the
 // back-compat read-only fallbacks; the canonical new home is
 // `.peaks/_runtime/`. `migrateOldRuntimeState` moves them to the new
@@ -488,6 +497,89 @@ function copyDirRecursiveSync(src, dest) {
         }
     }
 }
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/<sid>/system/subagent-progress.json`
+ *   - `.peaks/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export function migrateSubAgentState(projectRoot) {
+    const root = resolve(projectRoot);
+    const newDir = join(root, '.peaks', SUB_AGENTS_DIR);
+    const migratedFiles = [];
+    const errors = [];
+    for (const session of discoverSessions(projectRoot)) {
+        const oldSystemDir = join(session.path, 'system');
+        if (!existsSync(oldSystemDir))
+            continue;
+        const newSessionDir = join(newDir, session.sessionId);
+        mkdirSync(newSessionDir, { recursive: true });
+        for (const fname of SUB_AGENT_MIGRATION_FILES) {
+            const oldPath = join(oldSystemDir, fname);
+            const newPath = join(newSessionDir, fname);
+            if (!existsSync(oldPath))
+                continue;
+            if (existsSync(newPath)) {
+                // New path is authoritative; remove stale old file.
+                try {
+                    rmSync(oldPath, { force: true });
+                }
+                catch { /* best effort */ }
+                continue;
+            }
+            try {
+                try {
+                    renameSync(oldPath, newPath);
+                }
+                catch (renameError) {
+                    // Cross-device or locked-file fallback: copy + unlink.
+                    copyFileSync(oldPath, newPath);
+                    unlinkSync(oldPath);
+                }
+                migratedFiles.push(join('.peaks', session.sessionId, 'system', fname));
+            }
+            catch (error) {
+                errors.push({
+                    path: oldPath,
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        // R-2 guard: only remove the legacy system/ dir when it has zero
+        // remaining files (the user might have unrelated content there).
+        try {
+            const remaining = readdirSync(oldSystemDir);
+            if (remaining.length === 0) {
+                rmdirSync(oldSystemDir);
+            }
+        }
+        catch { /* best effort */ }
+    }
+    return { migratedFiles, errors };
+}
 /**
  * Top-level orchestrator. Wires migration (added in slice
  * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,
@@ -503,11 +595,19 @@ export function reconcileWorkspace(options) {
     // before that read means the new path is the only path observed by
     // `getSessionIdCanonical` after this call returns.
     const migration = migrateOldRuntimeState(projectRoot);
-    const migrateErrors = migration.errors.map((e) => ({
-        kind: 'migrate',
-        path: e.path,
-        message: e.message
-    }));
+    const subAgentMigration = migrateSubAgentState(projectRoot);
+    const migrateErrors = [
+        ...migration.errors.map((e) => ({
+            kind: 'migrate',
+            path: e.path,
+            message: e.message
+        })),
+        ...subAgentMigration.errors.map((e) => ({
+            kind: 'migrate',
+            path: e.path,
+            message: e.message
+        }))
+    ];
     const sessions = discoverSessions(projectRoot);
     const activeSkillSessionId = readActiveSkillSessionId(projectRoot);
     const canonical = pickCanonicalSession(sessions, activeSkillSessionId);
@@ -575,6 +675,7 @@ export function reconcileWorkspace(options) {
         apply,
         repointed,
         migratedFiles: migration.migratedFiles,
+        subAgentStateMigrated: subAgentMigration.migratedFiles.length,
         errors: [...migrateErrors, ...deletionResult.errors],
         changeMarker,
         systemCleaned

package/dist/src/services/workspace/reconcile-types.d.ts

@@ -65,6 +65,18 @@ export type ReconcileResult = {
      * consumers can ignore this field.
      */
     migratedFiles: string[];
+    /**
+     * Count of legacy per-session sub-agent state files moved from
+     * `.peaks/<sid>/system/{subagent-progress,progress-spawn}.json` into
+     * `.peaks/_sub_agents/<sid>/` during this reconcile run.
+     *
+     * Added in slice 2026-06-06-sub-agent-spawn-bug-and-decouple. The
+     * detailed list of moved files is not surfaced here (the count is
+     * what the CLI summary and QA test assert on); the underlying
+     * `migrateSubAgentState` helper returns the full path list for
+     * forensics. Additive — older consumers can ignore this field.
+     */
+    subAgentStateMigrated: number;
     /**
      * Errors encountered during the migration step. Each entry has a
      * `kind: 'migrate'` discriminator so consumers can tell migration

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.2";
+export declare const CLI_VERSION = "1.3.4";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.2";
+export const CLI_VERSION = "1.3.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -56,6 +56,7 @@
     "@colbymchenry/codegraph": "0.7.10",
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
+    "headroom-ai": "0.22.4",
     "ora": "^8.2.0",
     "shadcn": "4.7.0",
     "terminal-kit": "^3.1.2"

package/scripts/install-skills.mjs

@@ -363,6 +363,78 @@ function resolveProjectRoot(options) {
   return projectRoot ? resolve(projectRoot) : null;
 }
 
+/**
+ * Slice #011: Detect the installed IDE for the postinstall dispatch layer.
+ *
+ * Mirrors `src/services/ide/ide-detector.ts:detectInstalledIde` (cwd heuristic)
+ * but inlined here because `install-skills.mjs` is a plain `.mjs` script and
+ * cannot import the TS service at runtime. The dispatch:
+ *   - Look for `.claude`, `.trae`, `.codex`, `.cursor`, `.qoder`,
+ *     `.tongyi-lingma` in the project root in that insertion order
+ *     (matches the registry's adapter order in `src/services/ide/ide-registry.ts`).
+ *   - Returns the first match, or `null` if no adapter's directory is present.
+ *
+ * If the resolved IDE has no `skillInstall` declared (Trae in slice 1.3.2),
+ * the caller falls back to the legacy `~/.claude/{skills,output-styles}` path
+ * + emits a stderr warning. The dispatch is conservative: the env-var
+ * overrides `PEAKS_CLAUDE_SKILLS_DIR` / `PEAKS_CLAUDE_OUTPUT_STYLES_DIR`
+ * continue to work, and the legacy default is preserved.
+ */
+const IDE_DETECTION_DIRS = [
+  { id: 'claude-code', dir: '.claude' },
+  { id: 'trae', dir: '.trae' },
+  { id: 'codex', dir: '.codex' },
+  { id: 'cursor', dir: '.cursor' },
+  { id: 'qoder', dir: '.qoder' },
+  { id: 'tongyi-lingma', dir: '.tongyi-lingma' },
+];
+
+const IDE_SKILL_INSTALL_PROFILES = {
+  'claude-code': {
+    skillsDir: join(homedir(), '.claude', 'skills'),
+    outputStylesDir: join(homedir(), '.claude', 'output-styles'),
+    envVar: 'PEAKS_CLAUDE_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_CLAUDE_OUTPUT_STYLES_DIR',
+  },
+  'trae': null,
+  'codex': null,
+  'cursor': null,
+  'qoder': null,
+  'tongyi-lingma': null,
+};
+
+function detectInstalledIdeId(projectRoot) {
+  if (!projectRoot) return null;
+  for (const { id, dir } of IDE_DETECTION_DIRS) {
+    if (existsSync(join(projectRoot, dir))) {
+      return id;
+    }
+  }
+  return null;
+}
+
+function resolveIdeSkillInstallProfile(ideId) {
+  if (ideId === null) return null;
+  return IDE_SKILL_INSTALL_PROFILES[ideId] ?? null;
+}
+
+function warnUnverifiedIde(ideId, projectRoot) {
+  process.stderr.write(
+    `peaks install-skills: IDE '${ideId}' has no skillInstall profile declared; ` +
+      `falling back to the legacy Claude Code path (~/.claude/skills + ~/.claude/output-styles) ` +
+      `for project '${projectRoot}'. This is a slice #011 follow-up gap; ` +
+      `see .peaks/memory/ide-adapter-resource-profile-framework.md.\n`
+  );
+}
+
+function warnNoIdeDetected(projectRoot) {
+  process.stderr.write(
+    `peaks install-skills: no IDE detected in '${projectRoot ?? '(project root unknown)'}'; ` +
+      `installing to the legacy Claude Code path (~/.claude/skills + ~/.claude/output-styles). ` +
+      `Set PEAKS_CLAUDE_SKILLS_DIR / PEAKS_CLAUDE_OUTPUT_STYLES_DIR to override.\n`
+  );
+}
+
 function writeMergedConfig(configPath, label, defaults, writeConfig) {
   const existing = readConfigFile(configPath, label);
   const next = { ...(existing === null ? defaults : mergeMissingConfigValues(existing, defaults)), version: defaults.version };
@@ -424,12 +496,37 @@ export function installProjectConfig(options = {}) {
 export function installBundledSkills(options = {}) {
   const packageRoot = resolvePackageRoot(options);
   const skillsRoot = join(packageRoot, 'skills');
-  const targetRoot = resolve(options.targetRoot ?? process.env.PEAKS_CLAUDE_SKILLS_DIR ?? join(homedir(), '.claude', 'skills'));
 
   if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
     return createInstallResult();
   }
 
+  // Slice #011: IDE-aware dispatch. Precedence (highest first):
+  //   1. explicit options.targetRoot            (test / hook override)
+  //   2. options.ideId skillInstall.skillsDir   (per-IDE dispatch)
+  //   3. PEAKS_CLAUDE_SKILLS_DIR env var        (legacy back-compat)
+  //   4. detected IDE's skillInstall.skillsDir  (auto-detect from projectRoot)
+  //   5. legacy default (~/.claude/skills)      (no-IDE fallback)
+  const projectRoot = resolveProjectRoot(options);
+  const detectedIdeId = detectInstalledIdeId(projectRoot);
+  const detectedProfile = resolveIdeSkillInstallProfile(detectedIdeId);
+
+  if (options.targetRoot === undefined && options.ideId === undefined && detectedProfile === null && detectedIdeId !== null) {
+    warnUnverifiedIde(detectedIdeId, projectRoot ?? '(project root unknown)');
+  }
+  if (options.targetRoot === undefined && options.ideId === undefined && detectedIdeId === null && projectRoot !== null) {
+    warnNoIdeDetected(projectRoot);
+  }
+
+  const profileSkillsDir = detectedProfile?.skillsDir ?? null;
+  const targetRoot = resolve(
+    options.targetRoot
+      ?? (options.ideId !== undefined ? resolveIdeSkillInstallProfile(options.ideId)?.skillsDir ?? null : null)
+      ?? process.env.PEAKS_CLAUDE_SKILLS_DIR
+      ?? profileSkillsDir
+      ?? join(homedir(), '.claude', 'skills')
+  );
+
   const installed = [];
   const skipped = [];
   mkdirSync(targetRoot, { recursive: true });
@@ -485,12 +582,25 @@ export function installBundledSkills(options = {}) {
 export function installBundledOutputStyles(options = {}) {
   const packageRoot = resolvePackageRoot(options);
   const outputStylesRoot = join(packageRoot, 'output-styles');
-  const targetRoot = resolve(options.targetRoot ?? process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR ?? join(homedir(), '.claude', 'output-styles'));
 
   if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(outputStylesRoot)) {
     return createInstallResult();
   }
 
+  // Slice #011: IDE-aware dispatch. Same precedence as installBundledSkills.
+  const projectRoot = resolveProjectRoot(options);
+  const detectedIdeId = detectInstalledIdeId(projectRoot);
+  const detectedProfile = resolveIdeSkillInstallProfile(detectedIdeId);
+
+  const profileOutputStylesDir = detectedProfile?.outputStylesDir ?? null;
+  const targetRoot = resolve(
+    options.targetRoot
+      ?? (options.ideId !== undefined ? resolveIdeSkillInstallProfile(options.ideId)?.outputStylesDir ?? null : null)
+      ?? process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR
+      ?? profileOutputStylesDir
+      ?? join(homedir(), '.claude', 'output-styles')
+  );
+
   const installed = [];
   const skipped = [];
   mkdirSync(targetRoot, { recursive: true });

package/skills/peaks-ide/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: peaks-ide
+description: Orchestrate peaks-cli's IDE-aware behavior (hooks + statusline + handle) for a user's specific IDE. Detects the current state (which IDE the user is on, what peaks has already installed), plans the install / switch / status / uninstall actions, and invokes the existing peaks CLI primitives. Triggers on `/peaks-ide`, "set up peaks for my IDE", "switch peaks to Trae", "what did peaks install", "uninstall peaks hooks". Sits between the user and `peaks hooks install` / `peaks statusline install` / `peaks hook handle` — those are the CLI primitives; this skill is the user-facing surface.
+---
+
+# Peaks-Cli IDE Setup (peaks-ide)
+
+`peaks-ide` is the **user-facing surface** for everything peaks-cli does that's IDE-aware. It does NOT introduce new CLI commands. It orchestrates the existing CLI primitives — `peaks hooks install`, `peaks statusline install`, `peaks hook handle` — based on the user's intent and the IDE the user is on.
+
+**Why this exists (dev-preference red line):** "skill is primary, CLI is auxiliary." The behavior that only an LLM in a skill prompt would use ("detect which IDE the user is on", "plan the migration steps", "ask the user before destructive actions") lives in this SKILL.md, not in a new `peaks <cmd>`. The CLI commands stay as atomic primitives the skill composes.
+
+**Slice #2 scope:** the first version supports Trae (alongside Claude Code, the only other adapter in slice #2's registry). Cursor / Codex / Qoder / Tongyi Lingma will land in slice #3+ — the skill will pick them up automatically because the underlying auto-detect (the `peaks project dashboard --json` flow internally calls `listAdapterIds()` via the `IdeRegistry`) registers them as the registry grows.
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-ide --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+The presence marker tells the global peaks status line that peaks-ide is orchestrating. The memory read pulls forward the slice #1 contract: `peaks <cmd> --project <path>` is the canonical project-root source; `process.env[adapter.envVar]` (e.g. `CLAUDE_PROJECT_DIR`, `TRAE_PROJECT_DIR`) is the env-var override for auto-detect.
+
+## Step 1: detect current state
+
+The skill's first move is to **read**, not to ask. Build a complete picture of the user's IDE environment before any AskUserQuestion.
+
+```bash
+# 1. What adapters are registered? (slice #2 ships with claude-code + trae)
+peaks project dashboard --project <repo> --json
+
+# 2. Is the user on Claude Code, Trae, or something else?
+#    Check the cwd for adapter-specific directories:
+ls -la <repo>/.claude 2>/dev/null && echo "claude-code detected"
+ls -la <repo>/.trae 2>/dev/null && echo "trae detected"
+
+# 3. Are peaks hooks already installed? For each candidate, read settings.json:
+#    claude: <root>/.claude/settings.json
+#    trae:   <root>/.trae/settings.json
+peaks hooks status --project <repo> --json 2>/dev/null
+peaks statusline status --project <repo> --json 2>/dev/null
+```
+
+The skill composes a 1-2 sentence **state summary** before asking anything:
+
+> "I see you're on **Trae** (`.trae/` exists in the project root). peaks hooks are **not installed** yet. peaks statusline is **not installed** either. The `peaks hook handle` runtime is available as a CLI primitive — you don't need to install it separately; what needs installing is the settings.json entries that point to it."
+
+The user gets a complete picture without having to answer any question. The next step only fires AskUserQuestion if intent is genuinely ambiguous.
+
+## Step 2: AskUserQuestion (only if intent is ambiguous)
+
+If the user typed `/peaks-ide` without context, the skill's intent is genuinely ambiguous. The four canonical intents are:
+
+| Option | What it does |
+|---|---|
+| First-time install | Run `peaks hooks install` + `peaks statusline install` for the detected IDE |
+| Switch to a different IDE | Detect current install, uninstall from old IDE, install on new IDE (e.g. Claude → Trae) |
+| Show current status | Just print the state summary from Step 1; no side effects |
+| Uninstall peaks hooks | Run `peaks hooks uninstall` + `peaks statusline uninstall` for the detected IDE |
+
+**Default option is "Show current status"** — the cheapest action, and the user gets useful output even if they didn't know what they wanted. AskUserQuestion is the ONLY place this skill asks anything. All destructive paths (Switch, Uninstall) gate on user confirmation here.
+
+## Step 3: plan & preview (dry-run)
+
+Before any side effect, the skill prints the exact CLI invocations it will run. This is the "see before you leap" step.
+
+```
+Plan: First-time install for Trae (.trae/ detected in project root)
+
+  1. peaks hooks install --project <repo>
+     → writes a beforeToolCall hook entry to <root>/.trae/settings.json
+       that points to `peaks hook handle --project "${TRAE_PROJECT_DIR}"`
+
+  2. peaks statusline install --project <repo>
+     → writes a statusLine field with command `peaks statusline`
+
+  3. (no third command — `peaks hook handle` is the runtime; once the
+     settings.json entries point to it, the user's Trae will invoke it
+     on every PreToolUse event)
+
+Verification: after install, re-run `peaks hooks status --project <repo>`
+             to confirm the entries are present.
+
+Proceed? (Y/n)
+```
+
+The plan MUST be human-readable. Don't run a side effect until the user confirms.
+
+## Step 4: execute
+
+For each step in the plan, invoke the CLI primitive. The skill does NOT call out to a hidden script — it runs the actual peaks CLI commands, so the user sees the same output they'd see typing the command themselves.
+
+```bash
+# Example: first-time Trae install
+peaks hooks install --project <repo>
+peaks statusline install --project <repo>
+
+# After each command, check the exit code. If non-zero, STOP and report
+# the failure to the user. The skill does NOT auto-rollback; the user
+# decides what to do next.
+```
+
+For destructive paths (Switch, Uninstall), the skill uses a **transactional pattern**: it captures the current state, runs the destructive CLI, then runs the install CLI; if any step fails, it reports the partial state and lets the user decide.
+
+## Step 5: audit log
+
+Every successful execution writes one JSON line to `.peaks/_runtime/<sid>/ide-onboard.log`:
+
+```json
+{"timestamp":"2026-06-06T19:55:00Z","intent":"first-time-install","detected_ide":"trae","cli_invocations":["peaks hooks install --project <repo>","peaks statusline install --project <repo>"],"outcome":"success","session_id":"2026-06-06-session-22f08c"}
+```
+
+The audit log is **machine-readable** (so `peaks project dashboard` can read it and surface "you installed peaks for Trae on 2026-06-06") and **human-readable** (so the user can `cat` it to see the install history). The skill does NOT write the log file itself — it delegates to `peaks project dashboard` (the canonical log writer, per the dev-preference red line "skill-first for workflow, CLI-backed for gates / side effects"). The audit log writer is a CLI primitive, not a per-skill helper; the skill body MUST NOT introduce a new `peaks <cmd>` for the log writer. The thin helper that writes the log is `scripts/peaks-ide-audit-log.mjs`; see [audit-log-helper.md](references/audit-log-helper.md) for its CLI surface and contract.
+
+## Boundaries
+
+`peaks-ide` may:
+
+- detect the current IDE (cwd + env var + settings.json)
+- ask the user via AskUserQuestion (Step 2 only)
+- preview the CLI invocations (Step 3)
+- execute existing peaks CLI commands (Step 4)
+- write a single line to the audit log (Step 5)
+
+`peaks-ide` must NOT:
+
+- introduce new `peaks <cmd>` CLI commands (dev-preference red line: "Default-no on new CLI commands")
+- bypass the user's confirmation on destructive paths (Switch / Uninstall)
+- write the settings.json directly (the CLI primitives own that)
+- run other peaks skills (peaks-solo, peaks-qa, etc.) — those are separate skills with their own scopes
+- handle multi-IDE scenarios in slice #2 (e.g. "I use Claude at work and Trae at home" — the registry is single-IDE per session; a future slice could add multi-IDE)
+
+## Reference: the CLI primitives the skill composes
+
+- `peaks hooks install` / `peaks hooks uninstall` / `peaks hooks status` — adapter-driven; auto-detects IDE from env / stdin / cwd
+- `peaks statusline install` / `peaks statusline uninstall` / `peaks statusline status` — same
+- `peaks hook handle` — the runtime handler; not installed, just invoked
+- `peaks project dashboard --json` — surfaces the current state summary
+- `peaks skill runbook` — surfaces the peaks-ide skill body for inspection
+
+## Next-step references
+
+- The slice #1 RD artifact at `.peaks/_runtime/<sid>/rd/requests/002-2026-06-06-peaks-ide-skeleton.md` documents the slim `IdeAdapter` shape that the skill is built on.
+- The slice #2 PRD at `.peaks/_runtime/<sid>/prd/requests/002-2026-06-06-trae-adapter-and-peaks-ide-skill.md` documents the 13 ACs this skill is part of.
+- The slice #2 RD artifact (in flight) documents the implementation contract.
+
+## Default runbook
+
+The skill is invoked as `/peaks-ide` or via the natural-language triggers listed in the frontmatter. The runbook is the body of this SKILL.md (steps 1-5 plus the boundaries and reference sections above); the runbook-service extracts the section between this `## Default runbook` heading and the next `##` heading.
+
+When the user types `/peaks-ide` (or "set up peaks for my IDE" / "switch peaks to Trae" / "what did peaks install" / "uninstall peaks hooks"), execute Steps 1 → 5 in order:
+
+1. **Skill presence (MANDATORY first action)**: `peaks skill presence:set peaks-ide --project <repo> --gate startup` and `peaks project memories --project <repo> --json` (load durable memory).
+2. **Detect current state** (Step 1 above): `peaks project dashboard --project <repo> --json` + `peaks hooks status --project <repo> --json` + `peaks statusline status --project <repo> --json` + `ls -la <repo>/.claude 2>/dev/null` + `ls -la <repo>/.trae 2>/dev/null`. Build a 1-2 sentence state summary.
+3. **AskUserQuestion** (Step 2 above, only if intent is ambiguous). Default option: "Show current status". Destructive paths (Switch, Uninstall) gate on user confirmation here.
+4. **Plan & preview** (Step 3 above): print the exact `peaks hooks install` / `peaks statusline install` invocations before running them. Wait for "Proceed? (Y/n)".
+5. **Execute** (Step 4 above): run the `peaks hooks install` / `peaks statusline install` (or uninstall / status) commands. Stop on non-zero exit. Do not auto-rollback.
+6. **Audit log** (Step 5 above): delegate the JSONL write to `peaks project dashboard` (the canonical log writer; per the dev-preference red line, the skill MUST NOT introduce a new CLI primitive for the log writer).
+
+CLI primitives the skill composes (per the "Reference" section above): `peaks skill presence:set`, `peaks project memories`, `peaks project dashboard`, `peaks hooks install` / `uninstall` / `status`, `peaks statusline install` / `uninstall` / `status`, `peaks hook handle`, `peaks skill runbook`. The skill does NOT introduce any new `peaks <cmd>` command.

package/skills/peaks-ide/references/audit-log-helper.md

@@ -0,0 +1,52 @@
+---
+name: peaks-ide-audit-log-helper
+description: Thin Node helper that writes a single JSONL line to `.peaks/audit/peaks-ide-<UTC-date>.log`. Reachable from the peaks-ide SKILL.md Step 5 escape hatch. NOT a `peaks <cmd>` CLI primitive (slice #2 closeout + dev-preference red line).
+---
+
+# peaks-ide audit log helper
+
+The peaks-ide skill's Step 5 (`audit log`) delegates the JSONL write to
+`scripts/peaks-ide-audit-log.mjs`. The helper is a thin Node script, not a
+new `peaks <cmd>`, and is the single source of truth for the audit log
+shape (machine + human readable, one JSON object per line).
+
+## Why a thin helper, not a CLI primitive
+
+Per `.peaks/memory/peaks-ide-skill-ac-10-audit-log-writer-is-a-thin-helper-not-a-separate-cli-primitive.md`
+(slice #2 closeout), the audit log writer is reachable from the skill's
+Step 5 escape hatch but is NOT a new top-level `peaks <cmd>`. The
+`peaks project dashboard` command reads the log via the `audit` scan; the
+helper writes the log. The dev-preference red line "Default-no on new CLI
+commands" still applies — if the audit-trail becomes critical in a future
+slice, the helper can be promoted to a CLI primitive at that point.
+
+## CLI surface
+
+```
+node scripts/peaks-ide-audit-log.mjs --project <repo> --event <name> --adapter <id> [--ok true|false] [--detail <json>] [--dry-run]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--project <path>` | yes | Target project root (parent of `.peaks/`) |
+| `--event <name>` | yes | Event identifier (`install`, `statusline`, `hook-handle`, ...) |
+| `--adapter <id>` | yes | Adapter id (`claude-code`, `trae`, ...) |
+| `--ok <bool>` | no, default `true` | Outcome flag — `false` to record a failure |
+| `--detail <json>` | no | Free-form JSON object attached to the entry |
+| `--dry-run` | no | Print the would-be line; do not write |
+
+## Log line shape
+
+```json
+{"timestamp":"2026-06-07T16:00:00.000Z","event":"install","adapter":"trae","ok":true}
+```
+
+The log file path is `<projectRoot>/.peaks/audit/peaks-ide-<UTC-date>.log`
+and is gitignored per the repo root `.gitignore` (`.peaks/audit/`).
+
+## Contract pinned by tests
+
+`tests/unit/skills/peaks-ide/audit-log-helper.test.ts` pins 4 sub-cases
+(per AC-5): helper is at the documented path, write emits one JSONL line
+with `timestamp + event + adapter + ok`, the log path is in `.gitignore`,
+and `--dry-run` returns the would-be line without writing.