@lifeaitools/rdc-skills 0.9.32 → 0.9.34

package/scripts/self-test.mjs

@@ -124,6 +124,20 @@ function auditGuideFile(filepath, relPath) {
   }
 
   const lines = text.split(/\r?\n/);
+
+  if (
+    relPath === "guides/agent-bootstrap.md" &&
+    !text.includes("guides/engineering-behavior.md")
+  ) {
+    findings.push({
+      level: "error",
+      code: "guide-engineering-behavior-missing",
+      file: relPath,
+      line: 1,
+      message: "agent bootstrap must reference guides/engineering-behavior.md",
+    });
+  }
+
   lines.forEach((line, i) => {
     const lineNo = i + 1;
 

package/skills/build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:build
-description: "You have a planned epic with tasks ready to execute. Dispatches parallel typed agents, each commits atomically to develop, closes work items, and runs the validator gate. Call after rdc:plan or when told to build."
+description: "Usage `rdc:build <epic-id>` — You have a planned epic with tasks ready to execute. Dispatches parallel typed agents, each commits atomically to develop, closes work items, and runs the validator gate. Call after rdc:plan or when told to build."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -28,13 +28,15 @@ description: "You have a planned epic with tasks ready to execute. Dispatches pa
 
 Every dispatched agent MUST read two files before starting — in this order:
 1. `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` — credentials, git rules, completion report format
-   (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` if `.rdc/` does not exist)
-2. `{PROJECT_ROOT}/.rdc/guides/<type>.md` — role-specific guide
-   (fallback: `{PROJECT_ROOT}/.rdc/guides/<type>.md`)
+   (fallback: `.rdc/guides/agent-bootstrap.md` relative to cwd if `{PROJECT_ROOT}` is not substituted)
+2. `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md` — assumptions, minimal changes, surgical scope, verification evidence
+   (fallback: `.rdc/guides/engineering-behavior.md` relative to cwd if `{PROJECT_ROOT}` is not substituted)
+3. `{PROJECT_ROOT}/.rdc/guides/<type>.md` — role-specific guide
+   (fallback: `.rdc/guides/<type>.md` relative to cwd if `{PROJECT_ROOT}` is not substituted)
 
 Include both lines in every agent prompt:
 ```
-"Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md first (fallback: .rdc/guides/agent-bootstrap.md), then {PROJECT_ROOT}/.rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md) before starting."
+"Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md first (fallback: .rdc/guides/agent-bootstrap.md), then {PROJECT_ROOT}/.rdc/guides/engineering-behavior.md (fallback: .rdc/guides/engineering-behavior.md), then {PROJECT_ROOT}/.rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md) before starting."
 ```
 
 | Agent Type | Guide File | When to dispatch |
@@ -212,7 +214,7 @@ Read the task title and description, then:
    You are a frontend agent building <WP name>. Work item: <uuid>.
    Scope: <one sentence>. Files: <list>. Verification: tsc --noEmit.
    Set item to review when done, return AGENT_COMPLETE with verification evidence.
-   Read .rdc/guides/agent-bootstrap.md + .rdc/guides/frontend.md before starting.
+   Read .rdc/guides/agent-bootstrap.md + .rdc/guides/engineering-behavior.md + .rdc/guides/frontend.md before starting.
    ```
 
    **When the supervisor has NOT read the plan** (e.g. dispatching from a fresh `rdc:build` call with
@@ -224,6 +226,7 @@ Read the task title and description, then:
    - Set work item to `in_progress` before dispatching
    - Each agent prompt MUST include:
      - `"Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md first (fallback: .rdc/guides/agent-bootstrap.md), then {PROJECT_ROOT}/.rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md) before starting."`
+     - `"Read {PROJECT_ROOT}/.rdc/guides/engineering-behavior.md (fallback: .rdc/guides/engineering-behavior.md) before editing; follow it for assumptions, minimal changes, surgical scope, evidence, and escalation."`
      - Specific files to create/modify (or omit if forked agent inherits plan context)
      - Exact deliverables and commit message
      - `"NEVER run pnpm build/test. NEVER modify files outside your scope."`
@@ -233,14 +236,14 @@ Read the task title and description, then:
      - **`"If you find that a file or feature already exists: you MUST still verify it satisfies the full task spec before marking review. Finding a file is not completion. Run verification, check every requirement, and report what you found vs. what was required."`**
      - **The decomposition items from the work item's checklist** (all `decomp-*` prefixed items). Include them verbatim in the prompt and instruct the agent:
        ```
-       DECOMPOSITION CHECKLIST — you MUST implement/verify each row and tick it immediately via update_checklist_item:
+       DECOMPOSITION CHECKLIST — you MUST implement/verify each row and tick it immediately via update_checklist_item(..., p_actor_session_id := '<your-session-id>', p_actor_role := 'agent'):
        - decomp-ui-xxx: <route/file> | action=<action> | expect=<result> | evidence=<artifact>
        - decomp-api-xxx: <route/file> | action=<action> | expect=<result> | evidence=<artifact>
        Tick each item as soon as that specific behavior is implemented and proven. Do NOT batch.
        ```
      - **The test plan items from the work item's checklist** (all `test-*` prefixed items). Include them verbatim in the prompt and instruct the agent:
        ```
-       TEST PLAN — you MUST implement/verify each of these and tick them off via update_checklist_item:
+       TEST PLAN — you MUST implement/verify each of these and tick them off via update_checklist_item(..., p_actor_session_id := '<your-session-id>', p_actor_role := 'agent'):
        - test-assert-xxx: <description> → write a vitest test that proves this
        - test-smoke-xxx: <description> → run the command and confirm the result
        - test-visual-xxx: <description> → note: delegate to UI audit (you cannot verify this yourself)
@@ -299,6 +302,7 @@ Read the task title and description, then:
 
     ```
     "Read C:/Dev/regen-root/.rdc/guides/agent-bootstrap.md then C:/Dev/regen-root/.rdc/guides/verify.md.
+     Read C:/Dev/regen-root/.rdc/guides/engineering-behavior.md before validating scope, deviations, and evidence.
      Validate these work items: [list of IDs and titles].
      Apps touched: [list].
      Git diff since build start: [attach or reference].
@@ -326,7 +330,7 @@ Read the task title and description, then:
 
     **If the validator finds failures:** fix them in a new wave, then re-run the validator. Do not skip.
     **File existence alone is NOT verification.** A route returning 500 is a failure regardless of tsc passing.
-    **Unchecked test plan items are a hard gate** — `update_work_item_status('done')` will raise an exception if any `required: true` checklist item is unchecked.
+    **Unchecked test plan items are a hard gate** — `update_work_item_status('done', ..., p_actor_role := 'validator')` will raise an exception if any `required: true` checklist item is unchecked, missing agent-session tick evidence, or re-ticked by a supervisor/validator.
 
 11. **After verification passes:**
     - All wave commits are already on develop and pushed (Step 9 pushes after each wave merge).

package/skills/co-develop/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: rdc:co-develop
+description: "Usage `rdc:co-develop <ask|reply|inbox|start|resume|status>` — peer-aware Claude/Codex co-development over clauth, with ask --wait as the default delegation pattern."
+---
+
+> **⚠️ 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:co-develop — Peer-Aware Co-Development
+
+Use this skill when an RDC workflow needs Claude and Codex to work together in
+one governed session. This skill uses the clauth `codevelop_*` route only. Do
+not use `chitchat_*` for this workflow.
+
+## Arguments
+
+Use the high-level delegation commands by default:
+
+- `rdc:co-develop ask <peer> "<task>"` — delegate to partner and wait for the reply
+- `rdc:co-develop reply <turn-id> "<summary>"` — reply to a partner request with evidence
+- `rdc:co-develop inbox` — drain your inbox when you are explicitly acting as the worker
+
+- `rdc:co-develop start <name>` — create a session and return startup details
+- `rdc:co-develop resume <session-id> --peer <peer-id>` — join as a peer
+- `rdc:co-develop send --session <id> --from <peer> --to <peer> <task>` — send a turn
+- `rdc:co-develop poll --session <id> --peer <peer>` — drain messages for a peer
+- `rdc:co-develop status [session-id]` — show session status and queues
+- `rdc:co-develop stop <session-id>` — stop the session
+
+## Default Delegation Pattern
+
+When you need partner help, do not hand-write `/codevelop/send` JSON unless the
+CLI fails. Call the partner like a subagent:
+
+```powershell
+clauth codevelop ask --to codex --wait --task "Review this plan and identify blockers."
+clauth codevelop ask --to claude --wait --task "Review this implementation and advise."
+```
+
+`ask --wait` sends the request, captures the `turn_id`, polls the sender inbox,
+and returns the matching partner reply to the current live agent. This preserves
+the sender's active conversation context.
+
+When you receive a partner request, complete the bounded task and reply with:
+
+```powershell
+clauth codevelop reply --turn turn-0001 --verdict pass --summary "Reviewed plan." --evidence "Checked files X and Y" --files-changed ""
+```
+
+For manual worker intake:
+
+```powershell
+clauth codevelop inbox --peer codex
+clauth codevelop inbox --peer claude
+```
+
+## Required Transport
+
+HTTP routes:
+
+```text
+POST /codevelop/start
+POST /codevelop/join
+POST /codevelop/send
+POST /codevelop/poll
+GET  /codevelop/<session-id>/<peer-id>/stream
+GET  /codevelop/<session-id>/status
+GET  /codevelop
+POST /codevelop/stop
+```
+
+MCP tools:
+
+```text
+codevelop_start
+codevelop_join
+codevelop_send
+codevelop_poll
+codevelop_stream
+codevelop_status
+codevelop_stop
+```
+
+## Session Roles
+
+Default peers:
+
+| Peer | Role | Responsibility |
+|---|---|---|
+| `claude` | `supervisor` | RDC loop, work items, validation, integration |
+| `codex` | `implementation_partner` | implementation, focused audit, repair, evidence |
+
+Other valid turn roles: `planner`, `builder`, `reviewer`, `validator`,
+`advisor`, `release_guard`, `infra_operator`.
+
+## Message Envelope
+
+Always send structured JSON. The receiving peer must treat the JSON object as
+the source of truth.
+
+```json
+{
+  "session_id": "<session-id>",
+  "turn_id": "turn-0001",
+  "from": "claude",
+  "to": "codex",
+  "type": "audit_request",
+  "role": "reviewer",
+  "skill": "rdc:review",
+  "task": "Audit the current diff for regressions before merge.",
+  "context": {
+    "repo": "C:\\Dev\\regen-root",
+    "work_item_id": "<optional-uuid>",
+    "branch": "develop",
+    "owned_files": []
+  },
+  "expect": {
+    "response_format": "CO_DEVELOP_REPLY",
+    "evidence_required": true,
+    "commit_allowed": false
+  }
+}
+```
+
+Required reply shape:
+
+```json
+{
+  "session_id": "<session-id>",
+  "turn_id": "turn-0001",
+  "from": "codex",
+  "to": "claude",
+  "type": "reply",
+  "verdict": "pass",
+  "summary": "One paragraph.",
+  "evidence": [],
+  "files_changed": [],
+  "commits": [],
+  "blockers": [],
+  "next": []
+}
+```
+
+## Escalation Rules
+
+Invoke co-development when:
+
+- Dave asks for partner review, audit, second opinion, or co-development
+- a task crosses multiple apps, packages, repos, APIs, database surfaces, or deployment surfaces
+- `rdc:plan` creates 5 or more work packages, or 3 or more work packages with integration risk
+- `rdc:build` has file overlap or integration risk
+- `rdc:review` finds failures that need judgment
+- the same implementation, test, build, deploy, or migration path fails twice
+- architecture, auth, deployment, schema, source-of-truth, or bridge-mode interpretation is uncertain
+- a production-facing release path is about to proceed
+
+Do not invoke by default for simple read-only explanations, one-line command
+output, one-file typo fixes, or already decomposed low-risk work.
+
+## Workflow
+
+1. Start or resume a session with `codevelop_start` / `codevelop_join`.
+2. Join the local peer with a stable `peer_id`.
+3. Delegate with `clauth codevelop ask --to <partner> --wait --task "<task>"`.
+4. Treat the returned JSON as the partner result and continue your active work.
+5. If acting as the worker, drain inbox with `clauth codevelop inbox --peer <you>`.
+6. Reply with `clauth codevelop reply --turn <turn-id> ...`.
+7. Record evidence in the calling RDC skill report or work-item implementation report.
+8. Stop the session with `codevelop_stop` when the work is done.
+
+## Completion Evidence
+
+Every co-development turn must report:
+
+- session ID and turn ID
+- peer IDs
+- files changed
+- commands/tests/routes checked
+- commits, if any
+- blockers or decisions needed
+- next action

package/skills/collab/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:collab
-description: "Bidirectional relay with a claude.ai session — read inbox, do work, write outbox, loop. Use when coordinating with a parallel claude.ai conversation."
+description: "Usage `rdc:collab --session <session_id>` — Bidirectional relay with a claude.ai session — read inbox, do work, write outbox, loop. Use when coordinating with a parallel claude.ai conversation."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`

package/skills/deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:deploy
-description: "Deploy an app to Coolify (production) or PM2 (staging), add a new Coolify app, diagnose a failed deploy, or audit watch paths. Handles DNS, health checks, and post-deploy verification."
+description: "Usage `rdc:deploy <slug> [new|diagnose|audit] [--fix]` — Deploy an app to Coolify (production) or PM2 (staging), add a new Coolify app, diagnose a failed deploy, or audit watch paths. Handles DNS, health checks, and post-deploy verification."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:design
-description: "RDC-owned design work for Studio, Palette Library, and token-aware UI systems. Use for Rampant color work or design-system-first builds owned by the design cell. Not for general UI polish — use impeccable for that."
+description: "Usage `rdc:design <topic>` — RDC-owned design work for Studio, Palette Library, and token-aware UI systems. Use for Rampant color work or design-system-first builds owned by the design cell. Not for general UI polish — use impeccable for that."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -96,7 +96,7 @@ Project docs to read for Studio work:
      ```powershell
      curl.exe -s -X POST "http://127.0.0.1:52437/studio/debug/start" `
        -H "Content-Type: application/json" `
-       -d "{\"brandSlug\":\"<brandSlug>\",\"appSlug\":\"<appSlug>\",\"repoRoot\":\"C:/Dev/regen-root\",\"cwd\":\"C:/Dev/regen-root\",\"modeDefault\":\"direct_edit\",\"startedBy\":\"claude-cli\"}"
+       -d "{\"brandSlug\":\"<brandSlug>\",\"appSlug\":\"<appSlug>\",\"repoRoot\":\"{PROJECT_ROOT}\",\"cwd\":\"{PROJECT_ROOT}\",\"modeDefault\":\"direct_edit\",\"startedBy\":\"claude-cli\"}"
      ```
    - Expected successful response shape:
      ```json
@@ -128,7 +128,7 @@ Project docs to read for Studio work:
    - Allowed terminal statuses are `done`, `error`, `blocked`, and `needs_reference`.
    - Convenience helper, equivalent to the canonical start call plus attach URL construction:
      ```powershell
-     node scripts/studio-debug-start.mjs --target <url|domain|brand|app|file> [--brand <slug>] [--app <slug>] [--mode direct_edit|variant_edit|reference_replace|note] [--studio-origin http://localhost:3011] [--connector http://127.0.0.1:52437] [--repo-root C:/Dev/regen-root] [--cwd C:/Dev/regen-root] [--dev-url <url>] [--dev-command <command>] [--no-launch]
+     node scripts/studio-debug-start.mjs --target <url|domain|brand|app|file> [--brand <slug>] [--app <slug>] [--mode direct_edit|variant_edit|reference_replace|note] [--studio-origin http://localhost:3011] [--connector http://127.0.0.1:52437] [--repo-root {PROJECT_ROOT}] [--cwd {PROJECT_ROOT}] [--dev-url <url>] [--dev-command <command>] [--no-launch]
      ```
    - Helper output contract:
      ```txt

package/skills/fixit/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: rdc:fixit
-description: "Quick fix under 5 files / 30 min that does not warrant a full plan→build cycle. Creates a minimal work item, makes the change, commits, closes. The only sanctioned bypass of rdc:build."
+description: "Usage `rdc:fixit <description>` — Quick fix under 5 files / 30 min that does not warrant a full plan→build cycle. Creates a minimal work item, makes the change, commits, closes. The only sanctioned bypass of rdc:build."
 ---
 
 > **⚠️ 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`).
+> 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`), then `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md` (fallback: `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.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.
 
@@ -74,6 +74,10 @@ Do the minimal work. Scope creep rule: if you discover the fix requires more tha
 2. Delete the marker file
 3. Tell the user to use `/rdc:build` instead
 
+Apply `guides/engineering-behavior.md`: state material assumptions in the
+implementation report, avoid speculative abstractions, touch only required
+files, and verify behavior before moving the work item to `review`.
+
 ### 5. Commit
 
 ```bash
@@ -88,21 +92,31 @@ fi
 
 ### 6. Close and clean up
 
-Submit implementation report first, then mark done:
+Submit implementation report first, move to review, then close as validator:
 
 ```sql
 SELECT submit_implementation_report('<id>'::uuid,
-  '{"tldr":"<one sentence>","assumptions":[],"deviations":[],"uncertainty":[],"detail":"<what was fixed>","flags":[],"transactional":false,"memory_records":[]}'::jsonb
+  '{"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',
-  '["Fixed via rdc:fixit"]'::jsonb
+  '["Validator verified rdc:fixit report, CodeFlow post, and checklist evidence"]'::jsonb,
+  '<validator-session-id>',
+  'validator'
 );
 ```
 
 If the fix touched a transactional flow, API boundary, or package contract, set `"transactional": true` and populate `memory_records` (see `agent-bootstrap.md`), then run:
 ```bash
 node scripts/work-item-memory.mjs <work-item-id>
+# Note: verify script exists first: ls {PROJECT_ROOT}/scripts/work-item-memory.mjs
+# If the script is absent, skip this step and note it in the implementation report.
 ```
 
 ```bash

package/skills/fs-mcp/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: rdc:fs-mcp
+description: "Usage `rdc:fs-mcp <task>` — Use the File System MCP bridge for live repo reads, safe writes, cloud-to-local ingest, and GitHub-branch imports into a dirty local monorepo. Use when Claude.ai, Cowork, or CLI agents need fs_read/fs_write/fs_import_git_files guidance."
+---
+
+> **⚠️ 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:fs-mcp — File System MCP Bridge
+
+## When to Use
+- Claude.ai, Cowork, or another remote surface needs live access to `C:/Dev/regen-root` through the File System MCP.
+- You need to read, search, or list current local repo files without relying on GitHub freshness.
+- You need to write a small/scratch file through FS MCP.
+- You need to move a larger cloud file into the local repo.
+- Claude.ai created a durable new docs/corpus file on a GitHub branch and local dev needs to import it into a dirty monorepo.
+
+## Arguments
+- `rdc:fs-mcp read` — choose the right read/search/list tool.
+- `rdc:fs-mcp write` — choose direct write, chunked write, append, or URL ingest.
+- `rdc:fs-mcp import-git` — import named files from a GitHub branch/commit into local dev.
+- `rdc:fs-mcp status` — inspect mounts and repo state before deciding.
+
+## Procedure
+
+### 1. Identify the file intent
+
+Classify the file before writing:
+
+| Intent | Default path | Default action |
+|---|---|---|
+| Live repo read | Existing repo path | `fs_read`, `fs_grep`, `fs_glob`, `fs_list` |
+| Small scratch or relay file | `.rdc/relay/`, `.codex/tmp/`, agreed temp path | `fs_write` |
+| Large text file from the current chat | Target path | `fs_write_chunk` |
+| Cloud-hosted file | Target path | `fs_ingest_url` |
+| Durable new docs/corpus file from Claude.ai | Actual target path in `docs/**`, `.rdc/plans/**`, `.claude/context/**` | GitHub branch commit, then `fs_import_git_files` |
+| Existing file update | Existing repo path | Prefer patch/review workflow; do not overwrite unless explicitly requested |
+
+### 2. Read/search from live local FS
+
+Use FS MCP first for local state:
+
+```text
+fs_read CLAUDE.md
+fs_glob docs/**/*.md
+fs_grep "bridge mode" docs/
+fs_list .rdc/relay/from-claude-code/
+```
+
+Use GitHub for remote branch/file history, PRs, and durable publication. Use FS for the current local worktree.
+
+### 3. Choose the safest write surface
+
+Use direct FS writes only when the payload is small and the destination is clear:
+
+```text
+fs_write path=".rdc/relay/from-claude-ai/<timestamp>-topic.md"
+```
+
+Use chunked writes for larger text:
+
+```text
+fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=0 total_chunks=3 content="..."
+fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=1 total_chunks=3 content="..."
+fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=2 total_chunks=3 content="..."
+```
+
+Use URL ingest when the file already exists in cloud storage:
+
+```text
+fs_ingest_url url="https://..." path="docs/source/file.md" expected_sha256="<optional>"
+```
+
+Use guarded append when appending to a known file:
+
+```text
+fs_stat path="docs/plans/foo.md"
+fs_append path="docs/plans/foo.md" content="\n..." expected_sha256="<hash from fs_stat>"
+```
+
+### 4. Import durable new files from GitHub instead of large FS writes
+
+When Claude.ai creates a durable new docs/corpus file, publish it to a GitHub branch first, then ask FS MCP to import the exact file path.
+
+Required Claude.ai handoff shape:
+
+```json
+{
+  "repo": "LIFEAI/regen-root",
+  "remote": "origin",
+  "ref": "claude-ai/docs-upload-123",
+  "paths": ["docs/plans/foo.md"],
+  "mode": "new_only",
+  "commit": true,
+  "message": "docs(plans): add foo"
+}
+```
+
+Then call:
+
+```text
+fs_import_git_files remote="origin" ref="claude-ai/docs-upload-123" paths=["docs/plans/foo.md"] mode="new_only" commit=true message="docs(plans): add foo"
+```
+
+This tool must fetch only, restore only named paths, optionally commit only those paths, and never push.
+
+### 5. Safety rules
+
+- Never run or request `git pull` for the dirty monorepo.
+- Never checkout a whole branch into the local worktree.
+- For durable docs/corpus, save to the actual target path, not an upload folder, when the target is known.
+- Use upload/incoming folders only when the final destination is unknown.
+- Default to `new_only` for Git imports.
+- Refuse overwrites unless the user explicitly asks for overwrite/update behavior.
+- Stage only imported paths when committing.
+- Never push from FS import unless the user explicitly asks for a push-capable workflow.
+
+### 6. Completion report
+
+Report:
+
+```text
+FS MCP: <read/write/import> complete
+Paths: <paths>
+Source ref/commit: <if Git import>
+Local commit: <if committed>
+Verification: <fs_stat/hash or import result>
+Blocked/conflicts: <none or list>
+```

package/skills/handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:handoff
-description: "Convert a finalized plan or prototype into CLI-ready artifacts: writes .rdc/plans/, creates Supabase work items with DoD checklists, registers prototype if present. Bridge between planning session and rdc:build."
+description: "Usage `rdc:handoff [--from-prototype <id>]` — Convert a finalized plan or prototype into CLI-ready artifacts: writes .rdc/plans/, creates Supabase work items with DoD checklists, registers prototype if present. Bridge between planning session and rdc:build."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`

package/skills/help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:help
-description: "Show all rdc:* skills with full argument syntax. Call when unsure which skill to use or what args it takes."
+description: "Usage `rdc:help` — Show all rdc:* skills with full argument syntax. Call when unsure which skill to use or what args it takes."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -52,6 +52,7 @@ description: "Show all rdc:* skills with full argument syntax. Call when unsure
 | `rdc:prototype` | `rdc:prototype <description>` — JSX mock for review |
 | `rdc:workitems` | `rdc:workitems <add\|update\|done\|list\|epics> [args]` |
 | `rdc:collab` | `rdc:collab --session <id>` — claude.ai bidirectional relay |
+| `rdc:co-develop` | `rdc:co-develop <start\|resume\|send\|poll\|status\|stop>` — Claude/Codex peer-aware co-development |
 | `rdc:design` | `rdc:design <command\|brief>` — RDC/Studio design, tokens, palettes, themes, Rampa CLI |
 
 ## Agent guides (dispatched by rdc:build, not user-invocable)
@@ -89,6 +90,7 @@ Project lead says → invoke
 "hand this off" / "give to agents"      → rdc:handoff
 "show me what it looks like"            → rdc:prototype
 "add to backlog" / "create a ticket"    → rdc:workitems
+"work together" / "partner review"       → rdc:co-develop start <name>
 "design/tokens/palette/theme"           → rdc:design <command>
 "what commands" / "what skills"         → rdc:help
 ```
@@ -99,4 +101,4 @@ Project lead says → invoke
 - NEVER commit to `main` without explicit approval. Default branch is `develop`.
 - NEVER overlap agents on the same files.
 - ALWAYS update work items in real time via RPCs (see `.claude/rules/work-items-rpc.md`).
-- ALWAYS credentials via clauth daemon: `curl -s http://127.0.0.1:52437/get/<service>`.
+- ALWAYS credentials via clauth daemon: `curl -s http://127.0.0.1:52437/v/<service>` (returns plain text).

package/skills/overnight/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:overnight
-description: "Unattended end-to-end: drain the entire work queue autonomously (preplan → plan → build → review → report). Use when leaving Claude to run unsupervised for an extended session."
+description: "Usage `rdc:overnight [epic-id|label=<label>]` — Unattended end-to-end: drain the entire work queue autonomously (preplan → plan → build → review → report). Use when leaving Claude to run unsupervised for an extended session."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -29,13 +29,13 @@ description: "Unattended end-to-end: drain the entire work queue autonomously (p
 **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
+mkdir -p {PROJECT_ROOT}/.rdc && touch {PROJECT_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
+rm -f {PROJECT_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.

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:plan
-description: "No epic exists and you need architecture + task breakdown. Produces design decisions, tradeoffs, and Supabase epics/tasks with DoD checklists that feed rdc:build. Use after rdc:preplan or when given clear architectural direction."
+description: "Usage `rdc:plan <topic>` — No epic exists and you need architecture + task breakdown. Produces design decisions, tradeoffs, and Supabase epics/tasks with DoD checklists that feed rdc:build. Use after rdc:preplan or when given clear architectural direction."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -182,8 +182,9 @@ description: "No epic exists and you need architecture + task breakdown. Produce
        ]'::jsonb
      );
      ```
-   - Agents MUST tick each `decomp-*` and `test-*` checklist item as they implement/verify it (via `update_checklist_item`)
-   - `update_work_item_status('done')` will REJECT if any `required: true` item is unchecked — this is the enforcement gate
+   - Agents MUST tick each `decomp-*` and `test-*` checklist item as they implement/verify it via `update_checklist_item(..., p_actor_session_id := '<agent-session-id>', p_actor_role := 'agent')`
+   - Agents submit `implementation_report.codeflow_post`, then move work to `review`; validators close `done`
+   - `update_work_item_status('done', ..., p_actor_role := 'validator')` rejects missing reports, unchecked required items, and supervisor/validator re-ticks
    - Set priorities: urgent/high/normal based on sequencing
 
 7. **Report results:**

package/skills/preplan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:preplan
-description: "Before committing to an architecture, research unknowns first. Codebase scan + web search, no code written, no work items created. Output feeds rdc:plan. Use for open-ended approach questions."
+description: "Usage `rdc:preplan <topic>` — Before committing to an architecture, research unknowns first. Codebase scan + web search, no code written, no work items created. Output feeds rdc:plan. Use for open-ended approach questions."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`

package/skills/prototype/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:prototype
-description: "Build a JSX/TSX mockup for visual review before implementation. Saves to docs/source/, registers in prototype_registry. Use when asked to mock something up or show what it looks like. Not production code."
+description: "Usage `rdc:prototype <description>` — Build a JSX/TSX mockup for visual review before implementation. Saves to docs/source/, registers in prototype_registry. Use when asked to mock something up or show what it looks like. Not production code."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`

package/skills/release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:release
-description: "Promote develop→main and deploy to production for any LIFEAI repo (clauth, rdc-skills, regen-root, etc.), or promote a staged app with rdc:release promote <slug>. Requires dev verification first."
+description: "Usage `rdc:release [promote <slug>|rdc-skills|clauth]` — Promote develop→main and deploy to production for any LIFEAI repo (clauth, rdc-skills, regen-root, etc.), or promote a staged app with rdc:release promote <slug>. Requires dev verification first."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -186,7 +186,7 @@ Only run this after the channel event confirms success — don't poll npm indepe
 - **rdc-skills:** none
 
 #### 8. Smoke test
-- **clauth:** `curl -s http://127.0.0.1:52437/get/supabase-anon | python3 -c "import sys,json; print('ok' if json.load(sys.stdin).get('value') else 'fail')"` — expect `ok`
+- **clauth:** `curl -s http://127.0.0.1:52437/v/supabase-anon` — expect a non-empty JWT string
 - **rdc-skills:** read frontmatter of one new/updated SKILL.md — parse succeeds
 
 ---

package/skills/report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:report
-description: "Write the nightly session summary to .rdc/reports/YYYY-MM-DD.md covering completed work, open items, per-project progress, and infra status. Call at session end."
+description: "Usage `rdc:report` — Write the nightly session summary to .rdc/reports/YYYY-MM-DD.md covering completed work, open items, per-project progress, and infra status. Call at session end."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`