@lifeaitools/rdc-skills 0.35.8 → 0.35.9

package/commands/deploy.md

@@ -1,211 +0,0 @@
----
-name: deploy
-description: rdc:deploy (slug, [action]) - [--fix, --hotfix] — ship to PM2 dev; promote to Coolify 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.
-
-
-# rdc:deploy — Coolify Operations
-
-**READ FIRST:** `guides/output-contract.md`. Checklist-only output. No narration.
-No raw MCP dumps. No UUIDs unless asked.
-
-> **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.
->
-> *Under `$RDC_TEST=1`:* Modes 1 (deploy) and 2 (new) are **entirely skipped** — echo `[RDC_TEST] skipping Coolify deploy/create` and mark every `[ ]` line in those checklists as `[~]`. Modes 3 (diagnose) and 4 (audit without `--fix`) are **read-only and run normally**. Mode 4 with `--fix` skips all remediation — echo `[RDC_TEST] skipping audit --fix remediation` and report findings only. Registry SELECTs, Coolify status reads, HTTP gate probes, TLS checks, and DNS lookups are NOT destructive and run normally. Anything that writes (create app, set watch_paths, deploy trigger, env var write, DNS write, CF cache purge, registry UPDATE/INSERT) is gated.
-
-## Arguments
-
-- `rdc:deploy <slug>` — deploy existing app (latest commit on its watched branch)
-- `rdc:deploy <slug> <build-id>` — deploy specific commit/tag
-- `rdc:deploy new <slug>` — create a new Coolify app from registry
-- `rdc:deploy diagnose <slug>` — debug why an app is broken
-- `rdc:deploy audit` — fleet-wide scan for missed failures
-- `rdc:deploy audit --fix` — fleet scan + auto-remediate safe issues
-- `rdc:deploy maintenance <service>` — create, update, or verify a template-declared private service; no public domain or host port
-- `rdc:deploy dev <slug>` — deploy to PM2 dev (Vultr), not Coolify — see Mode 0
-- `rdc:deploy` (no args) — print mode menu, ask which
-
-## Modes
-
-### Mode 0 — dev <slug> (PM2 development, not Coolify)
-
-PM2 dev deploys route through the real, tested `rdc-harness` CLI instead of
-raw PM2/curl — it already implements this path (`shipRoute: pm2-development`,
-via `@lifeaitools/regen-deploy-mgr` on loopback :52438, never raw PM2):
-
-```
-rdc:deploy dev: <slug>
-[ ] node C:/Dev/rdc-harness/bin/rdc-harness.mjs deploy <slug> --monorepo-root <caller's own worktree>
-[ ] JSON receipt parsed — shipRoute confirmed "pm2-development" (else: not this product's route, see receipt.reason)
-[ ] Receipt reports ok / the specific refusal, reported verbatim — not narrated
-✅ rdc:deploy dev: <slug> — <receipt outcome in one line>
-```
-
-A receipt with `applicable: false, reason: 'not_pm2_shipped'` means this slug
-ships a different way (registry, static, or Coolify) — report that plainly,
-do not retry as Coolify without confirming that's actually the right route.
-
-### Mode 1 — deploy <slug> [build-id] (Coolify — staging/production)
-
-```
-rdc:deploy: <slug> → <domain>
-[ ] Registry lookup (slug, uuid, branch, type, env_vars_needed)
-[ ] Git state verified (branch matches Coolify, commit pushed)
-[ ] Build-id resolved (default: HEAD of watched branch)
-[ ] Env vars present in Coolify (compare to registry)
-[ ] Type-specific preflight (see docs/runbooks/coolify-deploy-checklist.md)
-[ ] Deploy triggered
-[ ] Deployment reached "finished" state
-[ ] Gate: HTTP 200
-[ ] Gate: TLS valid (no SSL cipher mismatch)
-[ ] Gate: cache headers correct on HTML
-[ ] Gate: container running on declared port
-[ ] Cloudflare cache purged (if proxied)
-[ ] deployment_registry updated (last_deploy_at, status)
-✅ rdc:deploy: <slug> deployed in Nm Ns
-```
-
-### Mode 2 — new <slug>
-
-```
-rdc:deploy new: <slug>
-[ ] Registry entry loaded (or interactive create)
-[ ] DNS path chosen (A: staging wildcard  B: apex  C: other zone)
-[ ] DNS record verified or wildcard confirmed
-[ ] Cloudflare proxy setting correct for DNS path
-[ ] server_uuid, project_uuid, environment_uuid, github_app_uuid resolved
-[ ] Build type chosen (Next.js / Vite / static / standalone)
-[ ] Type-specific fields filled (ports, build cmd, install cmd, start cmd)
-[ ] Application created via /applications/private-github-app
-[ ] watch_paths set and verified
-[ ] Env vars set in Coolify
-[ ] First deploy triggered
-[ ] Gate passed (5 checks)
-[ ] deployment_registry row inserted
-✅ rdc:deploy new: <slug> live at <domain>
-```
-
-### Mode 3 — diagnose <slug>
-
-```
-rdc:deploy diagnose: <slug>
-[ ] App located (uuid, domain, last deploy)
-[ ] Container state (running / restarting / stopped)
-[ ] Last 100 log lines scanned for known error patterns
-[ ] Port mismatch check (declared vs actual)
-[ ] Env var drift check (registry vs Coolify)
-[ ] watch_paths sanity check
-[ ] HTTP / TLS reachability
-[ ] Cloudflare proxy state check
-[ ] Disk space on server
-[ ] Branch mismatch check (Coolify git_branch vs expected)
-⚠️ rdc:deploy diagnose: <root cause in one sentence> — fix: <one command>
-```
-
-### Mode 4 — audit
-
-```
-rdc:deploy audit: fleet scan
-[ ] Inventory join: Coolify apps ⋈ deployment_registry
-[ ] Orphans (in one but not the other)
-[ ] Monorepo apps missing watch_paths
-[ ] Stale deploys (>14 days since last success)
-[ ] Registry rows with status='broken'
-[ ] Failed deployments in last 7 days
-[ ] HTTP gate sweep (non-200 per domain)
-[ ] TLS cert expiry <30 days
-[ ] Port mismatches (ports_exposes vs actual container port)
-[ ] Env var drift (registry.env_vars_needed vs Coolify env)
-[ ] Branch mismatches (Coolify git_branch ≠ expected)
-[ ] Disk space on 64.237.54.189
-[ ] DNS/proxy misconfigs on configured staging wildcard
-[ ] Duplicate apps (same repo, multiple UUIDs)
-
-Findings:
-| Severity | App | Issue | Fix |
-|----------|-----|-------|-----|
-| HIGH     | ... | ...   | ... |
-⚠️ rdc:deploy audit: N HIGH · M MED · K LOW — run `rdc:deploy audit --fix` to auto-remediate safe issues
-```
-
-Severity rules:
-- **HIGH** — user-facing down (HTTP non-200, TLS invalid, container not running)
-- **MED** — degraded or drifting (watch_paths missing, env var drift, stale deploy, branch mismatch)
-- **LOW** — cleanup (orphans, duplicates, registry status stale)
-
-`--fix` auto-remediates only: missing watch_paths, registry row updates, CF cache purges. Never touches env vars, DNS, or container config without explicit confirmation.
-
-### Mode 7 — maintenance <service> (private infrastructure)
-
-Use maintenance only for a service declared in the `private-service` template.
-It creates, updates, or verifies a Coolify-network service with no public
-domain, no DNS route, and no host-port publication. Secret checks use key names
-only; values are never retrieved or emitted. Retiring a service is outside this
-mode and requires separate explicit approval.
-
-```
-rdc:deploy maintenance: <service>
-[ ] Template and source/branch/Dockerfile/internal-port/health-path resolved
-[ ] Private-only contract: domains empty, host port absent, network alias declared
-[ ] Required secret keys confirmed by name only
-[ ] Explicit deploy completed
-[ ] Health gate passes inside the container
-[ ] Existing Coolify-network workload reaches the alias and health path
-[ ] No public domain, TLS route, DNS record, or host endpoint is present
-✅ rdc:deploy maintenance: <service> healthy on the private network
-```
-
-For `clauth`, require `CLAUTH_MACHINE_ID` and `CLAUTH_MASTER_PASSWORD`, port
-`52437`, and `/ping`. The container may bind `0.0.0.0` internally only;
-consumers must use its Coolify network alias rather than `localhost`.
-
-## Coolify Access — clauth + REST API
-
-All Coolify operations use the clauth daemon and the Coolify REST API directly.
-There is no Coolify MCP server — do not reference `@masonator/coolify-mcp`.
-
-```bash
-_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
-curl -s -H "Authorization: Bearer $_COOLIFY" "$DEPLOY_API_BASE/api/v1/applications"
-```
-
-**Triggering the actual deploy is different — use the wrapper, not raw curl.**
-`hooks/lib/guard-rules.mjs`'s `coolify-direct` rule blocks a raw curl (or any command whose
-TEXT contains the literal URL) to `/api/v1/deploy` — the deploy-trigger endpoint — on
-purpose, so a production deploy is never one arbitrary curl an agent can fire silently. This
-is NOT a bug to route around with SSH or a differently-worded command
-(`.rdc/lessons/2026-08-07-deploy-coolify-direct-blocks-own-documented-step.md`). The
-sanctioned way to actually trigger a deploy for Mode 1's "Deploy triggered" step is:
-
-```bash
-python3 scripts/coolify-deployments.py deploy <application-uuid>
-```
-
-Run from the regen-root repo root. Poll `status <deployment-uuid>` (the same script) or
-`GET /api/v1/deployments/<deployment-uuid>` (read-only, not blocked) until `status` is
-`finished`/`failed`/`cancelled` before moving to the gate checks.
-
-If clauth daemon is not responding:
-```
-BLOCKED: clauth daemon not responding. Run scripts\restart-clauth.bat, unlock at http://127.0.0.1:52437
-```
-
-## References
-
-- Type-specific checklists + DNS tree + gate commands: `docs/runbooks/coolify-deploy-checklist.md`
-- Rules / registry RPCs / hard limits: `.claude/rules/coolify-deployment.md`
-- Infrastructure constants:
-  ```
-  Server UUID:     ih386anenvvvn6fy1umtyow0
-  Server IP:       64.237.54.189
-  Dashboard:       <deployment-dashboard-url>
-  GitHub App UUID: xdmcy60putp5h9j7k4kwg9c3
-  ```
-
-## Supersedes
-
-`coolify-deploy` standalone skill (kept for back-compat; new work uses `rdc:deploy`).

package/commands/design.md

@@ -1,30 +0,0 @@
----
-name: design
-description: rdc:design (topic) — design Studio, palette and token-aware UI work
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-
-# rdc:design — RDC Design Skill
-
-Use `skills/design/SKILL.md` as the source of truth.
-
-## When to Use
-
-- Studio, Palette Library, brand-token, theme, component, or live-editor work
-- Any design task that must understand RDC's real token tables and Studio routes
-- UI critique, audit, polish, colorize, type, layout, or craft work in `{PROJECT_ROOT}`
-- Agent-side color-system exploration using Rampa CLI
-
-## Arguments
-
-- `rdc:design studio <target>`
-- `rdc:design tokens <brand-or-route>`
-- `rdc:design palette <brief>`
-- `rdc:design theme <brief>`
-- `rdc:design colorize <target>`
-- `rdc:design audit <target>`
-- `rdc:design critique <target>`
-- `rdc:design polish <target>`
-- `rdc:design craft <feature>`

package/commands/edit.md

@@ -1,27 +0,0 @@
----
-name: edit
-description: rdc:edit (target) — open the local website editor for a target
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-
-# rdc:edit — Local Website Editor
-
-Use `skills/edit/SKILL.md` as the source of truth.
-
-## When to Use
-
-- The user wants to open a site or route in the local editor app
-- The user says "open this in the editor" or "edit this site"
-- The target belongs in `@regen/editor-host`, not Studio
-
-## Arguments
-
-- `rdc:edit <site|brand|route|file>`
-
-## Notes
-
-- `prtrust.fund` and `dev.prtrust.fund` resolve to the `prt` brand/app pair.
-- `test`, `studio_test`, and `studio-test` resolve to the bundled local test target.
-- Under `RDC_TEST=1`, report the resolved editor URL instead of forcing a foreground browser action.

package/commands/fixit.md

@@ -1,172 +0,0 @@
----
-name: fixit
-description: rdc:fixit (description) — make a scoped fix under 5 files and ship it to dev
----
-
-> **⚠️ 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:fixit — Sanctioned Quick Fix
-
-## When to Use
-- Typo or single-line text correction
-- Config value change (env vars, constants, feature flags)
-- Emergency hotfix that cannot wait for a full build cycle
-- Dependency version bump
-- CSS/styling tweak on a single component
-- Broken import or export fix
-- Single-file logic correction
-
-## When NOT to Use — escalate to rdc:build instead
-- New feature of any size
-- Refactor touching >5 files
-- Anything requiring architecture decisions
-- Work that will take longer than 30 minutes
-- Schema changes or migrations
-
-## Arguments
-- `rdc:fixit <description>` — fix the described issue
-
-## Procedure
-
-### 1. Scope check (mandatory — do this before touching any file)
-
-Will this fix touch more than **5 files** or take more than **30 minutes**?
-
-- **YES** → Stop. Use `/rdc:build` instead. Explain to the user why.
-- **NO** → Continue.
-
-### 2. Create a minimal work item (before touching any code)
-
-```sql
-SELECT insert_work_item(
-  p_title     := 'fixit: <description>',
-  p_item_type := 'bug',
-  p_priority  := 'urgent',
-  p_status    := 'in_progress',
-  p_source    := 'fixit'
-);
-```
-
-Note the returned `id`.
-
-### 3. Write the fixit session marker
-
-Write to `{USER_HOME}/.claude/fixit.marker`:
-```
-<work_item_id>
-<ISO timestamp>
-<description>
-```
-
-This signals the Stop hook that fixit is handling its own documentation.
-
-### 4. Make the fix
-
-If the fix is a create/open/build/deploy step against a real fleet
-repository (materialize a product shape, open a signed edit session, run a
-target's declared build gates, or deploy to dev-PM2/npm-registry), use the
-real, tested `rdc-harness` CLI instead of hand-rolled bash/curl:
-
-```bash
-node C:/Dev/rdc-harness/bin/rdc-harness.mjs <create|open|edit|build|deploy> <slug> --monorepo-root <your own worktree, never the shared checkout>
-```
-
-One JSON receipt on stdout, exit 0/1 — use it as the evidence for whichever
-checklist/commit step it satisfies. It has no Coolify awareness (deploy here
-means PM2 dev or npm publish only — Coolify stays this skill's own §5.5 path)
-and no live co-editing surface outside `site-html`/`site-ts` targets (other
-classes get boundary-checked file save only). `open`/`edit` need
-`RDC_HARNESS_ISSUER_SECRET` set explicitly — no default exists or should.
-For anything not create/open/build/deploy shaped, edit files directly as below.
-
-Do the minimal work, conforming to `docs/CODING-STANDARDS.md` where present
-(regen-root; skip if absent). Scope creep rule: if you discover the fix requires more than originally scoped, **stop immediately**:
-1. Close the work item: `update_work_item_status('<id>', 'blocked', '["Escalated — scope exceeded fixit threshold"]')`
-2. Delete the marker file
-3. Tell the user to use `/rdc:build` instead
-
-### 5. Commit
-
-```bash
-git add <specific files only — never git add -A for a fixit>
-git commit -m "fix(<scope>): <description>"
-if [ "$RDC_TEST" != "1" ]; then
-  git push origin {development-branch}
-else
-  echo "[RDC_TEST] skipping git push origin {development-branch}"
-fi
-```
-
-### 5.5 Deliver to done (MANDATORY — a fixit is not done until the change is LIVE)
-
-⛔ **"Committed and pushed" is NOT done.** Editing code and walking away is the exact
-failure this step exists to prevent. Carry the change to where it is consumed and verify it:
-
-| Target shape | "Done" = delivered means | How + structural proof |
-|---|---|---|
-| Published package (npm / PyPI) | new version live on the registry | `npm publish --access public` (or repo release path); verify `npm view <pkg> version` == new version |
-| Deployed app (`apps/*`, sites) | change live on the running host | `/rdc:deploy <slug>` (dev) / `promote` (prod); verify HTTP 200 + content probe |
-| Shared lib consumed in-repo | landed on the integration branch | `node scripts/land.mjs`; verify branch contains the SHA |
-| Standalone repo | its own release ritual completed | repo release script/tag; verify the artifact/tag exists |
-| Pure doc / internal-only change, NO consumer | committed + landed | no deploy; the ONLY case where commit == done |
-
-- **A version bump obligates a release.** A bumped-but-unshipped version is an unfinished fixit.
-- **Verify structurally** (registry version, HTTP status, tag presence), never by assumption.
-- **If delivery can't complete in-session** (missing OTP/secret, human approval, denied
-  command, manual prod promotion): set the work item `blocked` with the exact remaining
-  command + reason and tell the user the one step to run — do NOT mark `done`.
-
-Under `RDC_TEST=1`: echo `[RDC_TEST] skipping delivery (publish/deploy)` and proceed.
-
-**ATF Test-Ladder / rdc-harness (WIP — best-effort, not a hard gate yet):** if the touched
-package/repo already ships an ATF `STP-001.md` or an `rdc-harness`-style
-`tools/mutate-check.mjs`/`tools/proof-ledger.mjs` pair, run it and quote the result. Neither
-is fleet-wide yet — its absence is not itself a fixit failure.
-
-### 6. Report, review, close, and clean up
-
-**Precondition: Step 5.5 delivery is verified.** If delivery is blocked, set `blocked` (not
-`done`) with the remaining step — never mark an undelivered change `done`.
-
-```sql
-SELECT submit_implementation_report('<id>'::uuid,
-  '{"tldr":"<one sentence>","assumptions":[],"deviations":[],"uncertainty":[],"detail":"<what was fixed>","flags":[],"transactional":false,"memory_records":[],"codeflow_post":{"agent_session_id":"<agent-session-id>","summary":"<what changed and why>","files_changed":["<path>"],"verification":["<command/evidence>"],"commit":"<hash optional>"}}'::jsonb
-);
-
-SELECT update_work_item_status('<id>'::uuid, 'review',
-  '["Fixed via rdc:fixit; ready for validation"]'::jsonb,
-  '<agent-session-id>',
-  'agent'
-);
-
-SELECT update_work_item_status('<id>'::uuid, 'done',
-  '["Validator verified rdc:fixit report, CodeFlow post, and checklist evidence"]'::jsonb,
-  '<validator-session-id>',
-  'validator'
-);
-```
-
-```bash
-rm {USER_HOME}/.claude/fixit.marker
-```
-
-### 7. Confirm to user
-
-Report: what was fixed, file(s) changed, commit hash. One sentence.
-
-## Rules
-- Work item created BEFORE any code change — never after
-- `git add` specific files only — never `-A` or `.` for a fixit
-- Branch: development branch always
-- Never run `pnpm build` — not needed for a fixit
-- If scope expands mid-fix: stop, escalate to rdc:build, don't finish under fixit
-- Marker file must be cleaned up whether fix succeeds or escalates
-- **Done = delivered, not committed.** Live where consumed (published/deployed/landed) +
-  verified. A version bump obligates a publish. Can't deliver in-session → `blocked`, never `done`.

package/commands/handoff.md

@@ -1,188 +0,0 @@
----
-name: handoff
-description: rdc:handoff () - [--from-prototype] — turn a plan or prototype into work items and artifacts
----
-
-> **⚠️ 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:handoff — Planning → CLI Bridge
-
-## When to Use
-
-- A prototype has been built and needs production implementation
-- A design decision has been made and needs to be executed
-- Project lead says "hand this off", "give this to the CLI", "write it up"
-- A plan exists in the conversation but hasn't been saved to disk or database yet
-
-## What This Skill Produces
-
-1. **Plan doc** → `.rdc/plans/<topic-slug>.md` (fallback: `.rdc/plans/<topic-slug>.md`)
-2. **Database epic + child tasks** (with agent types and guide file refs)
-3. **Prototype registry entry** (if a prototype was built)
-4. **Design context entries** (for decisions made in the session)
-
-## Procedure
-
-### Step 1 — Extract the Plan
-
-Identify from the conversation:
-- What is the goal?
-- What prototypes or designs were built? Where are they?
-- What decisions were made? What was rejected and why?
-- What is the sequencing (what depends on what)?
-- Which agent types are needed?
-
-### Step 2 — Write the Plan Doc
-
-```
-.rdc/plans/<topic-slug>.md
-```
-(fallback: `.rdc/plans/<topic-slug>.md` if `.rdc/` does not exist)
-
-Template:
-```markdown
-# Plan: <Topic>
-> Route: <app route or package>
-> Status: Ready for CLI build
-> Created: <date>
-> Source: planning session
-
----
-
-## What Already Exists (Do NOT Re-implement)
-
-[List any existing components, database tables, or files
- that agents must use rather than recreate]
-
-## What Was Built in Planning (Prototype)
-
-[Describe the prototype — file location, key design decisions,
- what to preserve vs what to adapt]
-
-## Work Packages
-
-### Package 1 — <Name>
-- Agent type: frontend | backend | data | design | infra | content | cs2 | viz
-- Guide: .rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md)
-- Files to create/modify: [list]
-- Deliverables: [specific outputs]
-- Depends on: [other packages if sequential]
-
-### Package 2 — <Name>
-[...]
-
-## Sequencing
-
-Wave 1 (parallel): Package 1, Package 2
-Wave 2 (after Wave 1): Package 3
-
-## Definition of Done
-
-- [ ] [specific acceptance criterion]
-- [ ] [build verification: zero new TS errors]
-- [ ] [functional test]
-```
-
-### Step 3 — Create Database Epic + Tasks
-
-```sql
--- Check for existing epics first
-SELECT get_open_epics();
-
--- Create epic
-SELECT insert_work_item(
-  p_title       := 'EPIC: <Topic>',
-  p_description := 'See .rdc/plans/<topic-slug>.md for full spec.',
-  p_item_type   := 'epic',
-  p_priority    := 'high',
-  p_labels      := ARRAY['<system-label>'],
-  p_source      := 'planning'
-);
-
--- Immediately populate governance refs — the handoff's plan doc IS the plan_ref/spec_ref.
--- Set architecture_ref ONLY when this handoff crosses an architectural boundary (storage
--- authority, process topology, auth boundary, deployment model, persistence, service
--- ownership, public contract); leave it NULL for ordinary feature work, or every task
--- below gets held for a review it doesn't need.
-SELECT set_epic_governance_refs(
-  p_epic_id := '<epic-uuid>'::uuid,
-  p_plan_ref := '.rdc/plans/<topic-slug>.md',
-  p_spec_ref := '.rdc/plans/<topic-slug>.md',
-  p_architecture_ref := '<docs/systems/<system>/ARCHITECTURE.md or NULL>',
-  p_scoping_statement := '<one paragraph: what is explicitly in scope and what is explicitly out of scope>'
-);
-
--- Create tasks (one per work package)
-SELECT insert_work_item(
-  p_title       := '<Package Name>',
-  p_description := 'What: <deliverable>
-Where: <files>
-Agent type: <type>
-Guide: .rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md)
-Design doc: .rdc/plans/<topic-slug>.md (fallback: .rdc/plans/<topic-slug>.md)
-Depends on: <other task if applicable>
-Est: <hours>',
-  p_parent_id   := '<epic-uuid>'::uuid,
-  p_item_type   := 'task',
-  p_priority    := 'high',
-  p_labels      := ARRAY['<label>'],
-  p_estimated_hours := 2,
-  p_source      := 'planning'
-  -- If the epic has architecture_ref set, also add a required
-  -- architecture-fidelity-<slug> checklist row via p_checklist here — the exit gate
-  -- hard-rejects `done` on any task under an architecture_ref epic that lacks one.
-);
-```
-
-### Step 4 — Register Prototype (if one was built)
-
-```sql
-INSERT INTO prototype_registry (name, component, source_path, notes, created_by)
-VALUES (
-  '<Component Name> v1',
-  '<ComponentName>',
-  'docs/source/<filename>.jsx',
-  '<Key design decisions, data shapes, what to preserve>',
-  'planning'
-)
-ON CONFLICT DO NOTHING;
-```
-
-### Step 5 — Record Design Decisions
-
-```sql
-INSERT INTO design_context (topic, context_type, summary, source, created_by)
-VALUES
-  ('<Topic>', 'decision', '<What was decided and why>', 'planning session', 'planning'),
-  ('<Topic>', 'rejected', '<What was considered but not chosen, and why>', 'planning session', 'planning');
-```
-
-## System Labels Reference
-
-| Label | When |
-|-------|------|
-| `project-a` | Your-app-specific label |
-| `marketing` | Marketing / outreach work |
-| `ui` | Component library work |
-| `data` | Schema, migrations |
-| `infrastructure` | CI/CD, deployment |
-| `cs2` | Core paradigm packages |
-| `website` | Public-facing sites |
-| `media` | Media/asset work |
-
-## Output
-
-When complete, tell the project lead:
-```
-Handoff complete:
-- Plan: .rdc/plans/<topic-slug>.md
-- Epic: <epic-id> ("<title>")
-- Tasks: <N> tasks created, wave structure: [Wave 1: X, Y | Wave 2: Z]
-- Prototype: registered at docs/source/<file> (if applicable)
-- CLI agents will pick this up on next run.
-```