@lifeaitools/rdc-skills 0.21.1 → 0.23.0

package/skills/preplan/SKILL.md

@@ -1,90 +1,90 @@
----
-name: rdc:preplan
-description: "Usage `rdc:preplan <topic>` — Before committing to an architecture, research unknowns first. Codebase scan + web search, no code written, no work items created. Output feeds rdc:plan. Use for open-ended approach questions."
----
-
-> **⚠️ 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. This skill is read-only and produces only local file writes — no destructive external calls to short-circuit.
-
-
-# rdc:preplan — Research Before Planning
-
-## When to Use
-- Starting a new feature area you haven't built before
-- Need to understand how best-in-class projects solve a problem
-- Codebase has unknowns that need mapping before planning
-- Project lead says "research", "look into", "what's the best way to", "how do others do"
-- Called by `rdc:overnight` before planning an epic with no existing tasks
-
-## Arguments
-- `rdc:preplan <topic>` — interactive research session
-- `rdc:preplan <topic> --unattended` — silent mode for overnight builds
-
-## Procedure
-
-1. **Parse the topic** from user input or epic title/description.
-   - Interactive: if vague, ask ONE clarifying question before proceeding
-   - Unattended: infer from the epic title + description — never pause to ask
-
-2. **Web research** — search for current (2025-2026) best practices:
-   - How do major projects solve this?
-   - What tools/libraries exist?
-   - What are the common tradeoffs?
-
-3. **Codebase analysis** — what do we already have?
-   - Search relevant packages for existing code
-   - Check `.rdc/research/` for prior research on this topic (fallback: `.rdc/research/`)
-   - Check `docs/archive/` for historical work
-   - Research agents should read relevant guides from `.rdc/guides/` (fallback: `.rdc/guides/`)
-   - Check work items for related epics
-   - Read relevant CLAUDE.md files
-
-4. **Best-in-class comparison** — create a comparison table:
-   | Approach | Pros | Cons | Fit for Us |
-
-5. **Surface unknowns** — what questions remain unanswered?
-
-6. **Write research doc** to `.rdc/research/<topic-slug>.md` (fallback: `.rdc/research/<topic-slug>.md` if `.rdc/` does not exist):
-   ```markdown
-   # Research: <Topic>
-   > Generated: <date> | Requested by: Project Lead
-
-   ## Question
-   ## What We Already Have
-   ## Best-in-Class Analysis
-   ## Comparison Table
-   ## Unknowns & Open Questions
-   ## Recommendation (preliminary — not a decision)
-   ```
-
-7. **Report results:**
-   - Interactive: summarize findings. Do NOT create epics or write code.
-   - Unattended: skip summary, emit status block only:
-     ```
-     PREPLAN_STATUS: { topic, doc_path, unknowns_count, recommendation_confidence: "high|medium|low" }
-     ```
-
-## Unattended Escalation
-
-When `--unattended` and `recommendation_confidence` is `"low"` (≥5 unresolved unknowns,
-or no clear best-fit approach exists), escalate via the advisor tool rather than stopping.
-Provide the advisor with: topic, unknowns list, comparison table. Resume with advisor's
-direction if given. If advisor cannot resolve, log and skip to next step.
-
-## Rules
-- Output is a RESEARCH DOC, not a plan
-- Do not make architectural decisions — surface options with tradeoffs
-- Do not create work items
-- Do not write code
-- Web search is mandatory — don't just analyze the codebase
-- Keep the doc under 200 lines — concise, not exhaustive
-- Unattended: NEVER pause for input; infer and proceed
-
-## Capture lessons (exit step)
-
-Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-preplan-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.
+---
+name: rdc:preplan
+description: "Usage `rdc:preplan <topic>` — Before committing to an architecture, research unknowns first. Codebase scan + web search, no code written, no work items created. Output feeds rdc:plan. Use for open-ended approach questions."
+---
+
+> **⚠️ 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. This skill is read-only and produces only local file writes — no destructive external calls to short-circuit.
+
+
+# rdc:preplan — Research Before Planning
+
+## When to Use
+- Starting a new feature area you haven't built before
+- Need to understand how best-in-class projects solve a problem
+- Codebase has unknowns that need mapping before planning
+- Project lead says "research", "look into", "what's the best way to", "how do others do"
+- Called by `rdc:overnight` before planning an epic with no existing tasks
+
+## Arguments
+- `rdc:preplan <topic>` — interactive research session
+- `rdc:preplan <topic> --unattended` — silent mode for overnight builds
+
+## Procedure
+
+1. **Parse the topic** from user input or epic title/description.
+   - Interactive: if vague, ask ONE clarifying question before proceeding
+   - Unattended: infer from the epic title + description — never pause to ask
+
+2. **Web research** — search for current (2025-2026) best practices:
+   - How do major projects solve this?
+   - What tools/libraries exist?
+   - What are the common tradeoffs?
+
+3. **Codebase analysis** — what do we already have?
+   - Search relevant packages for existing code
+   - Check `.rdc/research/` for prior research on this topic (fallback: `.rdc/research/`)
+   - Check `docs/archive/` for historical work
+   - Research agents should read relevant guides from `.rdc/guides/` (fallback: `.rdc/guides/`)
+   - Check work items for related epics
+   - Read relevant CLAUDE.md files
+
+4. **Best-in-class comparison** — create a comparison table:
+   | Approach | Pros | Cons | Fit for Us |
+
+5. **Surface unknowns** — what questions remain unanswered?
+
+6. **Write research doc** to `.rdc/research/<topic-slug>.md` (fallback: `.rdc/research/<topic-slug>.md` if `.rdc/` does not exist):
+   ```markdown
+   # Research: <Topic>
+   > Generated: <date> | Requested by: Project Lead
+
+   ## Question
+   ## What We Already Have
+   ## Best-in-Class Analysis
+   ## Comparison Table
+   ## Unknowns & Open Questions
+   ## Recommendation (preliminary — not a decision)
+   ```
+
+7. **Report results:**
+   - Interactive: summarize findings. Do NOT create epics or write code.
+   - Unattended: skip summary, emit status block only:
+     ```
+     PREPLAN_STATUS: { topic, doc_path, unknowns_count, recommendation_confidence: "high|medium|low" }
+     ```
+
+## Unattended Escalation
+
+When `--unattended` and `recommendation_confidence` is `"low"` (≥5 unresolved unknowns,
+or no clear best-fit approach exists), escalate via the advisor tool rather than stopping.
+Provide the advisor with: topic, unknowns list, comparison table. Resume with advisor's
+direction if given. If advisor cannot resolve, log and skip to next step.
+
+## Rules
+- Output is a RESEARCH DOC, not a plan
+- Do not make architectural decisions — surface options with tradeoffs
+- Do not create work items
+- Do not write code
+- Web search is mandatory — don't just analyze the codebase
+- Keep the doc under 200 lines — concise, not exhaustive
+- Unattended: NEVER pause for input; infer and proceed
+
+## Capture lessons (exit step)
+
+Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-preplan-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.

package/skills/prototype/SKILL.md

@@ -1,150 +1,150 @@
----
-name: rdc:prototype
-description: "Usage `rdc:prototype <description>` — Build a JSX/TSX mockup for visual review before implementation. Saves to docs/source/, registers in prototype_registry. Use when asked to mock something up or show what it looks like. Not production code."
----
-
-> **⚠️ 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 prototype_registry and design_context inserts, and git push are skipped under `RDC_TEST=1`.
-
-
-# rdc:prototype — Prototype Builder
-
-## When to Use
-
-- Project lead wants to see a design before committing to implementation
-- A new component or page needs visual review before wiring to database
-- Testing a data layout or interaction pattern
-- Building a visual mockup for approval
-
-## Arguments
-
-- `rdc:prototype <description>` — describe the UI to build (e.g. "a data table for work items")
-
-## What This Produces
-
-- JSX/TSX prototype file → `docs/source/<ComponentName>.jsx`
-- prototype_registry entry in database
-- design_context entries for key decisions
-
-## Prototype Rules
-
-1. **Self-contained** — no real database calls. Mock data arrays only.
-2. **Realistic data** — mock data must reflect actual schema field names
-3. **Full fidelity** — looks exactly like the final product should look
-4. **Annotated** — key design decisions commented at the top of the file
-5. **Handoff-ready** — includes the spec block at the bottom
-
-## Standard Mock Data Pattern
-
-Use realistic field names from the actual database schema:
-
-```tsx
-// Mock data — mirrors your_table
-const MOCK_DATA = [
-  {
-    id: "uuid-1",
-    slug: "example-slug",
-    name: "Example Name",
-    description: "...",
-    location_city: "City",
-    location_state: "State",
-    status: "active",
-    category: "example-category",
-    total_capital: 1000000,
-    total_area: 2400,
-    deploy_url: "https://...",
-    tags: ["tag1", "tag2"],
-    alignment: ["value1", "value2"],
-    web_visible: true,
-    ticker_label: "LABEL",
-    ticker_capital: "$1M",
-    scores: { field1: 82, field2: 71, field3: 68 },
-  },
-];
-```
-
-## File Header Template
-
-```tsx
-/**
- * <ComponentName>.jsx — PROTOTYPE
- * ─────────────────────────────────────────────
- * Status: Prototype — reference only, not production code
- * Created: <date>
- * Route (production target): <app-route>
- *
- * Key design decisions:
- * 1. <Decision and rationale>
- * 2. <Decision and rationale>
- *
- * What to preserve in production:
- * - <Design element>
- * - <Interaction pattern>
- *
- * What production implementation must do differently:
- * - Replace mock data with database query
- * - Import <Component> from @regen/ui instead of inline implementation
- * - Extract <Part> into shared component at src/components/<name>
- *
- * Production agent type: frontend | backend | data | viz
- * Production guide: .rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md)
- */
-```
-
-## File Footer Template
-
-```tsx
-// ─── HANDOFF SPEC ─────────────────────────────
-// Production files:
-//   apps/<app>/src/app/<route>/page.tsx           (server component)
-//   apps/<app>/src/app/<route>/<Name>Client.tsx   (client component)
-//   apps/<app>/src/app/<route>/<Name>Wrapper.tsx  (modal/state shell, if needed)
-//
-// Design system components to use (do not re-implement):
-//   <ComponentName> — <what it does>
-//
-// Database tables:
-//   <table> — <what to query>
-//
-// Form field schema additions needed:
-//   <table>.<column> — <input_type> — <label>
-```
-
-## After Building — Register and Record
-
-```sql
--- Register prototype
-INSERT INTO prototype_registry (name, component, source_path, notes, created_by)
-VALUES (
-  '<Name> Prototype v1',
-  '<ComponentName>',
-  'docs/source/<ComponentName>.jsx',
-  '<One-line description of key design: layout, data shape, interactions>',
-  'planning'
-);
-
--- Record design decisions
-INSERT INTO design_context (topic, context_type, summary, source, created_by)
-VALUES
-  ('<Topic>', 'prototype', 'Prototype built with <X> layout and <Y> interaction pattern', 'planning', 'planning'),
-  ('<Topic>', 'decision',  '<Key decision made during prototyping and why>', 'planning', 'planning');
-```
-
-## Handoff
-
-After prototype is approved, use `rdc:handoff` to create the plan doc and database work items.
-
-Or tell the project lead:
-```
-Prototype complete.
-File: docs/source/<ComponentName>.jsx
-Registered: prototype_registry
-
-To hand off to CLI build: use /rdc:handoff
-To build immediately: use /rdc:build
-```
+---
+name: rdc:prototype
+description: "Usage `rdc:prototype <description>` — Build a JSX/TSX mockup for visual review before implementation. Saves to docs/source/, registers in prototype_registry. Use when asked to mock something up or show what it looks like. Not production code."
+---
+
+> **⚠️ 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 prototype_registry and design_context inserts, and git push are skipped under `RDC_TEST=1`.
+
+
+# rdc:prototype — Prototype Builder
+
+## When to Use
+
+- Project lead wants to see a design before committing to implementation
+- A new component or page needs visual review before wiring to database
+- Testing a data layout or interaction pattern
+- Building a visual mockup for approval
+
+## Arguments
+
+- `rdc:prototype <description>` — describe the UI to build (e.g. "a data table for work items")
+
+## What This Produces
+
+- JSX/TSX prototype file → `docs/source/<ComponentName>.jsx`
+- prototype_registry entry in database
+- design_context entries for key decisions
+
+## Prototype Rules
+
+1. **Self-contained** — no real database calls. Mock data arrays only.
+2. **Realistic data** — mock data must reflect actual schema field names
+3. **Full fidelity** — looks exactly like the final product should look
+4. **Annotated** — key design decisions commented at the top of the file
+5. **Handoff-ready** — includes the spec block at the bottom
+
+## Standard Mock Data Pattern
+
+Use realistic field names from the actual database schema:
+
+```tsx
+// Mock data — mirrors your_table
+const MOCK_DATA = [
+  {
+    id: "uuid-1",
+    slug: "example-slug",
+    name: "Example Name",
+    description: "...",
+    location_city: "City",
+    location_state: "State",
+    status: "active",
+    category: "example-category",
+    total_capital: 1000000,
+    total_area: 2400,
+    deploy_url: "https://...",
+    tags: ["tag1", "tag2"],
+    alignment: ["value1", "value2"],
+    web_visible: true,
+    ticker_label: "LABEL",
+    ticker_capital: "$1M",
+    scores: { field1: 82, field2: 71, field3: 68 },
+  },
+];
+```
+
+## File Header Template
+
+```tsx
+/**
+ * <ComponentName>.jsx — PROTOTYPE
+ * ─────────────────────────────────────────────
+ * Status: Prototype — reference only, not production code
+ * Created: <date>
+ * Route (production target): <app-route>
+ *
+ * Key design decisions:
+ * 1. <Decision and rationale>
+ * 2. <Decision and rationale>
+ *
+ * What to preserve in production:
+ * - <Design element>
+ * - <Interaction pattern>
+ *
+ * What production implementation must do differently:
+ * - Replace mock data with database query
+ * - Import <Component> from @regen/ui instead of inline implementation
+ * - Extract <Part> into shared component at src/components/<name>
+ *
+ * Production agent type: frontend | backend | data | viz
+ * Production guide: .rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md)
+ */
+```
+
+## File Footer Template
+
+```tsx
+// ─── HANDOFF SPEC ─────────────────────────────
+// Production files:
+//   apps/<app>/src/app/<route>/page.tsx           (server component)
+//   apps/<app>/src/app/<route>/<Name>Client.tsx   (client component)
+//   apps/<app>/src/app/<route>/<Name>Wrapper.tsx  (modal/state shell, if needed)
+//
+// Design system components to use (do not re-implement):
+//   <ComponentName> — <what it does>
+//
+// Database tables:
+//   <table> — <what to query>
+//
+// Form field schema additions needed:
+//   <table>.<column> — <input_type> — <label>
+```
+
+## After Building — Register and Record
+
+```sql
+-- Register prototype
+INSERT INTO prototype_registry (name, component, source_path, notes, created_by)
+VALUES (
+  '<Name> Prototype v1',
+  '<ComponentName>',
+  'docs/source/<ComponentName>.jsx',
+  '<One-line description of key design: layout, data shape, interactions>',
+  'planning'
+);
+
+-- Record design decisions
+INSERT INTO design_context (topic, context_type, summary, source, created_by)
+VALUES
+  ('<Topic>', 'prototype', 'Prototype built with <X> layout and <Y> interaction pattern', 'planning', 'planning'),
+  ('<Topic>', 'decision',  '<Key decision made during prototyping and why>', 'planning', 'planning');
+```
+
+## Handoff
+
+After prototype is approved, use `rdc:handoff` to create the plan doc and database work items.
+
+Or tell the project lead:
+```
+Prototype complete.
+File: docs/source/<ComponentName>.jsx
+Registered: prototype_registry
+
+To hand off to CLI build: use /rdc:handoff
+To build immediately: use /rdc:build
+```