@lifeaitools/rdc-skills 0.15.0 → 0.17.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/bin/rdc-skills-mcp.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * bin/rdc-skills-mcp.mjs — local MCP server exposing the rdc-skills library.
+ *
+ * Mirrors the codeflow MCP topology (packages/codeflow/src/mcp/server.ts):
+ *   express + @modelcontextprotocol/sdk McpServer + StreamableHTTPServerTransport,
+ *   stateless (a fresh server+transport per POST /mcp), PORT from env.
+ *
+ * Routes:
+ *   POST /mcp     — MCP over StreamableHTTP. NO Authorization (URL is the shared
+ *                   secret, consistent with codeflow/clauth tunnel MCPs).
+ *   GET  /health  — { status, service, version, skills } — no auth, no heavy work.
+ *   /.well-known/* + /authorize + /token → 404 (force connectors to skip OAuth).
+ *
+ * It is tunneled in production at https://rdc-skills.regendevcorp.com/mcp; this
+ * process only listens on PORT (default 3110) and does not configure the tunnel.
+ *
+ * ── Caller detection → variant (best-effort) ────────────────────────────────
+ * Tools render a `cli` or `cloud` body. Detection rule: on MCP `initialize`,
+ * `clientInfo.name` containing `claude-code` or `codex` → `cli`; anything else
+ * (claude.ai web) → `cloud`; unknown → `cloud` (safer for web).
+ *
+ * APPROACH TAKEN — default + explicit override (NOT session-threaded):
+ * The transport is stateless (a new McpServer per POST, sessionIdGenerator:
+ * undefined), so there is no durable session to thread clientInfo through to a
+ * later tools/call. Rather than build a fragile session map, we:
+ *   - capture clientInfo on `initialize` and remember the MOST RECENT one
+ *     process-wide as a soft default (helps the common single-client case), and
+ *   - ALWAYS honor an explicit `variant` arg on rdc_skill_get (the must-have).
+ * If no explicit variant is given and no client has initialized this process,
+ * the default is `cloud`. This keeps the override correct and the auto-detect
+ * best-effort, exactly as the spec permits.
+ */
+
+import express from 'express';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  listSkills,
+  getSkill,
+  getSkillBody,
+  getCloudOverride,
+  skillNames,
+  searchSkills,
+} from '../lib/catalog.mjs';
+import { toCloudBody } from '../lib/cloud-rewrite.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const PORT = parseInt(process.env.PORT || '3110', 10);
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// Soft process-wide default variant, updated whenever a client initializes.
+let lastDetectedVariant = 'cloud';
+
+/** Map a clientInfo.name → variant. */
+function variantForClient(clientName) {
+  const n = String(clientName || '').toLowerCase();
+  if (n.includes('claude-code') || n.includes('codex')) return 'cli';
+  return 'cloud'; // claude.ai web client and anything unknown
+}
+
+/**
+ * Render a skill body for the resolved variant.
+ *   - cli   → SKILL.md body unchanged.
+ *   - cloud → SKILL.cloud.md verbatim if present, else toCloudBody(SKILL.md).
+ * Returns { header, body } or null if the skill has no body on disk.
+ */
+function renderSkill(name, variant) {
+  const body = getSkillBody(name);
+  if (body == null) return null;
+  if (variant === 'cli') {
+    return { header: `<!-- rdc-skills: '${name}' served as CLI variant -->`, body };
+  }
+  const override = getCloudOverride(name);
+  if (override != null) {
+    return {
+      header: `<!-- rdc-skills: '${name}' served as CLOUD variant (hand-tuned SKILL.cloud.md) -->`,
+      body: override,
+    };
+  }
+  return {
+    header: `<!-- rdc-skills: '${name}' served as CLOUD variant (auto-rewritten from SKILL.md) -->`,
+    body: toCloudBody(body),
+  };
+}
+
+function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function buildMcpServer() {
+  const srv = new McpServer({ name: 'rdc-skills', version: pkgVersion() });
+
+  // Capture clientInfo on initialize to refine the soft default variant.
+  // The SDK exposes the underlying low-level server; oninitialized fires after
+  // the client's initialize params are recorded.
+  try {
+    srv.server.oninitialized = () => {
+      const info = srv.server.getClientVersion?.();
+      if (info?.name) lastDetectedVariant = variantForClient(info.name);
+    };
+  } catch {
+    /* non-fatal: detection stays at the cloud default */
+  }
+
+  // ── rdc_skill_list ─────────────────────────────────────────────────────────
+  srv.registerTool(
+    'rdc_skill_list',
+    {
+      description:
+        'List the rdc-skills catalog: every skill with its slash form, category, summary, when-to-use triggers, usage, args, and required capabilities. No input required.',
+      inputSchema: {},
+    },
+    async () => {
+      const catalog = listSkills();
+      return textResult(JSON.stringify({ count: catalog.length, skills: catalog }, null, 2));
+    },
+  );
+
+  // ── rdc_skill_get ──────────────────────────────────────────────────────────
+  srv.registerTool(
+    'rdc_skill_get',
+    {
+      description:
+        "Get a skill's SKILL.md body rendered for the caller. variant 'cli' returns the body unchanged; 'cloud' rewrites local-shell/clauth-daemon steps for the claude.ai web client. Omit variant to use auto-detection (defaults to cloud).",
+      inputSchema: {
+        name: z.string().describe('Skill name (e.g. "deploy", "build"). See rdc_skill_list.'),
+        variant: z.enum(['cli', 'cloud']).optional().describe('Force the rendered variant; overrides caller detection.'),
+      },
+    },
+    async ({ name, variant }) => {
+      const valid = skillNames();
+      if (!valid.includes(name)) {
+        return textResult(
+          `Unknown skill '${name}'. Valid skills (${valid.length}): ${valid.join(', ')}`,
+        );
+      }
+      const resolved = variant || lastDetectedVariant || 'cloud';
+      const rendered = renderSkill(name, resolved);
+      if (!rendered) {
+        return textResult(`Skill '${name}' exists in the catalog but has no SKILL.md body on disk.`);
+      }
+      return textResult(`${rendered.header}\n\n${rendered.body}`);
+    },
+  );
+
+  // ── rdc_skill_search ───────────────────────────────────────────────────────
+  srv.registerTool(
+    'rdc_skill_search',
+    {
+      description:
+        'Fuzzy/substring search the rdc-skills catalog over name, slash, summary, and trigger phrases. Returns ranked matches.',
+      inputSchema: {
+        query: z.string().describe('Search terms, e.g. "deploy coolify" or "work items".'),
+      },
+    },
+    async ({ query }) => {
+      const results = searchSkills(query);
+      return textResult(JSON.stringify({ query, count: results.length, results }, null, 2));
+    },
+  );
+
+  return srv;
+}
+
+function startHttp() {
+  const app = express();
+  app.use(express.json({ limit: '4mb' }));
+
+  // /health — open, cheap, reports live skill count.
+  app.get('/health', (_req, res) => {
+    let skills = 0;
+    try {
+      skills = listSkills().length;
+    } catch {
+      skills = 0;
+    }
+    res.json({ status: 'ok', service: 'rdc-skills-mcp', version: pkgVersion(), skills });
+  });
+
+  // Block OAuth discovery so connectors skip OAuth and connect direct — /mcp is open.
+  app.get('/.well-known/oauth-authorization-server', (_req, res) => res.status(404).end());
+  app.get('/.well-known/openid-configuration', (_req, res) => res.status(404).end());
+  app.get('/authorize', (_req, res) => res.status(404).end());
+  app.post('/token', (_req, res) => res.status(404).end());
+
+  // POST /mcp — stateless StreamableHTTP transport, no Authorization required.
+  app.post('/mcp', async (req, res) => {
+    try {
+      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+      const srv = buildMcpServer();
+      await srv.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+      res.on('close', async () => {
+        await transport.close().catch(() => {});
+        await srv.close().catch(() => {});
+      });
+    } catch (err) {
+      console.error('[rdc-skills-mcp] MCP error:', err);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: err?.message || 'internal error' },
+          id: null,
+        });
+      }
+    }
+  });
+
+  app.get('/mcp', (_req, res) => {
+    res.status(405).json({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Use POST for MCP requests' },
+      id: null,
+    });
+  });
+
+  app.listen(PORT, () => {
+    console.log(`[rdc-skills-mcp] ready on port ${PORT}`);
+    console.log(`  MCP:    POST http://localhost:${PORT}/mcp`);
+    console.log(`  Health: GET  http://localhost:${PORT}/health`);
+  });
+}
+
+startHttp();

package/guides/lessons-learned-spec.md

@@ -0,0 +1,153 @@
+---
+mdk_schema_version: "1.0"
+doc_type: guide
+system: claude-workflow
+status: active
+owner: infrastructure
+created: 2026-06-08
+last_reviewed: 2026-06-08
+source_of_truth: true
+supersedes: []
+depends_on:
+  - ".claude/rules/architectural-change-approval.md"
+  - ".rdc/guides/output-contract.md"
+tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
+---
+
+# Lessons-Learned Capture & Triage — Spec
+
+> Auto-referenced by long-running `rdc:*` skills at exit, and by `rdc:housekeeping` for triage.
+> Goal: make the fleet an **interactive adaptive modeler** — every run that teaches us
+> something writes it down, and the weekly housekeeping pass turns those lessons into
+> actual fixes (rules, skill docs, work_items).
+
+---
+
+## Why this exists
+
+Lessons learned during a run (a non-obvious infra trap, a wrong assumption, a missing
+gate, a tooling gotcha) used to survive only if someone hand-wrote a memory. This system
+makes capture a **routine exit step** of every long skill, and triage a **routine phase**
+of the weekly housekeeping. Capture is cheap and append-only; triage is where fixes happen.
+
+Precedent: brochurify's `rdc-extract-verifier-rules` already does read-log → cluster →
+propose-rule for one domain. This generalizes that pattern fleet-wide.
+
+---
+
+## Storage — directory of per-lesson files
+
+Lessons live in **`.rdc/lessons/`**, one markdown file per lesson:
+
+```
+.rdc/lessons/<YYYY-MM-DD>-<skill>-<short-slug>.md
+```
+
+- One file per lesson (NOT a single appended file) so parallel agents finishing at the
+  same time never collide on one file in git.
+- `<skill>` is the capturing skill (`build`, `deploy`, `overnight`, `fixit`, `plan`,
+  `preplan`, `review`, `release`, `collab`).
+- `<short-slug>` is 2–4 kebab words naming the lesson.
+
+A run that taught nothing writes nothing — **absence is the default**. Only write a lesson
+when something was genuinely learned (see § When to capture).
+
+---
+
+## Lesson file schema
+
+```markdown
+---
+id: <YYYY-MM-DD>-<skill>-<short-slug>
+date: "<YYYY-MM-DD>"
+skill: build | deploy | overnight | fixit | plan | preplan | review | release | collab
+session: <session-id or short ref>
+scope: simple | architectural          # triage routing — see § Scope gate
+status: open | triaged | applied | wont-fix
+area: infra | skill | guide | rule | schema | ui | content | other
+links:
+  commits: []                          # SHAs that relate to the lesson
+  memory: []                           # memory file slugs, if a memory was also written
+  work_items: []                       # work_item UUIDs spawned during triage
+---
+
+## What happened
+<one paragraph — the concrete situation, with evidence (exit code, file:line, command)>
+
+## Root cause
+<one paragraph — the evidenced cause, not a guess>
+
+## The fix / rule
+<what should change so this never recurs: a rule edit, skill-doc line, code change,
+or a check. If already applied in the same run, say so and link the commit.>
+```
+
+`scope` is the single most important field — it routes triage:
+
+- **`simple`** — a doc line, a one-file fix, a config tweak, a clarifying sentence in a
+  skill, a missing grep guard. Housekeeping applies these directly.
+- **`architectural`** — anything matching `.claude/rules/architectural-change-approval.md`
+  (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
+  API/MCP changes, skill-contract changes affecting multiple skills). Housekeeping does
+  NOT apply these; it surfaces them via `AskUserQuestion` for explicit approval first.
+
+When unsure, mark `architectural`.
+
+---
+
+## When to capture (at skill exit)
+
+Write a lesson when ANY of these were true during the run:
+
+1. A root cause turned out to be different from the first theory (a wrong assumption).
+2. The standard/documented path didn't work and you had to do something non-obvious.
+3. A gate, check, or doc was missing and its absence cost a round.
+4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
+5. A hook blocked you and the block revealed a real gap (not just your mistake).
+
+Do NOT capture: routine success, your own one-off typo, anything already fully documented
+in a rule/guide. If a durable user preference or correction was involved, also write a
+`memory` (this spec and memory are complementary — link them).
+
+---
+
+## Capture procedure (the exit step long skills call)
+
+At the end of a long skill run, before the final verdict line:
+
+1. Decide if anything qualifies (§ When to capture). If not, write nothing and move on.
+2. For each lesson, write `.rdc/lessons/<date>-<skill>-<slug>.md` using the schema above.
+   Set `status: open` (or `applied` if you already shipped the fix in this same run, with
+   the commit linked).
+3. Set `scope` honestly (`simple` vs `architectural`).
+4. Commit the lesson file(s) on `develop` alongside the run's other commits.
+5. Mention in the verdict/summary that N lessons were captured.
+
+---
+
+## Triage procedure (rdc:housekeeping, weekly)
+
+`rdc:housekeeping` adds a **Lessons triage** phase:
+
+1. Read all `.rdc/lessons/*.md` with `status: open`.
+2. Cluster by `area` + root-cause similarity (dedupe repeats into one fix).
+3. For each cluster:
+   - `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard),
+     commit it, set the lesson(s) `status: applied` and link the commit.
+   - `scope: architectural` → do NOT edit. Present the issue + options via
+     `AskUserQuestion` (per `architectural-change-approval.md`). On approval, apply via the
+     correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set
+     `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
+   - Not worth fixing → `status: wont-fix` with a one-line reason.
+4. Summarize in the housekeeping report: captured / applied / escalated / deferred counts.
+
+Lessons are never silently deleted — `applied` and `wont-fix` files stay as the audit trail.
+
+---
+
+## Skills that capture (the long-running set)
+
+`build` · `deploy` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab`
+
+Each references this spec from a final "§ Capture lessons" step. A Stop-hook backstop warns
+when one of these skills ends a run with findings but no new `.rdc/lessons/` file.

package/lib/catalog.mjs

@@ -0,0 +1,174 @@
+/**
+ * lib/catalog.mjs — rdc-skills catalog loader for the local MCP server.
+ *
+ * Source of truth: `.claude-plugin/plugin.json` → `skills_meta` (an object keyed
+ * by skill name). Each entry provides { name, slash, category, usage, args,
+ * requires, triggers, ... }. We enrich each entry with the `description` from
+ * the skill's own `skills/<name>/SKILL.md` frontmatter (the human summary).
+ *
+ * Loading is LIVE: the catalog is re-read from disk when older than CACHE_TTL_MS
+ * so a skill edit (frontmatter or body) is picked up without a server restart.
+ * A skill that has a `skills_meta` entry but no SKILL.md on disk is still listed
+ * (meta-only); a skill dir with a SKILL.md but no meta entry is also surfaced
+ * (frontmatter-only) so nothing silently disappears from the catalog.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const PLUGIN_JSON = path.join(REPO_ROOT, '.claude-plugin', 'plugin.json');
+const SKILLS_DIR = path.join(REPO_ROOT, 'skills');
+
+const CACHE_TTL_MS = 5000; // short TTL: live-from-disk feel, cheap re-reads
+
+let _cache = null;
+let _cacheAt = 0;
+
+/** Read + parse the YAML frontmatter block of a SKILL.md. Returns {} on miss. */
+function readFrontmatter(skillMdPath) {
+  try {
+    const raw = fs.readFileSync(skillMdPath, 'utf8').replace(/\r\n/g, '\n');
+    const m = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return {};
+    const parsed = YAML.parse(m[1]);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Map a raw skills_meta entry + SKILL.md frontmatter into a compact catalog row. */
+function toCatalogEntry(name, meta, frontmatter) {
+  const description = frontmatter.description || meta.description || '';
+  // `summary` is the short customer-facing line; `when_to_use` pulls the triggers.
+  const triggers = Array.isArray(meta.triggers) ? meta.triggers : [];
+  return {
+    name,
+    slash: meta.slash || `rdc:${name}`,
+    category: meta.category || 'tooling',
+    summary: description,
+    when_to_use: triggers,
+    usage: meta.usage || '',
+    args: meta.args || { positional: [], flags: [] },
+    requires: Array.isArray(meta.requires) ? meta.requires : [],
+  };
+}
+
+/** Re-read plugin.json + skill frontmatter from disk and rebuild the catalog. */
+function buildCatalog() {
+  let plugin = {};
+  try {
+    plugin = JSON.parse(fs.readFileSync(PLUGIN_JSON, 'utf8'));
+  } catch {
+    plugin = {};
+  }
+  const skillsMeta = plugin.skills_meta && typeof plugin.skills_meta === 'object' ? plugin.skills_meta : {};
+
+  const byName = new Map();
+
+  // 1. Every skills_meta entry → enrich with its SKILL.md frontmatter.
+  for (const [name, meta] of Object.entries(skillsMeta)) {
+    const skillMd = path.join(SKILLS_DIR, name, 'SKILL.md');
+    const fm = fs.existsSync(skillMd) ? readFrontmatter(skillMd) : {};
+    byName.set(name, toCatalogEntry(name, meta || {}, fm));
+  }
+
+  // 2. Any skill dir with a SKILL.md but NO meta entry → frontmatter-only row.
+  if (fs.existsSync(SKILLS_DIR)) {
+    for (const entry of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+      if (!entry.isDirectory() || byName.has(entry.name)) continue;
+      const skillMd = path.join(SKILLS_DIR, entry.name, 'SKILL.md');
+      if (!fs.existsSync(skillMd)) continue;
+      const fm = readFrontmatter(skillMd);
+      byName.set(entry.name, toCatalogEntry(entry.name, {}, fm));
+    }
+  }
+
+  return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Return the cached catalog, rebuilding if the TTL has elapsed. */
+function getCatalog() {
+  const now = Date.now();
+  if (!_cache || now - _cacheAt > CACHE_TTL_MS) {
+    _cache = buildCatalog();
+    _cacheAt = now;
+  }
+  return _cache;
+}
+
+/** Compact catalog for `rdc_skill_list`. */
+export function listSkills() {
+  return getCatalog();
+}
+
+/** Full catalog row for one skill, or null if unknown. */
+export function getSkill(name) {
+  return getCatalog().find((s) => s.name === name) || null;
+}
+
+/** List of valid skill names (for error messages). */
+export function skillNames() {
+  return getCatalog().map((s) => s.name);
+}
+
+/**
+ * Read the raw SKILL.md body (frontmatter stripped) for a skill, live from disk.
+ * Returns null if the file does not exist.
+ */
+export function getSkillBody(name) {
+  const skillMd = path.join(SKILLS_DIR, name, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) return null;
+  const raw = fs.readFileSync(skillMd, 'utf8').replace(/\r\n/g, '\n');
+  // Strip the leading frontmatter block if present.
+  const m = raw.match(/^---\n[\s\S]*?\n---\n?/);
+  return m ? raw.slice(m[0].length).replace(/^\n+/, '') : raw;
+}
+
+/** Absolute path to a hand-tuned cloud override, or null if absent. */
+export function cloudOverridePath(name) {
+  const p = path.join(SKILLS_DIR, name, 'SKILL.cloud.md');
+  return fs.existsSync(p) ? p : null;
+}
+
+/** Read the hand-tuned cloud override body (frontmatter stripped), or null. */
+export function getCloudOverride(name) {
+  const p = cloudOverridePath(name);
+  if (!p) return null;
+  const raw = fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n');
+  const m = raw.match(/^---\n[\s\S]*?\n---\n?/);
+  return m ? raw.slice(m[0].length).replace(/^\n+/, '') : raw;
+}
+
+/**
+ * Fuzzy/substring search over name + slash + summary + triggers.
+ * Returns ranked [{ name, slash, summary, score }] (score: higher = better).
+ */
+export function searchSkills(query) {
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return [];
+  const terms = q.split(/\s+/).filter(Boolean);
+  const results = [];
+  for (const s of getCatalog()) {
+    const hay = {
+      name: s.name.toLowerCase(),
+      slash: (s.slash || '').toLowerCase(),
+      summary: (s.summary || '').toLowerCase(),
+      triggers: (s.when_to_use || []).join(' ').toLowerCase(),
+    };
+    let score = 0;
+    for (const term of terms) {
+      if (hay.name === term) score += 100;
+      else if (hay.name.includes(term)) score += 40;
+      if (hay.slash.includes(term)) score += 20;
+      if (hay.triggers.includes(term)) score += 12;
+      if (hay.summary.includes(term)) score += 6;
+    }
+    if (score > 0) results.push({ name: s.name, slash: s.slash, summary: s.summary, score });
+  }
+  return results.sort((a, b) => b.score - a.score);
+}