@apogeelabs/the-agency 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apogeelabs/the-agency",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Centralized Claude Code agents, commands, and workflows",
   "type": "module",
   "bin": {

package/src/templates/.ai/UnitTestGeneration.md

@@ -10,9 +10,9 @@ Before generating any tests, complete these steps in order:
 
 1. **Branch analysis** (Coverage-Driven Test Planning): Read the source, enumerate every branch, map each to a test scenario.
 2. **Superfluous test check** (Superfluous Test Prevention): Verify each planned scenario covers a distinct branch, not the same branch with different values.
-3. **Execution location check** (CRITICAL RULE #1): Execute methods under test in `beforeEach()`, not in `it()` blocks.
-4. **Mock configuration check** (CRITICAL RULE #2): Configure mock behavior in `beforeEach`, not at module level.
-5. **Callback invocation check** (CRITICAL RULE #3): Use `mockImplementation` for callbacks, not `mock.calls[N][M]()`.
+3. **Execution location check** (CRITICAL RULE 1): Execute methods under test in `beforeEach()`, not in `it()` blocks.
+4. **Mock configuration check** (CRITICAL RULE 2): Configure mock behavior in `beforeEach`, not at module level.
+5. **Callback invocation check** (CRITICAL RULE 3): Use `mockImplementation` for callbacks, not `mock.calls[N][M]()`.
 
 Once tests are generated:
 
@@ -21,7 +21,7 @@ Once tests are generated:
 
 ---
 
-## CRITICAL RULE #1: Test Execution Location
+## CRITICAL RULE 1: Test Execution Location
 
 ⚠️ **NON-NEGOTIABLE RULE** ⚠️
 
@@ -97,7 +97,7 @@ Before writing any test suite, verify:
 
 ---
 
-## CRITICAL RULE #2: Mock Configuration Location
+## CRITICAL RULE 2: Mock Configuration Location
 
 ⚠️ **NON-NEGOTIABLE RULE** ⚠️
 
@@ -152,7 +152,7 @@ const mockLuxon = {
 
 ---
 
-## CRITICAL RULE #3: Callback Invocation via mockImplementation
+## CRITICAL RULE 3: Callback Invocation via mockImplementation
 
 ⚠️ **NON-NEGOTIABLE RULE** ⚠️
 
@@ -329,7 +329,7 @@ describe("when status is inactive", () => {
     - Inner `describe` blocks handle specific scenarios ("when X condition")
 - **Test descriptions**:
     - `describe` blocks handle the "when" conditions/scenarios
-    - `it` blocks focus purely on "should" assertions (no conditions). See **CRITICAL RULE #1** above.
+    - `it` blocks focus purely on "should" assertions (no conditions). See **CRITICAL RULE 1** above.
     - Avoid redundancy - don't repeat conditions in both `describe` and `it`
 - **Grouping logic**:
     - Group related test cases under shared setup scenarios
@@ -366,7 +366,7 @@ describe("when status is inactive", () => {
 - **State initialization**: Variables initialized in `beforeEach`
 - **Fresh state guarantee**:
     - Call `jest.clearAllMocks()` and `jest.resetModules()` in outer `beforeEach`
-    - **Do NOT use `jest.resetAllMocks()`** in the outer `beforeEach` — it wipes implementations, which breaks module-level `mockReturnThis()` chains (see CRITICAL RULE #2 exception)
+    - **Do NOT use `jest.resetAllMocks()`** in the outer `beforeEach` — it wipes implementations, which breaks module-level `mockReturnThis()` chains (see CRITICAL RULE 2 exception)
     - Use `mockReset()` on **individual mocks** when a nested `beforeEach` needs to replace behavior already configured by an outer `beforeEach`
     - **Never use `mockRestore()`** — it only applies to `jest.spyOn`, which this codebase does not use
 
@@ -385,14 +385,14 @@ Am I in the **outer** `beforeEach`?
 
 ## Mocking Strategy
 
-- **Module-level mock declarations**: Dependencies mocked above test suites with bare `jest.fn()` — see **CRITICAL RULE #2** for configuration rules
+- **Module-level mock declarations**: Dependencies mocked above test suites with bare `jest.fn()` — see **CRITICAL RULE 2** for configuration rules
 - **Mock behavior configuration**: Configured per scenario in `beforeEach` blocks
 - **Mock naming**: Consistent mock prefix (e.g., `mockLogger`, `mockGetMessageBroker`)
 - **Selective mocking**: Mock only the methods being used unless it significantly raises complexity
 - **Mock verification**: Always verify mock calls when behavior depends on them
 - **Mock realism**: Ensure mocks behave like real implementations (same async patterns, error types)
 - **Mock methods**:
-    - Use `mockImplementation` when invoking callbacks passed to the mocked function — see **CRITICAL RULE #3**
+    - Use `mockImplementation` when invoking callbacks passed to the mocked function — see **CRITICAL RULE 3**
     - Use `mockResolvedValue` for async returns
     - Use `mockReturnValue` for sync returns
     - Prefer "Once" versions when appropriate (`mockResolvedValueOnce`, etc.)

package/src/templates/.claude/agents/test-hardener.md

@@ -11,6 +11,27 @@ Make this code bulletproof by writing the tests the developer didn't think of. A
 
 You have NO knowledge of how this code was written. You are seeing it for the first time. You are NOT rewriting the developer's tests — you're adding what's missing.
 
+## Tooling — Non-Negotiable
+
+**Use ONLY the repo's established tooling to run and verify tests.** You must discover the repo's conventions before writing or running anything.
+
+### Discovery (do this FIRST, before writing any tests)
+
+1. Read `package.json` (root and any relevant workspace package). Identify the test script — it will be one of `npm test`, `pnpm test`, `yarn test`, or similar. That is your test runner. Period.
+2. If the repo is a monorepo, identify the workspace tool (`pnpm --filter`, `npm -w`, `yarn workspace`, `turbo run`, `nx run`, etc.) and use that to scope test runs to the relevant package.
+3. Read the test framework config (e.g., `jest.config.ts`, `vitest.config.ts`, `.mocharc.*`) to understand module resolution, transforms, and path aliases.
+4. Read `.ai/UnitTestGeneration.md` and `.ai/UnitTestExamples.md` if they exist. These are your style guide. Follow them exactly.
+
+### The Rules
+
+- **Run tests with the repo's test script.** `npm test`, `pnpm test`, `pnpm --filter <pkg> test`, etc. Whatever `package.json` says.
+- **DO NOT use `node -e`, `npx tsx`, `npx jest`, `ts-node`, or any ad-hoc command to run, compile, or verify code.** Ever. No exceptions. The repo has a test runner. Use it.
+- **DO NOT improvise test runners or verification methods.** If you're tempted to run something outside the repo's scripts to "quickly check" something, stop. Use the test script.
+- **DO NOT install packages, add dependencies, or modify package.json.** You write tests using what's already available.
+- **When running tests, scope them.** Don't run the entire test suite when you only need to verify one file. Use the test runner's built-in filtering (e.g., `pnpm test -- --testPathPattern=path/to/file` for Jest, or equivalent).
+
+If you catch yourself about to type `node -e` or `npx tsx` or anything that isn't the repo's test script, you are doing it wrong. Back away from the keyboard.
+
 ## Input
 
 1. Read the build plan from `docs/build-plans/` to understand intended behavior.
@@ -97,12 +118,14 @@ Map every branch (`if`/`else`, `try`/`catch`, `switch`, early returns) in the so
 
 ## Process
 
-1. Audit existing tests. Catalog what's covered.
-2. Identify gaps by category.
-3. Prioritize: likely to happen OR catastrophic if it does.
-4. **Before writing any test**, verify it against the anti-patterns above. For every planned `describe` block, identify the specific source line/branch it uniquely covers. If you cannot, drop it.
-5. Write tests. Follow the existing test framework and patterns exactly.
-6. Write your report.
+1. **Discover repo tooling.** Follow the Tooling — Non-Negotiable section above. Identify the package manager, test script, test framework config, and any workspace/monorepo conventions. Do this BEFORE reading any source code.
+2. Audit existing tests. Catalog what's covered.
+3. Identify gaps by category.
+4. Prioritize: likely to happen OR catastrophic if it does.
+5. **Before writing any test**, verify it against the anti-patterns above. For every planned `describe` block, identify the specific source line/branch it uniquely covers. If you cannot, drop it.
+6. Write tests. Follow the existing test framework and patterns exactly.
+7. Run tests using the repo's test script. Fix any failures before proceeding.
+8. Write your report.
 
 ## Output
 
@@ -146,9 +169,10 @@ Actual bugs discovered during test hardening.
 
 ## Verification
 
-Before writing the report, verify:
+Before writing the report, verify by **reading your own code and the source code** — not by running ad-hoc commands:
 
-1. Every new `describe` block covers a code path no existing test covers.
+1. Every new `describe` block covers a code path no existing test covers. Verify this by reading the source, not by running coverage tools.
 2. No tests target `.tsx` files or barrel exports.
 3. Tests are added to existing test files, not new ones.
 4. No existing tests were modified.
+5. All tests pass when run with the repo's test script. This is the ONLY command you should have executed via Bash during this entire process.

package/src/templates/.claude/commands/prep-pr.md

@@ -67,27 +67,50 @@ The developer can accept the default or specify another branch. Use whatever the
 
 ## Step 3: Gather Diff
 
-Check that there are commits ahead of the target branch:
+Fetch the latest state of the target branch from the remote so comparisons reflect what's actually on the remote, not a potentially stale local copy:
 
 ```bash
-git log --oneline $TARGET..HEAD
+git fetch origin $TARGET
+```
+
+### 3.1: Resolve Comparison Ref
+
+Default to `origin/$TARGET` (the remote tracking ref) for all diff and log comparisons. Before proceeding, check whether a local copy of the target branch exists and is ahead of the remote:
+
+```bash
+git rev-list --count origin/$TARGET..$TARGET 2>/dev/null
+```
+
+- **If the command fails** (no local branch exists), or **returns 0** (local is behind or even with remote): use `origin/$TARGET` silently. No prompt needed.
+- **If the count is greater than 0**: the local branch has commits not yet on the remote. Ask the developer:
+
+> **Your local `{$TARGET}` is {count} commit(s) ahead of `origin/{$TARGET}`.** Use local or remote for comparison? (default: remote)
+
+Use whichever ref the developer chooses as `$COMPARE_REF` for all subsequent diff and log commands. If they accept the default or don't respond, use `origin/$TARGET`.
+
+### 3.2: Check for Commits
+
+Check that there are commits ahead of the comparison ref:
+
+```bash
+git log --oneline $COMPARE_REF..HEAD
 ```
 
 **If no commits are returned**, stop and output:
 
-> **No commits ahead of `{$TARGET}`. Nothing to PR.** You may need to rebase.
+> **No commits ahead of `{$COMPARE_REF}`. Nothing to PR.** You may need to rebase.
 
-Gather the change data:
+### 3.3: Gather Change Data
 
 ```bash
 # File list with change stats
-git diff --stat $TARGET...HEAD
+git diff --stat $COMPARE_REF...HEAD
 
 # Full diff
-git diff $TARGET...HEAD
+git diff $COMPARE_REF...HEAD
 
 # Commit log (excluding merges)
-git log --no-merges --oneline $TARGET..HEAD
+git log --no-merges --oneline $COMPARE_REF..HEAD
 ```
 
 ## Step 4: Categorize and Filter Files

package/src/templates/.claude/commands/review-pr.md

@@ -50,19 +50,52 @@ gh pr view --json number,title,baseRefName,headRefName,body,additions,deletions,
 
 ## Step 3: Gather Diff Information
 
-Use `gh pr diff` to get the diff as GitHub sees it. This avoids stale-local-branch problems where a behind-origin base branch inflates the diff with already-merged changes from other PRs.
+### 3.1: Resolve Comparison Ref
+
+Fetch the latest state of the base branch from the remote:
+
+```bash
+git fetch origin $baseRefName
+```
+
+Default to using the remote for comparison (via `gh pr diff`). Before proceeding, check whether the local copy of the base branch is ahead of the remote:
 
 ```bash
-# File list with change stats
-gh pr diff --stat
+git rev-list --count origin/$baseRefName..$baseRefName 2>/dev/null
+```
+
+- **If the command fails** (no local branch exists), or **returns 0** (local is behind or even with remote): use the remote. No prompt needed.
+- **If the count is greater than 0**: the local branch has commits not yet on the remote. Ask the developer:
+
+> **Your local `{baseRefName}` is {count} commit(s) ahead of `origin/{baseRefName}`.** Use local or remote for comparison? (default: remote)
+
+Store the choice as `$DIFF_MODE` — either `remote` (default) or `local`.
+
+### 3.2: Get the Diff
+
+**If `$DIFF_MODE` is `remote`** (the 95% case):
 
-# Full diff (for analysis)
+Use `gh pr diff` to get the full diff as GitHub sees it. This avoids stale-local-branch problems where a behind-origin base branch inflates the diff with already-merged changes from other PRs.
+
+```bash
 gh pr diff
 ```
 
-**For commit messages**, use the `commits` array already captured in Step 2 — that is the authoritative commit list for this PR. Do NOT use `git log`, which can include commits from other PRs if the local base branch is behind origin.
+**If `$DIFF_MODE` is `local`:**
 
-**Cross-check**: Compare the file count from `gh pr diff --stat` against the `changedFiles` value from Step 2. If they diverge significantly, flag the discrepancy in your output and prefer the `gh pr view` / `gh pr diff` data as the source of truth.
+Use local git to diff against the local base branch:
+
+```bash
+git diff $baseRefName...HEAD
+```
+
+⚠️ Note: local diffs may differ slightly from GitHub's view in repos with complex merge histories.
+
+### 3.3: Stats and Commit Messages
+
+File-level stats (additions, deletions, file count) are already available from the `gh pr view --json` output captured in Step 2 — don't duplicate that work here.
+
+**For commit messages**, use the `commits` array already captured in Step 2 — that is the authoritative commit list for this PR. Do NOT use `git log`, which can include commits from other PRs if the local base branch is behind origin.
 
 ## Step 4: Categorize and Filter Files