@lifeaitools/rdc-skills 0.9.33 → 0.9.34

package/guides/agent-bootstrap.md

@@ -1,85 +1,89 @@
-# Agent Bootstrap — Read This First
-> Every dispatched agent reads this before their role-specific guide.
-> Base guide for rdc-skills — provides credential, git, and reporting patterns across projects.
-
----
-
-## Who You Are
-
-You are a subagent dispatched by the rdc:build supervisor. You have a specific
-scope (files, package, feature) that will be in your prompt. Stay in that scope.
-NEVER modify files outside it.
-
----
-
-## Credentials — Daemon Access Pattern
-
-You do NOT have access to cloud MCP connectors. Instead, all credentials
-come from a daemon running locally (typically on localhost:52437).
-
-**Ping first to confirm availability:**
-```bash
-curl -s http://127.0.0.1:52437/ping
-```
-If it doesn't respond — report BLOCKED, do not proceed.
-
-**Get a credential:**
-```bash
-curl -s http://127.0.0.1:52437/get/<service>
-```
-
-**Pattern for extracting key/value without printing:**
-```bash
-# Correct pattern — never echo the key
-KEY=$(curl -s http://127.0.0.1:52437/get/<service> | python3 -c "import sys,json; print(json.load(sys.stdin)['key'])")
-curl -s -H "Authorization: Bearer $KEY" https://api.example.com/...
-```
-
-**Never print credentials to stdout.** Capture to a variable, use inline, discard.
-
----
-
-## Project Directory Convention
-
-This plugin uses the `.rdc/` directory convention. Check for it first:
-
-```bash
-# Check if .rdc/ exists at project root
-ls {PROJECT_ROOT}/.rdc/config.json 2>/dev/null && echo "using .rdc/" || echo "using docs/ fallback"
-```
-
-**Path resolution rule:**
-- Guides: `{PROJECT_ROOT}/.rdc/guides/` → fallback: `{PROJECT_ROOT}/docs/guides/`
-- Plans: `{PROJECT_ROOT}/.rdc/plans/` → fallback: `{PROJECT_ROOT}/docs/plans/`
-- Reports: `{PROJECT_ROOT}/.rdc/reports/` → fallback: `{PROJECT_ROOT}/docs/reports/`
-- Research: `{PROJECT_ROOT}/.rdc/research/` → fallback: `{PROJECT_ROOT}/docs/research/`
-
-If `.rdc/config.json` exists, read it for project metadata (name, description, conventions).
-
----
-
-## Database Access — Check Project Overlay
-
-The project overlay guide will specify:
-- Database project reference / instance name
-- Whether to use MCP connectors or daemon
-- Available RPC functions
-- Work item management patterns
-
-Read the project-specific agent-bootstrap.md overlay for exact connection details.
-
----
-
-## Git Rules
-
-- Branch: Always use the project's primary development branch (typically `develop` or `main`)
-- Auto-commit after completing your scope — no confirmation needed
-- Commit message must use conventional format: `feat/fix/chore/refactor(<scope>): description`
-- Push to origin after committing
-- NEVER force-push
-
----
-
+# Agent Bootstrap — Read This First
+> Every dispatched agent reads this before their role-specific guide.
+> Base guide for rdc-skills — provides credential, git, and reporting patterns across projects.
+
+---
+
+## Who You Are
+
+You are a subagent dispatched by the rdc:build supervisor. You have a specific
+scope (files, package, feature) that will be in your prompt. Stay in that scope.
+NEVER modify files outside it.
+
+Read `guides/engineering-behavior.md` next when it is available. It defines the
+RDC implementation posture for assumptions, minimal changes, surgical scope,
+verification evidence, and escalation.
+
+---
+
+## Credentials — Daemon Access Pattern
+
+You do NOT have access to cloud MCP connectors. Instead, all credentials
+come from a daemon running locally (typically on localhost:52437).
+
+**Ping first to confirm availability:**
+```bash
+curl -s http://127.0.0.1:52437/ping
+```
+If it doesn't respond — report BLOCKED, do not proceed.
+
+**Get a credential:**
+```bash
+curl -s http://127.0.0.1:52437/get/<service>
+```
+
+**Pattern for extracting key/value without printing:**
+```bash
+# Correct pattern — never echo the key
+KEY=$(curl -s http://127.0.0.1:52437/get/<service> | python3 -c "import sys,json; print(json.load(sys.stdin)['key'])")
+curl -s -H "Authorization: Bearer $KEY" https://api.example.com/...
+```
+
+**Never print credentials to stdout.** Capture to a variable, use inline, discard.
+
+---
+
+## Project Directory Convention
+
+This plugin uses the `.rdc/` directory convention. Check for it first:
+
+```bash
+# Check if .rdc/ exists at project root
+ls {PROJECT_ROOT}/.rdc/config.json 2>/dev/null && echo "using .rdc/" || echo "using docs/ fallback"
+```
+
+**Path resolution rule:**
+- Guides: `{PROJECT_ROOT}/.rdc/guides/` → fallback: `{PROJECT_ROOT}/docs/guides/`
+- Plans: `{PROJECT_ROOT}/.rdc/plans/` → fallback: `{PROJECT_ROOT}/docs/plans/`
+- Reports: `{PROJECT_ROOT}/.rdc/reports/` → fallback: `{PROJECT_ROOT}/docs/reports/`
+- Research: `{PROJECT_ROOT}/.rdc/research/` → fallback: `{PROJECT_ROOT}/docs/research/`
+
+If `.rdc/config.json` exists, read it for project metadata (name, description, conventions).
+
+---
+
+## Database Access — Check Project Overlay
+
+The project overlay guide will specify:
+- Database project reference / instance name
+- Whether to use MCP connectors or daemon
+- Available RPC functions
+- Work item management patterns
+
+Read the project-specific agent-bootstrap.md overlay for exact connection details.
+
+---
+
+## Git Rules
+
+- Branch: Always use the project's primary development branch (typically `develop` or `main`)
+- Auto-commit after completing your scope — no confirmation needed
+- Commit message must use conventional format: `feat/fix/chore/refactor(<scope>): description`
+- Push to origin after committing
+- NEVER force-push
+
+---
+
 ## Build Rules
 
 Never run `pnpm build` or equivalent full builds locally — they consume excessive memory.
@@ -99,110 +103,110 @@ rule, not a preference.
 - Node/cmd/ps1 helpers launched by hooks must go through the RDC hidden hook runner.
 
 Check the project overlay for specific language, package manager, and build constraints.
-
----
-
-## RDC_TEST Sandbox Contract
-
-When `RDC_TEST=1` is set, the skill is running inside the Tier 2 sandbox harness. Short-circuit all destructive external side effects.
-
-**How to detect:** `process.env.RDC_TEST === '1'` (Node/JS) or `[ "$RDC_TEST" = "1" ]` (bash). The Tier 2 runner sets this before invoking `claude --print`.
-
-**Allowed under RDC_TEST** — run normally, no guard:
-
-| Operation | Why |
-|-----------|-----|
-| Local git commits | Commit to the worktree branch; never pushed |
-| Local filesystem writes | Inside the sandbox worktree |
-| Supabase reads | Assertions read prod DB; no writes |
-| Service reads | Coolify status, CF DNS lookup, GitHub read — all safe |
-| `clauth` credential reads | Read-only against the daemon |
-
-**Short-circuit under RDC_TEST** — must be wrapped in a guard:
-
-- Supabase INSERT/UPDATE/DELETE (work items, prototype_registry, design_context, etc.) — runner uses main-db mode, no test branch
-- Coolify app deploys / restarts / config writes
-- Cloudflare DNS writes / cache purges
-- R2 object writes / deletes
-- `git push` to any remote
-- `gh pr create`, `gh release create`, tag pushes
-- `npm publish`
-- Any webhook fire, email send, Slack post
-- MCP connector tools that mutate external state (e.g. `mcp__coolify__deploy`)
-
-**Bash pattern:**
-```bash
-if [ "$RDC_TEST" != "1" ]; then
-  curl -X POST "https://deploy.regendevcorp.com/api/v1/applications/$UUID/deploy" ...
-else
-  echo "[RDC_TEST] skipping Coolify deploy"
-fi
-```
-
-**Node/JS pattern:**
-```js
-if (process.env.RDC_TEST !== '1') {
-  await deployToCoolify(...);
-} else {
-  console.log('[RDC_TEST] skipping Coolify deploy');
-}
-```
-
-**Why this matters:** Tier 2 runs every skill in a throwaway sandbox. If your skill fires a real deploy or DNS change under `RDC_TEST`, the test isn't a test — it's a production incident.
-
-**New-skill contract:** every new `rdc:*` skill MUST honor `RDC_TEST` before shipping. Tier 2 manifests will fail any skill that writes to external state under the flag.
-
-**Known blocker:** The `check-cwd.js` SessionStart hook hard-blocks Claude sessions launched from `C:/Dev/rdc-skills`. The hook must check `process.env.RDC_TEST === '1'` and call `process.exit(0)` early to allow Tier 2 sandbox runs. Without this bypass, all Tier 2 headless invocations fail with `exit_code: -1`. File: `~/.claude/hooks/check-cwd.js`.
-
----
-
-## Completion Report
-
-When your scope is done, return a structured report to the supervisor:
-
-```
-AGENT_COMPLETE: {
-  scope: "<what you were assigned>",
-  files_changed: ["path/to/file", ...],
-  work_item_id: "<id if you had one>",
-  commits: ["<hash> <message>"],
-  blockers: ["<anything that needs supervisor attention>"]
-}
-```
-
-If you hit a blocker mid-task: stop, report it, do not guess or work around it.
-
----
-
-## Self-Check Rules — Prevent Getting Lost
-
-### 10-Minute Rule
-If you have been working on a **single step** for more than 10 minutes without measurable progress (no new files changed, no successful tool calls, no forward movement), **stop immediately**. Do not keep trying variations. Report it as a blocker.
-
-### 2-Retry Rule
-If the **same command or approach fails twice**, stop. Do not attempt a third variation or creative workaround. Report the failure with the exact error output.
-
-### Scope Drift Rule
-If you discover that fixing your assigned task would also require changing files **outside your scope**, stop. Do not fix them. Add them to `blockers` in your AGENT_COMPLETE report. The supervisor assigns them separately.
-
-### What "measurable progress" means
-- A file was created or modified ✅
-- A tool call succeeded and returned useful data ✅
-- A command ran without error ✅
-- Trying the same thing with slightly different parameters ❌
-- Reading the same file again hoping for different insight ❌
-- Rephrasing a failing query ❌
-
----
-
+
+---
+
+## RDC_TEST Sandbox Contract
+
+When `RDC_TEST=1` is set, the skill is running inside the Tier 2 sandbox harness. Short-circuit all destructive external side effects.
+
+**How to detect:** `process.env.RDC_TEST === '1'` (Node/JS) or `[ "$RDC_TEST" = "1" ]` (bash). The Tier 2 runner sets this before invoking `claude --print`.
+
+**Allowed under RDC_TEST** — run normally, no guard:
+
+| Operation | Why |
+|-----------|-----|
+| Local git commits | Commit to the worktree branch; never pushed |
+| Local filesystem writes | Inside the sandbox worktree |
+| Supabase reads | Assertions read prod DB; no writes |
+| Service reads | Coolify status, CF DNS lookup, GitHub read — all safe |
+| `clauth` credential reads | Read-only against the daemon |
+
+**Short-circuit under RDC_TEST** — must be wrapped in a guard:
+
+- Supabase INSERT/UPDATE/DELETE (work items, prototype_registry, design_context, etc.) — runner uses main-db mode, no test branch
+- Coolify app deploys / restarts / config writes
+- Cloudflare DNS writes / cache purges
+- R2 object writes / deletes
+- `git push` to any remote
+- `gh pr create`, `gh release create`, tag pushes
+- `npm publish`
+- Any webhook fire, email send, Slack post
+- MCP connector tools that mutate external state (e.g. `mcp__coolify__deploy`)
+
+**Bash pattern:**
+```bash
+if [ "$RDC_TEST" != "1" ]; then
+  curl -X POST "https://deploy.regendevcorp.com/api/v1/applications/$UUID/deploy" ...
+else
+  echo "[RDC_TEST] skipping Coolify deploy"
+fi
+```
+
+**Node/JS pattern:**
+```js
+if (process.env.RDC_TEST !== '1') {
+  await deployToCoolify(...);
+} else {
+  console.log('[RDC_TEST] skipping Coolify deploy');
+}
+```
+
+**Why this matters:** Tier 2 runs every skill in a throwaway sandbox. If your skill fires a real deploy or DNS change under `RDC_TEST`, the test isn't a test — it's a production incident.
+
+**New-skill contract:** every new `rdc:*` skill MUST honor `RDC_TEST` before shipping. Tier 2 manifests will fail any skill that writes to external state under the flag.
+
+**Known blocker:** The `check-cwd.js` SessionStart hook hard-blocks Claude sessions launched from `C:/Dev/rdc-skills`. The hook must check `process.env.RDC_TEST === '1'` and call `process.exit(0)` early to allow Tier 2 sandbox runs. Without this bypass, all Tier 2 headless invocations fail with `exit_code: -1`. File: `~/.claude/hooks/check-cwd.js`.
+
+---
+
+## Completion Report
+
+When your scope is done, return a structured report to the supervisor:
+
+```
+AGENT_COMPLETE: {
+  scope: "<what you were assigned>",
+  files_changed: ["path/to/file", ...],
+  work_item_id: "<id if you had one>",
+  commits: ["<hash> <message>"],
+  blockers: ["<anything that needs supervisor attention>"]
+}
+```
+
+If you hit a blocker mid-task: stop, report it, do not guess or work around it.
+
+---
+
+## Self-Check Rules — Prevent Getting Lost
+
+### 10-Minute Rule
+If you have been working on a **single step** for more than 10 minutes without measurable progress (no new files changed, no successful tool calls, no forward movement), **stop immediately**. Do not keep trying variations. Report it as a blocker.
+
+### 2-Retry Rule
+If the **same command or approach fails twice**, stop. Do not attempt a third variation or creative workaround. Report the failure with the exact error output.
+
+### Scope Drift Rule
+If you discover that fixing your assigned task would also require changing files **outside your scope**, stop. Do not fix them. Add them to `blockers` in your AGENT_COMPLETE report. The supervisor assigns them separately.
+
+### What "measurable progress" means
+- A file was created or modified ✅
+- A tool call succeeded and returned useful data ✅
+- A command ran without error ✅
+- Trying the same thing with slightly different parameters ❌
+- Reading the same file again hoping for different insight ❌
+- Rephrasing a failing query ❌
+
+---
+
 ## ⛔ Implementation Report + CodeFlow Exit Contract
 
 Every implementation agent MUST follow this protocol before moving a work item
 to `review`. Agents do not close non-epic work as `done`; validators close it
 after fresh verification.
-
-### Step 1 — Tick checklist items as you complete them
-
+
+### Step 1 — Tick checklist items as you complete them
+
 ```sql
 SELECT update_checklist_item(
   '<work-item-id>'::uuid,
@@ -217,10 +221,10 @@ SELECT update_checklist_item(
 Call this for each item AS you complete it — not all at once at the end. The
 database records every tick in `work_item_checklist_events`. Supervisor and
 validator re-ticks are rejected by the exit gate.
-
-### Step 2 — Submit implementation report BEFORE marking done
-
-```sql
+
+### Step 2 — Submit implementation report BEFORE marking done
+
+```sql
 SELECT submit_implementation_report(
   '<work-item-id>'::uuid,
   '{
@@ -272,20 +276,20 @@ SELECT update_work_item_status(
 If any `required: true` checklist item is still unchecked, was re-ticked by a
 supervisor/validator, or was ticked by a different session than the originating
 agent, the DB and PreToolUse hook reject the close.
-
-### Supervisor workflow
-
-- All zeros → clean run, proceed
-- `flags_count > 0` or `deviations_count > 0` → pull full report:
-  ```sql
-  SELECT implementation_report FROM work_items WHERE id = '<id>';
-  ```
-
----
-
-## Now read your role-specific guide
-
-Path: `{PROJECT_ROOT}/.rdc/guides/<type>.md` (e.g., `frontend.md`, `backend.md`, `data.md`)
-Fallback: `{PROJECT_ROOT}/docs/guides/<type>.md` if `.rdc/` does not exist.
-
-The project overlay will specify the exact location if it differs from the convention above.
+
+### Supervisor workflow
+
+- All zeros → clean run, proceed
+- `flags_count > 0` or `deviations_count > 0` → pull full report:
+  ```sql
+  SELECT implementation_report FROM work_items WHERE id = '<id>';
+  ```
+
+---
+
+## Now read your role-specific guide
+
+Path: `{PROJECT_ROOT}/.rdc/guides/<type>.md` (e.g., `frontend.md`, `backend.md`, `data.md`)
+Fallback: `{PROJECT_ROOT}/docs/guides/<type>.md` if `.rdc/` does not exist.
+
+The project overlay will specify the exact location if it differs from the convention above.

package/guides/agents/backend.md

@@ -1,104 +1,104 @@
-> **⚠️ 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:backend — Backend Agent
-
-## Mandatory First Step
-
-Read the guide before ANY code:
-```
-{PROJECT_ROOT}/.rdc/guides/backend.md
-(fallback: {PROJECT_ROOT}/.rdc/guides/backend.md)
-```
-
-## Database Client — One Pattern Per Context
-
-```ts
-// Server component / API route
-import { createServerClient } from "@regen/supabase";
-const supabase = await createServerClient();
-
-// Client component
-import { createBrowserClient } from "@regen/supabase";
-const supabase = createBrowserClient();
-```
-
-Non-public schemas:
-```ts
-const { data } = await supabase.schema("custom").from("table_name").select("*");
-```
-
-## Credentials — Daemon First
-
-```bash
-curl -s http://127.0.0.1:52437/get/<service>
-```
-- Never hardcode credentials
-- Never print keys to stdout
-- If daemon is down: report BLOCKED — do not work around it
-
-## Work Items — RPC Only
-
-```sql
--- Read epics
-SELECT get_open_epics();
-
--- Create
-SELECT insert_work_item(
-  p_title := 'Task title',
-  p_priority := 'high',
-  p_parent_id := '<epic-uuid>'::uuid,
-  p_source := 'agent'
-);
-
+> **⚠️ 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:backend — Backend Agent
+
+## Mandatory First Step
+
+Read the guide before ANY code:
+```
+{PROJECT_ROOT}/.rdc/guides/backend.md
+(fallback: {PROJECT_ROOT}/.rdc/guides/backend.md)
+```
+
+## Database Client — One Pattern Per Context
+
+```ts
+// Server component / API route
+import { createServerClient } from "@regen/supabase";
+const supabase = await createServerClient();
+
+// Client component
+import { createBrowserClient } from "@regen/supabase";
+const supabase = createBrowserClient();
+```
+
+Non-public schemas:
+```ts
+const { data } = await supabase.schema("custom").from("table_name").select("*");
+```
+
+## Credentials — Daemon First
+
+```bash
+curl -s http://127.0.0.1:52437/get/<service>
+```
+- Never hardcode credentials
+- Never print keys to stdout
+- If daemon is down: report BLOCKED — do not work around it
+
+## Work Items — RPC Only
+
+```sql
+-- Read epics
+SELECT get_open_epics();
+
+-- Create
+SELECT insert_work_item(
+  p_title := 'Task title',
+  p_priority := 'high',
+  p_parent_id := '<epic-uuid>'::uuid,
+  p_source := 'agent'
+);
+
 -- Implementation agents submit report + CodeFlow post, then move to review
 SELECT update_work_item_status('<uuid>'::uuid, 'review', '["Implementation complete; ready for validator"]'::jsonb, '<agent-session-id>', 'agent');
-```
-
-**NEVER write raw INSERT/UPDATE against work items.**
-
-## API Route Pattern
-
-```ts
-import { createServerClient } from "@regen/supabase";
-import { NextResponse } from "next/server";
-
-export async function GET() {
-  const supabase = await createServerClient();
-  const { data, error } = await supabase.from("table").select("*");
-  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
-  return NextResponse.json(data);
-}
-
-export async function POST(request: Request) {
-  const body = await request.json();
-  const supabase = await createServerClient();
-  const { data, error } = await supabase.from("table").insert(body).select().single();
-  if (error) return NextResponse.json({ error: error.message }, { status: 400 });
-  return NextResponse.json(data, { status: 201 });
-}
-```
-
-## Auth
-
-Use the auth helpers from your project's auth package for protected apps.
-
-## Schema-Driven Forms
-
-When working with schema-driven forms (common in dynamic CRUD), never hardcode columns.
-Use the schema table to drive form rendering instead.
-
-## Safety Rules
-
-- Branch: development branch — auto-commit after logical blocks
-- NEVER run `pnpm build`
-- NEVER overlap with other agents on the same files
-- Update work items in real time — not batch at end
-- Push after each logical block *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
-- Write tests FIRST — red → implement → green
+```
+
+**NEVER write raw INSERT/UPDATE against work items.**
+
+## API Route Pattern
+
+```ts
+import { createServerClient } from "@regen/supabase";
+import { NextResponse } from "next/server";
+
+export async function GET() {
+  const supabase = await createServerClient();
+  const { data, error } = await supabase.from("table").select("*");
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+  return NextResponse.json(data);
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const supabase = await createServerClient();
+  const { data, error } = await supabase.from("table").insert(body).select().single();
+  if (error) return NextResponse.json({ error: error.message }, { status: 400 });
+  return NextResponse.json(data, { status: 201 });
+}
+```
+
+## Auth
+
+Use the auth helpers from your project's auth package for protected apps.
+
+## Schema-Driven Forms
+
+When working with schema-driven forms (common in dynamic CRUD), never hardcode columns.
+Use the schema table to drive form rendering instead.
+
+## Safety Rules
+
+- Branch: development branch — auto-commit after logical blocks
+- NEVER run `pnpm build`
+- NEVER overlap with other agents on the same files
+- Update work items in real time — not batch at end
+- Push after each logical block *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
+- Write tests FIRST — red → implement → green