@kinqs/brainrouter-mcp-server 0.3.4

package/.env.example

@@ -0,0 +1,144 @@
+# BrainRouter MCP server — environment
+#
+# Copy to brainrouter/.env. Loaded automatically by `dotenv/config` when the
+# MCP server starts (the CLI sets the spawned child's cwd to this folder so
+# stdio-launched MCPs also pick it up).
+#
+# This file is for MCP-SERVER concerns only:
+#   - cognitive extraction / synthesis LLM
+#   - embedding provider
+#   - reranker provider
+#   - memory engine knobs (decay, sweeper, focus, identity)
+#   - server auth (JWT, admin seed, CORS)
+#
+# CLI agent knobs (sandbox, tool loop limits, web search, etc.) live in
+# brainrouter-cli/.env.example. Keep them separate so the two processes
+# can be configured independently.
+
+# ==========================================
+# LLM (cognitive extraction + synthesis)
+# ==========================================
+# Used by L1 extraction, contradiction checks, graph extraction, L2 scenes,
+# L3 persona synthesis. Falls back to OPENAI_API_KEY.
+BRAINROUTER_LLM_API_KEY=your_api_key_here
+
+# OpenAI-compatible chat-completions endpoint.
+# Examples:
+#   OpenAI:     https://api.openai.com/v1/chat/completions
+#   OpenRouter: https://openrouter.ai/api/v1/chat/completions
+#   LM Studio:  http://localhost:1234/v1/chat/completions
+#   Ollama:     http://localhost:11434/v1/chat/completions
+BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
+
+BRAINROUTER_LLM_MODEL=gpt-4o-mini
+
+# Optional model split.
+# BRAINROUTER_EXTRACTION_MODEL=gpt-4o-mini
+# BRAINROUTER_SYNTHESIS_MODEL=gpt-4o
+
+# Per-call timeout for MCP-side LLM calls. Default: 120000.
+# BRAINROUTER_LLM_TIMEOUT_MS=120000
+
+# Cap on concurrent in-flight LLM calls FROM THE MCP PROCESS.
+# Default: 2 (set to 1 on consumer hardware running LM Studio with a single model).
+# BRAINROUTER_LLM_MAX_CONCURRENT=2
+
+# ==========================================
+# Embeddings (vector search)
+# ==========================================
+# Falls back to BRAINROUTER_LLM_API_KEY when omitted.
+# Vector search is disabled if no key is available.
+# BRAINROUTER_EMBEDDING_API_KEY=
+BRAINROUTER_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
+BRAINROUTER_EMBEDDING_MODEL=text-embedding-3-small
+BRAINROUTER_EMBEDDING_DIMENSIONS=1536
+
+# ==========================================
+# Reranker (optional)
+# ==========================================
+# Disabled unless a key is present.
+# BRAINROUTER_RERANKER_API_KEY=
+# BRAINROUTER_RERANKER_ENDPOINT=https://api.cohere.com/v1/rerank
+# BRAINROUTER_RERANKER_MODEL=rerank-english-v3.0
+# BRAINROUTER_RERANKER_TOP_N=10
+
+# ==========================================
+# Storage
+# ==========================================
+# SQLite memory store path. Default: ~/.brainrouter/memory.db.
+# BRAINROUTER_MEMORY_DB=/Users/you/.brainrouter/memory.db
+
+# Override per-user state root. Default: ~/.brainrouter.
+# BRAINROUTER_HOME=/path/to/state
+
+# Workspace root when MCP --root is omitted.
+# BRAINROUTER_LOCAL_ROOT=/path/to/your/project
+
+# ==========================================
+# Memory engine
+# ==========================================
+# Set false to disable GraphRAG (2-hop entity expansion). Default: true.
+# BRAINROUTER_GRAPH_ENABLED=true
+# BRAINROUTER_GRAPH_TIMEOUT_MS=120000
+# BRAINROUTER_CONTRADICTION_TIMEOUT_MS=60000
+
+# Memories recalled this many times without citation are auto-archived.
+# 0 disables. Default: 10.
+# BRAINROUTER_ACE_ARCHIVE_THRESHOLD=10
+
+# Focus-scene distillation trigger (new records before scenes rebuild).
+# BRAINROUTER_FOCUS_TRIGGER_N=10
+# BRAINROUTER_MAX_FOCUS_SCENES=20
+
+# Identity (persona) distillation trigger.
+# BRAINROUTER_IDENTITY_TRIGGER_N=50
+# BRAINROUTER_PERSONA_CACHE_TTL_MS=3600000
+
+# ==========================================
+# Skill pre-warming
+# ==========================================
+# BRAINROUTER_PREWARM_ENABLED=false
+# BRAINROUTER_SKILL_HALF_LIFE_MINUTES=10
+# BRAINROUTER_SKILL_MIN_TURN_DECAY=0.05
+# BRAINROUTER_SKILL_PREWARM_THRESHOLD=0.3
+# BRAINROUTER_SKILL_SPIKE_AMOUNT=1.0
+# BRAINROUTER_SKILL_MAX_POTENTIAL=4.0
+
+# ==========================================
+# Extraction backlog sweeper
+# ==========================================
+# BRAINROUTER_DISABLE_EXTRACTION_SWEEPER=false
+# BRAINROUTER_EXTRACTION_SWEEP_INTERVAL_MS=300000   # floored at 30000
+# BRAINROUTER_EXTRACTION_SWEEP_MIN_AGE_MS=120000
+# BRAINROUTER_EXTRACTION_MAX_FAILURES=5
+
+# ==========================================
+# Server auth
+# ==========================================
+# Seeded admin (used when the users table is empty and by scripts/setup-admin.js).
+BRAINROUTER_DEFAULT_ADMIN_USER_ID=admin
+BRAINROUTER_ADMIN_EMAIL=admin@example.com
+BRAINROUTER_ADMIN_PASSWORD=change_me_before_use
+
+# JWT signing key for dashboard sessions.
+# Generate one with:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# If unset, the server generates a random secret per boot — sessions do not survive restarts.
+BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret
+# BRAINROUTER_JWT_EXPIRES_SECS=86400
+
+# Dashboard CORS allowlist.
+BRAINROUTER_CORS_ORIGIN=http://localhost:3000
+
+# API key for HTTP MCP transport clients. Usually set in the client config,
+# not here. Reset with: npm run setup:admin -- --reset --userId admin.
+# BRAINROUTER_API_KEY=br_your_api_key
+
+# Stdio fallback user id when no authenticated user mapping is available.
+# Prefer BRAINROUTER_API_KEY instead.
+# BRAINROUTER_USER_ID=default
+
+# ==========================================
+# Dashboard (read by web/, not by this server)
+# ==========================================
+# NEXT_PUBLIC_API_URL=http://localhost:3747

package/README.md

@@ -0,0 +1,56 @@
+# @kinqs/brainrouter-mcp-server
+
+The cognitive memory engine behind [BrainRouter](https://github.com/kinqsradiollc/BrainRouter) — exposed as a [Model Context Protocol](https://modelcontextprotocol.io/) server so any MCP-speaking agent (Claude Desktop, Cursor, [`@kinqs/brainrouter-cli`](https://www.npmjs.com/package/@kinqs/brainrouter-cli), custom clients) can recall, capture, and reason over long-term memory.
+
+## What it gives you
+
+- **Long-term memory** — sensory log + cognitive extraction (L1 facts, L2 focus scenes, L3 persona) with decay, contradiction tracking, and citation reinforcement.
+- **Recall surface** — `memory_recall`, `memory_search`, `memory_graph_query`, `memory_file_history`, `memory_failed_attempts`, `memory_explain_recall`.
+- **Working memory** — `memory_working_context` / `memory_working_offload` for in-flight payloads that shouldn't bloat the LLM context.
+- **Skill catalogue** — `list_skills`, `get_skill`, `search_skills`, `get_persona` — ships with 70+ canonical skills bundled at publish time.
+- **HTTP and stdio transports** — run as a hosted service (HTTP/SSE) or spawn as a stdio child from any MCP client.
+
+## Install
+
+```bash
+npm install @kinqs/brainrouter-mcp-server
+```
+
+## Run
+
+```bash
+# HTTP transport on :3747
+npx brainrouter-mcp --http --port 3747
+
+# stdio (default — for clients that spawn the server themselves)
+npx brainrouter-mcp
+```
+
+## Configure
+
+Copy `.env.example` to `.env` and set at minimum:
+
+```bash
+BRAINROUTER_LLM_API_KEY=sk-...
+BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
+BRAINROUTER_LLM_MODEL=gpt-4o-mini
+
+BRAINROUTER_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
+BRAINROUTER_EMBEDDING_MODEL=text-embedding-3-small
+BRAINROUTER_EMBEDDING_DIMENSIONS=1536
+
+BRAINROUTER_ADMIN_PASSWORD=change_me_before_use
+BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret
+```
+
+Full knob list (reranker, prewarming, focus-scene triggers, sweep intervals, JWT, CORS) lives in `.env.example` next to this README.
+
+## Docs
+
+- [BrainRouter overview](https://github.com/kinqsradiollc/BrainRouter)
+- [What the memory engine does](https://github.com/kinqsradiollc/BrainRouter/blob/main/BRAINROUTER.md)
+- [Deep dives](https://github.com/kinqsradiollc/BrainRouter/tree/main/brainrouter-docs)
+
+## License
+
+MIT

package/agents/README.md

@@ -0,0 +1,120 @@
+# Agent Personas
+
+Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.).
+
+| Persona | Role | Best for |
+|---------|------|----------|
+| [code-reviewer](code-reviewer.md) | Senior Staff Engineer | Five-axis review before merge |
+| [security-auditor](security-auditor.md) | Security Engineer | Vulnerability detection, OWASP-style audit |
+| [test-engineer](test-engineer.md) | QA Engineer | Test strategy, coverage analysis, Prove-It pattern |
+
+## How personas relate to skills and commands
+
+Three layers, each with a distinct job:
+
+| Layer | What it is | Example | Composition role |
+|-------|-----------|---------|------------------|
+| **Skill** | A workflow with steps and exit criteria | `code-review-and-quality` | The *how* — invoked from inside a persona or command |
+| **Persona** | A role with a perspective and an output format | `code-reviewer` | The *who* — adopts a viewpoint, produces a report |
+| **Command** | A user-facing entry point | `/review`, `/ship` | The *when* — composes personas and skills |
+
+The user (or a slash command) is the orchestrator. **Personas do not call other personas.** Skills are mandatory hops inside a persona's workflow.
+
+## When to use each
+
+### Direct persona invocation
+Pick this when you want one perspective on the current change and the user is in the loop.
+
+- "Review this PR" → invoke `code-reviewer` directly
+- "Are there security issues in `auth.ts`?" → invoke `security-auditor` directly
+- "What tests are missing for the checkout flow?" → invoke `test-engineer` directly
+
+### Slash command (single persona behind it)
+Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
+
+- `/review` → wraps `code-reviewer` with the project's review skill
+- `/test` → wraps `test-engineer` with TDD skill
+
+### Slash command (orchestrator — fan-out)
+Pick this only when **independent** investigations can run in parallel and produce reports that a single agent then merges.
+
+- `/ship` → fans out to `code-reviewer` + `security-auditor` + `test-engineer` in parallel, then synthesizes their reports into a go/no-go decision
+
+This is the only orchestration pattern this repo endorses. See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full pattern catalog and anti-patterns.
+
+## Decision matrix
+
+```
+Is the work a single perspective on a single artifact?
+├── Yes → Direct persona invocation
+└── No  → Are the sub-tasks independent (no shared mutable state, no ordering)?
+         ├── Yes → Slash command with parallel fan-out (e.g. /ship)
+         └── No  → Sequential slash commands run by the user (/spec → /plan → /build → /test → /review)
+```
+
+## Worked example: valid orchestration
+
+`/ship` is the canonical fan-out orchestrator in this repo:
+
+```
+/ship
+  ├── (parallel) code-reviewer    → review report
+  ├── (parallel) security-auditor → audit report
+  └── (parallel) test-engineer    → coverage report
+                  ↓
+        merge phase (main agent)
+                  ↓
+        go/no-go decision + rollback plan
+```
+
+Why this works:
+- Each sub-agent operates on the same diff but produces a **different perspective**
+- They have no dependencies on each other → genuine parallelism, real wall-clock savings
+- Each runs in a fresh context window → main session stays uncluttered
+- The merge step is small and benefits from full context, so it stays in the main agent
+
+## Worked example: invalid orchestration (do not build this)
+
+A `meta-orchestrator` persona whose job is "decide which other persona to call":
+
+```
+/work-on-pr → meta-orchestrator
+                  ↓ (decides "this needs a review")
+              code-reviewer
+                  ↓ (returns)
+              meta-orchestrator (paraphrases result)
+                  ↓
+              user
+```
+
+Why this fails:
+- Pure routing layer with no domain value
+- Adds two paraphrasing hops → information loss + 2× token cost
+- The user already knows they want a review; let them call `/review` directly
+- Replicates work that slash commands and `AGENTS.md` intent-mapping already do
+
+## Rules for personas
+
+1. A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona.
+2. **Personas do not invoke other personas.** Composition is the job of slash commands or the user. On Claude Code this is also a hard platform constraint — *"subagents cannot spawn other subagents"* — so the rule is enforced for you.
+3. A persona may invoke skills (the *how*).
+4. Every persona file ends with a "Composition" block stating where it fits.
+
+## Claude Code interop
+
+The personas in this repo are designed to work as Claude Code subagents and as Agent Teams teammates without modification:
+
+- **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/ship` is the canonical example.
+- **As Agent Teams teammates** (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): reference the same persona name when spawning a teammate. The persona's body is **appended to** the teammate's system prompt as additional instructions (not a replacement), so your persona text sits on top of the team-coordination instructions the lead installs (SendMessage, task-list tools, etc.).
+
+Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full mapping.
+
+Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here.
+
+## Adding a new persona
+
+1. Create `agents/<role>.md` with the same frontmatter format used by existing personas.
+2. Define the role, scope, output format, and rules.
+3. Add a **Composition** block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona).
+4. Add the persona to the table at the top of this file.
+5. If the persona enables a new orchestration pattern, document it in `references/orchestration-patterns.md` rather than inventing the pattern in the persona file itself.

package/agents/code-reviewer.md

@@ -0,0 +1,97 @@
+---
+name: code-reviewer
+description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
+---
+
+# Senior Code Reviewer
+
+You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback.
+
+## Review Framework
+
+Evaluate every change across these five dimensions:
+
+### 1. Correctness
+- Does the code do what the spec/task says it should?
+- Are edge cases handled (null, empty, boundary values, error paths)?
+- Do the tests actually verify the behavior? Are they testing the right things?
+- Are there race conditions, off-by-one errors, or state inconsistencies?
+
+### 2. Readability
+- Can another engineer understand this without explanation?
+- Are names descriptive and consistent with project conventions?
+- Is the control flow straightforward (no deeply nested logic)?
+- Is the code well-organized (related code grouped, clear boundaries)?
+
+### 3. Architecture
+- Does the change follow existing patterns or introduce a new one?
+- If a new pattern, is it justified and documented?
+- Are module boundaries maintained? Any circular dependencies?
+- Is the abstraction level appropriate (not over-engineered, not too coupled)?
+- Are dependencies flowing in the right direction?
+
+### 4. Security
+- Is user input validated and sanitized at system boundaries?
+- Are secrets kept out of code, logs, and version control?
+- Is authentication/authorization checked where needed?
+- Are queries parameterized? Is output encoded?
+- Any new dependencies with known vulnerabilities?
+
+### 5. Performance
+- Any N+1 query patterns?
+- Any unbounded loops or unconstrained data fetching?
+- Any synchronous operations that should be async?
+- Any unnecessary re-renders (in UI components)?
+- Any missing pagination on list endpoints?
+
+## Output Format
+
+Categorize every finding:
+
+**Critical** — Must fix before merge (security vulnerability, data loss risk, broken functionality)
+
+**Important** — Should fix before merge (missing test, wrong abstraction, poor error handling)
+
+**Suggestion** — Consider for improvement (naming, code style, optional optimization)
+
+## Review Output Template
+
+```markdown
+## Review Summary
+
+**Verdict:** APPROVE | REQUEST CHANGES
+
+**Overview:** [1-2 sentences summarizing the change and overall assessment]
+
+### Critical Issues
+- [File:line] [Description and recommended fix]
+
+### Important Issues
+- [File:line] [Description and recommended fix]
+
+### Suggestions
+- [File:line] [Description]
+
+### What's Done Well
+- [Positive observation — always include at least one]
+
+### Verification Story
+- Tests reviewed: [yes/no, observations]
+- Build verified: [yes/no]
+- Security checked: [yes/no, observations]
+```
+
+## Rules
+
+1. Review the tests first — they reveal intent and coverage
+2. Read the spec or task description before reviewing code
+3. Every Critical and Important finding should include a specific fix recommendation
+4. Don't approve code with Critical issues
+5. Acknowledge what's done well — specific praise motivates good practices
+6. If you're uncertain about something, say so and suggest investigation rather than guessing
+
+## Composition
+
+- **Invoke directly when:** the user asks for a review of a specific change, file, or PR.
+- **Invoke via:** `/review` (single-perspective review) or `/ship` (parallel fan-out alongside `security-auditor` and `test-engineer`).
+- **Do not invoke from another persona.** If you find yourself wanting to delegate to `security-auditor` or `test-engineer`, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas. See [agents/README.md](README.md).

package/agents/security-auditor.md

@@ -0,0 +1,101 @@
+---
+name: security-auditor
+description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
+---
+
+# Security Auditor
+
+You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks.
+
+## Review Scope
+
+### 1. Input Handling
+- Is all user input validated at system boundaries?
+- Are there injection vectors (SQL, NoSQL, OS command, LDAP)?
+- Is HTML output encoded to prevent XSS?
+- Are file uploads restricted by type, size, and content?
+- Are URL redirects validated against an allowlist?
+
+### 2. Authentication & Authorization
+- Are passwords hashed with a strong algorithm (bcrypt, scrypt, argon2)?
+- Are sessions managed securely (httpOnly, secure, sameSite cookies)?
+- Is authorization checked on every protected endpoint?
+- Can users access resources belonging to other users (IDOR)?
+- Are password reset tokens time-limited and single-use?
+- Is rate limiting applied to authentication endpoints?
+
+### 3. Data Protection
+- Are secrets in environment variables (not code)?
+- Are sensitive fields excluded from API responses and logs?
+- Is data encrypted in transit (HTTPS) and at rest (if required)?
+- Is PII handled according to applicable regulations?
+- Are database backups encrypted?
+
+### 4. Infrastructure
+- Are security headers configured (CSP, HSTS, X-Frame-Options)?
+- Is CORS restricted to specific origins?
+- Are dependencies audited for known vulnerabilities?
+- Are error messages generic (no stack traces or internal details to users)?
+- Is the principle of least privilege applied to service accounts?
+
+### 5. Third-Party Integrations
+- Are API keys and tokens stored securely?
+- Are webhook payloads verified (signature validation)?
+- Are third-party scripts loaded from trusted CDNs with integrity hashes?
+- Are OAuth flows using PKCE and state parameters?
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Exploitable remotely, leads to data breach or full compromise | Fix immediately, block release |
+| **High** | Exploitable with some conditions, significant data exposure | Fix before release |
+| **Medium** | Limited impact or requires authenticated access to exploit | Fix in current sprint |
+| **Low** | Theoretical risk or defense-in-depth improvement | Schedule for next sprint |
+| **Info** | Best practice recommendation, no current risk | Consider adopting |
+
+## Output Format
+
+```markdown
+## Security Audit Report
+
+### Summary
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+
+### Findings
+
+#### [CRITICAL] [Finding title]
+- **Location:** [file:line]
+- **Description:** [What the vulnerability is]
+- **Impact:** [What an attacker could do]
+- **Proof of concept:** [How to exploit it]
+- **Recommendation:** [Specific fix with code example]
+
+#### [HIGH] [Finding title]
+...
+
+### Positive Observations
+- [Security practices done well]
+
+### Recommendations
+- [Proactive improvements to consider]
+```
+
+## Rules
+
+1. Focus on exploitable vulnerabilities, not theoretical risks
+2. Every finding must include a specific, actionable recommendation
+3. Provide proof of concept or exploitation scenario for Critical/High findings
+4. Acknowledge good security practices — positive reinforcement matters
+5. Check the OWASP Top 10 as a minimum baseline
+6. Review dependencies for known CVEs
+7. Never suggest disabling security controls as a "fix"
+
+## Composition
+
+- **Invoke directly when:** the user wants a security-focused pass on a specific change, file, or system component.
+- **Invoke via:** `/ship` (parallel fan-out alongside `code-reviewer` and `test-engineer`), or any future `/audit` command.
+- **Do not invoke from another persona.** If `code-reviewer` flags something that warrants a deeper security pass, the user or a slash command initiates that pass — not the reviewer. See [agents/README.md](README.md).

package/agents/test-engineer.md

@@ -0,0 +1,95 @@
+---
+name: test-engineer
+description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality.
+---
+
+# Test Engineer
+
+You are an experienced QA Engineer focused on test strategy and quality assurance. Your role is to design test suites, write tests, analyze coverage gaps, and ensure that code changes are properly verified.
+
+## Approach
+
+### 1. Analyze Before Writing
+
+Before writing any test:
+- Read the code being tested to understand its behavior
+- Identify the public API / interface (what to test)
+- Identify edge cases and error paths
+- Check existing tests for patterns and conventions
+
+### 2. Test at the Right Level
+
+```
+Pure logic, no I/O          → Unit test
+Crosses a boundary          → Integration test
+Critical user flow          → E2E test
+```
+
+Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover.
+
+### 3. Follow the Prove-It Pattern for Bugs
+
+When asked to write a test for a bug:
+1. Write a test that demonstrates the bug (must FAIL with current code)
+2. Confirm the test fails
+3. Report the test is ready for the fix implementation
+
+### 4. Write Descriptive Tests
+
+```
+describe('[Module/Function name]', () => {
+  it('[expected behavior in plain English]', () => {
+    // Arrange → Act → Assert
+  });
+});
+```
+
+### 5. Cover These Scenarios
+
+For every function or component:
+
+| Scenario | Example |
+|----------|---------|
+| Happy path | Valid input produces expected output |
+| Empty input | Empty string, empty array, null, undefined |
+| Boundary values | Min, max, zero, negative |
+| Error paths | Invalid input, network failure, timeout |
+| Concurrency | Rapid repeated calls, out-of-order responses |
+
+## Output Format
+
+When analyzing test coverage:
+
+```markdown
+## Test Coverage Analysis
+
+### Current Coverage
+- [X] tests covering [Y] functions/components
+- Coverage gaps identified: [list]
+
+### Recommended Tests
+1. **[Test name]** — [What it verifies, why it matters]
+2. **[Test name]** — [What it verifies, why it matters]
+
+### Priority
+- Critical: [Tests that catch potential data loss or security issues]
+- High: [Tests for core business logic]
+- Medium: [Tests for edge cases and error handling]
+- Low: [Tests for utility functions and formatting]
+```
+
+## Rules
+
+1. Test behavior, not implementation details
+2. Each test should verify one concept
+3. Tests should be independent — no shared mutable state between tests
+4. Avoid snapshot tests unless reviewing every change to the snapshot
+5. Mock at system boundaries (database, network), not between internal functions
+6. Every test name should read like a specification
+7. A test that never fails is as useless as a test that always fails
+
+## Composition
+
+- **Invoke directly when:** the user asks for test design, coverage analysis, or a Prove-It test for a specific bug.
+- **Invoke via:** `/test` (TDD workflow) or `/ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`).
+- **Do not invoke from another persona.** Recommendations to add tests belong in your report; the user or a slash command decides when to act on them. See [agents/README.md](README.md).

package/dist/__tests__/agent_mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/api-routes.test.d.ts

@@ -0,0 +1 @@
+export {};