@apogeelabs/the-agency 0.1.1 → 0.3.0

package/README.md

@@ -16,6 +16,9 @@ npx the-agency sync
 
 # Choose which files to sync
 npx the-agency sync --pick
+
+# Install optional review check plugins
+npx the-agency install-review-plugins
 ```
 
 Files are copied to `.claude/agents/`, `.claude/commands/`, and `.ai/` in the target project. If destination files already exist, you'll be prompted before overwriting.
@@ -39,12 +42,14 @@ Autonomous subagents that run in isolated context windows and communicate throug
 
 Slash commands invoked in Claude Code sessions.
 
-| Command      | Purpose                                            |
-| ------------ | -------------------------------------------------- |
-| `/architect` | Interactive architecture design session            |
-| `/build`     | Orchestrates the full dev → review → test pipeline |
-| `/pm`        | Interactive product requirements discovery         |
-| `/review-pr` | Structured PR review briefing                      |
+| Command           | Purpose                                            |
+| ----------------- | -------------------------------------------------- |
+| `/architect`      | Interactive architecture design session            |
+| `/build`          | Orchestrates the full dev → review → test pipeline |
+| `/pm`             | Interactive product requirements discovery         |
+| `/prep-pr`        | Pre-submission PR prep and draft creation          |
+| `/review-pr`      | Structured PR review briefing                      |
+| `/weekly-summary` | Weekly synthesis of merged PRs                     |
 
 ### AI Context (`.ai/`)
 
@@ -68,6 +73,43 @@ Reference material automatically available to Claude Code.
 
 See `.ai/workflow.md` after syncing for the full workflow guide.
 
+## Review Checks (`.ai/review-checks/`)
+
+The `/review-pr` command supports pluggable tribal knowledge checks. Place markdown files in `.ai/review-checks/` in your repo, and the review command discovers and evaluates them automatically.
+
+### Check File Format
+
+Each file uses YAML frontmatter with two fields:
+
+```markdown
+---
+name: Display Name for This Check Group
+applies_when: Natural language description of when these checks apply
+---
+
+- [ ] **Check name**: What to look for.
+```
+
+- **`name`** — heading used in the review output
+- **`applies_when`** — evaluated by the LLM against the PR's changed file list. Use plain language (e.g., "Changed files include `.tsx` files" or "Always").
+
+### Pre-packaged Plugins
+
+Install review plugins interactively:
+
+```bash
+npx the-agency install-review-plugins
+```
+
+This presents a multi-select of available plugins and copies your selections to `.ai/review-checks/`.
+
+| Plugin                | Targets                                             | Checks                                                                                               |
+| --------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **react-frontend.md** | `.tsx`, `.jsx`, `.css`, `.scss`, `.styled.ts` files | Hard-coded colors, missing `data-cy` attributes, accessibility gaps                                  |
+| **node-backend.md**   | `.ts` files in backend/service directories          | `console.log` usage, boundary violations, raw SQL, error swallowing                                  |
+| **general.md**        | All PRs (unconditional)                             | New env vars, dead code, dependency changes, type safety (`any`, `as`, `@ts-ignore`)                 |
+| **unit-test.md**      | `.test.ts`, `.spec.ts` files                        | Style guide adherence, barrel export testing, test description accuracy, missing `export default {}` |
+
 ## Project-Specific Configuration
 
 The sync does **not** copy `settings.local.json` or `settings.json` — those are project-specific. See the [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code) for configuring permissions per-project.

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { sync } from "./sync.js";
+import { installReviewPlugins } from "./install-review-plugins.js";
 const args = process.argv.slice(2);
 const command = args[0];
 if (!command || command === "help" || command === "--help") {
@@ -6,14 +7,17 @@ if (!command || command === "help" || command === "--help") {
 Usage: the-agency <command> [options]
 
 Commands:
-  sync          Sync all Claude Code files to the current project
-  sync --pick   Interactively select which files to sync
+  sync                    Sync all Claude Code files to the current project
+  sync --pick             Interactively select which files to sync
+  install-review-plugins  Install optional review check plugins
 `);
   process.exit(0);
 }
 if (command === "sync") {
   const pick = args.includes("--pick");
   await sync({ pick });
+} else if (command === "install-review-plugins") {
+  await installReviewPlugins();
 } else {
   console.error(`Unknown command: ${command}`);
   process.exit(1);

package/dist/install-review-plugins.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Presents an interactive multi-select of available review plugins and
+ * copies the selected ones into the consumer's project.
+ *
+ * This is deliberately separate from `sync` — sync handles core setup
+ * (agents, commands, AI context), while review plugins are optional
+ * extras that users pick à la carte.
+ */
+declare function installReviewPlugins(): Promise<void>;
+
+export { installReviewPlugins };

package/dist/install-review-plugins.js

@@ -0,0 +1,67 @@
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { copyFile, mkdir } from "node:fs/promises";
+import prompts from "prompts";
+import { manifest } from "./manifest.js";
+import { fileExists } from "./sync.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const srcDir = join(packageRoot, "src/review-plugins");
+const destDir = ".ai/review-checks";
+async function installReviewPlugins() {
+  const choices = manifest.reviewPlugins.map((plugin) => ({
+    title: plugin.file,
+    description: plugin.description,
+    value: plugin.file,
+    selected: true
+  }));
+  const { selected } = await prompts({
+    type: "multiselect",
+    name: "selected",
+    message: "Select review plugins to install",
+    choices,
+    instructions: false,
+    hint: "- Space to toggle, Enter to confirm"
+  });
+  if (!selected || selected.length === 0) {
+    console.log("Nothing selected. Exiting.");
+    return;
+  }
+  const destBase = join(process.cwd(), destDir);
+  const existing = [];
+  for (const file of selected) {
+    const dest = join(destBase, file);
+    if (await fileExists(dest)) {
+      existing.push(file);
+    }
+  }
+  if (existing.length > 0) {
+    console.log(`
+Existing files that will be overwritten:`);
+    for (const file of existing) {
+      console.log(`  - ${destDir}/${file}`);
+    }
+    const { proceed } = await prompts({
+      type: "confirm",
+      name: "proceed",
+      message: `Overwrite ${existing.length} existing file(s)?`,
+      initial: true
+    });
+    if (!proceed) {
+      console.log("Install cancelled.");
+      return;
+    }
+  }
+  await mkdir(destBase, { recursive: true });
+  for (const file of selected) {
+    const src = join(srcDir, file);
+    const dest = join(destBase, file);
+    await copyFile(src, dest);
+    console.log(`  \u2713 ${destDir}/${file}`);
+  }
+  console.log(`
+Installed ${selected.length} review plugin(s).`);
+}
+export {
+  installReviewPlugins
+};

package/dist/manifest.d.ts

@@ -6,6 +6,7 @@ interface Manifest {
     agents: ManifestItem[];
     commands: ManifestItem[];
     ai: ManifestItem[];
+    reviewPlugins: ManifestItem[];
 }
 declare const manifest: Manifest;
 

package/dist/manifest.js

@@ -11,12 +11,32 @@ const manifest = {
     { file: "architect.md", description: "Interactive architecture design sessions" },
     { file: "build.md", description: "Build orchestrator pipeline" },
     { file: "pm.md", description: "Interactive product requirements discovery" },
-    { file: "review-pr.md", description: "Structured PR review briefing" }
+    { file: "prep-pr.md", description: "Pre-submission PR prep and draft creation" },
+    { file: "review-pr.md", description: "Structured PR review briefing" },
+    { file: "weekly-summary.md", description: "Weekly synthesis of merged PRs" }
   ],
   ai: [
     { file: "UnitTestGeneration.md", description: "TypeScript/Jest unit testing style guide" },
     { file: "UnitTestExamples.md", description: "Reference examples for the test style guide" },
     { file: "workflow.md", description: "Multi-agent development workflow guide" }
+  ],
+  reviewPlugins: [
+    {
+      file: "general.md",
+      description: "General checks: env vars, type safety, dead code, debugging leftovers, breaking changes, binary assets"
+    },
+    {
+      file: "node-backend.md",
+      description: "Node.js backend checks: API design, error handling, security, database patterns"
+    },
+    {
+      file: "react-frontend.md",
+      description: "React frontend checks: component design, hooks, rendering, accessibility"
+    },
+    {
+      file: "unit-test.md",
+      description: "Unit test checks: test quality, coverage, mocking patterns, assertions"
+    }
   ]
 };
 export {

package/dist/sync.d.ts

@@ -5,8 +5,26 @@ interface SyncFile {
     dest: string;
     label: string;
 }
+/**
+ * Resolves manifest categories into concrete source/destination file paths.
+ * Only categories present in `categoryConfig` are valid — passing unknown
+ * categories (e.g. `reviewPlugins`) will throw at runtime.
+ */
 declare function getFilesToSync(categories: Record<string, ManifestItem[]>): SyncFile[];
+/**
+ * Checks whether a file exists at the given path.
+ * Uses `fs.access` rather than `stat` to avoid TOCTOU overhead we don't need.
+ */
 declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Copies agent, command, and AI context files from the package into the
+ * consumer's project. In pick mode, presents an interactive multi-select;
+ * otherwise syncs everything.
+ *
+ * Review plugins are deliberately excluded — they have their own install
+ * flow via `install-review-plugins` since they're opt-in extras, not
+ * core setup.
+ */
 declare function sync({ pick }?: {
     pick?: boolean | undefined;
 }): Promise<void>;

package/dist/sync.js

@@ -35,7 +35,10 @@ async function fileExists(path) {
 async function sync({ pick = false } = {}) {
   let selectedCategories;
   if (pick) {
-    const choices = Object.entries(manifest).flatMap(
+    const syncableCategories = Object.entries(manifest).filter(
+      ([category]) => category in categoryConfig
+    );
+    const choices = syncableCategories.flatMap(
       ([category, items]) => items.map((item) => ({
         title: `${categoryConfig[category].dest}/${item.file}`,
         description: item.description,
@@ -61,7 +64,8 @@ async function sync({ pick = false } = {}) {
       selectedCategories[category].push(item);
     }
   } else {
-    selectedCategories = { ...manifest };
+    const { agents, commands, ai } = manifest;
+    selectedCategories = { agents, commands, ai };
   }
   const files = getFilesToSync(selectedCategories);
   const existing = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apogeelabs/the-agency",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Centralized Claude Code agents, commands, and workflows",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/",
     "dist/",
     "src/templates/",
+    "src/review-plugins/",
     "!src/templates/.claude/settings*.json"
   ],
   "dependencies": {

package/src/review-plugins/general.md

@@ -0,0 +1,12 @@
+---
+name: General Checks
+applies_when: Always — applies to all PRs regardless of file types
+---
+
+- [ ] **New environment variables**: Are there new `process.env.*` references that need documentation or deployment configuration?
+- [ ] **Type safety**: Are there `any` types, type assertions (`as`), or `@ts-ignore` / `@ts-expect-error` comments that bypass TypeScript's type system?
+- [ ] **Dead code**: Flag new functions, methods, constants, or type definitions that are exported or defined but never referenced by any other code in the diff. Also flag commented-out code blocks and unreachable code after unconditional `return`, `throw`, or `process.exit` statements. If it's not called, imported, or reachable, it shouldn't be merged.
+- [ ] **Dependency changes**: Flag new packages added to `dependencies` or `devDependencies`. For each new dependency, consider: does the project already have a library that does this? Is a full package warranted or would a few lines of code suffice? Also flag removed packages (is anything still importing them?) and major version bumps (check for breaking changes in the upgrade path).
+- [ ] **Leftover debugging**: Flag `debugger` statements, `console.debug`, `.only` on test cases (`describe.only`, `it.only`, `test.only`), artificial delays (`sleep()`, `setTimeout` used as a wait hack), and commented-out code that was clearly used during development (e.g., commented-out `console.log`, toggled feature flags, hardcoded user IDs). These are fine locally — not fine in a merge to main.
+- [ ] **Breaking interface changes**: Flag changes to exported function signatures, type definitions, or shared interfaces that alter the contract — renamed fields, removed parameters, changed return types, narrowed union types. In a monorepo, these can silently break consumers in other packages. Flag when there's no corresponding update to callers visible in the diff, and no migration note or changelog entry.
+- [ ] **Large binary/asset additions**: Flag images, fonts, PDFs, video files, database dumps, or other binary assets added directly to the repo, especially files over 500KB. These inflate the git history permanently and typically belong in a CDN, object store, or asset pipeline. Small icons and favicons are fine.

package/src/review-plugins/node-backend.md

@@ -0,0 +1,17 @@
+---
+name: Node Backend Checks
+applies_when: Changed files include .ts files in backend or service directories (excluding test files)
+---
+
+- [ ] **Console.log usage**: Is `console.log` used instead of the project's structured logger?
+- [ ] **Boundary violations**: Is a handler reaching into a repository directly instead of going through a service layer?
+- [ ] **Raw SQL**: Are there string-concatenated queries instead of parameterized queries via the project's query builder?
+- [ ] **Error swallowing**: Are errors being caught and silently discarded without logging or re-throwing?
+- [ ] **Readability at a glance**: Can a developer unfamiliar with this code follow the logic 6 months from now? Flag functions longer than ~40 lines that lack decomposition, deeply nested conditionals (3+ levels), boolean parameters without named constants or descriptive variable assignments, and variable names that are ambiguous or require context to interpret (e.g., `data`, `result`, `temp`, `val`, single-letter names outside of trivial loops).
+- [ ] **Documentation gaps**: Public functions and methods should have JSDoc comments documenting purpose, parameters, and return values. Non-obvious logic — workarounds, business rules, performance trade-offs, "this looks wrong but isn't" patterns — should have inline comments explaining _why_, not _what_. Flag new public functions missing JSDoc and non-trivial logic blocks that would confuse a reader without context.
+- [ ] **N+1 query patterns**: Flag loops that execute a database call (find, findOne, aggregate, query, get, fetch) per iteration instead of batching. This includes `for` loops, `.forEach`, `.map`, and `for...of` over a collection where each iteration hits the DB. The fix is typically a single bulk query (`$in`, `WHERE IN`, `mget`, pipeline) before the loop, then an in-memory lookup. Also flag `Promise.all` wrapping per-item DB calls — it's parallel but still N round-trips.
+- [ ] **Unvalidated external input**: Flag request body fields, query parameters, route parameters, and header values used directly in business logic or DB queries without schema validation (e.g., zod, joi, class-validator). Trusting `req.body.email` without parsing it is an injection and type-safety risk. Internal function-to-function calls within the service layer do NOT need validation — only system boundaries (HTTP handlers, queue consumers, webhook receivers).
+- [ ] **Leaking internals in API responses**: Flag error handlers or response payloads that expose stack traces, raw database error messages, internal collection/table names, internal IDs (like MongoDB `_id` when a public-facing ID exists), or implementation details (library names, file paths). API consumers should get structured error codes and user-safe messages, not a guided tour of your infrastructure.
+- [ ] **Race conditions in async code**: Flag missing `await` on promises whose result or side effects matter (fire-and-forget is only acceptable for truly independent, failure-tolerant operations like analytics). Flag parallel mutations to shared state (e.g., two `await` calls that both read-then-write the same document without guarding against interleaving). Flag `Promise.all` over operations that have implicit ordering dependencies.
+- [ ] **Overly broad try/catch**: Flag `try` blocks spanning more than ~15-20 lines or wrapping multiple distinct operations where the `catch` handles all failures identically. Different failure modes (network error, validation error, auth error, DB constraint violation) usually need different responses. If a single `catch(e)` logs and returns a generic 500 for all of them, flag it. Each distinct failure mode should be catchable and handleable separately.
+- [ ] **Hardcoded magic numbers**: Flag raw numeric literals used for timeouts, retry counts, page sizes, rate limits, cache TTLs, port numbers, or threshold values. These should be named constants or pulled from configuration. `setTimeout(fn, 30000)` is unreadable; `setTimeout(fn, CACHE_TTL_MS)` communicates intent. Exceptions: `0`, `1`, `-1` in obvious arithmetic/index contexts, and HTTP status codes (e.g., `res.status(404)`) are fine.

package/src/review-plugins/react-frontend.md

@@ -0,0 +1,22 @@
+---
+name: React & Frontend Checks
+applies_when: Changed files include .tsx, .jsx, .css, .scss, or .styled.ts files
+---
+
+- [ ] **Hard-coded colors**: Are there hex values, `rgb()`, or named colors that should use theme variables or design tokens?
+- [ ] **Missing data-cy attributes**: Do new interactive elements (buttons, inputs, links, dropdowns) have `data-cy` attributes for end-to-end testing?
+- [ ] **Accessibility gaps**: Missing `alt` text on images? Click handlers on non-interactive elements (`div`, `span`) without proper roles? Missing `aria-label` on icon-only buttons?
+- [ ] **One public component per file**: Each `.tsx` file should export only one React component. If additional helper components exist in the same file, they must NOT be exported and should have a `/** @private */` JSDoc comment above their declaration. Flag any file that exports multiple components, or has unexported components missing the `@private` pragma.
+- [ ] **No direct component tests**: `.tsx` component files should NOT have corresponding `.test.tsx` or `.spec.tsx` test files. Style-only hooks (e.g., `useStyles`, `useTheme`) also do not need tests UNLESS the hook contains conditional logic that affects code paths beyond styling. Flag any new test file that directly tests a `.tsx` component or a pure-styling hook.
+- [ ] **BEM class naming**: CSS class names must follow BEM (Block Element Modifier) convention: `.block__element--modifier`. Flag class names that use camelCase, generic names without BEM structure, or inconsistent delimiter usage (e.g., single underscores or hyphens where BEM expects doubles).
+- [ ] **Rem units over pixels**: Use `rem` for all sizing and spacing values. `px` is acceptable ONLY for media query breakpoints. Flag any `px` usage in properties like `font-size`, `margin`, `padding`, `width`, `height`, `gap`, `border-radius`, etc.
+- [ ] **Inline styles**: Flag `style={{...}}` props in JSX. Styling should live in stylesheets, styled components, or style hooks — not inline objects. Exceptions: truly dynamic values computed at runtime (e.g., positioning from a calculation) are acceptable, but static visual properties (`color`, `padding`, `fontSize`) are not.
+- [ ] **Missing `key` on dynamic lists**: Flag `.map()` calls that return JSX without a `key` prop. Also flag usage of array index as `key` on lists that can be reordered, filtered, or have items added/removed — index keys cause subtle re-render bugs in those cases. Stable identifiers (IDs, slugs) are required.
+- [ ] **Direct DOM manipulation**: Flag usage of `document.querySelector`, `document.getElementById`, `document.createElement`, `.innerHTML`, `.innerText` assignment, or `.appendChild`. React components should use refs (`useRef`) for DOM access and state for DOM updates. Direct DOM manipulation bypasses React's reconciliation and causes stale UI.
+- [ ] **Inline event handler allocation in lists**: Flag arrow functions defined directly in JSX event props (`onClick={() => handler(id)}`) when they appear inside `.map()` or other list-rendering patterns. These create a new function reference per render per item. Extract to a named handler or use `useCallback`. Single-instance components (not in a loop) are fine.
+- [ ] **Derived state anti-pattern**: Flag `useState` + `useEffect` pairs where the effect's only job is to compute a value from other state or props and store it back into state. This should be `useMemo` (for expensive computations) or a plain `const` (for cheap ones). The pattern creates unnecessary render cycles and is a common source of stale-state bugs.
+- [ ] **Hardcoded user-facing strings**: Flag literal text strings rendered in JSX that a user would see on screen — headings, button labels, tooltips, placeholder text, error messages, `aria-label` values. These should use the project's i18n system (e.g., `t('key')`). Do NOT flag non-user-facing strings like prop names, CSS classes, `data-cy` values, log messages, or enum/constant comparisons.
+- [ ] **Missing error boundaries**: Flag new top-level route components or major feature entry-point components that are not wrapped in an error boundary. An unhandled throw in a component tree without a boundary will unmount the entire app. Leaf components and small utility components do not need their own boundaries.
+- [ ] **Prop drilling**: Flag props being passed through two or more intermediate components that don't use them — they just forward them deeper. This suggests the value should live in a React context, a state management store, or the component tree should be restructured using composition (children/render props). Name the prop and the pass-through chain in your finding.
+- [ ] **Non-memoized context values**: Flag React context providers where the `value` prop is an object literal, array literal, or function created inline (e.g., `<Ctx.Provider value={{ user, setUser }}>`). Every render creates a new reference, forcing all consumers to re-render. Wrap the value in `useMemo` (objects/arrays) or `useCallback` (functions).
+- [ ] **`useEffect` missing cleanup**: Flag `useEffect` hooks that create subscriptions (e.g., `addEventListener`, WebSocket connections, `subscribe()` calls), timers (`setTimeout`, `setInterval`), or `AbortController` instances without returning a cleanup function that tears them down. Also flag `async` operations in effects that set state after completion without checking whether the component is still mounted (missing abort signal or cancelled flag). These are memory leak and state-update-after-unmount bugs.

package/src/review-plugins/unit-test.md

@@ -0,0 +1,10 @@
+---
+name: Unit Test Checks
+applies_when: Changed files include .test.ts or .spec.ts files
+---
+
+- [ ] **Style guide adherence**: Test files must follow the conventions in `.ai/UnitTestGeneration.md`. Key rules to verify: method under test is executed in `beforeEach()` with assertions only in `it()` blocks (Critical Rule #1), mock behavior is configured in `beforeEach`/`beforeAll` and never at module level (Critical Rule #2), callbacks are invoked via `mockImplementation` and never via `mock.calls[N][M]()` (Critical Rule #3). Also check for coverage-driven test planning (every branch in the source has a corresponding test scenario) and superfluous test prevention (no duplicate scenarios exercising the same code path with different literal values). Note: the guide's suggestion to use "fun" test data is optional — straightforward data is equally acceptable.
+- [ ] **No testing pure style hooks**: Do not test hooks that simply export a memoized style object or return static style values (e.g., `useStyles`, `useTheme` wrappers that just return a `useMemo` around a style object). If the hook contains conditional logic, branching, or computation that determines _which_ styles to return based on props/state, it should be tested. The distinction: does the hook have code paths a reviewer would want coverage on, or is it just a memoized constant?
+- [ ] **No testing barrel exports**: Flag any new test file that tests an `index.ts` barrel export file (a file whose only purpose is re-exporting from other modules). These files have zero logic and zero branches — testing them adds maintenance cost with no coverage value.
+- [ ] **Test descriptions match assertions**: Flag `describe`/`it` blocks where the text description doesn't match what the `expect` statements actually verify. For example, `it("should return the user")` followed by `expect(mockLogger.warn).toHaveBeenCalled()` is a mismatch — the description claims one behavior but the assertion checks something unrelated. Descriptions should accurately predict what the assertions verify.
+- [ ] **Missing `export default {}`**: Every test file must include `export default {};` near the top of the file (after any eslint pragma comments). This prevents global scope collision between test files. Flag any new or modified test file missing this export — the resulting failures are cryptic and hard to trace back to this cause.