@abarcenas/ai-workflow-template 1.29.0 → 1.33.0

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

@@ -20,3 +20,49 @@
 - unit-tester: Must be told to look in `scripts/` for source and test files, not `src/`
 - coder: Must be told the project uses ES module syntax (import/export, not require/module.exports)
 - implementer: Plans should target `scripts/` for production code and tests
+
+## Session: 2026-07-24
+
+**Pipeline:** researcher → architect → implementer → coder (6 parallel batches) → unit-tester → tracker
+**Coverage:** 88/88 tests passing across 4 test files (discover 21, hooks 16, prepare 27, index 24)
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **npm v12 blocks postinstall scripts from dependencies** — this is a critical ecosystem shift that affects ALL npm library distribution. Postinstall auto-sync is no longer viable; explicit setup commands are required
+- **npx-based setup command pattern** (following Playwright, Prisma, Cypress convention) is the future-proof distribution mechanism for CLI tools that need to configure consumer projects
+- **Husky v9 programmatic API** is dead simple: `import husky from 'husky'; husky(consumerRoot)` — no need to shell out or manually manage shim files
+- **`child_process.spawn` for scripts with `process.exit()`** — importing sync.js (which calls `process.exit()`) directly into the setup process would kill the parent. Spawn as a child process to isolate exit behavior
+- **Marker comment idempotency** — a first-line comment (`# Managed by @abarcenas/ai-workflow-template setup`) on hook files enables content-based detection for safe re-runs. This pattern should be used for any managed file that needs idempotent installation
+- **6-batch parallel execution worked well**: Batch A (3 foundation: constants, utils, ui) → Batch B (5 core: discover, hooks, prepare, husky-init, sync-phase) → Batch C (2 orchestrator: index.js, bin/setup.js) → Batches D+E (3 config: pre-commit marker, post-merge marker, package.json) → Batch F (4 tests). Clear interface definitions were essential for parallelism
+- **Duplicate-marker trap** — constants.js `TEMPLATE_HOOKS.content` must stay in sync with actual `.husky/` hook files. During T12 (post-merge marker), a mismatch was discovered between the template content in constants.js (which already had the marker via `buildHookContent()`) and the actual disk file. Solution: update constants.js template content whenever hook files are modified
+
+**Agent tuning notes:**
+- **researcher**: Should explicitly investigate npm ecosystem changes (version-specific behavior, deprecations) — the npm v12 postinstall discovery was the single most important finding that drove the architecture
+- **architect**: Modular design with clear interface contracts (Context object shape, return types) paid off — all 5 Batch B modules could be implemented in parallel without coordination issues
+- **implementer**: The parallel batch plan with explicit dependency edges (Batch A → B → C, D+E → F) was critical for the 6 sub-agent coder execution. Without this structure, 6 concurrent coders would have had race conditions on shared files
+- **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/.github/workflows/npm-publish.yml

@@ -19,6 +19,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Run unit tests
+        run: npm run test:unit
+
       - name: Publish to npm
         run: npm publish --access public
         env:

package/.github/workflows/pr-test.yml

@@ -0,0 +1,23 @@
+name: PR Unit Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm run test:unit

package/.husky/post-merge

@@ -1,3 +1,4 @@
+# Managed by @abarcenas/ai-workflow-template setup
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 

package/.husky/pre-commit

@@ -1,2 +1,4 @@
+# Managed by @abarcenas/ai-workflow-template setup
+
 node scripts/bump-version.js
 node scripts/validate-memory-schema.js

package/README.md

@@ -35,7 +35,53 @@ Install directly into the project that needs AI workflow configuration:
 npm install @abarcenas/ai-workflow-template
 ```
 
-The package runs `postinstall` automatically to sync configurations.
+The package runs `postinstall` automatically to sync files. For full setup including git hooks, run the one-step setup command below.
+
+---
+
+## 🪝 Git Hook Setup
+
+After installing the package, configure husky git hooks with one command:
+
+```bash
+# One-step setup (fetches from npm registry automatically):
+npx @abarcenas/ai-workflow-template
+
+# Or if the package is already installed:
+npx ai-workflow-setup
+```
+
+### What It Does
+
+The setup command automatically:
+
+| Phase | Action |
+|-------|--------|
+| 🔍 **Discover** | Detects git repo, existing hooks, CI mode |
+| 🪝 **Hooks** | Installs `pre-commit` (version bump + validation) and `post-merge` (memory index update) |
+| 📦 **Prepare** | Merges `"husky"` into your `package.json` prepare script |
+| ⚙️ **Husky Init** | Initializes husky and sets `core.hooksPath` |
+| 🔄 **Sync** | Copies agent configurations, skills, and memory bank scaffolding |
+
+### Options
+
+```bash
+npx ai-workflow-setup --dry-run     # Preview without changes
+npx ai-workflow-setup --force       # Overwrite existing hooks
+npx ai-workflow-setup --skip-hooks  # Skip hook installation
+npx ai-workflow-setup --skip-sync   # Skip file sync
+npx ai-workflow-setup --help        # Show all options
+```
+
+### Hook Merging
+
+If you already have existing husky hooks, the setup command intelligently merges:
+- **Your hooks are never overwritten** — new content is appended after a separator
+- **Managed hooks are detected** via marker comments and updated idempotently
+- **Complex hooks** trigger a warning with manual merge instructions
+- **CI environments** auto-skip hook configuration
+
+> **ℹ️ npm v12 note:** Future npm versions block automatic `postinstall` scripts. The explicit `npx setup` command is the recommended, future-proof approach.
 
 ---
 
@@ -416,6 +462,7 @@ npm run memory:normalize
 - 📖 `AGENTS.md` is the main instruction file agents should read
 - 🎯 Package assumes public npm registry
 - 🎭 Playwright MCP integration documented in `docs/` folder
+- 🪝 Run `npx ai-workflow-setup` after install to configure git hooks (npm v12+ compatible)
 
 ---
 

package/bin/setup.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// ═════════════════════════════════════════════════════════════════════════════
+// bin/setup.js — CLI entry point for `npx ai-workflow-setup`
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Minimal shim that delegates to the orchestrator (scripts/setup/index.js).
+// Uses top-level await via ESM (requires "type": "module" in package.json).
+//
+// Exit codes:
+//   0 — All phases completed successfully
+//   1 — One or more phases had warnings / were skipped
+//   2 — Fatal error (discovery failure or unexpected exception)
+// ═════════════════════════════════════════════════════════════════════════════
+
+try {
+  const { main } = await import('../scripts/setup/index.js')
+  const exitCode = await main(process.argv.slice(2))
+  process.exit(exitCode)
+} catch (err) {
+  console.error('Fatal error:', err.message)
+  process.exit(2)
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.29.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": {
+    "ai-workflow-setup": "./bin/setup.js"
+  },
   "scripts": {
     "test": "playwright test",
     "test:headed": "playwright test --headed",
@@ -14,7 +17,7 @@
     "test:unit:watch": "vitest",
     "prepare": "husky",
     "sync": "node ./scripts/sync.js",
-    "postinstall": "node ./scripts/sync.js && node ./scripts/normalize-memory.js",
+    "postinstall": "node ./scripts/sync.js && node ./scripts/normalize-memory.js && echo '' && echo '⚠️  IMPORTANT: Run npx ai-workflow-setup to configure git hooks' && echo '   (npm postinstall scripts will be blocked by npm v12+)'",
     "memory:search": "node ./scripts/memory-cli.js search",
     "memory:rebuild": "node ./scripts/memory-cli.js rebuild",
     "memory:update": "node ./scripts/memory-cli.js update",
@@ -33,9 +36,11 @@
   },
   "homepage": "https://github.com/abarcenas29/ai-workflow-template#readme",
   "files": [
+    "bin/",
     ".agents/",
     ".github/workflows/",
     "scripts/",
+    "scripts/setup/",
     ".opencode/agents/",
     ".opencode/commands/",
     ".husky/",

package/scripts/setup/constants.js

@@ -0,0 +1,226 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// constants.js — Shared constants for the setup command pipeline
+// ═════════════════════════════════════════════════════════════════════════════
+
+// ── Package identity ──────────────────────────────────────────────────────────
+
+/** npm package name */
+export const PACKAGE_NAME = '@abarcenas/ai-workflow-template'
+
+/** CLI binary name (npm "bin" entry) */
+export const BIN_NAME = 'ai-workflow-setup'
+
+// ── Idempotency markers ───────────────────────────────────────────────────────
+
+/**
+ * First-line comment injected into every template hook file.
+ * Used to detect whether an existing consumer hook was installed by us
+ * (idempotency check in hooks.js, CASE C). Must be the first line of
+ * each template hook file.
+ */
+export const HOOK_MARKER = '# Managed by @abarcenas/ai-workflow-template setup'
+
+/**
+ * Separator inserted between a consumer's existing hook content and our
+ * appended content during hook merging (hooks.js, CASE D).
+ */
+export const HOOK_MERGE_SEPARATOR = '# --- @abarcenas/ai-workflow-template ---'
+
+// ── Template hook definitions ─────────────────────────────────────────────────
+
+/**
+ * Map of hook names → metadata for every git hook the setup command manages.
+ *
+ * Each entry carries:
+ *   `source`      — Relative path from the package root to the template file.
+ *                   Resolved at runtime by hooks.js.
+ *   `content`     — Exact content that will be written (or appended) to the
+ *                   consumer's hook file. This mirrors the actual file on disk.
+ *   `description` — Human-readable purpose, shown in output messages.
+ */
+export const TEMPLATE_HOOKS = {
+  'pre-commit': {
+    source: '.husky/pre-commit',
+    content:
+      '# Managed by @abarcenas/ai-workflow-template setup\n\nnode scripts/bump-version.js\nnode scripts/validate-memory-schema.js\n',
+    description:
+      'Auto-bump version + validate memory-bank schema before commits',
+  },
+  'post-merge': {
+    source: '.husky/post-merge',
+    content: [
+      '# Managed by @abarcenas/ai-workflow-template setup',
+      '#!/bin/sh',
+      '. "$(dirname "$0")/_/husky.sh"',
+      '',
+      '# After git pull/merge, check if memory-bank files changed',
+      '# and update the vector index incrementally',
+      '',
+      'if git diff HEAD@{1} --name-only 2>/dev/null | grep -q "^memory-bank\\|^docs/"; then',
+      '  echo "[memory-bank] Memory bank files changed. Updating vector index..."',
+      '  node scripts/memory-cli.js update 2>/dev/null || echo "[memory-bank] Index update skipped (service not installed)"',
+      'fi',
+      '',
+    ].join('\n'),
+    description:
+      'Auto-update memory bank vector index after pull/merge',
+  },
+}
+
+// ── CI/CD environment detection ───────────────────────────────────────────────
+
+/**
+ * Environment variable names checked to determine if the command is running
+ * inside a CI/CD pipeline.
+ *
+ * When `isCI()` from utils.js returns true, the setup command skips git hook
+ * installation entirely (REQ-07) and only performs file sync + memory-bank
+ * scaffolding.
+ *
+ * @note `NODE_ENV` is included here but is evaluated as
+ *       `process.env.NODE_ENV === 'production'` (equality check), whereas
+ *       all other entries are evaluated as simple truthiness checks.
+ */
+export const CI_ENV_VARS = [
+  'CI',
+  'GITHUB_ACTIONS',
+  'GITLAB_CI',
+  'CIRCLECI',
+  'TRAVIS',
+  'JENKINS_URL',
+  'BITBUCKET_BUILD_NUMBER',
+  'APPVEYOR',
+  'CODEBUILD_BUILD_ID',
+  'AZURE_HTTP_USER_AGENT',
+  'NODE_ENV',
+]
+
+// ── CLI flags ─────────────────────────────────────────────────────────────────
+
+/**
+ * Map of CLI argument strings (long and short forms) to their canonical
+ * camelCase property names on the flags object.
+ *
+ * Usage: `parseCliArgs()` in utils.js iterates over argv, looks up each
+ * element in this map, and sets the corresponding property to `true` on
+ * the returned flags object.
+ */
+export const SUPPORTED_FLAGS = {
+  '--force': 'force',
+  '--dry-run': 'dryRun',
+  '--yes': 'yes',
+  '-y': 'yes',
+  '--skip-hooks': 'skipHooks',
+  '--skip-prepare': 'skipPrepare',
+  '--skip-sync': 'skipSync',
+  '--help': 'help',
+  '-h': 'help',
+  '--version': 'version',
+  '-v': 'version',
+  '--quiet': 'quiet',
+  '-q': 'quiet',
+  '--verbose': 'verbose',
+  '-V': 'verbose',
+}
+
+// ── Exit codes ────────────────────────────────────────────────────────────────
+
+/**
+ * Numeric exit codes returned by the setup command.
+ *
+ *   SUCCESS  → All phases completed without errors or warnings
+ *   WARNINGS → One or more phases had non-fatal warnings (exit code 1)
+ *   FATAL    → A required phase encountered an unrecoverable error (exit code 2)
+ */
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  WARNINGS: 1,
+  FATAL: 2,
+}
+
+// ── Required directories ──────────────────────────────────────────────────────
+
+/**
+ * Relative paths (from the consumer project root) of directories that the
+ * setup command must ensure exist before running its pipeline.
+ */
+export const REQUIRED_DIRS = [
+  '.husky',
+  'memory-bank',
+]
+
+// ── Output symbols ────────────────────────────────────────────────────────────
+
+/**
+ * Unicode characters used as status indicators in the CLI output.
+ * Referenced by the ui.js module.
+ */
+export const UNICODE_CHARS = {
+  CHECK: '\u2713',  // ✓
+  WARN: '\u26A0',   // ⚠
+  CROSS: '\u2717',  // ✗
+  BULLET: '\u2022', // •
+  ARROW: '\u2192',  // →
+}
+
+// ── Memory bank stubs ─────────────────────────────────────────────────────────
+
+/**
+ * Template content for scaffolding a fresh memory-bank/ directory.
+ * Exact mirror of the `memoryBankStubs` object in `scripts/sync.js`
+ * (lines 204–254). Each key is a filename; each value is the file content.
+ *
+ * Used by the setup command's sync-phase when the consumer project lacks
+ * a memory-bank/ directory.
+ */
+export const MEMORY_BANK_STUBS = {
+  'projectbrief.md': `# projectbrief
+
+> Foundation document — defines core requirements and goals.
+
+- **Purpose**: {{describe project purpose}}
+- **Goals**: {{list project goals}}
+- **Scope**: {{define scope}}
+`,
+  'productContext.md': `# productContext
+
+> Why this project exists and what problems it solves.
+
+- **Problem**: {{describe the problem}}
+- **Solution**: {{describe the solution}}
+- **User Experience**: {{describe UX goals}}
+`,
+  'activeContext.md': `# activeContext
+
+> Current work focus, recent changes, next steps.
+
+- **Current Focus**: {{current task or goal}}
+- **Recent Changes**: {{list of recent changes}}
+- **Next Steps**: {{next actions}}
+`,
+  'systemPatterns.md': `# systemPatterns
+
+> Architecture, key decisions, design patterns.
+
+- **Architecture**: {{describe architecture}}
+- **Key Decisions**: {{list key technical decisions}}
+- **Patterns**: {{list design patterns in use}}
+`,
+  'techContext.md': `# techContext
+
+> Technologies, setup, constraints, dependencies.
+
+- **Stack**: {{list technologies}}
+- **Setup**: {{describe dev setup}}
+- **Constraints**: {{list technical constraints}}
+`,
+  'progress.md': `# progress
+
+> What works, what's left, current status.
+
+- **Working**: {{what's implemented and working}}
+- **To Build**: {{what remains}}
+- **Status**: {{overall project status}}
+- **Known Issues**: {{list known issues}}
+`,
+}