@lifeaitools/rdc-skills 0.24.7 → 0.24.9

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/channel-formatter.contract.test.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * Contract/system test for rdc:channel-formatter content repurposing.
+ *
+ * This does not test LLM prose generation. rdc:channel-formatter is an
+ * instruction skill served by the MCP, not an executable formatter function.
+ * What this test proves is that local and live MCP discovery return the
+ * expected skill and that the served skill body contains the required
+ * social-pack, campaign-pack, and source-fidelity contracts an agent must obey.
+ *
+ * Every MCP call is written to a JSONL audit log under .rdc/reports/.
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getSkillBody, listSkills, searchSkills } from '../lib/catalog.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const BIN = path.join(REPO_ROOT, 'bin', 'rdc-skills-mcp.mjs');
+const TEST_PORT = parseInt(process.env.TEST_PORT || '3198', 10);
+const LOCAL = `http://127.0.0.1:${TEST_PORT}/mcp`;
+const LOCAL_HEALTH = `http://127.0.0.1:${TEST_PORT}/health`;
+const REMOTE = 'https://rdc-skills.regendevcorp.com/mcp';
+const REPORT_DIR = path.join(REPO_ROOT, '.rdc', 'reports');
+const REPORT_FILE = path.join(
+  REPORT_DIR,
+  `channel-formatter-contract-${new Date().toISOString().replace(/[:.]/g, '-')}.jsonl`,
+);
+
+fs.mkdirSync(REPORT_DIR, { recursive: true });
+
+let pass = 0;
+let fail = 0;
+const failures = [];
+
+function log(event) {
+  fs.appendFileSync(REPORT_FILE, `${JSON.stringify({ ts: new Date().toISOString(), ...event })}\n`);
+}
+
+function check(name, condition, detail = '') {
+  if (condition) {
+    pass++;
+    log({ kind: 'assertion', name, status: 'pass', detail });
+  } else {
+    fail++;
+    failures.push(`${name}${detail ? ` - ${detail}` : ''}`);
+    log({ kind: 'assertion', name, status: 'fail', detail });
+  }
+}
+
+function resultText(json) {
+  return json?.result?.content?.[0]?.text || '';
+}
+
+function summarizeText(text) {
+  return {
+    length: text.length,
+    hasChannelFormatter: text.includes('channel-formatter'),
+    hasSocialPack: text.includes('social-pack'),
+    hasCampaignPack: text.includes('campaign-pack'),
+    hasStrictFormat: text.includes('strict-format'),
+    hasSourceFidelity: text.includes('Source-Fidelity'),
+    hasUnsupportedClaims: text.includes('unsupported claims') || text.includes('Do not invent statistics'),
+    hasChannelPackUsage: text.includes('<channel|pack>'),
+    hasLinkedIn: text.includes('LinkedIn'),
+    hasTwitterThread: text.includes('Twitter/X thread'),
+    hasSlack: text.includes('Slack/Teams'),
+  };
+}
+
+async function mcp(url, label, body) {
+  const request = {
+    method: body.method,
+    tool: body.params?.name || null,
+    arguments: body.params?.arguments || null,
+  };
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      'User-Agent': 'rdc-channel-formatter-contract-test',
+    },
+    body: JSON.stringify(body),
+  });
+  const raw = await res.text();
+  let json = null;
+  if (raw.includes('data:')) {
+    for (const line of raw.split('\n')) {
+      if (line.startsWith('data:')) json = JSON.parse(line.slice(5).trim());
+    }
+  } else if (raw.trim()) {
+    json = JSON.parse(raw);
+  }
+  const text = resultText(json);
+  log({
+    kind: 'mcp_call',
+    label,
+    url,
+    request,
+    status: res.status,
+    response: {
+      hasError: Boolean(json?.error),
+      text: summarizeText(text),
+      resultKeys: json?.result ? Object.keys(json.result) : [],
+    },
+  });
+  return { status: res.status, json, text };
+}
+
+async function waitHealth(url) {
+  for (let i = 0; i < 40; i++) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) return await res.json();
+    } catch {
+      // wait and retry
+    }
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  throw new Error(`health check timed out: ${url}`);
+}
+
+function inspectFormatterBody(body, prefix) {
+  const required = [
+    ['usage <channel|pack>', '<channel|pack>'],
+    ['social-pack mode', 'social-pack'],
+    ['campaign-pack mode', 'campaign-pack'],
+    ['exec-pack mode', 'exec-pack'],
+    ['launch-pack mode', 'launch-pack'],
+    ['strict-format mode', 'strict-format'],
+    ['long-source extraction', 'Long-Source Extraction'],
+    ['source-fidelity rules', 'Source-Fidelity'],
+    ['unsupported-claims guard', 'unsupported claims'],
+    ['LinkedIn pack output', 'LinkedIn thought-leadership post'],
+    ['Twitter thread pack output', 'Twitter/X thread'],
+    ['Slack pack output', 'Slack/Teams internal share'],
+    ['convert delegate', 'rdc:convert'],
+    ['brochure delegate', 'rdc:brochure'],
+    ['brochurify delegate', 'rdc:brochurify'],
+    ['brochure author delegate', 'lifeai-brochure-author'],
+  ];
+  for (const [name, needle] of required) {
+    check(`${prefix}: body contains ${name}`, body.includes(needle), needle);
+  }
+}
+
+function unitChecks() {
+  const names = listSkills().map((skill) => skill.name);
+  check('unit: channel-formatter in local catalog', names.includes('channel-formatter'));
+  for (const specialist of ['convert', 'brochure', 'rdc-brochurify', 'lifeai-brochure-author']) {
+    check(`unit: specialist present ${specialist}`, names.includes(specialist));
+  }
+  const results = searchSkills('turn this article into social posts');
+  check('unit: search top hit is channel-formatter', results[0]?.name === 'channel-formatter', results[0]?.name || 'none');
+  inspectFormatterBody(getSkillBody('channel-formatter') || '', 'unit');
+}
+
+async function endpointChecks(url, label) {
+  await mcp(url, label, {
+    jsonrpc: '2.0',
+    id: `${label}-init`,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'rdc-channel-formatter-contract-test', version: '1' },
+    },
+  });
+
+  const list = await mcp(url, label, {
+    jsonrpc: '2.0',
+    id: `${label}-list`,
+    method: 'tools/call',
+    params: { name: 'rdc_skill_list', arguments: {} },
+  });
+  const catalog = JSON.parse(list.text || '{"skills":[]}');
+  const names = catalog.skills.map((skill) => skill.name);
+  check(`${label}: list includes channel-formatter`, names.includes('channel-formatter'));
+  for (const specialist of ['convert', 'brochure', 'rdc-brochurify', 'lifeai-brochure-author']) {
+    check(`${label}: list includes ${specialist}`, names.includes(specialist));
+  }
+
+  const search = await mcp(url, label, {
+    jsonrpc: '2.0',
+    id: `${label}-search-social`,
+    method: 'tools/call',
+    params: { name: 'rdc_skill_search', arguments: { query: 'turn this article into social posts' } },
+  });
+  const searchPayload = JSON.parse(search.text || '{"results":[]}');
+  check(
+    `${label}: article-to-social search routes to channel-formatter`,
+    searchPayload.results[0]?.name === 'channel-formatter',
+    searchPayload.results[0]?.name || 'none',
+  );
+
+  const get = await mcp(url, label, {
+    jsonrpc: '2.0',
+    id: `${label}-get-formatter`,
+    method: 'tools/call',
+    params: { name: 'rdc_skill_get', arguments: { name: 'channel-formatter', variant: 'cli' } },
+  });
+  inspectFormatterBody(get.text, label);
+}
+
+async function main() {
+  log({ kind: 'test_start', reportFile: REPORT_FILE });
+  unitChecks();
+
+  const proc = spawn('node', [BIN], {
+    env: { ...process.env, PORT: String(TEST_PORT) },
+    stdio: 'ignore',
+  });
+  try {
+    const health = await waitHealth(LOCAL_HEALTH);
+    log({ kind: 'health', label: 'integration', health });
+    check('integration: local test server healthy', health.status === 'ok');
+    await endpointChecks(LOCAL, 'integration');
+  } finally {
+    proc.kill();
+  }
+
+  if (process.env.REMOTE || process.argv.includes('--remote')) {
+    const health = await (await fetch('https://rdc-skills.regendevcorp.com/health')).json();
+    log({ kind: 'health', label: 'systems', health });
+    check('systems: remote version is at least 0.24.8', /^0\.(2[4-9]|[3-9]\d)\./.test(health.version), health.version);
+    check('systems: remote skill count includes full catalog', health.skills >= 29, String(health.skills));
+    await endpointChecks(REMOTE, 'systems');
+  } else {
+    log({ kind: 'systems_skipped', reason: 'set REMOTE=1 or pass --remote' });
+  }
+
+  log({ kind: 'test_end', pass, fail, failures });
+  console.log(`channel-formatter contract: ${pass} passed, ${fail} failed`);
+  console.log(`audit log: ${REPORT_FILE}`);
+  if (fail) {
+    for (const failure of failures) console.log(`FAIL: ${failure}`);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  log({ kind: 'fatal', message: error?.message || String(error), stack: error?.stack || '' });
+  console.error(error);
+  process.exit(1);
+});
+