@abarcenas/ai-workflow-template 1.32.0 → 1.34.0

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

@@ -43,3 +43,53 @@
 - **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
+
+## Session: 2026-07-24 — Fix Hook Script References for Consumer Projects
+
+**Pipeline:** researcher → implementer → coder (5 parallel tasks T1–T5) → tracker
+**Coverage:** 7/7 unit tests passing (2 existing + 5 new), 52/52 integration assertions, 13/13 MCP references verified
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **Hash-based manifest namespace pattern** — `__scripts__/<relPath>` extends the proven `.agents/` (bare path) and `__opencode__/` namespace pattern. The 3-case sync logic (new → copy, untouched → overwrite, locally modified → skip with warning) applies identically across all sync sections. No manifest version schema change needed for adding new namespace keys.
+- **Co-location constraint for imported dependencies** — `memory-cli.js` imports `'./memory-index.js'` and `mcp-memory-server.js` also imports `'./memory-index.js'`. Both the consumer-facing script AND its co-located dependency must be in the same sync array. This is an architectural constraint: if you sync one, you must sync all of its relative-import dependencies.
+- **`ensureParentDirectory()` handles nested paths automatically** — `mcp/playwright-mcp-launcher.js` lives in a subdirectory, and the existing `ensureParentDirectory()` helper (which calls `mkdirSync(dirname(filePath), { recursive: true })`) creates it without any special handling.
+- **`spawnSync` for testing modules with `process.exit()`** — `sync.js` calls `process.exit()` and cannot be imported as a module. The proven pattern: use `child_process.spawnSync` to invoke it as a child process, with `INIT_CWD` pointing to an isolated temp directory (created via `mkdtempSync`), and clean up in `afterAll`. This is the same pattern used by `sync-phase.js` in production.
+- **Two Playwright MCP patterns coexist by design** — The template's own root `opencode.json` uses `npx @playwright/mcp@latest` (modern, no file dependency), while `opencode.mcp.example.json` uses the launcher script wrapper with env var configuration (`HEADLESS`, `SLOW_MO`, `VIEWPORT`). Both serve different audiences: the template itself vs. consumer projects that may need launcher configuration.
+- **Marker comment for managed-file detection** — The `HOOK_MARKER` (`# Managed by @abarcenas/ai-workflow-template setup`) is the first line of hook files. This enables `discover.js` `isManaged` detection by reading the first line. The marker must be on line 1 for detection to work — the shebang (`#!/bin/sh`) moves to line 2, which is safe because husky sources hook files rather than executing them directly.
+- **Relative paths in hooks become valid after script sync — no hook content changes needed** — The key architectural insight: `constants.js` `TEMPLATE_HOOKS` content uses `node scripts/memory-cli.js update` which resolves correctly from the consumer root once `scripts/` exists there. Zero modifications to `constants.js`, `hooks.js`, `.husky/post-merge`, or `.husky/pre-commit` are needed.
+- **Content integrity via SHA-256 manifest tracking** — Every synced file is hashed with SHA-256. The manifest tracks `__scripts__/<relPath>` → hash. This enables idempotent re-runs (hash match → no warning), local modification detection (on-disk hash ≠ manifest hash → skip with warning), and force overwrite (`--force` ignores local modifications).
+- **Cross-file MCP reference auditing is essential** — 13 reference points across 7 files needed verification (`opencode.mcp.example.json`, `opencode.mcp.json`, `opencode.json` root, `scripts/mcp-memory-server.js`, `scripts/sync.js`, `scripts/sync.test.js`, `.agents-sync-manifest.json`, `docs/playwright-mcp-configuration.md`). Every reference from MCP configs, sync arrays, test assertions, manifest entries, and documentation must be cross-checked to ensure path resolution after sync changes — this is easy to miss.
+- **`--force` flag consistency across all sync sections** — The `--force` flag semantics are identical for `.agents/`, `.opencode/`, `__scripts__/`, and root files: it bypasses local modification protection and overwrites. This consistency should be preserved for any future sync sections.
+
+**Agent tuning notes:**
+- **researcher**: Must conduct a 6-tier script inventory with dependency chain analysis when determining sync scope. The co-location constraint (`memory-cli.js` imports `'./memory-index.js'`) was discovered by tracing `import` chains — always follow relative imports to find all files that must be co-located. Also check MCP config files (`opencode.mcp.json`, `opencode.json`) for script path references that create additional sync requirements.
+- **implementer (planning)**: When parallel batches share a dependency (Phase 2 and 3 both depend on Phase 1), verify that batch-independent tasks truly have no shared-file dependencies. T2 (test code), T3 (integration verification), T4 (audit), and T5 (documentation) all depended on T1 but were fully independent of each other — this enabled parallel execution without conflicts. The plan's explicit dependency table with "Can run in parallel?" and "Depends on" columns is essential for coder batch scheduling.
+- **coder (T1 — sync.js core logic)**: When adding a new sync section that mirrors an existing one (`.opencode/` block), copy-paste with careful variable renaming is correct and efficient. The 3-case hash logic is proven and consistent. Only 3 things need to change: (1) the tracked key namespace (`__scripts__/` instead of `__opencode__/`), (2) source/target directory paths, (3) the log prefix in verbose messages. The accumulator pattern (`scriptsCopied`/`scriptsSkipped` feeding into global `copied`/`skipped`) should also be mirrored.
+- **coder (T2 — unit tests)**: Test infrastructure for `process.exit()` modules is reusable across all sync test files — create a `createTempDir()` helper with `mkdtempSync`, a `runSync(tempDir, args)` helper using `spawnSync`, and cleanup in `afterAll`. Assertion patterns to reuse: file existence (`expect(existsSync(path)).toBe(true)`), content match (`readFileSync(path) === sourceContent`), mtime invariance for skip tests, manifest key presence, and SHA-256 hash format validation (`/^[a-f0-9]{64}$/`).
+- **coder (T3 — integration verification)**: Integration verification in a simulated consumer project requires a comprehensive test harness. The pattern: create temp consumer dir with minimal `package.json`, run sync with `INIT_CWD`, then assert on filesystem state and script execution. Content integrity via SHA-256 comparison is more reliable than byte-by-byte comparison. Test groups should cover: first-run sync, idempotent re-run, locally modified preservation, `--force` overwrite, `--dry-run`, hook path resolution, post-merge hook path, syntax validation for all synced scripts, and script execution from consumer root.
+- **coder (T4 — MCP audit)**: MCP reference auditing requires structured cross-referencing. Create a table with columns: File, Lines, Reference text, and Status. Track every reference point across ALL files, not just obvious ones (documentation references are the ones most often missed). Note architectural nuances like the two Playwright patterns (npx vs launcher script) — these are design decisions worth documenting, not bugs.
+- **tracker**: The feature-specific documentation (`docs/hook-script-references/tracker.md`) should include a "Total Results" summary section at the end with unit tests, integration assertions, MCP references, and files modified. This gives readers an executive-summary view without reading the full multi-step pipeline.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.32.0",
+  "version": "1.34.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
@@ -166,6 +171,61 @@ if (existsSync(sourceOpenCodeDir)) {
   }
 }
 
+/* ──  Sync scripts/ directory ──────────────────────────────── */
+
+const scriptsToSync = [
+  'memory-cli.js',
+  'memory-index.js',
+  'bump-version.js',
+  'validate-memory-schema.js',
+  'mcp-memory-server.js',
+  'mcp/playwright-mcp-launcher.js',
+]
+
+const sourceScriptsDir = resolve(packageRoot, 'scripts')
+const targetScriptsDir = resolve(consumerRoot, 'scripts')
+let scriptsCopied = 0
+let scriptsSkipped = 0
+
+for (const scriptRelPath of scriptsToSync) {
+  const sourceFile = resolve(sourceScriptsDir, scriptRelPath)
+  const targetFile = resolve(targetScriptsDir, scriptRelPath)
+
+  if (!existsSync(sourceFile)) {
+    continue
+  }
+
+  const sourceHash = hashFile(sourceFile)
+  const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
+  const trackedKey = `__scripts__/${scriptRelPath}`
+  const recordedHash = manifest.files[trackedKey] ?? null
+
+  if (!existsSync(targetFile)) {
+    if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
+    syncFile(sourceFile, targetFile)
+    manifest.files[trackedKey] = sourceHash
+    scriptsCopied += 1
+    copied += 1
+    added += 1
+    continue
+  }
+
+  const isUntouched = recordedHash !== null && existingHash === recordedHash
+
+  if (forceOverwrite || isUntouched) {
+    if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
+    syncFile(sourceFile, targetFile)
+    manifest.files[trackedKey] = sourceHash
+    scriptsCopied += 1
+    copied += 1
+    continue
+  }
+
+  scriptsSkipped += 1
+  skipped += 1
+  console.warn(`[ai-workflow-template] Skipped locally modified script file: scripts/${scriptRelPath}`)
+}
+
 for (const rootFile of rootFiles) {
   const sourceFile = resolve(packageRoot, rootFile)
   if (!existsSync(sourceFile)) {
@@ -179,6 +239,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 +250,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 +327,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 +340,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

package/scripts/sync.test.js

@@ -1,4 +1,40 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, afterAll } from 'vitest'
+import { spawnSync } from 'child_process'
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  mkdtempSync,
+  statSync,
+} from 'fs'
+import { join, dirname } from 'path'
+import { tmpdir } from 'os'
+
+const projectRoot = process.cwd()
+const tempDirs = []
+
+function createTempDir() {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'sync-test-'))
+  tempDirs.push(tmpDir)
+  return tmpDir
+}
+
+function runSync(tempDir, args = []) {
+  return spawnSync('node', ['scripts/sync.js', ...args], {
+    cwd: projectRoot,
+    env: { ...process.env, INIT_CWD: tempDir },
+    encoding: 'utf8',
+  })
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
 
 describe('sync utility functions', () => {
   it('should validate basic assertions work', () => {
@@ -10,3 +46,143 @@ describe('sync utility functions', () => {
     expect(result).toBe('ai workflow template')
   })
 })
+
+describe('__scripts__ sync behavior', () => {
+  const scriptsToSync = [
+    'memory-cli.js',
+    'memory-index.js',
+    'bump-version.js',
+    'validate-memory-schema.js',
+    'mcp-memory-server.js',
+    'mcp/playwright-mcp-launcher.js',
+  ]
+
+  it('should copy scripts when they do not exist in consumer project', () => {
+    const tempDir = createTempDir()
+
+    // Create a manifest with __scripts__ entries (initial tracking)
+    const manifest = {
+      version: 1,
+      files: Object.fromEntries(
+        scriptsToSync.map((s) => [`__scripts__/${s}`, null]),
+      ),
+    }
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify(manifest, null, 2),
+    )
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Verify all 6 script files were created in the consumer's scripts/ dir
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      expect(
+        existsSync(targetFile),
+        `Expected scripts/${script} to exist`,
+      ).toBe(true)
+    }
+  })
+
+  it('should skip scripts that exist in target without manifest tracking', () => {
+    const tempDir = createTempDir()
+    const sourceScriptsDir = join(projectRoot, 'scripts')
+
+    // Pre-populate target with files matching source content (same hash)
+    // but create a manifest that has NO __scripts__ entries
+    for (const script of scriptsToSync) {
+      const sourceFile = join(sourceScriptsDir, script)
+      const targetFile = join(tempDir, 'scripts', script)
+      mkdirSync(dirname(targetFile), { recursive: true })
+      copyFileSync(sourceFile, targetFile)
+    }
+
+    // Empty manifest — no __scripts__ keys → isUntouched = false for all
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify({ version: 1, files: {} }),
+    )
+
+    // Record mtimes before sync
+    const mtimesBefore = {}
+    for (const script of scriptsToSync) {
+      mtimesBefore[script] = statSync(
+        join(tempDir, 'scripts', script),
+      ).mtimeMs
+    }
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Verify mtimes are unchanged (files were NOT overwritten)
+    for (const script of scriptsToSync) {
+      expect(statSync(join(tempDir, 'scripts', script)).mtimeMs).toBe(
+        mtimesBefore[script],
+      )
+    }
+  })
+
+  it('should force overwrite all scripts with --force', () => {
+    const tempDir = createTempDir()
+    const sourceScriptsDir = join(projectRoot, 'scripts')
+
+    // Pre-populate target with dummy content (different from source)
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      mkdirSync(dirname(targetFile), { recursive: true })
+      writeFileSync(targetFile, `// modified ${script}`)
+    }
+
+    const result = runSync(tempDir, ['--force'])
+    expect(result.status).toBe(0)
+
+    // Verify all 6 files were overwritten with source content
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      const sourceFile = join(sourceScriptsDir, script)
+      expect(existsSync(targetFile)).toBe(true)
+      expect(readFileSync(targetFile, 'utf8')).toBe(
+        readFileSync(sourceFile, 'utf8'),
+      )
+    }
+  })
+
+  it('should show scripts in --dry-run output but not write files', () => {
+    const tempDir = createTempDir()
+
+    const result = runSync(tempDir, ['--dry-run'])
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('dry-run')
+
+    // Verify no script files were written to disk
+    for (const script of scriptsToSync) {
+      expect(existsSync(join(tempDir, 'scripts', script))).toBe(false)
+    }
+  })
+
+  it('should track new manifest entries after sync', () => {
+    const tempDir = createTempDir()
+
+    // Create empty manifest
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify({ version: 1, files: {} }),
+    )
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Read back the updated manifest
+    const updatedManifest = JSON.parse(
+      readFileSync(join(tempDir, '.agents-sync-manifest.json'), 'utf8'),
+    )
+
+    // Verify all 6 __scripts__ entries are tracked with valid SHA-256 hashes
+    for (const script of scriptsToSync) {
+      const key = `__scripts__/${script}`
+      expect(updatedManifest.files[key]).toBeDefined()
+      expect(updatedManifest.files[key]).toMatch(/^[a-f0-9]{64}$/)
+    }
+  })
+})