@abarcenas/ai-workflow-template 1.32.0 → 1.33.0

package/.agents/instructions/learned-knowledge.instructions.md

@@ -43,3 +43,26 @@
 - **coder (parallel batches)**: Batch ordering discipline worked — foundation first, then core, then orchestrator. The truly independent batches (D: markers, F: tests) could run alongside later batches. Key lesson: define interfaces (Context shape, return types) before splitting work across parallel coders
 - **unit-tester**: Using real temp directories (`mkdtempSync`) over mocking filesystem operations catches path resolution and permission issues that mocks would miss. Mock only environment-dependent utilities (CI detection, Node version), not filesystem
 - **tracker**: Should capture ecosystem discoveries alongside implementation details — the npm v12 finding and marker idempotency pattern are valuable knowledge for future pipeline sessions
+
+## Session: 2026-07-24 — Verbose Logging for ai-workflow-setup
+
+**Pipeline:** implementer (bootstrap) → researcher → implementer (planning) → coder (4 parallel batches) → tracker
+**Coverage:** 96/96 tests passing across 5 test files (discover 23, hooks 16, prepare 27, index 25, sync-phase 5)
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **Dead code infrastructure is a valuable find** — the `--verbose` flag already existed in `constants.js` and was correctly parsed by `parseCliArgs()`, but was never checked anywhere. Always check for existing-but-unused infrastructure before building new mechanisms
+- **`spawnScript()` in `sync-phase.js` was the root cause of silent hangs** — child process stdout/stderr was captured into a string but that string was never displayed or logged. The fix: use `stdio: 'inherit'` when verbose, `'pipe'` for normal mode
+- **Child process communication requires env vars** — parent and child processes share no context object. `sync.js` reads `AI_WORKFLOW_VERBOSE` from `process.env` set by `sync-phase.js` before spawning
+- **`console.error` (stderr) is correct for verbose output in child processes** — stdout is captured by the parent for result parsing, but stderr streams to terminal in `stdio: 'inherit'` mode. Diagnostic messages go to stderr
+- **`index.js` needed ZERO changes** — the Context `verbose` field flows from `discover(flags)` through all phase modules automatically via the existing orchestration pattern. This validates the Context enrichment architecture
+- **Parallel batching with 4 batches and 10 tasks worked cleanly**: Batch A (T1–T2 foundation) → Batch B (T3–T6 core fixes) → Batch C (T7 single) → Batch D (T8–T10 tests). 0 collisions, clean interface boundaries. The explicit dependency graph (Batch A → B → C, B → D) prevented race conditions
+- **`normalize-memory.js` already has good internal logging** — when verbose mode streams child stdout in real-time, this existing logging becomes visible to the user for free, with no code changes needed
+- **Dim ANSI style (` … prefix`) for verbose output** — visually distinguishes verbose progress from normal output. Uses existing color infrastructure with TTY guard
+
+**Agent tuning notes:**
+- **researcher**: Should examine existing flag/configuration infrastructure for dead code — the `--verbose` flag was fully defined and parsed but never checked. This was the single most impactful finding because it revealed both the root cause (spawnScript capture) and the solution path (activate existing flag)
+- **implementer (planning)**: The "index.js needs zero changes" insight should be explicitly validated before including in plans — it's easy to miss that context flows automatically. Read the orchestrator code to verify before committing to "no changes" claims
+- **coder**: When fixing child process output capture, consider both stdout and stderr channels independently — they serve different purposes (results vs diagnostics). `stdio: 'inherit'` is clean for real-time streaming but means stdout is no longer capturable programmatically
+- **unit-tester**: When testing child process spawn behavior, mock `child_process` spawn module rather than using real subprocesses — this avoids side effects and keeps tests fast. Use `vi.mock` with factory functions to control `stdio` arg and `env` values
+- **tracker**: Record dead-code discoveries alongside implementation details — the "existing but unused infrastructure" finding is a recurring pattern worth tracking across sessions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
   "main": "index.js",
   "bin": {

package/scripts/setup/discover.js

@@ -14,6 +14,8 @@ import {
   safeReadJson,
 } from './utils.js'
 
+import { verbose } from './ui.js'
+
 // ── Defaults ─────────────────────────────────────────────────────────────────
 
 /**
@@ -52,6 +54,7 @@ function createDefaultContext(flags = {}) {
     isCI: false,
     nodeVersion: 0,
     dryRun: !!flags.dryRun,
+    verbose: !!flags.verbose,
   }
 }
 
@@ -144,8 +147,10 @@ function detectHook(consumerRoot, hookName) {
  */
 export async function discover(flags = {}) {
   const ctx = createDefaultContext(flags)
+  const verboseEnabled = !!flags.verbose
 
   // ── 1. Resolve consumer root ──────────────────────────────────────────
+  verbose(verboseEnabled, 'Resolving consumer root from INIT_CWD\u2026')
   try {
     ctx.consumerRoot = getConsumerRoot()
   } catch {
@@ -163,25 +168,31 @@ export async function discover(flags = {}) {
   }
 
   // ── 2. Detect git repository ──────────────────────────────────────────
+  verbose(verboseEnabled, 'Checking for .git directory\u2026')
   try {
     ctx.hasGit = dirExists(resolve(ctx.consumerRoot, '.git'))
+    verbose(verboseEnabled, ctx.hasGit ? 'Git repository found' : 'No git repository')
   } catch {
     // Non-fatal — hasGit stays false
   }
 
   // ── 3. Detect .husky/ directory ───────────────────────────────────────
+  verbose(verboseEnabled, 'Checking for .husky/ directory\u2026')
   try {
     ctx.hasHuskyDir = dirExists(resolve(ctx.consumerRoot, '.husky'))
+    verbose(verboseEnabled, ctx.hasHuskyDir ? '.husky/ directory found' : '.husky/ directory not found')
   } catch {
     // Non-fatal — hasHuskyDir stays false
   }
 
   // ── 4. Detect + parse package.json ────────────────────────────────────
+  verbose(verboseEnabled, 'Reading package.json\u2026')
   try {
     const pkgPath = resolve(ctx.consumerRoot, 'package.json')
     const pkg = safeReadJson(pkgPath)
     ctx.hasPackageJson = pkg !== undefined
     ctx.consumerPackageJson = pkg ?? null
+    verbose(verboseEnabled, ctx.hasPackageJson ? 'package.json found' : 'package.json not found')
   } catch {
     // Non-fatal — hasPackageJson stays false, consumerPackageJson stays null
   }
@@ -190,21 +201,30 @@ export async function discover(flags = {}) {
   // existingHooks is pre-initialised by createDefaultContext() so the loop
   // below only overrides the entries it successfully reads.  Any hook that
   // cannot be read keeps its safe default (exists: false).
+  verbose(verboseEnabled, 'Detecting existing hooks\u2026')
   try {
     for (const hookName of Object.keys(TEMPLATE_HOOKS)) {
       ctx.existingHooks[hookName] = detectHook(ctx.consumerRoot, hookName)
+      const hook = ctx.existingHooks[hookName]
+      if (hook.exists) {
+        verbose(verboseEnabled, `${hookName}: ${hook.isManaged ? 'managed' : 'found (unmanaged)'}`)
+      } else {
+        verbose(verboseEnabled, `${hookName}: not found`)
+      }
     }
   } catch {
     // Non-fatal — existingHooks already contains default entries
   }
 
   // ── 6. Extract existing prepare script ────────────────────────────────
+  verbose(verboseEnabled, 'Extracting prepare script\u2026')
   try {
     const prepare = ctx.consumerPackageJson?.scripts?.prepare
     ctx.existingPrepare =
       typeof prepare === 'string' && prepare.trim().length > 0
         ? prepare.trim()
         : null
+    verbose(verboseEnabled, ctx.existingPrepare ? `Prepare script: ${ctx.existingPrepare}` : 'No prepare script')
   } catch {
     // Non-fatal — existingPrepare stays null
   }
@@ -217,20 +237,25 @@ export async function discover(flags = {}) {
   }
 
   // ── 8. Detect CI environment ──────────────────────────────────────────
+  verbose(verboseEnabled, 'Detecting CI environment\u2026')
   try {
     ctx.isCI = isCI()
+    verbose(verboseEnabled, ctx.isCI ? 'CI detected' : 'Not CI')
   } catch {
     ctx.isCI = false
   }
 
   // ── 9. Detect Node.js version ─────────────────────────────────────────
+  verbose(verboseEnabled, 'Detecting Node.js version\u2026')
   try {
     ctx.nodeVersion = getNodeVersion()
+    verbose(verboseEnabled, `Node.js v${ctx.nodeVersion}`)
   } catch {
     ctx.nodeVersion = 0
   }
 
   // NOTE: `ctx.dryRun` is already set by createDefaultContext(flags)
 
+  verbose(verboseEnabled, 'Discovery complete')
   return ctx
 }

package/scripts/setup/discover.test.js

@@ -385,4 +385,24 @@ describe('discover()', () => {
     expect(h.content).toBe(content)
     expect(h.isManaged).toBe(true)
   })
+
+  // ── 21. verbose flag passthrough ─────────────────────────────────────────
+
+  it('should set verbose=true when verbose flag is passed', async () => {
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover({ verbose: true })
+
+    expect(ctx.verbose).toBe(true)
+  })
+
+  it('should set verbose=false when verbose flag is absent', async () => {
+    const dir = createProject()
+    mockConsumerRoot = dir
+
+    const ctx = await discover()
+
+    expect(ctx.verbose).toBe(false)
+  })
 })

package/scripts/setup/hooks.js

@@ -29,6 +29,7 @@ import {
   stepError,
   stepSuccess,
   stepWarn,
+  verbose,
 } from './ui.js'
 
 // ── Content builder ──────────────────────────────────────────────────────────
@@ -191,9 +192,13 @@ export async function installHooks(context) {
     try {
       // ── Case A: No .husky/ directory — create it and write hook ──
       if (!hasHuskyDir) {
+        verbose(context.verbose, `Creating .husky/ directory\u2026`)
         ensureDir(resolve(context.consumerRoot, '.husky'))
+        verbose(context.verbose, `Writing ${hookName} hook\u2026`)
         safeWriteFile(target, content)
+        verbose(context.verbose, 'Setting executable permissions\u2026')
         chmodX(target)
+        verbose(context.verbose, '  \u2713 done')
         const msg = `${hookName} hook created (\u2713 ${desc})`
         stepSuccess(msg)
         results.push({ hook: hookName, action: 'created', message: msg })
@@ -202,8 +207,11 @@ export async function installHooks(context) {
 
       // ── Case B: .husky/ exists but no hook file ─────────────────
       if (!existing) {
+        verbose(context.verbose, `Writing ${hookName} hook\u2026`)
         safeWriteFile(target, content)
+        verbose(context.verbose, 'Setting executable permissions\u2026')
         chmodX(target)
+        verbose(context.verbose, '  \u2713 done')
         const msg = `${hookName} hook created (\u2713 ${desc})`
         stepSuccess(msg)
         results.push({ hook: hookName, action: 'created', message: msg })
@@ -212,8 +220,11 @@ export async function installHooks(context) {
 
       // ── Case C: Hook exists AND is managed by us — overwrite ────
       if (isManaged) {
+        verbose(context.verbose, `Overwriting ${hookName} (idempotent update)\u2026`)
         safeWriteFile(target, content)
+        verbose(context.verbose, 'Setting executable permissions\u2026')
         chmodX(target)
+        verbose(context.verbose, '  \u2713 done')
         const msg = `${hookName} hook overwritten (idempotent update, ${desc})`
         stepSuccess(msg)
         results.push({ hook: hookName, action: 'overwritten', message: msg })
@@ -222,11 +233,15 @@ export async function installHooks(context) {
 
       // ── Case D: Hook exists, not ours, --force — back up + overwrite
       if (force) {
+        verbose(context.verbose, `Backing up existing ${hookName}\u2026`)
         const bakPath = target + '.bak'
         const originalContent = safeReadFile(target)
         safeWriteFile(bakPath, originalContent ?? '')
+        verbose(context.verbose, `Writing ${hookName} hook (force)\u2026`)
         safeWriteFile(target, content)
+        verbose(context.verbose, 'Setting executable permissions\u2026')
         chmodX(target)
+        verbose(context.verbose, '  \u2713 done')
         const msg =
           `${hookName} hook overwritten (original backed up to .bak, ${desc})`
         stepSuccess(msg)
@@ -235,11 +250,15 @@ export async function installHooks(context) {
       }
 
       // ── Case E: Hook exists, not ours, no --force — append ──────
+      verbose(context.verbose, `Reading existing ${hookName} for merge\u2026`)
       const existingContent = safeReadFile(target)
       const mergedContent =
         (existingContent ?? '') + '\n' + HOOK_MERGE_SEPARATOR + '\n' + content
+      verbose(context.verbose, `Writing merged ${hookName}\u2026`)
       safeWriteFile(target, mergedContent)
+      verbose(context.verbose, 'Setting executable permissions\u2026')
       chmodX(target)
+      verbose(context.verbose, '  \u2713 done')
       const msg = `${hookName} hook merged with existing content (${desc})`
       stepSuccess(msg)
       results.push({ hook: hookName, action: 'merged', message: msg })

package/scripts/setup/husky-init.js

@@ -12,10 +12,13 @@
 // installed husky version is used.
 // ═════════════════════════════════════════════════════════════════════════════
 
+import { execSync } from 'child_process'
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { createRequire } from 'module'
 
+import { info, warn, verbose } from './ui.js'
+
 // ── Main export ──────────────────────────────────────────────────────────────
 
 /**
@@ -34,14 +37,15 @@ import { createRequire } from 'module'
  * @param {boolean}  context.hasGit       - Whether the project has a `.git/` directory.
  * @param {boolean}  context.dryRun       - When `true` only report, do nothing.
  * @param {boolean}  context.isCI         - When `true` skip husky init entirely.
+ * @param {boolean}  context.verbose      - When `true` emit verbose progress messages.
  * @returns {Promise<{action: string, message: string}>}
  */
 export async function initHusky(context) {
-  const { consumerRoot, hasGit, dryRun, isCI } = context
+  const { consumerRoot, hasGit, dryRun, isCI, verbose: verboseFlag } = context
 
   // ── Dry-run mode ─────────────────────────────────────────────────────
   if (dryRun) {
-    console.log(
+    info(
       '[setup] Would initialize husky (generate .husky/_/ shims, set core.hooksPath)',
     )
     return { action: 'dry-run', message: 'Would initialize husky' }
@@ -49,7 +53,7 @@ export async function initHusky(context) {
 
   // ── CI environment ───────────────────────────────────────────────────
   if (isCI) {
-    console.log('[setup] CI environment detected — skipping husky init')
+    warn('[setup] CI environment detected — skipping husky init')
     return {
       action: 'skipped',
       message: 'Skipping husky init in CI environment',
@@ -67,27 +71,48 @@ export async function initHusky(context) {
 
   // ── Resolve husky from the consumer's node_modules ──────────────────
   let husky
+  verbose(verboseFlag, 'Resolving husky from consumer node_modules\u2026')
   try {
     const consumerRequire = createRequire(join(consumerRoot, 'package.json'))
     const huskyPath = consumerRequire.resolve('husky')
+    verbose(verboseFlag, `Found husky at ${huskyPath}`)
     const mod = await import(huskyPath)
     husky = mod.default
   } catch {
     // createRequire.resolve or import() failed — husky is not installed
+    verbose(verboseFlag, 'husky not found \u2014 skipping init')
     return {
       action: 'skipped',
       message: 'husky is not installed. Run: npm install husky --save-dev',
     }
   }
 
+  // ── Clear stale hooksPath ──────────────────────────────────────────
+  // Husky v9's programmatic API is a no-op when core.hooksPath already
+  // exists (even if pointing to a wrong value). Unset it so husky()
+  // actually generates the .husky/_/ shim files from scratch.
+  verbose(verboseFlag, 'Clearing stale core.hooksPath\u2026')
+  try {
+    execSync('git config --local --unset core.hooksPath', {
+      cwd: consumerRoot,
+      stdio: 'pipe',
+    })
+  } catch {
+    // Silently continue if the key didn't exist or is not unset-able.
+    // husky() will handle hooksPath setup internally.
+  }
+
   // ── Invoke husky() ──────────────────────────────────────────────────
+  verbose(verboseFlag, 'Calling husky()\u2026')
   try {
     husky(consumerRoot)
   } catch (err) {
+    verbose(verboseFlag, `husky() failed: ${err.message}`)
     return { action: 'failed', message: err.message }
   }
 
   // ── Verify post-condition ───────────────────────────────────────────
+  verbose(verboseFlag, 'Verifying .husky/_/h exists\u2026')
   const hPath = join(consumerRoot, '.husky', '_', 'h')
   if (!existsSync(hPath)) {
     return {

package/scripts/setup/index.test.js

@@ -135,6 +135,7 @@ const defaultContext = {
   isCI: false,
   nodeVersion: 20,
   dryRun: false,
+  verbose: false,
 }
 
 /**
@@ -557,7 +558,31 @@ describe('main() — setup orchestrator', () => {
     expect(runSyncPhase).toHaveBeenCalledWith(ctx)
   })
 
-  // ── 19. Flags object passed to discover ─────────────────────────────────
+  // ── 19a. --verbose flag passthrough to Context ──────────────────────────
+
+  it('--verbose: passes verbose flag through to Context', async () => {
+    const flags = { ...defaultFlags, verbose: true }
+    parseCliArgs.mockReturnValue(flags)
+    const ctx = { ...defaultContext, verbose: true }
+    discover.mockResolvedValue(ctx)
+
+    await main(['--verbose'])
+
+    // parseCliArgs was called with the expected argv
+    expect(parseCliArgs).toHaveBeenCalledWith(['--verbose'])
+    // discover received the flags with verbose: true
+    expect(discover).toHaveBeenCalledWith(flags)
+    // Every phase receives the context with verbose: true preserved
+    expect(installHooks).toHaveBeenCalledWith(ctx)
+    expect(handlePrepare).toHaveBeenCalledWith(ctx)
+    expect(initHusky).toHaveBeenCalledWith(ctx)
+    expect(runSyncPhase).toHaveBeenCalledWith(ctx)
+    // Normal pipeline — header and summary shown
+    expect(header).toHaveBeenCalledTimes(1)
+    expect(summary).toHaveBeenCalledTimes(1)
+  })
+
+  // ── 20. Flags object passed to discover ─────────────────────────────────
 
   it('passes the flags object to discover()', async () => {
     const flags = { ...defaultFlags, dryRun: true }

package/scripts/setup/sync-phase.js

@@ -7,6 +7,7 @@ import { spawn } from 'child_process'
 import { join } from 'path'
 
 import { resolvePackageRoot, logInfo, logWarn, logError } from './utils.js'
+import { verbose } from './ui.js'
 
 // ── Main export ─────────────────────────────────────────────────────────────
 
@@ -72,20 +73,24 @@ export async function runSyncPhase(context) {
 
   // ── Spawn sync.js ──────────────────────────────────────────────────────
   const syncPath = join(packageRoot, 'scripts', 'sync.js')
+  verbose(context.verbose, 'Spawning sync.js\u2026')
   const syncResult = await spawnScript(
     'sync.js',
     syncPath,
     consumerRoot,
     extraArgs,
+    context.verbose,
   )
 
   // ── Spawn normalize-memory.js ──────────────────────────────────────────
   const normPath = join(packageRoot, 'scripts', 'normalize-memory.js')
+  verbose(context.verbose, 'Spawning normalize-memory.js\u2026')
   const normResult = await spawnScript(
     'normalize-memory.js',
     normPath,
     consumerRoot,
     extraArgs,
+    context.verbose,
   )
 
   const results = [syncResult, normResult]
@@ -133,30 +138,32 @@ export async function runSyncPhase(context) {
  *   output: string
  * }>}
  */
-function spawnScript(name, scriptPath, cwd, extraArgs) {
+function spawnScript(name, scriptPath, cwd, extraArgs, verbose = false) {
   return new Promise((resolve) => {
     const child = spawn(process.execPath, [scriptPath, ...extraArgs], {
       cwd,
-      env: { ...process.env, INIT_CWD: cwd },
-      stdio: 'pipe',
+      env: { ...process.env, INIT_CWD: cwd, AI_WORKFLOW_VERBOSE: verbose ? '1' : '0' },
+      stdio: verbose ? 'inherit' : 'pipe',
     })
 
     let output = ''
 
-    child.stdout.on('data', (data) => {
-      output += data.toString()
-    })
+    if (!verbose) {
+      child.stdout.on('data', (data) => {
+        output += data.toString()
+      })
 
-    child.stderr.on('data', (data) => {
-      output += data.toString()
-    })
+      child.stderr.on('data', (data) => {
+        output += data.toString()
+      })
+    }
 
     child.on('close', (exitCode) => {
       resolve({
         script: name,
         success: exitCode === 0,
         exitCode: exitCode ?? -1,
-        output: output.trim(),
+        output: verbose ? '(streamed to terminal)' : output.trim(),
       })
     })
 

package/scripts/setup/sync-phase.test.js

@@ -0,0 +1,195 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// sync-phase.test.js — Unit tests for the sync phase module
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Tests the spawnScript() function's verbose vs non-verbose spawn behavior
+// by mocking `child_process.spawn` and inspecting the options passed.
+//
+// Covered scenarios (5 tests per T10 requirements):
+//   1. Uses stdio: 'pipe' when verbose is false (default behavior)
+//   2. Uses stdio: 'inherit' when verbose is true
+//   3. Sets AI_WORKFLOW_VERBOSE=1 in child env when verbose is true
+//   4. Sets AI_WORKFLOW_VERBOSE=0 in child env when verbose is false
+//   5. Captures stdout/stderr output correctly in non-verbose mode
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { vi, describe, it, expect, beforeEach } from 'vitest'
+
+// ── Mocks (vitest hoists these to the top of the module) ──────────────────
+
+vi.mock('child_process', () => ({
+  spawn: vi.fn(),
+}))
+
+vi.mock('./ui.js', () => ({
+  verbose: vi.fn(),
+}))
+
+vi.mock('./utils.js', () => ({
+  resolvePackageRoot: vi.fn(() => '/fake/package/root'),
+  logInfo: vi.fn(),
+  logWarn: vi.fn(),
+  logError: vi.fn(),
+}))
+
+import { spawn } from 'child_process'
+import { runSyncPhase } from './sync-phase.js'
+
+// ── Test helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Creates a mock child process that mimics a spawned Node.js script.
+ *
+ * The mock registers event handlers for stdout/stderr 'data' events and
+ * the 'close' event, then fires them asynchronously on a microtask.
+ * This allows the Promise-based flow in spawnScript() to resolve naturally.
+ *
+ * @param {object}   opts
+ * @param {number}   [opts.exitCode=0]    - Exit code for the 'close' event
+ * @param {string}   [opts.stdoutData='']  - Data emitted via stdout 'data'
+ * @param {string}   [opts.stderrData='']  - Data emitted via stderr 'data'
+ * @returns {object} Mock child process with .stdout.on, .stderr.on, .on
+ */
+function createMockChild({ exitCode = 0, stdoutData = '', stderrData = '' } = {}) {
+  const stdoutHandlers = []
+  const stderrHandlers = []
+  let closeHandler = null
+
+  const child = {
+    stdout: {
+      on: (event, handler) => {
+        if (event === 'data') stdoutHandlers.push(handler)
+      },
+    },
+    stderr: {
+      on: (event, handler) => {
+        if (event === 'data') stderrHandlers.push(handler)
+      },
+    },
+    on: (event, handler) => {
+      if (event === 'close') closeHandler = handler
+    },
+  }
+
+  // Fire events on a microtask so handlers are registered first
+  Promise.resolve().then(() => {
+    if (stdoutData) {
+      stdoutHandlers.forEach((h) => h(Buffer.from(stdoutData)))
+    }
+    if (stderrData) {
+      stderrHandlers.forEach((h) => h(Buffer.from(stderrData)))
+    }
+    if (closeHandler) closeHandler(exitCode)
+  })
+
+  return child
+}
+
+/**
+ * Builds a minimal context object accepted by runSyncPhase().
+ *
+ * @param {object} [overrides] - Properties to override on the default context.
+ * @returns {object} Context object.
+ */
+function makeContext(overrides = {}) {
+  return {
+    consumerRoot: '/fake/consumer',
+    verbose: false,
+    dryRun: false,
+    skipSync: false,
+    flags: {},
+    ...overrides,
+  }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe('sync-phase verbose spawn behavior', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // ── 1. Pipe mode (non-verbose, default) ───────────────────────────────
+
+  it('uses stdio: "pipe" when verbose is false', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: false }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].stdio).toBe('pipe')
+    }
+  })
+
+  // ── 2. Inherit mode (verbose) ─────────────────────────────────────────
+
+  it('uses stdio: "inherit" when verbose is true', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: true }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].stdio).toBe('inherit')
+    }
+  })
+
+  // ── 3. Verbose env var = '1' ──────────────────────────────────────────
+
+  it('sets AI_WORKFLOW_VERBOSE=1 in child env when verbose is true', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: true }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].env).toBeDefined()
+      expect(call[2].env.AI_WORKFLOW_VERBOSE).toBe('1')
+    }
+  })
+
+  // ── 4. Non-verbose env var = '0' ──────────────────────────────────────
+
+  it('sets AI_WORKFLOW_VERBOSE=0 in child env when verbose is false', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: false }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].env).toBeDefined()
+      expect(call[2].env.AI_WORKFLOW_VERBOSE).toBe('0')
+    }
+  })
+
+  // ── 5. Output capture in non-verbose mode ─────────────────────────────
+
+  it('captures stdout/stderr output in non-verbose mode', async () => {
+    vi.mocked(spawn).mockImplementation(() =>
+      createMockChild({
+        exitCode: 0,
+        stdoutData: 'copying files...\n',
+        stderrData: '',
+      }),
+    )
+
+    const result = await runSyncPhase(makeContext({ verbose: false }))
+
+    expect(result.action).toBe('completed')
+    expect(result.results).toHaveLength(2)
+    for (const r of result.results) {
+      expect(r.output).toBe('copying files...')
+      expect(r.success).toBe(true)
+      expect(r.exitCode).toBe(0)
+    }
+  })
+})

package/scripts/setup/ui.js

@@ -139,6 +139,24 @@ function write(...lines) {
   }
 }
 
+/**
+ * Prints a dimmed verbose/debug message to stdout when verbose mode is
+ * enabled.
+ *
+ * When `enabled` is falsy the function is a no-op, making it safe to call
+ * unconditionally in hot paths without an extra `if` guard.
+ *
+ * @param {*} enabled  - Truthy to print, falsy to skip.
+ * @param {string} message - Debug message to display.
+ * @example
+ *   verbose(true, 'Resolving consumer root from INIT_CWD\u2026')
+ *   //   \u2026 Resolving consumer root from INIT_CWD\u2026
+ */
+export function verbose(enabled, message) {
+  if (!enabled) return
+  write(`  ${DIM}\u2026 ${message}${RST}`)
+}
+
 // ── Public output API ───────────────────────────────────────────────────────
 
 /**

package/scripts/sync.js

@@ -13,6 +13,7 @@ const excludedRelativePaths = new Set([])
 const args = new Set(process.argv.slice(2))
 const forceOverwrite = args.has('--force')
 const dryRun = args.has('--dry-run')
+const isVerbose = process.env.AI_WORKFLOW_VERBOSE === '1'
 
 function hashFile(filePath) {
   const contents = readFileSync(filePath)
@@ -104,6 +105,7 @@ for (const sourceFile of sourceFiles) {
   const recordedHash = manifest.files[trackedKey] ?? null
 
   if (!existsSync(targetFile)) {
+    if (isVerbose) console.error(`  … syncing: .agents/${relativePath}`)
     syncFile(sourceFile, targetFile)
     manifest.files[trackedKey] = sourceHash
     copied += 1
@@ -114,6 +116,7 @@ for (const sourceFile of sourceFiles) {
   const isUntouched = recordedHash !== null && existingHash === recordedHash
 
   if (forceOverwrite || isUntouched) {
+    if (isVerbose) console.error(`  … syncing: .agents/${relativePath}`)
     syncFile(sourceFile, targetFile)
     manifest.files[trackedKey] = sourceHash
     copied += 1
@@ -145,6 +148,7 @@ if (existsSync(sourceOpenCodeDir)) {
     const recordedHash = manifest.files[trackedKey] ?? null
 
     if (!existsSync(targetFile)) {
+      if (isVerbose) console.error(`  … syncing: .opencode/${relativePath}`)
       syncFile(sourceFile, targetFile)
       manifest.files[trackedKey] = sourceHash
       copied += 1
@@ -155,6 +159,7 @@ if (existsSync(sourceOpenCodeDir)) {
     const isUntouched = recordedHash !== null && existingHash === recordedHash
 
     if (forceOverwrite || isUntouched) {
+      if (isVerbose) console.error(`  … syncing: .opencode/${relativePath}`)
       syncFile(sourceFile, targetFile)
       manifest.files[trackedKey] = sourceHash
       copied += 1
@@ -179,6 +184,7 @@ for (const rootFile of rootFiles) {
   const recordedHash = manifest.files[trackedKey] ?? null
 
   if (!existsSync(targetFile)) {
+    if (isVerbose) console.error(`  … syncing: ${rootFile}`)
     syncFile(sourceFile, targetFile)
     manifest.files[trackedKey] = sourceHash
     copied += 1
@@ -189,6 +195,7 @@ for (const rootFile of rootFiles) {
   const isUntouched = recordedHash !== null && existingHash === recordedHash
 
   if (forceOverwrite || isUntouched) {
+    if (isVerbose) console.error(`  … syncing: ${rootFile}`)
     syncFile(sourceFile, targetFile)
     manifest.files[trackedKey] = sourceHash
     copied += 1
@@ -265,6 +272,7 @@ for (const [fileName, fileContent] of Object.entries(memoryBankStubs)) {
   }
 
   ensureParentDirectory(targetFile)
+  if (isVerbose) console.error(`  … scaffolding: memory-bank/${fileName}`)
   writeFileSync(targetFile, fileContent, 'utf8')
   manifest.files[trackedKey] = hashFile(targetFile)
   scaffolded += 1
@@ -277,6 +285,7 @@ const targetMcpFile = resolve(consumerRoot, 'opencode.mcp.json')
 const mcpTrackedKey = '__root__/opencode.mcp.json'
 
 if (existsSync(exampleMcpFile) && !existsSync(targetMcpFile)) {
+  if (isVerbose) console.error('  … scaffolding: opencode.mcp.json from example')
   copyFileSync(exampleMcpFile, targetMcpFile)
   manifest.files[mcpTrackedKey] = hashFile(targetMcpFile)
   scaffolded += 1