@kinqs/brainrouter-mcp-server 0.3.4

package/skills/agent/skill-authoring/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: skill-authoring
+description: Defines the canonical structure, format, and writing principles for BrainRouter SKILL.md files. Use when creating a new skill, reviewing an existing skill for compliance, or understanding what sections a skill must contain.
+hints:
+  - Keep skills project-agnostic, professional, and targeted at engineers or VibeCoders.
+  - Standardize frontmatter name to match folder basename exactly.
+  - Exclude custom branding, metadata keys, or trailing placeholders (like [trigger condition]).
+  - Write high-rebuttal anti-rationalizations and actionable verification checklists.
+  - Structure all supporting reference or template files under subfolders (e.g. templates/, scripts/).
+---
+
+# Skill Anatomy
+
+This document describes the structure and format of agent-skills skill files. Use this as a guide when contributing new skills or understanding existing ones.
+
+## File Location
+
+Skills live in the following directory structure depending on their scope:
+
+- **Universal Skills**: `skills/<category>/<skill-name>/SKILL.md`
+- **Project-Specific Skills**: `projects/<project-name>/skills/<category>/<skill-name>/SKILL.md`
+
+In the global MCP repository (BrainRouter), both folders are used to organize universal and project-level knowledge. In a local project repository, skills are typically stored in the `skills/` directory.
+
+```
+[root]/
+  skills/
+    api/
+      auth-skill/
+        SKILL.md
+  projects/
+    YourProject/
+      skills/
+        api/
+          storage-skill/
+            SKILL.md
+```
+
+`SKILL.md` is the only required file. You can also include a `scripts/` directory for runnable helpers or additional supporting markdown files.
+
+## SKILL.md Format
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: skill-name-with-hyphens
+description: Guides agents through [task/workflow]. Use when [specific trigger conditions].
+hints: |
+  - Always execute step A before step B.
+  - Assert that all tests pass before completing.
+---
+```
+
+**Rules:**
+- `name`: Lowercase, hyphen-separated. Must match the directory name.
+- `description`: Start with what the skill does in third person, then include one or more clear "Use when" trigger conditions. Include both *what* and *when*. Maximum 1024 characters.
+- `hints`: (Recommended for L2 Pre-warming) A concise, bulleted list of essential instructions that should be injected into the LLM system prompt context when this skill is pre-warmed. Keep this under 5-6 bullet points (approx. 300 characters) to optimize token consumption.
+
+**Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.
+
+The `hints` field is parsed by BrainRouter's L2 pre-warming engine. When the skill's activation potential is spiked, these hints are automatically injected into the LLM prompt context to keep the model primed with core rules.
+
+### Standard Sections (Recommended Pattern)
+
+The frontmatter contract above is required. The section layout below is a recommended pattern, not a rigid template: equivalent headings are acceptable when they serve the same purpose clearly.
+
+```markdown
+# Skill Title
+
+## Overview
+One-two sentences explaining what this skill does and why it matters.
+
+## When to Use
+- Bullet list of triggering conditions (symptoms, task types)
+- When NOT to use (exclusions)
+
+## [Core Process / The Workflow / Steps]
+The main workflow, broken into numbered steps or phases.
+Include code examples where they help.
+Use flowcharts (ASCII) where decision points exist.
+
+## [Specific Techniques / Patterns]
+Detailed guidance for specific scenarios.
+Code examples, templates, configuration.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| Excuse agents use to skip steps | Why the excuse is wrong |
+
+## Red Flags
+- Behavioral patterns indicating the skill is being violated
+- Things to watch for during review
+
+## Verification
+After completing the skill's process, confirm:
+- [ ] Checklist of exit criteria
+- [ ] Evidence requirements
+```
+
+## Section Purposes
+
+### Overview
+The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it?
+
+### When to Use
+Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y").
+
+### Core Process
+The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice.
+
+**Good:** "Run `npm test` and verify all tests pass"
+**Bad:** "Make sure the tests work"
+
+### Common Rationalizations
+The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process.
+
+Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument.
+
+### Red Flags
+Observable signs that the skill is being violated. Useful during code review and self-monitoring.
+
+### Verification
+The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.).
+
+## Supporting Files
+
+Create supporting files only when:
+- Reference material exceeds 100 lines (keep the main SKILL.md focused)
+- Code tools or scripts are needed
+- Checklists are long enough to justify separate files
+
+Keep patterns and principles inline when under 50 lines.
+
+If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works.
+
+## Writing Principles
+
+1. **Process over knowledge.** Skills are workflows, not reference docs. Steps, not facts.
+2. **Specific over general.** "Run `npm test`" beats "verify the tests".
+3. **Evidence over assumption.** Every verification checkbox requires proof.
+4. **Anti-rationalization.** Every skip-worthy step needs a counter-argument in the rationalizations table.
+5. **Progressive disclosure.** Main SKILL.md is the entry point. Supporting files are loaded only when needed.
+6. **Token-conscious.** Every section must justify its inclusion. If removing it wouldn't change agent behavior, remove it.
+
+## L2 Skill Pre-Warming & SNN Routing
+
+BrainRouter implements a Spiking Neural Network (SNN) model to dynamically pre-warm skills. This mechanism keeps relevant skills active in the agent's prompt context without blowing up the token window:
+1. **Spikes**: Invoking a skill or querying memories related to it spikes its activation potential by `+1.0` (up to a maximum cap of `4.0`).
+2. **Decay**: The potential decays exponentially over idle turns and time ($Potential_{new} = Potential_{old} \times e^{-\lambda \Delta t}$).
+3. **Threshold Gate**: If a skill's potential is `>= 0.3`, it crosses the gate and is considered "active."
+4. **Context Injection**: Active skills automatically have their `hints` frontmatter or registered memory hints injected into the LLM system prompt context under the `<skill-prewarm>` block.
+
+When writing or updating skills, authors should:
+- Ensure that the frontmatter `hints` are present, concise, and target specific error prevention or structural patterns.
+- Register newly-added dynamic skill hints by invoking `mcp_brainrouter_memory_register_skill_hints` if the skill relies on user-customized memory overrides.
+
+## Naming Conventions
+
+- Skill directories: `lowercase-hyphen-separated`
+- Skill files: `SKILL.md` (always uppercase)
+- Supporting files: `lowercase-hyphen-separated.md`
+- References: stored in `references/` at the project root, not inside skill directories
+
+## Cross-Skill References
+
+Reference other skills by name:
+
+```markdown
+Follow the `test-driven-development` skill for writing tests.
+If the build breaks, use the `debugging-and-error-recovery` skill.
+```
+
+Don't duplicate content between skills — reference and link instead.
+
+## Required vs Recommended
+
+Required:
+
+- A `skills/<skill-name>/SKILL.md` file
+- Valid YAML frontmatter with `name` and `description`
+- A description that includes both what the skill does and when to use it
+
+Recommended:
+
+- The standard section flow shown above
+- Equivalent headings such as `How It Works`, `Core Process`, or `Workflow` when they read more naturally for the skill
+- Supporting files only when they keep the main `SKILL.md` focused

package/skills/agent/source-driven-skill/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: source-driven-skill
+description: Grounds every implementation decision in official documentation or local source code. Use when building with any framework, library, or SDK where correctness matters. Use when an agent is likely to hallucinate API names, or when docs are weak and the library source is available locally.
+hints: |
+  - Read package.json (or equivalent) to detect exact versions before fetching docs.
+  - Fetch the specific doc page for the feature — not the homepage, not the full docs.
+  - If an openSrc/ directory is present in the workspace, inspect its contents for reference implementations before writing code.
+  - Cite every framework-specific decision with a full URL in code comments.
+  - Flag anything that could not be verified as UNVERIFIED — never silently guess.
+---
+
+# Source-Driven Development
+
+## Overview
+
+Every framework-specific code decision must be backed by an authoritative source — either official documentation or the library's local source code. Training data goes stale, APIs get deprecated, and best practices evolve. This skill ensures every pattern traces back to a source the user can check, eliminating hallucinated APIs and broken deprecated patterns.
+
+## When to Use
+
+- Building with any framework, library, or SDK where the API surface matters.
+- The agent is about to write framework-specific code from memory.
+- Docs are weak, stale, or incomplete — but the library's source is available on disk.
+- Building boilerplate or patterns that will be copied across the project.
+- Reviewing code that uses framework-specific patterns.
+
+**When NOT to use:**
+- Pure logic that works the same across all versions (loops, conditionals, data structures).
+- Renaming variables, fixing typos, or moving files — correctness is not version-dependent.
+- The user explicitly wants speed over verification ("just do it quickly").
+
+## The Process
+
+```
+DETECT ──→ SOURCE ──→ IMPLEMENT ──→ CITE
+  │           │            │           │
+  ▼           ▼            ▼           ▼
+ Stack &    Fetch docs  Follow the  Show your
+ versions   or search   documented  sources
+            local repo  patterns
+```
+
+### Step 1: Detect Stack and Versions
+
+Read the project's dependency file to identify exact versions:
+
+```
+package.json            → Node / React / Vue / Angular / Svelte
+composer.json           → PHP / Symfony / Laravel
+requirements.txt        → Python / Django / Flask
+go.mod                  → Go
+Cargo.toml              → Rust
+Gemfile                 → Ruby / Rails
+```
+
+State what you found explicitly before doing anything else:
+
+```
+STACK DETECTED:
+- React 19.1.0 (from package.json)
+- Vite 6.2.0
+→ Fetching official docs for the relevant patterns.
+```
+
+If versions are missing or ambiguous, **ask the user**. The version determines which patterns are correct.
+
+### Step 2: Get the Source
+
+#### Option A — Official Documentation (default)
+
+Fetch the **specific documentation page** for the feature being implemented. Not the homepage. Not the full docs.
+
+**Source hierarchy (in order of authority):**
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 | Official documentation | react.dev, docs.djangoproject.com |
+| 2 | Official blog / changelog | react.dev/blog, nextjs.org/blog |
+| 3 | Web standards references | MDN, web.dev |
+| 4 | Browser/runtime compatibility | caniuse.com, node.green |
+
+**Never cite as primary sources:** Stack Overflow, blog posts, tutorials, AI-generated summaries, or training data.
+
+```
+BAD:  Fetch the React homepage
+GOOD: Fetch react.dev/reference/react/useActionState
+
+BAD:  Search "django authentication best practices"
+GOOD: Fetch docs.djangoproject.com/en/6.0/topics/auth/
+```
+
+#### Option B — Local Source & Open Source References (when docs are weak or missing)
+
+If reference repositories or libraries are available locally in the workspace (for example, in an `openSrc/` folder or a `reference/repos/` folder), search them directly. This is the most current and practical source possible to discover working API usage patterns and connection/error-handling structures.
+
+**Setup / Discovery:**
+1. Check if an `openSrc/` folder exists at the workspace root. If present, list its directories to see what reference repositories (such as `claude-code`, `agentmemory`, `openai-node`, etc.) are available.
+2. Place or look for local reference repos under: `openSrc/` or `reference/repos/github.com/company/project`
+3. Add a note to your `AGENT.md` or `CLAUDE.md`:
+
+```md
+When working with <library/tool>, reference the local open-source repos under:
+`openSrc/<repo-name>` or `reference/repos/<repo-name>`.
+Do not guess API signatures. Search the source first, then implement.
+```
+
+**Feature prompt template / workflow:**
+
+```md
+Build <feature>. We use <library/tool>.
+
+Before coding:
+1. If available, search the `openSrc/` directory or `reference/repos/` for reference implementation examples of this library.
+2. Identify the specific files/functions/patterns you are using as a model.
+3. Implement only the minimal service function and one calling component.
+4. Keep the diff small and clean.
+5. Explain which reference source files you inspected.
+```
+
+### Step 3: Implement Following the Source
+
+- Use the API signatures from the source, not from memory.
+- If the source shows a new way to do something, use the new way.
+- If the source marks something as deprecated, don't use it.
+- If the source doesn't cover something, flag it as unverified.
+
+**When source conflicts with existing project code:**
+
+```
+CONFLICT DETECTED:
+The existing codebase uses useState for form loading state,
+but React 19 docs recommend useActionState for this pattern.
+Source: react.dev/reference/react/useActionState
+
+Options:
+A) Use the modern pattern (useActionState) — consistent with current docs
+B) Match existing code (useState) — consistent with codebase
+→ Which approach do you prefer?
+```
+
+Surface the conflict. Don't silently pick one.
+
+### Step 4: Cite Your Sources
+
+Every framework-specific decision gets a citation — in code and in conversation.
+
+**In code comments:**
+
+```typescript
+// React 19 form handling with useActionState
+// Source: https://react.dev/reference/react/useActionState#usage
+const [state, formAction, isPending] = useActionState(submitOrder, initialState);
+```
+
+**Citation rules:**
+- Full URLs — not shortened
+- Deep links with anchors preferred (e.g. `/useActionState#usage`)
+- Quote the relevant passage for non-obvious decisions
+- If you cannot find documentation, say so explicitly:
+
+```
+UNVERIFIED: I could not find official documentation for this pattern.
+This is based on training data and may be outdated. Verify before using in production.
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'm confident about this API" | Confidence is not evidence. Training data contains outdated patterns that look correct but break against current versions. Verify. |
+| "Fetching docs wastes tokens" | Hallucinating an API wastes more. One fetch prevents hours of debugging a wrong function signature. |
+| "The docs won't have what I need" | If the docs don't cover it, that's valuable signal — the pattern may not be officially recommended. Check local source next. |
+| "I'll just mention it might be outdated" | A disclaimer doesn't help. Either verify and cite, or clearly flag it as UNVERIFIED. Hedging is the worst option. |
+| "This is a simple task, no need to check" | Simple tasks with wrong patterns become templates. The user copies your deprecated form handler into ten components before discovering the modern approach. |
+| "I can't find the API so I'll add a new dependency" | Search the local source first. The API may exist and simply be undocumented. |
+
+## Red Flags
+
+- Writing framework-specific code without checking docs or local source for that version.
+- Using "I believe" or "I think" about an API instead of citing the source.
+- Citing Stack Overflow or blog posts as primary sources.
+- Using deprecated APIs because they appear in training data.
+- Not reading `package.json` (or equivalent) before implementing.
+- Delivering code without citations for framework-specific decisions.
+- Installing an alternative package because the agent couldn't find the existing API.
+
+## Verification
+
+After implementing with source-driven development, confirm:
+
+- [ ] Framework and library versions were identified from the dependency file.
+- [ ] Official documentation or local source was consulted for framework-specific patterns.
+- [ ] All citations are official sources — not blog posts or training data.
+- [ ] Code follows the patterns shown in the current version's documentation.
+- [ ] Non-trivial decisions include source citations with full URLs.
+- [ ] No deprecated APIs are used (checked against migration guides).
+- [ ] Conflicts between source and existing code were surfaced to the user.
+- [ ] Anything that could not be verified is explicitly flagged as UNVERIFIED.

package/skills/agent/spec-driven-skill/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: spec-driven-skill
+description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.
+hints:
+  - Never write code for a new feature or major refactoring without a written specification.
+  - Review openSrc/ templates or existing specs in docs/specs/ if they exist to reuse standard structures.
+  - Define explicit, testable Definition of Done (DoD) criteria in every specification.
+  - Establish boundary conditions (Always, Ask First, Never) to govern agent behaviors.
+  - Commit the spec as a living markdown file in the repository (e.g. docs/specs/) before implementing.
+---
+
+# Spec-Driven Development
+
+## Overview
+
+Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
+
+## When to Use
+
+- Starting a new project or feature
+- Requirements are ambiguous or incomplete
+- The change touches multiple files or modules
+- You're about to make an architectural decision
+- The task would take more than 30 minutes to implement
+
+**When NOT to use:** Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
+
+## The Gated Workflow
+
+Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
+
+```
+SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
+   │          │        │          │
+   ▼          ▼        ▼          ▼
+ Human      Human    Human      Human
+ reviews    reviews  reviews    reviews
+```
+
+### Phase 1: Specify
+
+Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.
+
+**Surface assumptions immediately.** Before writing any spec content, list what you're assuming:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. This is a web application (not native mobile)
+2. Authentication uses session-based cookies (not JWT)
+3. The database is PostgreSQL (based on existing Prisma schema)
+4. We're targeting modern browsers only (no IE11)
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding.
+
+**Write a spec document covering these six core areas:**
+
+1. **Objective** — What are we building and why? Who is the user? What does success look like?
+
+2. **Commands** — Full executable commands with flags, not just tool names.
+   ```
+   Build: npm run build
+   Test: npm test -- --coverage
+   Lint: npm run lint --fix
+   Dev: npm run dev
+   ```
+
+3. **Project Structure** — Where source code lives, where tests go, where docs belong.
+   ```
+   src/           → Application source code
+   src/components → React components
+   src/lib        → Shared utilities
+   tests/         → Unit and integration tests
+   e2e/           → End-to-end tests
+   docs/          → Documentation
+   ```
+
+4. **Code Style** — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
+
+5. **Testing Strategy** — What framework, where tests live, coverage expectations, which test levels for which concerns.
+
+6. **Boundaries** — Three-tier system:
+   - **Always do:** Run tests before commits, follow naming conventions, validate inputs
+   - **Ask first:** Database schema changes, adding dependencies, changing CI config
+   - **Never do:** Commit secrets, edit vendor directories, remove failing tests without approval
+
+**Spec template:**
+
+```markdown
+# Spec: [Project/Feature Name]
+
+## Objective
+[What we're building and why. User stories or acceptance criteria.]
+
+## Tech Stack
+[Framework, language, key dependencies with versions]
+
+## Commands
+[Build, test, lint, dev — full commands]
+
+## Project Structure
+[Directory layout with descriptions]
+
+## Code Style
+[Example snippet + key conventions]
+
+## Testing Strategy
+[Framework, test locations, coverage requirements, test levels]
+
+## Boundaries
+- Always: [...]
+- Ask first: [...]
+- Never: [...]
+
+## Success Criteria
+[How we'll know this is done — specific, testable conditions]
+
+## Open Questions
+[Anything unresolved that needs human input]
+```
+
+**Reframe instructions as success criteria.** When receiving vague requirements, translate them into concrete conditions:
+
+```
+REQUIREMENT: "Make the dashboard faster"
+
+REFRAMED SUCCESS CRITERIA:
+- Dashboard LCP < 2.5s on 4G connection
+- Initial data load completes in < 500ms
+- No layout shift during load (CLS < 0.1)
+→ Are these the right targets?
+```
+
+This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.
+
+### Phase 2: Plan
+
+With the validated spec, generate a technical implementation plan:
+
+1. Identify the major components and their dependencies
+2. Determine the implementation order (what must be built first)
+3. Note risks and mitigation strategies
+4. Identify what can be built in parallel vs. what must be sequential
+5. Define verification checkpoints between phases
+
+The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."
+
+### Phase 3: Tasks
+
+Break the plan into discrete, implementable tasks:
+
+- Each task should be completable in a single focused session
+- Each task has explicit acceptance criteria
+- Each task includes a verification step (test, build, manual check)
+- Tasks are ordered by dependency, not by perceived importance
+- No task should require changing more than ~5 files
+
+**Task template:**
+```markdown
+- [ ] Task: [Description]
+  - Acceptance: [What must be true when done]
+  - Verify: [How to confirm — test command, build, manual check]
+  - Files: [Which files will be touched]
+```
+
+### Phase 4: Implement
+
+Execute tasks one at a time following `skills/incremental-implementation/SKILL.md` (`incremental-implementation`) and `skills/test-driven-development/SKILL.md` (`test-driven-development`). Use `skills/context-engineering/SKILL.md` (`context-engineering`) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.
+
+## Keeping the Spec Alive
+
+The spec is a living document, not a one-time artifact:
+
+- **Update when decisions change** — If you discover the data model needs to change, update the spec first, then implement.
+- **Update when scope changes** — Features added or cut should be reflected in the spec.
+- **Commit the spec** — The spec belongs in version control alongside the code.
+- **Reference the spec in PRs** — Link back to the spec section that each PR implements.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "This is simple, I don't need a spec" | Simple tasks don't need *long* specs, but they still need acceptance criteria. A two-line spec is fine. |
+| "I'll write the spec after I code it" | That's documentation, not specification. The spec's value is in forcing clarity *before* code. |
+| "The spec will slow us down" | A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours. |
+| "Requirements will change anyway" | That's why the spec is a living document. An outdated spec is still better than no spec. |
+| "The user knows what they want" | Even clear requests have implicit assumptions. The spec surfaces those assumptions. |
+
+## Red Flags
+
+- Starting to write code without any written requirements
+- Asking "should I just start building?" before clarifying what "done" means
+- Implementing features not mentioned in any spec or task list
+- Making architectural decisions without documenting them
+- Skipping the spec because "it's obvious what to build"
+
+## Required Checks
+
+Before proceeding to implementation, confirm:
+
+- [ ] The spec covers all six core areas
+- [ ] The human has reviewed and approved the spec
+- [ ] Success criteria are specific and testable
+- [ ] Boundaries (Always/Ask First/Never) are defined
+- [ ] The spec is saved to a file in the repository
+
+## Workflow
+
+1. **Analyze Requirements:** Review user requests, existing code, and optional openSrc/ reference examples to identify ambiguities.
+2. **Draft the Specification:** Create a document (e.g., `docs/specs/feature-spec.md`) detailing the Goal, User Stories, Architecture changes, In-Scope vs Out-of-Scope, and Boundaries.
+3. **Formulate Definition of Done:** Establish concrete, testable criteria for success (e.g., unit tests, visual checks, command runs).
+4. **Obtain User Approval:** Share the spec with the user, collect feedback, and get explicit sign-off before coding.
+5. **Update Continuously:** If requirements evolve during implementation, update the specification first.
+
+## Verification
+
+After executing this skill, confirm:
+- [ ] A written specification is committed to the repository.
+- [ ] Definition of Done and boundaries are fully defined and approved by the user.
+- [ ] The implementation plan maps directly to the spec sections.