@kinqs/brainrouter-mcp-server 0.3.4

package/references/testing-patterns.md

@@ -0,0 +1,236 @@
+# Testing Patterns Reference
+
+Quick reference for common testing patterns across the stack. Use alongside the `test-driven-development` skill.
+
+## Table of Contents
+
+- [Test Structure (Arrange-Act-Assert)](#test-structure-arrange-act-assert)
+- [Test Naming Conventions](#test-naming-conventions)
+- [Common Assertions](#common-assertions)
+- [Mocking Patterns](#mocking-patterns)
+- [React/Component Testing](#reactcomponent-testing)
+- [API / Integration Testing](#api--integration-testing)
+- [E2E Testing (Playwright)](#e2e-testing-playwright)
+- [Test Anti-Patterns](#test-anti-patterns)
+
+## Test Structure (Arrange-Act-Assert)
+
+```typescript
+it('describes expected behavior', () => {
+  // Arrange: Set up test data and preconditions
+  const input = { title: 'Test Task', priority: 'high' };
+
+  // Act: Perform the action being tested
+  const result = createTask(input);
+
+  // Assert: Verify the outcome
+  expect(result.title).toBe('Test Task');
+  expect(result.priority).toBe('high');
+  expect(result.status).toBe('pending');
+});
+```
+
+## Test Naming Conventions
+
+```typescript
+// Pattern: [unit] [expected behavior] [condition]
+describe('TaskService.createTask', () => {
+  it('creates a task with default pending status', () => {});
+  it('throws ValidationError when title is empty', () => {});
+  it('trims whitespace from title', () => {});
+  it('generates a unique ID for each task', () => {});
+});
+```
+
+## Common Assertions
+
+```typescript
+// Equality
+expect(result).toBe(expected);           // Strict equality (===)
+expect(result).toEqual(expected);        // Deep equality (objects/arrays)
+expect(result).toStrictEqual(expected);  // Deep equality + type matching
+
+// Truthiness
+expect(result).toBeTruthy();
+expect(result).toBeFalsy();
+expect(result).toBeNull();
+expect(result).toBeDefined();
+expect(result).toBeUndefined();
+
+// Numbers
+expect(result).toBeGreaterThan(5);
+expect(result).toBeLessThanOrEqual(10);
+expect(result).toBeCloseTo(0.3, 5);      // Floating point
+
+// Strings
+expect(result).toMatch(/pattern/);
+expect(result).toContain('substring');
+
+// Arrays / Objects
+expect(array).toContain(item);
+expect(array).toHaveLength(3);
+expect(object).toHaveProperty('key', 'value');
+
+// Errors
+expect(() => fn()).toThrow();
+expect(() => fn()).toThrow(ValidationError);
+expect(() => fn()).toThrow('specific message');
+
+// Async
+await expect(asyncFn()).resolves.toBe(value);
+await expect(asyncFn()).rejects.toThrow(Error);
+```
+
+## Mocking Patterns
+
+### Mock Functions
+
+```typescript
+const mockFn = jest.fn();
+mockFn.mockReturnValue(42);
+mockFn.mockResolvedValue({ data: 'test' });
+mockFn.mockImplementation((x) => x * 2);
+
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+expect(mockFn).toHaveBeenCalledTimes(3);
+```
+
+### Mock Modules
+
+```typescript
+// Mock an entire module
+jest.mock('./database', () => ({
+  query: jest.fn().mockResolvedValue([{ id: 1, title: 'Test' }]),
+}));
+
+// Mock specific exports
+jest.mock('./utils', () => ({
+  ...jest.requireActual('./utils'),
+  generateId: jest.fn().mockReturnValue('test-id'),
+}));
+```
+
+### Mock at Boundaries Only
+
+```
+Mock these:                    Don't mock these:
+├── Database calls             ├── Internal utility functions
+├── HTTP requests              ├── Business logic
+├── File system operations     ├── Data transformations
+├── External API calls         ├── Validation functions
+└── Time/Date (when needed)    └── Pure functions
+```
+
+## React/Component Testing
+
+```tsx
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+
+describe('TaskForm', () => {
+  it('submits the form with entered data', async () => {
+    const onSubmit = jest.fn();
+    render(<TaskForm onSubmit={onSubmit} />);
+
+    // Find elements by accessible role/label (not test IDs)
+    await screen.findByRole('textbox', { name: /title/i });
+    fireEvent.change(screen.getByRole('textbox', { name: /title/i }), {
+      target: { value: 'New Task' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({ title: 'New Task' });
+    });
+  });
+
+  it('shows validation error for empty title', async () => {
+    render(<TaskForm onSubmit={jest.fn()} />);
+
+    fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+    expect(await screen.findByText(/title is required/i)).toBeInTheDocument();
+  });
+});
+```
+
+## API / Integration Testing
+
+```typescript
+import request from 'supertest';
+import { app } from '../src/app';
+
+describe('POST /api/tasks', () => {
+  it('creates a task and returns 201', async () => {
+    const response = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'Test Task' })
+      .set('Authorization', `Bearer ${testToken}`)
+      .expect(201);
+
+    expect(response.body).toMatchObject({
+      id: expect.any(String),
+      title: 'Test Task',
+      status: 'pending',
+    });
+  });
+
+  it('returns 422 for invalid input', async () => {
+    const response = await request(app)
+      .post('/api/tasks')
+      .send({ title: '' })
+      .set('Authorization', `Bearer ${testToken}`)
+      .expect(422);
+
+    expect(response.body.error.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('returns 401 without authentication', async () => {
+    await request(app)
+      .post('/api/tasks')
+      .send({ title: 'Test' })
+      .expect(401);
+  });
+});
+```
+
+## E2E Testing (Playwright)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('user can create and complete a task', async ({ page }) => {
+  // Navigate and authenticate
+  await page.goto('/');
+  await page.fill('[name="email"]', 'test@example.com');
+  await page.fill('[name="password"]', 'testpass123');
+  await page.click('button:has-text("Log in")');
+
+  // Create a task
+  await page.click('button:has-text("New Task")');
+  await page.fill('[name="title"]', 'Buy groceries');
+  await page.click('button:has-text("Create")');
+
+  // Verify task appears
+  await expect(page.locator('text=Buy groceries')).toBeVisible();
+
+  // Complete the task
+  await page.click('[aria-label="Complete Buy groceries"]');
+  await expect(page.locator('text=Buy groceries')).toHaveCSS(
+    'text-decoration-line', 'line-through'
+  );
+});
+```
+
+## Test Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|---|---|---|
+| Testing implementation details | Breaks on refactor | Test inputs/outputs |
+| Snapshot everything | No one reviews snapshot diffs | Assert specific values |
+| Shared mutable state | Tests pollute each other | Setup/teardown per test |
+| Testing third-party code | Wastes time, not your bug | Mock the boundary |
+| Skipping tests to pass CI | Hides real bugs | Fix or delete the test |
+| Using `test.skip` permanently | Dead code | Remove or fix it |
+| Overly broad assertions | Doesn't catch regressions | Be specific |
+| No async error handling | Swallowed errors, false passes | Always `await` async tests |

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

@@ -0,0 +1,299 @@
+---
+name: adr-skill
+description: Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.
+hints:
+  - Document the 'why' (context, constraints, trade-offs) behind a change, not just the 'what'.
+  - Write an ADR (Architecture Decision Record) for any decision that would be expensive to reverse.
+  - Review openSrc/ directories or existing ADRs under docs/decisions/ for structure and style guidelines.
+  - Store ADRs in docs/decisions/ with sequential, three-digit numbering (e.g., ADR-001).
+  - Keep public API and inline documentation clean, type-annotated, and free of commented-out code.
+---
+
+# Documentation and ADRs
+
+## Overview
+
+Document decisions, not just code. The most valuable documentation captures the *why* — the context, constraints, and trade-offs that led to a decision. Code shows *what* was built; documentation explains *why it was built this way* and *what alternatives were considered*. This context is essential for future humans and agents working in the codebase.
+
+## When to Use
+
+- Making a significant architectural decision
+- Choosing between competing approaches
+- Adding or changing a public API
+- Shipping a feature that changes user-facing behavior
+- Onboarding new team members (or agents) to the project
+- When you find yourself explaining the same thing repeatedly
+
+**When NOT to use:** Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
+
+## Architecture Decision Records (ADRs)
+
+ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.
+
+### When to Write an ADR
+
+- Choosing a framework, library, or major dependency
+- Designing a data model or database schema
+- Selecting an authentication strategy
+- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
+- Choosing between build tools, hosting platforms, or infrastructure
+- Any decision that would be expensive to reverse
+
+### ADR Template
+
+Store ADRs in `docs/decisions/` with sequential numbering:
+
+```markdown
+# ADR-001: Use PostgreSQL for primary database
+
+## Status
+Accepted | Superseded by ADR-XXX | Deprecated
+
+## Date
+2025-01-15
+
+## Context
+We need a primary database for the task management application. Key requirements:
+- Relational data model (users, tasks, teams with relationships)
+- ACID transactions for task state changes
+- Support for full-text search on task content
+- Managed hosting available (for small team, limited ops capacity)
+
+## Decision
+Use PostgreSQL with Prisma ORM.
+
+## Alternatives Considered
+
+### MongoDB
+- Pros: Flexible schema, easy to start with
+- Cons: Our data is inherently relational; would need to manage relationships manually
+- Rejected: Relational data in a document store leads to complex joins or data duplication
+
+### SQLite
+- Pros: Zero configuration, embedded, fast for reads
+- Cons: Limited concurrent write support, no managed hosting for production
+- Rejected: Not suitable for multi-user web application in production
+
+### MySQL
+- Pros: Mature, widely supported
+- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
+- Rejected: PostgreSQL is the better fit for our feature requirements
+
+## Consequences
+- Prisma provides type-safe database access and migration management
+- We can use PostgreSQL's full-text search instead of adding Elasticsearch
+- Team needs PostgreSQL knowledge (standard skill, low risk)
+- Hosting on managed service (Supabase, Neon, or RDS)
+```
+
+### ADR Lifecycle
+
+```
+PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
+```
+
+- **Don't delete old ADRs.** They capture historical context.
+- When a decision changes, write a new ADR that references and supersedes the old one.
+
+## Inline Documentation
+
+### When to Comment
+
+Comment the *why*, not the *what*:
+
+```typescript
+// BAD: Restates the code
+// Increment counter by 1
+counter += 1;
+
+// GOOD: Explains non-obvious intent
+// Rate limit uses a sliding window — reset counter at window boundary,
+// not on a fixed schedule, to prevent burst attacks at window edges
+if (now - windowStart > WINDOW_SIZE_MS) {
+  counter = 0;
+  windowStart = now;
+}
+```
+
+### When NOT to Comment
+
+```typescript
+// Don't comment self-explanatory code
+function calculateTotal(items: CartItem[]): number {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+
+// Don't leave TODO comments for things you should just do now
+// TODO: add error handling  ← Just add it
+
+// Don't leave commented-out code
+// const oldImplementation = () => { ... }  ← Delete it, git has history
+```
+
+### Document Known Gotchas
+
+```typescript
+/**
+ * IMPORTANT: This function must be called before the first render.
+ * If called after hydration, it causes a flash of unstyled content
+ * because the theme context isn't available during SSR.
+ *
+ * See ADR-003 for the full design rationale.
+ */
+export function initializeTheme(theme: Theme): void {
+  // ...
+}
+```
+
+## API Documentation
+
+For public APIs (REST, GraphQL, library interfaces):
+
+### Inline with Types (Preferred for TypeScript)
+
+```typescript
+/**
+ * Creates a new task.
+ *
+ * @param input - Task creation data (title required, description optional)
+ * @returns The created task with server-generated ID and timestamps
+ * @throws {ValidationError} If title is empty or exceeds 200 characters
+ * @throws {AuthenticationError} If the user is not authenticated
+ *
+ * @example
+ * const task = await createTask({ title: 'Buy groceries' });
+ * console.log(task.id); // "task_abc123"
+ */
+export async function createTask(input: CreateTaskInput): Promise<Task> {
+  // ...
+}
+```
+
+### OpenAPI / Swagger for REST APIs
+
+```yaml
+paths:
+  /api/tasks:
+    post:
+      summary: Create a task
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTaskInput'
+      responses:
+        '201':
+          description: Task created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '422':
+          description: Validation error
+```
+
+## README Structure
+
+Every project should have a README that covers:
+
+```markdown
+# Project Name
+
+One-paragraph description of what this project does.
+
+## Quick Start
+1. Clone the repo
+2. Install dependencies: `npm install`
+3. Set up environment: `cp .env.example .env`
+4. Run the dev server: `npm run dev`
+
+## Commands
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server |
+| `npm test` | Run tests |
+| `npm run build` | Production build |
+| `npm run lint` | Run linter |
+
+## Architecture
+Brief overview of the project structure and key design decisions.
+Link to ADRs for details.
+
+## Contributing
+How to contribute, coding standards, PR process.
+```
+
+## Changelog Maintenance
+
+For shipped features:
+
+```markdown
+# Changelog
+
+## [1.2.0] - 2025-01-20
+### Added
+- Task sharing: users can share tasks with team members (#123)
+- Email notifications for task assignments (#124)
+
+### Fixed
+- Duplicate tasks appearing when rapidly clicking create button (#125)
+
+### Changed
+- Task list now loads 50 items per page (was 20) for better UX (#126)
+```
+
+## Documentation for Agents
+
+Special consideration for AI agent context:
+
+- **CLAUDE.md / rules files** — Document project conventions so agents follow them
+- **Spec files** — Keep specs updated so agents build the right thing
+- **ADRs** — Help agents understand why past decisions were made (prevents re-deciding)
+- **Inline gotchas** — Prevent agents from falling into known traps
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The code is self-documenting" | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. |
+| "We'll write docs when the API stabilizes" | APIs stabilize faster when you document them. The doc is the first test of the design. |
+| "Nobody reads docs" | Agents do. Future engineers do. Your 3-months-later self does. |
+| "ADRs are overhead" | A 10-minute ADR prevents a 2-hour debate about the same decision six months later. |
+| "Comments get outdated" | Comments on *why* are stable. Comments on *what* get outdated — that's why you only write the former. |
+
+## Red Flags
+
+- Architectural decisions with no written rationale
+- Public APIs with no documentation or types
+- README that doesn't explain how to run the project
+- Commented-out code instead of deletion
+- TODO comments that have been there for weeks
+- No ADRs in a project with significant architectural choices
+- Documentation that restates the code instead of explaining intent
+
+## Required Checks
+
+After documenting:
+
+- [ ] ADRs exist for all significant architectural decisions
+- [ ] README covers quick start, commands, and architecture overview
+- [ ] API functions have parameter and return type documentation
+- [ ] Known gotchas are documented inline where they matter
+- [ ] No commented-out code remains
+- [ ] Rules files (CLAUDE.md etc.) are current and accurate
+
+## Workflow
+
+1. **Identify Significant Decisions:** Recognize when a change impacts API structure, package dependencies, data model/schema, or deployment architecture.
+2. **Draft the Architecture Decision Record (ADR):** Create a new markdown file under `docs/decisions/` prefixed with a sequential index (e.g., `ADR-005-redis-caching.md`).
+3. **Analyze Alternatives:** Outline at least 2 distinct alternatives, detailing explicit pros/cons and clear reasons for rejection.
+4. **Define Consequences:** Explicitly capture downstream engineering impacts, risks, and onboarding implications.
+5. **Verify and Update:** Review against similar historical decisions (checking `openSrc/` patterns if an openSrc/ directory is present) before finalizing.
+
+## Verification
+
+After executing this skill, confirm:
+- [ ] ADR file is correctly formatted and located in `docs/decisions/`.
+- [ ] No un-analyzed alternatives or vague rationalizations exist in the record.
+- [ ] Code references to the decision are updated to cross-reference the ADR.

package/skills/agent/agentic-engineering-workflow/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: agentic-engineering-workflow
+description: Provides an end-to-end operating system for building software with AI agents. Use when starting any non-trivial feature, MVP, or tool build with an AI coding agent. Use when you want a repeatable workflow instead of ad-hoc prompting.
+hints: |
+  - Keep each task small and PR-sized — one feature or fix at a time.
+  - Build the minimal working version first, then run a cleanup pass.
+  - Never guess APIs — reference official docs or the openSrc/ folder (if present) before coding.
+  - Run a review-fix loop after every PR until tests pass and review is clean.
+  - Launch earlier than feels comfortable. Feedback beats perfection.
+---
+
+# Agentic Engineering Workflow
+
+## Overview
+
+A repeatable operating system for building software with AI coding agents. The human decides the outcome, the agent does the mechanical work, and tight feedback loops keep the result honest. This is not "ask the AI to build everything and hope" — it is a disciplined process where every step is small, verifiable, and reversible.
+
+## When to Use
+
+- You are building an MVP, feature, internal tool, or AI-assisted product.
+- You want a repeatable AI coding workflow instead of random prompting.
+- You are using Cursor, Claude Code, Codex, Hermes, or another coding harness.
+
+**When NOT to use:** One-off tiny edits where a normal direct prompt is sufficient.
+
+## Workflow
+
+```
+HARNESS → SMALL TASK → SOURCE CONTEXT → BUILD MINIMAL → CLEANUP → REVIEW LOOP → LAUNCH → SECURITY
+```
+
+1. **Pick the strongest harness/model you can access.** The harness is the wrapper around the model: file search, terminal, browser, tools, system prompt, and project memory. The model matters, but the harness determines what the model can actually do.
+
+2. **Keep the task small.** Ask for one feature, one fix, or one reviewable unit at a time. If a plan is too large, ask the agent to split it into smaller PR-sized chunks.
+
+3. **Give source code as context when docs are not enough.** If you are using a package, SDK, framework, or open-source tool, tell the agent to search it before coding. If an `openSrc/` folder is present in the workspace, check its reference repositories for high-quality implementation examples. See `source-driven-skill` for the full pattern.
+
+4. **Build the minimal feature first.** Do not refactor the whole app while building the feature. Get the smallest working version running.
+
+5. **Run a cleanup pass.** After the feature works, ask the agent to find duplicated runtime mechanics and move them into reusable service-layer modules. See `code-structure-cleanup`.
+
+6. **Run a review-fix loop.** Use tests, typechecks, and AI/human review. Feed review feedback back into the coding agent. Keep fixing until the PR is clean or a human decision is needed. See `code-review-and-quality`.
+
+7. **Launch earlier than feels comfortable.** A semi-functional MVP with real user feedback beats a perfect private project every time.
+
+8. **Apply security guardrails.** Never install a package less than 14 days old without human approval. Use 2FA via authenticator app, not SMS. Never paste secrets into prompts. When a package breach trends, ask the agent to scan your local projects for that package/version.
+
+## Copy-Paste Starter Prompt
+
+```md
+We are going to build this using an agentic engineering workflow.
+
+Rules:
+1. Keep the change small and reviewable.
+2. Search the existing code before creating new abstractions.
+3. If using a package/framework, reference its local source or official repo before guessing APIs.
+4. Build the minimal working version first.
+5. After it works, run a code-structure cleanup pass.
+6. Run relevant tests/typechecks.
+7. Summarize what changed, what was tested, and what still needs human judgment.
+
+Task:
+<describe the feature or fix here>
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Let the agent decide the approach" | The agent is a worker, not the product owner. You decide the outcome — the agent executes it. |
+| "More context is always better" | Context overload degrades output quality. Give only the files and specs relevant to the current task. |
+| "One big PR is faster" | Review loops break down on large diffs. Split into small, reviewable units. |
+| "I'll do the cleanup later" | Working code with duplicated mechanics is technical debt that slows every future agent working in that area. |
+| "It just needs one more feature before launch" | Waiting for perfect is how competitors ship before you. Ship now, improve with feedback. |
+
+## Red Flags
+
+- Starting a task without defining what "done" means.
+- Asking the agent to build multiple features in a single session without a plan.
+- PRs with thousands of changed lines — the review loop will break down.
+- Agent inventing API names instead of referencing source or docs.
+- No cleanup pass after a feature ships.
+- Secrets in prompts, screenshots, or code comments.
+
+## Verification
+
+After completing a feature using this workflow, confirm:
+
+- [ ] Task was scoped to a single small, reviewable unit.
+- [ ] Agent searched relevant existing code before editing.
+- [ ] External package/framework behavior was checked against source or official docs.
+- [ ] Feature works locally.
+- [ ] Cleanup pass was run and obvious duplication was removed.
+- [ ] Tests/typechecks ran, or the reason they could not is stated.
+- [ ] Security-sensitive changes were explicitly reviewed by a human.