mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/mcp-server-patterns/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: mcp-server-patterns
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: mcp server, model context protocol, mcp tools, mcp resources, mcp prompts, stdio transport, streamable http, mcp registration, mcp handler, mcp schema, build mcp, mcp patterns
+---
+
+# Skill — MCP Server Patterns
+
+## When this skill activates
+
+When designing, building, or debugging Model Context Protocol (MCP) servers that
+expose tools, resources, or prompts to AI agents. Use when implementing the server
+side of MCP — registering capabilities, handling requests, managing transport, and
+following protocol conventions.
+
+MCP is the standard protocol for extending AI agents with external capabilities.
+A well-built MCP server is the difference between an agent that can only talk and
+one that can act.
+
+## Mandatory actions when this skill is active
+
+### Before building the MCP server
+
+1. **Identify capability types needed:**
+
+   | Type | Purpose | Agent interaction | Example |
+   |------|---------|-------------------|---------|
+   | **Tools** | Actions agents invoke | Agent calls with args, gets result | `create-file`, `run-query`, `send-email` |
+   | **Resources** | Data agents read | Agent requests by URI, gets content | `file://`, `db://schema`, `config://env` |
+   | **Prompts** | Reusable templates | Agent fills arguments, gets formatted prompt | `code-review`, `summarize`, `translate` |
+
+2. **Choose transport:**
+
+   | Transport | Use when | Characteristics |
+   |-----------|----------|-----------------|
+   | **stdio** | Local tools, CLI integration, dev/test | Process-based, simple, synchronous feel |
+   | **Streamable HTTP** | Remote servers, multi-client, production | Scalable, stateless, HTTP-based |
+
+3. **Design the schema contract:**
+   - Every tool must have a typed input schema (Zod for TypeScript, Pydantic for Python)
+   - Every resource must have a URI pattern and content type
+   - Every prompt must declare its arguments with descriptions
+   - Write the schema FIRST, implement SECOND (contract-first design)
+
+4. **Plan error handling strategy:**
+   - Tool errors: return structured error with code and message (never throw unhandled)
+   - Resource not found: return appropriate MCP error code
+   - Validation failures: return detailed field-level errors
+   - Never expose internal stack traces to the client
+
+### During MCP server implementation
+
+**Project structure (TypeScript/Node.js):**
+```
+mcp-server-[name]/
+  src/
+    index.ts              # Server initialization and transport setup
+    tools/
+      index.ts            # Tool registration aggregator
+      [tool-name].ts      # One file per tool
+    resources/
+      index.ts            # Resource registration aggregator
+      [resource-name].ts  # One file per resource
+    prompts/
+      index.ts            # Prompt registration aggregator
+      [prompt-name].ts    # One file per prompt
+    lib/
+      errors.ts           # Custom MCP error classes
+      schemas.ts          # Shared Zod schemas
+  tests/
+    tools/
+      [tool-name].test.ts
+    integration/
+      stdio.test.ts       # Full server integration via stdio
+  package.json
+  tsconfig.json
+```
+
+**Tool registration pattern:**
+```typescript
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+const InputSchema = z.object({
+  filePath: z.string().describe("Absolute path to the target file"),
+  content: z.string().describe("Content to write to the file"),
+  overwrite: z.boolean().default(false).describe("Whether to overwrite existing files"),
+});
+
+export function registerCreateFileTool(server: McpServer) {
+  server.tool(
+    "create-file",
+    "Create a new file with the specified content at the given path",
+    InputSchema.shape,
+    async ({ filePath, content, overwrite }) => {
+      // Validate path is within allowed directories
+      validatePath(filePath);
+
+      // Check existing file
+      if (!overwrite && await fileExists(filePath)) {
+        return {
+          content: [{ type: "text", text: `Error: File already exists at ${filePath}. Use overwrite: true to replace.` }],
+          isError: true,
+        };
+      }
+
+      await writeFile(filePath, content);
+
+      return {
+        content: [{ type: "text", text: `Successfully created file at ${filePath} (${content.length} bytes)` }],
+      };
+    }
+  );
+}
+```
+
+**Resource registration pattern:**
+```typescript
+export function registerFileResource(server: McpServer) {
+  // Static resource
+  server.resource(
+    "project-config",
+    "config://project",
+    "The project's configuration file",
+    async (uri) => ({
+      contents: [{
+        uri: uri.href,
+        mimeType: "application/json",
+        text: await readFile("./config.json", "utf-8"),
+      }],
+    })
+  );
+
+  // Dynamic resource with URI template
+  server.resource(
+    "source-file",
+    new ResourceTemplate("file:///{path}", { list: undefined }),
+    "Read a source file by path",
+    async (uri, { path }) => ({
+      contents: [{
+        uri: uri.href,
+        mimeType: getMimeType(path),
+        text: await readFile(path, "utf-8"),
+      }],
+    })
+  );
+}
+```
+
+**Prompt registration pattern:**
+```typescript
+export function registerCodeReviewPrompt(server: McpServer) {
+  server.prompt(
+    "code-review",
+    "Generate a structured code review for the given diff",
+    {
+      diff: z.string().describe("The git diff to review"),
+      severity: z.enum(["quick", "thorough", "security"]).default("thorough")
+        .describe("Review depth level"),
+    },
+    ({ diff, severity }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `Review this code diff at ${severity} level:\n\n${diff}\n\nProvide findings as: [SEVERITY] file:line - description`,
+        },
+      }],
+    })
+  );
+}
+```
+
+**Transport setup:**
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+const server = new McpServer({
+  name: "my-mcp-server",
+  version: "1.0.0",
+});
+
+// Register all capabilities
+registerTools(server);
+registerResources(server);
+registerPrompts(server);
+
+// stdio transport (local/CLI)
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// OR: Streamable HTTP transport (remote/production)
+// const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+// app.post("/mcp", async (req, res) => { await transport.handleRequest(req, res); });
+```
+
+**Error handling (mandatory):**
+```typescript
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+
+// In tool handlers:
+if (!isValid(input)) {
+  throw new McpError(
+    ErrorCode.InvalidParams,
+    `Invalid input: ${validationErrors.join(", ")}`
+  );
+}
+
+// For "soft" errors (operation failed but not a protocol error):
+return {
+  content: [{ type: "text", text: `Operation failed: ${reason}` }],
+  isError: true,
+};
+```
+
+**Security considerations:**
+- Validate all file paths against an allowlist of directories
+- Sanitize inputs that will be used in shell commands or SQL
+- Rate limit tool invocations if exposed over HTTP
+- Log all tool invocations for audit trail
+- Never expose secrets through resource responses
+- Use environment variables for sensitive configuration
+
+### After MCP server implementation
+
+1. **Testing protocol:**
+   - Unit test each tool handler with valid inputs, invalid inputs, and edge cases
+   - Integration test via stdio transport (spawn server, send requests, verify responses)
+   - Use MCP Inspector for interactive testing during development:
+     ```bash
+     npx @modelcontextprotocol/inspector node dist/index.js
+     ```
+   - Test error paths: malformed requests, missing required fields, timeout scenarios
+   - Verify resource URIs resolve correctly under all template patterns
+
+2. **Documentation requirements:**
+   - README with: what the server does, prerequisites, installation, configuration
+   - Tool catalog: name, description, input schema, example usage, error cases
+   - Resource catalog: URI patterns, content types, access patterns
+   - Configuration: all environment variables with types and defaults
+
+3. **Deployment checklist:**
+   - `package.json` has correct `bin` entry for stdio servers
+   - `"type": "module"` set if using ESM
+   - All dependencies are production dependencies (not devDependencies)
+   - Server starts cleanly with no warnings or unhandled rejections
+   - Graceful shutdown on SIGTERM/SIGINT
+
+## Self-check before task completion
+
+Before marking an MCP server task done:
+
+- [ ] Did I define typed input schemas for every tool (Zod/Pydantic)?
+- [ ] Did I implement proper error handling (McpError with codes, isError for soft failures)?
+- [ ] Did I validate and sanitize all inputs (especially file paths and shell args)?
+- [ ] Did I write integration tests using stdio transport?
+- [ ] Did I test with MCP Inspector to verify the server works interactively?
+- [ ] Did I document all tools, resources, and prompts with examples?
+- [ ] Did I choose the appropriate transport for the deployment context?
+- [ ] Does the server start cleanly and shut down gracefully?

package/.mindforge/skills/media-streaming/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: media-streaming
+version: 1.0.0
+min_mindforge_version: 10.2.0
+status: stable
+triggers: media streaming architecture, video transcoding pipeline, adaptive bitrate streaming, DRM implementation, live streaming system, audio streaming, media delivery network, HLS DASH streaming, media processing pipeline, content protection, video on demand, streaming infrastructure
+compose: cdn-optimization
+---
+
+# Skill — Media Streaming
+
+## When this skill activates
+This skill activates when building video/audio streaming platforms, transcoding pipelines, adaptive bitrate delivery (HLS/DASH), DRM content protection, live streaming systems, CDN integration, or video-on-demand (VOD) architectures.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Design transcoding pipeline: ingest source video (MP4, MOV, AVI) → extract metadata (resolution, bitrate, codec, duration) → transcode to multiple renditions (4K/1080p/720p/480p/360p), audio tracks (AAC 128kbps stereo), generate HLS/DASH manifests (.m3u8/.mpd), output to object storage (S3), with job queue (SQS) and status webhooks
+2. Model adaptive bitrate delivery: client requests master playlist (m3u8) → server returns variant streams (bitrate ladder: 8 Mbps, 5 Mbps, 2.5 Mbps, 1 Mbps, 500 kbps) → client measures bandwidth → switches to appropriate quality → seamless transition without buffering
+3. Map DRM content protection workflow: encrypt video segments (AES-128 or CBCS), generate license keys (Widevine, FairPlay, PlayReady), store keys in key server, client requests license → key server validates entitlement (subscription active, geo-restrictions) → returns decryption key → client decrypts and plays
+
+### During implementation
+- Implement transcoding with FFmpeg or cloud services (AWS MediaConvert, Azure Media Services): configure encoding ladder (GOP size 2s, H.264 High profile, AAC audio), generate thumbnails (every 10s), extract VTT subtitles, optimize for web (moov atom at start for MP4), enable hardware acceleration (GPU encoding for faster processing)
+- Build HLS/DASH streaming with segmentation: split video into 6-second segments (TS for HLS, MP4 for DASH), generate manifest with variant streams (EXT-X-STREAM-INF for bitrate/resolution), enable discontinuity tags for ad insertion, support live DVR (sliding window of last 2 hours)
+- Design CDN delivery with edge caching: upload to origin (S3 bucket), configure CloudFront distribution, set TTL policies (video segments: 7 days, manifests: 60s for VOD, 5s for live), enable signed URLs for protected content (expire after 2 hours), use geo-restriction for licensing compliance
+- Implement DRM integration: encrypt video during transcoding (specify key ID), integrate with key server (AWS SPEKE, Axinom, BuyDRM), client-side DRM initialization (Shaka Player for DASH, hls.js with EME for HLS), handle license renewal (for long-form content >2 hours), support offline downloads with persistent licenses
+- Build player analytics: track playback events (video_start, video_pause, video_complete, error, buffering), measure quality metrics (startup time, rebuffering ratio, bitrate distribution), aggregate by user/video/device, identify issues (high rebuffering on specific ISP, low bitrate selection on mobile)
+
+### After implementation
+- Validate streaming quality: measure startup latency (<2s for 90th percentile), rebuffering ratio (<1% of playback time), bitrate adaptation responsiveness (switch within 10s of bandwidth change), A/V sync (<200ms drift), and seek accuracy (land within 500ms of target time)
+- Test DRM enforcement: attempt playback without valid license (should fail), expired license (should prompt re-authentication), screen recording detection (Widevine L1 blocks HDMI capture on Android), device limit enforcement (max 3 concurrent streams per account)
+- Execute load testing for live streams: simulate 10K+ concurrent viewers, measure origin-to-edge latency (should be <3s for live), segment availability (all segments delivered before next segment starts), CDN cache hit ratio (>95% after warm-up), and origin load (offloaded to CDN)
+
+## Self-check before task completion
+- [ ] Transcoding pipeline functional: ingest source video, transcode to multiple renditions (4K to 360p), generate HLS/DASH manifests, output to object storage
+- [ ] Adaptive bitrate streaming: bitrate ladder defined (8 Mbps to 500 kbps), client switches based on bandwidth, seamless quality transitions
+- [ ] DRM content protection: video encrypted (AES-128/CBCS), license server integrated (Widevine/FairPlay/PlayReady), entitlement validation before key delivery
+- [ ] CDN delivery optimized: edge caching configured, TTL policies set (long for segments, short for manifests), signed URLs for protected content
+- [ ] Player analytics tracked: playback events (start, pause, complete, error), quality metrics (startup time, rebuffering, bitrate), aggregated reports
+- [ ] Live streaming supported: real-time segmentation (6s segments), sliding window DVR (last 2 hours), low latency (<3s origin-to-edge)
+- [ ] Quality targets met: startup <2s, rebuffering <1%, bitrate adaptation <10s, A/V sync <200ms, seek accuracy <500ms

package/.mindforge/skills/meeting-architecture/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: meeting-architecture
+version: 1.0.0
+min_mindforge_version: 10.3.0
+status: stable
+triggers: meeting architecture, meeting design pattern, decision documentation, async-first communication, standup optimization, meeting efficiency, RFC process, architecture decision record, async collaboration, meeting agenda design, meeting decision log, remote meeting facilitation
+---
+
+# Meeting Architecture
+
+## When this skill activates
+
+This skill activates when designing effective meetings, implementing async-first communication patterns, optimizing standups, documenting decisions, creating RFC processes, or facilitating remote meetings. It applies to tech leads, engineering managers, and senior engineers responsible for team communication effectiveness.
+
+## Mandatory actions when this skill is active
+
+### Before scheduling any meeting
+
+1. **Apply the async-first test** — Can this be an email, Slack message, document, or recorded video? Only schedule a synchronous meeting if you need real-time discussion, debate, or decision-making.
+2. **Define the meeting purpose** — Is it informational (status update), collaborative (brainstorming), or decisional (approve/reject proposal)? Different purposes require different formats.
+3. **Identify required vs optional attendees** — Required: people who must participate for the meeting to succeed. Optional: people who benefit from being there but aren't essential. Respect people's time.
+4. **Create a clear agenda** — No agenda = no meeting. Agenda should include: topics, time allocation, desired outcomes, and pre-reads. Send agenda 24 hours in advance.
+
+### During meeting design
+
+#### Meeting Type Catalog
+
+**1. Daily Standup (15 minutes max)**
+- **Purpose**: Synchronize team, surface blockers, maintain momentum.
+- **Format**: Each person answers: (1) What did I accomplish yesterday? (2) What am I working on today? (3) Am I blocked?
+- **Optimizations**:
+  - Keep it to 15 minutes. If you need more time, the team is too big or the updates are too detailed.
+  - Do it async if possible (Slack standup bot, Geekbot, GitHub comments on project board).
+  - Timebox each person to 1-2 minutes. Use a timer.
+  - Blockers get discussed after standup, not during. Don't derail everyone's focus.
+- **Pitfall**: Standup becomes a status report to the manager. It should be peer-to-peer synchronization, not upward reporting.
+
+**2. Sprint Planning (1-2 hours)**
+- **Purpose**: Commit to work for the upcoming sprint.
+- **Format**: Review backlog, prioritize, estimate, assign ownership, identify dependencies.
+- **Pre-work**: Product or tech lead preps the backlog. Engineers review tickets ahead of time. Don't do backlog grooming during sprint planning.
+- **Optimizations**:
+  - Timebox story estimation. Use t-shirt sizes (S/M/L) or Fibonacci (1/2/3/5/8) to avoid false precision.
+  - Identify blockers early. If a task depends on another team, escalate before the sprint starts.
+  - Set a realistic capacity. Don't overcommit. Leave 20% buffer for unplanned work (bugs, support, incidents).
+- **Pitfall**: Spending 30 minutes debating whether a task is a 3 or a 5. Estimates are guesses. Move on.
+
+**3. Retrospective (45-60 minutes)**
+- **Purpose**: Reflect on what went well, what didn't, and how to improve.
+- **Format**: What went well? What went poorly? What should we start/stop/continue doing?
+- **Facilitation**:
+  - Everyone contributes. Silence from some people means they're not engaged or don't feel safe.
+  - Focus on systems, not individuals. "Code reviews are too slow" is better than "Alice didn't review my PR."
+  - Action items must have owners and deadlines. Otherwise they're wishes, not commitments.
+- **Optimizations**:
+  - Rotate facilitator. Prevents one person from dominating.
+  - Use techniques like Start/Stop/Continue, 4Ls (Liked/Learned/Lacked/Longed For), or Rose/Bud/Thorn.
+  - Review action items from the previous retro. Did we follow through? If not, why?
+- **Pitfall**: Retrospectives devolve into venting sessions. Keep it constructive.
+
+**4. Design Review / Architecture Review (60-90 minutes)**
+- **Purpose**: Vet technical designs before implementation. Catch issues early.
+- **Format**: Presenter shares design doc (sent 24-48 hours in advance). Team probes assumptions, identifies edge cases, suggests alternatives.
+- **Pre-work**: Attendees read the design doc before the meeting. Don't use meeting time for reading.
+- **Optimizations**:
+  - Use a design doc template: problem statement, requirements, proposed solution, alternatives considered, tradeoffs, open questions.
+  - Assign a devil's advocate. Their job is to poke holes. Prevents groupthink.
+  - Document decisions in the design doc during the meeting. Don't rely on memory.
+- **Pitfall**: Rubber-stamping designs that are already implemented. Design reviews should happen before code is written, not after.
+
+**5. Incident Postmortem (60 minutes)**
+- **Purpose**: Learn from incidents, identify systemic improvements.
+- **Format**: Timeline, root cause analysis, what went well, what went poorly, action items.
+- **Facilitation**:
+  - Blameless. Focus on systems, not individuals.
+  - Use the Five Whys to get to root cause.
+  - Every action item needs an owner and a deadline.
+- **Optimizations**:
+  - Share postmortem document 24 hours before the meeting. Use meeting time for discussion, not writing.
+  - Invite all incident responders + relevant stakeholders.
+  - Timebox to 60 minutes. If you can't finish, schedule a follow-up.
+- **Pitfall**: Postmortems that generate 15 action items but complete zero. Prioritize. Pick the top 3 and execute.
+
+**6. 1:1s (30 minutes, weekly or bi-weekly)**
+- **Purpose**: Manager-engineer relationship building, career development, feedback, unblocking.
+- **Format**: Open agenda. Employee drives the conversation. Manager listens, coaches, provides context.
+- **Optimizations**:
+  - Don't use 1:1s for status updates. That's what standups and project boards are for.
+  - Ask open-ended questions: "What's on your mind?" "What's frustrating you?" "What do you need from me?"
+  - Take notes. Reference previous 1:1s. Show that you remember and care.
+  - Cancel other meetings, not 1:1s. 1:1s are sacred.
+- **Pitfall**: Manager dominates the conversation. The 1:1 is for the employee, not the manager.
+
+**7. RFC (Request for Comments) Review (Async + Optional Sync Meeting)**
+- **Purpose**: Propose architectural changes, gather feedback, build consensus.
+- **Format**: Author writes RFC document (problem, proposal, alternatives, tradeoffs). Team comments asynchronously. Optional sync meeting to resolve open questions.
+- **Optimizations**:
+  - Set a comment deadline (e.g., 5 business days). After deadline, author addresses feedback and makes a decision.
+  - Use a template. Consistency reduces cognitive load.
+  - Distinguish between blocking concerns (correctness, security) and non-blocking suggestions (style, minor optimizations).
+- **Pitfall**: RFCs that linger for weeks with no decision. Set a decision deadline and stick to it.
+
+#### Async-First Communication Patterns
+
+- **Default to async** — Status updates, announcements, design proposals, and decisions should be written and shared asynchronously. Reserve sync meetings for real-time collaboration.
+- **Use threads, not channels** — In Slack or Teams, use threads for discussions. Keeps channels scannable. Main channel is for announcements, threads are for details.
+- **Document decisions publicly** — Every significant decision (architectural choice, roadmap change, policy update) gets written down in a shared doc or wiki. Don't let decisions live only in someone's head or in a Slack thread.
+- **Record meetings** — For all-hands, demos, or important discussions, record the meeting and share the link. Accommodates different time zones and allows people to catch up asynchronously.
+- **Set response time expectations** — Async doesn't mean "respond whenever." Set norms: Slack messages within 4 hours during work hours, emails within 24 hours, RFCs within 5 days.
+
+#### Decision Documentation
+
+- **Use Architecture Decision Records (ADRs)** — Every significant architectural decision gets a lightweight ADR:
+  - **Title**: Short description (e.g., "Use Postgres for primary datastore")
+  - **Context**: What's the situation?
+  - **Decision**: What did we decide?
+  - **Consequences**: What are the tradeoffs?
+  - **Alternatives Considered**: What else did we evaluate?
+- **Maintain a decision log** — Store ADRs in the repo (`docs/adr/`) or wiki. Version control ensures decisions are traceable.
+- **Link decisions to code** — In PRs, reference the ADR. Future engineers will thank you.
+
+#### Remote Meeting Facilitation
+
+- **Video on by default** — Encourages engagement. People are less likely to multitask when video is on.
+- **Use collaborative tools** — Miro, Figma, Google Docs for real-time collaboration. Screen sharing alone is passive.
+- **Timebox discussions** — Use a timer. When time's up, move on. Prevents bikeshedding.
+- **Mute when not speaking** — Reduces background noise. Unmute to contribute.
+- **Use breakout rooms for large meetings** — If you have >8 people, break into smaller groups for brainstorming. Reconvene to share findings.
+
+### After meetings
+
+- **Publish meeting notes within 2 hours** — Key decisions, action items, owners, deadlines. Share in the team channel or wiki.
+- **Track action items to completion** — Review action items in the next meeting. If they're not getting done, either they weren't important or there's a resourcing issue.
+- **Measure meeting effectiveness** — Periodically survey the team: "Are meetings productive? Too many? Too few?" Course-correct based on feedback.
+- **Cancel recurring meetings that lost their purpose** — If a meeting becomes a status update or no one has updates, cancel it. Don't let zombie meetings linger.
+
+## Self-check before task completion
+
+- [ ] Meeting passes the async-first test (can't be an email or doc)
+- [ ] Agenda is created and shared 24 hours in advance with topics, time allocation, and desired outcomes
+- [ ] Required vs optional attendees are explicitly identified
+- [ ] Meeting type is appropriate for the goal (standup, planning, retro, design review, 1:1)
+- [ ] Design reviews and RFC reviews require pre-reading; meeting time is for discussion, not reading
+- [ ] Decisions are documented using ADRs or decision logs and shared publicly
+- [ ] Meeting notes with action items, owners, and deadlines are published within 2 hours
+- [ ] Recurring meetings are reviewed quarterly and canceled if they've lost their purpose

package/.mindforge/skills/mentoring-patterns/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: mentoring-patterns
+version: 1.0.0
+min_mindforge_version: 10.3.0
+status: stable
+triggers: mentoring developer, pair programming pedagogy, code review teaching, career ladder design, junior developer growth, technical mentorship, developer onboarding mentoring, skill gap assessment, growth plan engineering, coaching engineers, feedback delivery, mentee progress tracking
+---
+
+# Mentoring Patterns
+
+## When this skill activates
+
+This skill activates when mentoring junior or mid-level developers, conducting pair programming sessions, giving pedagogical code reviews, designing career growth plans, assessing skill gaps, or coaching engineers through challenging technical problems. It applies to senior engineers, tech leads, and engineering managers responsible for developing others.
+
+## Mandatory actions when this skill is active
+
+### Before starting mentorship
+
+1. **Assess current skill level** — Don't assume. Ask mentee to walk through a recent PR or design doc. Identify gaps in fundamentals (data structures, testing, debugging) vs advanced topics (distributed systems, performance optimization).
+2. **Understand mentee's goals** — Are they aiming for senior engineer? Staff? Management? Different trajectories require different skill development. Don't project your own career path onto them.
+3. **Establish mentorship contract** — Frequency (weekly 1:1s? ad-hoc?), topics (code review? architecture? career?), communication channels, and how to ask for help. Implicit expectations cause friction.
+4. **Identify mentee's learning style** — Do they learn by reading (send docs), watching (pair program), or doing (give them a project)? Mismatch between teaching style and learning style wastes time.
+
+### During mentorship activities
+
+#### Pair Programming Pedagogy
+
+- **Use driver-navigator pattern** — Junior is driver (typing), senior is navigator (guiding). Keeps mentee engaged and forces them to articulate their reasoning. Don't grab the keyboard.
+- **Ask guiding questions, don't give answers** — Instead of "Use a hash map here," ask "How would you optimize this lookup?" Let them arrive at the solution. Spoon-feeding creates dependency.
+- **Narrate your thought process** — When you're the driver, verbalize your reasoning: "I'm adding this null check because..." or "I'm writing the test first because...". Juniors can't see inside your head.
+- **Timebox exploration** — Let mentee struggle for 10-15 minutes. If stuck, give a hint, not the solution. If still stuck after 30 minutes, show the approach and explain why.
+- **Refactor together** — Take working but messy code and refactor it as a pair. Teaches that code quality is iterative, not achieved on the first pass.
+
+#### Code Review Teaching
+
+- **Classify feedback by severity** — Critical (security, correctness, data loss), Major (performance, maintainability, architectural misalignment), Minor (style, readability). Juniors often can't distinguish signal from noise.
+- **Explain the "why," not just the "what"** — Don't say "Extract this into a function." Say "This block is duplicated in 3 places. Extracting it into a function ensures future bug fixes apply everywhere, not just one call site."
+- **Use the "teach, don't tell" pattern** — First review: point out the issue and suggest a fix. Second occurrence: point out the issue, ask them to suggest a fix. Third occurrence: ask if they see the issue. Eventually they internalize the pattern.
+- **Limit feedback to 3-5 key points per review** — Wall-of-text reviews overwhelm. Pick the most important lessons. Other issues can wait for the next PR.
+- **Celebrate improvements** — When mentee applies feedback from a previous review, call it out: "Great null handling here, much cleaner than last time." Positive reinforcement accelerates learning.
+
+#### Career Growth Plans
+
+- **Use the skill matrix** — List skills required for the next level (e.g., to reach senior: owns 1-2 services end-to-end, writes design docs, mentors 1-2 juniors). Rate mentee as Beginner / Intermediate / Advanced / Expert on each skill.
+- **Create 30-60-90 day goals** — 30 days: quick wins (improve test coverage on X service, ship Y feature). 60 days: medium scope (lead Z project, mentor junior on onboarding). 90 days: stretch goals (present at team meeting, write architecture proposal).
+- **Identify growth projects** — Assign projects slightly above their current level. Too easy = no learning. Too hard = frustration and failure. The sweet spot is 20% beyond their comfort zone.
+- **Track skill acquisition, not task completion** — The goal isn't "ship feature X." It's "learn how to design APIs" or "get comfortable with debugging production issues." Task completion is the vehicle, skill acquisition is the outcome.
+
+#### Feedback Delivery
+
+- **Use Situation-Behavior-Impact (SBI) framework** — "In yesterday's design review (situation), you interrupted Sarah twice (behavior), which made her hesitant to share more ideas (impact)." Specific, observable, non-judgmental.
+- **Give feedback close to the event** — Real-time or within 24 hours. Waiting for quarterly reviews dilutes the learning and makes feedback feel like a performance audit, not coaching.
+- **Balance positive and developmental feedback** — Ratio: 3-5 pieces of positive feedback for every 1 piece of developmental feedback. Overweighting critique creates defensiveness.
+- **Focus on one behavior at a time** — Don't bundle 5 unrelated pieces of feedback. Pick the most impactful behavior to improve. Once they've made progress, address the next one.
+
+#### Skill Gap Assessment
+
+- **Distinguish between knowledge gaps and capability gaps** — Knowledge gaps (doesn't know how to use Redis) are fixed with learning. Capability gaps (struggles to break down ambiguous problems) require coaching and practice.
+- **Use the Dreyfus model** — Novice (needs recipes), Advanced Beginner (starts recognizing patterns), Competent (can troubleshoot), Proficient (intuitive understanding), Expert (creates new patterns). Mentor at the appropriate level.
+- **Create learning paths** — For knowledge gaps: reading list, courses, toy projects. For capability gaps: shadowing, pair programming, progressively harder assignments.
+
+### After mentorship sessions
+
+- **Document progress** — Keep notes on what you discussed, insights they shared, and commitments they made. Refer back in future sessions. Memory fades; notes compound.
+- **Assign practice work** — After teaching a concept, give them a small task to apply it. "We talked about database indexing. Add indexes to the Users table and measure query performance before/after."
+- **Check for understanding** — Ask mentee to summarize what they learned. If they can't explain it in their own words, they didn't internalize it.
+- **Adjust mentorship approach based on feedback** — Periodically ask: "Is this mentorship helping? What should I do more/less of?" Course-correct before frustration builds.
+
+## Self-check before task completion
+
+- [ ] Mentee's current skill level and learning style are explicitly assessed
+- [ ] Mentorship goals are aligned with mentee's career trajectory, not mentor's preferences
+- [ ] Pair programming sessions use driver-navigator pattern with guiding questions, not answers
+- [ ] Code review feedback is classified by severity and includes "why," not just "what"
+- [ ] Career growth plan has 30-60-90 day goals tied to specific skill acquisition
+- [ ] Feedback uses SBI framework, is delivered within 24 hours, and focuses on one behavior at a time
+- [ ] Progress is documented and reviewed regularly to track skill development over time

package/.mindforge/skills/microservices-patterns/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: microservices-patterns
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: microservice, service boundary, bounded context, api contract, saga pattern, event-driven architecture, bulkhead, service mesh, service discovery, distributed system, inter-service communication, service decomposition
+---
+
+# Skill — Microservices Patterns
+
+## When this skill activates
+Any task involving microservice architecture, service decomposition, inter-service
+communication, distributed system design, or API contract definition between services.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Identify bounded contexts** — Map business capabilities to service boundaries using DDD. Each service owns one bounded context, one database, one deployment unit.
+2. **Define communication style** — Synchronous (REST/gRPC) for queries, asynchronous (events) for cross-domain state changes. Default to async.
+3. **Assess data ownership** — Each service owns its data exclusively. No shared databases. Cross-service access via APIs or event propagation.
+
+### During
+
+#### Service boundary design (DDD)
+```
+Decomposition heuristics:
+  - Single Responsibility: one reason to change per service
+  - Team Ownership: one team owns one service (Conway's Law)
+  - Data Cohesion: entities that change together stay together
+  - Independent Deployability: releasing one never requires releasing another
+```
+
+#### API contracts
+- Version all APIs (URL path or header-based)
+- REST (OpenAPI 3.1) for external/public APIs
+- gRPC (protobuf) for high-throughput internal calls
+- Consumer-driven contract testing (Pact) between services
+- Breaking changes require new major version + deprecation period
+
+#### Saga orchestration
+```
+Choreography (2-3 services, simple flows):
+  Service A -> emits Event -> Service B reacts -> emits Event -> Service C reacts
+  Each service owns its compensating action
+
+Orchestration (4+ services, complex flows):
+  SagaCoordinator defines steps + compensations:
+    Step 1: InventoryService.reserve() | compensate: release()
+    Step 2: PaymentService.charge()    | compensate: refund()
+    Step 3: OrderService.confirm()     | compensate: cancel()
+```
+
+#### Resilience patterns
+```
+Bulkhead: separate thread/connection pools per dependency
+Circuit Breaker: Closed -> Open (5 failures/10s) -> Half-Open (probe after 30s)
+Retry: exponential backoff + jitter, max 3 attempts, idempotent ops only
+Timeout: every sync call has an explicit deadline (never infinite)
+```
+
+#### Service mesh and discovery
+- Kubernetes: use native Services (DNS-based, server-side discovery)
+- Non-K8s: Consul or Eureka with client-side load balancing
+- Service mesh (Istio/Linkerd) for: mTLS, traffic shaping, observability, retries
+- Health checks: active (ping /health every 5s, 3 failures = remove from pool)
+
+### After
+
+1. **Validate data ownership** — No service reads another service's database directly.
+2. **Verify fault tolerance** — Every sync call has timeout, retry policy, and circuit breaker.
+3. **Check observability** — Distributed tracing (OpenTelemetry), structured logs with correlation IDs, health endpoints.
+4. **Contract tests pass** — Consumer-driven contract tests verify API compatibility.
+
+## Self-check before task completion
+- [ ] Each service owns exactly one bounded context and one database
+- [ ] API contracts versioned and published (OpenAPI or protobuf)
+- [ ] Saga compensation defined for every step that can fail
+- [ ] Bulkhead isolation prevents cascading failures
+- [ ] Circuit breakers on all synchronous inter-service calls
+- [ ] Distributed tracing propagates correlation IDs across boundaries
+- [ ] No shared databases between services
+- [ ] Service discovery mechanism documented and tested