@kinqs/brainrouter-mcp-server 0.3.4

package/skills/devops/domain-skill/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: domain-skill
+description: Architect production-ready domain routing. Configure reverse proxies (e.g., Traefik), SSL/TLS certificates, and Cloudflare tunnels for secure public access.
+hints: |
+  - Always identify the primary hostnames (e.g. app.domain.com, api.domain.com) before structuring routing.
+  - Review Traefik labels in docker-compose.yml to ensure correct entrypoint and rule mappings.
+  - Use Cloudflare Zero Trust tunnels to establish secure outbound-only ingress paths without exposing local ports.
+  - Set up environment variables (like DOMAIN, CORS_ORIGIN, and WebAuthn relying party IDs) dynamically.
+  - Test routing and certificate issuance sequentially, beginning with Flexible TLS before strict enforcement.
+---
+
+# Custom Domain & Networking
+
+## Overview
+
+A robust routing architecture ensures secure, encrypted public access to backend and frontend services. This skill guides the setup of production-ready routing using reverse proxies (e.g., Traefik v3) coupled with secure edge ingress (e.g., Cloudflare Tunnels) to direct external traffic cleanly to containerized services without exposing local ports.
+
+## Ingress Architecture
+
+```
+Browser
+  │  HTTPS (TLS terminated by Cloudflare)
+  ▼
+Cloudflare Edge (api.yourdomain.com)
+  │  Outbound tunnel (no open ports needed)
+  ▼
+cloudflared daemon  ← Docker container, profile: production
+  │  HTTP  http://traefik:80
+  ▼
+Traefik v3          ← traefik container
+  │  HTTP  :3001
+  ▼
+Node.js / Express   ← backend container
+```
+
+> Local dev skips cloudflared entirely. Traefik routes `Host(\`localhost\`)` directly.
+
+---
+
+## Environment Variables
+
+Ensure the following networking environment variables are configured in the `.env` or deployment settings:
+
+| Variable | Dev value | Prod value | Purpose |
+|---|---|---|---|
+| `DOMAIN` | `api.yourdomain.com` | `api.yourdomain.com` | Traefik HTTPS router host rule |
+| `ACME_EMAIL` | `admin@yourdomain.com` | `admin@yourdomain.com` | Let's Encrypt certificate contact |
+| `CLOUDFLARE_TUNNEL_TOKEN` | *(blank)* | `<token from CF dashboard>` | Authenticates cloudflared to Cloudflare |
+| `FRONTEND_URL` | `http://localhost:3000` | `https://yourdomain.com` | Email link base URL |
+| `CORS_ORIGIN` | `http://localhost:3000,https://yourdomain.com` | `https://yourdomain.com` | Allowed CORS origins |
+| `PASSKEY_RP_ID` | `localhost` | `yourdomain.com` | WebAuthn Relying Party ID |
+| `PASSKEY_ORIGIN` | `http://localhost:3000` | `https://yourdomain.com` | WebAuthn allowed origin |
+
+---
+
+## Traefik Router Setup
+
+Two routers are typically configured in `docker-compose.yml` on the `backend` service:
+
+### HTTP Router (always active)
+
+```yaml
+- "traefik.http.routers.backend.rule=Host(`localhost`) || Host(`api.yourdomain.com`)"
+- "traefik.http.routers.backend.entrypoints=web"
+```
+
+Accepts both `localhost` (dev) and `api.yourdomain.com` (prod via cloudflared HTTP passthrough).
+
+### HTTPS Router (activates with Cloudflare Full strict)
+
+```yaml
+- "traefik.http.routers.backend-secure.rule=Host(`api.yourdomain.com`)"
+- "traefik.http.routers.backend-secure.entrypoints=websecure"
+- "traefik.http.routers.backend-secure.tls=true"
+- "traefik.http.routers.backend-secure.tls.certresolver=letsencrypt"
+```
+
+Traefik will auto-issue a Let's Encrypt cert once `api.yourdomain.com` is publicly resolvable.
+
+---
+
+## Cloudflare SSL Mode Decision
+
+| Mode | When to use | Traefik TLS needed? |
+|---|---|---|
+| **Flexible** | Dev/staging; simplest setup | ❌ No |
+| **Full** | Traefik has any cert (even self-signed) | ✅ Yes |
+| **Full (strict)** | Production; Traefik has valid Let's Encrypt cert | ✅ Yes |
+
+> **Recommended:** Start with **Flexible** to verify connectivity, then switch to **Full (strict)** once the domain is proven reachable and Let's Encrypt issues the cert.
+
+---
+
+## Workflow
+
+### Step 1 — Create the tunnel
+
+1. Go to [Cloudflare Zero Trust](https://one.dash.cloudflare.com) → **Networks → Tunnels → Create a tunnel**
+2. Choose **Cloudflared** connector
+3. Name the tunnel `app-tunnel`
+4. Copy the **tunnel token** — this is your `CLOUDFLARE_TUNNEL_TOKEN`
+
+### Step 2 — Configure Public Hostname
+
+In the tunnel settings, add a Public Hostname:
+
+| Field | Value |
+|---|---|
+| Subdomain | `api` |
+| Domain | `yourdomain.com` |
+| Service Type | `HTTP` |
+| Service URL | `traefik:80` |
+
+Cloudflare will automatically create the DNS record:
+
+| Type | Name | Target | Proxy |
+|---|---|---|---|
+| CNAME | `api` | `<tunnel-id>.cfargotunnel.com` | ✅ Proxied |
+
+### Step 3 — Add token to `.env`
+
+```bash
+# .env
+CLOUDFLARE_TUNNEL_TOKEN=<paste token here>
+```
+
+### Step 4 — Start cloudflared
+
+```bash
+# Only starts services with the production profile
+docker compose --profile production up -d cloudflared
+
+# Verify connection
+docker logs cloudflared --tail 20
+# Expected: "Connection established" / "Registered tunnel connection"
+```
+
+### Step 5 — Verify
+
+```bash
+# Health check through the full tunnel
+curl https://api.yourdomain.com/health
+# Expected: { "status": "ok", ... }
+
+# Check Traefik picked up the new router
+open http://localhost:8080   # Traefik dashboard
+```
+
+---
+
+## SSL Mode: Switch to Full (strict)
+
+Once Let's Encrypt issues the cert (check Traefik dashboard → TLS), switch Cloudflare:
+
+1. Cloudflare dashboard → **SSL/TLS → Overview**
+2. Change mode to **Full (strict)**
+3. No Docker restart needed — Traefik handles this automatically
+
+---
+
+## Cloudflared Compose Profile
+
+The `cloudflared` service uses `profiles: [production]` so it **never starts** during normal dev:
+
+```bash
+# Dev (cloudflared excluded)
+docker compose up -d
+
+# Production (all services including cloudflared)
+docker compose --profile production up -d
+
+# Start cloudflared only (if stack is already running)
+docker compose --profile production up -d cloudflared
+```
+
+---
+
+## Migration Path: Tunnel → VPS + WireGuard
+
+When you move to a dedicated server with a static IP:
+
+1. **Remove** `cloudflared` service from docker-compose (or keep as fallback)
+2. **Point** Cloudflare DNS `A` record `api` → `<vps-ip>` (Proxied ✅)
+3. **Open** ports `80` and `443` on the VPS firewall
+4. **Traefik** will handle Let's Encrypt directly via HTTP challenge on port 80
+5. **Update** SSL/TLS mode to **Full (strict)** in Cloudflare
+
+The Traefik labels and ACME config in docker-compose remain identical — only the ingress path changes.
+
+---
+
+## Pitfalls
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `curl: (6) Could not resolve host` | DNS not propagated | Wait 1–5 min after Cloudflare saves the CNAME |
+| Tunnel connected but 502 | cloudflared can't reach `traefik:80` | Verify both are on the same docker network; check `docker network inspect` |
+| Let's Encrypt cert not issued | Domain not publicly reachable on port 80 | Use Flexible SSL mode until tunnel is confirmed working |
+| CORS errors in browser | `CORS_ORIGIN` missing origin domain | Add proper origin to `.env` and restart backend |
+| WebAuthn fails on prod | `PASSKEY_RP_ID` still set to `localhost` | Update to the production domain and redeploy |
+| `--profile production` not recognized | Old Docker Compose version | Upgrade to Docker Compose v2.x (`docker compose version`) |
+
+## When to Use
+
+- Mapping custom domains (e.g., `app.domain.com` or `api.domain.com`) to containerized services.
+- Designing secure ingress architectures via reverse proxies (e.g., Traefik, Nginx) and edge providers (e.g., Cloudflare).
+- Setting up SSL/TLS termination, automated certificate resolvers (Let's Encrypt), or Cloudflare Tunnels (`cloudflared`).
+
+**When NOT to use:**
+- Basic local-only dev environments that do not require DNS mapping or secure public access.
+- Deploying on serverless platforms (e.g., Vercel, Netlify) where domain routing is fully managed by the provider.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I will expose the container port directly to the internet." | Exposing service ports directly bypasses reverse proxy benefits (load balancing, SSL termination, request filtering) and introduces massive security vulnerabilities. |
+| "I'll use HTTP in staging to save setup time." | Staging must mimic production. Omitting TLS in staging leads to hidden CORS, WebAuthn, cookie security, or certificate routing errors that only show up in production. |
+| "Setting up Cloudflare tunnels is too slow; I'll just open port 80/443." | Opening incoming ports makes the host machine an active target for automated port scanners. Outbound-only tunnels are vastly more secure. |
+
+## Red Flags
+
+- Hardcoded domain names in docker-compose configurations instead of environment variables.
+- Using Flexible SSL/TLS modes in production indefinitely without terminating TLS at the reverse proxy (leaves edge-to-origin traffic unencrypted).
+- Mixing production tunnel credentials or domain records directly inside shared development files.
+- Exposing Traefik dashboards publicly without authentication or strong basic auth middlewares.
+
+## Verification
+
+After completing the domain setup, verify:
+- [ ] Ingress paths are tested and return valid HTTP statuses (e.g., 200 OK, secure 301 redirects).
+- [ ] SSL/TLS certificate is verified as valid and issued by a recognized CA (e.g., Let's Encrypt, Cloudflare Edge).
+- [ ] CORS origins and authentication parameters (e.g., WebAuthn/Passkey RP IDs) match the active host exactly.
+- [ ] Cloudflared connections are confirmed in container logs with `Connection established` and no active errors.

package/skills/lifecycle/changelog-generator/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: changelog-generator
+description: Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.
+hints:
+  - Check openSrc/ or existing project files for CHANGELOG.md patterns and formats if available.
+  - Exclude developer-only noise (e.g. chore, simple refactoring, config updates) from user-facing logs.
+  - Group additions into cohesive, standard categories: Features, Improvements, Bug Fixes, Breaking Changes, Security.
+  - Translate technical implementation terms (e.g., class names, SQL keys) into user-facing benefits and actions.
+  - Highlight breaking changes or required migration steps prominently at the top of the changelog notes.
+---
+
+# Changelog Generator
+
+This skill transforms technical git commits into polished, user-friendly changelogs that your customers and users will actually understand and appreciate.
+
+## When to Use This Skill
+
+- Preparing release notes for a new version
+- Creating weekly or monthly product update summaries
+- Documenting changes for customers
+- Writing changelog entries for app store submissions
+- Generating update notifications
+- Creating internal release documentation
+- Maintaining a public changelog/product updates page
+
+## Overview
+
+1. **Scans Git History**: Analyzes commits from a specific time period or between versions
+2. **Categorizes Changes**: Groups commits into logical categories (features, improvements, bug fixes, breaking changes, security)
+3. **Translates Technical → User-Friendly**: Converts developer commits into customer language
+4. **Formats Professionally**: Creates clean, structured changelog entries
+5. **Filters Noise**: Excludes internal commits (refactoring, tests, etc.)
+6. **Follows Best Practices**: Applies changelog guidelines and your brand voice
+
+
+## Workflow
+
+1. Identify release scope (version range, commit range, or date range).
+2. Gather relevant commits and exclude maintenance noise.
+3. Group changes into user-facing categories.
+4. Rewrite each item in plain customer language.
+5. Format output as publish-ready markdown and verify clarity.
+
+## Usage
+
+### Basic Usage
+
+From your project repository:
+
+```
+Create a changelog from commits since last release
+```
+
+```
+Generate changelog for all commits from the past week
+```
+
+```
+Create release notes for version 2.5.0
+```
+
+### With Specific Date Range
+
+```
+Create a changelog for all commits between March 1 and March 15
+```
+
+### With Custom Guidelines
+
+```
+Create a changelog for commits since v2.4.0, using my changelog 
+guidelines from CHANGELOG_STYLE.md
+```
+
+## Example
+
+**User**: "Create a changelog for commits from the past 7 days"
+
+**Output**:
+```markdown
+# Updates - Week of March 10, 2024
+
+## ✨ New Features
+
+- **Team Workspaces**: Create separate workspaces for different 
+  projects. Invite team members and keep everything organized.
+
+- **Keyboard Shortcuts**: Press ? to see all available shortcuts. 
+  Navigate faster without touching your mouse.
+
+## 🔧 Improvements
+
+- **Faster Sync**: Files now sync 2x faster across devices
+- **Better Search**: Search now includes file contents, not just titles
+
+## 🐛 Fixes
+
+- Fixed issue where large images wouldn't upload
+- Resolved timezone confusion in scheduled posts
+- Corrected notification badge count
+```
+
+**Inspired by:** Manik Aggarwal's use case from Lenny's Newsletter
+
+## Tips
+
+- Run from your git repository root
+- Specify date ranges for focused changelogs
+- Use your CHANGELOG_STYLE.md for consistent formatting
+- Review and adjust the generated changelog before publishing
+- Save output directly to CHANGELOG.md
+
+## Related Use Cases
+
+- Creating GitHub release notes
+- Writing app store update descriptions
+- Generating email updates for users
+- Creating social media announcement posts
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| I'll just dump raw commit logs directly. | Raw commits contain internal technical jargon (e.g. `refactor: fix database constraints`) that confuses users. |
+| No one reads changelogs, so formatting doesn't matter. | Well-structured changelogs demonstrate project health, building trust with users and stakeholders. |
+
+## Red Flags
+- Including chore commits (`chore: update eslint`) or test commits in user-facing release notes.
+- Highlighting internal module names or database parameters instead of functional product capabilities.
+- Obfuscating or hiding major breaking changes in fine print.
+
+## Verification
+After completing the skill, confirm:
+- [ ] Technical jargon is completely rewritten to represent user-facing value and utility.
+- [ ] Internal/engineering noise (tests, configs, refactors) is filtered out.
+- [ ] Markdown formatting is verified clean, readable, and properly categorized.

package/skills/lifecycle/incremental-skill/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: incremental-skill
+description: Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step.
+hints:
+  - Check openSrc/ or existing project layouts for modular folder structures if available.
+  - Implement code in thin vertical slices (e.g. database schema first, then api route, then frontend UI components).
+  - Verify every single micro-slice immediately after implementation via test runner or build suites.
+  - Wrap incomplete code blocks behind feature flags before merging to the main branch.
+  - Adhere strictly to scope discipline: document out-of-scope issues rather than attempting to refactor them immediately.
+---
+
+# Incremental Implementation
+
+## Overview
+
+Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
+
+## When to Use
+
+- Implementing any multi-file change
+- Building a new feature from a task breakdown
+- Refactoring existing code
+- Any time you're tempted to write more than ~100 lines before testing
+
+**When NOT to use:** Single-file, single-function changes where the scope is already minimal.
+
+## The Increment Cycle
+
+```
+┌──────────────────────────────────────┐
+│                                      │
+│   Implement ──→ Test ──→ Verify ──┐  │
+│       ▲                           │  │
+│       └───── Commit ◄─────────────┘  │
+│              │                       │
+│              ▼                       │
+│          Next slice                  │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+For each slice:
+
+1. **Implement** the smallest complete piece of functionality
+2. **Test** — run the test suite (or write a test if none exists)
+3. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check)
+4. **Commit** -- save your progress with a descriptive message (see `git-workflow-and-versioning` for atomic commit guidance)
+5. **Move to the next slice** — carry forward, don't restart
+
+## Slicing Strategies
+
+### Vertical Slices (Preferred)
+
+Build one complete path through the stack:
+
+```
+Slice 1: Create a task (DB + API + basic UI)
+    → Tests pass, user can create a task via the UI
+
+Slice 2: List tasks (query + API + UI)
+    → Tests pass, user can see their tasks
+
+Slice 3: Edit a task (update + API + UI)
+    → Tests pass, user can modify tasks
+
+Slice 4: Delete a task (delete + API + UI + confirmation)
+    → Tests pass, full CRUD complete
+```
+
+Each slice delivers working end-to-end functionality.
+
+### Contract-First Slicing
+
+When backend and frontend need to develop in parallel:
+
+```
+Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
+Slice 1a: Implement backend against the contract + API tests
+Slice 1b: Implement frontend against mock data matching the contract
+Slice 2: Integrate and test end-to-end
+```
+
+### Risk-First Slicing
+
+Tackle the riskiest or most uncertain piece first:
+
+```
+Slice 1: Prove the WebSocket connection works (highest risk)
+Slice 2: Build real-time task updates on the proven connection
+Slice 3: Add offline support and reconnection
+```
+
+If Slice 1 fails, you discover it before investing in Slices 2 and 3.
+
+## Implementation Rules
+
+### Rule 0: Simplicity First
+
+Before writing any code, ask: "What is the simplest thing that could work?"
+
+After writing code, review it against these checks:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+- Am I building for hypothetical future requirements, or the current task?
+
+```
+SIMPLICITY CHECK:
+✗ Generic EventBus with middleware pipeline for one notification
+✓ Simple function call
+
+✗ Abstract factory pattern for two similar components
+✓ Two straightforward components with shared utilities
+
+✗ Config-driven form builder for three forms
+✓ Three form components
+```
+
+Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.
+
+### Rule 0.5: Scope Discipline
+
+Touch only what the task requires.
+
+Do NOT:
+- "Clean up" code adjacent to your change
+- Refactor imports in files you're not modifying
+- Remove comments you don't fully understand
+- Add features not in the spec because they "seem useful"
+- Modernize syntax in files you're only reading
+
+If you notice something worth improving outside your task scope, note it — don't fix it:
+
+```
+NOTICED BUT NOT TOUCHING:
+- src/utils/format.ts has an unused import (unrelated to this task)
+- The auth middleware could use better error messages (separate task)
+→ Want me to create tasks for these?
+```
+
+### Rule 1: One Thing at a Time
+
+Each increment changes one logical thing. Don't mix concerns:
+
+**Bad:** One commit that adds a new component, refactors an existing one, and updates the build config.
+
+**Good:** Three separate commits — one for each change.
+
+### Rule 2: Keep It Compilable
+
+After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.
+
+### Rule 3: Feature Flags for Incomplete Features
+
+If a feature isn't ready for users but you need to merge increments:
+
+```typescript
+// Feature flag for work-in-progress
+const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
+
+if (ENABLE_TASK_SHARING) {
+  // New sharing UI
+}
+```
+
+This lets you merge small increments to the main branch without exposing incomplete work.
+
+### Rule 4: Safe Defaults
+
+New code should default to safe, conservative behavior:
+
+```typescript
+// Safe: disabled by default, opt-in
+export function createTask(data: TaskInput, options?: { notify?: boolean }) {
+  const shouldNotify = options?.notify ?? false;
+  // ...
+}
+```
+
+### Rule 5: Rollback-Friendly
+
+Each increment should be independently revertable:
+
+- Additive changes (new files, new functions) are easy to revert
+- Modifications to existing code should be minimal and focused
+- Database migrations should have corresponding rollback migrations
+- Avoid deleting something in one commit and replacing it in the same commit — separate them
+
+## Working with Agents
+
+When directing an agent to implement incrementally:
+
+```
+"Let's implement Task 3 from the plan.
+
+Start with just the database schema change and the API endpoint.
+Don't touch the UI yet — we'll do that in the next increment.
+
+After implementing, run `npm test` and `npm run build` to verify
+nothing is broken."
+```
+
+Be explicit about what's in scope and what's NOT in scope for each increment.
+
+## Increment Checklist
+
+After each increment, verify:
+
+- [ ] The change does one thing and does it completely
+- [ ] All existing tests still pass (`npm test`)
+- [ ] The build succeeds (`npm run build`)
+- [ ] Type checking passes (`npx tsc --noEmit`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] The new functionality works as expected
+- [ ] The change is committed with a descriptive message
+
+**Note:** Run each verification command after a change that could affect it. After a successful run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no information.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |
+| "It's faster to do it all at once" | It *feels* faster until something breaks and you can't find which of 500 changed lines caused it. |
+| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. |
+| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. |
+| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. |
+| "Let me run the build command again just to be sure" | After a successful run, repeating the same command adds nothing unless the code has changed since. Run it again after subsequent edits, not as reassurance. |
+
+## Red Flags
+
+- More than 100 lines of code written without running tests
+- Multiple unrelated changes in a single increment
+- "Let me just quickly add this too" scope expansion
+- Skipping the test/verify step to move faster
+- Build or tests broken between increments
+- Large uncommitted changes accumulating
+- Building abstractions before the third use case demands it
+- Touching files outside the task scope "while I'm here"
+- Creating new utility files for one-time operations
+- Running the same build/test command twice in a row without any intervening code change
+
+## Required Checks
+
+After completing all increments for a task:
+
+- [ ] Each increment was individually tested and committed.
+- [ ] The full test suite passes.
+- [ ] The build is clean and error-free.
+- [ ] The feature works end-to-end as specified.
+- [ ] No uncommitted files or styling junk are left behind.
+
+## Verification
+After completing the skill, confirm:
+- [ ] Each micro-slice is verified functionally and committed with an atomic, conventional message.
+- [ ] Build processes and lint suites run successfully without errors or warnings.
+- [ ] Scope discipline has been strictly observed, and no out-of-scope code changes were introduced.