@codyswann/lisa 1.76.6 → 1.78.0

package/all/deletions.json

@@ -125,12 +125,16 @@
     ".claude/hooks/track-plan-sessions.sh",
     ".claude/hooks/verify-completion.sh",
     ".claude/hooks/README.md",
-    ".claude/rules/coding-philosophy.md",
     ".claude/rules/verfication.md",
     ".coderabbit.yml",
     "scripts/setup-deploy-key.sh",
     "HUMAN.md",
     ".claude/rules/lisa.md",
+    ".claude/rules/base-rules.md",
+    ".claude/rules/coding-philosophy.md",
+    ".claude/rules/intent-routing.md",
+    ".claude/rules/security-audit-handling.md",
+    ".claude/rules/verification.md",
     ".lisa-manifest"
   ],
   "keep": [

package/package.json

@@ -74,7 +74,7 @@
     "flatted": "^3.4.2"
   },
   "name": "@codyswann/lisa",
-  "version": "1.76.6",
+  "version": "1.78.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "1.76.6",
+  "version": "1.78.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"
@@ -96,6 +96,15 @@
           }
         ]
       },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [
@@ -115,6 +124,17 @@
         ]
       }
     ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": "",

package/plugins/lisa/hooks/inject-rules.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Reads all .md files from the plugin's rules/ directory and injects them
+# into the session context via additionalContext.
+# Used by SessionStart and SubagentStart hooks.
+set -euo pipefail
+
+RULES_DIR="${CLAUDE_PLUGIN_ROOT}/rules"
+
+# Bail silently if no rules directory
+[ -d "$RULES_DIR" ] || exit 0
+
+CONTEXT=""
+for file in "$RULES_DIR"/*.md; do
+  [ -f "$file" ] || continue
+  CONTEXT+="$(cat "$file")"$'\n\n'
+done
+
+# Bail if no rules found
+[ -n "$CONTEXT" ] || exit 0
+
+# Output as JSON — jq handles escaping
+jq -n --arg ctx "$CONTEXT" '{"additionalContext": $ctx}'

package/{all/copy-overwrite/.claude → plugins/lisa}/rules/base-rules.md

@@ -2,12 +2,15 @@ Requirement Verification:
 
 Never assume the person providing instructions has given you complete, correct, or technically precise requirements. Treat every request as potentially underspecified. Before starting any work:
 
-1. Verify the request is specific enough to produce a verifiable outcome. If it is not, stop and ask for clarification.
-2. Verify you can empirically prove the work is done when complete (e.g. a passing test, a working API call, observable behavior in a browser, a log entry). If you cannot define how to prove it, stop and ask for clarification.
-3. If a request contradicts existing code, architecture, or conventions, do not silently comply. Raise the contradiction and confirm intent before proceeding.
+1. Identify any ambiguities in the request that would prevent you from completing the work. If any exist, stop and ask for clarification.
+2. Identify any open questions whose answers would change your approach. If any exist, stop and ask.
+3. Define how you will empirically verify the work is complete — not by running tests or linters, but by using the resulting software the way a user would. If you cannot define this, stop and ask for clarification.
+4. If a request contradicts existing code, architecture, or conventions, do not silently comply. Raise the contradiction and confirm intent before proceeding.
 
 DO NOT START WORK if any of the above are unclear. Asking a clarifying question is always cheaper than implementing the wrong thing.
 
+Do not begin a task if there are any blockers, ambiguities, access requirements, unanswered questions, or unknowns that would prevent you from completing it. Identify these before starting — not during implementation. If you cannot confirm that you have everything needed to finish the work end-to-end, stop and surface what is missing.
+
 Project Discovery:
 - Determine the project's package manager before installing or running anything.
 - Read the project manifest (e.g. package.json, pyproject.toml, Cargo.toml, go.mod) to understand available scripts and dependencies.

package/{all/copy-overwrite/.claude → plugins/lisa}/rules/verification.md

@@ -16,6 +16,16 @@ No agent may claim success without evidence from runtime verification.
 
 Never assume something works because the code "looks correct." Run a command, observe the output, compare to expected result.
 
+**Verification is not linting, typechecking, or testing.** Those are quality checks. Verification is using the resulting software the way a user would — interacting with the UI, calling the API, running the CLI command, observing the behavior. Tests pass in isolation; verification proves the system works as a whole. Passing tests, linting, and typechecking does not constitute verification.
+
+Verification is mandatory. Never skip it, defer it, or claim it was unnecessary. Every task must be verified before claiming completion.
+
+Before starting implementation, state your verification plan — how you will use the resulting software to prove it works. Do not begin implementation until the plan is confirmed.
+
+After verifying a change empirically, encode that verification as automated tests. The manual proof that something works should become a repeatable regression test that catches future regressions. Every verification should answer: "How do I turn this into a test?"
+
+Every pull request must include step-by-step instructions for reviewers to independently replicate the verification. These are not test commands — they are the exact steps a human would follow to use the software and confirm the change works. If a reviewer cannot reproduce your verification from the PR description alone, the PR is incomplete.
+
 ---
 
 ## Roles

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "1.76.6",
+  "version": "1.78.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "1.76.6",
+  "version": "1.78.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "1.76.6",
+  "version": "1.78.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,11 +1,33 @@
 {
   "name": "lisa-rails",
-  "version": "1.76.6",
+  "version": "1.78.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

package/plugins/lisa-rails/hooks/inject-rules.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Reads all .md files from the plugin's rules/ directory and injects them
+# into the session context via additionalContext.
+# Used by SessionStart and SubagentStart hooks.
+set -euo pipefail
+
+RULES_DIR="${CLAUDE_PLUGIN_ROOT}/rules"
+
+# Bail silently if no rules directory
+[ -d "$RULES_DIR" ] || exit 0
+
+CONTEXT=""
+for file in "$RULES_DIR"/*.md; do
+  [ -f "$file" ] || continue
+  CONTEXT+="$(cat "$file")"$'\n\n'
+done
+
+# Bail if no rules found
+[ -n "$CONTEXT" ] || exit 0
+
+# Output as JSON — jq handles escaping
+jq -n --arg ctx "$CONTEXT" '{"additionalContext": $ctx}'

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "1.76.6",
+  "version": "1.78.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/.claude-plugin/plugin.json

@@ -58,9 +58,13 @@
     ],
     "SessionStart": [
       { "matcher": "startup", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/install-pkgs.sh" }] },
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] },
       { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/setup-jira-cli.sh" }] },
       { "matcher": "", "hooks": [{ "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code session-start || true" }] }
     ],
+    "SubagentStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] }
+    ],
     "SessionEnd": [
       { "matcher": "", "hooks": [{ "type": "command", "command": "command -v entire >/dev/null 2>&1 && entire hooks claude-code session-end || true" }] }
     ]

package/plugins/src/base/hooks/inject-rules.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Reads all .md files from the plugin's rules/ directory and injects them
+# into the session context via additionalContext.
+# Used by SessionStart and SubagentStart hooks.
+set -euo pipefail
+
+RULES_DIR="${CLAUDE_PLUGIN_ROOT}/rules"
+
+# Bail silently if no rules directory
+[ -d "$RULES_DIR" ] || exit 0
+
+CONTEXT=""
+for file in "$RULES_DIR"/*.md; do
+  [ -f "$file" ] || continue
+  CONTEXT+="$(cat "$file")"$'\n\n'
+done
+
+# Bail if no rules found
+[ -n "$CONTEXT" ] || exit 0
+
+# Output as JSON — jq handles escaping
+jq -n --arg ctx "$CONTEXT" '{"additionalContext": $ctx}'

package/plugins/src/base/rules/base-rules.md

@@ -0,0 +1,91 @@
+Requirement Verification:
+
+Never assume the person providing instructions has given you complete, correct, or technically precise requirements. Treat every request as potentially underspecified. Before starting any work:
+
+1. Identify any ambiguities in the request that would prevent you from completing the work. If any exist, stop and ask for clarification.
+2. Identify any open questions whose answers would change your approach. If any exist, stop and ask.
+3. Define how you will empirically verify the work is complete — not by running tests or linters, but by using the resulting software the way a user would. If you cannot define this, stop and ask for clarification.
+4. If a request contradicts existing code, architecture, or conventions, do not silently comply. Raise the contradiction and confirm intent before proceeding.
+
+DO NOT START WORK if any of the above are unclear. Asking a clarifying question is always cheaper than implementing the wrong thing.
+
+Do not begin a task if there are any blockers, ambiguities, access requirements, unanswered questions, or unknowns that would prevent you from completing it. Identify these before starting — not during implementation. If you cannot confirm that you have everything needed to finish the work end-to-end, stop and surface what is missing.
+
+Project Discovery:
+- Determine the project's package manager before installing or running anything.
+- Read the project manifest (e.g. package.json, pyproject.toml, Cargo.toml, go.mod) to understand available scripts and dependencies.
+- Read the project's linting and formatting configuration to understand its standards.
+- Regenerate the lockfile after adding, removing, or updating dependencies.
+- Ignore build output directories (dist, build, out, target, etc.) unless specified otherwise.
+- Ignore configuration linter hints/warnings — only fix actual unused exports/dependencies reported as errors.
+
+Code Quality:
+- Make atomic commits with clear conventional commit messages.
+- Create clear documentation preambles for new code. Update preambles when modifying existing code.
+- Document the "why", not the "what". Code explains what it does; documentation explains why it exists.
+- Always add new imports and their first usage in the same edit. The lint-on-edit hook runs `eslint --fix` after every Edit, which auto-removes unused imports. If you add an import in one edit and plan to use it in a second edit, the hook will strip the import before the second edit runs.
+- Add language specifiers to fenced code blocks in Markdown.
+- Use project-relative paths rather than absolute paths in documentation and Markdown.
+- Delete old code completely when replacing it. No deprecation unless specifically requested.
+- Fix bugs and issues properly. Never cover them up or work around them.
+- Test empirically to confirm something worked. Never assume.
+- Never assume test expectations before verifying actual implementation behavior. Run tests to learn the behavior, then adjust expectations to match.
+- Always provide a solution. Never dismiss something as "not related to our changes" or "not relevant to this task".
+
+Git Discipline:
+- Prefix git push with `GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"`.
+- Never commit directly to an environment branch (dev, staging, main).
+- Never use --no-verify or attempt to bypass a git hook.
+- Never stash changes you cannot commit. Either fix whatever is preventing the commit or fail out and let the human know why.
+- Never add "BREAKING CHANGE" to a commit message unless there is actually a breaking change.
+- When opening a PR, watch the PR. If any status checks fail, fix them. For all bot code reviews, if the feedback is valid, implement it and push the change to the PR. Then resolve the feedback. If the feedback is not valid, reply to the feedback explaining why it's not valid and then resolve the feedback. Do this in a loop until the PR is able to be merged and then merge it.
+- When merging a PR into an environment branch (dev, staging, main), watch the resultant deploy until it fully succeeds. If it fails for any reason, fix the failure and then open a new PR with the fix.
+- When referencing a PR in a response, always include the url
+
+Testing Discipline:
+- Never skip or disable any tests or quality checks.
+- Never add skip directives to a test unless explicitly asked to.
+- Never lower thresholds to pass a pre-push hook. Increase test coverage to make it pass.
+- Never duplicate test helper functions without appropriate lint suppression when duplication is intentional for test isolation.
+
+JIRA Discipline:
+- If working on a JIRA issue, make sure the branch you're working on references and is added to the JIRA issue.
+- If working on a JIRA issue, update the issue as you work through it. For example, if working on a Bug Triage, update the issue with your questions/feedback/suggestions.
+
+Agent Behavior:
+- Never handle tasks yourself when working in a team of agents. Always delegate to a specialized agent.
+
+NEVER:
+- Modify this file directly. To add a memory or learning, use the project's rules file or create a skill.
+- Directly modify files inside dependency directories (e.g. node_modules, .venv, vendor, target).
+- Delete anything that is not tracked in git.
+- Delete anything outside of this project's directory.
+- Create placeholder implementations.
+- Create TODOs.
+- Create versioned copies of files or functions (e.g. V2, Optimized, processNew, handleOld).
+- Write migration code unless explicitly requested.
+- Write functions or methods unless they are needed.
+- Write unhelpful comments like "removed code" or "old implementation".
+- Update CHANGELOG.
+
+ASK FIRST:
+- Before adding a lint suppression comment (e.g. eslint-disable, noqa, #[allow(...)], @SuppressWarnings). These should be a last resort.
+- Before adding a type-checking suppression comment (e.g. ts-ignore, ts-expect-error, ts-nocheck, type: ignore).
+- Lint suppression in test files is acceptable without asking only when comprehensive test coverage requires it (e.g. file length limits) or when intentional duplication improves test isolation. Include matching re-enable comments where applicable.
+
+Multi-Repository Awareness:
+
+When working in a microservices architecture, the code you need may span multiple repositories. Watch for these signals that you're missing context:
+
+1. Import paths or package references that don't resolve in the current repository
+2. API calls to internal services where you can't find the contract, schema, or handler
+3. Shared libraries, SDKs, or proto/OpenAPI definitions referenced but not present
+4. Environment variables or config referencing service names you don't have code for
+5. Error messages or stack traces pointing to code outside the current repo
+6. JIRA issues or documentation referencing components in other repositories
+
+When you detect any of the above:
+1. Do NOT guess or make assumptions about what the external code does
+2. Identify which repository contains the missing code
+3. Add that repository to your current session before proceeding
+4. If you cannot determine which repository contains the code, ask — do not proceed without it

package/plugins/src/base/rules/coding-philosophy.md

@@ -0,0 +1,428 @@
+# Coding Philosophy
+
+This rule enforces the core coding philosophy: **immutability**, **predictable structure**, **functional transformations**, **test-driven development**, **clean deletion**, and **simplicity**.
+
+## Guiding Principles: YAGNI + SOLID + DRY + KISS
+
+Follow these software engineering principles, **deferring to Occam's Razor/KISS whenever principles conflict**:
+
+### KISS (Keep It Simple, Stupid) - The Tiebreaker
+
+When principles conflict, **always choose the simpler solution**.
+
+```typescript
+// KISS: Simple direct approach
+const isAdmin = user.role === "admin";
+
+// Over-engineered: Abstraction without value
+const isAdmin = RoleChecker.getInstance().checkRole(user, RoleTypes.ADMIN);
+```
+
+### YAGNI (You Ain't Gonna Need It)
+
+Don't build features, abstractions, or flexibility you don't need **right now**.
+
+```typescript
+// Correct: Solve today's problem
+const formatDate = (date: Date) => date.toISOString().split("T")[0];
+
+// Wrong: Building for hypothetical future needs
+const formatDate = (date: Date, format?: string, locale?: string, timezone?: string) => {
+  // 50 lines handling cases that may never be used
+};
+```
+
+### DRY (Don't Repeat Yourself) - With KISS Constraint
+
+Extract duplication only when:
+1. The same logic appears **3+ times**
+2. The abstraction is **simpler** than the duplication
+3. The extracted code has a **clear single purpose**
+
+### SOLID Principles - Applied Pragmatically
+
+| Principle                 | Apply When                                    | Skip When                               |
+| ------------------------- | --------------------------------------------- | --------------------------------------- |
+| **S**ingle Responsibility | Function does 2+ unrelated things             | Splitting adds complexity               |
+| **O**pen/Closed           | Extension points have clear use cases         | No foreseeable extensions               |
+| **L**iskov Substitution   | Using inheritance hierarchies                 | Using composition (preferred)           |
+| **I**nterface Segregation | Consumers need different subsets              | Interface is already small              |
+| **D**ependency Inversion  | Testing requires mocking external services    | Direct dependency is simpler            |
+
+### Decision Framework
+
+When unsure, ask in order:
+1. **Do I need this now?** (YAGNI) - If no, don't build it
+2. **Is there a simpler way?** (KISS) - Choose the simpler option
+3. **Am I repeating myself 3+ times?** (DRY) - Extract if the abstraction is simpler
+4. **Does this function do one thing?** (SOLID-SRP) - Split only if clearer
+
+---
+
+## Core Principles
+
+### 1. Immutability First
+
+Never mutate data. Always create new references.
+
+```typescript
+// Correct - spread creates new object
+const updated = { ...user, name: "New Name" };
+
+// Incorrect - mutation
+user.name = "New Name";
+```
+
+### 2. Function Structure Ordering
+
+All functions, hooks, and components follow a strict ordering:
+
+```text
+1. Variable definitions and derived state (const, useState, useMemo, useCallback)
+2. Side effects (useEffect, function calls with no return value)
+3. Return statement
+```
+
+### 3. Functional Transformations
+
+Use `map`, `filter`, `reduce` instead of imperative loops and mutations.
+
+```typescript
+// Correct - functional transformation
+const names = users.map(u => u.name);
+
+// Incorrect - imperative mutation
+const names = [];
+users.forEach(u => names.push(u.name));
+```
+
+### 4. Test-Driven Development (TDD)
+
+**Always write failing tests before implementation code.** This is mandatory, not optional.
+
+```text
+TDD Cycle:
+1. RED: Write a failing test that defines expected behavior
+2. GREEN: Write the minimum code to make the test pass
+3. REFACTOR: Clean up while keeping tests green
+```
+
+### 5. Clean Deletion
+
+**Delete old code completely.** No deprecation warnings, migration shims, or backward-compatibility layers unless explicitly requested.
+
+```typescript
+// Correct: Remove the old code entirely
+const calculateScore = (player: Player): number => player.stats.overall;
+
+// Wrong: Keeping deprecated versions around
+/** @deprecated Use calculateScore instead */
+const getPlayerScore = (player: Player): number => calculateScore(player);
+```
+
+**Clean deletion rules:**
+- When replacing code, delete the old version completely
+- Never create `V2`, `New`, or `Old` suffixed functions/variables
+- Never add `@deprecated` comments - just remove the code
+- Never write migration code unless explicitly asked
+- Trust git history for recovery if needed
+
+---
+
+## Quick Reference
+
+### Variable Declaration
+
+| Pattern | Status    | Example                       |
+| ------- | --------- | ----------------------------- |
+| `const` | Required  | `const value = calculate();`  |
+| `let`   | Forbidden | Use ternary or reduce instead |
+| `var`   | Forbidden | Never use                     |
+
+### Array Operations
+
+| Instead of              | Use                                          |
+| ----------------------- | -------------------------------------------- |
+| `arr.push(item)`        | `[...arr, item]`                             |
+| `arr.pop()`             | `arr.slice(0, -1)`                           |
+| `arr.splice(i, 1)`      | `arr.filter((_, idx) => idx !== i)`          |
+| `arr.sort()`            | `[...arr].sort()`                            |
+| `arr[i] = value`        | `arr.map((v, idx) => idx === i ? value : v)` |
+| `forEach` with mutation | `reduce` or `map`                            |
+
+### Object Operations
+
+| Instead of                | Use                           |
+| ------------------------- | ----------------------------- |
+| `obj.key = value`         | `{ ...obj, key: value }`      |
+| `delete obj.key`          | `({ key: _, ...rest } = obj)` |
+| `Object.assign(obj, ...)` | `{ ...obj, ...other }`        |
+
+### Building Lookup Objects
+
+```typescript
+// Correct - reduce with spread
+const lookup = items.reduce(
+  (acc, item) => ({ ...acc, [item.id]: item }),
+  {} as Record<string, Item>
+);
+
+// Incorrect - forEach with Map.set
+const lookup = new Map();
+items.forEach(item => lookup.set(item.id, item));
+```
+
+### Conditional Values
+
+```typescript
+// Correct - ternary expression
+const status = isComplete ? "done" : "pending";
+
+// Incorrect - let with reassignment
+let status = "pending";
+if (isComplete) {
+  status = "done";
+}
+```
+
+---
+
+## Hook Structure Example
+
+```typescript
+export const usePlayerData = (playerId: string) => {
+  // 1. VARIABLES & STATE (first)
+  const [isLoading, setIsLoading] = useState(true);
+  const { data } = useQuery(GetPlayerDocument, { variables: { playerId } });
+
+  const playerName = useMemo(() => data?.player?.name ?? "Unknown", [data]);
+
+  const handleRefresh = useCallback(() => {
+    refetch();
+  }, [refetch]);
+
+  // 2. SIDE EFFECTS (second)
+  useEffect(() => {
+    console.log("Player loaded:", playerName);
+  }, [playerName]);
+
+  // 3. RETURN (last)
+  return { playerName, isLoading, handleRefresh };
+};
+```
+
+## Container Component Example
+
+```typescript
+const PlayerCardContainer: React.FC<Props> = ({ playerId }) => {
+  // 1. VARIABLES & STATE
+  const { data, loading } = useQuery(GetPlayerDocument, { variables: { playerId } });
+  const { colors } = useTheme();
+
+  const formattedStats = useMemo(
+    () => data?.stats?.map(s => ({ ...s, display: formatStat(s) })) ?? [],
+    [data?.stats]
+  );
+
+  const handlePress = useCallback(() => {
+    router.push(`/players/${playerId}`);
+  }, [playerId]);
+
+  // 2. SIDE EFFECTS (none in this example)
+
+  // 3. RETURN
+  return (
+    <PlayerCardView
+      stats={formattedStats}
+      colors={colors}
+      loading={loading}
+      onPress={handlePress}
+    />
+  );
+};
+```
+
+## Utility Function Example
+
+```typescript
+export const calculateTeamRankings = (
+  players: readonly Player[]
+): readonly TeamRanking[] => {
+  // 1. VARIABLES & DERIVED VALUES
+  const validPlayers = players.filter(p => p.team && p.score != null);
+
+  const teamScores = validPlayers.reduce(
+    (acc, player) => ({
+      ...acc,
+      [player.team.id]: {
+        teamId: player.team.id,
+        totalScore: (acc[player.team.id]?.totalScore ?? 0) + player.score,
+        count: (acc[player.team.id]?.count ?? 0) + 1,
+      },
+    }),
+    {} as Record<string, { teamId: string; totalScore: number; count: number }>
+  );
+
+  const rankings = Object.values(teamScores).map(t => ({
+    teamId: t.teamId,
+    avgScore: t.totalScore / t.count,
+  }));
+
+  const sorted = [...rankings].sort((a, b) => b.avgScore - a.avgScore);
+
+  // 2. NO SIDE EFFECTS IN PURE FUNCTIONS
+
+  // 3. RETURN
+  return sorted;
+};
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### Never use `let` for conditional assignment
+
+```typescript
+// Wrong
+let result;
+if (condition) {
+  result = valueA;
+} else {
+  result = valueB;
+}
+
+// Correct
+const result = condition ? valueA : valueB;
+```
+
+### Never mutate arrays
+
+```typescript
+// Wrong
+const items = [];
+data.forEach(d => items.push(transform(d)));
+
+// Correct
+const items = data.map(d => transform(d));
+```
+
+### Never use Map when Record suffices
+
+```typescript
+// Wrong
+const lookup = new Map<string, User>();
+users.forEach(u => lookup.set(u.id, u));
+const user = lookup.get(userId);
+
+// Correct
+const lookup = users.reduce(
+  (acc, u) => ({ ...acc, [u.id]: u }),
+  {} as Record<string, User>
+);
+const user = lookup[userId];
+```
+
+### Never sort in place
+
+```typescript
+// Wrong - mutates original
+const sorted = items.sort((a, b) => a.value - b.value);
+
+// Correct - creates new array
+const sorted = [...items].sort((a, b) => a.value - b.value);
+```
+
+### Never place useEffect before variable definitions
+
+```typescript
+// Wrong
+useEffect(() => {
+  /* ... */
+}, [value]);
+const value = useMemo(() => calculate(), [dep]);
+
+// Correct
+const value = useMemo(() => calculate(), [dep]);
+useEffect(() => {
+  /* ... */
+}, [value]);
+```
+
+---
+
+## Immutable Patterns Reference
+
+### Building Lookup Objects with Reduce
+
+```typescript
+const colorMap =
+  edges?.reduce(
+    (acc, edge) => (edge.color ? { ...acc, [edge.tagId]: edge.color } : acc),
+    {} as Record<string, string>
+  ) ?? {};
+```
+
+### Accumulating Multiple Properties
+
+```typescript
+const teamGprAccumulator = validPlayers.reduce(
+  (acc, player) => {
+    const teamId = player.team?.id;
+    if (!teamId) return acc;
+
+    const existing = acc[teamId];
+    return {
+      ...acc,
+      [teamId]: {
+        teamId,
+        teamName: player.team.name,
+        gprSum: (existing?.gprSum ?? 0) + player.gpr,
+        playerCount: (existing?.playerCount ?? 0) + 1,
+      },
+    };
+  },
+  {} as Record<string, { teamId: string; teamName: string; gprSum: number; playerCount: number }>
+);
+```
+
+### Nested Object Updates
+
+```typescript
+const updated = {
+  ...state,
+  user: {
+    ...state.user,
+    profile: {
+      ...state.user.profile,
+      avatar: newAvatar,
+    },
+  },
+};
+```
+
+### Conditional Property Addition
+
+```typescript
+const result = {
+  ...baseObj,
+  ...(condition && { optionalProp: value }),
+};
+```
+
+### Ternary Chain for Multiple Conditions
+
+```typescript
+const priority = score > 90 ? "high" : score > 70 ? "medium" : "low";
+```
+
+### Readonly Types for Function Parameters
+
+```typescript
+export const calculateTeamGprRank = (
+  leaguePlayers: readonly (PlayerWithScores | null | undefined)[],
+  myTeamId: string | null | undefined
+): number | null => {
+  // ...
+};
+```

package/plugins/src/base/rules/intent-routing.md

@@ -0,0 +1,126 @@
+# Intent Routing
+
+Classify the user's request and execute the matching flow. Each flow is a sequence of agents. Sub-flows can be invoked by any flow.
+
+## Flows
+
+### Fix
+When: Bug reports, broken behavior, error messages, JIRA bug tickets.
+
+Sequence:
+1. `git-history-analyzer` — understand why affected code exists, find related past fixes/reverts
+2. `debug-specialist` — reproduce the bug, prove root cause with evidence
+3. `architecture-specialist` — assess fix risk, identify files to change, check for ripple effects
+4. `test-specialist` — design regression test strategy
+5. `bug-fixer` — implement fix via TDD (reproduction becomes failing test)
+6. **Verify sub-flow**
+7. **Ship sub-flow**
+8. `learner` — capture discoveries for future sessions
+
+### Build
+When: New features, stories, tasks, JIRA story/task tickets.
+
+Sequence:
+1. `product-specialist` — define acceptance criteria, user flows, error states
+2. `architecture-specialist` — research codebase, design approach, map dependencies
+3. `test-specialist` — design test strategy (coverage, edge cases, TDD sequence)
+4. `builder` — implement via TDD (acceptance criteria become tests)
+5. **Verify sub-flow**
+6. **Review sub-flow**
+7. **Ship sub-flow**
+8. `learner` — capture discoveries
+
+### Investigate
+When: "Why is this happening?", triage requests, JIRA spike tickets.
+
+Sequence:
+1. `git-history-analyzer` — understand code evolution, find related changes
+2. `debug-specialist` — reproduce, trace execution, prove root cause
+3. `ops-specialist` — check logs, errors, health (if runtime issue)
+4. Report findings with evidence, recommend next action (Fix, Build, or escalate)
+
+### Plan
+When: "Break this down", epic planning, large scope work, JIRA epic tickets.
+
+Sequence:
+1. `product-specialist` — define acceptance criteria for the whole scope
+2. `architecture-specialist` — understand scope, map dependencies, identify cross-cutting concerns
+3. Break down into ordered tasks, each with: acceptance criteria, verification type, dependencies
+
+### Verify
+When: Pre-ship quality gate. Used as a sub-flow by Fix and Build.
+
+Sequence:
+1. Run full test suite — all tests must pass before proceeding
+2. Run quality checks — lint, typecheck, and format
+3. `verification-specialist` — verify acceptance criteria are met empirically
+
+### Ship
+When: Code is ready to deploy. Used as a sub-flow by Fix, Build, and Improve.
+
+Sequence:
+1. Commit — atomic conventional commits via `git-commit` skill
+2. PR — create/update pull request via `git-submit-pr` skill
+3. **Review sub-flow** (if not already done)
+4. PR Watch Loop (repeat until mergeable):
+   - If status checks fail → fix and push
+   - If merge conflicts → resolve and push
+   - If bot review feedback (CodeRabbit, etc.):
+     - Valid feedback → implement fix, push, resolve comment
+     - Invalid feedback → reply explaining why, resolve comment
+   - Repeat until all checks pass and all comments are resolved
+5. Merge the PR
+6. `ops-specialist` — deploy to target environment
+7. `verification-specialist` — post-deploy health check and smoke test
+8. `ops-specialist` — monitor for errors in first minutes
+
+### Review
+When: Code review requests, PR review, quality assessment. Used as a sub-flow by Build.
+
+Sequence:
+1. Run in parallel: `quality-specialist`, `security-specialist`, `performance-specialist`
+2. `product-specialist` — verify acceptance criteria are met empirically
+3. `test-specialist` — verify test coverage and quality
+4. Consolidate findings, ranked by severity
+
+### Improve
+When: Refactoring, optimization, coverage improvement, complexity reduction.
+
+Sequence:
+1. `architecture-specialist` — identify target, measure baseline, plan approach
+2. `test-specialist` — ensure existing test coverage before refactoring (safety net)
+3. `builder` — implement improvements via TDD
+4. `verification-specialist` — measure again, prove improvement
+5. **Ship sub-flow**
+6. `learner` — capture discoveries
+
+#### Improve: Test Quality
+When: "Improve tests", "strengthen test suite", "fix weak tests", test quality improvement.
+
+Sequence:
+1. `test-specialist` — scan tests, identify weak/brittle tests, rank by improvement impact
+2. `builder` — implement test improvements
+3. **Verify sub-flow**
+4. **Ship sub-flow**
+5. `learner` — capture discoveries
+
+### Monitor
+When: "Check the logs", "Any errors?", health checks, production monitoring.
+
+Sequence:
+1. `ops-specialist` — health checks, log inspection, error monitoring, performance analysis
+2. Report findings, escalate if action needed
+
+## JIRA Entry Point
+
+When the request references a JIRA ticket (ticket ID like PROJ-123 or a JIRA URL):
+
+1. Hand off to `jira-agent`
+2. `jira-agent` reads the ticket, validates structural quality, and runs analytical triage
+3. If triage finds unresolved ambiguities, `jira-agent` posts findings and STOPS — no work begins
+4. `jira-agent` determines intent and delegates to the appropriate flow above
+5. `jira-agent` syncs progress at milestones and posts evidence at completion
+
+## Sub-flow Usage
+
+Flows reference sub-flows by name. When a flow says "Ship sub-flow", execute the full Ship sequence. When it says "Review sub-flow", execute the full Review sequence. Sub-flows can be nested (e.g., Ship includes Review).

package/plugins/src/base/rules/security-audit-handling.md

@@ -0,0 +1,30 @@
+# Security Audit Handling
+
+If `git push` fails because the pre-push hook reports security vulnerabilities, follow these steps. Never use `--no-verify` to bypass the security audit.
+
+## Node.js Projects (GHSA advisories)
+
+1. Note the GHSA ID(s), affected package(s), and advisory URL from the error output
+2. Check the advisory URL to determine if a patched version of the vulnerable package exists
+3. If a patched version exists: add a resolution/override in package.json to force the patched version (add to both `resolutions` and `overrides` sections), then run the package manager install command to regenerate the lockfile, commit the changes, and retry the push
+4. If no patched version exists and the vulnerability is safe for this project (e.g., transitive dependency with no untrusted input, devDeps only, or build tool only): add an exclusion entry to `audit.ignore.local.json` with the format `{"id": "GHSA-xxx", "package": "pkg-name", "reason": "why this is safe for this project"}`, then commit and retry the push
+
+### Critical: Override the vulnerable package, not its parent
+
+When the audit output shows a dependency chain like `@expo/cli › glob › minimatch`, the vulnerable package is **minimatch**, not glob. Always override the **leaf package** that has the actual vulnerability.
+
+**Never override a parent package to force a lower major version** — other packages in the project may depend on a newer major version, and a resolution/override forces ALL installations to the specified version. For example, overriding `glob` to `^8.1.0` will break `@expo/cli` which requires `glob@^13.0.0`, causing `expo prebuild` to fail with `files.map is not a function`.
+
+Before adding a resolution/override, verify:
+- You are targeting the **actually vulnerable package**, not a parent in the chain
+- The override version is **compatible with all dependents** (check with `bun why <package>` or `npm ls <package>`)
+- The override does not **downgrade** a package across a major version boundary that other dependencies require
+
+## Rails Projects (bundler-audit)
+
+1. Note the advisory ID, affected gem, and advisory URL from the error output
+2. Check if a patched version of the gem exists
+3. If a patched version exists:
+   - If the gem is a **direct dependency** (listed in Gemfile): update its version constraint in Gemfile, run `bundle update <gem>`, commit the changes, and retry the push
+   - If the gem is a **transitive dependency** (not in Gemfile, only in Gemfile.lock): run `bundle update <gem>` to pull the patched version without changing the Gemfile, commit the lockfile change, and retry the push
+4. If no patched version exists and the vulnerability is safe for this project: document the exception and retry the push

package/plugins/src/base/rules/verification.md

@@ -0,0 +1,93 @@
+# Empirical Verification
+
+This repository supports AI agents as first-class contributors.
+
+This file is the operational contract that defines how agents plan work, execute changes, verify outcomes, and escalate when blocked.
+
+If anything here conflicts with other repo docs, treat this file as authoritative for agent behavior.
+
+---
+
+## Core Principle
+
+Agents must close the loop between code changes and observable system behavior.
+
+No agent may claim success without evidence from runtime verification.
+
+Never assume something works because the code "looks correct." Run a command, observe the output, compare to expected result.
+
+**Verification is not linting, typechecking, or testing.** Those are quality checks. Verification is using the resulting software the way a user would — interacting with the UI, calling the API, running the CLI command, observing the behavior. Tests pass in isolation; verification proves the system works as a whole. Passing tests, linting, and typechecking does not constitute verification.
+
+Verification is mandatory. Never skip it, defer it, or claim it was unnecessary. Every task must be verified before claiming completion.
+
+Before starting implementation, state your verification plan — how you will use the resulting software to prove it works. Do not begin implementation until the plan is confirmed.
+
+After verifying a change empirically, encode that verification as automated tests. The manual proof that something works should become a repeatable regression test that catches future regressions. Every verification should answer: "How do I turn this into a test?"
+
+Every pull request must include step-by-step instructions for reviewers to independently replicate the verification. These are not test commands — they are the exact steps a human would follow to use the software and confirm the change works. If a reviewer cannot reproduce your verification from the PR description alone, the PR is incomplete.
+
+---
+
+## Roles
+
+### Builder Agent
+
+Implements the change in code and infrastructure.
+
+### Verifier Agent
+
+Acts as the end user (human user, API client, operator, attacker, or system) and produces proof artifacts.
+
+Verifier Agent must be independent from Builder Agent when possible.
+
+### Human Overseer
+
+Approves risky operations, security boundary crossings, and any work the agents cannot fully verify.
+
+---
+
+## Verification Levels
+
+Agents must label every task outcome with exactly one of these:
+
+- **FULLY VERIFIED**: Verified in the target environment with end-user simulation and captured artifacts.
+- **PARTIALLY VERIFIED**: Verified in a lower-fidelity environment or with incomplete surfaces, with explicit gaps documented.
+- **UNVERIFIED**: Verification blocked, human action required, no claim of correctness permitted.
+
+---
+
+## Verification Types
+
+Every change requires one or more verification types. Classify the change first, then verify each applicable type.
+
+### Always Required
+
+| Type | What to prove | Acceptable proof |
+|------|---------------|------------------|
+| **Test** | Unit and integration tests pass for all changed code paths | Test runner output showing all relevant tests green with no skips |
+| **Type Safety** | No type errors introduced by the change | Type checker exits clean on the full project |
+| **Lint/Format** | Code meets project style and quality rules | Linter and formatter exit clean on changed files |
+
+### Conditional
+
+| Type | When it applies | What to prove | Acceptable proof |
+|------|----------------|---------------|------------------|
+| **UI** | Change affects user-visible interface | Feature renders correctly and interactions work as expected | Automated session recording or screenshots showing correct states; for cross-platform changes, evidence from each platform or explicit gap documentation |
+| **API** | Change affects HTTP/GraphQL/RPC endpoints | Endpoint returns correct status, headers, and body for success and error cases | Request/response capture showing schema and data match expectations |
+| **Database** | Change involves schema, migrations, or queries | Schema is correct after migration; data integrity is maintained | Query output showing expected schema and data state |
+| **Auth** | Change affects authentication or authorization | Correct access for allowed roles; rejection for disallowed roles | Request traces showing enforcement across at least two roles |
+| **Security** | Change involves input handling, secrets, or attack surfaces | Exploit is prevented; safe handling is enforced | Reproduction of attack pre-fix failing post-fix, or evidence of sanitization/rejection |
+| **Performance** | Change claims performance improvement or affects hot paths | Measurable improvement in latency, throughput, or resource usage | Before/after benchmarks with methodology documented |
+| **Infrastructure** | Change affects deployment, scaling, or cloud resources | Resources are created/updated correctly; system is stable | Infrastructure state output showing expected configuration; stability metrics during transition |
+| **Observability** | Change affects logging, metrics, or tracing | Events are emitted with correct structure and correlation | Log or metric output showing expected entries with correlation IDs |
+| **Background Jobs** | Change affects queues, workers, or scheduled tasks | Job enqueues, processes, and reaches terminal state correctly | Evidence of enqueue, processing, and final state; idempotency check when relevant |
+| **Configuration** | Change affects config files, feature flags, or environment variables | Configuration is loaded and applied correctly at runtime | Application output showing the configuration taking effect |
+| **Documentation** | Change affects documentation content or structure | Documentation is accurate and matches implementation | Content inspection confirming accuracy against actual behavior |
+| **Cache** | Change affects caching behavior or invalidation | Cache hits, misses, and invalidation work as expected | Evidence of cache behavior (hit/miss logs, TTL verification, key inspection) |
+| **Email/Notification** | Change affects outbound messages | Message is sent with correct content to correct recipient | Captured message content or delivery log showing expected output |
+| **PR** | Shipping code (always applies when opening a PR) | PR includes goal summary, verification level, proof artifacts, and reproduction steps | PR description containing all required sections |
+| **Deploy** | Shipping code to an environment | Deployment completes and application is healthy in the target environment | Deployment output and health check evidence from the target environment |
+
+---
+
+For the full verification lifecycle (classify, check tooling, plan, execute, loop), surfaces, escalation protocol, and proof artifact requirements, see the `verification-lifecycle` skill loaded by the `verification-specialist` agent.

package/plugins/src/rails/.claude-plugin/plugin.json

@@ -4,6 +4,12 @@
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": { "name": "Cody Swann" },
   "hooks": {
+    "SessionStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] }
+    ],
+    "SubagentStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

package/plugins/src/rails/hooks/inject-rules.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Reads all .md files from the plugin's rules/ directory and injects them
+# into the session context via additionalContext.
+# Used by SessionStart and SubagentStart hooks.
+set -euo pipefail
+
+RULES_DIR="${CLAUDE_PLUGIN_ROOT}/rules"
+
+# Bail silently if no rules directory
+[ -d "$RULES_DIR" ] || exit 0
+
+CONTEXT=""
+for file in "$RULES_DIR"/*.md; do
+  [ -f "$file" ] || continue
+  CONTEXT+="$(cat "$file")"$'\n\n'
+done
+
+# Bail if no rules found
+[ -n "$CONTEXT" ] || exit 0
+
+# Output as JSON — jq handles escaping
+jq -n --arg ctx "$CONTEXT" '{"additionalContext": $ctx}'

package/plugins/src/rails/rules/rails-conventions.md

@@ -0,0 +1,176 @@
+# Rails Coding Conventions
+
+This rule enforces Rails-specific coding standards for consistency, maintainability, and performance.
+
+## Fat Models, Skinny Controllers
+
+Controllers handle HTTP concerns only. Business logic belongs in models or service objects.
+
+```ruby
+# Correct — controller delegates to model
+class OrdersController < ApplicationController
+  def create
+    @order = Order.place(order_params, current_user)
+    redirect_to @order
+  end
+end
+
+# Wrong — business logic in controller
+class OrdersController < ApplicationController
+  def create
+    @order = Order.new(order_params)
+    @order.user = current_user
+    @order.total = @order.line_items.sum(&:price)
+    @order.apply_discount(current_user.discount_rate)
+    @order.save!
+    OrderMailer.confirmation(@order).deliver_later
+    redirect_to @order
+  end
+end
+```
+
+## Service Objects
+
+Extract complex business logic into service objects when a model method would be too large or spans multiple models.
+
+```ruby
+# app/services/order_placement_service.rb
+class OrderPlacementService
+  def initialize(user:, params:)
+    @user = user
+    @params = params
+  end
+
+  def call
+    order = Order.new(@params)
+    order.user = @user
+    order.calculate_total
+    order.save!
+    OrderMailer.confirmation(order).deliver_later
+    order
+  end
+end
+```
+
+## Concerns
+
+Use concerns to share behavior across models or controllers. Keep concerns focused on a single responsibility.
+
+```ruby
+# app/models/concerns/searchable.rb
+module Searchable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :search, ->(query) { where("name ILIKE ?", "%#{query}%") }
+  end
+end
+```
+
+## ActiveRecord Patterns
+
+### Scopes over class methods for chainable queries
+
+```ruby
+# Correct — scope
+scope :active, -> { where(active: true) }
+scope :recent, -> { order(created_at: :desc) }
+
+# Wrong — class method for simple query
+def self.active
+  where(active: true)
+end
+```
+
+### Validations
+
+```ruby
+# Use built-in validators
+validates :email, presence: true, uniqueness: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :age, numericality: { greater_than: 0 }
+```
+
+### Callbacks — use sparingly
+
+Prefer explicit service objects over callbacks for complex side effects. Callbacks are acceptable for simple data normalization.
+
+```ruby
+# Acceptable — simple normalization
+before_validation :normalize_email
+
+private
+
+def normalize_email
+  self.email = email&.downcase&.strip
+end
+```
+
+## N+1 Query Prevention
+
+Always use `includes`, `preload`, or `eager_load` to prevent N+1 queries. The Bullet gem is included to detect these in development.
+
+```ruby
+# Correct — eager loading
+@posts = Post.includes(:author, :comments).where(published: true)
+
+# Wrong — N+1 query
+@posts = Post.where(published: true)
+@posts.each { |post| post.author.name } # N+1!
+```
+
+## Strong Parameters
+
+Always use strong parameters in controllers. Never use `permit!`.
+
+```ruby
+# Correct
+def order_params
+  params.require(:order).permit(:product_id, :quantity, :notes)
+end
+
+# Wrong — permits everything
+def order_params
+  params.require(:order).permit!
+end
+```
+
+## Database Migrations
+
+- Use `strong_migrations` gem constraints (included via Gemfile.lisa)
+- Never modify `db/schema.rb` directly
+- Always add indexes for foreign keys and commonly queried columns
+- Use `change` method when the migration is reversible; use `up`/`down` when it is not
+
+```ruby
+class AddIndexToOrdersUserId < ActiveRecord::Migration[7.2]
+  def change
+    add_index :orders, :user_id
+  end
+end
+```
+
+## Testing with RSpec
+
+- Use `let` and `let!` for test setup
+- Use `described_class` instead of repeating the class name
+- Use `factory_bot` for test data, not fixtures
+- Use `shoulda-matchers` for model validation tests
+- Keep tests focused — one assertion concept per example
+
+```ruby
+RSpec.describe Order, type: :model do
+  describe "validations" do
+    it { is_expected.to validate_presence_of(:user) }
+    it { is_expected.to validate_numericality_of(:total).is_greater_than(0) }
+  end
+
+  describe ".recent" do
+    it "returns orders in descending creation order" do
+      old_order = create(:order, created_at: 1.day.ago)
+      new_order = create(:order, created_at: 1.hour.ago)
+
+      expect(described_class.recent).to eq([new_order, old_order])
+    end
+  end
+end
+```

package/rails/deletions.json

@@ -8,6 +8,7 @@
     ".claude/skills/plan-fix-linter-error",
     ".claude/skills/plan-lower-code-complexity",
     ".claude/skills/plan-reduce-max-lines",
-    ".claude/skills/plan-reduce-max-lines-per-function"
+    ".claude/skills/plan-reduce-max-lines-per-function",
+    ".claude/rules/rails-conventions.md"
   ]
 }