@lifeaitools/rdc-skills 0.25.9 → 0.26.0

package/skills/workitems/SKILL.md

@@ -1,151 +1,151 @@
----
-name: rdc:workitems
-description: "Usage `rdc:workitems [add|done|status|list|query]` — Manual work item CRUD outside the normal build flow: add to backlog, mark done, update status, list open epics, query by label."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`).
-
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag. Supabase work item writes (`insert_work_item`, `update_work_item_status`, `bump_epic_version`) are skipped under `RDC_TEST=1`.
-
-
-# rdc:workitems — Work Item Management
-
-## When to Use
-- Project lead says "create a ticket", "add to backlog", "log this bug", "update status"
-- An agent needs to create or update epics/tasks during a build session
-- Checking what work is open before starting a new epic
-
-## Arguments
-
-- `rdc:workitems epics` — list open epics
-- `rdc:workitems add <title> --epic <id>` — create a task under an epic
-- `rdc:workitems update <id> --status <status>` — update a work item's status
-- `rdc:workitems done <id>` — mark a task complete
-- `rdc:workitems list <epic-id>` — list tasks in an epic
-
-## Rules
-
-1. **Epic first, always.** Never create a task without a parent epic.
-2. **Label everything.** Minimum one system label per item.
-3. **Check first.** `get_open_epics()` before creating anything new.
-4. **Link design docs.** Put `.rdc/plans/` or `.rdc/research/` paths in descriptions (fallback: `.rdc/plans/` / `.rdc/research/`).
-
-## Read Epics
-
-```sql
-SELECT get_open_epics();
-SELECT get_open_epics('urgent');
-SELECT get_open_epics(p_label_filter := 'custom-label');
-```
-
-## Create Epic
-
-```sql
-SELECT insert_work_item(
-  p_title       := 'EPIC: Clear descriptive title',
-  p_description := 'What and why. Reference .rdc/plans/<n>.md if applicable.',
-  p_item_type   := 'epic',
-  p_priority    := 'high',
-  p_labels      := ARRAY['system-label'],
-  p_source      := 'planning'
-);
-```
-
-## Create Task
-
-```sql
-SELECT insert_work_item(
-  p_title       := 'Specific actionable task title',
-  p_description := 'What: <deliverable>
-Where: <files to create/modify>
-Agent type: frontend | backend | data | design | infra | content | cs2
-Guide: .rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md)
-Design doc: .rdc/plans/<n>.md (fallback: .rdc/plans/<n>.md, if exists)
-Depends on: <other task title if sequential>
-Est: <hours>',
-  p_parent_id   := '<epic-uuid>'::uuid,
-  p_item_type   := 'task',
-  p_priority    := 'high',
-  p_labels      := ARRAY['system-label'],
-  p_estimated_hours := 2,
-  p_source      := 'planning'
-);
-```
-
-## Update Status
-
-```sql
-SELECT update_work_item_status('<uuid>'::uuid, 'in_progress');
-SELECT update_work_item_status('<uuid>'::uuid, 'review', '["Implementation complete; ready for validator"]'::jsonb, '<agent-session-id>', 'agent');
-SELECT update_work_item_status('<uuid>'::uuid, 'done', '["Validator verified implementation report, CodeFlow post, and checklist evidence"]'::jsonb, '<validator-session-id>', 'validator');
-SELECT update_work_item_status('<uuid>'::uuid, 'blocked', '["Why it is blocked"]'::jsonb);
-```
-
-Non-epic `done` is a validator-only close and requires an existing
-`implementation_report.codeflow_post`, checked required checklist evidence, and
-originating-agent tick audit.
-
-## Read Tasks in an Epic
-
-```sql
-SELECT get_work_items_by_epic('<epic-uuid>'::uuid);
-SELECT get_work_items_by_epic('<epic-uuid>'::uuid, 'todo');
-```
-
-## Bump Epic Version
-
-```sql
-SELECT bump_epic_version('<epic-uuid>'::uuid, '0.2.0', 'What changed', 'planning');
-```
-
-## Valid Values
-
-| Field | Values |
-|-------|--------|
-| status | `todo` `in_progress` `blocked` `review` `done` `archived` |
-| priority | `urgent` `high` `normal` `low` |
-| item_type | `epic` `task` `subtask` `bug` `spike` |
-
-## System Labels
-
-| Label | When |
-|-------|------|
-| `project-a` | Your-app-specific work |
-| `project-b` | Another app work |
-| `cs2` | Core paradigm packages |
-| `hail` | Grammar, DSL compiler |
-| `pal` | Moment windows, memory |
-| `virtue` | Virtue engine, coherence |
-| `marketing` | Outreach, campaigns |
-| `media` | Assets, R2, image pipeline |
-| `infrastructure` | CI/CD, deployment |
-| `ui` | Component library |
-| `data` | Schema, migrations |
-| `content` | Copy, messaging |
-| `website` | Public-facing sites |
-
-## Agent Type → Guide File Reference
-
-| Type | Guide | Use For |
-|------|-------|---------|
-| `frontend` | .rdc/guides/frontend.md | React, pages, UI, Tailwind |
-| `backend` | .rdc/guides/backend.md | API routes, database, auth |
-| `data` | .rdc/guides/data.md | Migrations, schema, RPC |
-| `design` | .rdc/guides/design.md | Brand, palette, OG images |
-| `infra` | .rdc/guides/infrastructure.md | CI/CD, deploy, DNS |
-| `content` | .rdc/guides/content.md | Copy, messaging, tone |
-| `cs2` | .rdc/guides/cs2.md | CS 2.0 paradigm |
-| `hail` | .rdc/guides/cs2.md + packages/hail/CLAUDE.md | Grammar, DSL |
-| `viz` | .rdc/guides/frontend.md + design.md | Custom visualizations |
-
-## What NOT to Do
-
-- Never raw INSERT/UPDATE against work items — RPC functions only
-- Never create tasks without a parent epic
-- Never leave labels empty
-- Never write vague titles ("Fix stuff") — be specific
-- Never put design intention in the task — put it in `.rdc/research/` (fallback: `.rdc/research/`) and link
+---
+name: rdc:workitems
+description: "Usage `rdc:workitems [add|done|status|list|query]` — Manual work item CRUD outside the normal build flow: add to backlog, mark done, update status, list open epics, query by label."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`).
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag. Supabase work item writes (`insert_work_item`, `update_work_item_status`, `bump_epic_version`) are skipped under `RDC_TEST=1`.
+
+
+# rdc:workitems — Work Item Management
+
+## When to Use
+- Project lead says "create a ticket", "add to backlog", "log this bug", "update status"
+- An agent needs to create or update epics/tasks during a build session
+- Checking what work is open before starting a new epic
+
+## Arguments
+
+- `rdc:workitems epics` — list open epics
+- `rdc:workitems add <title> --epic <id>` — create a task under an epic
+- `rdc:workitems update <id> --status <status>` — update a work item's status
+- `rdc:workitems done <id>` — mark a task complete
+- `rdc:workitems list <epic-id>` — list tasks in an epic
+
+## Rules
+
+1. **Epic first, always.** Never create a task without a parent epic.
+2. **Label everything.** Minimum one system label per item.
+3. **Check first.** `get_open_epics()` before creating anything new.
+4. **Link design docs.** Put `.rdc/plans/` or `.rdc/research/` paths in descriptions (fallback: `.rdc/plans/` / `.rdc/research/`).
+
+## Read Epics
+
+```sql
+SELECT get_open_epics();
+SELECT get_open_epics('urgent');
+SELECT get_open_epics(p_label_filter := 'custom-label');
+```
+
+## Create Epic
+
+```sql
+SELECT insert_work_item(
+  p_title       := 'EPIC: Clear descriptive title',
+  p_description := 'What and why. Reference .rdc/plans/<n>.md if applicable.',
+  p_item_type   := 'epic',
+  p_priority    := 'high',
+  p_labels      := ARRAY['system-label'],
+  p_source      := 'planning'
+);
+```
+
+## Create Task
+
+```sql
+SELECT insert_work_item(
+  p_title       := 'Specific actionable task title',
+  p_description := 'What: <deliverable>
+Where: <files to create/modify>
+Agent type: frontend | backend | data | design | infra | content | cs2
+Guide: .rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md)
+Design doc: .rdc/plans/<n>.md (fallback: .rdc/plans/<n>.md, if exists)
+Depends on: <other task title if sequential>
+Est: <hours>',
+  p_parent_id   := '<epic-uuid>'::uuid,
+  p_item_type   := 'task',
+  p_priority    := 'high',
+  p_labels      := ARRAY['system-label'],
+  p_estimated_hours := 2,
+  p_source      := 'planning'
+);
+```
+
+## Update Status
+
+```sql
+SELECT update_work_item_status('<uuid>'::uuid, 'in_progress');
+SELECT update_work_item_status('<uuid>'::uuid, 'review', '["Implementation complete; ready for validator"]'::jsonb, '<agent-session-id>', 'agent');
+SELECT update_work_item_status('<uuid>'::uuid, 'done', '["Validator verified implementation report, CodeFlow post, and checklist evidence"]'::jsonb, '<validator-session-id>', 'validator');
+SELECT update_work_item_status('<uuid>'::uuid, 'blocked', '["Why it is blocked"]'::jsonb);
+```
+
+Non-epic `done` is a validator-only close and requires an existing
+`implementation_report.codeflow_post`, checked required checklist evidence, and
+originating-agent tick audit.
+
+## Read Tasks in an Epic
+
+```sql
+SELECT get_work_items_by_epic('<epic-uuid>'::uuid);
+SELECT get_work_items_by_epic('<epic-uuid>'::uuid, 'todo');
+```
+
+## Bump Epic Version
+
+```sql
+SELECT bump_epic_version('<epic-uuid>'::uuid, '0.2.0', 'What changed', 'planning');
+```
+
+## Valid Values
+
+| Field | Values |
+|-------|--------|
+| status | `todo` `in_progress` `blocked` `review` `done` `archived` |
+| priority | `urgent` `high` `normal` `low` |
+| item_type | `epic` `task` `subtask` `bug` `spike` |
+
+## System Labels
+
+| Label | When |
+|-------|------|
+| `project-a` | Your-app-specific work |
+| `project-b` | Another app work |
+| `cs2` | Core paradigm packages |
+| `hail` | Grammar, DSL compiler |
+| `pal` | Moment windows, memory |
+| `virtue` | Virtue engine, coherence |
+| `marketing` | Outreach, campaigns |
+| `media` | Assets, R2, image pipeline |
+| `infrastructure` | CI/CD, deployment |
+| `ui` | Component library |
+| `data` | Schema, migrations |
+| `content` | Copy, messaging |
+| `website` | Public-facing sites |
+
+## Agent Type → Guide File Reference
+
+| Type | Guide | Use For |
+|------|-------|---------|
+| `frontend` | .rdc/guides/frontend.md | React, pages, UI, Tailwind |
+| `backend` | .rdc/guides/backend.md | API routes, database, auth |
+| `data` | .rdc/guides/data.md | Migrations, schema, RPC |
+| `design` | .rdc/guides/design.md | Brand, palette, OG images |
+| `infra` | .rdc/guides/infrastructure.md | CI/CD, deploy, DNS |
+| `content` | .rdc/guides/content.md | Copy, messaging, tone |
+| `cs2` | .rdc/guides/cs2.md | CS 2.0 paradigm |
+| `hail` | .rdc/guides/cs2.md + packages/hail/CLAUDE.md | Grammar, DSL |
+| `viz` | .rdc/guides/frontend.md + design.md | Custom visualizations |
+
+## What NOT to Do
+
+- Never raw INSERT/UPDATE against work items — RPC functions only
+- Never create tasks without a parent epic
+- Never leave labels empty
+- Never write vague titles ("Fix stuff") — be specific
+- Never put design intention in the task — put it in `.rdc/research/` (fallback: `.rdc/research/`) and link

package/tests/no-local-pm2.test.mjs

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (relative) => fs.readFileSync(path.join(ROOT, relative), 'utf8');
+
+test('SessionStart verifies package files without a local MCP or PM2', () => {
+  const hook = read('hooks/check-rdc-environment.js');
+  assert.doesNotMatch(hook, /\bpm2\b/i);
+  assert.doesNotMatch(hook, /127\.0\.0\.1:3110/);
+  assert.doesNotMatch(hook, /rdc-skills-mcp/);
+  assert.match(hook, /global package missing/);
+  assert.match(hook, /rdc-skills-install/);
+});
+
+test('installer registers the public MCP and never launches a process manager', () => {
+  const installer = read('scripts/install-rdc-skills.js');
+  assert.match(installer, /https:\/\/rdc-skills\.regendevcorp\.com\/mcp/);
+  assert.doesNotMatch(installer, /\bpm2\b/i);
+  assert.doesNotMatch(installer, /127\.0\.0\.1:3110/);
+});
+
+test('environment skill and release contract preserve the runtime boundary', () => {
+  for (const relative of ['skills/env/SKILL.md', 'RELEASE.md']) {
+    const content = read(relative);
+    assert.doesNotMatch(content, /\bpm2\s+(start|stop|restart|resurrect|jlist|list|ping)\b/i);
+    assert.match(content, /public.*rdc-skills MCP/is);
+  }
+});
+
+test('legacy local PM2 helpers are absent', () => {
+  for (const relative of [
+    'scripts/local-install-with-stop.sh',
+    'scripts/probe-lock-holders.mjs',
+    'scripts/rebuild-mcp.mjs',
+  ]) {
+    assert.equal(fs.existsSync(path.join(ROOT, relative)), false, `${relative} still exists`);
+  }
+
+  const pkg = JSON.parse(read('package.json'));
+  assert.equal(pkg.scripts['rebuild-mcp'], undefined);
+});

package/scripts/local-install-with-stop.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# Install rdc-skills globally FROM LOCAL SOURCE, using the stop-first sequence.
-#
-# This is the empirical test of the fix: the same `npm install -g` that produced
-# EBUSY should now succeed because the lock holder is stopped first. It is a LOCAL
-# install (a path, not the registry) — nothing is published.
-#
-# The restart is unconditional: leaving the MCP down after a failed install would
-# be worse than the failure being repaired.
-set -u
-
-HOLDER=rdc-skills-mcp
-
-echo "== before =="
-pm2 jlist | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const p=JSON.parse(s).find(x=>x.name===process.argv[1]);console.log('  '+process.argv[1]+': '+(p?p.pm2_env.status:'absent'));})" "$HOLDER"
-npm ls -g '@lifeaitools/rdc-skills' --depth=0 2>/dev/null | tail -1
-
-echo "== stop the lock holder =="
-pm2 stop "$HOLDER" >/dev/null 2>&1 && echo "  stopped $HOLDER" || echo "  could not stop (may be absent)"
-
-echo "== npm install -g from local source =="
-set +e
-npm install -g "C:/Dev/rdc-skills" 2>&1 | tail -5
-INSTALL_RC=${PIPESTATUS[0]}
-set -e
-echo "  install exit=$INSTALL_RC"
-
-echo "== restart (always) =="
-pm2 restart "$HOLDER" >/dev/null 2>&1 && echo "  restarted $HOLDER" || echo "  restart FAILED"
-
-echo "== after =="
-npm ls -g '@lifeaitools/rdc-skills' --depth=0 2>/dev/null | tail -1
-for i in 1 2 3 4 5 6 7 8; do
-  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 http://127.0.0.1:3110/health 2>/dev/null)
-  [ "$code" = "200" ] && break
-  sleep 1
-done
-echo "  health 3110 -> HTTP ${code:-none}"
-curl -s --max-time 3 http://127.0.0.1:3110/health 2>/dev/null | head -c 200
-echo
-exit "$INSTALL_RC"

package/scripts/probe-lock-holders.mjs

@@ -1,36 +0,0 @@
-#!/usr/bin/env node
-/**
- * Read-only probe: which PM2 processes hold the global rdc-skills package dir?
- *
- * Mirrors processesHoldingPackage() in hooks/check-rdc-environment.js so the
- * matcher can be verified WITHOUT running a real repair (which would stop the
- * MCP and reinstall the package).
- *
- * `npm install -g` upgrades by renaming that directory; Windows refuses to rename
- * a live process's cwd, which is the EBUSY that hard-blocked sessions.
- */
-import { execSync } from 'node:child_process';
-import path from 'node:path';
-
-const shell = (c) => execSync(c, { encoding: 'utf8', timeout: 15000 }).trim();
-const norm = (p) => String(p || '').toLowerCase().replace(/\\/g, '/');
-
-const root = shell('npm root -g');
-const pkgDir = norm(path.join(root, '@lifeaitools', 'rdc-skills'));
-
-const all = JSON.parse(shell('pm2 jlist'));
-const holders = all.filter((p) => {
-  const cwd = norm(p?.pm2_env?.pm_cwd);
-  return cwd && (cwd === pkgDir || cwd.startsWith(`${pkgDir}/`));
-});
-
-console.log(`package dir : ${pkgDir}`);
-console.log(`pm2 procs   : ${all.length}`);
-for (const p of holders) {
-  console.log(`  HOLDS LOCK: ${p.name}  status=${p.pm2_env.status}  cwd=${norm(p.pm2_env.pm_cwd)}`);
-}
-console.log(
-  holders.length
-    ? `\nMATCHED ${holders.length} — these are stopped before npm -g, so EBUSY is avoided.`
-    : '\nNO MATCH — nothing holds the dir; npm -g would have been safe anyway.',
-);

package/scripts/rebuild-mcp.mjs

@@ -1,107 +0,0 @@
-#!/usr/bin/env node
-/**
- * scripts/rebuild-mcp.mjs — "build hook" for the rdc-skills MCP server.
- *
- * The server reads skills live from disk, so a skill edit is usually picked up
- * without a restart. This script exists to (a) bounce the PM2 process so any
- * in-memory module cache is dropped, and (b) assert the local /health endpoint
- * reports the current on-disk skill count — a fast smoke that the server is up
- * and seeing the same catalog this script does.
- *
- * Tolerant of a missing PM2: if pm2 is not installed/registered, it prints how
- * to start the server and exits 0. It never hard-fails the caller.
- */
-
-import { execSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { listSkills } from '../lib/catalog.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(__dirname, '..');
-const PM2_NAME = 'rdc-skills-mcp';
-const PORT = parseInt(process.env.PORT || '3110', 10);
-const BIN = path.join(REPO_ROOT, 'bin', 'rdc-skills-mcp.mjs');
-
-const ok = (m) => console.log(`  \x1b[32m✓\x1b[0m ${m}`);
-const info = (m) => console.log(`  \x1b[36m→\x1b[0m ${m}`);
-const warn = (m) => console.log(`  \x1b[33m⚠\x1b[0m ${m}`);
-
-function sh(cmd) {
-  return execSync(cmd, { encoding: 'utf8', stdio: 'pipe' }).trim();
-}
-
-function pm2Available() {
-  try {
-    sh('pm2 -v');
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function pm2HasProcess() {
-  try {
-    const list = JSON.parse(sh('pm2 jlist'));
-    return Array.isArray(list) && list.some((p) => p.name === PM2_NAME);
-  } catch {
-    return false;
-  }
-}
-
-async function checkHealth(expectedSkills) {
-  // Node 22 has global fetch.
-  try {
-    const res = await fetch(`http://127.0.0.1:${PORT}/health`, { signal: AbortSignal.timeout(4000) });
-    if (!res.ok) {
-      warn(`/health returned HTTP ${res.status}`);
-      return false;
-    }
-    const json = await res.json();
-    if (json.skills === expectedSkills) {
-      ok(`/health OK — skills=${json.skills} (matches disk), version=${json.version}`);
-      return true;
-    }
-    warn(`/health skills=${json.skills} but disk has ${expectedSkills} — server may be stale`);
-    return false;
-  } catch (err) {
-    warn(`/health unreachable on port ${PORT}: ${err?.message || err}`);
-    return false;
-  }
-}
-
-async function main() {
-  const diskSkills = listSkills().length;
-  info(`On-disk catalog: ${diskSkills} skill(s)`);
-
-  if (!pm2Available()) {
-    warn('pm2 not found — cannot bounce the MCP process.');
-    info(`Start it manually:  PORT=${PORT} pm2 start ${BIN} --name ${PM2_NAME}`);
-    info(`Or run directly:    PORT=${PORT} node ${BIN}`);
-    process.exit(0);
-  }
-
-  if (pm2HasProcess()) {
-    try {
-      sh(`pm2 restart ${PM2_NAME} --update-env`);
-      ok(`pm2 restart ${PM2_NAME}`);
-    } catch (err) {
-      warn(`pm2 restart failed: ${err?.message || err}`);
-    }
-  } else {
-    info(`pm2 process '${PM2_NAME}' not registered.`);
-    info(`Start it:  PORT=${PORT} pm2 start ${BIN} --name ${PM2_NAME}`);
-    process.exit(0);
-  }
-
-  // Give the process a beat to bind, then probe /health (no long sleeps).
-  await new Promise((r) => setTimeout(r, 1200));
-  await checkHealth(diskSkills);
-  process.exit(0);
-}
-
-main().catch((err) => {
-  warn(`rebuild-mcp error (non-fatal): ${err?.message || err}`);
-  process.exit(0);
-});