@rune-kit/rune 2.1.1

package/skills/mcp-builder/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: mcp-builder
+description: Build Model Context Protocol servers from specifications. Generates tool definitions, resource handlers, and test suites for MCP servers in TypeScript or Python (FastMCP).
+metadata:
+  author: runedev
+  version: "0.2.0"
+  layer: L2
+  model: sonnet
+  group: creation
+  tools: "Read, Write, Edit, Bash, Glob, Grep"
+---
+
+# mcp-builder
+
+## Purpose
+
+MCP server builder. Generates complete, tested MCP servers from a natural language description or specification. Handles tool definitions, resource handlers, input validation, error handling, configuration, tests, and documentation. Supports TypeScript (official SDK) and Python (FastMCP).
+
+## Triggers
+
+- Called by `cook` when MCP-related task detected (keywords: "MCP server", "MCP tool", "model context protocol")
+- Called by `scaffold` when MCP Server template selected
+- `/rune mcp-builder <description>` — manual invocation
+- Auto-trigger: when project contains `mcp.json`, `@modelcontextprotocol/sdk`, or `fastmcp` in dependencies
+
+## Calls (outbound)
+
+- `ba` (L2): if user description is vague — elicit requirements for what tools/resources the server should expose
+- `research` (L3): look up target API documentation, existing MCP servers for reference
+- `test` (L2): generate and run test suite for the server
+- `docs` (L2): generate server documentation (tool catalog, installation, configuration)
+- `verification` (L3): verify server builds and tests pass
+
+## Called By (inbound)
+
+- `cook` (L1): when MCP-related task detected
+- `scaffold` (L1): MCP Server template in Phase 5
+- User: `/rune mcp-builder` direct invocation
+
+## Executable Steps
+
+### Step 1 — Spec Elicitation
+
+If description is detailed enough (tools, resources, target API specified), proceed.
+If vague, ask targeted questions:
+
+1. **What tools should this MCP server expose?** (actions the AI can perform)
+2. **What resources does it manage?** (data the AI can read)
+3. **What external APIs does it connect to?** (if any)
+4. **TypeScript or Python?** (default: TypeScript with @modelcontextprotocol/sdk)
+5. **Authentication?** (API keys, OAuth, none)
+
+If user provides a detailed spec or existing API docs → extract answers, confirm.
+
+### Step 2 — Architecture Design
+
+Determine server structure based on spec:
+
+**TypeScript (default):**
+```
+mcp-server-<name>/
+├── src/
+│   ├── index.ts          — server entry point, tool/resource registration
+│   ├── tools/
+│   │   ├── <tool-name>.ts — one file per tool
+│   │   └── index.ts       — tool registry
+│   ├── resources/
+│   │   ├── <resource>.ts  — one file per resource type
+│   │   └── index.ts       — resource registry
+│   ├── lib/
+│   │   ├── client.ts      — external API client (if applicable)
+│   │   └── types.ts       — shared types
+│   └── config.ts          — environment variable validation
+├── tests/
+│   ├── tools/
+│   │   └── <tool-name>.test.ts
+│   └── resources/
+│       └── <resource>.test.ts
+├── package.json
+├── tsconfig.json
+├── .env.example
+└── README.md
+```
+
+**Python (FastMCP):**
+```
+mcp-server-<name>/
+├── src/
+│   ├── server.py          — FastMCP server with tool/resource decorators
+│   ├── tools/
+│   │   └── <tool_name>.py
+│   ├── resources/
+│   │   └── <resource>.py
+│   ├── lib/
+│   │   ├── client.py      — external API client
+│   │   └── types.py       — Pydantic models
+│   └── config.py          — settings via pydantic-settings
+├── tests/
+│   ├── test_<tool_name>.py
+│   └── test_<resource>.py
+├── pyproject.toml
+├── .env.example
+└── README.md
+```
+
+### Step 3 — Generate Server Code
+
+#### Tool Generation
+
+For each tool:
+
+**TypeScript:**
+```typescript
+import { z } from 'zod';
+
+export const toolName = {
+  name: 'tool_name',
+  description: 'What this tool does — used by AI to decide when to call it',
+  inputSchema: z.object({
+    param1: z.string().describe('Description for AI'),
+    param2: z.number().optional().describe('Optional parameter'),
+  }),
+  async handler(input: { param1: string; param2?: number }) {
+    // Implementation
+    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+  },
+};
+```
+
+**Python (FastMCP):**
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("server-name")
+
+@mcp.tool()
+async def tool_name(param1: str, param2: int | None = None) -> str:
+    """What this tool does — used by AI to decide when to call it."""
+    # Implementation
+    return json.dumps(result)
+```
+
+#### Resource Generation
+
+For each resource:
+- URI template with parameters
+- Read handler that returns structured content
+- List handler for collections
+
+#### Configuration
+
+Generate `.env.example` with all required environment variables:
+```env
+# Required
+API_KEY=your_api_key_here
+API_BASE_URL=https://api.example.com
+
+# Optional
+LOG_LEVEL=info
+CACHE_TTL=300
+```
+
+Generate config validation:
+```typescript
+// config.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  API_KEY: z.string().min(1, 'API_KEY is required'),
+  API_BASE_URL: z.string().url().default('https://api.example.com'),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+
+export const config = envSchema.parse(process.env);
+```
+
+### Step 4 — Generate Tests
+
+For each tool:
+- **Happy path**: valid input → expected output
+- **Validation**: invalid input → proper error message
+- **Error handling**: API failure → graceful error response
+- **Edge cases**: empty input, max limits, special characters
+
+For each resource:
+- **Read**: valid URI → expected content
+- **Not found**: invalid URI → proper error
+- **List**: collection URI → paginated results
+
+```typescript
+describe('tool_name', () => {
+  it('should return results for valid input', async () => {
+    const result = await toolName.handler({ param1: 'test' });
+    expect(result.content[0].type).toBe('text');
+    // Assert expected structure
+  });
+
+  it('should handle API errors gracefully', async () => {
+    // Mock API failure
+    const result = await toolName.handler({ param1: 'trigger-error' });
+    expect(result.isError).toBe(true);
+  });
+});
+```
+
+### Step 5 — Generate Documentation
+
+Produce README.md with:
+- Server description and purpose
+- Tool catalog (name, description, parameters, example usage)
+- Resource catalog (URI templates, content types)
+- Installation instructions (npm/pip, Claude Code config, Cursor config)
+- Configuration reference (all env vars with descriptions)
+- Example usage showing AI interactions
+
+Claude Code installation snippet:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["path/to/dist/index.js"],
+      "env": {
+        "API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### Step 6 — Verify
+
+Invoke `rune:verification`:
+- TypeScript: `tsc --noEmit` + `npm test`
+- Python: `mypy src/` + `pytest`
+- Ensure all tools respond correctly
+- Ensure configuration validation works
+
+## Output Format
+
+### Generated Project Structure
+
+**TypeScript:**
+```
+mcp-server-<name>/
+├── src/
+│   ├── index.ts          — server entry, tool/resource registration
+│   ├── tools/<name>.ts   — one file per tool (Zod input schema + handler)
+│   ├── resources/<name>.ts — one file per resource (URI template + reader)
+│   ├── lib/client.ts     — external API client
+│   ├── lib/types.ts      — shared TypeScript interfaces
+│   └── config.ts         — env var validation (Zod schema)
+├── tests/tools/<name>.test.ts — per-tool tests (happy, validation, error, edge)
+├── tests/resources/<name>.test.ts
+├── package.json, tsconfig.json, .env.example, README.md
+```
+
+**Python (FastMCP):**
+```
+mcp-server-<name>/
+├── src/
+│   ├── server.py         — FastMCP server with @mcp.tool() decorators
+│   ├── tools/<name>.py   — tool implementations
+│   ├── resources/<name>.py
+│   ├── lib/client.py     — external API client
+│   ├── lib/types.py      — Pydantic models
+│   └── config.py         — pydantic-settings
+├── tests/test_<name>.py
+├── pyproject.toml, .env.example, README.md
+```
+
+### README Structure
+- Server description + tool catalog (name, description, params, example)
+- Resource catalog (URI templates, content types)
+- Installation: Claude Code, Cursor, Windsurf config snippets
+- Configuration reference (env vars with descriptions)
+
+## Constraints
+
+1. MUST validate all tool inputs with Zod (TS) or Pydantic (Python) — never trust AI-provided inputs
+2. MUST handle API errors gracefully — return MCP error responses, don't crash the server
+3. MUST generate .env.example — never hardcode API keys or secrets
+4. MUST generate tests — no MCP server without test suite
+5. MUST generate installation docs for at least Claude Code — other IDEs are bonus
+6. MUST use official MCP SDK (@modelcontextprotocol/sdk for TS, fastmcp for Python)
+7. Tool descriptions MUST be AI-friendly — clear, specific, include parameter semantics
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Tool descriptions too vague for AI to use effectively | HIGH | Step 3: descriptions must explain WHEN to use the tool, not just WHAT it does |
+| Missing input validation → server crashes on bad input | HIGH | Constraint 1: Zod/Pydantic validation on all inputs |
+| Hardcoded API keys in generated code | CRITICAL | Constraint 3: always use env vars + .env.example |
+| Tests mock everything → no real integration coverage | MEDIUM | Generate both unit tests (mocked) and integration test template (real API) |
+| Generated server doesn't match MCP spec | HIGH | Use official SDK — don't hand-roll protocol handling |
+| Installation docs only for Claude Code | LOW | Include Cursor/Windsurf config examples too |
+
+## Done When
+
+- Server specification elicited (tools, resources, target API, language)
+- Architecture designed (file structure, module boundaries)
+- Server code generated (tools, resources, config, types)
+- Test suite generated (happy path, validation, errors, edge cases)
+- Documentation generated (README with tool catalog, installation, config)
+- Verification passed (types + tests)
+- Ready to install in Claude Code / Cursor / other IDEs
+
+## Cost Profile
+
+~3000-6000 tokens input, ~2000-5000 tokens output. Sonnet — MCP server generation is a structured code task, not architectural reasoning.

package/skills/onboard/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: onboard
+description: Auto-generate project context for AI sessions. Scans codebase, creates CLAUDE.md and .rune/ setup so every future session starts with full context.
+metadata:
+  author: runedev
+  version: "0.2.0"
+  layer: L2
+  model: sonnet
+  group: quality
+  tools: "Read, Write, Edit, Glob, Grep"
+---
+
+# onboard
+
+## Purpose
+
+Auto-generate project context for AI sessions. Scans the codebase and creates a CLAUDE.md project config plus .rune/ state directory so every future session starts with full context. Saves 10-20 minutes of re-explaining per session on undocumented projects.
+
+## Triggers
+
+- `/rune onboard` — manual invocation on any project
+- Called by `rescue` as Phase 0 (understand before refactoring)
+- Auto-trigger: when no CLAUDE.md exists in project root
+
+## Calls (outbound)
+
+- `scout` (L2): deep codebase scan — structure, frameworks, patterns, dependencies
+- `autopsy` (L2): when project appears messy or undocumented — health assessment
+
+## Called By (inbound)
+
+- User: `/rune onboard` manual invocation
+- `rescue` (L1): Phase 0 — understand legacy project before refactoring
+- `cook` (L1): if no CLAUDE.md found, onboard first
+
+## Output Files
+
+```
+project/
+├── CLAUDE.md              # Project config for AI sessions
+└── .rune/
+    ├── conventions.md     # Detected patterns & style
+    ├── decisions.md       # Empty, ready for session-bridge
+    ├── progress.md        # Empty, ready for session-bridge
+    ├── session-log.md     # Empty, ready for session-bridge
+    └── DEVELOPER-GUIDE.md # Human-readable onboarding for new developers
+```
+
+## Executable Steps
+
+### Step 1 — Full Scan
+Invoke `rune:scout` on the project root. Collect:
+- Top-level directory structure (depth 2)
+- All config files: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `composer.json`, `.nvmrc`, `.python-version`, `Pipfile.lock`, `poetry.lock`, `uv.lock`
+- Python environment markers: `.venv/`, `venv/`, `conda-meta/`, `.python-version`
+- Entry point files: `main.*`, `index.*`, `app.*`, `server.*`
+- Test directory names and test file patterns
+- CI/CD config files: `.github/workflows/`, `Makefile`, `Dockerfile`
+- README.md if present
+
+Do not read every source file — scout gives the skeleton. Use `Read` only on config files and entry points.
+
+### Step 2 — Detect Tech Stack
+From the scan output, determine with confidence:
+- **Language**: TypeScript | JavaScript | Python | Rust | Go | other
+- **Framework**: Next.js | Vite+React | SvelteKit | Express | FastAPI | Django | none | other
+- **Package manager**: npm | pnpm | yarn | pip | poetry | cargo | go modules
+- **Test framework**: Vitest | Jest | pytest | cargo test | go test | none
+- **Build tool**: tsc | vite | webpack | esbuild | cargo | none
+- **Linter/formatter**: ESLint | Biome | Ruff | Black | Clippy | none
+- **Python environment** (if Python project): detect from project markers:
+  - `.venv/` or `venv/` directory → venv
+  - `poetry.lock` → poetry
+  - `uv.lock` → uv
+  - `.python-version` → pyenv
+  - `conda-meta/` or `environment.yml` → conda
+  - `Pipfile.lock` → pipenv
+  - None found → none (note: recommend setting up a virtual environment)
+
+If a field cannot be determined with confidence, write "unknown" — do not guess.
+
+### Step 3 — Extract Conventions
+Read 3–5 representative source files (pick files with the most connections in the project — typically the main module, a route/controller file, and a utility file). Extract:
+- **Naming patterns**: camelCase | snake_case | PascalCase for files, functions, variables
+- **Import style**: named imports | default imports | barrel files (index.ts)
+- **Error handling pattern**: try/catch | Result type | error boundary | unhandled
+- **State management**: React Context | Zustand | Redux | Svelte stores | none
+- **API pattern**: REST | tRPC | GraphQL | SDK | none
+- **Test structure**: co-located (`file.test.ts`) | separate directory (`tests/`) | none
+
+Write extracted conventions as bullet points — be specific, not generic.
+
+### Step 4 — Generate CLAUDE.md
+Use `Write` to create `CLAUDE.md` at the project root. Populate every section using data from Steps 2–3. Do not leave template placeholders — if data is unknown, write "unknown" or omit the section. Use the template below as the exact structure.
+
+If a `CLAUDE.md` already exists, use `Read` to load it first, then merge — preserve any human-written sections (comments starting with `<!-- manual -->`) and update auto-detected sections only.
+
+### Step 5 — Initialize .rune/ Directory
+Use `Bash` to create the directory: `mkdir -p .rune`
+
+Use `Write` to create each file:
+- `.rune/conventions.md` — paste the extracted conventions from Step 3 in full detail
+- `.rune/decisions.md` — create with header `# Architecture Decisions` and one placeholder row in a markdown table (Date | Decision | Rationale | Status)
+- `.rune/progress.md` — create with header `# Progress Log` and one placeholder entry
+- `.rune/session-log.md` — create with header `# Session Log` and current date as first entry
+
+### Step 6b — Generate DEVELOPER-GUIDE.md
+
+Use the data from Steps 2–3 to generate `.rune/DEVELOPER-GUIDE.md` — a human-readable onboarding guide for new team members joining the project. This is NOT AI context. This is plain English for humans.
+
+Use `Write` to create `.rune/DEVELOPER-GUIDE.md` with this template:
+
+```markdown
+# Developer Guide: [Project Name]
+
+## What This Does
+[2 sentences max. What problem does this project solve? Who uses it?]
+
+## Quick Setup
+[Copy-paste commands to get from zero to running locally]
+```bash
+# [Python projects] Activate virtual environment
+[detected activation command — e.g., source .venv/bin/activate | poetry shell | uv venv && source .venv/bin/activate]
+
+# Install dependencies
+[detected command — e.g., pip install -e ".[dev]" | poetry install | npm install]
+
+# Run development server
+[detected command]
+
+# Run tests
+[detected command]
+```
+
+## Key Files
+[5–10 most important files with one-line description each]
+- `[path]` — [what it does]
+
+## How to Contribute
+1. Fork or branch from main
+2. Make changes, run tests: `[test command]`
+3. Open a PR — describe what and why
+
+## Common Issues
+[Top 3 "it doesn't work" situations with fixes. Only include issues you can infer from the codebase — e.g., missing .env, wrong Node version, database not running]
+
+[Python projects — always include these if applicable:]
+- **ModuleNotFoundError** → Virtual environment not activated. Run: `[activation command]`
+- **ImportError: cannot import name X** → Dependencies outdated. Run: `[install command]`
+- **PYTHONPATH issues** → If using src layout, install in editable mode: `pip install -e .`
+
+## Who to Ask
+[If git log reveals consistent contributors, list them. Otherwise omit this section.]
+```
+
+If `.rune/DEVELOPER-GUIDE.md` already exists, skip and log **INFO**: "Skipped existing .rune/DEVELOPER-GUIDE.md — manual content preserved."
+
+### Step 6c — Suggest L4 Extension Packs
+
+Based on the detected tech stack from Step 2, recommend relevant L4 extension packs. Use the mapping table below to find applicable packs. Only suggest packs that match the detected stack — do not suggest all packs.
+
+| Detected Stack | Suggest Pack | Why |
+|----------------|-------------|-----|
+| React, Next.js, Vue, Svelte, SvelteKit | `@rune/ui` | Frontend component patterns, design system, accessibility audit |
+| Express, Fastify, FastAPI, Django, NestJS, Go HTTP | `@rune/backend` | API patterns, auth flows, middleware, rate limiting |
+| Docker, GitHub Actions, Kubernetes, Terraform, CI/CD config | `@rune/devops` | Container patterns, deployment pipelines, infrastructure as code |
+| React Native, Expo, Flutter, SwiftUI | `@rune/mobile` | Mobile architecture, navigation patterns, offline sync |
+| Security-focused codebase (auth, payments, HIPAA/PCI markers) | `@rune/security` | Threat modeling, OWASP flows, compliance patterns |
+| Trading, finance, pricing, portfolio, market data | `@rune/trading` | Market data validation, risk calculation, backtesting patterns |
+| Subscription billing, tenant isolation, feature flags | `@rune/saas` | Multi-tenancy, billing integration, feature flag patterns |
+| Cart, checkout, product catalog, inventory, payments | `@rune/ecommerce` | Cart patterns, payment flows, inventory management |
+| ML models, training pipelines, embeddings, LLM integration | `@rune/ai-ml` | Model evaluation, prompt patterns, inference optimization |
+| Game loop, physics, entity systems, multiplayer | `@rune/gamedev` | Game architecture, ECS patterns, netcode |
+| CMS, blog, newsletter, SEO, content workflows | `@rune/content` | Content modeling, SEO patterns, editorial workflows |
+| Analytics, dashboards, metrics, data pipelines, BI | `@rune/analytics` | Data modeling, visualization patterns, pipeline architecture |
+
+If 0 packs match: omit this section from the report (no suggestions is correct for a generic project).
+
+**Community pack discovery**: Also check if `.rune/community-packs/registry.json` exists. If it does, list installed community packs alongside core pack suggestions. If community packs are installed, include them under a `### Installed Community Packs` subsection.
+
+If ≥1 packs match: include in the Onboard Report under a `### Suggested L4 Packs` section:
+
+```
+### Suggested L4 Packs
+Based on your detected stack ([detected frameworks]), these extension packs may be useful:
+
+- **@rune/[pack]** — [one-line reason based on detected stack]
+  Install: [link or command when available]
+```
+
+### Step 7 — Commit
+Use `Bash` to stage and commit the generated files:
+```bash
+git add CLAUDE.md .rune/ && git commit -m "chore: initialize rune project context"
+```
+
+If `git` is not available or the directory is not a git repo, skip this step and add an INFO note to the report: "Not a git repository — files written but not committed."
+
+If any of the `.rune/` files already exist, do not overwrite them (they may contain human-written decisions). Log **INFO**: "Skipped existing .rune/[file] — manual content preserved."
+
+## CLAUDE.md Template
+
+```markdown
+# [Project Name] — Project Configuration
+
+## Overview
+[Auto-detected description from README or entry point comments]
+
+## Tech Stack
+- Framework: [detected]
+- Language: [detected]
+- Package Manager: [detected]
+- Test Framework: [detected]
+- Build Tool: [detected]
+- Linter: [detected]
+- Python Environment: [detected — venv/poetry/uv/conda/pyenv/pipenv/none] (only if Python project)
+
+## Directory Structure
+[Generated tree with one-line annotations per directory]
+
+## Conventions
+- Naming: [detected patterns — specific, not generic]
+- Error handling: [detected pattern]
+- State management: [detected pattern]
+- API pattern: [detected pattern]
+- Test structure: [detected pattern]
+
+## Commands
+- Install: [detected command]
+- Dev: [detected command]
+- Build: [detected command]
+- Test: [detected command]
+- Lint: [detected command]
+
+## Key Files
+- Entry point: [absolute path]
+- Config: [absolute paths]
+- Routes/API: [absolute paths]
+```
+
+## Output Format
+
+```
+## Onboard Report
+- **Project**: [name] | **Framework**: [detected] | **Language**: [detected]
+- **Files**: [count] | **LOC**: [estimate] | **Modules**: [count]
+
+### Generated
+- CLAUDE.md (project configuration)
+- .rune/conventions.md (detected patterns)
+- .rune/decisions.md (initialized)
+- .rune/progress.md (initialized)
+- .rune/session-log.md (initialized)
+- .rune/DEVELOPER-GUIDE.md (human onboarding guide)
+
+### Skipped (already exist)
+- [list of files not overwritten]
+
+### Observations
+- [notable patterns or anomalies found]
+- [potential issues detected]
+- [recommendations for the developer]
+
+### Suggested L4 Packs
+- **@rune/[pack]** — [reason] (only shown if applicable packs detected)
+```
+
+## Constraints
+
+1. MUST scan actual project files — never generate CLAUDE.md from assumptions
+2. MUST detect and respect existing CLAUDE.md content — merge, don't overwrite
+3. MUST include: build commands, test commands, lint commands, project structure
+4. MUST NOT include obvious/generic advice ("write clean code", "use meaningful names")
+5. MUST verify generated commands actually work by running them
+6. MUST NOT overwrite existing .rune/ files — always preserve human-written content
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| CLAUDE.md generated from README alone (no file scan) | CRITICAL | Step 1 MUST invoke scout — never skip actual file scanning |
+| DEVELOPER-GUIDE.md contains generic placeholder text not derived from project | HIGH | Every section must reference actual detected commands, files, and patterns — no generic advice |
+| Overwriting existing .rune/ files with manual content | CRITICAL | Check file existence before every Write — skip and log INFO if exists |
+| Common Issues section fabricated (no actual issues detected) | MEDIUM | Only list issues inferable from codebase (missing .env, Node version, etc.) — omit section if none found |
+
+## Done When
+
+- CLAUDE.md written (or merged) with all detected tech stack fields populated
+- .rune/ directory initialized with conventions, decisions, progress, session-log
+- .rune/DEVELOPER-GUIDE.md written with setup commands from actual scan
+- All generated commands verified to exist in package.json/Makefile/etc.
+- Onboard Report emitted with Generated + Skipped + Observations sections
+
+## Cost Profile
+
+~2000-5000 tokens input, ~1000-2000 tokens output. Sonnet for analysis quality.