@abarcenas/ai-workflow-template 1.49.0 → 2.0.0

package/.agents/instructions/knowledgebase.instructions.md

@@ -65,7 +65,7 @@ Before debugging from scratch, search for similar errors and their known resolut
 Example queries:
 - "spawnScript child process hanging silent output"
 - "process.exit kills parent import module"
-- "npm postinstall blocked in v12"
+- "npm dependency lifecycle scripts blocked in v12"
 
 ### 3. Making Architectural Decisions
 
@@ -117,7 +117,7 @@ knowledgebase_search({
 **Finding specific error resolutions:**
 ```
 knowledgebase_search({
-    query: "npm postinstall execution blocked in v12 dependency lifecycle",
+    query: "npm dependency lifecycle script execution blocked in v12",
     topK: 3
 })
 ```

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

@@ -28,7 +28,7 @@
 **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
+- **npm v12 blocks dependency lifecycle scripts** — this is a critical ecosystem shift that affects ALL npm library distribution. Install-time 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
@@ -37,7 +37,7 @@
 - **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
+- **researcher**: Should explicitly investigate npm ecosystem changes (version-specific behavior, deprecations) — the npm v12 lifecycle-script 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
@@ -595,3 +595,48 @@
 - **reviewer (two-round shape)**: round 1 caught missing user-facing coverage; round 2 blocked the *new* mechanism for being wrong in both directions. A fix that introduces a heuristic deserves a dedicated review pass — reviewing it as part of the original change under-weights it.
 - **coder (docs for honest gaps)**: protect-but-don't-honour (`.agents-sync-ignore`) must be stated plainly in the README and in code comments. Shipping the storage without the semantics is acceptable only when it is impossible to mistake for working.
 - **all agents (knowledge retrieval)**: `memory_search` executed (cwd-scoped to this repo); `knowledgebase_search` **NOT executed** (PG vector unavailable — `DATABASE_URL` not configured). Neither retried nor treated as a task failure.
+
+## Session: 2026-11-01 — MCP `environment` Block Shadowing (`{env:X}` injects an empty string)
+
+**Pipeline:** coder (read-only investigation) → coder (fix + A/B shell verification) → tracker
+**Coverage:** N/A (one config-block deletion in `opencode.json`; no test or `scripts/` surface changed, so the Vitest suite is unaffected)
+**TDD Iterations:** 0 (support-driven bug fix, not TDD)
+
+**New knowledge:**
+- **`"environment": { "X": "{env:X}" }` in an OpenCode MCP server config injects an EMPTY STRING when the parent process lacks `X`.** It does not omit the key, pass `undefined`, or leave inheritance intact — it sets the variable to `""` in the child. Prefer **omitting the block entirely**: MCP children inherit the parent environment by default, so the block is redundant when the variable is set and actively harmful when it is not. **Universal pattern:** an "explicit passthrough" of a parent variable is not a no-op — it converts "absent" (inheritable/fallback-eligible) into "set but empty" (a real value that defeats every fallback).
+- **An injected empty string silently defeats a `dotenv` fallback, because dotenv never overwrites an existing key.** `import 'dotenv/config'` at the top of `scripts/mcp-knowledgebase-server.js` is powerless once `process.env.DATABASE_URL === ''`: dotenv's loader skips keys already present, so a valid `.env` three feet away is never consulted and the server reports "DATABASE_URL is not configured". **Universal pattern:** `dotenv` is a *default provider*, not a *repair mechanism* — it cannot distinguish "legitimately set" from "set to garbage by a wrapper", so upstream config must not pre-set keys it does not actually have values for. This is the same family as the established "script reads `process.env` without loading `.env`" gotcha, but inverted: here the variable exists and is still unusable.
+- **"Empty" and "unset" must be distinguished on both sides.** Diagnostic evidence that mattered: the MCP children showed `DATABASE_URL: <present but EMPTY>` while the parent showed it absent. A presence-only check (`if (process.env.DATABASE_URL)`) happens to work because `''` is falsy, but a presence-based diagnostic (`Object.hasOwn`, `env | grep`) reads "present" and sends you hunting in the wrong layer. Record emptiness, not just presence, when inspecting a child's environment.
+- **`.zshrc` exports never reach a daemon started outside an interactive shell.** `~/.zshrc` had an unconditional top-level `export DATABASE_URL=...`; `~/.zshenv` and `~/.zprofile` did not. `.zshrc` is sourced only for **interactive** shells, so `zsh -c '…'` → unset while `zsh -ic '…'` → set, and `opencode serve` launched from a non-interactive context never saw the value. **Universal pattern:** for any long-lived service/daemon that needs env vars, the correct homes are `~/.zshenv` (every zsh) or a launchd/systemd unit — never `.zshrc`. Use `zsh -c` vs `zsh -ic` as a two-line A/B test to prove whether an export is interactive-only.
+- **The A/B shell test is the decisive evidence, because it isolates the config from the shell.** `zsh -ic 'npm run kb:stats'` → connected (4 projects, 56 chunks, last sync 2026-10-31); `zsh -c 'npm run kb:stats'` → "DATABASE_URL not set". The delta is exactly `.zshrc` sourcing, which both confirms the diagnosis and proves the config fix (post-fix, connectivity is now conditioned only on how the host was started). **Universal pattern:** when a "missing env var" bug could be in the config OR in the launching environment, run the same command under an interactive and a non-interactive shell — the difference localizes the fault without touching either layer.
+- **One-entry-point-fixed, sibling-missed recurs again — audit the whole config for the same pattern.** The `github` server still carries `GITHUB_PERSONAL_ACCESS_TOKEN: "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"` (`opencode.json:22-23`) with its export at `~/.zshrc:6`, so it is very likely failing identically today. Deliberately left out of scope to keep verification clean, and recorded as an explicit follow-up rather than silently expanded. This is now the fourth appearance of this bug class in this project (dotenv imports, threshold defaults, `registerProject`, and now `{env:…}` passthrough).
+- **A "recommended fix" can become the defect — spikes assert state and go stale.** `docs/spike-kb-mcp-database-url-investigation.md` still claims the server has no env block and no dotenv import (both untrue today) and recommends adding the `environment` block that is now the root cause. A spike is a snapshot, not a living contract. **Universal pattern:** when a spike's recommendation is implemented and later reversed, the spike must be corrected or explicitly superseded — a stale recommendation is worse than no recommendation, because the next agent will implement it again.
+- **Long-lived MCP children do not reload config — a restart is part of the fix, not an afterthought.** The three live children (pids 50430, 55767, 58594 under `opencode serve` 26325) kept the injected `""` after the config edit, so the tools stayed broken while the files on disk were correct. This restates the established MCP-restart rule with a new cause: here it is a *config* change, not a code change, and it fails identically.
+- **A tracked-secret blob in history outlives the file.** Commit `d788f68` retains the previously tracked `.env` (a live-looking credential) in git history, and rotation is still outstanding. Removing the file from the tree does not remove the exposure; only rotation (and optionally a history purge) does — and rotation is a user-owned, non-automatable step.
+
+**Agent tuning notes:**
+- **coder (investigation)**: For "can process A see variable X?" questions, gather three independent evidence layers before theorizing — (1) the tool's own reported behavior, (2) the config file that wires the env, (3) the actual child-process environment. Read the *loader's* behavior in `node_modules` when a fallback is claimed to work; the dotenv no-overwrite rule was verified at source rather than assumed. Keep such investigations strictly read-only so the diagnosis can be reviewed before any change.
+- **coder (fix)**: Fix at the config layer, not by teaching the app to treat `""` as absent — the latter hides a defect class that affects every `{env:…}` entry. Validation for a JSON config edit should be concrete and cheap: `JSON.parse`, the entry's key set, all servers still present, and the removed key genuinely gone.
+- **reviewer / future auditors**: When reviewing MCP config, treat every `{env:…}` passthrough as a suspect, not a best practice — ask "what happens when the parent lacks this?" before approving. Check `environment` blocks against where the variable is actually exported (`.zshrc` vs `.zshenv`).
+- **tracker**: Record the durable rule (`"environment": { "X": "{env:X}" }` injects `""` when the parent lacks `X`; omit the block) as a config-level universal pattern, and pair it with the `.zshrc`-is-interactive-only fact — together they explain a failure mode that looks like an app bug, a dotenv bug, and a shell bug simultaneously. Never record the secret value, a prefix, or a full connection string; scheme/port/database are sufficient to make the record useful.
+- **all agents (knowledge retrieval)**: `memory_search` executed — its top hit was the stale spike document itself, which independently corroborated the "spike is stale" finding. `knowledgebase_search` **NOT executed** (PG vector unavailable — the live MCP child still holds the injected empty string, so this very bug made the cross-project layer unreachable). Neither retried nor treated as a task failure.
+
+## Session: 2026-11-01 — `github` MCP `{env:…}` Removal + Service Restart Topology (verify the premise)
+
+**Pipeline:** coder (config fix + live process probe) → tracker
+**Coverage:** N/A (one config-block deletion in `opencode.json`; no test or `scripts/` surface changed, so the Vitest suite is unaffected)
+**TDD Iterations:** 0 (support-driven bug fix, not TDD)
+
+**New knowledge:**
+- **Verify the premise before fixing — and before REPORTING — a latent defect.** Pipeline 16 predicted the `github` server was "likely failing identically" because it carried the same `environment: { GITHUB_PERSONAL_ACCESS_TOKEN: "{env:…}" }` block. Live process probing of the parent `opencode serve` process showed the variable **was present** (non-empty, length matching the shell-exported value, so the child inherited a real value) and that the server was connecting successfully. The `{env:X}` pattern only degrades to an injected `""` when the parent **lacks** `X`; where the parent has it, the block is a redundant no-op. Removing it was still correct — it eliminates the trap — but the defect was **latent, not active**, and the earlier "likely failing" prediction has been explicitly superseded in the record. **Universal pattern:** a config pattern that is *capable* of failing is not evidence that it *is* failing. Before reporting a defect as active, prove the failing precondition (here: probe the actual parent environment) — and when a later probe contradicts an earlier prediction, supersede it in writing rather than leaving a misleading claim standing.
+- **OpenCode service restart topology: `opencode serve --service` owns the config, the MCP spawning, and the environment.** The relevant chain was `-bash` → `opencode` client → `opencode serve --service` (its own process group, listening on a loopback port), which spawned the MCP children; several additional clients were attached to that same service. There is **no launchd job** — the service is started on demand by the **first** client and inherits **that** client's environment, then keeps it for the lifetime of the process. Durable consequences: (1) quitting the TUI, or any individual client, changes nothing — the service survives every client; (2) `opencode reload` re-reads configuration but **cannot change a running process's environment**, so it does not fix a missing env var; (3) a restart must originate from a process whose environment is already correct — `opencode service restart` from a fresh interactive shell, or better, move the exports to `~/.zshenv` so any on-demand start inherits them. **Universal pattern:** for any on-demand-supervised service, "restart the client" is not "restart the environment holder" — identify which process actually owns config + env, confirm how it was started (launcher/supervisor vs first-client inheritance), and restart *that* from a correctly-populated shell.
+- **A redundant `{env:…}` passthrough is only harmless while the parent has the value — that is exactly why it survives undetected.** The `knowledgebase` entry in the same file was *actually* broken (its variable was genuinely absent from the parent) while the `github` entry was *quietly* fine. Two entries, one identical pattern, opposite outcomes. **Universal pattern:** identical code/config defects do not have identical activations; a "same defect class, same failure" assumption will be wrong whenever the preconditions differ — check each instance's precondition separately.
+- **`headers` interpolation on a REMOTE MCP server is a different mechanism and is not the same defect.** The one `{env:…}` left in `opencode.json` is `context7` → `headers.CONTEXT7_API_KEY: "{env:CONTEXT7_TOKEN}"`. A remote server has no parent-environment inheritance and no `dotenv` fallback; request headers are its authentication path. A blanket "every `{env:…}` is suspect" sweep would have wrongly removed it. **Universal pattern:** distinguish *child-process environment passthrough* (local servers — omit the block) from *request-header interpolation* (remote servers — keep it); the defect class is scoped to the former.
+- **The consumer scaffold is where this defect class ships.** `opencode.mcp.example.json` still carries the same pattern for `github`, `playwright`, and `playwright-firefox`. The local fix corrects one repo; the scaffold propagates the trap to every adopting project. **Universal pattern:** when a defect is fixed in a live config, grep the shipped/example/scaffold configs for the same pattern — fixing the instance without fixing the distribution leaves the defect in the product.
+- **A diagnostic echo can put a live token in a session transcript.** One echo during this pipeline expanded a token variable into the transcript; it reached no file and no summary. **Universal pattern:** when probing a secret to prove presence, print presence/length only (`[ -n "$VAR" ]`, `${#VAR}`), never the expanded value — and if it does leak into a transcript, record the fact and recommend rotation rather than reproducing it in the permanent record.
+
+**Agent tuning notes:**
+- **coder (config fix)**: Confirm the entry's full key set after every edit (`type`, `command`, `enabled`), re-validate the JSON, and assert zero `environment` keys remain in the block plus all servers still present. When a sibling entry is fixed for the same pattern, do not assume this one is broken in the same way — probe the parent environment for the specific variable first and report latent vs active explicitly.
+- **coder (process probing)**: Never print a secret value; use presence tests and length only, and note that an older/stale child process may carry a different value than the current service (stale per-session MCP children coexist with fresh ones — probe the service, not a random child).
+- **reviewer / future auditors**: Ask "does the parent actually lack this variable?" before accepting a `{env:…}` entry as an active bug; accept config changes that remove a latent trap, but require the record to say latent rather than active. Distinguish remote-header interpolation from local-env passthrough, and check the example/scaffold config separately from the live one.
+- **tracker**: Record the corrected assumption as a **supersede** of the earlier prediction (name the earlier pipeline and the claim) so the log does not carry a contradiction; keep the restart topology as durable operational knowledge, not a one-off note; and for any transcript exposure record only the fact plus the rotation recommendation — never the value, prefix, fragment, or connection detail.
+- **all agents (knowledge retrieval)**: `memory_search` executed (its top hits surfaced the companion Pipeline 16 entries for both the `knowledgebase` and `github` fixes). `knowledgebase_search` **NOT executed** (PG vector unavailable — `DATABASE_URL` is still absent from the parent service until it is restarted). Neither retried nor treated as a task failure.

package/.agents/instructions/memory-schema.instructions.md

@@ -57,7 +57,7 @@ Docs files do not require `category`, `entities`, or strict heading structure. H
 
 ## Auto-Suggest on Normalization
 
-When `scripts/normalize-memory.js` runs (postinstall or manual), it:
+When `scripts/normalize-memory.js` runs — via `npx ai-workflow-setup`, `npm run memory:normalize`, or directly — it:
 - Adds missing frontmatter using filename, H1 title, and git modification date
 - Auto-suggests `tags` by scanning content for vocabulary keywords
 - Auto-suggests `entities` using regex patterns from `.vocabulary.json`

package/.github/workflows/npm-publish.yml

@@ -1,16 +1,52 @@
+# Publishes @abarcenas/ai-workflow-template to npm when work lands on main.
+#
+# - Trigger: push to main (i.e. a merged PR), plus a manual workflow_dispatch for
+#   retrying a run that failed after the merge. Tags play no part in publishing.
+# - Version: read from package.json. Nothing in CI derives it from a git ref.
+# - Bumping: handled locally by the Husky pre-commit hook (scripts/bump-version.js),
+#   which bumps the minor version on every commit. Whatever version is on main when
+#   the PR merges is the version that gets published.
+# - Safety: a preflight step hard-fails if that exact version is already on the
+#   registry, so a duplicate merge fails loudly instead of silently no-op'ing.
+
 name: Publish to npm
 
 on:
   push:
     branches:
       - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+# Serialize publishes: two quick merges must not both clear the preflight guard
+# and race each other at the registry. Never cancel — an in-flight publish should
+# be allowed to finish rather than be killed mid-upload.
+concurrency:
+  group: npm-publish-main
+  cancel-in-progress: false
 
 jobs:
   publish:
+    # This file is distributed to consumers, who may adapt it for their own
+    # package. Keep it inert anywhere but the upstream repo.
+    if: github.repository == 'abarcenas29/ai-workflow-template'
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v4
 
+      # A manual run may be started against any ref, and it would publish that
+      # ref's tree with the real NPM_TOKEN and a provenance attestation. Only
+      # main is releasable.
+      - name: Require main for manual runs
+        if: github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/main'
+        run: |
+          echo "::error::Manual publishes must run against refs/heads/main (got ${GITHUB_REF})."
+          exit 1
+
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
@@ -32,7 +68,39 @@ jobs:
           # The config defaults to headed mode; CI runners have no display.
           HEADLESS: 'true'
 
+      # Refuse to publish a version that already exists. Without this, merging a PR
+      # that forgot to bump package.json fails deep inside `npm publish` with an
+      # opaque 403, or (worse) is retried by hand against the wrong version.
+      - name: Ensure version is unpublished
+        run: |
+          NAME="$(node -p "require('./package.json').name")"
+          VERSION="$(node -p "require('./package.json').version")"
+
+          # The version must be a plain X.Y.Z: no ranges, no pre-release tags.
+          case "$VERSION" in
+            *[!0-9.]*|*..*|.*|*.) echo "::error::package.json version '${VERSION}' is not a plain X.Y.Z"; exit 1 ;;
+          esac
+
+          echo "Checking ${NAME}@${VERSION} on the registry..."
+          # One deterministic read of the published version list. Its exit status
+          # — not the text of an error message — decides whether the registry
+          # answered, so an auth/network/registry failure fails closed.
+          VERSIONS="$(npm view "${NAME}" versions --json)" || {
+            echo "::error::Registry read failed for ${NAME}. Refusing to publish."
+            exit 1
+          }
+
+          # `-F` keeps the dots in the version literal instead of regex wildcards,
+          # and the surrounding quotes anchor the match to a whole JSON string, so
+          # "2.0.0" cannot match inside "2.0.0-rc.1" or "12.0.0".
+          if printf '%s' "$VERSIONS" | grep -qF "\"${VERSION}\""; then
+            echo "::error::Version ${VERSION} is already published to npm. Bump package.json before merging to main."
+            exit 1
+          fi
+
+          echo "Version ${VERSION} is unpublished — proceeding."
+
       - name: Publish to npm
-        run: npm publish --access public
+        run: npm publish --access public --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.opencode/plugins/graphify.js

@@ -0,0 +1,22 @@
+// graphify OpenCode plugin
+// Injects a knowledge graph reminder before bash tool calls when the graph exists.
+import { existsSync } from "fs";
+import { join } from "path";
+
+export const GraphifyPlugin = async ({ directory }) => {
+  let reminded = false;
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (reminded) return;
+      if (!existsSync(join(directory, "graphify-out", "graph.json"))) return;
+
+      if (input.tool === "bash") {
+        output.args.command =
+          'echo "[graphify] knowledge graph at graphify-out/. For focused questions, run \`graphify query \"<question>\"\` (scoped subgraph, usually much smaller than GRAPH_REPORT.md) instead of grepping raw files. Read GRAPH_REPORT.md only for broad architecture context." && ' +
+          output.args.command;
+        reminded = true;
+      }
+    },
+  };
+};

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 abarcenas29
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,22 +1,29 @@
 # AI Workflow Template
 
-Publishable AI workflow starter pack for OpenCode — auto-syncing, version-managed, npm-distributed agent configuration suite with vector search memory.
+Publishable AI workflow starter pack for OpenCode — explicitly-synced, version-managed, npm-distributed agent configuration suite with vector search memory.
 
 ## Install
 
 ```bash
-npm install @abarcenas/ai-workflow-template
+npm install --save-dev @abarcenas/ai-workflow-template
+npx ai-workflow-setup
 ```
 
-The package runs `postinstall` to sync files; for full setup including git hooks, use the setup command below.
+This package is a **CLI/scaffold, not a runtime library** — it has no `require`/`import` entry point, so importing it is not supported by design. Installing it copies nothing into your project and ships no install/`postinstall` hook; `npx ai-workflow-setup` is the only setup path and does all file syncing, memory-bank scaffolding, and hook installation.
 
-## Git Hook Setup
+### Upgrading to 2.0.0
+
+2.0.0 removed the install-time `postinstall` sync, so upgrading no longer copies anything into your project. After installing the new version, run the setup command once:
 
 ```bash
-# One-step setup (fetches from npm registry automatically):
-npx @abarcenas/ai-workflow-template
+npx ai-workflow-setup
+```
 
-# Or if the package is already installed:
+Node 20 support was also dropped (`engines.node` is now `>=22`), and the package no longer declares a `main` entry point — it is a scaffold CLI, not an importable library.
+
+## Git Hook Setup
+
+```bash
 npx ai-workflow-setup
 ```
 
@@ -29,11 +36,13 @@ npx ai-workflow-setup
 | 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 |
+| Skills | Refreshes pinned skills from upstream (skipped with `--skip-sync`) |
+| Knowledgebase | Registers the project with the centralized knowledgebase (skipped with `--skip-knowledgebase`) |
 
 ### Options
 
 ```bash
-npx ai-workflow-setup --dry-run        # Preview without changes
+npx ai-workflow-setup --dry-run        # Preview hooks/prepare/skills, skip sync
 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
@@ -48,7 +57,7 @@ npx ai-workflow-setup --help           # Show all options
 - **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.
+> **No install-time scripts:** npm 12+, pnpm 10+, and Yarn 4 block dependency lifecycle scripts by default. This package ships no `postinstall`; everything runs when you explicitly invoke `npx ai-workflow-setup`.
 
 ## What This Package Does
 
@@ -59,10 +68,12 @@ npx ai-workflow-setup --help           # Show all options
 - **Memory bank** — persistent project context with sqlite-vec semantic search
 - **Caveman mode** — ultra-compressed communication for token efficiency
 - **Playwright + Vitest testing** — E2E browser tests, unit tests with v8 coverage (≥90%)
-- **Version auto-bumping + auto-publishing** — Husky-managed, npm publish on merge to `main`
+- **Version auto-bumping + auto-publishing** — Husky-managed; npm publish on merge to `main`
 - **graphify knowledge graph** — queryable code-level relationship mapping
 
-## Sync Behavior
+## Maintainer sync (in this repo)
+
+`npm run sync` is a maintainer command defined in this repository's own `package.json`. It is not shipped to consumers — consumer projects sync by running `npx ai-workflow-setup`, which invokes the same sync engine.
 
 ```bash
 npm run sync -- --dry-run   # Preview changes without applying
@@ -78,7 +89,7 @@ npm run sync                # Normal sync
 - Project-owned files are never overwritten or pruned after creation, and `--force` cannot replace them
 - GitHub Actions workflows are excluded from consumer sync (`.github/workflows/`)
 
-> `--dry-run` previews copies and prunes, but missing scaffold files (memory-bank stubs, `opencode.json`, `AGENTS.project.md`, `.prettierignore`) are still created. This matches the pre-existing scaffold behaviour.
+> `npx ai-workflow-setup --dry-run` previews the hooks, prepare, and skills phases but skips sync, so no files are copied or pruned and no scaffold files are created. For a preview of sync itself, run `npm run sync -- --dry-run` in this repository; consumers sync with `npx ai-workflow-setup`.
 
 ### Project-owned files
 
@@ -107,11 +118,18 @@ Post-install, your project receives this structure:
 ├── instructions/   # Framework, workflow, and security guidance
 ├── skills/         # 34 specialized AI skills
 └── prompts/        # Reusable prompt templates
-.opencode/agents/   # Orchestrator + specialized sub-agents
-.github/workflows/  # CI/CD automation (excluded from sync)
-docs/               # Guides (e.g. playwright-mcp-configuration.md)
+.opencode/
+├── agents/         # Orchestrator + specialized sub-agents
+├── commands/       # Slash commands
+└── plugins/        # graphify knowledge-graph plugin
+memory-bank/        # Persistent project context (+ tasks/)
+scripts/            # Sync, memory, and knowledgebase CLI helpers
 AGENTS.md           # Master instruction file with agent guidance
 AGENTS.project.md   # Project-owned rules (recreated if deleted, never overwritten)
+opencode.json       # OpenCode config (project-owned after creation)
+.prettierignore     # Formatter coverage for managed files (project-owned)
+skills-lock.json    # Pinned skill versions
+.github/workflows/  # Repo-only — never synced to consumers
 ```
 
 ## Multi-Agent Orchestrator
@@ -149,7 +167,7 @@ Invoke the orchestrator with `@orchestrator` followed by your task:
 
 ### MCP Tooling
 
-Some agents require MCP servers configured in `opencode.mcp`:
+Some agents require MCP servers configured in `opencode.json` (template: `opencode.mcp.example.json`):
 
 | Agent | Required MCP | Purpose |
 | --- | --- | --- |
@@ -158,6 +176,9 @@ Some agents require MCP servers configured in `opencode.mcp`:
 | Reviewer | GitHub | PR and issue management |
 | Deployer | GitHub | Releases, Actions |
 
+Playwright MCP is configured twice for browser parity: `playwright` (Google Chrome — the `chrome` channel, which `@playwright/mcp` uses by default, so Google Chrome must be installed) and `playwright-firefox` (Firefox, `--browser firefox --isolated`). Each server needs its own permission entry (`playwright_*`, `playwright-firefox_*`), and Firefox must be installed first with `npx playwright install firefox` — see [`docs/playwright-mcp-configuration.md`](https://github.com/abarcenas29/ai-workflow-template/blob/main/docs/playwright-mcp-configuration.md#browser-selection). Existing `opencode.json` files are never rewritten by sync, so upgrading projects must add the `playwright-firefox` block and its permission by hand.
+
+
 ## TDD Orchestrator
 
 Strict Test-Driven Development through the RED → GREEN → REFACTOR/VERIFY cycle:
@@ -219,7 +240,7 @@ projectbrief.md → productContext.md / systemPatterns.md / techContext.md → a
 
 ### Document Schema
 
-All memory-bank files use YAML frontmatter (`id`, `title`, `updated`, `tags`, `entities`, `category`) for search indexing; see `memory-bank/.vocabulary.json` for the controlled vocabulary. `npm install` runs `normalize-memory.js` to add frontmatter; the Husky pre-commit hook rejects invalid frontmatter. Task commands: `add task`, `update task [ID]`, `show tasks [filter]`.
+All memory-bank files use YAML frontmatter (`id`, `title`, `updated`, `tags`, `entities`, `category`) for search indexing; see `memory-bank/.vocabulary.json` for the controlled vocabulary. `npx ai-workflow-setup` runs `normalize-memory.js` to add frontmatter; the Husky pre-commit hook rejects invalid frontmatter. Task commands: `add task`, `update task [ID]`, `show tasks [filter]`.
 
 ### Token Efficiency
 
@@ -258,7 +279,20 @@ Husky auto-bumps versions on every commit: minor by default (`1.2.0 → 1.3.0`),
 
 ## Publish Flow
 
-GitHub Actions automatically publishes to npm when merging to `main`.
+GitHub Actions publishes to npm when work lands on `main` — that is, when a PR is merged. The version published is whatever `package.json` says at merge time (the Husky pre-commit hook already bumped the minor version):
+
+```bash
+git push origin feat/my-change
+gh pr merge --merge    # merging to main publishes that version
+```
+
+A version already on the registry fails the run instead of republishing, so bump `package.json` rather than re-running against the same version. To retry a failed publish, dispatch against `main` — there are no inputs:
+
+```bash
+gh workflow run npm-publish.yml --ref main
+```
+
+Pushing a `v*` tag does not publish anything.
 
 Add `NPM_TOKEN` to GitHub repository secrets:
 
@@ -283,7 +317,7 @@ npm run test:unit:watch    # Watch mode for unit tests
 npm run memory:rebuild     # Build the vector index (one-time, ~8 min)
 npm run memory:update      # Incremental index update (seconds)
 npm run memory:search "tdd orchestrator status"
-npm run memory:normalize   # Normalize frontmatter (runs automatically on install)
+npm run memory:normalize   # Normalize frontmatter (also runs during npx ai-workflow-setup)
 ```
 
 ### Testing
@@ -301,8 +335,8 @@ npm run memory:normalize   # Normalize frontmatter (runs automatically on instal
 1. Edit files in `.agents/`, `docs/`, or `scripts/`
 2. Test changes locally
 3. Commit (triggers auto-version bump)
-4. Merge to `main` (triggers npm publish)
-5. Consumers run `npm install` to get updates
+4. Merge the PR to `main` (triggers npm publish)
+5. Consumers install the new version, then re-run `npx ai-workflow-setup` to sync
 
 ## Important Notes
 
@@ -312,5 +346,5 @@ npm run memory:normalize   # Normalize frontmatter (runs automatically on instal
 - Do not add `AGENTS.project.md` or `opencode.json` to `package.json` `files`: both are scaffolded create-if-absent and must never ship from the package
 - `AGENTS.md` is the main instruction file agents should read
 - Package assumes the public npm registry
-- Playwright MCP integration is documented in `docs/`
+- Playwright MCP integration is documented in [`docs/playwright-mcp-configuration.md`](https://github.com/abarcenas29/ai-workflow-template/blob/main/docs/playwright-mcp-configuration.md)
 - Run `npx ai-workflow-setup` after install to configure git hooks (npm v12+ compatible)

package/memory-bank/.vocabulary.json

@@ -56,6 +56,7 @@
       "dotenv",
       "embeddings",
       "env-remediation",
+      "env-var-shadowing",
       "feature-vocab-sync",
       "fix-kb-registerproject",
       "float32array",
@@ -65,11 +66,13 @@
       "knowledgebase",
       "learned-knowledge",
       "mcp",
+      "mcp-config",
       "package-structure",
       "pgvector",
       "pipeline-follow-up",
       "pre-commit",
       "readme",
+      "restart",
       "security",
       "test-hardening",
       "vocabulary"

package/opencode.mcp.example.json

@@ -44,6 +44,18 @@
       "timeout": 120000,
       "enabled": true
     },
+    "playwright-firefox": {
+      "type": "local",
+      "command": ["node", "scripts/mcp/playwright-mcp-launcher.js"],
+      "environment": {
+        "BROWSER": "firefox",
+        "ISOLATED": "true",
+        "HEADLESS": "{env:HEADLESS}",
+        "VIEWPORT": "{env:VIEWPORT}"
+      },
+      "timeout": 120000,
+      "enabled": true
+    },
     "example-server": {
       "type": "local",
       "command": ["npx", "-y", "your-mcp-package"],
@@ -66,6 +78,7 @@
     "mcp-everything_*": "allow",
     "angular-cli_*": "allow",
     "playwright_*": "allow",
+    "playwright-firefox_*": "allow",
     "context7_*": "allow",
     "memory-bank_*": "allow"
   }

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.49.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",
+  "version": "2.0.0",
+  "description": "OpenCode scaffolding CLI for AI-assisted development workflows — syncs agent configurations, skills, memory bank, and reusable prompts into any project.",
   "bin": {
     "ai-workflow-setup": "./bin/setup.js"
   },
@@ -17,7 +16,6 @@
     "test:unit:watch": "vitest",
     "prepare": "husky",
     "sync": "node ./scripts/sync.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",
@@ -30,31 +28,43 @@
     "type": "git",
     "url": "git+https://github.com/abarcenas29/ai-workflow-template.git"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "opencode",
+    "ai-agents",
+    "scaffold",
+    "mcp",
+    "memory-bank",
+    "developer-tools"
+  ],
+  "author": "Aldrich Allen Barcenas <aldrich.barcenas@gmail.com>",
   "license": "ISC",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "bugs": {
     "url": "https://github.com/abarcenas29/ai-workflow-template/issues"
   },
   "homepage": "https://github.com/abarcenas29/ai-workflow-template#readme",
-  "//": "Never add AGENTS.project.md or opencode.json to files: both are scaffolded create-if-absent at the consumer root and must not ship from the package.",
   "files": [
     "bin/",
     ".agents/",
     ".github/workflows/",
     "scripts/",
-    "scripts/setup/",
     ".opencode/agents/",
     ".opencode/commands/",
+    ".opencode/plugins/",
     ".husky/",
     "memory-bank/.vocabulary.json",
     "AGENTS.md",
     ".prettierignore",
     "opencode.mcp.example.json",
     "skills-lock.json",
-    ".husky/post-merge",
-    ".husky/post-commit"
+    "LICENSE"
   ],
   "devDependencies": {
     "@playwright/test": "^1.59.1",

package/scripts/bump-version.js

@@ -1,10 +1,11 @@
-import { readFileSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { execSync } from 'child_process'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkgPath = resolve(__dirname, '../package.json')
+const lockPath = resolve(__dirname, '../package-lock.json')
 
 // Opt-out: SKIP_BUMP=1 keeps the current version (e.g. when a batch of commits
 // is one logical change set and should yield a single bump).
@@ -32,5 +33,20 @@ const newVersion =
 
 pkg.version = newVersion
 writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
-execSync('git add package.json')
+
+// Keep the lockfile's root version in sync so `npm ci` does not report a
+// mismatch after the hook stages the commit.
+if (existsSync(lockPath)) {
+  const lock = JSON.parse(readFileSync(lockPath, 'utf8'))
+  lock.version = newVersion
+  if (lock.packages && lock.packages['']) {
+    lock.packages[''].version = newVersion
+  }
+  writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n')
+  execSync('git add package.json')
+  execSync('git add package-lock.json')
+} else {
+  execSync('git add package.json')
+}
+
 console.log(`Version bumped: ${current} → ${newVersion}`)