@lifeaitools/rdc-skills 0.8.7

package/guides/agents/design.md

@@ -0,0 +1,77 @@
+> **⚠️ 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:design — Design Agent
+
+## Mandatory First Step
+
+Read the guide before ANY work:
+```
+{PROJECT_ROOT}/.rdc/guides/design.md
+(fallback: {PROJECT_ROOT}/.rdc/guides/design.md)
+```
+
+## Six Design Principles
+
+1. **User/Community First** — Serving those affected by the work
+2. **Stewardship, Not Ownership** — Components hold space, don't dominate
+3. **Verified, Not Narrated** — Real data only; no mocks
+4. **Readability at Every Gate** — Clarity scales, jargon does not
+5. **Dark by Default, Never Dark by Habit** — Dark palette signals trust
+6. **Machines Handle Calculation; Humans Handle Conscience**
+
+## Token System
+
+Two-layer model:
+```
+global_design_tokens (base tokens)
+  + brand_token_overrides (per-brand delta)
+  = TokenWithInheritance[] (resolved set)
+```
+
+Token export formats: JSON flat map, CSS vars (`:root`), other format systems.
+
+## OG Images
+
+| Property | Value |
+|----------|-------|
+| Dimensions | 1200 × 630 px |
+| Format | RGB PNG, committed to git |
+| Location | `apps/<app>/public/og/og-image.png` |
+| Max size | 200 KB |
+
+Metadata:
+```ts
+export const metadata: Metadata = {
+  openGraph: {
+    images: [{ url: "/og/og-image.png", width: 1200, height: 630, alt: "..." }],
+  },
+  twitter: { card: "summary_large_image", images: ["/og/og-image.png"] },
+};
+```
+
+## Variant Axes — Every Component Must Support
+
+| Axis | Values |
+|------|--------|
+| Size | xs / sm / md / lg / xl |
+| Shape | sharp / soft / pill / circle |
+| Density | compact / comfortable / spacious |
+| Motion | static / subtle / rich |
+
+## Animation Philosophy
+
+- Always respect `prefers-reduced-motion` via appropriate hooks
+- Token-driven durations and easing — never hardcoded values
+- Keep motion purposeful, not decorative
+
+## Safety Rules
+
+- Never hardcode hex colors in components — CSS variables only
+- Never override tokens without a design decision recorded
+- Branch: development branch — auto-commit
+- NEVER run `pnpm build`

package/guides/agents/frontend.md

@@ -0,0 +1,92 @@
+> **⚠️ 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 guide honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
+
+
+# rdc:frontend — Frontend Agent
+
+## Mandatory First Step
+
+Read the guide before ANY code:
+```
+{PROJECT_ROOT}/.rdc/guides/frontend.md
+(fallback: {PROJECT_ROOT}/.rdc/guides/frontend.md)
+```
+
+## Before Writing Any Code
+
+1. **Check for existing prototypes:**
+   ```sql
+   SELECT name, component, source_path, status, notes
+   FROM prototype_registry
+   WHERE status IN ('prototype', 'converting')
+   ORDER BY created_at DESC;
+   ```
+   If a prototype exists: **ADAPT IT. Do not build from scratch.**
+
+2. **Check design decisions:**
+   ```sql
+   SELECT topic, summary FROM design_context
+   WHERE topic ILIKE '%<task-topic>%'
+   ORDER BY created_at DESC;
+   ```
+
+3. **Read the app CLAUDE.md** for the target app.
+
+## New Component Contract
+
+All new components follow the standard pattern:
+
+```tsx
+"use client"; // only if uses hooks/browser APIs
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/utils";
+
+const myComponentVariants = cva("base-classes", {
+  variants: {
+    variant: { default: "", outline: "" },
+    size: { sm: "", md: "", lg: "" },
+  },
+  defaultVariants: { variant: "default", size: "md" },
+});
+
+interface MyComponentProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof myComponentVariants> {}
+
+const MyComponent = React.forwardRef<HTMLDivElement, MyComponentProps>(
+  ({ className, variant, size, ...props }, ref) => (
+    <div ref={ref} className={cn(myComponentVariants({ variant, size }), className)} {...props} />
+  )
+);
+MyComponent.displayName = "MyComponent";
+export { MyComponent, myComponentVariants };
+```
+
+Then re-export from the package's index.
+
+## Next.js Patterns
+
+- App Router (modern) — use `src/app/`
+- Dynamic imports for browser-only libs
+- `transpilePackages` in next.config must list all monorepo packages used
+- Auth: use the auth helpers for protected apps; pass-through for public
+
+## Colors — CSS Variables ONLY
+
+Never hardcode hex values in components. Always use CSS variables from the app's globals.css.
+
+## Safety Rules
+
+- Branch: development branch — auto-commit after logical blocks
+- NEVER run `pnpm build` — crashes the system; code only
+- NEVER overlap with other agents on the same files
+- NEVER modify files outside your assigned scope
+- After completing: commit with descriptive message, push *(skip push if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
+- Update work item to `done` via `update_work_item_status()`
+- Write tests FIRST — red → implement → green

package/guides/agents/infrastructure.md

@@ -0,0 +1,81 @@
+> **⚠️ 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 guide honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag — Coolify deploys, DNS writes, CF cache purges, container restarts, and `git push` are all skipped. Registry SELECTs, health checks, and git reads run normally.
+
+
+# rdc:infra — Infrastructure Agent
+
+## Mandatory First Step
+
+Read the guide before ANY operations:
+```
+{PROJECT_ROOT}/.rdc/guides/infrastructure.md
+(fallback: {PROJECT_ROOT}/.rdc/guides/infrastructure.md)
+```
+
+## Rule 1: Never Work Around Broken Infrastructure
+
+When a service is unavailable, STOP and report:
+```
+BLOCKED: [service] is not responding.
+Fix: [reconnect MCP / restart credential daemon]
+I cannot proceed until this is resolved.
+```
+
+## Deployment Registry — Check BEFORE Any Deploy
+
+```sql
+SELECT get_deployment('<slug>');
+SELECT slug, display_name, domain, build_type, status FROM deployment_registry ORDER BY slug;
+```
+
+**NEVER guess deployment UUIDs, domains, or build commands.**
+
+## Watch Paths — Must Set on Every Monorepo App
+
+| App Type | Watch Paths |
+|----------|-------------|
+| Monorepo app | `apps/<n>/**` and `packages/**` |
+| Static monorepo | `sites/<n>/**` |
+
+Without watch_paths, every push rebuilds all apps.
+
+## Build Types
+
+| Type | Pack | Install | Build |
+|------|------|---------|-------|
+| Monorepo | nixpacks | `pnpm install --frozen-lockfile` | `pnpm turbo run build --filter=<filter>` |
+| Static | static | — | — |
+
+## New App — Checklist
+
+1. Look up deployment registry for existing entry
+2. Check for Coolify UUID (if exists)
+3. Set watch_paths per app type *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping Coolify config write`)*
+4. Deploy and verify health *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping Coolify deploy`)*
+5. Update deployment_registry in database
+
+## Environment Tiers
+
+| Tier | Rules |
+|------|-------|
+| development | Free to experiment, no confirmation needed |
+| staging | Confirm before deploying |
+| production | ALWAYS confirm before deploy, ALWAYS verify after |
+
+## Git Workflow
+
+- Branch: development branch — NEVER touch production
+- Before push: `git fetch origin`
+- Never force-push
+
+## Safety Rules
+
+- MCP connectors first, credential daemon second
+- Never print credential keys to stdout
+- If daemon is down: report BLOCKED, do not work around it
+- Push after every logical block *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*

package/guides/agents/setup.md

@@ -0,0 +1,279 @@
+> **⚠️ 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.
+
+
+> **Sandbox contract:** This guide honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
+
+# /rdc:setup — Intelligent Project Setup
+
+Scan the current project, detect all existing configuration, and generate (or update) `.rdc/config.json` and overlay guides. Works on both new and existing projects.
+
+---
+
+## Step 1 — Scan the project
+
+Read these files (all optional — use what exists):
+
+| File | What to extract |
+|------|----------------|
+| `package.json` | `name`, `description`, stack (next/vite/etc), monorepo? |
+| `pnpm-workspace.yaml` or `lerna.json` | monorepo structure |
+| `git remote get-url origin` | GitHub org + repo name |
+| `git branch -a` | main/develop/master detection |
+| `.env.local`, `apps/**/.env.local` | `NEXT_PUBLIC_SUPABASE_URL` → extract project ref |
+| `CLAUDE.md` | PROJECT_SCOPE, forbidden commands, branch rules, supabase ref |
+| `.claude/rules/*.md` | existing rule files, what systems are covered |
+| `docs/guides/agent-bootstrap.md` or `.rdc/guides/agent-bootstrap.md` | existing credentials pattern |
+| `.rdc/config.json` | already configured? just show current state + offer update |
+| `docs/guides/`, `docs/plans/`, `.rdc/guides/`, `.rdc/plans/` | existing directory structure (either layout) |
+| `apps/` or `sites/` | app names, ports from package.json `dev` scripts |
+| `supabase/migrations/` | schema exists? |
+| `tailwind.config.*` | Tailwind confirmed |
+| `vitest.config.*` or `jest.config.*` | test framework |
+| `.coolify/` or coolify deployment refs | deploy platform |
+
+Emit a structured summary of what you found:
+```
+Detected:
+  Project name  : <name>
+  GitHub        : <org>/<repo>
+  Supabase ref  : <ref or "not found">
+  Branches      : main=<branch>, dev=<branch>
+  Stack         : <next.js 14 / vite / etc>
+  Monorepo      : yes/no (<tool>)
+  Apps found    : <list or "none">
+  Guides dir    : <.rdc/guides or docs/guides or "none">
+  Existing cfg  : yes/no
+  Hook scope    : <detected folder name or "unknown">
+```
+
+---
+
+## Step 2 — Check for gaps
+
+List anything that was NOT found and ask the user to fill in:
+
+```
+Missing (please provide):
+  [ ] Project description
+  [ ] Deploy platform / dashboard URL
+  [ ] Forbidden commands beyond defaults?
+  [ ] Any satellite repos (other GitHub repos in this project)?
+```
+
+Keep questions to a minimum — only ask what can't be auto-detected.
+
+---
+
+## Step 3 — Generate .rdc/config.json
+
+Using all detected + user-supplied values, write `.rdc/config.json`:
+
+```json
+{
+  "name": "<slug>",
+  "version": "1.0.0",
+  "description": "<description>",
+  "rdc_skills_version": ">=0.2.0",
+  "hook_scope": "<project-folder-name>",
+  "git": {
+    "org": "<githubOrg>",
+    "repo": "<githubRepo>",
+    "main_branch": "<main>",
+    "dev_branch": "<develop>",
+    "auto_commit_branch": "<develop>"
+  },
+  "supabase": {
+    "ref": "<ref>",
+    "url": "https://<ref>.supabase.co",
+    "mcp_server": "mcp__claude_ai_Supabase__execute_sql"
+  },
+  "credentials": {
+    "provider": "clauth",
+    "daemon_url": "http://127.0.0.1:52437",
+    "env_paths": [".env.local"]
+  },
+  "repos": [
+    { "path": ".", "role": "primary", "description": "<project name>" }
+  ],
+  "paths": {
+    "guides":   ".rdc/guides",
+    "plans":    ".rdc/plans",
+    "reports":  ".rdc/reports",
+    "research": ".rdc/research",
+    "state":    ".rdc/state",
+    "systems":  "docs/systems"
+  },
+  "work_items": { "enabled": true },
+  "constraints": {
+    "forbidden_commands": ["pnpm build"],
+    "typecheck_command": "npx tsc --noEmit",
+    "test_command": "npx vitest run",
+    "never_push_to": ["main"]
+  }
+}
+```
+
+If `.rdc/config.json` already exists, show a diff of proposed changes and ask before overwriting.
+
+---
+
+## Step 4 — Generate overlay guides
+
+Create `.rdc/guides/agent-bootstrap.md` if it doesn't exist:
+
+```markdown
+# Agent Bootstrap — <Project Name>
+> Project overlay — extends rdc-skills base guide.
+
+## Credentials
+curl -s http://127.0.0.1:52437/get/<service>
+
+## Git Rules
+- Branch: `<devBranch>` for all work. `<mainBranch>` = production.
+- GitHub org: <githubOrg>
+- Auto-commit to `<devBranch>` after every logical block.
+
+## Supabase
+Project ref: `<ref>`
+Use `mcp__claude_ai_Supabase__execute_sql` — no `project_id` needed.
+
+## Work Items
+SELECT get_open_epics();
+SELECT insert_work_item(p_title := '...', p_priority := 'high');
+SELECT update_work_item_status('<id>'::uuid, 'done');
+Create work items BEFORE starting work.
+
+## Completion Report
+After finishing work, output:
+## Work Summary
+- Files changed: <list>
+- Tests: pass/fail
+- Work items updated: <list>
+- Committed: <sha>
+```
+
+If `docs/guides/` or `.rdc/guides/` already has an `agent-bootstrap.md`, read it and preserve any custom sections — only add missing sections, don't overwrite existing ones.
+
+---
+
+## Step 5 — Offer to move docs/ dirs
+
+If `docs/guides/`, `docs/plans/`, `docs/reports/`, or `docs/research/` exist, ask:
+
+```
+Found existing docs/ directories. Move to .rdc/ layout?
+  docs/guides   → .rdc/guides   [Y/n]
+  docs/plans    → .rdc/plans    [Y/n]
+  docs/reports  → .rdc/reports  [Y/n]
+  docs/research → .rdc/research [Y/n]
+```
+
+Move only the directories the user confirms.
+
+---
+
+## Step 6 — Scaffold CLAUDE.ai.md and relay dirs
+
+Create `.rdc/relay/from-claude-ai/`, `.rdc/relay/from-claude-code/`, and `.rdc/relay/RELAY.md`.
+
+Create `CLAUDE.ai.md` in the project root if it doesn't exist:
+
+```markdown
+# CLAUDE.ai — Startup Guide for claude.ai Sessions
+> Read this at the start of every claude.ai session on this repo.
+
+## What You Are
+
+You are a claude.ai session — the **creative studio** in this stack. You produce artifacts,
+React prototypes, plans, copy, and designs. Claude Code CLI is the **build engine** — it runs
+agents, manages git, enforces hooks, and ships to production.
+
+**This is co-working, not handoff.** You produce real artifacts; Claude Code adapts and ships them.
+
+## Startup Sequence — every session
+
+```
+1. fs_read CLAUDE.ai.md                     ← you are here
+2. fs_read CLAUDE.md                        ← CLI routing, hard rules
+3. SELECT get_open_epics()                  ← what's in flight
+4. fs_list .rdc/relay/from-claude-code/     ← messages from Claude Code
+5. fs_read apps/<app>/CLAUDE.md             ← only if working in a specific app
+```
+
+## Capabilities
+
+| Capability | Tool |
+|-----------|------|
+| Read/write repo files | `fs_read`, `fs_write`, `fs_glob`, `fs_grep` |
+| Query Supabase | Supabase MCP `execute_sql` |
+| GitHub operations | Github Proxy MCP |
+| Credentials | clauth MCP `clauth_get` |
+| Trigger Claude Code | `monkey_dispatch` MCP |
+
+## Two-Claude Relay
+
+Two channels to communicate with Claude Code:
+
+**File relay (async):** Write to `.rdc/relay/from-claude-ai/<timestamp>-<topic>.md`:
+```
+---
+from: claude-ai
+to: claude-code
+type: task | artifact
+topic: <slug>
+epic_id: <uuid>
+status: pending
+---
+<agent prompt or artifact content>
+```
+
+**Live dispatch (immediate):** Fire Claude Code directly:
+```
+mcp__claude_ai_clauth__monkey_dispatch({
+  prompt: "Read .rdc/guides/agent-bootstrap.md. Your task: ...",
+  cwd: "<project root>"
+})
+```
+
+Check `.rdc/relay/from-claude-code/` at startup for results and questions from Claude Code.
+Full protocol: `.rdc/relay/RELAY.md`
+
+## Hard Rules
+
+- **NEVER run `pnpm build`** — crashes machine
+- **NEVER commit to `main`** — always `<devBranch>`
+- **NEVER start work without a work item**
+- **NEVER ask for credentials** — use clauth MCP directly
+```
+
+If `CLAUDE.ai.md` already exists, read it first and add only the relay section if missing — do not overwrite existing content.
+
+---
+
+## Step 7 — Commit
+
+```bash
+git add .rdc/ CLAUDE.ai.md
+git commit -m "feat(rdc): add .rdc/ config, guides, relay scaffold and CLAUDE.ai.md
+
+Generated by /rdc:setup scan.
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
+if [ "$RDC_TEST" != "1" ]; then
+  git push origin <devBranch>
+else
+  echo "[RDC_TEST] skipping git push origin <devBranch>"
+fi
+```
+
+---
+
+## Output
+
+Report:
+- What was detected automatically
+- What was generated
+- What still needs manual attention (e.g. `deploy_dashboard_url`, `satellite_repos`)
+- Next step: `/rdc:status` to verify

package/guides/agents/verify.md

@@ -0,0 +1,132 @@
+> **⚠️ 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.
+
+
+# rdc:verify — Verification Before Completion
+
+> Adapted from obra/superpowers `verification-before-completion`.
+> Stack-specific: uses `npx vitest run` + `npx tsc --noEmit`. NEVER `pnpm build` (crashes machine — 800MB/process).
+
+## The Iron Law
+
+**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**
+
+You may not say "done", "complete", "working", "fixed", "passing", or imply success until you have:
+
+1. **Identified** the exact commands that prove the claim
+2. **Run** those commands fresh in the current state (not memory, not "earlier", not "should")
+3. **Read** the full output
+4. **Verified** the output matches the claim
+5. Only THEN made the claim, quoting the evidence
+
+If you cannot run the commands, say so explicitly. Do not substitute reasoning for evidence.
+
+## Red Flags — Stop and Verify
+
+If you're about to write any of these, STOP:
+
+- "should work" / "should pass" / "should be fine"
+- "probably" / "seems to" / "looks good"
+- "I think the tests pass"
+- "the types check out" (without running tsc)
+- "everything compiles" (without fresh output)
+- Expressing satisfaction or wrapping up before the gate ran
+
+## The Gate — Commands for This Stack
+
+Run these in order. All must pass. Capture output.
+
+### 1. Per-package vitest (every package touched)
+
+```bash
+cd <repo-root>
+for pkg in <changed-packages>; do
+  npx vitest run --dir packages/$pkg 2>&1 | tee /tmp/verify-$pkg.log
+done
+```
+
+Or for a single package:
+```bash
+npx vitest run --dir packages/<pkg>
+npx vitest run --dir apps/<app>
+```
+
+**NEVER** run `pnpm build` or `pnpm test` at the repo root — spawns 5-7 node processes at 800MB each and crashes the machine.
+
+### 2. Typecheck per package
+
+```bash
+npx tsc --noEmit --project packages/<pkg>/tsconfig.json
+npx tsc --noEmit --project apps/<app>/tsconfig.json
+```
+
+One package at a time. Read the full output — zero errors required.
+
+### 3. Lint (if configured for the package)
+
+```bash
+npx eslint <paths> --max-warnings=0
+```
+
+### 4. Smoke check exports (if package adds public API)
+
+```bash
+node -e "const m = require('<pkg>'); console.log(Object.keys(m));"
+```
+
+Or for ESM:
+```bash
+node --input-type=module -e "import * as m from '<pkg>'; console.log(Object.keys(m));"
+```
+
+## Rationalization Prevention
+
+| You're tempted to think... | Reality |
+|---|---|
+| "Tests passed earlier, should still pass" | Run them now. Code changed. |
+| "TypeScript is strict, if it built it works" | You didn't build. Run tsc. |
+| "Small change, no need to retest" | Small changes are where regressions hide. |
+| "I'll note it as pending verification" | No. Verify now or mark incomplete. |
+| "The test file looks right" | Reading ≠ running. Run it. |
+
+## Output Format — Required
+
+When reporting completion, use this structure:
+
+```
+## Verification Evidence
+
+### vitest
+$ npx vitest run --dir packages/hail
+ Test Files  12 passed (12)
+      Tests  147 passed (147)
+
+### tsc
+$ npx tsc --noEmit --project packages/hail/tsconfig.json
+(no output — clean)
+
+### Status
+PASS — safe to mark tasks done.
+```
+
+If any step fails: do NOT claim completion. Report the failure, fix it, re-run the entire gate.
+
+## When to Invoke
+
+- **End of `/rdc:build`** — mandatory final phase before marking epic done
+- **During `/rdc:review`** — verification gate after fixes applied
+- **Before any "done" declaration** — if an agent or supervisor is about to say work is complete
+- **After merging waves** — when parallel agents finish and their work is combined
+
+## Agent Delegation
+
+When dispatching a verification agent, give them:
+- Exact list of packages/apps to verify
+- Explicit ban on `pnpm build` / `pnpm test` / `pnpm -r`
+- Required output format (above)
+- Instruction: "If any command fails, STOP and report. Do not fix. Do not continue."
+
+## The Bottom Line
+
+Evidence before claims. Fresh evidence, not remembered evidence. Full output, not selective reading. If you skip the gate, you are lying about the work being done.