@abarcenas/ai-workflow-template 1.44.0 → 1.45.0

package/.agents/instructions/agent.instructions.md

@@ -12,7 +12,7 @@ Instructions for creating effective and maintainable custom agent files that pro
 - Target audience: Developers creating custom agents for opencode
 - File format: Markdown with YAML frontmatter
 - File naming convention: lowercase with hyphens (e.g., `test-specialist.agent.md`)
-- Location: `.agents/agents/` directory (repository-level) or `.opencode/agents/` directory
+- Location: `.opencode/agents/` directory (repository-level)
 - Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks
 - Official documentation: [opencode.ai](https://opencode.ai)
 
@@ -191,7 +191,7 @@ Structure each step invocation with:
 ```text
 Step 1: Transform raw input data
 Agent: data-processor
-Spec: .agents/agents/data-processor.agent.md
+Spec: .opencode/agents/data-processor.agent.md
 Context: projectName, basePath
 Input: basePath/raw/
 Output: basePath/processed/
@@ -199,7 +199,7 @@ Expected: write basePath/processed/summary.md
 
 Step 2: Analyze processed data (depends on Step 1 output)
 Agent: data-analyst
-Spec: .agents/agents/data-analyst.agent.md
+Spec: .opencode/agents/data-analyst.agent.md
 Context: projectName, basePath
 Input: basePath/processed/
 Output: basePath/analysis/
@@ -363,7 +363,7 @@ When invoking a sub-agent, pass all context through descriptive instructions in
 Example (prompt template):
 
 ```text
-This phase must be performed as the agent "documentation-writer" defined in ".agents/agents/documentation-writer.agent.md".
+This phase must be performed as the agent "documentation-writer" defined in ".opencode/agents/documentation-writer.agent.md".
 
 IMPORTANT:
 - Read and apply the entire .agent.md spec.
@@ -394,19 +394,19 @@ Example of a simple orchestrator that validates code through multiple specialize
 ```text
 Step 1: Security Review
 Agent: security-reviewer
-Spec: .agents/agents/security-reviewer.agent.md
+Spec: .opencode/agents/security-reviewer.agent.md
 Context: repository name, PR number, base path
 Output: security-review.md
 
 Step 2: Test Coverage
 Agent: test-coverage
-Spec: .agents/agents/test-coverage.agent.md
+Spec: .opencode/agents/test-coverage.agent.md
 Context: repository name, PR number, base path
 Output: coverage-report.md
 
 Step 3: Aggregate
 Agent: review-aggregator
-Spec: .agents/agents/review-aggregator.agent.md
+Spec: .opencode/agents/review-aggregator.agent.md
 Context: repository name, PR number, base path
 Output: final-review.md
 ```
@@ -456,7 +456,7 @@ Use consistent variable naming conventions:
 
 ### Repository-Level Agents
 
-- Location: `.agents/agents/` or `.opencode/agents/`
+- Location: `.opencode/agents/`
 - Scope: Available only in the specific repository
 - Access: Uses repository-configured MCP servers from `opencode.json`
 
@@ -491,7 +491,7 @@ Use consistent variable naming conventions:
 ### File Structure
 
 - [ ] Filename follows lowercase-with-hyphens convention
-- [ ] File placed in correct directory (`.agents/agents/` or `.opencode/agents/`)
+- [ ] File placed in correct directory (`.opencode/agents/`)
 - [ ] Filename uses only allowed characters
 - [ ] File extension is `.agent.md`
 
@@ -564,7 +564,7 @@ Use consistent variable naming conventions:
 ### Organizational Issues
 
 - ❌ Filename doesn't reflect agent purpose
-- ❌ Wrong directory (using `.github/agents/` instead of `.agents/agents/`)
+- ❌ Wrong directory (using `.github/agents/` instead of `.opencode/agents/`)
 - ❌ Using spaces or special characters in filename
 - ❌ Duplicate agent names causing conflicts
 

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

@@ -407,3 +407,63 @@
 - **unit-tester**: Independently re-prove negative-assertion non-vacuity with a real temp mutation (inject the forbidden pattern into a scoped file → test FAILS → `git checkout` restore → PASSES). Independently verify git state: `git log --oneline -3` order, `git ls-files .env` empty, commit-scope diffs (`--name-status`), local `.env` preserved. Grep the commit TREES for the secret (`git grep`), not just the working tree.
 - **reviewer**: For a security remediation review, verify: gitignore line present, `git ls-files` empty, local file preserved, `git grep` 0 hits in HEAD AND HEAD~1, commit scopes exact, redaction complete across all committed docs. Check for the two re-leak footguns explicitly: (1) untracked secret-bearing files, (2) uncommitted working-tree entries (memory-bank) that quote the secret in verification commands — these are the classic ways a "clean" commit still leaks. When the working tree is dirty with the secret, DO NOT append your own memory-bank entry until it is fixed (appending entrenches the leak). Check derived indexes for residue (memory.db WAL) — `memory_rebuild` alone may not purge; VACUUM may be required.
 - **tracker**: When documenting a security pipeline, use ONLY the established redacted forms (`<REDACTED>` or the short truncated prefix) — never reproduce the full leaked value, including inside quoted grep commands in docs (that is exactly how the leak re-entrenched this pipeline). Record the tracked-secret remediation pattern (git rm --cached + gitignore + redact-all-sources + commit split) as a universal pattern, and reuse the canonical `projectId` from `require('./package.json').name` (`@abarcenas/ai-workflow-template`) when re-indexing this session into the PG knowledgebase.
+
+## Session: 2026-09-14 — Stale Path Reference Cleanup + Env-Var Fail-Fast (vendor-neutral defaults)
+
+**Pipeline:** coder (2 tasks) → reviewer (✅ APPROVED) → tracker
+**Coverage:** N/A (documentation + Python helper scripts only; Vitest suite 15 files / 285 tests unaffected)
+**TDD Iterations:** 0 (quick-fix pipeline, not TDD)
+
+**New knowledge:**
+- **A ported instruction file can carry a mechanically-renamed but non-existent path for months** — `.agents/instructions/agent.instructions.md` referenced `.agents/agents/` in 10 places because the original Copilot→opencode port mechanically substituted `.github/agents/` → `.agents/agents/` (logged at `docs/tracker-log.md` line 109 of the 2026-06-25 standalone entry) without verifying the directory exists. All real agent specs live in `.opencode/agents/`. **Universal pattern:** after any bulk find-and-replace/rebase of path references, verify EACH new path exists on disk — a plausible-looking rename (`.github/agents/` → `.agents/agents/`, both in the `.agents/` family) is exactly the kind of change that silently produces a dead path.
+- **Freeze historical audit-trail docs; fix only live docs** — `docs/tracker-log.md`, `docs/.orchestrator-log.md`, `memory-bank` history, and `learned-knowledge.instructions.md` deliberately keep the literal `.agents/agents` string as an accurate record of past state; editing them would falsify the audit trail. This is the third pipeline to apply the "historical documentation freeze" precedent (MCP Config Rename, README trim). **Universal pattern:** when correcting a stale reference, classify hits into live vs historical and only edit live docs.
+- **Vendor-neutral defaults: fail fast on an unset env var instead of hardcoding a model** — replacing `os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5")` with `os.environ.get("CAVEMAN_MODEL")` + an explicit `RuntimeError` when unset removes a vendor lock-in default and converts a silent misconfiguration into an actionable failure. **Universal pattern:** a template/distributed tool should not hardcode a vendor-specific model/endpoint default; require the env var and fail with a message that NAMES the variable and shows the format (`export CAVEMAN_MODEL="<model-id>"`).
+- **Fail-fast exceptions must not be swallowed by sibling `except` clauses** — the `RuntimeError` is raised INSIDE the `try:` whose sibling handler is `except ImportError: pass` (which falls through to the `claude --print` CLI fallback). Because `RuntimeError` is not an `ImportError`, it correctly propagates. The reviewer explicitly verified this propagation path (the narrow except must not be broadened to a bare `except:`). **Universal pattern:** when adding a fail-fast raise inside an existing try/except, confirm the exception type is not caught by any handler in scope.
+- **Byte-identical duplicate files must be edited in lockstep and verified with `cmp`** — `.agents/skills/compress/` and `.agents/skills/caveman-compress/` hold duplicate `compress.py` copies; the fix was applied to both and the reviewer confirmed byte-identity via `cmp`. **Universal pattern:** duplicated files drift silently — edit all copies together and make `cmp`/`diff` a verification step, not just a claim.
+- **`CAVEMAN_MODEL` is required but undocumented** — after making the env var mandatory, the skill docs (`.agents/skills/compress/SKILL.md`, `.agents/skills/caveman-compress/SKILL.md`, `.agents/skills/caveman-compress/README.md`, `.agents/skills/caveman-compress/SECURITY.md`) still mention only `ANTHROPIC_API_KEY` and the CLI fallback. **Universal pattern:** whenever a code change makes a new env var/flag REQUIRED, grep the docs for the sibling env vars (here `ANTHROPIC_API_KEY`) and add the new one to the same sections — a required config knob that is undocumented is a support trap.
+
+**Agent tuning notes:**
+- **coder**: For a stale-path task, enumerate ALL hits first and split "live docs" from "historical audit trail"; remap a non-existent referenced filename to the REAL equivalent you verify on disk (here `implementation-plan.agent.md` → `implementer.agent.md`) rather than inventing a file. For env-var defaults, grep for sibling copies of the script and keep them byte-identical.
+- **reviewer**: Independently verify (a) each relinked target exists, (b) 0 stale refs remain in live docs only, (c) the fail-fast exception actually propagates past narrower `except` clauses, and (d) duplicated files are byte-identical. Flag doc/`.gitignore` gaps (an undocumented required env var; untracked `__pycache__`) as NON-blocking recommendations rather than blockers when core behavior is correct.
+- **tracker**: Record the "bulk path rename must be existence-verified" and "vendor-neutral fail-fast default" patterns as universal — both recurred here (a long-ago ported instruction file; a vendor default copied into two duplicate scripts). When a pipeline touches only docs + non-test helper scripts, state explicitly that the Vitest suite is unaffected.
+
+## Session: 2026-09-14 — Pipeline 11 Follow-ups (required-env-var docs + multi-commit auto-bump side effect)
+
+**Pipeline:** coder (3 tasks) → reviewer (✅ APPROVED) → deployer (5 atomic commits) → tracker
+**Coverage:** N/A (documentation + `.gitignore` + agent frontmatter only; Vitest suite unaffected)
+**TDD Iterations:** 0 (quick-fix follow-up pipeline, not TDD)
+
+**New knowledge:**
+- **Required-env-var documentation must describe EACH auth/branch path, not just the var's existence** — the `CAVEMAN_MODEL` docs added in this pipeline are deliberately conditional: "When `ANTHROPIC_API_KEY` is set, the script calls the Anthropic API directly and REQUIRES `CAVEMAN_MODEL` … it fails fast with a clear error if unset. When relying on the `claude` CLI fallback, no model variable is needed." Writing a bare "`CAVEMAN_MODEL` is required" would be wrong — it only applies to one of the two branches. **Universal pattern:** when a required config knob applies to only one code path, document the conditional (which path requires it, which does not) — an unconditional claim misleads users of the other path. This extends the prior session's "required env var must be documented alongside sibling env vars" with *which branch* precision.
+- **A partial auth-behavior doc is still incomplete — enumerate every branch** — the reviewer flagged (non-blocking) that the "`anthropic` SDK not installed" edge is undocumented. The actual control flow has three states: (1) API key set + SDK importable → direct API + requires `CAVEMAN_MODEL`; (2) API key set + SDK missing (`except ImportError: pass`) → falls through to the `claude` CLI (no model var); (3) API key unset → `claude` CLI. Documenting only the SDK-present and no-key paths leaves the middle state implied. **Universal pattern:** when documenting a try/except-fallback flow, count the branches and describe each — a two-path description of a three-path flow is a latent support trap.
+- **Precisely inventory a large PRE-EXISTING diff before committing — never blind `git add`** — the pipeline committed a 14-file working-tree diff it did not author (the `model:` frontmatter removals, mtime 2026-09-13). The coder characterized it exactly first: 14 files, exactly **one deletion each** (0 insertions/1 deletion per file, 1-deletion hunk, no other changes), two distinct values (`deepseek/deepseek-v4-pro` ×7 / `deepseek/deepseek-v4-flash` ×7), and `git grep '^model:' HEAD -- .opencode/agents` returning the same 14 files. That inventory made a scoped, atomic `chore(agents): remove hardcoded model bindings from agent definitions` commit safe and reviewable. **Universal pattern:** a pre-existing diff must be inventoried (`git diff --stat` + per-file hunk inspection) and committed with a scope-accurate message; blind staging can mix unrelated hunks or ship unexpected deletions.
+- **Committing a PRIOR pipeline's uncommitted docs is a valid close-the-loop move** — the deployer's `docs:` commit (`4f84947`) shipped the previous Pipeline 11 tracker record (tracker-log entry + index rows + learned-knowledge session + memory-bank updates) that had been written but never committed. Previously this work was left in the working tree (Pipeline 11's own note: "No commit made by this pipeline — the orchestrator handles staging/commit"). Committing it as its own `docs:` commit closed the loop and left a clean tree. **Universal pattern:** when a pipeline leaves documentation uncommitted, a later deployer step should commit it as a correctly-scoped `docs:` commit rather than letting it accumulate indefinitely.
+- **The Husky pre-commit `bump-version.js` hook auto-bumps the MINOR version on EVERY commit and has no `SKIP_BUMP` guard** — across this pipeline's 5 sequential commits, `package.json` moved **1.44.0 → 1.49.0** (+0.1.0 × 5) with no intended release. The deployer deliberately did **not** use `--no-verify` (contrast Pipeline 10, where `--no-verify` + manual validator re-run was the compensating control). This is the second time the auto-bump has bitten (first documented 2026-08-02). **Universal pattern:** with an unconditional bump-on-commit hook, an N-commit pipeline produces N minor bumps — before cutting a release, either settle/revert the version or add a `SKIP_BUMP` env guard; and when `--no-verify` IS used, always re-run `validate-memory-schema.js` + `vocab-sync.js` manually.
+- **Docs + `.gitignore` + YAML-frontmatter changes leave the test suite bit-identical** — no test-relevant surface changed, so the Vitest suite was explicitly declared unaffected. **Universal pattern:** state this invariant explicitly when a pipeline touches no test/`scripts/` surface, so the missing coverage delta is not mistaken for a regression signal.
+
+**Agent tuning notes:**
+- **coder**: For doc follow-ups, describe every branch of the code path being documented (primary + fallback + edge like SDK-missing) and prefer a complete-sentence section (e.g. `## Configuration`) when the rule is conditional; a terse one-liner invites ambiguity. When a pre-existing diff is to be committed, inventory it first (`git diff --stat`, per-file hunk check) and never stage blindly.
+- **reviewer**: For doc-only changes, verify wording precision against the ACTUAL code branches — flag terse/ambiguous lines (e.g. `README.md:84`) and missing branches (the "SDK not installed" edge) as non-blocking minors. Confirm the documented fail-fast still matches the code's exception type and propagation.
+- **deployer**: Before a multi-commit pipeline, check the pre-commit hook for an unconditional version bump and count the expected bumps (N commits → N minor bumps here); plan to settle the version or add a `SKIP_BUMP` guard before release. Commit pre-existing diffs with a scope-accurate message derived from the inventory. Commit any lingering prior-pipeline docs as a separate `docs:` commit.
+- **tracker**: Record the auto-bump as an explicit side effect with the exact version delta (`1.44.0 → 1.49.0`) whenever a multi-commit pipeline runs; note when a deployer has committed a prior pipeline's provisional record. Reuse the canonical `projectId` from `require('./package.json').name` (`@abarcenas/ai-workflow-template`) when re-indexing this session.
+
+## Session: 2026-09-14 — Pipeline 11 Final Polish (doc nits + version settle + `SKIP_BUMP` opt-out)
+
+**Pipeline:** coder (4 tasks) → reviewer (✅ APPROVED) → deployer (4 commits) → tracker
+**Coverage:** N/A (docs + a comment-only script change + a version constant; Vitest suite unaffected)
+**TDD Iterations:** 0 (quick-fix follow-up pipeline, not TDD)
+
+**New knowledge:**
+- **The long-recommended `SKIP_BUMP` opt-out is now implemented as an additive pre-write guard — and it was exercised on the very commits that introduced it.** `scripts/bump-version.js` now checks `if (process.env.SKIP_BUMP) { log + process.exit(0) }` at lines 9–15, BEFORE reading or writing `package.json`; the default (unset) path is unchanged. The deployer ran all 4 commits with `SKIP_BUMP=1`, and the hook logged "SKIP_BUMP set — version bump skipped" each time, leaving the settled `1.45.0` stable. **Universal pattern:** when you add an opt-out flag for a hook that fires on every commit, use that flag on the commits that introduce it — self-dogfooding is both the proof the guard works and the way to keep the batch's own version stable. This also closes the recommendation first recorded 2026-08-02 and repeated 2026-09-14 (Pipeline 11 Follow-ups). Prefer this opt-out over `--no-verify`, which skips ALL hooks (including memory-schema validation).
+- **Settling an N-commit auto-bump batch: target = pre-batch base parent's version + exactly one bump, not a guessed number.** `package.json` had drifted `1.44.0 → 1.49.0` over the 5-commit follow-up batch (the hook bumps minor on EVERY commit). The correct settled value was derived from `git show 267da69^:package.json` → base `1.44.0`, and one logical change set ⇒ one bump ⇒ `1.45.0` (reverting the four spurious bumps `1.46.0`–`1.49.0`). **Universal pattern:** to undo spurious bump-on-commit drift, compute the target from the base commit's PARENT (`<base_commit>^`) plus a single bump — the post-batch current value tells you how far it drifted but not where it should settle.
+- **JS truthy-string footgun for env-var flags: `SKIP_BUMP=0` and `SKIP_BUMP=false` are non-empty strings and therefore TRUTHY — they also skip the bump.** The documented contract is "set `SKIP_BUMP=1`", but the guard as written accepts ANY non-empty value. Flagged as non-blocking M-1; a strict parse (`value === '1' || value === 'true'`) would close it. **Universal pattern:** an `if (process.env.X)` guard treats `"0"`/`"false"`/`"no"` as enabled — if the flag is meant to be numeric/boolean, parse it explicitly rather than relying on string truthiness.
+- **A stale lockfile is a separate concern from the manifest version — do not "fix" it inside a version-settle commit.** `package-lock.json` exists but is stale at `1.34.0` (last touched `d788f68`) and does NOT mirror `package.json`; the repo's `bump-version.js` convention never syncs it. Keeping it out of scope avoided a large, unrelated lockfile churn; `npm ci --dry-run` passes, so it is not a build blocker. **Universal pattern:** when the task is "settle the manifest version," leave lockfile drift alone and flag it as pre-existing; classify pre-existing drift separately from pipeline findings.
+- **Comment-only edits to byte-identical duplicate files still require byte-identity verification.** The `except ImportError:` clarification was applied to BOTH `compress.py` copies (`.agents/skills/compress/scripts/`, `.agents/skills/caveman-compress/scripts/`) and the reviewer confirmed `cmp`/`diff` byte-identity. Runtime behavior is unchanged, so the Vitest suite is unaffected — consistent with the established "duplicated files drift silently; edit in lockstep + `cmp`" rule.
+- **A three-path try/except-fallback flow must be documented as three paths, and this pipeline actually did it.** The auth behavior now reads: (1) `ANTHROPIC_API_KEY` set + SDK installed → direct API + `CAVEMAN_MODEL` required; (2) key set but SDK missing (`except ImportError: pass`) → `claude` CLI, no model var; (3) key unset → `claude` CLI. This implements the "count the branches, describe each" rule from the prior session instead of leaving the middle state implied. **Universal pattern:** a two-path description of a three-path flow is a latent support trap — enumerate every branch.
+- **A version-settle commit does not need a CHANGELOG.** None exists in this repo; the settle is documented in the commit message + tracker record, not fabricated into a changelog file. **Universal pattern:** do not invent release-notes artifacts to justify a version change — record the rationale where the repo already keeps history.
+
+**Agent tuning notes:**
+- **coder**: For a version settle, derive the target from `<base_commit>^` + one bump and leave any stale lockfile untouched (flag it as drift). For comment-only edits to duplicated scripts, apply to every copy and verify byte-identity. When you implement a hook opt-out, verify the default path is byte-unchanged and exercise the flag (`SKIP_BUMP=1 node scripts/bump-version.js` → exit 0, manifest untouched). When documenting a try/except fallback, enumerate all three states.
+- **reviewer**: Verify the opt-out guard is placed BEFORE any read/write (additive, default unchanged) and probe the truthy-string edge — `SKIP_BUMP=0`/`false` also skip (M-1). Confirm comment-only changes leave duplicate files byte-identical and runtime unchanged. Distinguish pre-existing drift (`package-lock.json` at `1.34.0`; missing `architecture-context` vocab entity) from issues introduced by the change; a historical tracker entry referencing the pre-settle version is a frozen-record artifact, not a defect.
+- **deployer**: Use the newly added `SKIP_BUMP=1` on the commits that introduce it, rather than `--no-verify` — the guard is the targeted mitigation and keeps the other hooks (memory-schema validation, vocab-sync) running. After a version settle, verify the manifest version at HEAD and that it was committed exactly once (no re-bump), and confirm the hook logged the skip.
+- **tracker**: Record the `SKIP_BUMP` guard as IMPLEMENTED (closing the 2026-08-02 / 2026-09-14 recommendation) with the exact settle delta (`1.49.0 → 1.45.0`), and carry the non-blocking minors forward (M-1 truthy string, M-2 missing SDK qualifier in README, M-3 lockfile drift, M-4 vocab entity gap, M-5 stale historical "1.49.0" narrative). Reuse the canonical `projectId` from `require('./package.json').name` (`@abarcenas/ai-workflow-template`) when re-indexing this session.

package/.agents/skills/caveman-compress/README.md

@@ -81,6 +81,8 @@ caveman-compress/
 
 **Requires:** Python 3.10+
 
+**Model config:** When `ANTHROPIC_API_KEY` is set, `CAVEMAN_MODEL` must also be exported (e.g. `export CAVEMAN_MODEL=<model-id>`) — the script fails fast if it is unset. When using the `claude` CLI fallback, no model variable is needed.
+
 ## Usage
 
 ```

package/.agents/skills/caveman-compress/SECURITY.md

@@ -20,7 +20,9 @@
 
 ### Auth behavior
 
-If `ANTHROPIC_API_KEY` is set, the skill uses the Anthropic Python SDK directly (no subprocess). If not set, it falls back to the `claude` CLI, which uses the user's existing Claude desktop authentication.
+If `ANTHROPIC_API_KEY` is set and the Anthropic Python SDK is installed, the skill uses the SDK directly (no subprocess). If the key is not set — or the SDK is not installed — it falls back to the `claude` CLI, which uses the user's existing Claude desktop authentication.
+
+When using the Anthropic API directly (i.e. the SDK is installed), `CAVEMAN_MODEL` MUST also be exported with the model identifier (e.g. `export CAVEMAN_MODEL=<model-id>`) — the skill fails fast with a clear error if it is unset. The `claude` CLI fallback requires no model variable.
 
 ### File size limit
 

package/.agents/skills/caveman-compress/SKILL.md

@@ -35,6 +35,10 @@ cd caveman-compress && python3 -m scripts <absolute_filepath>
 
 4. Return result to user
 
+## Configuration
+
+When `ANTHROPIC_API_KEY` is set, the script calls the Anthropic API directly (when the Anthropic SDK is installed) and REQUIRES `CAVEMAN_MODEL` to be exported with the model identifier (e.g. `export CAVEMAN_MODEL=<model-id>`); it fails fast with a clear error if unset. If the Anthropic SDK is not installed, it falls back to the `claude` CLI, which requires no model variable.
+
 ## Compression Rules
 
 ### Remove

package/.agents/skills/caveman-compress/scripts/compress.py

@@ -78,15 +78,22 @@ def call_claude(prompt: str) -> str:
         try:
             import anthropic
 
+            model = os.environ.get("CAVEMAN_MODEL")
+            if not model:
+                raise RuntimeError(
+                    "CAVEMAN_MODEL environment variable is not set. "
+                    "Set it to the model identifier to use for compression "
+                    '(e.g. export CAVEMAN_MODEL="<model-id>").'
+                )
             client = anthropic.Anthropic(api_key=api_key)
             msg = client.messages.create(
-                model=os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5"),
+                model=model,
                 max_tokens=8192,
                 messages=[{"role": "user", "content": prompt}],
             )
             return strip_llm_wrapper(msg.content[0].text.strip())
         except ImportError:
-            pass  # anthropic not installed, fall back to CLI
+            pass  # anthropic SDK not installed → fall back to CLI (no CAVEMAN_MODEL needed)
     # Fallback: use claude CLI (handles desktop auth)
     try:
         result = subprocess.run(

package/.agents/skills/compress/SKILL.md

@@ -35,6 +35,10 @@ cd <directory_containing_this_SKILL.md> && python3 -m scripts <absolute_filepath
 
 4. Return result to user
 
+## Configuration
+
+When `ANTHROPIC_API_KEY` is set, the script calls the Anthropic API directly (when the Anthropic SDK is installed) and REQUIRES `CAVEMAN_MODEL` to be exported with the model identifier (e.g. `export CAVEMAN_MODEL=<model-id>`); it fails fast with a clear error if unset. If the Anthropic SDK is not installed, it falls back to the `claude` CLI, which requires no model variable.
+
 ## Compression Rules
 
 ### Remove

package/.agents/skills/compress/scripts/compress.py

@@ -78,15 +78,22 @@ def call_claude(prompt: str) -> str:
         try:
             import anthropic
 
+            model = os.environ.get("CAVEMAN_MODEL")
+            if not model:
+                raise RuntimeError(
+                    "CAVEMAN_MODEL environment variable is not set. "
+                    "Set it to the model identifier to use for compression "
+                    '(e.g. export CAVEMAN_MODEL="<model-id>").'
+                )
             client = anthropic.Anthropic(api_key=api_key)
             msg = client.messages.create(
-                model=os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5"),
+                model=model,
                 max_tokens=8192,
                 messages=[{"role": "user", "content": prompt}],
             )
             return strip_llm_wrapper(msg.content[0].text.strip())
         except ImportError:
-            pass  # anthropic not installed, fall back to CLI
+            pass  # anthropic SDK not installed → fall back to CLI (no CAVEMAN_MODEL needed)
     # Fallback: use claude CLI (handles desktop auth)
     try:
         result = subprocess.run(

package/.opencode/agents/architect.agent.md

@@ -6,7 +6,6 @@ permission:
   search: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Architect - System Design

package/.opencode/agents/coder.agent.md

@@ -8,7 +8,6 @@ permission:
   execute: "allow"
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Coder - Implementation

package/.opencode/agents/deployer.agent.md

@@ -9,7 +9,6 @@ permission:
   "github/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Deployer - Release Engineering

package/.opencode/agents/designer.agent.md

@@ -6,7 +6,6 @@ permission:
   search: "allow"
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Designer - UI/UX

package/.opencode/agents/e2e-tester.agent.md

@@ -7,7 +7,6 @@ permission:
   "chrome-devtools/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # E2E Tester - Browser Automation

package/.opencode/agents/implementer.agent.md

@@ -8,7 +8,6 @@ permission:
    execute: allow
    "memory-bank/*": allow
    "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Implementer - Implementation Planning

package/.opencode/agents/orchestrator/feature-pipeline.agent.md

@@ -8,7 +8,6 @@ permission:
   todo: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Feature Pipeline

package/.opencode/agents/orchestrator/orchestrator.agent.md

@@ -13,7 +13,6 @@ permission:
   "chrome-devtools/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Orchestrator - Multi-Agent Workflow

package/.opencode/agents/orchestrator/tdd-orchestrator.agent.md

@@ -8,7 +8,6 @@ permission:
   todo: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # TDD Orchestrator - Test-Driven Development

package/.opencode/agents/plan.agent.md

@@ -9,7 +9,6 @@ permission:
   question: allow
   webfetch: allow
   websearch: allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Plan Mode - Strategic Planning & Architecture Assistant

package/.opencode/agents/researcher.agent.md

@@ -9,7 +9,6 @@ permission:
   "context7/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Technical spike research mode

package/.opencode/agents/reviewer.agent.md

@@ -8,7 +8,6 @@ permission:
   "github/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Reviewer - Code Quality

package/.opencode/agents/tracker.agent.md

@@ -9,7 +9,6 @@ permission:
   write: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Tracker - Documentation Recorder

package/.opencode/agents/unit-tester.agent.md

@@ -8,7 +8,6 @@ permission:
   execute: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Unit Tester - Test Coverage

package/AGENTS.md

@@ -6,13 +6,13 @@ This project includes AI-assisted development configuration distributed through
 
 - `.agents/instructions/` — Language, framework, and workflow instructions
 - `.agents/skills/` — Reusable skill definitions for task-based workflows
-- `.agents/agents/` — Specialized agent definitions for planning, research, and implementation
+- `.opencode/agents/` — Specialized agent definitions for planning, research, and implementation
 - `.agents/prompts/` — Reusable prompt templates
 
 ## Core Workflow
 
 1. **Understand before acting** — Read relevant instructions from `.agents/instructions/` before working with specific technologies
-2. **Plan before implementing** — Use `.agents/agents/plan.agent.md` or `.agents/agents/implementation-plan.agent.md` patterns for structured work
+2. **Plan before implementing** — Use `.opencode/agents/plan.agent.md` or `.opencode/agents/implementer.agent.md` patterns for structured work
 3. **Track progress** — Update `memory-bank/activeContext.md` and `memory-bank/progress.md` after each task (see `.agents/instructions/task-implementation.instructions.md`)
 4. **Maintain context** — Keep memory bank files updated (see `.agents/instructions/memory-bank.instructions.md`)
 
@@ -81,7 +81,7 @@ Prompts in `.agents/prompts/` can be invoked directly:
 
 ## Available Agent Workflows
 
-These agent workflows (from `.agents/agents/`) define specialized modes of operation. Invoke the relevant workflow at the start of a task by stating which mode you want to activate.
+These agent workflows (from `.opencode/agents/`) define specialized modes of operation. Invoke the relevant workflow at the start of a task by stating which mode you want to activate.
 
 ### Plan Mode — Strategic Planning & Architecture
 

package/README.md

@@ -229,7 +229,7 @@ All memory-bank files use YAML frontmatter (`id`, `title`, `updated`, `tags`, `e
 
 ## Versioning
 
-Husky auto-bumps versions on every commit: minor by default (`1.2.0 → 1.3.0`), patch resets to 0 on each bump, and major changes reset to `<major>.0.0`. No manual version management required.
+Husky auto-bumps versions on every commit: minor by default (`1.2.0 → 1.3.0`), patch resets to 0 on each bump, and major changes reset to `<major>.0.0`. No manual version management required. Set `SKIP_BUMP=1` (e.g. `SKIP_BUMP=1 git commit ...`) to skip the bump for that commit — useful for doc-only changes.
 
 ## Publish Flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.44.0",
+  "version": "1.45.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/bump-version.js

@@ -6,6 +6,13 @@ import { fileURLToPath } from 'url'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkgPath = resolve(__dirname, '../package.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).
+if (process.env.SKIP_BUMP) {
+  console.log('SKIP_BUMP set — version bump skipped')
+  process.exit(0)
+}
+
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
 const current = pkg.version
 const [curMajor, curMinor] = current.split('.').map(Number)