AGENT INSTRUCTION: This is your primary instruction hub for developing, maintaining, and building the BrainRouter repository. You are the AI engineer building BrainRouter, not a client using its MCP server.
Audience: AI Coding Agents and Developers building BrainRouter.
- No MCP Tool Calling for Development: Since we are the ones building BrainRouter, do NOT attempt to invoke
mcp_brainrouter_*tools. Instead, perform all tasks locally using file system tools and local terminal commands. - Reference the
skills/Folder Directly: To maintain premium engineering workflow discipline, check theskills/folder directly using filesystem tools (view_file,grep_search). If a task matches a skill (e.g.,planning-skill,spec-driven-skill,debugging-and-error-recovery), read itsSKILL.mddirectly and follow its steps. - Incremental & Test-Driven: When working on BrainRouter packages, dashboard, CLI, or MCP servers, write/update tests first and run the local test suites to prevent regressions.
skills/: Universal skill workflows and markdown definitions (organized by category:agent,api,codebase,design,devops,lifecycle,memory,qa,ux).brainrouter-cli/: Node.js/TypeScript CLI interface for working with local session memories and skills.brainrouter/: Model Context Protocol (MCP) server implementations and tool definitions — the BrainRouter core (memory engine + tool registry). The recall pipeline lives insrc/memory/recall.tsand runs four stages: keyword/vector/filepath retrieval → reranker → optional LLM relevance judge → graph expansion.brainrouter-dashboard/: React/Vite/Next.js dashboard for visualizing cognitive graphs, recall histories, and memory states.packages/: Shared core utility libraries and modules.
When you are assigned a development task in this codebase, look up the scenario below and read the corresponding skill file directly from the filesystem:
Focus: Clarifying ambiguous requirements, creating specs, and defining tasks.
- planning-skill: Standard planning mode, tracking progress in
task.md. - spec-driven-skill: Creating specs under
brainrouter-docs/specs/before writing core code. - adr-skill: Creating ADRs under
brainrouter-docs/decisions/for major database or routing decisions.
Focus: Writing robust code, refactoring layers, and codebase cleanup.
- incremental-skill: Implementing features in small, vertical micro-slices.
- code-structure-cleanup: Cleaning structural entropy, removing dead code, and standardizing service layers.
- code-simplification: Refactoring complex routines for high comprehension speed.
- conventions-skill: Checking import order, type annotations, and naming style.
Focus: Running test runners, browser test cases, and error recovery.
- debugging-and-error-recovery: Systematic Reproduce → Localize → Fix → Guard debugging.
- testing-skill: Writing Vitest/Jest unit and integration tests.
- browser-testing-skill: Inspecting and testing dashboard UI.
Focus: Creating changelogs, preparing rollouts, and documenting changes.
- shipping-skill: Pre-flight checklist before finishing tasks.
- changelog-generator: Compiling structured release changelogs.
- handover-skill: Summarizing accomplishments in
walkthrough.md.
- Create a
task.mdchecklist in the workspace to track progress. - If the user request is ambiguous, draft a micro-specification file and get explicit user approval.
- Implement in small, verifiable steps.
- Run build scripts (
npm run buildor equivalent) and local tests after each significant change. - Write test cases for any new functionality added to
brainrouter-clior core packages.
- Run linting and formatting suites to keep codebase clean.
- Record all completed checklist items in
task.md. - Generate a structured summary of changes in
walkthrough.mdfor human review.