@apogeelabs/the-agency 0.6.0 → 0.8.0

package/package.json

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

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

@@ -2,15 +2,15 @@
 
 ## Goal
 
-Prepare and create a draft pull request for the current branch. Run pre-submission checks, generate a PR title and description, collect testing steps, and create the draft PR.
+Prepare and create a draft pull request for the current branch. Run pre-submission checks, generate a full PR review, collect optional author testing notes, and create the draft PR.
 
 This command takes no arguments. It operates on the currently checked-out branch.
 
-<!-- Sibling command: review-pr.md uses the same plugin discovery/loading flow but with deeper evaluation. If the plugin format changes, update both files. -->
+<!-- Sibling command: review-pr.md uses the same analysis approach and plugin discovery/loading flow. If the analysis format or plugin format changes, update both files. -->
 
 ## Constraints
 
-- This command is conversational. There are multiple points where you pause and wait for developer input (Step 2, Step 6, Step 7, Step 8). Don't try to rush through without their responses.
+- This command is conversational. There are multiple points where you pause and wait for developer input (Step 2, Step 10, Step 11, Step 12). Don't try to rush through without their responses.
 - Check failures are informational, not blocking. The developer can still create the PR even if checks fail.
 - Always create the PR as a draft. No option to toggle this.
 - If the developer wants to bail at any point, respect that. Don't push them to continue.
@@ -90,11 +90,94 @@ git diff $TARGET...HEAD
 git log --no-merges --oneline $TARGET..HEAD
 ```
 
-## Step 4: Review Plugin Checks
+## Step 4: Categorize and Filter Files
 
-Review plugin checks are loaded dynamically from `.ai/review-checks/`. Each check file is a markdown file with YAML frontmatter.
+Before analysis, categorize the changed files:
 
-<!-- This is the same discovery/loading flow as review-pr.md, but with lighter evaluation: pass/fail with brief file/line pointers rather than full reviewer narrative. -->
+**Noise files (acknowledge but don't analyze deeply):**
+
+- `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` -> "lock file updated"
+- `*.min.js`, `*.min.css`, `dist/*`, `build/*` -> "generated/bundled files"
+- Binary files (images, fonts, etc.) -> "binary file added/modified/deleted"
+
+**Categorize by area:**
+
+Group changed files by top-level directory. If the repo uses workspaces (check for a `workspaces` field in `package.json` or the presence of `pnpm-workspace.yaml`), use the workspace definitions to inform grouping. Otherwise, fall back to top-level directory names.
+
+## Step 5: Analyze Changes
+
+### For Small PRs (fewer than 30 changed files):
+
+Analyze **per-commit**. For each commit, produce a narrative block with:
+
+1. **The Mental Model Shift** -- plain English explanation of how the codebase's story changed. Focus on "why" and "so what," not restating the diff. Highlight:
+    - Architectural shifts or new patterns introduced
+    - Patterns retired or approaches abandoned
+    - Code that appears orphaned, half-finished, or disconnected
+
+2. **What Changed Structurally** -- numbered list of concrete changes:
+    - Collapse repetitive/mechanical changes (e.g., "~15 files updated imports from X to Y")
+    - Call out meaningful changes individually with enough context to understand impact
+
+### For Large PRs (30 or more changed files):
+
+Analyze **by theme/area** rather than per-commit. Group changes by package or functional area:
+
+1. First, identify the major themes/areas touched
+2. For each theme, produce a narrative block (Mental Model Shift + Structural Changes)
+3. After per-area analysis, produce a **holistic summary** that captures cross-cutting changes and overall architectural impact
+
+### Analysis Guidance:
+
+- **Explain the "why" and "so what"**, not just the "what"
+- **Collapse noise**: If 50 files have the same mechanical change, that's one bullet point
+- **Highlight signal**: New public APIs, changed interfaces, deleted capabilities, behavioral changes
+- **Flag disconnects**: Code that doesn't seem to connect to anything, half-implemented features, TODOs left behind
+- **Note removals**: Deleted code is as important as added code -- what capability is gone?
+
+## Step 6: Identify Risks
+
+Scan for and report:
+
+**Security concerns:**
+
+- Auth/authorization changes
+- New API endpoints or route changes
+- Injection vectors (SQL, command, XSS)
+- Sensitive data in logs or error messages
+- Secrets or credentials (even if they look like placeholders)
+- Changes to validation or sanitization
+
+**Behavioral risks:**
+
+- Changes to public APIs or interfaces
+- Modified default values or fallback behavior
+- Error handling changes that might swallow errors
+- Timing or ordering changes in async code
+
+**Architectural concerns:**
+
+- Layer boundary violations (e.g., handler calling repository directly)
+- New circular dependencies
+- Assumptions in one layer that depend on implementation details of another
+- Patterns that diverge from established codebase conventions
+
+**Dependency concerns:**
+
+- New dependencies added
+- Dependencies removed (what relied on them?)
+- Major version bumps
+- Dependencies with known security issues
+
+**Before finalizing risk callouts related to test files (`.test.ts`, `.spec.ts`):**
+
+Read `.ai/UnitTestGeneration.md` (if it exists) and cross-reference any test-related findings against the project's testing conventions. Do NOT flag patterns that conform to those guidelines -- they are intentional, not risks.
+
+## Step 7: Tribal Knowledge Checks
+
+Tribal knowledge checks are loaded dynamically from `.ai/review-checks/`. Each check file is a markdown file with YAML frontmatter.
+
+<!-- This is the same discovery/loading flow as review-pr.md. -->
 
 **Expected check file format:**
 
@@ -116,7 +199,7 @@ applies_when: Changed files include .ts files in src/
 ls .ai/review-checks/*.md 2>/dev/null
 ```
 
-2. **If the directory does not exist or contains no `.md` files**, skip the entire review plugin checks section silently — no error, no placeholder text. Proceed to Step 5.
+2. **If the directory does not exist or contains no `.md` files**, skip the entire Tribal Knowledge Checks section silently -- no error, no placeholder text. Proceed to Step 8.
 
 3. **If files are found**, read each one:
 
@@ -126,34 +209,60 @@ cat .ai/review-checks/*.md
 
 4. For each file, parse the YAML frontmatter to extract `name` and `applies_when`. If a file is missing frontmatter or has invalid/unparseable YAML, skip it and note: "Skipped `{filename}`: missing or invalid frontmatter."
 
-5. Evaluate each file's `applies_when` value against the list of changed files from the diff (gathered in Step 3). Use your judgment — `applies_when` is natural language, not a glob pattern. Match generously but sensibly.
+5. Evaluate each file's `applies_when` value against the list of changed files from the diff (gathered in Step 3). Use your judgment -- `applies_when` is natural language, not a glob pattern. Match generously but sensibly.
 
-6. For each check group where `applies_when` matches, evaluate each check item against the diff. Output format: **pass/fail per check with brief file/line pointers for failures** — enough breadcrumb to find and fix the issue, not a full review narrative.
+6. For each check group where `applies_when` matches, include its checks in the output under a heading using the `name` from frontmatter. Evaluate each check against the actual diff.
 
-7. If files exist but **none** of their `applies_when` criteria match the diff, skip the check results silently.
-
-Store the check results — they'll be included in the PR body later.
+7. If files exist but **none** of their `applies_when` criteria match the diff, skip the Tribal Knowledge Checks section entirely.
 
 Display the check results to the developer as you go so they can see what passed and what needs attention.
 
-## Step 5: Generate Title and Description
+## Step 8: Testing Recommendations
+
+Based on the changes, provide concrete testing recommendations. This is NOT generic "write more tests" advice -- recommendations must be tied to the actual changes.
+
+### What to recommend:
+
+**Manual verification:**
+
+- Specific user flows or scenarios the reviewer should manually test
+- Edge cases introduced by the changes that aren't obvious from reading the code
+- Integration points that might behave differently after these changes
+
+**Automated test coverage:**
+
+- New code paths that lack corresponding tests
+- Behavioral changes that existing tests might not cover
+- Specific test scenarios to add (with enough detail to write the test)
+- **Do NOT recommend tests for React components (`.tsx` files).** We do not unit test React components.
+
+**Regression risks:**
+
+- Existing functionality that might be affected and should be regression tested
+- Areas where the change assumptions might conflict with existing behavior
+
+### Guidance:
+
+- Be specific: "Test the login flow with an expired token" not "test authentication"
+- Reference the actual changes: "The new `validateApiKey` middleware should be tested with missing, invalid, and expired keys"
+- Prioritize: If there are many potential tests, highlight the most important ones first
+- If the PR includes good test coverage already, acknowledge that and note any gaps
+
+## Step 9: Generate Title
 
 Analyze the diff and commit history gathered in Step 3. Generate:
 
 - **Title**: Concise, reflects the nature of the changes (bug fix, feature, refactor, etc.). Keep it under 70 characters.
-- **Description**: Summarize what changed and why. Focus on the "so what" — not a restatement of the diff. Draw from commit messages and the actual code changes.
-
-For large diffs, prioritize analyzing `git diff --stat` and the commit log, then selectively read diffs for the most significant files rather than trying to process the entire diff.
 
-## Step 6: Collect Testing Steps
+## Step 10: Collect Author Testing Notes (Optional)
 
 Ask the developer:
 
-> **Testing steps — how should a reviewer verify these changes?**
+> **Do you have any additional testing steps you'd like to include?** These will appear in the PR as "PR Author Testing Recommendations" alongside the generated testing analysis. Feel free to skip if the generated recommendations cover it.
 
-The developer provides their own testing steps as free-form text. These are NOT AI-generated. Wait for their input before proceeding.
+If the developer provides testing steps, store them for inclusion in the PR body. If they skip or decline, proceed without them.
 
-## Step 7: Present Full Preview
+## Step 11: Present Full Preview
 
 Show the developer the complete PR preview:
 
@@ -164,24 +273,59 @@ Show the developer the complete PR preview:
 
 ---
 
+# {title}
+
+**Branch**: {current branch} -> {$TARGET}
+**Changes**: {additions} additions, {deletions} deletions across {changed file count} files
+
+---
+
 ## Summary
 
-{generated description}
+[Per-commit or per-theme narrative blocks from Step 5]
 
-## Test Plan
+---
 
-{developer-provided testing steps}
+## Risk Callouts
+
+[Risks from Step 6, or "No significant risks identified"]
+
+---
+
+## Tribal Knowledge Checks
+
+[Only if matching check files were found in Step 7. Omit section entirely otherwise.]
+
+### [name from check file frontmatter]
+
+- [x] [Check passed or N/A]
+- [ ] **[Check failed]**: [Specific finding with file:line references]
+
+---
+
+## Testing Recommendations
+
+### Manual Verification
+
+- [Specific scenario to test manually]
+
+### Automated Test Gaps
+
+- [Specific test that should be written]
+
+### Regression Risks
+
+- [Existing functionality to regression test]
 ```
 
-If check results exist from Step 4, also show:
+If the developer provided author testing notes in Step 10, also show:
 
 ```
-<details>
-<summary>Pre-submission Checks</summary>
+---
 
-{check results — pass/fail with names}
+## PR Author Testing Recommendations
 
-</details>
+{developer-provided testing steps}
 ```
 
 Then ask:
@@ -190,7 +334,7 @@ Then ask:
 
 Let the developer make edits. Iterate until they're satisfied.
 
-## Step 8: Push Branch
+## Step 12: Push Branch
 
 Check whether the branch has an upstream and is up to date:
 
@@ -218,32 +362,60 @@ git push -u origin $(git branch --show-current)
 
 **If the branch is already up to date with the remote**, skip this step silently.
 
-## Step 9: Create Draft PR
+## Step 13: Create Draft PR
 
-Assemble the PR body:
+Assemble the PR body using the full review content from Steps 5-8:
 
 ```
+# {title}
+
+**Branch**: {current branch} -> {$TARGET}
+**Changes**: {additions} additions, {deletions} deletions across {changed file count} files
+
+---
+
 ## Summary
 
-{description}
+{per-commit or per-theme narrative blocks}
 
-## Test Plan
+---
+
+## Risk Callouts
 
-{testing steps}
+{risks, or "No significant risks identified"}
 ```
 
-If check results exist from Step 4, append:
+If tribal knowledge check results exist from Step 7, append:
 
 ```
-<details>
-<summary>Pre-submission Checks</summary>
+---
 
-{check results — pass/fail with names}
+## Tribal Knowledge Checks
 
-</details>
+{check results with pass/fail and file:line references}
 ```
 
-If no check results (no plugin files found or none matched), omit the `<details>` section entirely.
+If no check results (no plugin files found or none matched), omit the Tribal Knowledge Checks section entirely.
+
+Append the testing recommendations from Step 8:
+
+```
+---
+
+## Testing Recommendations
+
+{testing recommendations}
+```
+
+If the developer provided author testing notes in Step 10, append:
+
+```
+---
+
+## PR Author Testing Recommendations
+
+{developer-provided testing steps}
+```
 
 Create the draft PR:
 

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

@@ -223,7 +223,7 @@ Based on the changes in this PR, provide concrete testing recommendations. This
 Produce your output as inline markdown with these sections:
 
 ```markdown
-# PR Review: #{number} — {title}
+# {title}
 
 **Branch**: {headRefName} → {baseRefName}
 **Changes**: {additions} additions, {deletions} deletions across {changedFiles} files
@@ -288,3 +288,31 @@ Each block contains:
 
 [If test coverage is already good, say so and note any minor gaps]
 ```
+
+## Step 9: Offer to Update PR Description
+
+After producing the review output, ask the user:
+
+> **Would you like to update the PR description with this review?**
+
+If the user declines, you're done.
+
+If the user accepts, update the PR description by prepending the review content above the original description, separated as follows:
+
+```
+{review content}
+
+---
+Original PR Description
+---
+
+{original PR description}
+```
+
+Use the `body` captured in Step 2 as the original PR description. Update the PR with:
+
+```bash
+gh pr edit --body "{new body content}"
+```
+
+⚠️ **Preserve the original description exactly as-is** — no reformatting, no trimming, no "improving" it.