@codyswann/lisa 1.67.3 → 1.69.0

package/plugins/src/base/agents/performance-specialist.md

@@ -2,23 +2,14 @@
 name: performance-specialist
 description: Performance specialist agent. Identifies N+1 queries, inefficient algorithms, memory leaks, missing indexes, unnecessary re-renders, bundle size issues, and other software performance problems. Recommends optimizations with evidence.
 tools: Read, Grep, Glob, Bash
+skills:
+  - performance-review
 ---
 
 # Performance Specialist Agent
 
 You are a performance specialist who identifies bottlenecks, inefficiencies, and scalability risks in code changes.
 
-## Analysis Process
-
-1. **Read affected files** -- understand data access patterns, algorithmic complexity, and resource usage
-2. **Identify N+1 queries** -- look for ORM calls inside loops, missing eager loading, unbatched database access
-3. **Check algorithmic complexity** -- nested loops over collections, repeated linear scans, unnecessary sorting
-4. **Evaluate memory usage** -- large object allocations, unbounded caches, retained references, memory leaks
-5. **Review database patterns** -- missing indexes, full table scans, unoptimized joins, excessive round trips
-6. **Check caching** -- missing cache layers, cache invalidation issues, redundant computations
-7. **Assess bundle/payload size** -- unnecessary imports, large dependencies, uncompressed responses
-8. **Review rendering performance** -- unnecessary re-renders, missing memoization, layout thrashing (frontend)
-
 ## Output Format
 
 Structure your findings as:

package/plugins/src/base/agents/product-specialist.md

@@ -2,22 +2,14 @@
 name: product-specialist
 description: Product/UX specialist agent. Defines user flows in Gherkin, writes acceptance criteria from user perspective, identifies UX concerns and error states, and empirically verifies behavior matches requirements.
 tools: Read, Grep, Glob, Bash
+skills:
+  - acceptance-criteria
 ---
 
 # Product Specialist Agent
 
 You are a product/UX specialist who evaluates changes from a non-technical user's perspective.
 
-## Analysis Process
-
-1. **Understand the user goal** -- what problem does this solve for the end user?
-2. **Define user flows** -- step-by-step paths through the feature, including happy path and error paths
-3. **Write acceptance criteria** -- testable conditions from the user's perspective
-4. **Identify UX concerns** -- confusing interactions, missing feedback, accessibility issues
-5. **Map error states** -- what happens when things go wrong, and what the user sees
-6. **Run the feature** -- execute scripts, call APIs, or trigger the described behavior to verify empirically
-7. **Compare output to requirements** -- does actual behavior match expectations?
-
 ## Output Format
 
 Structure your findings as:

package/plugins/src/base/agents/quality-specialist.md

@@ -2,6 +2,8 @@
 name: quality-specialist
 description: Code quality specialist agent. Reviews correctness, coding philosophy compliance (immutability, function structure), test coverage, and documentation. Explains findings in beginner-friendly plain English, ranked by severity.
 tools: Read, Grep, Glob, Bash
+skills:
+  - quality-review
 ---
 
 # Quality Specialist Agent

package/plugins/src/base/agents/security-specialist.md

@@ -2,21 +2,15 @@
 name: security-specialist
 description: Security specialist agent. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling, and recommends mitigations.
 tools: Read, Grep, Glob, Bash
+skills:
+  - security-review
+  - security-zap-scan
 ---
 
 # Security Specialist Agent
 
 You are a security specialist who identifies vulnerabilities, evaluates threats, and recommends mitigations for code changes.
 
-## Analysis Process
-
-1. **Read affected files** -- understand current security posture of the code being changed
-2. **STRIDE analysis** -- evaluate Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege risks
-3. **Check input validation** -- are user inputs sanitized at system boundaries?
-4. **Check secrets handling** -- are credentials, tokens, or API keys exposed in code, logs, or error messages?
-5. **Check auth/authz** -- are access controls properly enforced for new endpoints or features?
-6. **Review dependencies** -- do new dependencies introduce known vulnerabilities?
-
 ## Output Format
 
 Structure your findings as:

package/plugins/src/base/agents/test-specialist.md

@@ -2,28 +2,14 @@
 name: test-specialist
 description: Test specialist agent. Designs test strategy (matrix, edge cases, coverage targets, TDD sequence), writes comprehensive unit and integration tests, and reviews test quality. Tests behavior, not implementation details.
 tools: Read, Write, Edit, Bash, Grep, Glob
+skills:
+  - test-strategy
 ---
 
 # Test Specialist Agent
 
 You are a test specialist who designs test strategies, writes tests, and reviews test quality.
 
-## Analysis Process
-
-1. **Read existing tests** -- understand the project's test conventions (describe/it structure, naming, helpers)
-2. **Identify test types needed** -- unit, integration, E2E based on the scope of changes
-3. **Map edge cases** -- boundary values, empty inputs, error states, concurrency scenarios
-4. **Check coverage gaps** -- run existing tests to understand current coverage of affected files
-5. **Design verification commands** -- proof commands that empirically demonstrate the code works
-
-## Test Writing Process
-
-1. **Analyze the source file** to understand its functionality
-2. **Identify untested code paths**, edge cases, and error conditions
-3. **Write comprehensive, meaningful tests** (not just coverage padding)
-4. **Follow the project's existing test patterns** and conventions
-5. **Ensure tests are readable and maintainable**
-
 ## Output Format
 
 Structure your findings as:

package/plugins/src/base/agents/verification-specialist.md

@@ -1,14 +1,17 @@
 ---
 name: verification-specialist
-description: Verification specialist agent. Plans and executes empirical proof that work is done. Discovers existing scripts and tools (deploy, start, run), creates new verification scripts when needed, and runs them to produce irrefutable evidence. Experts in Playwright browser automation, curl E2E flows, and CLI verification.
+description: Verification specialist agent. Discovers project tooling and executes verification for all required types. Plans and executes empirical proof that work is done by running the actual system and observing results.
 tools: Read, Write, Edit, Bash, Grep, Glob
+skills:
+  - verification-lifecycle
+  - jira-journey
 ---
 
 # Verification Specialist Agent
 
 You are a verification specialist. Your job is to **prove empirically** that work is done -- not by reading code, but by running the actual system and observing the results.
 
-Read `.claude/rules/verification.md` at the start of every investigation for the full verification framework, types, and examples.
+Read `.claude/rules/verification.md` at the start of every investigation for the full verification framework, types, and lifecycle.
 
 ## Core Philosophy
 
@@ -16,31 +19,36 @@ Read `.claude/rules/verification.md` at the start of every investigation for the
 
 ## Verification Process
 
-### 1. Discover Existing Tools
+Follow the verification lifecycle: **classify, check tooling, fail fast, plan, execute, loop.**
+
+### 1. Classify
+
+Read `.claude/rules/verification.md` to determine which verification types apply to the current change. Start with the three always-required types (Test, Type Safety, Lint/Format), then check each conditional type against the change scope.
+
+### 2. Discover Available Tools
 
 Before creating anything new, find what the project already has.
 
-**Package scripts:**
-- Read `package.json` scripts for: `start`, `dev`, `serve`, `deploy`, `test`, `e2e`, `preview`
-- Check for environment-specific variants: `start:dev`, `start:staging`, `start:local`
+**Project manifest:**
+- Read the manifest file for available scripts and their variants (build, test, lint, deploy, start, environment-specific variants)
 
-**Shell scripts:**
-- Search `scripts/` directory for deployment, setup, and run scripts
-- Search for docker-compose files, Makefiles, Procfiles
+**Script directories:**
+- Search for shell scripts, automation files, and task runners in `scripts/`, `bin/`, and project root
 
 **Test infrastructure:**
-- Check for Playwright config (`playwright.config.ts`), Cypress config, Jest config
-- Check for existing E2E test directories (`e2e/`, `tests/`, `__tests__/`)
-- Check for test fixtures, seed data, or factory files
+- Check for test framework configurations, E2E test directories, test fixtures, seed data, and factory files
 
 **Cloud/infrastructure tooling:**
-- Search for AWS CLI wrappers, CDK deploy scripts, serverless configs
-- Check `.env`, `.env.example`, `.env.local` for service URLs and connection strings
+- Search for cloud CLI wrappers, deployment scripts, infrastructure-as-code configs
+- Check environment files for service URLs and connection strings
 - Look for health check endpoints or status pages already defined
 
-### 2. Plan the Verification
+**MCP tools:**
+- Check available MCP server tools for browser automation, observability, issue tracking, and other capabilities
 
-For each piece of work to verify, determine:
+### 3. Plan the Verification
+
+For each required verification type, determine:
 
 | Question | Answer needed |
 |----------|---------------|
@@ -49,70 +57,9 @@ For each piece of work to verify, determine:
 | What does success look like? | Status code, response body, UI state, database record |
 | What does failure look like? | Error message, wrong status, missing data |
 | What prerequisites are needed? | Running server, seeded database, auth token, test user |
+| What tool/command will be used? | Discovered tool from step 2 |
 
-### 3. Create Verification Scripts When Needed
-
-When existing tools are insufficient, write focused verification scripts.
-
-#### API Verification Script
-```bash
-#!/usr/bin/env bash
-# verify-<feature-name>.sh -- E2E verification for <feature>
-set -euo pipefail
-
-BASE_URL="${BASE_URL:-http://localhost:3000}"
-
-echo "=== Verifying <feature> ==="
-
-# Step 1: Setup (create test data if needed)
-RESPONSE=$(curl -sf -X POST "$BASE_URL/api/resource" \
-  -H "Content-Type: application/json" \
-  -d '{"key":"value"}')
-RESOURCE_ID=$(echo "$RESPONSE" | jq -r '.id')
-echo "Created resource: $RESOURCE_ID"
-
-# Step 2: Exercise the feature
-RESULT=$(curl -sf "$BASE_URL/api/resource/$RESOURCE_ID/action")
-echo "Action result: $RESULT"
-
-# Step 3: Assert expected outcome
-ACTUAL=$(echo "$RESULT" | jq -r '.status')
-EXPECTED="completed"
-if [ "$ACTUAL" = "$EXPECTED" ]; then
-  echo "PASS: status is '$ACTUAL'"
-else
-  echo "FAIL: expected '$EXPECTED', got '$ACTUAL'"
-  exit 1
-fi
-
-# Step 4: Cleanup (optional)
-curl -sf -X DELETE "$BASE_URL/api/resource/$RESOURCE_ID" > /dev/null
-echo "=== Verification complete ==="
-```
-
-#### Browser Verification (Playwright)
-```javascript
-// Use Playwright MCP browser tools or npx playwright test
-async (page) => {
-  // Navigate to the feature
-  await page.goto('http://localhost:3000/feature');
-
-  // Perform the user action
-  await page.getByRole('button', { name: 'Submit' }).click();
-
-  // Wait for and assert the expected outcome
-  await page.waitForSelector('[data-testid="success-message"]');
-  const message = await page.textContent('[data-testid="success-message"]');
-
-  return { message, url: page.url() };
-}
-```
-
-#### Database Verification
-```bash
-# Verify a migration or data change
-psql "$DATABASE_URL" -t -c "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'users' AND column_name = 'last_login_at';"
-```
+If any required verification type has no available tool and no reasonable alternative, escalate immediately.
 
 ### 4. Execute and Report
 
@@ -123,22 +70,24 @@ Run the verification and capture output. Always include:
 - Whether it matched the expected result
 - If it failed, what the actual output was
 
+If any verification fails, fix and re-verify. Do not declare done until all required types pass.
+
 ## Output Format
 
 ```
 ## Verification Report
 
 ### Prerequisites
-- [x] Server running at localhost:3000 (`npm run dev`)
-- [x] Database seeded (`npm run db:seed`)
-- [ ] External service X (unavailable -- verification blocked)
+- [x] Prerequisite 1 (how it was confirmed)
+- [x] Prerequisite 2 (how it was confirmed)
+- [ ] Prerequisite 3 (unavailable -- verification blocked)
 
 ### Verification Results
 
-| # | What was verified | Method | Command | Result |
-|---|-------------------|--------|---------|--------|
-| 1 | Feature description | curl/playwright/test | `command` | PASS/FAIL |
-| 2 | Edge case | curl/playwright/test | `command` | PASS/FAIL |
+| # | Type | What was verified | Command | Result |
+|---|------|-------------------|---------|--------|
+| 1 | Test | Description | `command` | PASS/FAIL |
+| 2 | Type Safety | Description | `command` | PASS/FAIL |
 
 ### Evidence
 
@@ -158,26 +107,13 @@ Run the verification and capture output. Always include:
 - `scripts/verify-<feature>.sh` -- purpose (delete after verification if temporary)
 
 ### Blocked Verifications
-- [verification] -- blocked because [reason], would need [what]
+- [type] -- blocked because [reason], would need [what]
 ```
 
-## Verification Method Selection
-
-Choose the right method for the work:
-
-| Work Type | Primary Method | Fallback |
-|-----------|---------------|----------|
-| API endpoint | curl script with assertions | Playwright API testing |
-| UI feature | Playwright browser automation | Manual screenshot comparison |
-| CLI tool | Run the command, check exit code and stdout | Bash script with assertions |
-| Database change | SQL query against the database | ORM/migration status check |
-| Config change | Read the config and grep for expected values | Start the app, observe behavior |
-| Performance fix | Benchmark before/after | Load test with k6 or ab |
-| Bug fix | Reproduce the bug, apply fix, run reproduction again | Regression test |
-
 ## Rules
 
-- Always read `.claude/rules/verfication.md` first for the project's verification standards
+- Always read `.claude/rules/verification.md` first for the project's verification standards and type taxonomy
+- Follow the verification lifecycle: classify, check tooling, fail fast, plan, execute, loop
 - Discover existing project scripts and tools before creating new ones
 - Every verification must produce observable output -- a status code, a response body, a UI state, a test result
 - Verification scripts must be runnable locally without CI/CD dependencies
@@ -185,5 +121,4 @@ Choose the right method for the work:
 - Clean up temporary verification scripts after use unless the user wants to keep them
 - If a verification is blocked (missing service, credentials, etc.), report exactly what is needed to unblock it -- do not skip it
 - Never report "verified by reading the code" -- that is not verification
-- When using Playwright, prefer the MCP browser tools for ad-hoc checks and `npx playwright test` for repeatable test files
 - Always capture and report the actual output, even on failure -- the output is the evidence

package/plugins/src/base/commands/build.md

@@ -0,0 +1,10 @@
+---
+description: "Build a feature. Defines acceptance criteria, researches codebase, implements via TDD, reviews, verifies, and ships."
+argument-hint: "<description-or-ticket-id-or-url>"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Build** flow.
+
+If the argument is a JIRA ticket ID or URL, hand off to the `jira-agent` which will read the ticket, extract context, and delegate back to the Build flow.
+
+$ARGUMENTS

package/plugins/src/base/commands/fix.md

@@ -0,0 +1,10 @@
+---
+description: "Fix a bug. Analyzes git history, reproduces, finds root cause, implements fix via TDD, verifies, and ships."
+argument-hint: "<description-or-ticket-id-or-url>"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Fix** flow.
+
+If the argument is a JIRA ticket ID or URL, hand off to the `jira-agent` which will read the ticket, extract context, and delegate back to the Fix flow.
+
+$ARGUMENTS

package/plugins/src/base/commands/improve.md

@@ -0,0 +1,16 @@
+---
+description: "Improve existing code. Identifies target, measures baseline, implements improvements via TDD, measures again, and ships."
+argument-hint: "<target-description>"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Improve** flow.
+
+For specific improvement types, you can also use:
+- `/lisa:plan:add-test-coverage` — increase test coverage
+- `/lisa:plan:fix-linter-error` — fix lint rule violations
+- `/lisa:plan:lower-code-complexity` — reduce cognitive complexity
+- `/lisa:plan:reduce-max-lines` — reduce file length
+- `/lisa:plan:reduce-max-lines-per-function` — reduce function length
+- `/lisa:plan:improve-tests` — improve test quality
+
+$ARGUMENTS

package/plugins/src/base/commands/investigate.md

@@ -0,0 +1,10 @@
+---
+description: "Investigate an issue. Analyzes git history, reproduces, traces execution, checks logs, and reports findings with evidence."
+argument-hint: "<description-or-ticket-id-or-url>"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Investigate** flow.
+
+If the argument is a JIRA ticket ID or URL, hand off to the `jira-agent` which will read the ticket and extract context.
+
+$ARGUMENTS

package/plugins/src/base/commands/jira/triage.md

@@ -0,0 +1,7 @@
+---
+description: "Analytical triage of a JIRA ticket -- ambiguity detection, edge case analysis, verification methodology"
+allowed-tools: ["Skill"]
+argument-hint: "<TICKET-ID>"
+---
+
+Use the /lisa:ticket-triage skill to run analytical triage on the JIRA ticket. $ARGUMENTS

package/plugins/src/base/commands/monitor.md

@@ -0,0 +1,10 @@
+---
+description: "Monitor application health. Checks health endpoints, logs, errors, and performance across environments."
+argument-hint: "[environment]"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Monitor** flow.
+
+Delegates to `ops-specialist` for health checks, log inspection, error monitoring, and performance analysis.
+
+$ARGUMENTS

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

@@ -3,4 +3,4 @@ description: "Creates an implementation plan from a ticket URL, file path, or te
 argument-hint: "<ticket-url | @file-path | description>"
 ---
 
-Use the /lisa:plan-execute skill on $ARGUMENTS
+Read `.claude/rules/intent-routing.md` and execute the **Plan** flow on $ARGUMENTS

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

@@ -3,5 +3,4 @@ description: "Deploys an agent team to research, implement, review and deploy a
 argument-hint: "<ticket-url | @file-path | description>"
 ---
 
-
-Use the /lisa:plan-execute skill on $ARGUMENTS
+Read `.claude/rules/intent-routing.md` and determine the appropriate flow for $ARGUMENTS. Execute the full flow including implementation, review, and ship sub-flows.

package/plugins/src/base/commands/plan/improve-tests.md

@@ -0,0 +1,7 @@
+---
+description: "Improve test quality by analyzing and strengthening weak, brittle, or poorly-written tests"
+allowed-tools: ["Skill"]
+argument-hint: "<target-description>"
+---
+
+Use the /lisa:plan-improve-tests skill to improve test quality. $ARGUMENTS

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

@@ -0,0 +1,10 @@
+---
+description: "Plan work. Defines acceptance criteria, researches codebase, maps dependencies, and breaks down into ordered tasks."
+argument-hint: "<description-or-ticket-id-or-url>"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Plan** flow.
+
+If the argument is a JIRA ticket ID or URL, hand off to the `jira-agent` which will read the ticket and extract context.
+
+$ARGUMENTS

package/plugins/src/base/commands/review.md

@@ -0,0 +1,10 @@
+---
+description: "Review code changes. Runs quality, security, performance, product, and test reviews in parallel, then consolidates findings."
+argument-hint: "[pr-link-or-branch]"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Review** flow.
+
+Runs `quality-specialist`, `security-specialist`, and `performance-specialist` in parallel, followed by `product-specialist` and `test-specialist`. Consolidates all findings ranked by severity.
+
+$ARGUMENTS

package/plugins/src/base/commands/ship.md

@@ -0,0 +1,10 @@
+---
+description: "Ship current changes. Commits, opens PR, handles review feedback loop, deploys, verifies, and monitors."
+argument-hint: "[commit-message-hint]"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Ship** flow.
+
+This includes: atomic commits, PR creation, review-fix loop (fix failed checks, resolve merge conflicts, handle bot review feedback until mergeable), merge, deploy, post-deploy verification, and monitoring.
+
+$ARGUMENTS

package/plugins/src/base/skills/acceptance-criteria/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: acceptance-criteria
+description: "Acceptance criteria definition. Gherkin user flows (Given/When/Then), error states, UX concerns, and empirical verification from the user perspective."
+---
+
+# Acceptance Criteria
+
+Evaluate changes from a non-technical user's perspective. Define acceptance criteria and verify behavior matches requirements.
+
+## Analysis Process
+
+1. **Understand the user goal** -- what problem does this solve for the end user?
+2. **Define user flows** -- step-by-step paths through the feature, including happy path and error paths
+3. **Write acceptance criteria** -- testable conditions from the user's perspective
+4. **Identify UX concerns** -- confusing interactions, missing feedback, accessibility issues
+5. **Map error states** -- what happens when things go wrong, and what the user sees
+6. **Run the feature** -- execute scripts, call APIs, or trigger the described behavior to verify empirically
+7. **Compare output to requirements** -- does actual behavior match expectations?
+
+## Output Format
+
+Structure findings as:
+
+```
+## Product Analysis
+
+### User Goal
+[1-2 sentence summary of what the user wants to accomplish]
+
+### User Flows (Gherkin)
+
+#### Happy Path
+Given [precondition]
+When [action]
+Then [expected outcome]
+
+#### Error Path: [description]
+Given [precondition]
+When [action that fails]
+Then [error handling behavior]
+
+### Acceptance Criteria
+- [ ] [criterion from user perspective]
+
+### UX Concerns
+- [concern] -- impact on user experience
+
+### Error Handling Requirements
+| Error Condition | User Sees | User Can Do |
+|----------------|-----------|-------------|
+
+### Verification Results
+For each acceptance criterion:
+- **Criterion:** [what was expected]
+- **Result:** Pass / Fail / Not Yet Testable
+- **Evidence:** [what was observed]
+
+### Out of Scope
+- [thing that might be expected but is not part of this work]
+```
+
+## Rules
+
+- Write acceptance criteria from the user's perspective, not the developer's
+- Every user flow must include at least one error path
+- Use Gherkin format (Given/When/Then) for user flows to enable direct translation into test cases
+- When verifying, always run the feature -- never review by only reading code
+- If you cannot run the feature (missing dependencies, services unavailable), report as a blocker -- do not guess
+- If the changes are purely internal (refactoring, config, tooling), report "No user-facing impact" and explain why
+- Do not propose UX changes beyond what was described -- flag scope concerns instead
+- Assume the reviewer has no technical background

package/plugins/src/base/skills/bug-triage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: bug-triage
+description: "8-step bug triage and implementation workflow. Ensures bugs are reproducible, root-caused, and fixable before implementation begins."
+---
+
+# Bug Triage
+
+Follow this 8-step triage process before implementing any bug fix. Do not skip triage.
+
+## Triage Steps
+
+1. Verify you have all information needed to reproduce the bug (authentication requirements, environment information, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
+2. Reproduce the bug. If you cannot reproduce it, stop and report what you tried and what you observed.
+3. Once reproduced, verify you are 100% positive on how to fix it. If not, determine what you need to do to be 100% positive (e.g. add logging, trace the code path, inspect state) and do that first.
+4. Verify you have access to the tools, environments, and permissions needed to deploy and verify this fix (e.g. CI/CD pipelines, deployment targets, logging/monitoring systems, API access, database access). If any are missing or inaccessible, stop and raise them before starting implementation.
+5. Define the tests you will write to confirm the fix and prevent a regression.
+6. Define the documentation you will create or update to explain this bug so another developer understands the "how" and "what" behind it.
+7. If you can verify your fix before deploying to the target environment (e.g. start the app, invoke the API, open a browser, run the process, check logs), do so before deploying.
+8. Define how you will verify the fix beyond a shadow of a doubt (e.g. deploy to the target environment, invoke the API, open a browser, run the process, check logs).
+
+## Implementation
+
+Use the output of the triage steps above as your guide. Do not skip triage.

package/plugins/src/base/skills/codebase-research/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: codebase-research
+description: "Codebase exploration and architecture analysis. Read files, trace data flow, identify modification points, map dependencies, find reusable code, evaluate design patterns."
+---
+
+# Codebase Research
+
+Systematically explore and analyze a codebase to understand its architecture, trace data flow, and identify how to make changes safely.
+
+## Analysis Process
+
+Follow these steps in order. Do not skip steps or propose changes to code you have not read.
+
+### 1. Read Referenced Files
+
+- Read every file that is directly relevant to the task
+- Understand the current architecture before proposing changes
+- Read imports and dependencies to understand the module graph
+- Check for configuration files that affect behavior (tsconfig, eslint, webpack, etc.)
+
+### 2. Trace Data Flow
+
+- Follow the path from entry point to output for the affected feature
+- Identify every transformation the data undergoes
+- Map inputs, intermediate states, and outputs
+- Note where data crosses boundaries (API calls, database queries, message queues)
+
+### 3. Identify Modification Points
+
+- Determine which files, functions, and interfaces need changes
+- Note the exact lines where modifications are required
+- Identify any type definitions, schemas, or contracts that must be updated
+- Check for generated code that may need regeneration
+
+### 4. Map Dependencies
+
+- Identify what depends on the code being changed (downstream consumers)
+- Identify what the code being changed depends on (upstream providers)
+- Determine the safe modification order to avoid breaking intermediate states
+- Flag any circular dependencies
+
+### 5. Check for Reusable Code
+
+- Search for existing utilities, helpers, or patterns that apply to the task
+- Check shared libraries and common modules
+- Look for similar implementations elsewhere in the codebase that can be referenced
+- Prefer reusing existing code over creating new abstractions
+
+### 6. Evaluate Design Patterns
+
+- Match the codebase's existing patterns -- do not introduce new architectural patterns without reason
+- Check naming conventions, file organization, and code style
+- Identify any patterns that are partially implemented and should be completed
+- Note anti-patterns that should not be propagated
+
+## Output Format
+
+```text
+## Architecture Analysis
+
+### Files to Create
+- `path/to/file.ts` -- purpose
+
+### Files to Modify
+- `path/to/file.ts:L42-L68` -- what changes and why
+
+### Dependency Graph
+- [file A] -> [file B] -> [file C] (modification order)
+
+### Design Decisions
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+
+### Reusable Code
+- `path/to/util.ts:functionName` -- how it applies
+
+### Risks
+- [risk description] -- [mitigation]
+```
+
+## Rules
+
+- Always read files before recommending changes to them
+- Follow existing patterns in the codebase -- do not introduce new architectural patterns unless explicitly required
+- Include file:line references for all recommendations
+- Flag breaking changes explicitly
+- Keep the modification surface area as small as possible