qualia-framework 2.1.6 → 2.2.0

package/framework/.claudeignore

@@ -0,0 +1,51 @@
+# ~/.claude/.claudeignore
+# Patterns to exclude from Claude Code context
+
+# Secrets and credentials
+.env
+.env.*
+*.pem
+*.key
+credentials.json
+*secret*
+.credentials.json
+askpass.sh
+
+# Analytics and internal state
+usage-data/
+sessions/
+statsig/
+
+# Node modules (anywhere)
+skills/*/node_modules/
+plugins/cache/*/node_modules/
+node_modules/
+
+# Large generated directories
+.next/
+dist/
+build/
+*.log
+
+# Claude internals (prevent recursion/bloat)
+plugins/cache/
+shell-snapshots/
+debug/
+file-history/
+projects/
+archive/
+todos/
+session-env/
+paste-cache/
+backups/
+cache/
+cowork-knowledge-pack.md
+
+# IDE and editor
+.vscode/
+.idea/
+
+# History and state files
+history.jsonl
+*.jsonl
+cleanup.log

package/framework/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md — Qualia Solutions
+
+## Identity
+**Fawzi Goussous** — Founder, Qualia Solutions. Nicosia, Cyprus.
+
+- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, VAPI, ElevenLabs, Telnyx, Retell AI, OpenRouter
+- Partner: Jay | Team: Moayad (full-time, Jordan), Ahasan (part-time, Cyprus)
+
+## Role: OWNER
+
+Full authority over all projects, deployments, architecture, and client decisions.
+- Deploy directly to production
+- Make architectural decisions unilaterally
+- Access all Supabase projects and service role keys
+- Modify the Qualia framework (CLAUDE.md, skills, hooks)
+
+## Rules
+- Read before Write/Edit — no exceptions
+- Feature branches only — never commit to main/master
+- MVP first. Build only what's asked. No over-engineering.
+- Root cause on failures — no band-aids
+- `npx tsc --noEmit` after multi-file TS changes
+- Glob/Grep directly — no Task(Explore) unless 5+ rounds needed
+- For non-trivial work (multi-file changes, architectural decisions, unfamiliar codebases), confirm understanding before coding — quick tasks are exempt
+- See `rules/security.md` for auth, RLS, Zod, secrets rules
+- See `rules/frontend.md` for design standards
+- See `rules/deployment.md` for deploy checklist
+- See `rules/speed.md` for tool usage and workflow shortcuts
+- See `rules/context7.md` for library documentation lookup
+
+## Collaboration
+Collaborator, not executor. Speak up about bugs, simpler approaches, bad architecture.
+Be honest. Default to action. Never speculate on unread code. Say when blocked.
+- Direct, action-oriented, no fluff. Code > theory.
+- Arabic or English — match whatever language is used
+
+## Workflow
+- **MANDATORY FIRST ACTION**: On every session start, invoke the `qualia-start` skill before doing anything else. This is non-negotiable — do not wait for user input, do not skip it, do not just acknowledge the hook message. Actually invoke the skill using the Skill tool.
+- Subagents (Opus) for research and complex reasoning.
+- `/compact` at 60%. `/clear` between tasks. `/learn` after mistakes.
+
+## Qualia Mode (always active)
+These behaviors apply to ALL interactions:
+- **Frontend guard:** Read .planning/DESIGN.md before any frontend file changes
+- **Deploy guard:** Check .planning/REVIEW.md freshness before any deploy command (run /qualia-review to generate)
+- **Intent verification:** Confirm before modifying 3+ files in one response
+- **Task-type detection:** Auto-load relevant skill patterns based on what's being done
+- **Quality defaults:** Security rules, tsc checks, RLS consideration — always enforced
+
+## Compaction — ALWAYS preserve:
+Project path/name/ref, branch, modified files, decisions, test results, in-progress work, errors, Qualia phase/milestone state, Qualia mode active/inactive state, session digest context.
+
+## Learned Patterns & Gotchas
+See ~/.claude/knowledge/learned-patterns.md for full rules and project gotchas.

package/framework/MCP_SETUP.md

@@ -0,0 +1,229 @@
+# MCP Server Setup & Security Guide
+
+Configuration and security best practices for Model Context Protocol servers.
+
+---
+
+## Current Configuration
+
+### Active MCP Servers (as of 2026-03-30)
+
+| Server | Package | Purpose | Status |
+|--------|---------|---------|--------|
+| `filesystem` | `@modelcontextprotocol/server-filesystem` | Local file operations | Active |
+| `context7` | `@context7/mcp-server` | Documentation search | Active |
+| `playwright` | `@playwright/mcp@latest` | Browser automation | Active |
+| `vapi` | `@vapi-ai/mcp-server` | Voice AI integration | Active |
+| `telnyx_api` | `telnyx-mcp-server` | Telecom integration | Active |
+| `elevenlabs` | `@anthropic/elevenlabs-mcp-server` | Audio synthesis | Active |
+
+**Removed servers:**
+- `supabase` MCP — replaced by the `/supabase` skill (CLI + Management API, zero context overhead)
+- `n8n-mcp` — removed, not actively used
+
+---
+
+## Server Details
+
+### Filesystem
+```json
+{
+  "filesystem": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/qualia"]
+  }
+}
+```
+**Security:** Restricts access to home directory only.
+
+---
+
+### Context7
+```json
+{
+  "context7": {
+    "command": "npx",
+    "args": ["-y", "@context7/mcp-server"]
+  }
+}
+```
+**Purpose:** Search and retrieve up-to-date library documentation.
+
+---
+
+### Playwright
+```json
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["-y", "@playwright/mcp@latest"]
+  }
+}
+```
+**Purpose:** Browser automation and web testing.
+
+---
+
+### ~~Supabase~~ (REMOVED)
+Replaced by the `/supabase` skill which uses CLI + Management API with zero context overhead.
+
+Previously:
+    "command": "npx",
+    "args": ["-y", "@anthropic-ai/mcp-supabase"],
+    "env": {
+      "SUPABASE_URL": "${SUPABASE_URL}",
+      "SUPABASE_KEY": "${SUPABASE_KEY}"
+    }
+  }
+}
+```
+**Security:** Store credentials in `.env.claude` only.
+
+---
+
+## Security Best Practices
+
+### 1. Credential Storage
+
+**DO:**
+```bash
+# Store in .env.claude
+SUPABASE_URL="https://xxx.supabase.co"
+SUPABASE_KEY="your-key-here"
+```
+
+**DON'T:**
+```json
+// Never put credentials directly in settings.json
+"env": {
+  "SUPABASE_KEY": "eyJhbGciOiJIUzI1NiIs..."  // BAD!
+}
+```
+
+### 2. File Permissions
+```bash
+chmod 600 ~/.claude/.env.claude
+chmod 600 ~/.claude/settings.json
+chmod 600 ~/.claude/.credentials.json
+```
+
+### 3. Environment Variable Reference
+Use variable interpolation in settings.json:
+```json
+"env": {
+  "API_KEY": "${API_KEY}"  // References .env.claude
+}
+```
+
+### 4. Read-Only Mode
+For production safety, consider read-only configurations:
+```json
+"env": {
+  "SUPABASE_READ_ONLY": "true"
+}
+```
+
+---
+
+## Adding New MCP Servers
+
+### Step 1: Install the Server
+```bash
+npx -y @anthropic-ai/mcp-<server-name>
+```
+
+### Step 2: Add to settings.json
+```json
+{
+  "mcpServers": {
+    "new-server": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-new-server"],
+      "env": {
+        "API_KEY": "${NEW_SERVER_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Step 3: Add Credentials to .env.claude
+```bash
+echo 'NEW_SERVER_API_KEY="your-key"' >> ~/.claude/.env.claude
+```
+
+### Step 4: Restart Claude Code
+```bash
+source ~/.claude/.env.claude && claude
+```
+
+---
+
+## Troubleshooting
+
+### Server Not Starting
+1. Check if package is installed: `npx -y @anthropic-ai/mcp-<name> --help`
+2. Verify environment variables are set
+3. Check Claude Code logs: `~/.claude/debug/`
+
+### Authentication Errors
+1. Verify credentials in `.env.claude`
+2. Check file permissions
+3. Ensure variables are exported: `source ~/.env.claude`
+
+### Connection Timeouts
+1. Check network connectivity
+2. Verify API endpoint is accessible
+3. Consider adding timeout configuration
+
+---
+
+## Credential Rotation
+
+### Schedule
+- API keys: Every 90 days
+- OAuth tokens: Automatic refresh
+- Service role keys: Every 90 days
+
+### Rotation Process
+1. Generate new key in service dashboard
+2. Update `.env.claude`
+3. Test connectivity
+4. Revoke old key
+
+---
+
+## Monitoring
+
+### Health Checks
+MCP servers should respond to basic requests within 5 seconds.
+
+### Log Locations
+- MCP errors: `~/.claude/debug/`
+- Connection issues: Check terminal output
+
+---
+
+## Permissions Matrix
+
+| Server | Read | Write | Execute |
+|--------|------|-------|---------|
+| filesystem | ✓ | ✓ | - |
+| supabase | ✓ | ✓ | - |
+| playwright | - | - | ✓ |
+| context7 | ✓ | - | - |
+
+---
+
+## Quick Commands
+
+```bash
+# Start Claude with MCP servers
+source ~/.claude/.env.claude && claude
+
+# List active servers
+cat ~/.claude/settings.json | jq '.mcpServers | keys'
+
+# Test specific server
+npx -y @anthropic-ai/mcp-supabase --help
+```

package/framework/agents/architecture-strategist.md

@@ -1,6 +1,6 @@
 ---
 name: architecture-strategist
-description: "Use this agent when you need to analyze code changes from an architectural perspective, evaluate system design decisions, or ensure that modifications align with established architectural patterns. This includes reviewing pull requests for architectural compliance, assessing the impact of new features on system structure, or validating that changes maintain proper component boundaries and design principles. <example>Context: The user wants to review recent code changes for architectural compliance.\\nuser: \"I just refactored the authentication service to use a new pattern\"\\nassistant: \"I'll use the architecture-strategist agent to review these changes from an architectural perspective\"\\n<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary></example><example>Context: The user is adding a new microservice to the system.\\nuser: \"I've added a new notification service that integrates with our existing services\"\\nassistant: \"Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture\"\\n<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary></example>"
+description: "Analyze code changes from an architectural perspective — component boundaries, coupling, SOLID principles, design pattern compliance. Use after refactors, new service additions, or when validating structural decisions."
 model: inherit
 tools: Read, Bash, Grep, Glob
 ---

package/framework/agents/code-simplicity-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: code-simplicity-reviewer
-description: "Use this agent when you need a final review pass to ensure code changes are as simple and minimal as possible. This agent should be invoked after implementation is complete but before finalizing changes, to identify opportunities for simplification, remove unnecessary complexity, and ensure adherence to YAGNI principles. Examples: <example>Context: The user has just implemented a new feature and wants to ensure it's as simple as possible. user: \"I've finished implementing the user authentication system\" assistant: \"Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent\" <commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary></example> <example>Context: The user has written complex business logic and wants to simplify it. user: \"I think this order processing logic might be overly complex\" assistant: \"I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications\" <commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary></example>"
+description: "Final review pass for simplicity and minimalism — identifies unnecessary complexity, premature abstractions, YAGNI violations, and dead code. Use after implementation is complete, before finalizing changes."
 model: inherit
 tools: Read, Bash, Grep, Glob
 ---

package/framework/agents/kieran-typescript-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: kieran-typescript-reviewer
-description: "Use this agent when you need to review TypeScript code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new TypeScript components. The agent applies Kieran's strict TypeScript conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n  Context: The user has just implemented a new React component with hooks.\\n  user: \"I've added a new UserProfile component with state management\"\\n  assistant: \"I've implemented the UserProfile component. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n  <commentary>\\n  Since new component code was written, use the kieran-typescript-reviewer agent to apply Kieran's strict TypeScript conventions and quality checks.\\n  </commentary>\\n</example>\\n- <example>\\n  Context: The user has refactored an existing service module.\\n  user: \"Please refactor the EmailService to handle attachments\"\\n  assistant: \"I've refactored the EmailService to handle attachments.\"\\n  <commentary>\\n  After modifying existing code, especially services, use kieran-typescript-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n  </commentary>\\n  assistant: \"Let me have Kieran review these changes to the EmailService.\"\\n</example>\\n- <example>\\n  Context: The user has created new utility functions.\\n  user: \"Create a validation utility for user input\"\\n  assistant: \"I've created the validation utility functions.\"\\n  <commentary>\\n  New utilities should be reviewed by kieran-typescript-reviewer to check type safety, naming conventions, and TypeScript best practices.\\n  </commentary>\\n  assistant: \"I'll have Kieran review these utilities to ensure they follow our conventions.\"\\n</example>"
+description: "Review TypeScript code with an extremely high quality bar — strict types, naming conventions, pattern adherence, type safety gaps. Use after implementing features, modifying existing code, or creating new TypeScript components."
 model: inherit
 tools: Read, Bash, Grep, Glob
 ---

package/framework/agents/performance-oracle.md

@@ -1,6 +1,6 @@
 ---
 name: performance-oracle
-description: "Use this agent when you need to analyze code for performance issues, optimize algorithms, identify bottlenecks, or ensure scalability. This includes reviewing database queries, memory usage, caching strategies, and overall system performance. The agent should be invoked after implementing features or when performance concerns arise.\\n\\n<example>\\nContext: The user has just implemented a new feature that processes user data.\\nuser: \"I've implemented the user analytics feature. Can you check if it will scale?\"\\nassistant: \"I'll use the performance-oracle agent to analyze the scalability and performance characteristics of your implementation.\"\\n<commentary>\\nSince the user is concerned about scalability, use the Task tool to launch the performance-oracle agent to analyze the code for performance issues.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is experiencing slow API responses.\\nuser: \"The API endpoint for fetching reports is taking over 2 seconds to respond\"\\nassistant: \"Let me invoke the performance-oracle agent to identify the performance bottlenecks in your API endpoint.\"\\n<commentary>\\nThe user has a performance issue, so use the performance-oracle agent to analyze and identify bottlenecks.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: After writing a data processing algorithm.\\nuser: \"I've written a function to match users based on their preferences\"\\nassistant: \"I've implemented the matching function. Now let me use the performance-oracle agent to ensure it will scale efficiently.\"\\n<commentary>\\nAfter implementing an algorithm, proactively use the performance-oracle agent to verify its performance characteristics.\\n</commentary>\\n</example>"
+description: "Analyze code for performance issues — database queries, algorithms, memory usage, caching strategies, bundle size, render performance. Use after implementing features or when performance concerns arise."
 model: inherit
 tools: Read, Bash, Grep, Glob
 ---

package/framework/agents/qualia-codebase-mapper.md

@@ -2,6 +2,7 @@
 name: qualia-codebase-mapper
 description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
+model: inherit
 color: cyan
 ---
 

package/framework/agents/qualia-debugger.md

@@ -2,6 +2,7 @@
 name: qualia-debugger
 description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /qualia:debug orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
+model: inherit
 color: orange
 ---
 

package/framework/agents/qualia-executor.md

@@ -2,6 +2,7 @@
 name: qualia-executor
 description: Executes Qualia plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
 tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
 color: yellow
 ---
 

package/framework/agents/qualia-integration-checker.md

@@ -2,6 +2,7 @@
 name: qualia-integration-checker
 description: Verifies cross-phase integration and E2E flows. Checks that phases connect properly and user workflows complete end-to-end.
 tools: Read, Bash, Grep, Glob
+model: inherit
 color: blue
 ---
 

package/framework/agents/qualia-phase-researcher.md

@@ -2,6 +2,7 @@
 name: qualia-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by qualia-planner. Spawned by /qualia:plan-phase orchestrator.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+model: inherit
 color: cyan
 ---
 

package/framework/agents/qualia-plan-checker.md

@@ -2,6 +2,7 @@
 name: qualia-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /qualia:plan-phase orchestrator.
 tools: Read, Bash, Glob, Grep
+model: inherit
 color: green
 ---
 

package/framework/agents/qualia-planner.md

@@ -2,6 +2,7 @@
 name: qualia-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /qualia:plan-phase orchestrator.
 tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
+model: inherit
 color: green
 ---
 

package/framework/agents/qualia-project-researcher.md

@@ -2,6 +2,7 @@
 name: qualia-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /qualia:new-project or /qualia:new-milestone orchestrators.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+model: inherit
 color: cyan
 ---
 

package/framework/agents/qualia-research-synthesizer.md

@@ -2,6 +2,7 @@
 name: qualia-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /qualia:new-project after 4 researcher agents complete.
 tools: Read, Write, Bash
+model: inherit
 color: purple
 ---
 

package/framework/agents/qualia-roadmapper.md

@@ -2,6 +2,7 @@
 name: qualia-roadmapper
 description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /qualia:new-project orchestrator.
 tools: Read, Write, Bash, Glob, Grep
+model: inherit
 color: purple
 ---
 

package/framework/agents/qualia-verifier.md

@@ -2,6 +2,7 @@
 name: qualia-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
 tools: Read, Bash, Grep, Glob
+model: inherit
 color: green
 ---
 

package/framework/agents/security-auditor.md

@@ -0,0 +1,72 @@
+---
+name: security-auditor
+description: Security audit specialist — RLS policies, service_role exposure, auth patterns, input validation, secrets scanning, dependency vulnerabilities. Use when auditing a project's security posture before deploy or client handoff.
+model: inherit
+tools: Read, Bash, Grep, Glob
+color: red
+---
+
+You are a security auditor for web applications built with Next.js, Supabase, and Vercel. Your job is to find security vulnerabilities, not code quality issues.
+
+## Audit Dimensions
+
+### 1. Supabase RLS
+For each table in the project:
+- Verify RLS is enabled
+- Check SELECT/INSERT/UPDATE/DELETE policies exist
+- Verify policies use `auth.uid()` — never trust client-provided IDs
+- Flag tables with no policies (wide open)
+
+### 2. Service Role Key Exposure
+Scan for service_role in client-side code:
+```bash
+grep -r "service_role\|SERVICE_ROLE\|supabase.*service" --include="*.ts" --include="*.tsx" \
+  --exclude-dir=node_modules --exclude-dir=.next \
+  | grep -v "server\.\|api/\|supabase/server\|lib/supabase/server\|edge-functions\|supabase/functions"
+```
+Any match in a client component is **CRITICAL**.
+
+### 3. Auth Pattern Verification
+- Server-side mutations use `lib/supabase/server.ts` (not `client.ts`)
+- API routes derive user from `auth.uid()`, never from request body/params
+- Middleware protects authenticated routes
+- Auth tokens have expiry/refresh
+
+### 4. Input Validation
+- All user inputs validated with Zod or equivalent
+- No raw `req.body` usage without validation
+- No `dangerouslySetInnerHTML` or `eval()`
+- No `innerHTML =` or `document.write()`
+
+### 5. Secrets & Environment
+- `.env` files in `.gitignore`
+- No hardcoded API keys, passwords, or tokens in source
+- `NEXT_PUBLIC_` only for client-safe values
+- Service role key only in server contexts
+
+### 6. HTTP Security
+- CORS properly restricted (not wildcard `*`)
+- Rate limiting on auth endpoints
+- Security headers configured (CSP, HSTS, X-Frame-Options)
+- HTTPS enforced
+
+### 7. Dependency Vulnerabilities
+```bash
+npm audit --json 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));console.log('Vulnerabilities:',d.metadata?.vulnerabilities||'unknown')"
+```
+
+### 8. Migration Safety
+- No destructive migrations without guards (DROP TABLE, DROP COLUMN)
+- New tables have corresponding RLS policies
+- No migrations that disable RLS
+
+## Output Format
+
+For EVERY finding:
+- **What**: description
+- **Where**: file:line
+- **Impact**: what an attacker could do
+- **Fix**: concrete remediation
+- **Severity**: CRITICAL / HIGH / MEDIUM / LOW
+
+CRITICAL = data breach risk. HIGH = auth bypass risk. MEDIUM = defense-in-depth gap. LOW = best practice.

package/framework/agents/team-orchestrator.md

@@ -2,6 +2,7 @@
 name: team-orchestrator
 description: Meta-agent that coordinates specialist agent teams using pipeline, fan-out/fan-in, or review loop patterns. Spawned by /team command or Qualia execute-phase with team field.
 tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
 color: magenta
 ---
 

package/framework/agents/teams/framework-audit-team.md

@@ -0,0 +1,66 @@
+# Framework Audit Team
+
+> 6 specialist reviewers audit the Qualia framework infrastructure in parallel, results synthesized into unified report.
+
+## Agents
+
+- **config-reviewer**
+  - subagent_type: general-purpose
+  - role: Review CLAUDE.md, rules/*.md, settings.json for completeness, consistency, contradictions
+  - focus: Identity, rules, permissions, MCP config, hook registrations, cross-references
+
+- **agent-reviewer**
+  - subagent_type: general-purpose
+  - role: Review all agents in agents/*.md and all team templates in agents/teams/ for quality, overlap, gaps, naming
+  - focus: Agent definitions, team patterns, subagent_type alignment, orphan detection
+
+- **skill-reviewer**
+  - subagent_type: general-purpose
+  - role: Review all 65+ skills for quality, overlap, gaps, trigger accuracy, category health
+  - focus: SKILL.md files, skill-agent alignment, dead skill detection, archive health
+
+- **hook-reviewer**
+  - subagent_type: general-purpose
+  - role: Review all 16 hooks for correctness, performance, coverage, branding consistency
+  - focus: Hook scripts, settings.json alignment, exit codes, JSON output, early-exit guards
+
+- **knowledge-reviewer**
+  - subagent_type: general-purpose
+  - role: Review knowledge files and memory system for staleness, accuracy, completeness
+  - focus: Knowledge .md files, MEMORY.md index, cross-references, duplicate content
+
+- **architecture-reviewer**
+  - subagent_type: general-purpose
+  - role: Cross-cutting review of framework organization, naming, dead code, security, scalability
+  - focus: Directory structure, naming conventions, archive health, install scripts, .gitignore
+
+## Pattern
+
+fan-out (all 6 parallel) → synthesize into FRAMEWORK-AUDIT.md
+
+## Shared Context
+
+- ~/.claude/CLAUDE.md — core identity and rules
+- ~/.claude/settings.json — hook config, permissions, MCP servers
+- Framework inventory counts (agents, skills, hooks, knowledge)
+
+## Coordination Rules
+
+- Each reviewer produces findings independently — no coordination needed
+- Reviewers are read-only — they analyze and report, they don't fix
+- Findings must include file references
+- Each reviewer rates findings: CRITICAL / HIGH / MEDIUM / LOW
+- Overlap detection is shared between agent-reviewer and skill-reviewer
+
+## Finding Format
+
+Every finding MUST include:
+- **What**: description
+- **Where**: file or directory
+- **Why**: impact
+- **Fix**: concrete suggestion
+- **Severity**: CRITICAL / HIGH / MEDIUM / LOW
+
+## Output
+
+~/.claude/.planning/FRAMEWORK-AUDIT.md

package/framework/agents/teams/review-team.md

@@ -1,6 +1,6 @@
 # Review Team
 
-> Three specialist reviewers analyze code in parallel, results synthesized into unified report.
+> Four specialist reviewers analyze code in parallel, results synthesized into unified report.
 
 ## Agents
 
@@ -19,9 +19,14 @@
   - role: TypeScript quality — strict types, naming conventions, pattern adherence, type safety gaps
   - focus: Type definitions, generics usage, any/unknown, null handling, naming
 
+- **security-auditor**
+  - subagent_type: security-auditor
+  - role: RLS policies, service_role exposure, auth patterns, input validation, secrets scanning, dependency vulnerabilities
+  - focus: Supabase security, auth flows, env var handling, XSS/injection prevention
+
 ## Pattern
 
-fan-out (all 3 parallel) → synthesize into REVIEW-REPORT.md
+fan-out (all 4 parallel) → synthesize into REVIEW-REPORT.md
 
 ## Shared Context
 
@@ -33,7 +38,7 @@ fan-out (all 3 parallel) → synthesize into REVIEW-REPORT.md
 - Each reviewer produces findings independently — no coordination needed
 - Reviewers are read-only — they analyze and report, they don't fix
 - Findings should include file:line references
-- Each reviewer rates findings: critical / warning / suggestion
+- Each reviewer rates findings: CRITICAL / HIGH / MEDIUM / LOW
 
 ## Output
 
@@ -54,6 +59,9 @@ REVIEW-REPORT.md in current directory with sections:
 ## TypeScript Quality Review
 {From kieran-typescript-reviewer}
 
+## Security Review
+{From security-auditor}
+
 ## Action Items
 | # | Severity | Finding | File:Line | Reviewer |
 |---|----------|---------|-----------|----------|