164 lines
72 KiB
YAML
164 lines
72 KiB
YAML
plan-build-review:
|
||
description: "Plan, implement, and review — the standard development cycle"
|
||
steps:
|
||
- agent: planner
|
||
prompt: "Plan the implementation for: $INPUT"
|
||
- agent: builder
|
||
prompt: "Implement the following plan:\n\n$INPUT"
|
||
- agent: reviewer
|
||
prompt: "Review this implementation for bugs, style, and correctness:\n\n$INPUT"
|
||
|
||
plan-build:
|
||
description: "Plan then build — fast two-step implementation without review"
|
||
steps:
|
||
- agent: planner
|
||
prompt: "Plan the implementation for: $INPUT"
|
||
- agent: builder
|
||
prompt: "Based on this plan, implement:\n\n$INPUT"
|
||
|
||
full-pipeline:
|
||
description: "End-to-end pipeline — scout, plan, build, review, test"
|
||
steps:
|
||
- agent: scout
|
||
prompt: "Explore the codebase and identify: $INPUT"
|
||
- agent: planner
|
||
prompt: "Based on this analysis, create a plan:\n\n$INPUT"
|
||
- agent: builder
|
||
prompt: "Implement this plan:\n\n$INPUT"
|
||
- agent: reviewer
|
||
prompt: "Review this implementation:\n\n$INPUT"
|
||
- agent: tester
|
||
prompt: "Write and run tests for this implementation. Report results.\n\n$INPUT"
|
||
|
||
investigate-fix:
|
||
description: "Bug fix flow — investigate, propose fix, implement, review"
|
||
steps:
|
||
- agent: scout
|
||
prompt: "Explore the codebase relevant to this bug report:\n\n$INPUT"
|
||
- agent: reviewer
|
||
prompt: "Investigate this bug and propose a fix. Include reproduction steps and root cause.\n\nContext:\n$INPUT\n\nOriginal request: $ORIGINAL"
|
||
- agent: builder
|
||
prompt: "Implement the proposed fix from the reviewer. Apply the changes exactly as specified.\n\n$INPUT"
|
||
- agent: reviewer
|
||
prompt: "Review this bug fix for correctness and completeness:\n\n$INPUT"
|
||
|
||
plan-review-plan:
|
||
description: "Iterative planning — plan, critique, then refine with feedback"
|
||
steps:
|
||
- agent: planner
|
||
prompt: "Create a detailed implementation plan for: $INPUT"
|
||
- agent: reviewer
|
||
prompt: "Critically review this implementation plan. Challenge assumptions, find gaps, and suggest improvements:\n\n$INPUT\n\nOriginal request: $ORIGINAL"
|
||
- agent: planner
|
||
prompt: "Revise and improve your implementation plan based on this critique. Address every issue raised and incorporate the recommendations:\n\nOriginal request: $ORIGINAL\n\nCritique:\n$INPUT"
|
||
|
||
test-fix:
|
||
description: "Test-driven fix cycle — add tests, implement, review"
|
||
steps:
|
||
- agent: tester
|
||
prompt: "Write tests for the following requirement or failing behavior. Run existing tests and report status.\n\n$INPUT"
|
||
- agent: builder
|
||
prompt: "Implement the changes needed to make these tests pass:\n\n$INPUT"
|
||
- agent: reviewer
|
||
prompt: "Review this implementation and test results:\n\n$INPUT"
|
||
|
||
audit:
|
||
description: "Comprehensive code audit — scans project, finds issues, generates report and hardening plan"
|
||
steps:
|
||
- agent: scout
|
||
prompt: "# Phase 0: Project Discovery\n\nBefore touching any code, understand what we're working with.\n\n## Steps\n\n1. **Scan the project root** — Read `package.json`, `Cargo.toml`, `requirements.txt`, `go.mod`, `build.gradle`, `Podfile`, or any manifest files to identify:\n - Language(s) and runtime (Node.js, Python, Rust, Go, Swift, Kotlin, etc.)\n - Framework(s) (React, Next.js, Express, FastAPI, Capacitor, Flutter, etc.)\n - Key dependencies and their versions\n - Build tooling and bundlers\n\n2. **Map the architecture** — Identify:\n - Entry points (servers, main files, route handlers, app delegates)\n - Data layer (databases, ORMs, caches, queues)\n - External integrations (APIs, SDKs, third-party services)\n - Auth and session management patterns\n - Background jobs, workers, or scheduled tasks\n\n3. **Classify the project type** and load the appropriate best-practice lens:\n - **Web API / Backend Service** → OWASP API Top 10, 12-factor app principles\n - **Frontend SPA / SSR** → XSS prevention, CSP, bundle security, hydration safety\n - **Mobile App (iOS/Android/Capacitor)** → Platform security guidelines, secure storage, deep link validation\n - **CLI Tool / Agent System** → Input sanitization, privilege escalation, subprocess safety\n - **Library / SDK** → Supply chain safety, API surface minimization, semver discipline\n - **Monorepo / Multi-service** → Audit each service independently, then cross-service boundaries\n\n4. **Search for current best practices** — Based on the identified stack, search the web for:\n - `\"{framework} security best practices {current_year}\"`\n - `\"{language} memory leak patterns\"`\n - `\"{framework} performance optimization\"`\n - Known CVEs for detected dependency versions\n - Official security hardening guides for the framework\n\n$INPUT\n\nReport your findings in a clear, structured format."
|
||
- agent: reviewer
|
||
prompt: "# Phase 1: Deep Scan — Memory, Patterns, Performance, Resilience\n\nPerform a methodical, file-by-file audit. For each finding, record: **file path, line number(s), severity (critical/high/medium/low), category, and description.**\n\n**Project Context:**\n$INPUT\n\n## 1.1 Memory Leaks & Resource Management\n\nScan for:\n- **Unclosed resources** — database connections, file handles, streams, sockets, WebSocket connections not properly closed or disposed\n- **Event listener accumulation** — listeners added in loops, on mount, or in constructors without corresponding removal on teardown/unmount/dispose\n- **Uncleared timers** — `setInterval`, `setTimeout`, cron jobs, or polling loops without cleanup\n- **Orphaned subscriptions** — RxJS/Observable/EventEmitter subscriptions without unsubscribe logic\n- **Circular references** — objects referencing each other preventing garbage collection\n- **Cache without eviction** — in-memory caches (`Map`, `Set`, objects) that grow unbounded with no TTL, LRU, or size limit\n- **Closure captures** — closures inadvertently capturing large scopes or DOM references\n- **Buffer accumulation** — streams or buffers that accumulate without draining\n- **Global state pollution** — data appended to global/module-level variables across requests or invocations\n- **Detached DOM nodes** — references to DOM elements that have been removed from the tree (frontend)\n- **Native bridge leaks** — (mobile) native plugin callbacks not cleaned up, Capacitor/Cordova listener leaks\n\n## 1.2 Anti-Patterns & Code Smells\n\nScan for:\n- **Error swallowing** — empty catch blocks, `.catch(() => {})`, ignored promise rejections\n- **Unhandled async** — missing `await`, fire-and-forget promises without error handling, unhandled rejection paths\n- **Race conditions** — shared mutable state accessed from concurrent contexts without synchronization\n- **Callback hell / pyramid of doom** — deeply nested callbacks that should be refactored to async/await or pipelines\n- **God objects / functions** — single files or functions with 500+ lines doing too many things\n- **Magic numbers and strings** — hardcoded values without named constants or configuration\n- **Copy-paste duplication** — repeated code blocks that should be abstracted\n- **Tight coupling** — direct instantiation or deep import chains making testing/mocking impossible\n- **Missing type safety** — `any` types in TypeScript, no input validation, implicit type coercion\n- **Improper null handling** — unchecked nullable values, missing optional chaining, bare property access on potentially undefined objects\n- **Synchronous blocking** — blocking the event loop (Node.js), main thread (mobile), or UI thread with heavy computation\n- **Dead code** — unreachable code, unused imports, commented-out blocks, deprecated feature flags still in codebase\n\n## 1.4 Performance & Reliability\n\nScan for:\n- **N+1 queries** — database calls inside loops instead of batch/join operations\n- **Missing indexes** — queries on unindexed fields (check schema + query patterns)\n- **Unbounded queries** — `SELECT *` or queries without `LIMIT` that could return massive result sets\n- **Missing pagination** — list endpoints that return all records\n- **Redundant re-renders** — (frontend) components re-rendering without memoization, missing `useMemo`/`useCallback`/`React.memo`\n- **Large bundle / payload** — importing entire libraries when only a subset is needed, no tree-shaking, oversized API responses\n- **Missing caching** — repeated expensive computations or network calls without caching layers\n- **No graceful degradation** — missing circuit breakers, retries, fallbacks, or timeout configurations\n- **Missing health checks** — no liveness/readiness endpoints for services\n- **Unoptimized assets** — uncompressed images, unminified JS/CSS in production builds\n\n## 1.5 Resilience & Error Handling\n\nScan for:\n- **Missing error boundaries** — (React) no `ErrorBoundary` components around critical UI sections\n- **Crash-inducing exceptions** — unhandled exceptions that crash the process/app instead of being caught\n- **No retry logic** — network calls to external services without retry + backoff\n- **Missing timeouts** — HTTP requests, database queries, or external calls with no timeout configured\n- **Incomplete cleanup on failure** — transactions not rolled back, temp files not deleted, locks not released on error paths\n- **Silent failures** — operations that fail but the system continues in a corrupt or inconsistent state\n- **Missing validation at boundaries** — no input validation on API endpoints, form submissions, or message handlers\n\nReport findings with file paths, line numbers, severity, category, and description."
|
||
- agent: red-team
|
||
prompt: "# Phase 1: Deep Scan — Security Vulnerabilities\n\nPerform a methodical security audit. For each finding, record: **file path, line number(s), severity (critical/high/medium/low), category, and description.**\n\n**Project Context:**\n$INPUT_1\n\n## 1.3 Security Vulnerabilities\n\nScan for:\n- **Injection flaws** — SQL injection, NoSQL injection, command injection, LDAP injection, template injection\n- **XSS vectors** — unsanitized user input rendered in HTML/DOM, `dangerouslySetInnerHTML`, `innerHTML`, `eval()`\n- **Authentication weaknesses** — hardcoded credentials, weak token generation, missing token expiration, insecure session management\n- **Authorization gaps** — missing permission checks, IDOR (Insecure Direct Object References), privilege escalation paths\n- **Secrets exposure** — API keys, tokens, passwords in source code, `.env` files committed, secrets in logs\n- **Insecure data storage** — sensitive data in `localStorage`, `SharedPreferences` without encryption, plaintext storage\n- **Insecure communication** — HTTP instead of HTTPS, missing TLS certificate validation, insecure WebSocket connections\n- **Dependency vulnerabilities** — outdated packages with known CVEs, unpinned versions, untrusted registries\n- **Path traversal** — user-controlled file paths without sanitization\n- **CORS misconfiguration** — overly permissive origins, credentials exposure\n- **CSRF / SSRF** — missing anti-forgery tokens, unvalidated redirect URLs, internal network access via user-supplied URLs\n- **Logging sensitive data** — PII, tokens, or credentials written to logs\n- **Insecure deserialization** — parsing untrusted data (JSON, YAML, pickle, XML) without validation\n- **Rate limiting absence** — no throttling on auth endpoints, API routes, or resource-intensive operations\n\nReport findings with file paths, line numbers, severity, category, and description."
|
||
- agent: reviewer
|
||
prompt: "# Phase 2: Findings Report\n\nConsolidate the audit findings into a structured report.\n\n**Phase 1 Findings:**\n\n## Code Quality & Performance Findings\n\n$INPUT_2\n\n## Security Findings\n\n$INPUT_3\n\n## Format\n\n```markdown\n## Audit Findings Report\n\n**Project:** [name]\n**Stack:** [detected languages, frameworks, key deps]\n**Scanned:** [number of files] files across [number of directories] directories\n**Date:** [current date]\n\n### Summary\n\n| Severity | Count |\n|----------|-------|\n| 🔴 Critical | X |\n| 🟠 High | X |\n| 🟡 Medium | X |\n| 🔵 Low | X |\n\n### Critical Findings\n\n#### [CRIT-001] [Title]\n- **File:** `path/to/file.ts:42`\n- **Category:** Memory Leak | Security | Anti-Pattern | Performance | Resilience\n- **Description:** [What's wrong]\n- **Impact:** [What can go wrong if unaddressed]\n- **Evidence:** [Code snippet or reference]\n\n[...repeat for each finding, grouped by severity...]\n```\n\nProduce the complete findings report following this format."
|
||
- agent: planner
|
||
prompt: "# Phase 3: Hardening Plan\n\nBased on the findings report, create a prioritized, actionable remediation plan.\n\n**Findings Report:**\n$INPUT\n\n## Format\n\n```markdown\n## Hardening Plan\n\n### Priority 1: Critical Fixes (Do Immediately)\n\n#### [Fix for CRIT-001]\n- **What:** [Concise description of the change]\n- **Where:** `path/to/file.ts`\n- **How:** [Step-by-step implementation approach]\n- **Verification:** [How to confirm the fix works — test, metric, or check]\n\n### Priority 2: High-Impact Improvements (This Sprint)\n[...]\n\n### Priority 3: Medium-Term Hardening (Next 2-4 Weeks)\n[...]\n\n### Priority 4: Long-Term Excellence (Backlog)\n[...]\n\n### Recommended Tooling & Automation\n\n| Purpose | Tool | Notes |\n|---------|------|------|\n| Static analysis | [e.g., ESLint strict config, Semgrep] | [setup notes] |\n| Dependency audit | [e.g., npm audit, Snyk, Dependabot] | [frequency] |\n| Memory profiling | [e.g., Chrome DevTools, Instruments, Valgrind] | [when to run] |\n| Security scanning | [e.g., OWASP ZAP, Trivy, CodeQL] | [CI integration] |\n| Performance monitoring | [e.g., Sentry, Datadog, Lighthouse CI] | [thresholds] |\n\n### Recommended Process Changes\n\n- [ ] Add pre-commit hooks for [specific checks]\n- [ ] Add CI pipeline stages for [security scan, lint, type check]\n- [ ] Establish code review checklist covering [top finding categories]\n- [ ] Schedule recurring dependency audits every [timeframe]\n- [ ] Add monitoring/alerting for [specific metrics from findings]\n```\n\nProduce the complete hardening plan following this format."
|
||
|
||
sentry-setup:
|
||
description: "Verify Sentry CLI setup — check auth, project linking, SDK integration, and DSN configuration"
|
||
steps:
|
||
- agent: reviewer
|
||
prompt: "# Phase 1: Check Sentry Auth & Project\n\nVerify the Sentry CLI setup for this project.\n\n## Steps\n\n1. **Check authentication** — Run `sentry auth login --check` or `sentry info` to verify the CLI is authenticated.\n\n2. **List organizations** — Run `sentry org list --json` to see available orgs.\n\n3. **List projects** — Run `sentry project list --json` to see available projects.\n\n4. **Check local config** — Look for:\n - `.sentryclirc` file in the project root\n - `SENTRY_DSN` in `.env` or environment config files\n - `sentry.properties` or `sentry.client.config.js/ts` files\n - SDK integration in code (search for `@sentry/`, `sentry-sdk`, `sentry_sdk`, `Sentry.init`)\n\n$INPUT\n\nReport all findings clearly: what's configured, what's missing, and any errors encountered."
|
||
- agent: reviewer
|
||
prompt: "# Phase 2: Sentry Setup Report\n\nBased on the investigation results, produce a clear setup status report.\n\n**Investigation Results:**\n$INPUT\n\n## Format\n\n```markdown\n## Sentry Setup Report\n\n**Date:** [current date]\n\n### Authentication\n- **Status:** ✅ Authenticated / ❌ Not authenticated\n- **Details:** [user/org info if available]\n\n### Organization & Project\n- **Org:** [detected org or \"not detected\"]\n- **Project:** [detected project or \"not detected\"]\n- **Linked:** ✅ / ❌\n\n### SDK Integration\n- **SDK Found:** ✅ / ❌\n- **Package:** [e.g., @sentry/node, @sentry/react]\n- **Init Location:** [file path if found]\n\n### DSN Configuration\n- **DSN Found:** ✅ / ❌\n- **Location:** [.env, config file, etc.]\n\n### Missing Steps\n\n[Numbered list of things that need to be done to complete setup, with instructions for each. If everything is configured, say \"All set!\"]\n```\n\nProduce the complete report following this format."
|
||
|
||
sentry-logs:
|
||
description: "Fetch Sentry issues, analyze root causes with Seer, and create a prioritized fix plan"
|
||
steps:
|
||
- agent: reviewer
|
||
prompt: "# Phase 1: Fetch Sentry Issues\n\nRetrieve current issues from Sentry.\n\n## Steps\n\n1. **List issues** — Run `sentry issue list --json` to get current issues/crashes.\n\n2. **Parse and categorize** — Organize issues by:\n - Severity / level (fatal, error, warning)\n - Frequency (event count)\n - Type (error, crash, performance issue)\n - First seen / last seen dates\n\n3. **Identify top issues** — Rank by frequency × severity to find the most impactful issues.\n\n$INPUT\n\nReport the full issue list with categorization, and highlight the top issues that need immediate attention."
|
||
- agent: reviewer
|
||
prompt: "# Phase 2: Deep Investigation\n\nFor the top issues identified, get AI-powered root cause analysis.\n\n**Issue List:**\n$INPUT\n\n## Steps\n\n1. **For each top issue** (up to 10 by impact), run:\n - `sentry issue explain <short-id>` — get Seer's AI root cause analysis\n\n2. **Correlate with local code** — For each explained issue:\n - Identify the affected file(s) and line(s) in the local codebase\n - Check if the code has changed since the issue was first reported\n - Note any patterns (same module, same dependency, same error type)\n\nReport each issue with its Seer explanation and local code correlation."
|
||
- agent: red-team
|
||
prompt: "# Phase 3: Impact Analysis\n\nAssess the real-world impact of the Sentry issues.\n\n**Issues with Root Causes:**\n$INPUT\n\n## Steps\n\n1. **User-facing impact** — For each issue:\n - Does it crash the app / break functionality?\n - How many users are affected?\n - Is it visible to users or silent?\n\n2. **System impact** — For each issue:\n - Does it degrade performance?\n - Does it cause data loss or corruption?\n - Does it affect other services?\n\n3. **Pattern analysis** — Look for:\n - Issues with the same root cause\n - Related services or modules affected\n - Recurring regressions (issues that were fixed and came back)\n - Common dependency issues\n\n4. **Cross-reference with codebase** — Check affected code paths for:\n - Missing error handling\n - Race conditions\n - Resource leaks\n - Configuration issues\n\nReport impact assessment for each issue with severity classification."
|
||
- agent: reviewer
|
||
prompt: "# Phase 4: Findings Report\n\nConsolidate all Sentry findings into a structured report.\n\n**Issue List & Categories:**\n$INPUT_1\n\n**Root Cause Analysis:**\n$INPUT_2\n\n**Impact Analysis:**\n$INPUT_3\n\n## Format\n\n```markdown\n## Sentry Issues Report\n\n**Project:** [name]\n**Date:** [current date]\n**Total Issues:** [count]\n\n### Summary\n\n| Severity | Count |\n|----------|-------|\n| 🔴 Fatal/Critical | X |\n| 🟠 Error | X |\n| 🟡 Warning | X |\n| 🔵 Info | X |\n\n### Top Issues\n\n#### [SENTRY-001] [Issue Title / Short ID]\n- **Level:** fatal / error / warning\n- **Events:** [count] | **Users affected:** [count]\n- **First seen:** [date] | **Last seen:** [date]\n- **File:** `path/to/file.ts:42`\n- **Root Cause:** [Seer explanation summary]\n- **Impact:** [User-facing and system impact]\n\n[...repeat for each top issue...]\n\n### Patterns & Trends\n\n[Common root causes, affected modules, recurring issues]\n```\n\nProduce the complete findings report following this format."
|
||
- agent: planner
|
||
prompt: "# Phase 5: Fix Plan\n\nCreate a prioritized, actionable plan to fix the Sentry issues.\n\n**Findings Report:**\n$INPUT\n\n## Steps\n\n1. **Group related fixes** — Issues with the same root cause should be fixed together.\n\n2. **For complex issues**, reference `sentry issue plan <short-id>` output where relevant.\n\n3. **Include verification steps** — How to confirm each fix resolves the issue in Sentry.\n\n## Format\n\n```markdown\n## Sentry Fix Plan\n\n### Priority 1: Critical Fixes (Do Immediately)\n\n#### [Fix for SENTRY-001]\n- **Issue(s):** [short-id(s)]\n- **What:** [Concise description of the fix]\n- **Where:** `path/to/file.ts`\n- **How:** [Step-by-step implementation]\n- **Verification:** [How to confirm the fix — check Sentry for issue resolution, add test, etc.]\n\n### Priority 2: High-Impact Fixes (This Sprint)\n[...]\n\n### Priority 3: Medium-Term Improvements\n[...]\n\n### Monitoring Recommendations\n\n- [ ] Set up Sentry alerts for [specific conditions]\n- [ ] Add custom breadcrumbs for [specific flows]\n- [ ] Configure performance monitoring for [specific transactions]\n- [ ] Review error budgets and set SLOs\n```\n\nProduce the complete fix plan following this format."
|
||
|
||
performance:
|
||
description: "Performance optimization — profile bottlenecks, stress-test, and build an optimization plan"
|
||
steps:
|
||
- agent: scout
|
||
prompt: "# Phase 0: Performance Discovery\n\nBefore optimizing anything, understand what we're working with.\n\n## Steps\n\n1. **Identify the stack** — Read manifest files (`package.json`, `Cargo.toml`, `requirements.txt`, `go.mod`, etc.) to identify:\n - Language(s), runtime, and framework(s)\n - Build tooling and bundlers (Webpack, Vite, esbuild, Turbopack, etc.)\n - Key dependencies and their versions\n\n2. **Map entry points and hot paths** — Identify:\n - Server entry points, route handlers, middleware chains\n - Client entry points, page routes, critical rendering paths\n - Background jobs, workers, scheduled tasks, queue consumers\n - Database access patterns (ORMs, raw queries, connection setup)\n\n3. **Inventory existing perf tooling** — Check for:\n - Monitoring/APM (Sentry, Datadog, New Relic, Lighthouse CI)\n - Caching layers (Redis, Memcached, in-memory caches, CDN config)\n - Build optimizations (code splitting, tree shaking, minification, compression)\n - Load balancing, auto-scaling, or concurrency configuration\n\n4. **Establish baseline metrics** — Note current state of:\n - Bundle sizes (if frontend)\n - Dependency count and tree depth\n - Number of API routes / endpoints\n - Database migration count and schema complexity\n - Any existing benchmarks or perf test suites\n\n$INPUT\n\nReport your findings in a clear, structured format."
|
||
- agent: reviewer
|
||
prompt: "# Phase 1: Deep Performance Scan\n\nPerform a methodical, file-by-file performance audit. For each finding, record: **file path, line number(s), severity (critical/high/medium/low), category, and description.**\n\n**Project Context:**\n$INPUT\n\n## 1.1 Database & Query Performance\n\nScan for:\n- **N+1 queries** — database calls inside loops instead of batch/join operations\n- **Missing indexes** — queries on unindexed fields (check schema + query patterns)\n- **Unbounded queries** — `SELECT *` or queries without `LIMIT` that could return massive result sets\n- **Missing pagination** — list endpoints returning all records\n- **Inefficient joins** — cartesian products, unnecessary subqueries, missing query optimization\n- **Connection pool misconfiguration** — pool too small for load, no idle timeout, missing connection reuse\n- **Missing query caching** — repeated identical queries without caching layer\n- **Slow migrations** — locking migrations on large tables, missing concurrent index creation\n\n## 1.2 Compute & I/O Bottlenecks\n\nScan for:\n- **Blocking I/O** — synchronous file reads, blocking network calls on main/event-loop thread\n- **CPU-bound work on hot paths** — JSON parsing of large payloads, regex on untrusted input, heavy computation without worker threads\n- **Unnecessary serialization** — repeated JSON.stringify/parse cycles, deep cloning where shallow would suffice\n- **Missing streaming** — loading entire files/responses into memory instead of streaming\n- **Inefficient algorithms** — O(n²) or worse where O(n log n) or O(n) alternatives exist\n- **Redundant work** — recomputing values that could be memoized or cached\n- **Missing concurrency** — sequential awaits that could be parallelized with Promise.all/allSettled\n\n## 1.3 Frontend & Rendering Performance\n\nScan for:\n- **Redundant re-renders** — components re-rendering without memoization, missing useMemo/useCallback/React.memo\n- **Large bundles** — importing entire libraries when only a subset is needed, no tree-shaking\n- **Missing code splitting** — no lazy loading for routes or heavy components\n- **Unoptimized assets** — uncompressed images, unminified JS/CSS, missing WebP/AVIF\n- **Layout thrashing** — reading and writing DOM layout properties in tight loops\n- **Missing virtual scrolling** — rendering thousands of list items instead of virtualizing\n- **Render-blocking resources** — synchronous scripts in head, CSS not deferred for below-fold content\n- **Missing preloading** — critical resources not preloaded, no resource hints (prefetch, preconnect)\n\n## 1.4 Network & Caching\n\nScan for:\n- **Missing HTTP caching** — no Cache-Control headers, no ETag/Last-Modified, no CDN caching\n- **Waterfall requests** — sequential API calls that could be batched or parallelized\n- **Over-fetching** — API responses returning much more data than the client needs\n- **Missing compression** — no gzip/brotli on API responses or static assets\n- **Chatty protocols** — many small requests where a single batch request would suffice\n- **Missing connection reuse** — not using HTTP keep-alive, creating new connections per request\n- **No request deduplication** — identical concurrent requests not deduplicated\n\n## 1.5 Memory & Resource Management\n\nScan for:\n- **Memory leaks** — unclosed resources, event listener accumulation, uncleared timers, orphaned subscriptions\n- **Cache without eviction** — in-memory caches that grow unbounded with no TTL, LRU, or size limit\n- **Buffer accumulation** — streams or buffers that accumulate without draining\n- **Large object retention** — holding references to large objects longer than necessary\n- **Missing garbage collection hints** — (where applicable) not releasing references to allow GC\n\nReport findings with file paths, line numbers, severity, category, and description."
|
||
- agent: red-team
|
||
prompt: "# Phase 2: Load & Stress Analysis\n\nAnalyze the codebase for breaking points under load. For each finding, record: **file path, line number(s), severity (critical/high/medium/low), category, and description.**\n\n**Project Context:**\n$INPUT_1\n\n## 2.1 Concurrency & Contention\n\nScan for:\n- **Race conditions** — shared mutable state accessed from concurrent contexts without synchronization\n- **Lock contention** — mutexes, semaphores, or database locks held too long or too broadly\n- **Deadlock potential** — multiple locks acquired in inconsistent order\n- **Thread pool exhaustion** — blocking operations consuming all available threads/workers\n- **Missing atomic operations** — read-modify-write sequences that aren't atomic\n\n## 2.2 Resource Exhaustion Under Load\n\nScan for:\n- **Unbounded queues** — in-memory queues or buffers that grow without limit under backpressure\n- **Connection pool exhaustion** — pools too small for peak load, no queuing or timeout for pool acquisition\n- **File descriptor leaks** — handles not released on error paths, especially under high concurrency\n- **Memory pressure** — allocations that scale linearly with request count without bounds\n- **Missing backpressure** — producers faster than consumers with no flow control mechanism\n- **Goroutine/fiber/task leaks** — spawned concurrent tasks that never complete or get cleaned up\n\n## 2.3 Scalability Bottlenecks\n\nScan for:\n- **Single points of contention** — shared resources that become bottlenecks (single DB connection, global locks, shared counters)\n- **Missing horizontal scaling support** — in-memory sessions, local file storage, node-specific state\n- **Thundering herd** — cache stampede on expiry, all instances retrying simultaneously on failure\n- **Missing rate limiting** — no throttling on expensive operations, allowing resource exhaustion via legitimate traffic\n- **Inefficient serialization under load** — serialization formats that degrade with payload size (XML vs protobuf)\n\n## 2.4 Timeout & Failure Cascade\n\nScan for:\n- **Missing timeouts** — HTTP requests, database queries, or external calls with no timeout configured\n- **No circuit breakers** — failing external dependencies causing cascading failures\n- **Missing retry budgets** — unlimited retries amplifying load during partial outages\n- **No graceful degradation** — system fails completely instead of degrading specific features\n- **Health check gaps** — no liveness/readiness probes, or probes that don't check actual dependencies\n\nReport findings with file paths, line numbers, severity, category, and description."
|
||
- agent: reviewer
|
||
prompt: "# Phase 3: Performance Findings Report\n\nConsolidate all performance findings into a structured report.\n\n**Deep Scan Findings:**\n$INPUT_2\n\n**Load & Stress Findings:**\n$INPUT_3\n\n## Format\n\n```markdown\n## Performance Findings Report\n\n**Project:** [name]\n**Stack:** [detected languages, frameworks, key deps]\n**Scanned:** [number of files] files across [number of directories] directories\n**Date:** [current date]\n\n### Summary\n\n| Severity | Count |\n|----------|-------|\n| 🔴 Critical | X |\n| 🟠 High | X |\n| 🟡 Medium | X |\n| 🔵 Low | X |\n\n### Critical Findings\n\n#### [PERF-001] [Title]\n- **File:** `path/to/file.ts:42`\n- **Category:** Database | Compute | Frontend | Network | Memory | Concurrency | Scalability\n- **Description:** [What's slow or inefficient]\n- **Impact:** [Estimated performance impact — latency, throughput, memory, bundle size]\n- **Evidence:** [Code snippet, query plan, or metric reference]\n\n[...repeat for each finding, grouped by severity...]\n```\n\nProduce the complete findings report following this format."
|
||
- agent: planner
|
||
prompt: "# Phase 4: Optimization Plan\n\nBased on the performance findings report, create a prioritized, actionable optimization plan.\n\n**Findings Report:**\n$INPUT\n\n## Format\n\n```markdown\n## Performance Optimization Plan\n\n### Priority 1: Quick Wins (High Impact, Low Effort)\n\n#### [Fix for PERF-001]\n- **What:** [Concise description of the optimization]\n- **Where:** `path/to/file.ts`\n- **How:** [Step-by-step implementation approach]\n- **Expected Impact:** [Estimated improvement — e.g., \"reduces API latency by ~40%\", \"cuts bundle size by 200KB\"]\n- **Verification:** [How to measure the improvement — benchmark, metric, or test]\n- **Risk:** [Low/Medium — what could go wrong and how to mitigate]\n\n### Priority 2: Significant Optimizations (This Sprint)\n[...]\n\n### Priority 3: Architectural Improvements (Next 2-4 Weeks)\n[...]\n\n### Priority 4: Long-Term Performance Excellence (Backlog)\n[...]\n\n### Recommended Tooling & Monitoring\n\n| Purpose | Tool | Notes |\n|---------|------|------|\n| APM / Tracing | [e.g., Sentry Performance, Datadog APM, OpenTelemetry] | [setup notes] |\n| Bundle analysis | [e.g., webpack-bundle-analyzer, source-map-explorer] | [when to run] |\n| Load testing | [e.g., k6, Artillery, autocannon, wrk] | [scenarios to test] |\n| Memory profiling | [e.g., Chrome DevTools, Instruments, clinic.js] | [when to profile] |\n| Database profiling | [e.g., EXPLAIN ANALYZE, pg_stat_statements, slow query log] | [thresholds] |\n| Lighthouse / Web Vitals | [e.g., Lighthouse CI, web-vitals library] | [target scores] |\n\n### Recommended Process Changes\n\n- [ ] Add performance budgets to CI (bundle size, Lighthouse scores)\n- [ ] Set up continuous load testing for critical paths\n- [ ] Add database query logging with slow query alerts\n- [ ] Establish performance review checklist for PRs\n- [ ] Schedule regular profiling sessions every [timeframe]\n```\n\nProduce the complete optimization plan following this format."
|
||
|
||
secure:
|
||
description: "AI security sweep — detect prompt injection vulnerabilities, credential exposure, and missing protections"
|
||
steps:
|
||
- agent: scout
|
||
prompt: "# Phase 0: AI Security Discovery\n\nMap this project's AI attack surface.\n\n1. Identify AI service imports (openai, anthropic, langchain, cohere, huggingface, vercel ai sdk, google generative-ai)\n2. Find AI API calls (chat.completions.create, messages.create, generateText, etc.)\n3. Find AI-related env vars and endpoints (/api/chat, /api/completion, /api/ai)\n4. Map data flow: where user input enters, how it reaches AI calls, what happens with responses\n5. Check for input validation, output filtering, rate limiting, auth on AI endpoints\n6. Check secrets management: are keys in env vars, is .env in .gitignore\n\n$INPUT\n\nReport all findings with file paths and line numbers."
|
||
- agent: red-team
|
||
prompt: "# Phase 1: AI Security Vulnerability Analysis\n\nBased on the discovery, identify specific attack vectors.\n\n**Discovery Results:**\n$INPUT\n\n## Evaluate:\n1. **Prompt Injection** — can users inject instructions that override system prompts? Is there input/instruction separation? Indirect injection via databases, URLs, files?\n2. **Credential Exfiltration** — can injection reveal API keys? Can tool calling send data externally? Can system prompts be extracted?\n3. **Data Leakage** — can users access other users' data? Is PII flowing unprotected? Are responses logged insecurely?\n4. **Abuse** — rate limits? Billing limits? Token exhaustion protection?\n5. **Output Safety** — is AI output sanitized before HTML rendering? Can output be eval'd as code?\n\nFor each vulnerability: file, line, severity, proof of concept, and impact."
|
||
- agent: reviewer
|
||
prompt: "# Phase 2: AI Security Findings Report\n\nConsolidate findings into a structured report.\n\n**Discovery:**\n$INPUT_1\n\n**Vulnerabilities:**\n$INPUT_2\n\nFormat as:\n- Security Score X/100\n- Executive Summary\n- Findings table (severity, count)\n- Each finding: ID, severity, category (Prompt Injection / Credential Exposure / Data Leakage / Missing Protection), file:line, description, proof of concept, impact, recommendation\n- Positive findings (security measures already in place)"
|
||
- agent: planner
|
||
prompt: "# Phase 3: AI Security Hardening Plan\n\nCreate prioritized remediation with installable protections.\n\n**Security Report:**\n$INPUT\n\n## Plan:\n1. **Priority 1: Critical Fixes** — immediate code changes with file:line and code examples\n2. **Priority 2: Install Protections** — recommend running /secure install to generate AI Security Guard (input sanitization + output filtering), Security Policy YAML, rate limiting middleware, and CI security checks\n3. **Priority 3: Configuration** — rate limits, token limits, logging, monitoring\n4. **Priority 4: Process** — security review checklist, incident response, alerting\n\nRecommended architecture: User Input -> Rate Limiter -> Input Sanitizer -> AI API -> Output Filter -> Response, with Audit Logger and Content Filter as side-channels."
|
||
|
||
network-security-local:
|
||
description: "Curated security intelligence, passive local inspection, safe local port analysis, and defensive reporting"
|
||
steps:
|
||
- agent: security-news-analyst
|
||
prompt: "Gather current trusted security intelligence relevant to this local network security task. Prefer official or high-trust sources only. Include OWASP, CISA, NVD, CVE, and protocol-relevant items when applicable.\n\nTask:\n$INPUT"
|
||
- agent: network-scout
|
||
prompt: "Perform passive local network inspection for this task. Inventory interfaces and local listeners first, then summarize any bounded passive inspection findings that are safe and authorized.\n\nTask context:\n$ORIGINAL\n\nThreat intelligence context:\n$INPUT"
|
||
- agent: port-scan-analyst
|
||
prompt: "Perform a safe, scope-restricted local port analysis only if the task includes an explicit loopback or private IP target. Use conservative defaults and explain any refusal clearly.\n\nTask context:\n$ORIGINAL\n\nPassive inspection context:\n$INPUT"
|
||
- agent: reviewer
|
||
prompt: "Produce a defensive local network security report. Consolidate trusted intelligence, passive inspection findings, and safe port-analysis results. Clearly separate: completed checks, refused or skipped actions, findings, and recommended mitigations.\n\nSecurity intelligence:\n$INPUT_1\n\nPassive inspection:\n$INPUT_2\n\nPort analysis:\n$INPUT_3"
|
||
|
||
code-review:
|
||
description: "Multi-pass code review — parallel context gathering, split review, remediation, validation, test verification, and final report"
|
||
steps:
|
||
- agent: scout
|
||
prompt: "# Step 1: Architecture Scout — Deep Structural Research\n\nMap the high-level architecture of the code under review. Do NOT skim — read files thoroughly.\n\n## Scope\n\nThe user's request determines what to review. Parse their intent:\n- If they mention 'last commit' or 'HEAD~1', run `git diff HEAD~1` and focus on those files\n- If they mention 'staged' or 'cached', run `git diff --cached` and focus on those files\n- If they mention 'unstaged' or 'current changes', run `git diff` and focus on those files\n- If they mention a specific directory or file path, focus on that\n- If they say 'full' or 'everything', scan the entire project\n- If unclear, default to `git diff` (unstaged changes)\n\nUser request: $ORIGINAL\n\n## Tasks\n\n1. **Identify the change scope** — run the appropriate git diff command and list all affected files\n2. **Deep-read every changed file end-to-end** — do not skim. For each changed file, identify:\n - What module/subsystem it belongs to\n - Its entry points and exports\n - Key interfaces, types, enums, and data structures it defines or uses\n - Base classes and inheritance chains it participates in\n3. **Identify the tech stack** — languages, frameworks, build tools, runtime\n4. **Map the module boundaries** — how changed files relate to each other and to the rest of the codebase\n5. **Map the class/type hierarchy** — for any new classes, interfaces, enums, or types introduced in the diff:\n - Search the ENTIRE codebase for existing base classes, abstract classes, or interfaces that could have been extended instead\n - Search for existing enums that could have been extended with new values instead of creating new enums\n - Search for existing utility functions/helpers that already do what the new code does\n - Run targeted grep/find for similar names, similar functionality, similar patterns\n6. **Catalog reusable infrastructure** — identify shared utilities, common base classes, helper libraries, and framework abstractions that already exist in the project\n\nReport findings with file paths and line numbers. Be thorough — the downstream review depends on the depth of your research."
|
||
- agent: ranger
|
||
prompt: "# Step 2: Pattern, Convention & DRY Scout — Deep Research\n\nDeeply analyze coding patterns and enforce DRY (Don't Repeat Yourself) principles. This is the most critical scout — your findings determine whether the code is extending the codebase properly or reinventing the wheel.\n\nUser request: $ORIGINAL\n\n## Tasks\n\n1. **Identify the change scope** — run the appropriate git diff command based on the user's request (see Step 1 for scope parsing rules) and list all affected files\n\n2. **Study existing examples FIRST** — before judging the changed code, deeply research the codebase:\n - Find 3-5 existing files that do similar things to the changed files\n - Read those examples end-to-end to understand the established patterns\n - Note the naming conventions, file organization, error handling, and code structure used\n - Identify the 'golden example' — the best-written existing file that the new code should emulate\n\n3. **DRY Enforcement — the core mission:**\n - **New files created?** Search the codebase for existing files that already solve the same problem or a similar one. Could the existing file have been extended instead?\n - **New classes/interfaces?** Search for existing base classes, abstract classes, mixins, or interfaces that the new class should extend or implement. Run `grep -r 'class ' --include='*.ts'` (or equivalent) to find all classes.\n - **New enums or constants?** Search for existing enums that could have received new values instead of creating a new enum. Run `grep -r 'enum ' --include='*.ts'` to find all enums.\n - **New utility functions?** Search for existing helpers, utils, and shared libraries. Run `find . -name '*util*' -o -name '*helper*' -o -name '*common*' -o -name '*shared*'` to locate them. Read them.\n - **New types?** Search for existing type definitions that could be extended, intersected, or reused.\n - **Duplicated logic?** For any block of 5+ lines in the changed code, search the codebase for similar logic that already exists elsewhere.\n - For every DRY violation found, report: the new code location, the existing code it duplicates or should extend, and the specific refactoring suggested.\n\n4. **Catalog existing patterns** in the changed files and their surrounding context:\n - Naming conventions (variables, functions, files, classes)\n - Error handling patterns (try/catch, Result types, error callbacks)\n - Async patterns (async/await, promises, callbacks, observables)\n - State management patterns\n - Import/export organization\n - How similar features were added before (find the git log for analogous past changes if possible)\n\n5. **Identify pattern violations** — places where the changed code breaks established conventions\n\n6. **Check code style** — formatting, indentation, comment style, documentation patterns\n\n7. **Look for anti-patterns** — copy-paste duplication, god objects, deep nesting, magic numbers, dead code\n\n## Output: DRY Violations Section (REQUIRED)\n\nYou MUST include a dedicated DRY Violations section in your report:\n\n```\n### DRY Violations\n\n| New Code | Existing Code | Action |\n|----------|--------------|--------|\n| path/new.ts:15 NewClass | path/existing.ts:30 BaseClass | Extend BaseClass instead of creating NewClass |\n| path/new.ts:45 StatusEnum | path/types.ts:10 StateEnum | Add values to StateEnum instead |\n| path/new.ts:80 formatDate() | path/utils.ts:20 formatTimestamp() | Reuse formatTimestamp() |\n```\n\nIf no DRY violations found, explicitly state: 'No DRY violations detected — all new code is justified.'\n\nReport all findings with file paths and line numbers."
|
||
- agent: scout
|
||
prompt: "# Step 3: Dependency, Configuration & Secrets Scout — Deep Research\n\nAnalyze dependencies, configuration, and secrets exposure in the code under review. Research thoroughly before reporting.\n\nUser request: $ORIGINAL\n\n## Tasks\n\n### Dependency Analysis\n1. **Identify the change scope** — run the appropriate git diff command based on the user's request and list all affected files\n2. **Map dependency changes** — check if any manifest files changed (package.json, Cargo.toml, requirements.txt, go.mod, etc.):\n - New dependencies added — are they necessary? Are they well-maintained? Does the project already have a dependency that does the same thing?\n - Dependencies removed — is anything still importing them?\n - Version changes — any breaking changes or known CVEs?\n3. **DRY at the dependency level** — for any new external dependency added:\n - Search the existing codebase for similar functionality already provided by current dependencies\n - Check if the project already has a wrapper/abstraction for this kind of functionality\n - Determine if a small utility function would suffice instead of adding a full dependency\n4. **Check configuration changes** — env files, config files, build configs, CI/CD pipelines\n5. **Trace import chains** — for each changed file, map what it imports and what imports it\n - Are there existing shared modules that should be imported instead of duplicating logic?\n - Are imports organized consistently with the rest of the codebase?\n6. **Identify circular dependencies** — check for import cycles involving changed files\n\n### Secrets Scanning (CRITICAL)\n7. **Scan ALL changed files line-by-line** for secrets exposure:\n - **API keys** — patterns like `AKIA`, `sk-`, `sk_live_`, `pk_live_`, `ghp_`, `gho_`, `github_pat_`, `xoxb-`, `xoxp-`\n - **Tokens & passwords** — any string assigned to variables named `token`, `secret`, `password`, `passwd`, `api_key`, `apiKey`, `auth`, `credential`\n - **Connection strings** — database URIs (`mongodb://`, `postgres://`, `mysql://`, `redis://`), DSNs (`https://*.ingest.sentry.io`)\n - **Private keys** — `BEGIN RSA PRIVATE KEY`, `BEGIN OPENSSH PRIVATE KEY`, `BEGIN EC PRIVATE KEY`, `BEGIN PGP PRIVATE KEY`\n - **Cloud credentials** — AWS access keys, GCP service account JSON, Azure connection strings\n - **JWT secrets** — hardcoded JWT signing keys or HMAC secrets\n - **Webhook URLs** — Slack webhooks (`hooks.slack.com`), Discord webhooks, generic callback URLs with tokens in query params\n - **High-entropy strings** — any suspicious base64 or hex string longer than 32 characters assigned to a constant\n8. **Scan git history of changed files** — run `git log --diff-filter=D -p -- <file>` on changed files to check if secrets were added then removed (still in history)\n9. **Check .env and config files** — verify:\n - `.env` files are in `.gitignore`\n - `.env.example` or `.env.template` exists with placeholder values (not real secrets)\n - No `.env` files are tracked in git (`git ls-files '*.env'`)\n - Config files don't contain inline secrets\n10. **Check for secrets in logs** — scan changed code for logging statements that might output sensitive data:\n - `console.log`, `logger.info/debug/error`, `print`, `fmt.Println` statements that include tokens, passwords, headers, or request bodies\n - Error messages that might leak internal paths, stack traces, or credentials\n11. **Verify secrets management** — check if the project uses proper secrets management:\n - Environment variables for runtime secrets\n - Secret managers (AWS Secrets Manager, Vault, 1Password CLI)\n - Encrypted config files\n - `.gitignore` entries for sensitive files\n\n## Output: Secrets Report Section (REQUIRED)\n\n```\n### Secrets Scan Results\n\n**Status:** CLEAN / FINDINGS DETECTED\n\n| Severity | File | Line | Type | Detail |\n|----------|------|------|------|--------|\n| CRITICAL | path/file.ts | 15 | API Key | Hardcoded Stripe key `sk_live_...` |\n| HIGH | path/config.ts | 30 | Connection String | Postgres URI with embedded password |\n| MEDIUM | path/logger.ts | 45 | Log Leak | Auth header logged in debug mode |\n\n### .env / Gitignore Status\n- .env in .gitignore: YES/NO\n- .env.example exists: YES/NO\n- Tracked .env files: [list or NONE]\n\n### Secrets Management Assessment\n[How the project handles secrets — good practices and gaps]\n```\n\nReport ALL findings with file paths and line numbers. Secrets exposure is a blocking issue — never downplay it."
|
||
- agent: scout
|
||
prompt: "# Step 4: Test, Documentation & Best Practices Scout — Deep Research\n\nAnalyze test coverage, inline documentation quality, and best practices compliance for the code under review. Research the project's documentation standards before judging.\n\nUser request: $ORIGINAL\n\n## Tasks\n\n### Test Coverage\n1. **Identify the change scope** — run the appropriate git diff command based on the user's request and list all affected files\n2. **Find existing tests** for each changed file:\n - Co-located tests (same directory, .test.ts/.spec.ts pattern)\n - Test directory tests (tests/, __tests__/, spec/)\n - Integration tests that exercise the changed code\n3. **Assess test coverage gaps** — which changed functions/methods/components lack tests?\n4. **Check test quality** — are existing tests meaningful or just smoke tests?\n5. **Run existing tests** — execute the test suite and report:\n - Pass/fail status\n - Any tests that broke due to the changes\n - Test execution time\n6. **Identify test infrastructure** — test framework, test runners, fixtures, mocks, CI test config\n\n### Inline Documentation Audit\n7. **Study existing documentation patterns FIRST** — before judging the new code:\n - Read 3-5 well-documented files in the project to understand the documentation standard\n - Check for JSDoc/TSDoc/docstring conventions, ABOUTME headers, README patterns\n - Note the level of detail expected: are params documented? Return types? Examples? Exceptions?\n - Check for comment style: block comments for sections, inline for tricky logic, or minimal?\n8. **Audit changed files for documentation compliance:**\n - **Exported functions/methods** — do they have proper JSDoc/TSDoc with @param, @returns, @throws, @example?\n - **Exported types/interfaces** — are fields documented with /** */ comments explaining purpose and constraints?\n - **Exported classes** — do they have class-level documentation explaining purpose, usage, and lifecycle?\n - **Complex logic** — are non-obvious algorithms, workarounds, or business rules explained with inline comments?\n - **Magic numbers/strings** — are they documented or extracted to named constants?\n - **ABOUTME headers** — if the project uses them, do new files have them?\n - **Module-level documentation** — do new files explain their purpose at the top?\n9. **Flag under-documented code** — for each finding, show:\n - The function/type/class that needs documentation\n - What the documentation should cover\n - An example of good documentation from elsewhere in the project\n\n### Best Practices Compliance\n10. **Identify the stack** — detect language, framework, and runtime from manifest files\n11. **Check framework-specific best practices** — based on the detected stack:\n - **TypeScript** — strict mode compliance, proper type narrowing, no `any` abuse, discriminated unions, proper generics\n - **React** — hooks rules, proper key usage, memo boundaries, effect cleanup, controlled vs uncontrolled\n - **Node.js** — async best practices, stream handling, graceful shutdown, proper signal handling\n - **Express/Fastify** — middleware ordering, error middleware, request validation, response typing\n - **Next.js** — server vs client boundaries, proper data fetching, metadata, caching strategies\n - **Python** — PEP 8, type hints, context managers, proper exception hierarchy\n - **Go** — error wrapping, context propagation, goroutine lifecycle, defer patterns\n - **General** — SOLID principles, proper abstraction levels, separation of concerns, single responsibility\n12. **Check for common pitfalls** specific to the detected framework version\n13. **Search the web** for '{framework} best practices {year}' if needed to verify current recommendations\n\n## Output: Documentation & Best Practices Section (REQUIRED)\n\nYou MUST include these dedicated sections:\n\n```\n### Documentation Gaps\n\n| Location | What Needs Documentation | Example From Codebase |\n|----------|------------------------|----------------------|\n| path/file.ts:15 export function foo() | Missing JSDoc — needs @param, @returns | See path/other.ts:30 bar() for good example |\n| path/file.ts:45 interface Config | Fields undocumented | See path/types.ts:10 Options for good example |\n\n### Best Practices Violations\n\n| Location | Violation | Best Practice | Reference |\n|----------|-----------|--------------|----------|\n| path/file.ts:20 | Using `any` type | Use proper generics or unknown | TS strict mode guidelines |\n| path/file.ts:50 | useEffect missing cleanup | Return cleanup function for subscriptions | React hooks rules |\n```\n\nReport all findings with file paths, line numbers, and test output."
|
||
- agent: warden
|
||
prompt: "# Step 5: Context Synthesis\n\nYou are the synthesizer. Merge the findings from all four scouts into a unified context document that will drive the code review.\n\n## Scout Reports\n\n### Architecture Scout Report\n$INPUT_1\n\n### Pattern, Convention & DRY Scout Report\n$INPUT_2\n\n### Dependency & Configuration Scout Report\n$INPUT_3\n\n### Test, Documentation & Best Practices Scout Report\n$INPUT_4\n\n## Tasks\n\n1. **Consolidate the change scope** — produce a definitive list of files under review with their purpose\n2. **Build the review context** — for each file, summarize:\n - What it does and why it's changing\n - Architecture context (module, dependencies, consumers)\n - Pattern compliance status\n - Test coverage status\n - Documentation compliance status\n - DRY compliance status\n3. **Consolidate DRY violations** — merge the DRY findings from scouts 1, 2, and 3 into a single prioritized table. These are high-priority review items — new code that duplicates or fails to extend existing code.\n4. **Consolidate documentation gaps** — merge inline documentation findings into a single section showing what needs JSDoc/TSDoc/comments and the project's documentation standard.\n5. **Consolidate best practices violations** — merge framework-specific and language-specific best practice violations.\n6. **Flag high-risk areas** — files or changes that need extra scrutiny:\n - Security-sensitive code (auth, crypto, input handling)\n - Complex logic or algorithmic changes\n - Breaking changes to public APIs or interfaces\n - Configuration or infrastructure changes\n - DRY violations (new code that should extend existing code)\n7. **Identify quick wins** — obvious issues already surfaced by scouts\n8. **Produce a review priority map** — rank files by risk for the reviewers\n\n## Output Format\n\n```markdown\n## Code Review Context\n\n### Change Summary\n[Total files, lines added/removed, scope description]\n\n### Files Under Review (by priority)\n\n| Priority | File | Risk | Reason |\n|----------|------|------|--------|\n| 1 | path/to/file | High | [reason] |\n| ... | ... | ... | ... |\n\n### Per-File Context\n\n#### [filename]\n- **Purpose:** [what and why]\n- **Architecture:** [module, deps, consumers]\n- **Patterns:** [compliance status, violations found]\n- **Tests:** [coverage status, existing tests]\n- **Documentation:** [compliance status, gaps found]\n- **DRY:** [compliance status, violations found]\n- **Best Practices:** [compliance status, violations found]\n- **Risk factors:** [what to watch for]\n\n### DRY Violations (Consolidated)\n\n| New Code | Existing Code | Recommended Action |\n|----------|--------------|-------------------|\n| ... | ... | Extend/reuse instead of creating new |\n\n### Documentation Gaps (Consolidated)\n\n| Location | What Needs Documentation | Project Standard Reference |\n|----------|------------------------|---------------------------|\n| ... | ... | See [example file] for the expected style |\n\n### Best Practices Violations (Consolidated)\n\n| Location | Violation | Best Practice | Severity |\n|----------|-----------|--------------|----------|\n| ... | ... | ... | High/Medium/Low |\n\n### High-Risk Areas\n[Prioritized list with reasons]\n\n### Quick Wins\n[Issues already identified by scouts]\n```"
|
||
- agent: warden
|
||
prompt: "# Step 6: Code Quality Review\n\nPerform a thorough code quality review using the synthesized context. Pay special attention to DRY violations, documentation gaps, and best practices — the scouts have already identified these, and you must validate and enforce them.\n\n## Review Context\n$INPUT\n\n## Review Checklist\n\nFor each file under review, evaluate:\n\n### Correctness\n- Logic errors, off-by-one, wrong comparisons\n- Null/undefined handling — missing optional chaining, unchecked returns\n- Type safety — any casts, implicit conversions, missing generics\n- Edge cases — empty arrays, zero values, boundary conditions\n- Error handling — swallowed errors, missing catch, unhandled rejections\n- Race conditions — shared state, async ordering, concurrent access\n\n### Performance\n- N+1 queries, unbounded iterations\n- Missing memoization, redundant computation\n- Large allocations, memory leaks, unclosed resources\n- Blocking operations on hot paths\n\n### DRY Compliance (enforce the scouts' findings)\n- Validate every DRY violation from the synthesis — read both the new code and the existing code it should extend\n- New classes that should extend existing base classes — confirm the inheritance is feasible\n- New enums that should be values in existing enums — confirm the enum is the right place\n- New utility functions that duplicate existing helpers — confirm the existing helper covers the use case\n- Duplicated code blocks — confirm extraction is possible and beneficial\n- For each confirmed DRY violation, provide the specific refactoring: what to remove, what to extend, what to import\n\n### Documentation Quality (enforce the scouts' findings)\n- Validate every documentation gap from the synthesis\n- **Exported functions** — must have JSDoc/TSDoc with @param, @returns, @throws as appropriate\n- **Exported types/interfaces** — fields must have /** */ descriptions for non-obvious properties\n- **Exported classes** — must have class-level documentation with purpose and usage\n- **Complex logic** — must have inline comments explaining the 'why', not the 'what'\n- **Module headers** — new files must have a top-level comment or ABOUTME explaining the file's purpose\n- For each documentation finding, write the EXACT documentation that should be added (not just 'add docs' — write the actual JSDoc block)\n\n### Best Practices (enforce the scouts' findings)\n- Validate every best practices violation from the synthesis\n- Check framework-specific patterns are followed correctly\n- Verify SOLID principles, proper abstraction, separation of concerns\n- Check error handling follows the project's established pattern\n\n### Maintainability\n- Readability — clear naming, appropriate abstraction level\n- Complexity — cyclomatic complexity, deep nesting, long functions\n- Dead code — unused imports, unreachable branches, commented-out code\n\n### API Design\n- Breaking changes to public interfaces\n- Consistency with existing API patterns\n- Input validation at boundaries\n- Appropriate error types and messages\n\n## Output Format\n\nFor each finding:\n```\n### [QUAL-NNN] [Title]\n- **Severity:** Critical / High / Medium / Low\n- **File:** `path/to/file:line`\n- **Category:** Correctness / Performance / DRY / Documentation / Best Practices / Maintainability / API Design\n- **Description:** [What's wrong]\n- **Impact:** [What can go wrong]\n- **Suggested Fix:** [Specific code change, refactoring, or exact documentation to add]\n```\n\nGroup findings by severity. Include a summary count table at the top. DRY violations and missing documentation for exported APIs are at minimum Medium severity."
|
||
- agent: knight
|
||
prompt: "# Step 7: Security Review\n\nPerform a security-focused review of the code changes. Cross-reference with the secrets scan from the Dependency Scout.\n\n## Review Context\n$INPUT_5\n\n## Secrets Scan from Dependency Scout (Step 3)\nReview and validate the secrets findings from Step 3. The Dependency Scout already performed a thorough secrets scan — verify its findings and dig deeper.\n$INPUT_3\n\n## Security Review Checklist\n\nFor each file under review, evaluate:\n\n### Secrets & Credential Exposure (Cross-reference with Step 3)\n- Validate every secret finding from the Dependency Scout — confirm or dismiss\n- Dig deeper: check for obfuscated or encoded secrets the automated scan might have missed\n- Check git history for secrets that were committed then removed\n- Verify .env/.gitignore setup is airtight\n- Check for secrets leaking through error messages, stack traces, or debug output\n\n### Input Validation & Injection\n- SQL/NoSQL injection vectors\n- Command injection (exec, spawn, system calls)\n- Template injection (string interpolation in templates)\n- XSS vectors (unsanitized output, innerHTML, dangerouslySetInnerHTML)\n- Path traversal (user-controlled file paths)\n- Regex DoS (catastrophic backtracking)\n\n### Authentication & Authorization\n- Missing auth checks on endpoints or functions\n- Insecure token handling (storage, transmission, expiry)\n- Privilege escalation paths\n- IDOR (Insecure Direct Object Reference)\n- Session management issues\n\n### Data Protection\n- Sensitive data in logs — cross-reference with secrets scan log-leak findings\n- PII handling (storage, transmission, access control)\n- Insecure data storage (plaintext, localStorage for sensitive data)\n- Missing encryption for data at rest or in transit\n\n### Configuration & Infrastructure\n- CORS misconfiguration\n- Missing rate limiting\n- Insecure defaults\n- Missing security headers\n- Dependency vulnerabilities (run `npm audit` / equivalent if applicable)\n\n## Output Format\n\nFor each finding:\n```\n### [SEC-NNN] [Title]\n- **Severity:** Critical / High / Medium / Low\n- **File:** `path/to/file:line`\n- **Category:** Secrets / Injection / Auth / Data Protection / Configuration\n- **Description:** [What's vulnerable]\n- **Attack Vector:** [How it could be exploited]\n- **Impact:** [What an attacker could achieve]\n- **Remediation:** [Specific code fix]\n```\n\nGroup findings by severity. Include a summary count table at the top. Secrets findings are ALWAYS Critical or High — never downgrade them."
|
||
- agent: paladin
|
||
prompt: "# Step 8: First Remediation\n\nYou are the remediation agent. Apply fixes for the issues found in the code quality and security reviews.\n\n## Code Quality Findings\n$INPUT_6\n\n## Security Findings\n$INPUT_7\n\n## Instructions\n\n1. **Prioritize by severity** — fix Critical and High issues first, then Medium\n2. **Apply fixes directly** — edit the actual source files to resolve the issues\n3. **Follow existing patterns** — match the codebase's style, naming, and conventions\n4. **Be surgical** — make minimal, focused changes. Do not refactor beyond what's needed\n5. **Skip Low severity** — leave nitpicks and optional suggestions for the developer\n\n## Fix Categories (in priority order):\n\n### 1. Secrets Remediation (HIGHEST PRIORITY)\n- If any hardcoded secrets were found, IMMEDIATELY:\n - Replace the hardcoded value with an environment variable reference (e.g., `process.env.API_KEY`)\n - Add the variable name to `.env.example` with a placeholder value\n - Ensure `.env` is in `.gitignore`\n - Add a comment noting the secret should be rotated since it was exposed in source\n- **NEVER skip a secrets finding** — always remediate, even if the fix is just replacing with an env var\n\n### 2. DRY Violation Remediation\n- For each confirmed DRY violation:\n - Read BOTH the new code and the existing code it should extend\n - Refactor the new code to extend/import/reuse the existing code\n - If extending a class: make the new class extend the base class, call super(), override only what's different\n - If reusing a utility: replace the duplicated logic with a call to the existing function\n - If extending an enum: add new values to the existing enum instead of creating a new one\n - Remove the redundant new code after refactoring\n\n### 3. Documentation Remediation\n- Add the exact JSDoc/TSDoc blocks specified in the review findings\n- Add ABOUTME headers to new files that lack them\n- Add inline comments to complex logic blocks\n- Follow the documentation style established elsewhere in the project\n\n### 4. Best Practices Remediation\n- Apply framework-specific fixes (proper hooks usage, async patterns, error handling, etc.)\n- Fix type safety issues (remove `any`, add proper generics, add type guards)\n\n### 5. Correctness & Performance Fixes\n- Fix logic errors, null handling, edge cases\n- Fix performance issues (N+1, missing memoization, blocking calls)\n\n## For each fix:\n1. Read the file and understand the surrounding context\n2. Apply the fix with a focused edit\n3. Verify the fix doesn't break anything obvious\n4. Document what you changed and why\n\n## Output Format\n\nAfter applying all fixes, produce a remediation summary:\n\n```markdown\n## Remediation Summary\n\n### Fixes Applied\n\n| ID | Severity | Category | File | What Changed |\n|----|----------|----------|------|--------------|\n| SEC-001 | Critical | Secrets | path/to/file:line | Replaced hardcoded API key with env var |\n| QUAL-005 | High | DRY | path/to/file:line | Refactored to extend BaseClass |\n| QUAL-010 | Medium | Documentation | path/to/file:line | Added JSDoc to exported functions |\n| ... | ... | ... | ... | ... |\n\n### Fixes Skipped (with reason)\n\n| ID | Severity | Reason |\n|----|----------|--------|\n| ... | ... | [why it was skipped — needs human decision, too risky, etc.] |\n\n### Secrets Rotation Advisory\n[If any secrets were found in source, list them here with rotation instructions]\n\n### Changes Made\n\n[For each file modified, show what was changed and the reasoning]\n```\n\nBe thorough but conservative. When in doubt about correctness fixes, skip and explain. But NEVER skip secrets, DRY, or documentation fixes."
|
||
- agent: warden
|
||
prompt: "# Step 9: Validation Review (Devil's Advocate)\n\nYou are the validation reviewer. Your job is to challenge and verify the remediation that was just applied.\n\n## Original Request\n$ORIGINAL\n\n## Remediation Summary\n$INPUT\n\n## Your Mission\n\nBe skeptical. Assume the fixes might have introduced new problems. Check everything.\n\n### Verify Each Fix\nFor each fix that was applied:\n1. **Read the actual file** — do not trust the summary alone. Open the file and verify the change.\n2. **Check correctness** — does the fix actually resolve the original issue?\n3. **Check for regressions** — did the fix break anything else?\n4. **Check for incomplete fixes** — did it address the root cause or just a symptom?\n5. **Check the surrounding code** — did the fix create inconsistencies with nearby code?\n\n### Find What Was Missed\n1. **Review the skipped fixes** — should any of them have been applied?\n2. **Look for new issues** — did the remediation introduce new bugs, security holes, or style violations?\n3. **Check edge cases** — did the fixes handle all edge cases?\n4. **Verify the original findings** — were any of the original review findings false positives?\n\n### Challenge Severity Ratings\n- Were any Critical/High findings actually lower severity?\n- Were any Low/Medium findings actually higher severity?\n- Are there findings that should have been caught but weren't?\n\n## Output Format\n\n```markdown\n## Validation Review\n\n### Overall Assessment\n[APPROVED / NEEDS FURTHER CHANGES]\n[Brief summary of the remediation quality]\n\n### Fix Verification Results\n\n| ID | Fix Status | Verdict | Notes |\n|----|-----------|---------|-------|\n| QUAL-001 | Applied | Verified OK | [notes] |\n| SEC-003 | Applied | Has Issues | [what's wrong] |\n| ... | ... | ... | ... |\n\n### New Issues Found\n[Any issues introduced by the remediation]\n\n### Missed Issues\n[Issues that should have been caught or fixed]\n\n### Severity Adjustments\n[Any re-ratings with justification]\n\n### Recommendations\n[Final recommendations for the developer]\n```"
|
||
- agent: herald
|
||
prompt: "# Step 10: Test Verification & Remediation\n\nVerify that the codebase is in good shape after the code review remediation.\n\n## Validation Review Results\n$INPUT\n\n## Tasks\n\n1. **Run the full test suite** — execute all existing tests and report results\n - If tests pass: report the pass and move on\n - If tests fail: analyze the failure and determine if it was caused by the remediation fixes\n\n2. **Fix test failures caused by remediation** — if the remediation broke any tests:\n - Determine if the test needs updating (the fix changed correct behavior)\n - Or if the fix has a bug (the test was right, the fix was wrong)\n - Apply the appropriate correction\n\n3. **Check for missing test coverage** — based on the validation review:\n - If critical fixes were applied, write tests to prevent regression\n - Focus on the highest-severity fixes that lack test coverage\n - Write focused, minimal tests — not a full test suite rewrite\n\n4. **Run tests again** after any changes to confirm everything passes\n\n## Output Format\n\n```markdown\n## Test Verification Report\n\n### Initial Test Run\n- **Status:** All Pass / X Failures\n- **Total Tests:** [count]\n- **Duration:** [time]\n- **Output:** [relevant test output]\n\n### Test Failures Remediated\n\n| Test | Cause | Fix Applied |\n|------|-------|-------------|\n| test_name | Remediation changed behavior | Updated test expectation |\n| ... | ... | ... |\n\n### New Tests Added\n\n| Test File | Covers | Finding ID |\n|-----------|--------|------------|\n| path/to/test | [what it tests] | QUAL-001 |\n| ... | ... | ... |\n\n### Final Test Run\n- **Status:** All Pass / X Failures\n- **Total Tests:** [count]\n- **Output:** [relevant test output]\n\n### Notes\n[Any concerns, flaky tests, or coverage gaps remaining]\n```"
|
||
- agent: warden
|
||
prompt: "# Step 11: Final Consolidated Report\n\nProduce the final code review report consolidating all phases of the review.\n\n## Source Data\n\n### Context Synthesis (Step 5)\n$INPUT_5\n\n### Code Quality Review (Step 6)\n$INPUT_6\n\n### Security Review (Step 7)\n$INPUT_7\n\n### Remediation Summary (Step 8)\n$INPUT_8\n\n### Validation Review (Step 9)\n$INPUT_9\n\n### Test Verification (Step 10)\n$INPUT_10\n\n## Instructions\n\nProduce a comprehensive, well-structured code review report. This is the final deliverable. Include dedicated sections for DRY compliance, documentation quality, secrets status, and best practices — these are first-class review dimensions, not afterthoughts.\n\n## Output Format\n\n```markdown\n# Code Review Report\n\n**Date:** [current date]\n**Scope:** [what was reviewed — files, commit range, etc.]\n**Verdict:** APPROVED / APPROVED WITH NOTES / NEEDS CHANGES\n\n---\n\n## Executive Summary\n\n[2-3 paragraph summary: what was reviewed, key findings, what was fixed, what remains]\n\n## Findings Overview\n\n| Category | Found | Fixed | Remaining |\n|----------|-------|-------|-----------|\n| Secrets / Credentials | X | X | X |\n| Security (other) | X | X | X |\n| DRY Violations | X | X | X |\n| Documentation Gaps | X | X | X |\n| Best Practices | X | X | X |\n| Correctness | X | X | X |\n| Performance | X | X | X |\n| Maintainability | X | X | X |\n\n| Severity | Found | Fixed | Remaining |\n|----------|-------|-------|-----------|\n| Critical | X | X | X |\n| High | X | X | X |\n| Medium | X | X | X |\n| Low | X | X | X |\n\n## Secrets & Credentials Status\n\n**Status:** CLEAN / NEEDS ROTATION / EXPOSED\n\n[Summary of secrets scanning results. If any secrets were found:]\n- What was found and where\n- What was remediated (moved to env vars)\n- Which secrets need immediate rotation\n- .env/.gitignore status\n\n## DRY Compliance\n\n**Status:** COMPLIANT / VIOLATIONS FOUND\n\n[Summary of DRY analysis:]\n- New code that was refactored to extend existing code\n- Remaining DRY violations that need attention\n- Reusable components that were properly leveraged\n\n| New Code | Should Extend | Status |\n|----------|--------------|--------|\n| ... | ... | Fixed / Remaining |\n\n## Documentation Quality\n\n**Status:** COMPLIANT / GAPS FOUND\n\n[Summary of documentation audit:]\n- Project documentation standard (what the codebase expects)\n- Documentation that was added during remediation\n- Remaining gaps that need attention\n- Files/functions with exemplary documentation (for reference)\n\n## Best Practices Assessment\n\n**Stack:** [detected languages, frameworks]\n\n[Summary of best practices compliance:]\n- Framework-specific practices followed/violated\n- Language-specific practices followed/violated\n- Fixes applied and remaining violations\n\n## Security Assessment\n\n[Summary of non-secrets security findings, what was fixed, what remains]\n\n## Changes Applied\n\n### Files Modified During Remediation\n\n| File | Category | Changes | Verified |\n|------|----------|---------|----------|\n| path/to/file | Secrets | Moved API key to env var | Yes/No |\n| path/to/file | DRY | Extended BaseClass | Yes/No |\n| path/to/file | Docs | Added JSDoc to exports | Yes/No |\n| ... | ... | ... | ... |\n\n## Remaining Issues\n\n### Must Fix Before Merge\n[Critical/High issues that were not remediated — especially any remaining secrets exposure]\n\n### Should Fix Soon\n[Medium issues worth addressing]\n\n### Nice to Have\n[Low-priority improvements]\n\n## Test Status\n\n- **Tests Passing:** [count]\n- **Tests Added:** [count]\n- **Coverage Notes:** [any gaps]\n\n## Recommendations\n\n1. [Actionable recommendation]\n2. [Actionable recommendation]\n3. [Actionable recommendation]\n\n---\n\n*Generated by code-review agent chain*\n```\n\nBe thorough, accurate, and actionable. Cross-reference findings across all steps. Highlight anything the validation review flagged as problematic. Secrets findings ALWAYS appear prominently — never bury them."
|