@abarcenas/ai-workflow-template 1.44.0 → 1.46.0

package/.agents/config/README.md

@@ -0,0 +1,43 @@
+---
+title: "Agent skills and configuration"
+description: "Discovery pointer for the scoping skills, the scope agent, and domain documentation locations."
+---
+
+## Why this file exists
+
+Root-file sync skips any file you have modified locally. If you edited `AGENTS.md`, newer
+versions of the template will not overwrite it, so a `## Agent skills` section added upstream
+will never reach your copy. This file is the discovery path in that case: it lives under
+`.agents/`, which syncs on every update.
+
+## Scoping skills
+
+Each skill lives at `.agents/skills/<name>/SKILL.md` and is loaded with the skill tool.
+
+| Skill | Use it when |
+|-------|-------------|
+| `grilling` | A plan, decision, or idea needs stress-testing, or a request is too vague to plan — rounds of numbered questions narrow the frontier, each with a recommended answer. |
+| `grill-me` | You want the same interview with no repository context and no document output — a stateless, one-shot entry point. |
+| `grill-with-docs` | You want the interview plus the written record — the glossary and ADRs are created as decisions settle. |
+| `domain-modeling` | Project terminology or architectural decisions are being introduced or changed, and `GLOSSARY.md` or an ADR needs to capture them. |
+| `prototype` | A design question can only be settled by running throwaway code — the logic branch for state models and data flow, the UI branch for look and feel. |
+
+`grill-me` and `grill-with-docs` are human-invoked wrappers: the first calls `grilling` alone,
+the second calls `grilling` and `domain-modeling` together.
+
+## Scope agent
+
+`.opencode/agents/scope.agent.md` is the front door for underspecified feature requests. It
+runs grilling in rounds against a draft file, emits the current frontier as numbered questions,
+and finishes by writing a spike document at `docs/spike-<feature>.md` — the input
+`researcher.agent.md` already expects.
+
+It never builds or runs code. When a question needs a prototype it emits
+`prototype needed: <question>`, and the orchestrator delegates the work to `coder` (logic) or
+`designer` (UI).
+
+## Domain docs
+
+`.agents/config/domain.md` declares where domain documentation lives: `GLOSSARY.md` at the
+repository root and ADRs under `docs/adr/`. The `domain-modeling` skill reads it; when the file
+or the docs it names are absent, the skill proceeds silently.

package/.agents/config/domain.md

@@ -0,0 +1,37 @@
+---
+description: "Domain artifact paths for domain-modeling and grill-with-docs"
+applyTo: "**"
+---
+
+# Domain Documentation
+
+Read this file to locate the project's domain artifacts before exploring the
+codebase or changing the domain model.
+
+## Layout
+
+This repository uses a single-context layout:
+
+- `GLOSSARY.md` at the repository root — the project's domain vocabulary.
+- `docs/adr/` — Architecture Decision Records, numbered `0001-slug.md`,
+  `0002-slug.md`, and so on.
+
+Read only the ADRs that touch the area you are about to work in.
+
+## When a file or directory is absent
+
+Proceed silently. Do not report the absence, do not treat it as an error, and
+do not scaffold `GLOSSARY.md` or `docs/adr/` unprompted. Create them lazily,
+only when a term or decision has actually been resolved.
+
+## Use the glossary's vocabulary
+
+Name domain concepts exactly as `GLOSSARY.md` defines them. Do not drift to
+synonyms the glossary avoids. If a concept is missing, treat it as a gap to
+resolve with the user rather than inventing new language.
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, state the conflict explicitly and
+cite the ADR number. Never silently override or quietly reinterpret a recorded
+decision.

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,173 @@
 - **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.
+
+## Session: 2026-10-24 — Matt Pocock Skills Integration + Scope Agent (pinned vendored skills + new setup phase)
+
+**Pipeline:** implementer (bootstrap + read-only pre-flight) → coder ∥(T1,T2,T3) → coder(T4) → coder ∥(T5,T6) → coder(T7) → coder(T8+T9) → coder(T10+T11) → coder ∥(T12,T13,T14) → coder(T15) → coder ∥(T16,T17) → tracker
+**Coverage:** 16 files / 331 tests, 0 failures; `scripts/setup/` 7 files / 142 tests; `scripts/sync.test.js` 15/15; `spec-orchestrator-parity` 8/8; `spec-knowledge-retrieval` 6/6; `scripts/setup/skills-phase.js` 99.42% stmts / 97.34% branch / 100% funcs / 100% lines
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **`bin/setup.js` is a 26-line shim — every setup phase lives in `scripts/setup/`.** `index.js` orchestrates; siblings are `sync-phase.js`, `prepare.js`, `husky-init.js`,
+  `knowledgebase.js`, `constants.js`, `ui.js`.
+  The plan targeted `bin/setup.js` for a new install phase; the correct home was a new `skills-phase.js` module plus a step in `index.js`'s Phase 6. **Universal pattern:** before
+  planning an edit to an entry-point file, check whether it is a shim that delegates to a phase directory — targeting the entry point produces a feature that lives in the wrong
+  layer and is untestable in the project's established style.
+- **`vitest.config.ts` enforces 90% coverage over `scripts/**`, and every setup module has a sibling `.test.js` — but the GLOBAL threshold already fails at HEAD.** New `scripts/`
+  code must ship with tests (the per-file numbers matter), yet the repo-wide number was **48.05% statements at HEAD** and **~50.69%** after this feature. **Universal pattern:**
+  distinguish the *per-file* coverage contract from the *repo-wide* threshold.
+  A pre-existing global failure is not a regression and must not be "fixed" opportunistically by changing thresholds or exclusions; record the baseline you measured at HEAD so the
+  delta is auditable.
+- **The v8 coverage provider reads 0% for code exercised only through `spawnSync` child processes.** `scripts/sync.js` executes at import (no exported `main`), so its tests spawn
+  it as a child; v8 cannot instrument across the process boundary.
+  Its 0% coverage is structural and pre-existing. **Universal pattern:** for child-process entry points, rely on behavioural assertions (exit code, stdout/stderr, filesystem/tree
+  diffs) and state in the record that the coverage number is meaningless — never chase it by refactoring the entry point purely for coverage.
+- **`tests/spec-orchestrator-parity.test.js` asserts EXACT OCCURRENCE COUNTS of literal phrases** (2× `knowledge-retrieval`, 2× `knowledgebase`) in `orchestrator.agent.md`.
+  **Universal pattern:** before editing an orchestrator spec, grep the parity test for occurrence-count guards; an edit that quotes the same literal a third time fails the suite
+  even though the change is correct.
+  Either avoid duplicating the string or update the counts deliberately and say so.
+- **`tests/spec-knowledge-retrieval.test.js` derives the pipeline agent set by scanning `.opencode/agents/*.agent.md` minus `plan.agent.md` and asserts an exact length.** Adding
+  `scope.agent.md` broke it until `EXPECTED_PIPELINE_AGENTS` went 10 → 11. **Universal pattern:** a new agent file is a two-part change — the spec plus every enumeration of agents
+  (this one, `CHECK_PATHS`, docs tables, registry rows).
+  Grep for the expected count, not just the file list.
+- **`tests/spec-kb-consolidation.test.js` holds a SEPARATE `CHECK_PATHS` enumeration of every agent spec** — the second place that must be updated when an agent is added.
+  It was discovered only during the verification phase. **Universal pattern:** after adding an agent/skill/instruction, grep the whole test tree for the old count and for
+  enumerations of sibling paths; two independent lists drifting is the normal failure mode, not the exception.
+- **The pre-commit hook runs `bump-version` → `vocab-sync` → `validate-memory-schema`, and the auto-bump is PRE-commit, not post-commit.** `SKIP_BUMP=1` is honored at
+  `scripts/bump-version.js:9-15` (the guard sits before any read/write).
+  The plan's DEP-03 stated the opposite ordering; the read-only pre-flight caught it. **Universal pattern:** read the hook file itself before planning version strategy.
+  Edit the version ONCE by hand per PR and commit with `SKIP_BUMP=1`; do not let N commits produce N minor bumps, and do not use `--no-verify` (it also skips memory-schema
+  validation).
+- **Upstream `mattpocock/skills` has ASYMMETRIC category paths** — `skills/productivity/` for `grilling` and `grill-me`, `skills/engineering/` for
+  `grill-with-docs`/`domain-modeling`/`prototype` — so a raw URL must **never** be derived from a skill name. **Universal pattern:** when pinning remote files, record the full
+  upstream path per file in the lock (`upstreamPath`) and build URLs from the lock alone; deriving paths from names silently 404s for exactly the entries whose category differs.
+- **`grill-me` and `grill-with-docs` are `disable-model-invocation: true`** — they are human-invoked routers, not agent-loadable skills.
+  Agents must invoke `grilling` directly (plus `domain-modeling` when a term or decision settles) and must never delegate to the wrappers. **Universal pattern:** check
+  `disable-model-invocation` on every vendored skill before wiring it into an agent; a router that only a human can start cannot be a pipeline step (the same reason `wayfinder` was
+  dropped).
+- **`docs/` is neither in `package.json` `files` nor in `scripts/sync.js`'s root-file list (CON-09).** Configuration placed under `docs/agents/` would never reach consumers, no
+  matter how correct it is. **Universal pattern:** before choosing a location for distributed configuration, verify the path is actually packaged AND synced — pick
+  `.agents/config/` (synced recursively) over a conventional `docs/` location.
+- **Root-file sync (`AGENTS.md`, `opencode.json`, `skills-lock.json`) SKIPS locally modified consumer files.** A consumer who edited `AGENTS.md` will never receive a new section.
+  **Universal pattern:** every user-facing instruction added to a root-synced file needs a backstop under `.agents/` (here `.agents/config/README.md`) plus a visible install-time
+  warning.
+  The warning itself must be printed in non-verbose mode — see DEF-01.
+- **`scripts/sync.js` executes at import (no exported `main`); tests use `spawnSync('node', ['scripts/sync.js', ...])` with `INIT_CWD`.** Prune iterates only manifest keys that
+  existed **before** the run, so it never deletes files the same run just scaffolded. **Universal pattern:** a newly added destructive path must snapshot its input set at
+  start-of-run; otherwise "prune what the package no longer ships" deletes the files the current install just created (all of which are absent from the pre-run manifest).
+
+**Agent tuning notes:**
+- **implementer / orchestrator (pre-flight)**: One read-only pre-flight before dispatching any implementation batch is high-value and should be standard whenever a plan references
+  specific files.
+  Here it caught **9 plan errors** — wrong file target (`bin/setup.js`), the coverage gate's sibling-test requirement, an inverted dependency (DEP-03), the parity-test
+  occurrence-count trap, an incomplete lock schema (per-file `upstreamPath`), and others — each of which would have cost a full rework cycle.
+  It must stay read-only (no edits, no builds) so it cannot invalidate the plan before the gate is approved.
+- **orchestrator (parallel batches)**: Parallel subagents that each append to `memory-bank/activeContext.md` / `progress.md` cause write races. Parallel batches should either skip memory-bank updates (and say so explicitly in the delegation) or the orchestrator must serialize that write. Disjoint source files are not sufficient — the shared documentation sink is the collision point.
+- **orchestrator (interruption recovery)**: Subagents that mark their own plan checkboxes are reliable, but an interrupted subagent leaves the work done and the rows unmarked. Always re-verify disk state after an interruption (grep for the artifact, run the targeted test) before re-dispatching; re-dispatching an interrupted-but-complete task duplicates work and risks conflicting edits.
+- **orchestrator (concurrent verification)**: Verify-by-diff beats verify-by-test when two agents edit related files concurrently — have one agent diff against sibling files instead of running a suite the other agent is about to change. Tests are a moving target during a parallel batch; diffs against a stable sibling are not.
+- **all agents (knowledgebase_search)**: `knowledgebase_search` was unavailable repo-wide (`DATABASE_URL` unset). Every agent should report it as "NOT executed (PG vector unavailable)" and continue — never retry, never treat it as a task failure, and never block the pipeline on it. The explicit report is the accountability mechanism that keeps a graceful degradation from becoming a silent one.
+
+## Session: 2026-10-25 — Repo-Wide Coverage Gate Met (in-process refactors) + MCP Launcher ESM Bug
+
+**Pipeline:** coder (10 new test files, 6 extended, 4 source refactors) → deployer (commit + this record)
+**Coverage:** repo-wide **96.93% stmts / 95.23% branch / 96.62% funcs / 97.16% lines** (was ~50.6% pre-change, 48.05% at HEAD before Feature Pipeline 12); `scripts/` 94.97 / 93.76 / 93.16 / 95.24; `scripts/setup/` 99.88 / 97.80 / 100 / 100. Suite **331 → 746 tests** (16 → 26 files), 0 failures. `npm test` 7 passed / 1 skipped. **0 thresholds lowered, 0 excludes added, 0 `v8 ignore` comments.**
+**TDD Iterations:** 0 (coverage-remediation pipeline, not TDD)
+
+**New knowledge:**
+- **v8 coverage cannot instrument CHILD PROCESSES — a module exercised only through `spawnSync` reads 0% forever.** `scripts/sync.js` had 15 behavioural tests and still reported **0.00%** because every test ran `spawnSync('node', ['scripts/sync.js', …])`; the instrumented parent never executes the child's code. The fix is **not** to lower the threshold: extract the top-level body into named functions (`parseArgs`, `createSyncContext`, `readManifest`/`writeManifest`, `isUntouched`, `isPathInside`, `resolvePruneEntry`, `isRegularFile`, `syncProject`, `runSync`), export them, and add an `isEntryPoint()` guard. The same 15 spawn tests then pass **unmodified** while in-process tests cover the units — 0% → **99.65%** with zero assertion changes. **Universal pattern:** "0% but well tested" almost always means child-process execution, not missing tests; refactor for importability, never reduce the gate.
+- **An entry point that runs on import is untestable AND can have side effects on import.** `scripts/mcp-memory-server.js` opened a **stdio transport** the moment it was imported, which is worse than a missing export — importing it in a test would hijack the test process's stdio. Extract `main()`, add `bootstrap()` + a direct-run guard, and the module becomes importable. **Universal pattern:** any module an MCP server / CLI exposes must separate *definition* from *invocation*; a guard is the seam that makes the difference.
+- **macOS reports the same file as `/var/...` through `import.meta.url` and `/private/var/...` through `process.argv[1]`.** A naive `fileURLToPath(import.meta.url) === resolve(process.argv[1])` comparison therefore **fails on macOS temp paths** (and `/tmp` is a symlink to `/private/tmp`). Entry-point detection must compare **`realpathSync()` of both sides**, inside a `try/catch` (a path may not exist): `realpathSync(modulePath) === realpathSync(argvPath)`. Keep the cheap string comparison first as a fast path. **Universal pattern:** any path-identity comparison — entry points, containment checks, dedupe keys — must normalise symlinks on macOS.
+- **Under `"type": "module"`, a `.js` file using `require(...)` throws `ReferenceError: require is not defined` — and import-time-only tests never notice.** `scripts/mcp/playwright-mcp-launcher.js` was **dead on arrival**: CJS `require` in an ESM package. No test executed it (it lives at module top level, so importing it would spawn `npx`), so nothing caught the failure until it was actually exercised. This session converted it to `import` + `buildArgs()` / `launch()` helpers. **Universal pattern:** the `.status?` equivalent for ESM is "is it ever executed, not merely imported?" — a file with no sibling test and top-level side effects can be broken for months; when a package is `"type": "module"`, grep for `require(`/`module.exports` in `.js` files as a lint step.
+- **`better-sqlite3` + `sqlite-vec` DO load in this environment; real temp DBs are the right fixture.** Memory tests use `mkdtempSync` + a real SQLite file, so schema, joins, and `vec_memory` behaviour are exercised for real. Only **`@xenova/transformers`** needs mocking, because its real use downloads a **~90 MB** model — that is the one legitimate mock boundary. **Universal pattern:** mock only what is slow/network-bound; a real temp DB is a better fixture than a fake DB object and costs milliseconds.
+- **`memory-index.js` has a latent orphan-row bug (documented, NOT fixed).** Around lines 242–263 the `SELECT` fetches only `id, content_hash`, so `existing.vec_rowid` is always `undefined`; the update path's `if (oldVecRowid != null)` is dead, and re-indexing a changed chunk **orphans its old `vec_memory` row**. Invisible to search (the JOIN keys on `memory_chunks.vec_rowid`) but a storage leak that grows per changed chunk. **Universal pattern:** when a `SELECT` feeds a conditional that deletes from another table, verify every column the condition reads is actually selected — a column silently missing from the projection turns cleanup into dead code that no test catches.
+- **`.agents-sync-manifest.json` is gitignored — never commit it.** Stale hashes there only make `scripts/sync.js` skip local copies in a consumer tree; it is derived state, not source. **Universal pattern:** before staging a large diff, check `git status` for derived manifests/databases/reports — they are regenerated, not reviewed.
+- **Established entry-point-guard pattern in this repo** (copy it rather than inventing one): `scripts/vocab-sync.js`, `scripts/validate-memory-schema.js`, `scripts/normalize-memory.js`, and now `scripts/sync.js` / `mcp-memory-server.js` / `mcp/playwright-mcp-launcher.js` — named exports + `isEntryPoint()`/`isDirectRun` + invoke only when run directly.
+
+**Agent tuning notes:**
+- **coder (coverage remediation)**: Inventory coverage by module first and classify each 0% file as (a) never tested, (b) tested only via a child process, or (c) untestable because of import-time side effects. Each class has a different fix; only (c) needs a `bootstrap()` seam. Preserve existing spawn tests verbatim as the behavioural backstop — if a refactor forces you to change them, the refactor changed behaviour. Never reach for `/* v8 ignore */`, excludes, or threshold edits; if you are tempted, the module is untestable by design and needs the seam instead.
+- **coder (SQLite/vector tests)**: Use `mkdtempSync` + a real DB. Mock only the embedding model (`@xenova/transformers`) — it is the sole network/size boundary. Clean up temp dirs in `afterEach`.
+- **deployer**: Re-verify all three gates (`--coverage`, `vitest run`, `npm test`) **before** committing, and prove the gate is honest with `git diff vitest.config.ts` (must be empty) plus a grep for ignore comments. Stage exactly the enumerated modified/untracked set; never `git add -A` when derived artifacts (`.agents-sync-manifest.json`, `playwright-report/`, `test-results/`, `memory-bank/.index/`) may be present. Use `SKIP_BUMP=1` so a test-only commit does not bump the minor version.
+- **tracker**: Record the before/after coverage as a table plus the explicit "no thresholds/excludes/ignore comments" proof — the credibility of a coverage claim rests on that negative evidence. Always carry a deliberately-unfixed latent bug forward as an open follow-up with its mechanism, not just its name.
+- **all agents (knowledge retrieval)**: `memory_search` returned "No results found. The index may be empty" and `knowledgebase_search` returned "Knowledgebase not available: DATABASE_URL is not configured" — both reported as skipped/unavailable, neither retried nor treated as a task failure.
+
+## Session: 2026-10-25 — `vec_memory` Orphan Leaks Fixed (vec0 has no foreign keys; audit removal paths)
+
+**Pipeline:** coder (test-first: 7 tests written and failing before the fix) → deployer (commit + this record)
+**Scope:** `scripts/memory-index.js`, `scripts/memory-index.test.js`
+**Verification:** `npx vitest run` → 26 files / **753 tests** (746 → 753, 68 in `memory-index.test.js`), 0 failures; `npx vitest run --coverage` → exit 0, **97.02 / 95.28 / 96.74 / 97.25** (was 96.93 / 95.23 / 96.62 / 97.16); `memory-index.js` **98.83 / 96.33 / 96.87 / 99.56**; `npm test` → 7 passed / 1 skipped.
+
+**New knowledge:**
+- **`vec0` virtual tables have NO foreign keys; reachability is only via `memory_chunks.vec_rowid`.** A `vec_memory` row that loses its link is unreachable by `search` (the JOIN keys on `memory_chunks.vec_rowid`) yet still occupies storage — an unbounded leak that no query can reveal. The correct invariant is **one vector per *linked* chunk**, i.e. `COUNT(vec_memory) === COUNT(memory_chunks WHERE vec_rowid IS NOT NULL) === COUNT(DISTINCT vec_rowid)`, **not** `vec_memory == memory_chunks`: embed failures legitimately leave `vec_rowid IS NULL` and must be allowed (assert the expected null count explicitly per test, don't hide it). **Universal pattern:** any table without referential integrity needs an explicit integrity assertion in tests, because the database will not enforce it and the query path will not expose it.
+- **A `LEFT JOIN` on the vector row is required to detect *dangling* links, not just `NULL` ones.** `WHERE vec_rowid IS NOT NULL` catches an unlinked chunk but **misses a legacy row whose `vec_rowid` points at a vector that no longer exists** (or a crash between vector insert and link update). Selecting `v.rowid AS vec_exists` via `LEFT JOIN vec_memory v ON v.rowid = mc.vec_rowid` distinguishes live / dangling / null in one query, and the skip path must require `hash matches AND vec_exists != null` — otherwise a dangling chunk is "unchanged" forever and never repaired.
+- **Test SQLite vector integrity by counting rows before/after a content edit, never by trusting `search`.** Orphans are invisible to queries **by construction** — the leak is precisely the rows the JOIN cannot reach. The test helper `assertVectorIntegrity()` counts vectors, linked chunks, distinct links, orphans (`LEFT JOIN … WHERE mc.id IS NULL`), and dangling links (`LEFT JOIN … WHERE vec_rowid IS NOT NULL AND v.rowid IS NULL`). **Universal pattern:** for any cache/index, assert the storage invariant directly against the tables; a passing `search` proves nothing about leaked rows.
+- **Pattern: detach-then-delete-then-reinsert inside `db.transaction()`.** On update, first set `vec_rowid = NULL` and `DELETE` the old vector in one transaction, **then** re-embed and insert + relink in a second transaction. A failed embed then leaves a retryable `NULL` link rather than a dangling reference, and an interruption can never produce an orphan. **Universal pattern:** when two side-effect writes must agree but the store cannot enforce it, order them so every intermediate state is self-consistent and retryable.
+- **`incrementalUpdate` had no deleted-file pruning at all — deleted files remained searchable.** Both `memory_chunks` and `vec_memory` rows survived, so `search` could return content from a source file that no longer existed. Fixed with `pruneMissingSources()` (delete chunks + vectors for sources absent from the current file set) and `pruneOrphanVectors()` (sweep any vector row no chunk references, healing DBs corrupted by the old code). **Universal pattern:** when auditing a cache/index for leaks, audit the **removal** paths too — update paths get the tests, deletion paths get forgotten, and stale entries are worse than stale bytes because they are still served.
+- **SQLite `.db` files do not shrink after `DELETE` without `VACUUM`.** Row growth stops immediately (verifiable by `COUNT(*)`), but the file keeps its high-water mark (visible in `memory_stats` size). **Never use file size as the leak metric** in a test or an audit — assert row counts.
+- **A `SELECT` feeding a cross-table cleanup must project every column the cleanup condition reads.** The original bug was a projection omitting `vec_rowid`: `existing.vec_rowid` was always `undefined`, so `if (oldVecRowid != null)` was dead code. No test noticed for months because the symptom (orphan rows) was outside the normal query path. **Universal pattern:** when a condition guards a `DELETE`/cleanup in another table, assert the guard is non-vacuous — mutation-test it or write the failing-first test that observes the cleanup, not just the read path.
+
+**Agent tuning notes:**
+- **coder (test-first bug fix)**: Write the failing tests **first** and record the predicted failure messages — here every one landed as predicted (`vec_memory` 3 vs 2, 2 chunks vs 1, `indexed 0 / skipped 2`, deleted-file chunks present, invariant 5 vectors vs 4 linked). A predicted-then-observed failure is much stronger evidence than a test that passes after the fact.
+- **coder (index audits)**: Enumerate all mutating paths — create, update, shrink, delete-source, failure — then assert the same invariant helper on each. The bug was in the paths that had never been tested, not in the one that had.
+- **deployer**: This was a **follow-up fix** to a bug deliberately recorded as open in commit `308c90f`; the tracker entry must explicitly mark that follow-up **resolved** so the audit trail does not keep an open defect that no longer exists. Re-run all three gates before and after, stage only the enumerated files, and use `SKIP_BUMP=1` so the fix does not bump the minor version.
+- **all agents (knowledge retrieval)**: `memory_search` returned "No results found. The index may be empty"; `knowledgebase_search` was **not executed** (PG vector unavailable — `DATABASE_URL` not configured). Both reported as skipped/unavailable, neither retried, neither treated as a task failure.

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

@@ -134,6 +134,17 @@ All `memory-bank/**/*.md` files must have YAML frontmatter for search indexing.
 
 ### Plan Mode
 
+Scope comes before planning. Underspecified work enters through the `scope` agent; planning starts only once the request is narrowed.
+
+1. **Scope first** — for an underspecified request, the front door is the `scope` agent (`.opencode/agents/scope.agent.md`). It runs grilling rounds against a single draft file, then writes a terminal spike document at `docs/spike-<feature>.md`.
+2. **Hand the spike to research** — that spike document is the input `researcher.agent.md` expects; pass its path as the required spike argument.
+3. **Continue the pipeline** — after research (or directly, when no research is needed), the work continues to `implementer`, `architect`, or `coder`, following the recommended next step recorded in the spike.
+4. **Deep planning is optional** — `plan.agent.md` remains available as an optional deep-planning mode for work that is already scoped. It is demoted in the default flow, not removed or deprecated.
+
+When scope runs, record the spike document in the memory bank (a task entry in `tasks/` and/or `activeContext.md`) before implementation planning begins, so the settled and deferred decisions survive a session reset.
+
+The flow below applies once the scope is settled:
+
 ```mermaid
 flowchart TD
     Start[Start] --> CheckGraph{graphify-out/graph.json exists?}

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/.agents/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/.agents/skills/domain-modeling/GLOSSARY-FORMAT.md

@@ -0,0 +1,60 @@
+# GLOSSARY.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `GLOSSARY.md` at the repo root.
+
+**Multiple contexts:** A `GLOSSARY-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Glossary Map
+
+## Contexts
+
+- [Ordering](./src/ordering/GLOSSARY.md): receives and tracks customer orders
+- [Billing](./src/billing/GLOSSARY.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/GLOSSARY.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `GLOSSARY-MAP.md` exists, read it to find contexts
+- If only a root `GLOSSARY.md` exists, single context
+- If neither exists, create a root `GLOSSARY.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.