@yeison.restrepo.r/code-conductor 1.23.0

package/lib/installer/settings.mjs

@@ -0,0 +1,77 @@
+import { readFileSync, writeFileSync, copyFileSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+
+const FINGERPRINT = 'verbosity-remind.sh';
+const MAX_MALFORMED_BACKUPS = 5;
+
+function utcStamp(d) {
+  // Date.toISOString() is ALWAYS UTC (trailing Z). Strip the separators and the
+  // fractional millis: 2026-07-05T12:34:56.789Z -> 20260705T123456Z. Fixed width,
+  // so lexical filename order == chronological order (drives pruneMalformedBackups).
+  return d.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+export function verbosityHookCommand(home) {
+  // Normalize backslashes to forward slashes: the command is executed by `bash`
+  // (Git Bash/WSL on Windows), which treats `\` as an escape char, so a native
+  // Windows path would break. Forward slashes are valid on every platform and keep
+  // the stored command byte-stable, which is what the idempotency check compares.
+  const hookPath = join(home, '.claude', 'hooks', 'verbosity-remind.sh').replace(/\\/g, '/');
+  return `bash ${hookPath}`;
+}
+
+function entryHasCommand(entry, predicate) {
+  return entry && Array.isArray(entry.hooks) && entry.hooks.some(h => h && predicate(h));
+}
+
+function backupMalformed(settingsPath, now) {
+  const dst = `${settingsPath}.malformed-backup.${utcStamp(now)}`;
+  copyFileSync(settingsPath, dst);
+  pruneMalformedBackups(settingsPath);
+}
+
+export function pruneMalformedBackups(settingsPath, keep = MAX_MALFORMED_BACKUPS) {
+  const dir = dirname(settingsPath);
+  const prefix = `${basename(settingsPath)}.malformed-backup.`;
+  const backups = readdirSync(dir).filter(n => n.startsWith(prefix)).sort();
+  for (const n of backups.slice(0, Math.max(0, backups.length - keep))) {
+    try { unlinkSync(join(dir, n)); } catch { /* best effort */ }
+  }
+}
+
+export function mergeVerbosityHook(settingsPath, hookCmd, now = new Date()) {
+  // A missing settings.json (ENOENT) is not an error: initialize a fresh, empty
+  // config object and let the merge create the file. The existsSync check plus
+  // the ENOENT catch guard against both the plain-missing case and a TOCTOU
+  // delete between the check and the read.
+  let raw = '{}';
+  if (existsSync(settingsPath)) {
+    try { raw = readFileSync(settingsPath, 'utf8'); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+  // A zero-byte or whitespace-only file is NOT malformed — it is an uninitialized
+  // config. Treat it as an empty object and merge (matching install.sh, which starts
+  // from {} on an empty file). Only genuine non-empty invalid JSON triggers a backup.
+  if (raw.trim() === '') raw = '{}';
+  let obj;
+  try { obj = JSON.parse(raw); } catch { backupMalformed(settingsPath, now); return { status: 'malformed-skipped' }; }
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    backupMalformed(settingsPath, now);
+    return { status: 'malformed-skipped' };
+  }
+  if (typeof obj.hooks !== 'object' || obj.hooks === null || Array.isArray(obj.hooks)) obj.hooks = {};
+  let arr = Array.isArray(obj.hooks.UserPromptSubmit) ? obj.hooks.UserPromptSubmit : [];
+
+  if (arr.some(e => entryHasCommand(e, h => h.command === hookCmd))) return { status: 'idempotent-skip' };
+
+  arr = arr.filter(e => !entryHasCommand(e, h => typeof h.command === 'string' && h.command.includes(FINGERPRINT)));
+  arr.push({ matcher: '', hooks: [{ type: 'command', command: hookCmd }] });
+  obj.hooks.UserPromptSubmit = arr;
+  // Enforce 2-space indentation (matches install.sh's JSON.stringify(d,null,2) and the
+  // bundled settings.json) rather than detecting/preserving the user's indent width —
+  // one canonical format keeps diffs stable and the merge deterministic. The `+ '\n'`
+  // appends the single trailing newline POSIX text files expect (and that the bundled
+  // settings.json already ends with). Explicit utf8 encoding.
+  writeFileSync(settingsPath, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+  return { status: 'merged' };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@yeison.restrepo.r/code-conductor",
+  "version": "1.23.0",
+  "description": "A spec-first, token-efficient Claude Code configuration and installer CLI.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yeisonrestrepo/code-conductor.git"
+  },
+  "type": "module",
+  "bin": {
+    "code-conductor": "bin/code-conductor.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "global/",
+    "skills/",
+    "project-template/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.0.0",
+    "vitest": "^3.0.0"
+  }
+}

package/project-template/.claude/commands/cc-debug.md

@@ -0,0 +1,42 @@
+---
+description: "(Conductor) Systematically diagnose and fix a bug"
+---
+
+## Phase 0 — Skill activation
+
+Before doing anything else, invoke both skills in order:
+
+```
+Skill({ skill: "subagent-driven-development", args: "$ARGUMENTS" })
+Skill({ skill: "critical-review" })
+```
+
+`subagent-driven-development` delegates investigation to sub-agents (graph query + git log — no inline file reads). `critical-review` Phase 2 RESILIENCE check then runs on the proposed fix before it is applied — confirm the fix doesn't introduce a silent failure or new boundary condition. The fix must pass Phase 3 self-correction before being committed. End with `[VALIDATION]`.
+
+---
+
+Characterize the problem before investigating:
+
+**Symptom:** [what is observed]
+**Expected:** [what should happen]
+**Reproduction:** [exact steps to reproduce]
+**Frequency:** [always / intermittent / only under condition X]
+**Context:** [environment, recent changes, logs]
+
+List 2–4 hypotheses ordered by probability. Present them and confirm which to investigate first before touching any code.
+
+For visual bugs or UI flow problems, activate Playwright MCP:
+"This looks like a visual/UI issue. I'll use Playwright MCP to inspect it — confirm?"
+
+**Investigation:**
+- Use grep to locate relevant code — never read whole files
+- Read only the sections that match the hypothesis
+- Check git log for recent changes to the area
+
+**Report:**
+- Root cause: [file:line]
+- Why it happens: [explanation]
+- Impact: [what else could be affected]
+- Proposed fix: [exact change]
+
+Apply the fix only after the developer confirms. After fixing, suggest a test that would have caught this bug.

package/project-template/.claude/commands/cc-docs.md

@@ -0,0 +1,49 @@
+---
+description: "(Conductor) Audit and update project documentation"
+---
+
+Audit existing docs first:
+- Run: `grep -r "TODO\|FIXME\|@deprecated" src/ --include="*.{ts,js,py,java,go,rs}" -l`
+- Check if public functions and classes already have doc comments
+- Identify the highest-impact gaps (public API, core modules)
+
+**Inline doc format by language:**
+
+TypeScript/JavaScript — JSDoc:
+```typescript
+/**
+ * Finds a user by their unique identifier.
+ * Returns null when no matching user exists — callers must handle this case.
+ */
+function getUserById(id: string): User | null { ... }
+```
+
+Python — docstrings:
+```python
+def get_user_by_id(user_id: str) -> User | None:
+    """
+    Find a user by their unique identifier.
+
+    Returns None when no matching user exists — callers must handle this case.
+    """
+```
+
+Java — JavaDoc:
+```java
+/**
+ * Finds a user by their unique identifier.
+ * Returns {@code Optional.empty()} when no matching user exists.
+ */
+Optional<User> getUserById(String id);
+```
+
+Go — GoDoc:
+```go
+// GetUserByID returns the user with the given ID.
+// Returns ErrNotFound if no matching user exists.
+func GetUserByID(ctx context.Context, id string) (User, error) { ... }
+```
+
+**Rule:** Document WHY (non-obvious behavior, side effects, callers' responsibilities), not WHAT (the function name already says that).
+
+Preview all doc changes before writing to files. Show a diff of what will be added.

package/project-template/.claude/commands/cc-implement.md

@@ -0,0 +1,164 @@
+---
+description: "(Conductor) Execute implementation tasks from an approved plan"
+---
+
+## Phase entry - Resume Read
+
+Before doing anything else, restore any stored context for the current commit by running `scripts/resume-read.mjs`. It resolves the current git hash, prefers a valid DB snapshot (`conductor-db get-snapshot`), falls back to the `.claude/memory/session-snapshot.json` handoff file, and prints a `RESUME_HIT` block on a hit / nothing on a miss. Capture its stdout **and** its exit code with the canonical per-platform form (each first probes for `node` and treats its absence as a clean miss, never an error):
+
+- **Unix / Git Bash:**
+  ```sh
+  if command -v node >/dev/null 2>&1; then
+    resume_out="$(node scripts/resume-read.mjs 2>>.conductor/last-write.log)"; resume_rc=$?
+  else resume_rc=3; resume_out=""; fi
+  ```
+- **PowerShell:**
+  ```powershell
+  if (Get-Command node -ErrorAction SilentlyContinue) {
+    $__eap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
+    if (Test-Path variable:PSNativeCommandUseErrorActionPreference) {
+      $__nap = $PSNativeCommandUseErrorActionPreference; $PSNativeCommandUseErrorActionPreference = $false
+    }
+    try {
+      $resume_out = node scripts/resume-read.mjs 2>> .conductor/last-write.log; $resume_rc = $LASTEXITCODE
+    } catch { $resume_rc = 3; $resume_out = "" }
+    finally {
+      $ErrorActionPreference = $__eap
+      if (Test-Path variable:__nap) { $PSNativeCommandUseErrorActionPreference = $__nap }
+    }
+  } else { $resume_rc = 3; $resume_out = "" }
+  ```
+
+Branch on `resume_rc` - **only `0` and `4` are meaningful; every other code proceeds fresh:**
+
+- **`0`** → parse the captured block and adopt it as this phase's starting context, then echo one banner to the user: `> Resumed from stored snapshot @ <commit> (phase: <phase>)`, appending ` (checkpoint prose available)` when the block reports `prose: available`. Parsing (the command owns normalization): split on `\n`; strip a trailing `\r` from every line; drop leading/trailing wholly-blank lines; require `lines[0].trim() === 'RESUME_HIT'` (anything else = miss); `key: value` lines split on the first `': '` (both sides trimmed); the `pending:` block is every subsequent `^\s*-\s+` line up to the first blank line or EOF, each item trimmed. Unknown keys are ignored. In PowerShell, `node …` binds `string[]` for multi-line output - normalize with `$lines = @($resume_out)`; a `$null`/empty capture with `resume_rc = 3` is a miss.
+- **`4`** → **operational halt.** Do not run this phase's normal work. Emit exactly: `SNAP_INVALID: corrupt handoff at .claude/memory/session-snapshot.json - inspect or remove it, then re-run.` and enter standby awaiting user action. The corrupt file is left on disk (the script did not delete it).
+- **`3` or any other code** → **proceed fresh** (clean miss, bypass, degrade, absent `node`, or any unexpected runtime code). Ignore the capture.
+
+`resume-read.mjs` writes its own trace lines to `.conductor/last-write.log` via `appendFileSync`; the `2>>` redirect above only sinks the incidental exit-4 halt reason away from the UI - it is not the trace channel.
+
+---
+
+Read `.claude/memory/project.md` before starting any task.
+
+## Surgical Plan State Ritual
+
+Execute all plan tasks using the 5-step surgical ritual below. **Do not read the full plan file.**
+
+### Checkbox State Protocol
+
+| Symbol | Meaning |
+|--------|---------|
+| `[ ]` | Pending |
+| `[>]` | In-progress (pre-flipped before execution begins) |
+| `[X]` | Complete |
+| `[!]` | Failed; halt immediately |
+
+The Grep locator targets only `[ ]` states. `[>]`, `[X]`, and `[!]` are invisible to the locator.
+
+### String Rules
+
+**Comparison normalization** (Steps 2 and 3 — used only to decide if strings match, never as `old_string`):
+1. Strip leading/trailing ASCII whitespace (space, tab)
+2. Strip `\r`
+3. Strip Unicode invisible characters: `​`, ``, `‌`, `‍`
+
+**`old_string` construction** (Steps 3 and 5 — the actual string passed to `Edit`):
+- Take the Read result verbatim; strip trailing whitespace and `\r` only
+- Preserve all leading whitespace (indentation)
+- Do NOT strip Unicode invisibles
+
+### Step 1: Locate
+
+Run `Grep` with:
+- `pattern`: `\[ \] \[T-\d{3,}(-[A-Z0-9]+)*\]`
+- `path`: active plan file path (resolved from session context; never the workspace root)
+- `head_limit: 20`
+- `offset`: total results examined so far in this scan loop (starts at 0)
+
+**Fallback**: if `offset` is unsupported, replace the loop with a single `head_limit: 200` Grep.
+
+**Unicode note**: the pattern assumes clean ASCII `[ ]` (U+0020 space only between brackets). Task lines with Unicode invisible characters within the checkbox brackets will not be matched; this condition is prevented by the ASCII-only generation rule in `cc-plan.md` (Task 3).
+
+From the returned batch, apply dependency evaluation:
+- **Eligible**: all declared prerequisites carry `[X]`
+- **Transiently blocked** (`[ ]` prerequisite): skip; advance offset and re-run Grep
+- **Stalled** (`[>]` prerequisite): halt with `PREREQUISITE_IN_PROGRESS`; report the in-progress task ID; do not skip to unrelated tasks
+- **Permanently blocked** (`[!]` prerequisite): halt with `DEPENDENCY_FAILED`; report the failed prerequisite ID
+
+**Scan loop cap**: 10 Grep iterations maximum (<=200 tasks). If the cap is reached with no eligible task, halt with `SCAN_LIMIT_EXCEEDED`; list all blocked tasks and their unmet dependencies.
+
+If Grep returns no `[ ]` matches and `offset = 0`: output a completion summary and stop. If Grep returns no `[ ]` matches and `offset > 0`: halt with `SCAN_LIMIT_EXCEEDED`; all pending tasks are blocked (do not output a completion summary).
+
+### Step 2: Verify
+
+`Read` the active plan file with `offset: N-1, limit: 1` (N = 1-based line number from Step 1).
+
+Apply Comparison Normalization to both the Read result and the Grep match:
+- Normalized match → proceed to Step 3 using the Read result for `old_string` construction
+- Normalized mismatch → line drift; discard N and return to Step 1
+
+**Drift cap**: after 5 consecutive drift mismatches, halt with `VERIFY_DRIFT_EXCEEDED`.
+
+### Step 3: Pre-flip
+
+Assert uniqueness: run `Grep` for the exact task ID — for task `[T-001-A]`, use pattern `\[T-001-A\]` (the closing `\]` prevents sub-task prefix matches without requiring PCRE2). Scope to the active plan file. Confirm match count = 1. If count ≠ 1, halt and report the ID for manual resolution.
+
+Construct `old_string` using the `old_string` construction rule. Use `Edit` to replace `[ ]` with `[>]`.
+
+**Pre-flip retry cap**: if `Edit` reports `old_string` not found, return to Step 1. After 3 consecutive failures on the same task ID: run `Grep` for the task ID pattern scoped to the active plan file → `Read` the matched line (`offset: N-1, limit: 1`) → construct `old_string` from the Read result verbatim (trailing whitespace and `\r` stripped, regardless of current checkbox state) → construct `new_string` by replacing only the **first** `[_]` pattern (where `_` is any single character) with `[!]`, preserving all other brackets in the line → apply `Edit`. Then halt with a pre-flip failure report.
+
+### Step 4: Execute
+
+Carry out the task described on that line.
+
+### Step 5: Post-flip
+
+Construct `old_string` from the pre-flip line with `[ ]` replaced by `[>]` (the state after Step 3). Apply the `old_string` construction rule. Use `Edit` to replace:
+- `[>]` → `[X]` on success
+- `[>]` → `[!]` on failure
+
+On `[!]`: proceed to Step 6 to record the failure state, then halt with a failure report. Post-flip Edit no-match (unexpected `[>]` absence) → halt immediately for manual resolution; do not proceed to Step 6.
+
+### Step 6: Hook
+
+Runs after both success (`[X]`) and failure (`[!]`) paths. Record the task's final state to the local cache, best-effort:
+
+1. Probe `node --version`. If it is missing or below `22.5.0`, skip the cache write (the `node:sqlite` engine needs `>= 22.5`); the plan file remains authoritative.
+2. Decide how to launch so that an unrecognized flag can never fatally abort Node at startup. Probe with throwaway children, in order:
+   a. **No flag first:** run `node --no-warnings -e "require('node:sqlite')"`. Exit 0 means `node:sqlite` is stable on this Node — launch the recorder **without** `--experimental-sqlite`.
+   b. **Flag second:** else run `node --experimental-sqlite --no-warnings -e "require('node:sqlite')"`. Exit 0 means the flag is needed and recognized — launch the recorder **with** `--experimental-sqlite --no-warnings`.
+   c. **Neither:** else skip the cache write. Both a too-old Node and a future Node that removed/renamed the flag land here.
+
+   Each probe is a disposable child; a non-zero exit — including a fatal `bad option: --experimental-sqlite` from a Node that does not recognize the flag — is caught and simply advances to the next branch. The fatal startup error is therefore always contained inside a probe whose failure is expected; it never propagates and never aborts the hook.
+3. Launch the chosen form, from the repo root, with the active plan file path, the task ID, and the just-written state character (`X` or `!`):
+
+   `node <chosen-flags> scripts/conductor-db.mjs record "<plan_file>" "<task_id>" "<state>"`
+
+   All three arguments **must** be wrapped in double quotes exactly as shown. A repository path can contain spaces (e.g. `/Users/me/My Projects/repo/docs/plan.md`); unquoted, the shell word-splits it into several argv entries and the recorder sees `!== 3` positionals, silently rejecting a legitimate write. `--no-warnings` (in both probe and launch) suppresses Node's `ExperimentalWarning: SQLite is an experimental feature` line so it never pollutes hook stderr; it does not affect the recorder's own `CONDUCTOR_DB:` diagnostics (those are direct `process.stderr` writes, not process warnings).
+
+   The recorder self-initializes `.conductor/cache.db`, upserts the row, and exits 0 on every path. If the launch fails for any reason (permission error, unexpected abort), it is non-fatal: log a warning and continue. The plan file is the authoritative state record.
+
+After the hook: if the task state is `[!]`, halt with the failure report from Step 5.
+
+### Repeat from Step 1.
+
+### Error Reference
+
+| Condition | Action |
+|-----------|--------|
+| Verify drift < 5 | Discard line, return to Step 1 |
+| Verify drift >= 5 consecutive | Halt; `VERIFY_DRIFT_EXCEEDED` |
+| Pre-flip uniqueness != 1 | Halt; duplicate ID report |
+| Pre-flip Edit no-match < 3 (same task) | Return to Step 1 |
+| Pre-flip Edit no-match >= 3 (same task) | Mark `[!]`, halt |
+| Post-flip Edit no-match | Halt; manual resolution |
+| Task execution failure | Mark `[>]` → `[!]`, halt |
+| Hook write failure | Log warning, continue |
+| `[>]` prerequisite | Halt; `PREREQUISITE_IN_PROGRESS`; report task ID |
+| `DEPENDENCY_FAILED` | Halt; report failed prerequisite |
+| `SCAN_LIMIT_EXCEEDED` | Halt; report blocked task list |
+
+---
+
+Confirm between tasks unless the developer explicitly says to proceed without confirmation.

package/project-template/.claude/commands/cc-init.md

@@ -0,0 +1,84 @@
+---
+description: "(Conductor) Initialize or re-sync the project environment"
+---
+
+## Step 1 — Detect project state
+
+List files in the project (exclude `.git/`, `.claude/`, `node_modules/`, and dot-files, max depth 3). Count source files found.
+
+If the count is 0 or only `CLAUDE.md` / config files exist, treat this as a **new/empty project** (`IS_NEW=true`). Otherwise set `IS_NEW=false`.
+
+## Step 2 — Auto-detect and collect project identity
+
+Check if `scripts/detect-stack.mjs` exists in the project root. If it does, run:
+
+```bash
+node scripts/detect-stack.mjs "$PWD"
+```
+
+**Environment flags:** `CC_GLOB_DEPTH` and any other `CC_*` env vars the user may have set are automatically inherited by the child `node` process — no explicit export or forwarding is required. The `/cc-init` command must NOT reset or unset these variables before calling detect-stack.
+
+Capture the JSON output. For each field in the JSON (name, description, stack, build, test, lint, format, setup), check the corresponding line in CLAUDE.md:
+- If the CLAUDE.md line contains `<command>` (any case) or is blank after `Key:` → replace with the detected value using a single `Edit` call.
+- If the CLAUDE.md line already has a non-placeholder value → skip (never overwrite).
+
+Apply all replacements in a **single `Edit` call** after collecting all detected values.
+
+If `scripts/detect-stack.mjs` is missing or returns `{}`, skip auto-detection.
+
+After auto-detection (or if skipped), check which identity fields remain blank:
+
+Read `CLAUDE.md`. Check the `## Project Identity` section.
+
+If **Name** is still empty, ask the user all of these questions at once (not one at a time):
+
+1. What is the project name?
+2. One sentence: what does it do?
+3. Primary tech stack (e.g. "TypeScript + React", "Python + FastAPI") — **only ask if `IS_NEW=false` AND stack was not auto-detected**
+4. Response language preference? (default: `en` — only ask if context suggests otherwise)
+
+If Name was already filled (by auto-detection or previous run), skip directly to Step 3 without asking.
+
+Once any manual fields are collected, update CLAUDE.md with a single `Edit` call covering all remaining blank fields.
+
+**CI mode:** If `CI=true` or stdin is not a TTY, skip all interactive questions. Leave unresolved `<command>` placeholders in place.
+
+## Step 3 — Stack detection *(skip if IS_NEW=true)*
+
+Run `/cc-stack`. Wait for stack profile confirmation before continuing.
+
+## Step 4 — Memory checkpoint *(skip if IS_NEW=true)*
+
+Run `/cc-checkpoint`. Persist current architectural state to `.claude/memory/project.md`.
+
+## Step 5 — Graph sync *(skip if IS_NEW=true)*
+
+Run `/graphify .` to build or refresh the project knowledge graph from the current working directory.
+
+## Step 6 — Hook integrity check
+
+Verify `.claude/hooks/pre-tool-use.sh` exists and is executable:
+
+```bash
+HOOK=".claude/hooks/pre-tool-use.sh"
+if [ ! -f "$HOOK" ]; then
+  echo "⚠️  Hook missing: $HOOK"
+  echo "Run: bash install.sh  (or copy from project-template/.claude/hooks/)"
+  exit 1
+fi
+[ -x "$HOOK" ] || chmod +x "$HOOK"
+echo "✓ Hook OK: $HOOK"
+```
+
+If the hook file is absent, stop and report. Do not proceed silently.
+
+## Step 7 — Confirm
+
+Report:
+- Project identity: [name / stack / language — written to CLAUDE.md]
+- Stack profile loaded: [name / skipped — new project]
+- Memory checkpoint: [saved / skipped — new project]
+- Graph: [built / refreshed / skipped — new project]
+- Hook: [OK / MISSING]
+
+`/cc-init complete.`

package/project-template/.claude/commands/cc-plan.md

@@ -0,0 +1,114 @@
+---
+description: "(Conductor) Map implementation steps from an approved spec"
+---
+
+## Phase entry - Resume Read
+
+Before doing anything else, restore any stored context for the current commit by running `scripts/resume-read.mjs`. It resolves the current git hash, prefers a valid DB snapshot (`conductor-db get-snapshot`), falls back to the `.claude/memory/session-snapshot.json` handoff file, and prints a `RESUME_HIT` block on a hit / nothing on a miss. Capture its stdout **and** its exit code with the canonical per-platform form (each first probes for `node` and treats its absence as a clean miss, never an error):
+
+- **Unix / Git Bash:**
+  ```sh
+  if command -v node >/dev/null 2>&1; then
+    resume_out="$(node scripts/resume-read.mjs 2>>.conductor/last-write.log)"; resume_rc=$?
+  else resume_rc=3; resume_out=""; fi
+  ```
+- **PowerShell:**
+  ```powershell
+  if (Get-Command node -ErrorAction SilentlyContinue) {
+    $__eap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
+    if (Test-Path variable:PSNativeCommandUseErrorActionPreference) {
+      $__nap = $PSNativeCommandUseErrorActionPreference; $PSNativeCommandUseErrorActionPreference = $false
+    }
+    try {
+      $resume_out = node scripts/resume-read.mjs 2>> .conductor/last-write.log; $resume_rc = $LASTEXITCODE
+    } catch { $resume_rc = 3; $resume_out = "" }
+    finally {
+      $ErrorActionPreference = $__eap
+      if (Test-Path variable:__nap) { $PSNativeCommandUseErrorActionPreference = $__nap }
+    }
+  } else { $resume_rc = 3; $resume_out = "" }
+  ```
+
+Branch on `resume_rc` - **only `0` and `4` are meaningful; every other code proceeds fresh:**
+
+- **`0`** → parse the captured block and adopt it as this phase's starting context, then echo one banner to the user: `> Resumed from stored snapshot @ <commit> (phase: <phase>)`, appending ` (checkpoint prose available)` when the block reports `prose: available`. Parsing (the command owns normalization): split on `\n`; strip a trailing `\r` from every line; drop leading/trailing wholly-blank lines; require `lines[0].trim() === 'RESUME_HIT'` (anything else = miss); `key: value` lines split on the first `': '` (both sides trimmed); the `pending:` block is every subsequent `^\s*-\s+` line up to the first blank line or EOF, each item trimmed. Unknown keys are ignored. In PowerShell, `node …` binds `string[]` for multi-line output - normalize with `$lines = @($resume_out)`; a `$null`/empty capture with `resume_rc = 3` is a miss.
+- **`4`** → **operational halt.** Do not run this phase's normal work. Emit exactly: `SNAP_INVALID: corrupt handoff at .claude/memory/session-snapshot.json - inspect or remove it, then re-run.` and enter standby awaiting user action. The corrupt file is left on disk (the script did not delete it).
+- **`3` or any other code** → **proceed fresh** (clean miss, bypass, degrade, absent `node`, or any unexpected runtime code). Ignore the capture.
+
+`resume-read.mjs` writes its own trace lines to `.conductor/last-write.log` via `appendFileSync`; the `2>>` redirect above only sinks the incidental exit-4 halt reason away from the UI - it is not the trace channel.
+
+---
+
+## Phase 0 — Skill activation
+
+Before doing anything else, invoke both skills in order:
+
+```
+Skill({ skill: "writing-plans", args: "$ARGUMENTS" })
+Skill({ skill: "critical-review" })
+```
+
+`writing-plans` structures the format and sequencing strategy. `critical-review` Phase 1 then runs the Pre-Flight Analysis on the implementation approach — surface failure points and boundary conditions before committing to an ordered step list. Do not generate steps until both have completed.
+
+---
+
+Require an approved spec before starting. If no spec is in `.claude/memory/project.md` or in the recent conversation, stop and say:
+"No approved spec found. Run `/cc-spec [name]` first."
+
+Read `.claude/memory/project.md` and this project's `CLAUDE.md` before doing anything else.
+
+**Map the codebase structure** before reading any file content:
+- List directories
+- Identify files related to the spec using grep, not reads
+- Note existing patterns to follow
+
+**Generate a plan with:**
+
+## Task ID Requirements
+
+Every task checkbox line must carry a unique alphanumeric ID:
+
+    - [ ] [T-001] Top-level task
+    - [ ] [T-001-A] Sub-task A
+    - [ ] [T-001-A-1] Sub-sub-task
+    - [ ] [T-002] Next top-level task
+
+Rules:
+- Minimum 3 digits (`T-001`); no upper bound (`T-1000` is valid)
+- Suffix depth is unlimited: `T-NNN(-[A-Z0-9]+)*`
+- IDs must be unique within the file; verify before saving; no two tasks may share the same ID
+- Generated checkbox lines must use plain ASCII `[ ]` (U+0020 space only between brackets); no Unicode invisible characters
+- Apply to all generated task lines only; do not add IDs retroactively to existing plan files
+
+## Ordered Steps
+
+Each step must include:
+- Exact file path(s)
+- Action (create / modify / delete)
+- What changes and why
+- Whether it has a dependency on a previous step
+
+## Test List
+- [ ] Unit tests for [unit]
+- [ ] Integration test for [seam]
+- [ ] E2E test if UI is affected
+
+## Commit Order
+[Which steps to group into commits]
+
+## Identified Risks
+[What could go wrong and how to catch it early]
+
+---
+
+Execute one step at a time. Confirm between steps unless the developer explicitly says to proceed without confirmation.
+
+---
+
+## Phase exit
+
+Once the plan is approved and saved, instruct the user:
+
+> "Plan complete. Run `/cc-compact` now before starting implementation."
+
+Do not proceed to implementation without user confirmation that `/cc-compact` has been run.

package/project-template/.claude/commands/cc-refactor.md

@@ -0,0 +1,42 @@
+---
+description: "(Conductor) Refactor a file or module for clarity and simplicity"
+---
+
+## Phase 0 — Skill activation
+
+Invoke both skills before doing anything else:
+
+```
+Skill({ skill: "code-simplifier", args: "$ARGUMENTS" })
+Skill({ skill: "subagent-driven-development", args: "$ARGUMENTS" })
+```
+
+`code-simplifier` defines the refactoring rules to apply. `subagent-driven-development` governs how to delegate each step to sub-agents — one per change, keeping the main context clean.
+
+---
+
+Diagnose the target file or module:
+
+**Complexity issues found:**
+- Functions over 30 lines: [list with line numbers]
+- Nesting over 3 levels: [list with line numbers]
+- Classes with 5+ dependencies: [list]
+- Layers that only delegate: [list]
+- Misleading names: [list]
+
+Generate a refactor plan: ordered list of changes, one per step.
+
+For each step:
+- What changes (exact file:line range)
+- Why (complexity signal it resolves)
+- Risk (what could break)
+
+**Execute one change at a time.** After each:
+1. Run the test suite
+2. Report: tests passed / failed
+3. Confirm before the next step
+
+**Final report:**
+- Before: [line count, complexity metrics]
+- After: [line count, complexity metrics]
+- Test status: [passed / N failed]