@codyswann/lisa 1.85.10 → 1.86.0

package/package.json

@@ -78,7 +78,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "1.85.10",
+  "version": "1.86.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.85.10",
+  "version": "1.86.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/commands/plan/execute.md

@@ -3,4 +3,4 @@ description: "Deploys an agent team to research, implement, review and deploy a
 argument-hint: "<ticket-url | @file-path | description>"
 ---
 
-Read `.claude/rules/intent-routing.md` and determine the appropriate flow for $ARGUMENTS. Execute the full flow including implementation, review, and verify flows.
+Pass through to `/build` with $ARGUMENTS. The Build command reads `.claude/rules/intent-routing.md` and runs the full Implement → Review → Verify chain, which is what this command historically did.

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

@@ -72,6 +72,13 @@ JIRA Discipline:
 Agent Behavior:
 - Never handle tasks yourself when working in a team of agents. Always delegate to a specialized agent.
 
+Pace:
+- Never rush. There is no pressure to finish quickly. Speed is not a measure of quality, and a fast wrong answer is worse than a slow correct one.
+- Take the time to read the relevant code in full, verify assumptions empirically, ask clarifying questions when something is ambiguous, and check your work before declaring it done.
+- Do not skip steps to save time — quality gates, verification, reading existing code, asking the user — these exist because shortcuts cost more than they save.
+- If a task feels like it's taking "too long," that is almost always a sign that the task is harder than it first appeared, not a sign that you should cut corners. Surface the difficulty to the user instead of compressing the work.
+- Optimize for being correct, thorough, and reversible. Time spent doing the work right is never wasted; time spent recovering from a rushed answer often is.
+
 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).

package/plugins/lisa/rules/intent-routing.md

@@ -253,3 +253,40 @@ The full lifecycle for a large initiative: Research -> Plan -> Implement (per it
 ## Sub-flow Usage
 
 Flows reference sub-flows by name. When a flow says "Investigate sub-flow", execute the full Investigate sub-flow sequence. When it says "Review sub-flow", execute the full Review sequence. Sub-flows can be invoked by any main flow.
+
+## Orchestration
+
+How a flow dispatches its agents depends on the flow's shape. Pick the orchestration mode that matches the work — do not default to the heaviest one.
+
+### Agent Teams (default for multi-step flows)
+
+Use an **agent team** (TeamCreate + TaskCreate per step) for:
+
+- **Implement** (Build, Fix, Improve) — long sequences with parallel review and a real risk of compaction
+- **Plan** — multiple specialists feeding a shared decomposition
+- **Research** — multiple specialists feeding a shared PRD
+- Any flow that invokes the **Review sub-flow** (the four review specialists run in parallel and gate a single follow-up task)
+
+Why: these flows have enough steps that context compaction is likely; the Review sub-flow is parallel-by-design and `blockedBy` expresses that cleanly; durable task state lets the team lead recover assignments after compaction.
+
+When using a team:
+
+1. Create one team per top-level flow invocation. Do not nest teams for sub-flows — sub-flow steps become tasks within the existing team.
+2. Express parallelism with `blockedBy`. The Review sub-flow's four specialists are independent; the "implement valid suggestions" task is `blockedBy` all four.
+3. On every TaskUpdate that sets `owner`, also store it in `metadata.owner` so the assignment survives context compaction.
+4. Re-read TaskList after any compaction event before assigning new work.
+
+### One-shot Sub-agents (for short or single-agent flows)
+
+Use direct `Agent` tool invocations (no team) for:
+
+- **Verify** when run standalone — it's a linear gate sequence with no parallelism
+- **Monitor** standalone — single specialist (`ops-specialist`) producing a report
+- **Investigate Only** spikes — single investigation, findings out
+- Any flow chained as a sub-flow inside a larger team — its agents become tasks in the parent team, not a new team
+
+Why: TeamCreate plus per-step TaskCreate is real overhead. For a one-or-two-agent flow with no parallelism, the bookkeeping cost outweighs the recovery and orchestration benefits.
+
+### When in doubt
+
+If the flow has more than three agent steps, or any parallel step, or is likely to span a compaction boundary, use a team. Otherwise, sub-agents are fine.

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "1.85.10",
+  "version": "1.86.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.85.10",
+  "version": "1.86.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,9 +1,21 @@
 {
   "name": "lisa-nestjs",
-  "version": "1.85.10",
-  "description": "NestJS-specific skills (GraphQL, TypeORM)",
+  "version": "1.86.0",
+  "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"
   },
-  "hooks": {}
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-migration-edits.sh"
+          }
+        ]
+      }
+    ]
+  }
 }

package/plugins/lisa-nestjs/hooks/block-migration-edits.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+
+# PreToolUse hook: block Write/Edit on TypeORM migration files.
+# NestJS projects must use `bun run migration:generate` to create migrations
+# from entity diffs. Hand-written migrations drift from entity metadata and
+# break the schema/migration contract.
+# Reference: https://docs.claude.com/en/docs/claude-code/hooks
+# Exit code 2 blocks the tool call and surfaces stderr to Claude.
+
+JSON_INPUT=$(cat)
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "⚠ block-migration-edits: jq not available, allowing edit" >&2
+  exit 0
+fi
+
+FILE_PATH=$(echo "$JSON_INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  */migrations/*.ts|*/migrations/*.js)
+    cat >&2 <<EOF
+❌ Blocked: Direct edits to TypeORM migration files are not allowed.
+
+File: $FILE_PATH
+
+Entity files (src/database/entities/*.ts) are the single source of
+truth for the database schema in this project. Migrations are a derived
+artifact — generate them from entity diffs:
+
+  1. Edit the entity to express the desired schema.
+  2. Run: bun run migration:generate --name=<DescriptiveName>
+  3. Review the generated migration; commit entity + migration together.
+
+If a schema change cannot be expressed via the entity model, the entity
+model is wrong — fix the entity, do not hand-write the migration.
+
+OUT-OF-BAND MIGRATIONS (seed data, backfills, data transformations,
+one-off cleanup): these genuinely cannot come from entity diffs. They
+are legitimate but they bypass the entity-as-source-of-truth contract.
+
+If you believe this edit is an out-of-band migration:
+  1. STOP and tell the user what change is needed and why it cannot
+     be expressed via the entity model.
+  2. Get explicit approval before proceeding.
+  3. Document the rationale in the migration's class comment.
+
+Do NOT silently hand-write a migration. See the nestjs-rules skill
+for the full rationale.
+EOF
+    exit 2
+    ;;
+esac
+
+exit 0

package/plugins/lisa-nestjs/skills/nestjs-rules/SKILL.md

@@ -43,15 +43,44 @@ The `--no-spec` flag is used because this project follows TDD (Test-Driven Devel
 
 ## Database Migrations
 
+### Entity Files Are the Source of Truth
+
+In this project, **entity files (`src/database/entities/*.ts`) are the single source of truth for the database schema**. Migrations are a derived artifact — TypeORM diffs the entity metadata against the current database and emits the migration for you. The workflow is always:
+
+1. Edit the entity file to express the desired schema.
+2. Run `bun run migration:generate --name=<DescriptiveName>` to produce the migration from the diff.
+3. Review the generated migration, then commit both the entity change and the migration together.
+
+If a schema change cannot be expressed via the entity model, the entity model is wrong — fix the entity, do not hand-write the migration.
+
 ### Never Create Migration Files Manually
 
-Never create or modify a TypeORM migration file directly. Instead, use `migration:generate` from `package.json`:
+Never create or modify a TypeORM migration file directly. Use `migration:generate` from `package.json`:
 
 ```bash
-bun run migration:generate
+bun run migration:generate --name=<DescriptiveName>
 ```
 
-**Exception**: Direct modification is allowed only for changes that don't break syncing with entity files (e.g., adding indexes, comments, or non-structural changes).
+### Out-of-Band Migrations (Seed Data, Backfills)
+
+Some changes genuinely cannot be derived from entity diffs:
+
+- **Seed data** (reference rows, lookup tables, initial admin user)
+- **Data backfills** (populating a new column from existing rows)
+- **Data transformations** (splitting a column, normalizing values)
+- **One-off cleanup** (deleting orphaned rows before a constraint is added)
+
+These are legitimate cases for a hand-written migration, but they are **out-of-band** — they bypass the entity-as-source-of-truth contract. When you encounter one:
+
+1. **Stop and tell the user.** Explain what change is needed and why it cannot be expressed via the entity model.
+2. **Get explicit approval** before writing the migration by hand.
+3. Document the rationale in the migration's class comment so future readers understand why this one was not generated.
+
+Do not silently hand-write a migration for a backfill or seed-data change. The user must know that the entity-as-source-of-truth contract is being intentionally bypassed for this case.
+
+### Enforcement
+
+The `lisa-nestjs` plugin ships a `PreToolUse` hook (`block-migration-edits.sh`) that blocks `Write`/`Edit` on any path matching `**/migrations/*.ts` or `**/migrations/*.js`. The block surfaces this rule's guidance to remind you to either (a) edit the entity instead, or (b) ask the user before proceeding with an out-of-band migration.
 
 ### Why Auto-Generation
 

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "1.85.10",
+  "version": "1.86.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/src/base/commands/plan/execute.md

@@ -3,4 +3,4 @@ description: "Deploys an agent team to research, implement, review and deploy a
 argument-hint: "<ticket-url | @file-path | description>"
 ---
 
-Read `.claude/rules/intent-routing.md` and determine the appropriate flow for $ARGUMENTS. Execute the full flow including implementation, review, and verify flows.
+Pass through to `/build` with $ARGUMENTS. The Build command reads `.claude/rules/intent-routing.md` and runs the full Implement → Review → Verify chain, which is what this command historically did.

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

@@ -72,6 +72,13 @@ JIRA Discipline:
 Agent Behavior:
 - Never handle tasks yourself when working in a team of agents. Always delegate to a specialized agent.
 
+Pace:
+- Never rush. There is no pressure to finish quickly. Speed is not a measure of quality, and a fast wrong answer is worse than a slow correct one.
+- Take the time to read the relevant code in full, verify assumptions empirically, ask clarifying questions when something is ambiguous, and check your work before declaring it done.
+- Do not skip steps to save time — quality gates, verification, reading existing code, asking the user — these exist because shortcuts cost more than they save.
+- If a task feels like it's taking "too long," that is almost always a sign that the task is harder than it first appeared, not a sign that you should cut corners. Surface the difficulty to the user instead of compressing the work.
+- Optimize for being correct, thorough, and reversible. Time spent doing the work right is never wasted; time spent recovering from a rushed answer often is.
+
 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).

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

@@ -253,3 +253,40 @@ The full lifecycle for a large initiative: Research -> Plan -> Implement (per it
 ## Sub-flow Usage
 
 Flows reference sub-flows by name. When a flow says "Investigate sub-flow", execute the full Investigate sub-flow sequence. When it says "Review sub-flow", execute the full Review sequence. Sub-flows can be invoked by any main flow.
+
+## Orchestration
+
+How a flow dispatches its agents depends on the flow's shape. Pick the orchestration mode that matches the work — do not default to the heaviest one.
+
+### Agent Teams (default for multi-step flows)
+
+Use an **agent team** (TeamCreate + TaskCreate per step) for:
+
+- **Implement** (Build, Fix, Improve) — long sequences with parallel review and a real risk of compaction
+- **Plan** — multiple specialists feeding a shared decomposition
+- **Research** — multiple specialists feeding a shared PRD
+- Any flow that invokes the **Review sub-flow** (the four review specialists run in parallel and gate a single follow-up task)
+
+Why: these flows have enough steps that context compaction is likely; the Review sub-flow is parallel-by-design and `blockedBy` expresses that cleanly; durable task state lets the team lead recover assignments after compaction.
+
+When using a team:
+
+1. Create one team per top-level flow invocation. Do not nest teams for sub-flows — sub-flow steps become tasks within the existing team.
+2. Express parallelism with `blockedBy`. The Review sub-flow's four specialists are independent; the "implement valid suggestions" task is `blockedBy` all four.
+3. On every TaskUpdate that sets `owner`, also store it in `metadata.owner` so the assignment survives context compaction.
+4. Re-read TaskList after any compaction event before assigning new work.
+
+### One-shot Sub-agents (for short or single-agent flows)
+
+Use direct `Agent` tool invocations (no team) for:
+
+- **Verify** when run standalone — it's a linear gate sequence with no parallelism
+- **Monitor** standalone — single specialist (`ops-specialist`) producing a report
+- **Investigate Only** spikes — single investigation, findings out
+- Any flow chained as a sub-flow inside a larger team — its agents become tasks in the parent team, not a new team
+
+Why: TeamCreate plus per-step TaskCreate is real overhead. For a one-or-two-agent flow with no parallelism, the bookkeeping cost outweighs the recovery and orchestration benefits.
+
+### When in doubt
+
+If the flow has more than three agent steps, or any parallel step, or is likely to span a compaction boundary, use a team. Otherwise, sub-agents are fine.

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

@@ -1,7 +1,19 @@
 {
   "name": "lisa-nestjs",
   "version": "1.0.0",
-  "description": "NestJS-specific skills (GraphQL, TypeORM)",
+  "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": { "name": "Cody Swann" },
-  "hooks": {}
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-migration-edits.sh"
+          }
+        ]
+      }
+    ]
+  }
 }

package/plugins/src/nestjs/hooks/block-migration-edits.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+
+# PreToolUse hook: block Write/Edit on TypeORM migration files.
+# NestJS projects must use `bun run migration:generate` to create migrations
+# from entity diffs. Hand-written migrations drift from entity metadata and
+# break the schema/migration contract.
+# Reference: https://docs.claude.com/en/docs/claude-code/hooks
+# Exit code 2 blocks the tool call and surfaces stderr to Claude.
+
+JSON_INPUT=$(cat)
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "⚠ block-migration-edits: jq not available, allowing edit" >&2
+  exit 0
+fi
+
+FILE_PATH=$(echo "$JSON_INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  */migrations/*.ts|*/migrations/*.js)
+    cat >&2 <<EOF
+❌ Blocked: Direct edits to TypeORM migration files are not allowed.
+
+File: $FILE_PATH
+
+Entity files (src/database/entities/*.ts) are the single source of
+truth for the database schema in this project. Migrations are a derived
+artifact — generate them from entity diffs:
+
+  1. Edit the entity to express the desired schema.
+  2. Run: bun run migration:generate --name=<DescriptiveName>
+  3. Review the generated migration; commit entity + migration together.
+
+If a schema change cannot be expressed via the entity model, the entity
+model is wrong — fix the entity, do not hand-write the migration.
+
+OUT-OF-BAND MIGRATIONS (seed data, backfills, data transformations,
+one-off cleanup): these genuinely cannot come from entity diffs. They
+are legitimate but they bypass the entity-as-source-of-truth contract.
+
+If you believe this edit is an out-of-band migration:
+  1. STOP and tell the user what change is needed and why it cannot
+     be expressed via the entity model.
+  2. Get explicit approval before proceeding.
+  3. Document the rationale in the migration's class comment.
+
+Do NOT silently hand-write a migration. See the nestjs-rules skill
+for the full rationale.
+EOF
+    exit 2
+    ;;
+esac
+
+exit 0

package/plugins/src/nestjs/skills/nestjs-rules/SKILL.md

@@ -43,15 +43,44 @@ The `--no-spec` flag is used because this project follows TDD (Test-Driven Devel
 
 ## Database Migrations
 
+### Entity Files Are the Source of Truth
+
+In this project, **entity files (`src/database/entities/*.ts`) are the single source of truth for the database schema**. Migrations are a derived artifact — TypeORM diffs the entity metadata against the current database and emits the migration for you. The workflow is always:
+
+1. Edit the entity file to express the desired schema.
+2. Run `bun run migration:generate --name=<DescriptiveName>` to produce the migration from the diff.
+3. Review the generated migration, then commit both the entity change and the migration together.
+
+If a schema change cannot be expressed via the entity model, the entity model is wrong — fix the entity, do not hand-write the migration.
+
 ### Never Create Migration Files Manually
 
-Never create or modify a TypeORM migration file directly. Instead, use `migration:generate` from `package.json`:
+Never create or modify a TypeORM migration file directly. Use `migration:generate` from `package.json`:
 
 ```bash
-bun run migration:generate
+bun run migration:generate --name=<DescriptiveName>
 ```
 
-**Exception**: Direct modification is allowed only for changes that don't break syncing with entity files (e.g., adding indexes, comments, or non-structural changes).
+### Out-of-Band Migrations (Seed Data, Backfills)
+
+Some changes genuinely cannot be derived from entity diffs:
+
+- **Seed data** (reference rows, lookup tables, initial admin user)
+- **Data backfills** (populating a new column from existing rows)
+- **Data transformations** (splitting a column, normalizing values)
+- **One-off cleanup** (deleting orphaned rows before a constraint is added)
+
+These are legitimate cases for a hand-written migration, but they are **out-of-band** — they bypass the entity-as-source-of-truth contract. When you encounter one:
+
+1. **Stop and tell the user.** Explain what change is needed and why it cannot be expressed via the entity model.
+2. **Get explicit approval** before writing the migration by hand.
+3. Document the rationale in the migration's class comment so future readers understand why this one was not generated.
+
+Do not silently hand-write a migration for a backfill or seed-data change. The user must know that the entity-as-source-of-truth contract is being intentionally bypassed for this case.
+
+### Enforcement
+
+The `lisa-nestjs` plugin ships a `PreToolUse` hook (`block-migration-edits.sh`) that blocks `Write`/`Edit` on any path matching `**/migrations/*.ts` or `**/migrations/*.js`. The block surfaces this rule's guidance to remind you to either (a) edit the entity instead, or (b) ask the user before proceeding with an out-of-band migration.
 
 ### Why Auto-Generation