@lifeaitools/rdc-skills 0.8.7

package/commands/overnight.md

@@ -0,0 +1,220 @@
+---
+name: rdc:overnight
+description: >-
+  Usage `rdc:overnight [epic-id|label=X]` — unattended overnight supervisor, chains preplan → plan → build → review → report across all high-priority epics in --unattended mode. Use for "run overnight", "build while I sleep".
+---
+
+> **⚠️ 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.
+
+
+# rdc:overnight — Overnight Build Supervisor
+
+## When to Use
+- Starting an unattended multi-hour build session
+- Project lead says "run overnight", "build everything", "go while I sleep"
+- Kicking off a full epic queue after scoping is agreed
+
+## Arguments
+- `/rdc:overnight` — work all urgent/high priority todo epics
+- `/rdc:overnight <epic-id>` — work a specific epic only
+- `/rdc:overnight label=<label>` — work epics matching label
+
+## Phase 1 — Pre-flight
+
+**First action — set the overnight sentinel** so the `no-stop-open-epics` Stop hook engages (interactive sessions are not gated by it):
+
+```bash
+mkdir -p C:/Dev/regen-root/.rdc && touch C:/Dev/regen-root/.rdc/overnight.lock
+```
+
+**Last action at end of run (success OR failure) — remove the sentinel:**
+
+```bash
+rm -f C:/Dev/regen-root/.rdc/overnight.lock
+```
+
+If the sentinel file does not exist, the Stop hook will NOT block — which means interactive sessions stop freely and only `rdc:overnight` is held to the "drain the queue" contract.
+
+Before touching any code, verify the environment is safe:
+
+1. **Clauth daemon alive:**
+   ```bash
+   curl -s http://127.0.0.1:52437/ping
+   ```
+   If not responding: report `BLOCKED: credential daemon offline` and exit. Do not proceed.
+
+2. **Git state clean:**
+   ```bash
+   git status --short
+   ```
+   Must be on the development branch with no uncommitted changes. If dirty: commit or stash first.
+
+3. **Baseline review:**
+   Run `rdc:review --unattended`. If `REVIEW_STATUS.verdict = "HAS_ISSUES"` and
+   issues cannot be auto-fixed: report `BLOCKED: codebase has pre-existing issues` and exit.
+   A dirty baseline overnight compounds into a disaster by morning.
+
+If all three pass: proceed to Phase 2.
+
+## Phase 2 — Load Scope
+
+Determine which epics to work:
+
+- **Specific epic arg:** load that one epic via `get_work_items_by_epic()`
+- **Label filter:** `SELECT get_open_epics(p_label_filter := '<label>')`
+- **No arg (default):** `SELECT get_open_epics()` filtered to:
+  - `priority IN ('urgent', 'high')`
+  - `status IN ('todo', 'in_progress')`
+  - Order: urgent first, then high, then by `created_at`
+
+Log the epic queue at the start of `.rdc/reports/overnight-<YYYY-MM-DD>.md` (fallback: `.rdc/reports/overnight-<YYYY-MM-DD>.md` if `.rdc/` does not exist).
+
+## Phase 3 — Epic Loop
+
+For each epic in the queue, run this sequence:
+
+### 3a. Research (if needed)
+Condition: epic has 0 child tasks AND no matching doc in `.rdc/plans/` (or `.rdc/plans/` as fallback)
+
+```
+rdc:preplan <topic> --unattended
+```
+
+Check `PREPLAN_STATUS.recommendation_confidence`:
+- `"high"` or `"medium"`: proceed
+- `"low"`: escalate via advisor tool (see Escalation Protocol below)
+  - If advisor gives direction: proceed with that direction
+  - If advisor cannot resolve: skip this epic, log reason, move to next
+
+### 3b. Plan (if no tasks exist)
+Condition: epic has 0 child tasks after preplan
+
+```
+rdc:plan <epic-id> --unattended
+```
+
+Check `PLAN_STATUS.task_count > 0` before continuing.
+If 0 tasks created: escalate via advisor, then skip if still unresolved.
+
+### 3c. Build
+
+This skill delegates to rdc:build which uses typed agent dispatch. See rdc:build for agent type classification.
+
+```
+rdc:build <epic-id> --unattended
+```
+
+Agents receive the relevant guide file from `.rdc/guides/` (fallback: `.rdc/guides/`) based on their work package type.
+
+After each wave: check `BUILD_STATUS`. If `escalated: true`, log the escalation
+in the overnight doc and continue — don't stop the loop.
+
+### 3d. Review
+
+```
+rdc:review --unattended
+```
+
+Check `REVIEW_STATUS.verdict`:
+- `"CLEAN"`: mark epic `done` in work_items, push, continue to next epic
+- `"HAS_ISSUES"` with `escalations > 0`: log issues, push what's clean, continue
+- `"HAS_ISSUES"` with `escalations = 0` (all auto-fixed): push, continue
+
+### 3e. Commit checkpoint
+
+After each epic (pass or fail):
+```bash
+if [ "$RDC_TEST" != "1" ]; then
+  git push origin {development-branch}
+else
+  echo "[RDC_TEST] skipping git push origin {development-branch}"
+fi
+```
+
+This ensures every epic's work is saved regardless of what comes next.
+
+## Phase 4 — Exit
+
+After all epics are processed:
+
+1. Run `rdc:report --unattended`
+
+2. Write session summary to `.rdc/reports/overnight-<YYYY-MM-DD>.md` (fallback: `.rdc/reports/overnight-<YYYY-MM-DD>.md`):
+   ```markdown
+   # Overnight Session — YYYY-MM-DD
+
+   ## Started
+   <timestamp>
+
+   ## Epics Attempted
+   | Epic | Status | Tasks Done | Commits |
+
+   ## Epics Completed
+   <list with epic IDs>
+
+   ## Escalations
+   N advisor calls — details:
+   - <epic>: <what was escalated> → <advisor response>
+
+   ## Blockers Remaining
+   <any epics skipped or partially done>
+
+   ## Git Summary
+   - Total commits: N
+   - Push status: ✅
+
+   ## Completed
+   <timestamp>
+   ```
+
+3. Final push:
+   ```bash
+   if [ "$RDC_TEST" != "1" ]; then
+     git push origin {development-branch}
+   else
+     echo "[RDC_TEST] skipping final git push origin {development-branch}"
+   fi
+   ```
+
+## Escalation Protocol
+
+The advisor tool pairs this executor with a high-level model for high-stakes decisions.
+Use it when genuinely stuck — not for every small uncertainty.
+
+**Escalation triggers:**
+- `PREPLAN_STATUS.recommendation_confidence = "low"` (too many unknowns)
+- `PLAN_STATUS.task_count = 0` after planning (nothing actionable)
+- Build agent fails twice on the same task
+- `REVIEW_STATUS` has unfixable issues requiring architectural judgment
+- Credential daemon goes down mid-session (escalate before exiting)
+
+**How to escalate:**
+Provide the advisor with:
+1. What was attempted and what failed
+2. The error or ambiguity in detail
+3. Two most likely paths forward with tradeoffs
+4. Which epic/task is blocked
+
+**After advisor responds:**
+- Log the guidance in the overnight doc
+- Resume the loop from where it stopped
+- If advisor cannot resolve: mark task/epic `blocked`, log reason, skip to next
+
+**Max escalations:** 3 per epic. After 3, skip the epic and log.
+
+## Safety Rules
+
+- Branch: development branch always — NEVER touch main/production
+- NEVER run `pnpm build` — use `npx tsc --noEmit` for typecheck, vitest for tests only on modified packages
+- NEVER let agents overlap on the same files
+- Push after every epic, not just at the end
+- Update Supabase work items in real time throughout
+- Max 2 hours per epic — if exceeded, skip and log `TIMEOUT`
+- If credential daemon goes down mid-session: write current state to overnight doc, push, exit gracefully
+- If git push fails: log the failure, attempt rebase, retry once — do not force push

package/commands/plan.md

@@ -0,0 +1,158 @@
+---
+name: rdc:plan
+description: >-
+  Usage `rdc:plan <topic> [--unattended]` — architecture doc with design decisions, tradeoffs, work packages. Creates Supabase epics/tasks. Use after rdc:preplan or when given clear architectural direction.
+---
+
+> **⚠️ 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`).
+
+
+# rdc:plan — Architecture & Work Packages
+
+## When to Use
+- After `/rdc:preplan` produced research findings
+- Project lead gives architectural direction ("build X with Y approach")
+- An epic exists but needs breakdown into implementable tasks
+- Before any large build session
+- Called by `rdc:overnight` when an epic has no child tasks
+
+## Arguments
+- `rdc:plan <topic>` — interactive planning session
+- `rdc:plan <epic-id> --unattended` — silent mode for overnight builds
+
+## Procedure
+
+1. **Load source documents — MANDATORY before any planning decisions.**
+
+   **Step 1a — Always load these regardless of topic:**
+   ```
+   .claude/rules/infrastructure-contract.md   — hard deployment + registry rules
+   .claude/rules/work-items-rpc.md            — work item schema, RPC, status enums
+   .claude/rules/system-quick-links.md        — routing map to all system architecture docs
+   .claude/rules/version-numbering.md         — version bump rules for affected packages
+   ```
+
+   **Step 1b — Identify affected domains, then load the matching architecture doc:**
+
+   | Domain keywords in topic | Architecture doc to read |
+   |--------------------------|---------------------------|
+   | PRT, trust, capital, NAV, investor, land, DST | `docs/systems/prt/ARCHITECTURE.md` |
+   | CS 2.0, HAIL, PAL, virtue, quad-pixel, ontology, BPMN, cognitive | `docs/systems/cs2/ARCHITECTURE.md` |
+   | marketing, CRM, campaign, contact, outreach, RDC app | `docs/systems/rdc/ARCHITECTURE.md` |
+   | Claude workflow, skills, agents, dispatch, rdc:build | `docs/systems/claude-workflow/ARCHITECTURE.md` |
+   | Life AI, LIFEAI platform, life.ai | `docs/systems/lifeai/ARCHITECTURE.md` |
+   | media, R2, images, regen-media, MCP image | `docs/systems/media/ARCHITECTURE.md` |
+   | UI, component, brand, design token, shared, OG image | `docs/systems/shared/ARCHITECTURE.md` |
+
+   If the topic spans multiple domains: read ALL matching architecture docs before proceeding.
+   A plan that contradicts an existing architecture doc is invalid — load them first.
+
+   **Step 1c — Load domain-specific rules and context files:**
+
+   | Domain | Additional files to read |
+   |--------|---------------------------|
+   | CS 2.0 / any CS2 paradigm work | `.claude/rules/cs2-architecture-first.md` |
+   | Database, schema, migrations, RPC | `.claude/context/supabase-schema.md` |
+   | UI, components, brand, tokens | `.claude/context/design-system-global.md` |
+   | Deploy, infrastructure, DNS, SSL | `.claude/context/coolify-deployment.md` |
+   | Credentials, MCP, clauth, subagents | `.claude/context/clauth.md` |
+   | OG images, social meta, brand assets | `.claude/context/brand-gate.md` |
+   | Cross-platform, Cowork, subagent MCP | `.claude/context/platform-cross-ref.md` |
+   | MCP server development | `.claude/context/mcp-server-auth.md` |
+
+   **Step 1d — Load CLAUDE.md for every affected package:**
+   - Identify which packages in `packages/` will be created or modified
+   - Read `packages/<name>/CLAUDE.md` for each one that has one
+   - Mandatory: `packages/supabase/CLAUDE.md` if any DB work is involved
+   - Mandatory: `packages/ui/CLAUDE.md` if any UI work is involved
+   - Read `packages/<name>/package.json` to understand current exports and dependencies
+
+2. **Gather additional inputs:**
+   - Research doc from preplan (if exists): `.rdc/research/<topic>.md` (fallback: `.rdc/research/<topic>.md`)
+   - Project lead's architectural direction from conversation
+   - Existing Supabase epics: `SELECT get_open_epics()`
+   - Check `prototype_registry` for any existing prototypes on this topic:
+     ```sql
+     SELECT name, component, source_path, status FROM prototype_registry
+     WHERE status IN ('prototype', 'converting') ORDER BY created_at DESC;
+     ```
+   - Check `design_context` for prior design decisions:
+     ```sql
+     SELECT topic, context_type, summary FROM design_context
+     WHERE topic ILIKE '%<topic>%' ORDER BY created_at DESC;
+     ```
+
+3. **Read the codebase** — understand current state:
+   - What packages are affected?
+   - What types/interfaces already exist?
+   - What tests exist?
+   - What's the dependency graph?
+
+4. **Make design decisions** — for each major choice:
+   - State the decision clearly
+   - Document what was chosen and what was rejected
+   - Explain WHY (tradeoff rationale)
+   - Note consequences and reversibility
+   - **Verify the decision does not contradict any loaded architecture doc** — if it does, flag the conflict before proceeding
+
+5. **Define work packages** — break into agent-dispatchable units:
+   - Each work package = one agent assignment
+   - No file overlap between packages
+   - Each package has: scope, files to create/modify, test requirements
+   - Assign an agent type to each work package from the typed dispatch table in rdc:build
+   - Include the guide file path (from `.rdc/guides/`, fallback `.rdc/guides/`) in each work package description
+   - Include any relevant architecture doc, context file, or package CLAUDE.md the agent must read
+   - Estimate: small (1 agent, <500 LOC), medium (1 agent, 500-1500 LOC), large (needs splitting)
+
+6. **Write plan doc** to `.rdc/plans/<topic-slug>.md` (fallback: `.rdc/plans/<topic-slug>.md` if `.rdc/` does not exist):
+   ```markdown
+   # Plan: <Topic>
+   > Generated: <date> | Epic: <id if exists>
+
+   ## Source Documents Read
+   (list every architecture doc, rules file, context file, and package CLAUDE.md loaded in Step 1)
+
+   ## Goal
+   ## Design Decisions
+   ## Work Packages
+   (each package must include: agent type, guide file, architecture docs agent must read, files to create/modify, test requirements)
+   ## Sequencing (what can parallelize, what depends on what)
+   ## Risks & Mitigations
+   ## Architecture Doc Conflicts (if any)
+   ```
+
+7. **Create Supabase epic + child tasks:**
+   - Epic via `insert_work_item(p_item_type := 'epic', ...)`
+   - One task per work package via `insert_work_item(p_parent_id := <epic_id>, ...)`
+   - Set priorities: urgent/high/normal based on sequencing
+
+8. **Report results:**
+   - Interactive: present the plan for approval before building
+   - Unattended: skip approval, proceed immediately, emit status block:
+     ```
+     PLAN_STATUS: { epic_id, task_count, doc_path, waves, source_docs_read: [list], architecture_conflicts: [] }
+     ```
+
+## Unattended Escalation
+
+When `--unattended` and genuine architectural ambiguity is detected — meaning multiple
+valid approaches exist with significantly different tradeoffs (not just minor style choices)
+— escalate via the advisor tool. Provide: the decision point, the options with tradeoffs,
+and the project context. Resume with advisor's recommendation. If advisor is unavailable,
+choose the most conservative/reversible approach and document the decision.
+
+## Rules
+- **Source documents in Step 1 are MANDATORY — a plan that hasn't read the architecture docs is invalid**
+- Interactive: ALWAYS get approval before proceeding to build
+- Unattended: proceed immediately without approval
+- Plan doc goes in `.rdc/plans/` (fallback: `.rdc/plans/` if `.rdc/` does not exist) — not `.planning/`
+- Each work package must be independently executable by an agent
+- No file overlap between work packages
+- Include test requirements in every work package
+- Reference affected CLAUDE.md files and architecture docs in each work package description
+- Reference the relevant guide file from `.rdc/guides/` (fallback: `.rdc/guides/`) for agent context
+- Always list source docs read in the output doc header and status block

package/commands/preplan.md

@@ -0,0 +1,131 @@
+---
+name: rdc:preplan
+description: >-
+  Usage `rdc:preplan <topic> [--unattended]` — research best practices, analyze codebase, compare approaches, surface unknowns before committing to a plan. Produces a research doc. No decisions, no 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`).
+
+
+# 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. **Load source documents — MANDATORY before any analysis.**
+
+   **Step 2a — Always load these regardless of topic:**
+   ```
+   .claude/rules/infrastructure-contract.md   — hard deployment + registry rules
+   .claude/rules/work-items-rpc.md            — work item schema and RPC patterns
+   .claude/rules/system-quick-links.md        — routing map to system architecture docs
+   ```
+
+   **Step 2b — Identify affected domains, then load the matching architecture doc:**
+
+   | Domain keywords in topic | Architecture doc to read |
+   |--------------------------|---------------------------|
+   | PRT, trust, capital, NAV, investor, land, DST | `docs/systems/prt/ARCHITECTURE.md` |
+   | CS 2.0, HAIL, PAL, virtue, quad-pixel, ontology, BPMN, cognitive | `docs/systems/cs2/ARCHITECTURE.md` |
+   | marketing, CRM, campaign, contact, outreach, RDC app | `docs/systems/rdc/ARCHITECTURE.md` |
+   | Claude workflow, skills, agents, dispatch, rdc:build | `docs/systems/claude-workflow/ARCHITECTURE.md` |
+   | Life AI, LIFEAI platform, life.ai | `docs/systems/lifeai/ARCHITECTURE.md` |
+   | media, R2, images, regen-media, MCP image | `docs/systems/media/ARCHITECTURE.md` |
+   | UI, component, brand, design token, shared, OG image | `docs/systems/shared/ARCHITECTURE.md` |
+
+   If topic spans multiple domains, read ALL matching architecture docs.
+   If unsure which domain applies, read `docs/systems/claude-workflow/ARCHITECTURE.md` as the fallback.
+
+   **Step 2c — Load domain-specific rules and context files:**
+
+   | Domain | Additional files to read |
+   |--------|---------------------------|
+   | CS 2.0 / any CS2 paradigm work | `.claude/rules/cs2-architecture-first.md` |
+   | Database, schema, migrations, RPC | `.claude/context/supabase-schema.md` |
+   | UI, components, brand, tokens | `.claude/context/design-system-global.md` |
+   | Deploy, infrastructure, DNS, SSL | `.claude/context/coolify-deployment.md` |
+   | Credentials, MCP, clauth, subagents | `.claude/context/clauth.md` |
+   | OG images, social meta, brand assets | `.claude/context/brand-gate.md` |
+   | Cross-platform, Cowork, subagent MCP | `.claude/context/platform-cross-ref.md` |
+
+   **Step 2d — Load CLAUDE.md for every affected package:**
+   - Identify which packages in `packages/` are relevant to the topic
+   - Read `packages/<name>/CLAUDE.md` for each one
+   - At minimum read `packages/supabase/CLAUDE.md` if any DB work is involved
+   - At minimum read `packages/ui/CLAUDE.md` if any UI work is involved
+
+3. **Web research** — search for current (2025-2026) best practices:
+   - How do major projects solve this?
+   - What tools/libraries exist?
+   - What are the common tradeoffs?
+
+4. **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
+
+5. **Best-in-class comparison** — create a comparison table:
+   | Approach | Pros | Cons | Fit for Us |
+
+6. **Surface unknowns** — what questions remain unanswered?
+
+7. **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
+
+   ## Source Documents Read
+   (list every architecture doc, rules file, context file, and package CLAUDE.md loaded in Step 2)
+
+   ## Question
+   ## What We Already Have
+   ## Best-in-Class Analysis
+   ## Comparison Table
+   ## Unknowns & Open Questions
+   ## Recommendation (preliminary — not a decision)
+   ```
+
+8. **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", source_docs_read: [list] }
+     ```
+
+## 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
+- **Source documents in Step 2 are MANDATORY — research without them is blind**
+- 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
+- Always list source docs read in the output doc header

package/commands/prototype.md

@@ -0,0 +1,145 @@
+---
+name: rdc:prototype
+description: >-
+  Usage `rdc:prototype <description>` — build JSX/TSX prototype for review before CLI handoff. Saves to docs/source/, registers in prototype_registry. Use for "mock this up", "show me what it looks like". Reference material only, not production.
+---
+
+> **⚠️ 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`).
+
+
+# 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
+
+## 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
+```