@lifeaitools/rdc-skills 0.9.32 → 0.9.33

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,217 +1,217 @@
----
-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."
----
-
-> **⚠️ 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 skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag. Chitchat relay writes (`chitchat_reply`) and git push are skipped under `RDC_TEST=1`.
-
-
-# /rdc:collab — Claude Code Collab Session Listener
-> Invoked as: `/rdc:collab --session <session_id>`
-> You are the build/execute half of a live collab session with claude.ai.
-> Transport: chitchat MCP tools (`chitchat_poll` / `chitchat_reply`) + SSE stream
-> Dave is watching this terminal and can interject at any time.
-
----
-
-## When to Use
-- Project lead wants to delegate a task to a claude.ai session
-- You need bidirectional relay between this CLI agent and a claude.ai coworker
-- An async work handoff is in progress via the chitchat relay
-
-## Arguments
-
-- `rdc:collab --session <id>` — start or resume a collab relay with the given session ID
-
-## What This Is
-
-claude.ai writes tasks into your inbox via `chitchat_send`. The clauth daemon
-queues them and — if you are connected to the SSE stream — pushes the event
-immediately (zero-latency). You read, act, commit, reply via `chitchat_reply`,
-and loop. Dave can watch everything in this terminal and interject by typing —
-treat anything Dave types as a high-priority override.
-
----
-
-## Step 1 — Parse session ID
-
-Extract `--session <uuid>` from args.
-
-If no `--session`, call `chitchat_list` and show all active sessions.
-
----
-
-## Step 2 — Initialize (chitchat-native)
-
-Call `chitchat_list` to verify the session exists in the daemon.
-
-If the session is not found:
-```
-Session <id> not found in clauth daemon.
-Start a session from claude.ai first:
-  chitchat_start(name: "<session-slug>")
-Then pass the returned session_id here.
-```
-
-Send the ready signal via MCP:
-```
-chitchat_reply(session_id, "Claude Code connected. Ready to receive tasks.\ncwd: <rootPath>")
-```
-
-Print to terminal:
-```
-[rdc:collab] Session <id> active (chitchat transport).
-SSE stream: http://127.0.0.1:52437/chitchat/<id>/stream
-Waiting for messages from claude.ai... (Ctrl+C to end)
-```
-
-Note: File relay at `.rdc/relay/sessions/` is kept for backwards compatibility
-but is no longer the primary transport. Chitchat MCP + SSE is the default.
-
----
-
-## Step 3 — Wait for message (SSE-first, poll-fallback)
-
-### Primary path — SSE (zero-latency)
-
-Connect to the SSE stream and wait for the daemon to push a message:
-
-```bash
-curl -s -N --max-time 30 http://127.0.0.1:52437/chitchat/<session_id>/stream
-```
-
-The stream emits:
-- `event: message` lines with `data: <JSON>` when `chitchat_send` fires from claude.ai
-- `: keepalive` comment lines every 15s (ignore these)
-
-**When a `data:` event arrives:** parse the JSON directly — it contains the
-message. The SSE stream drains the inbox as it delivers; do NOT call
-`chitchat_poll` after receiving via SSE. Proceed directly to Step 4 with the
-parsed message body.
-
-**If 30s elapses with no message event (only keepalives or silence):**
-Print `[rdc:collab] Still listening...` and retry SSE immediately. After 10
-consecutive 30s timeouts (5 min idle), print a longer heartbeat but keep
-looping.
-
-**If curl fails (daemon restart, connection refused, non-200):** fall back to
-polling path below.
-
-### Fallback path — polling (2s interval)
-
-Use this path only when SSE is unavailable:
-
-```
-loop:
-  result = chitchat_poll(session_id)
-  if result.status == "ready":
-    → proceed to Step 4 with result.message
-  else (status == "idle"):
-    wait 2 seconds
-    continue loop
-```
-
-**`chitchat_poll` return shapes:**
-- `{ status: "idle" }` — inbox empty, keep polling
-- `{ status: "ready", message: "..." }` — message waiting, consume it
-
----
-
-## Step 4 — Process message
-
-You now have the message body (from SSE `data:` JSON or `chitchat_poll` result).
-
-Check if the message begins with `type: stop` (literal prefix) or contains a
-`type` field equal to `"stop"` in the JSON.
-
-**`type: stop`** → go to Step 7.
-
-**Anything else (default: task/message):**
-
-Print to terminal:
-```
-[rdc:collab] Turn <N> from claude.ai:
-──────────────────────────────────────
-<message body>
-──────────────────────────────────────
-```
-
----
-
-## Step 5 — Do the work
-
-Act on the message. Full Claude Code capabilities:
-- File edits, git commits to `develop`
-- Supabase RPC queries
-- Type-checks: `npx tsc --noEmit` (never `pnpm build`)
-- Run skills: `/rdc:plan`, `/rdc:fixit`, etc.
-- Answer questions directly
-
-Follow `.rdc/guides/agent-bootstrap.md` rules throughout.
-
-For long tasks, stream progress updates mid-work:
-```
-chitchat_reply(session_id, "Turn <N> in progress: <what you've done so far>...")
-```
-This lets claude.ai see progress immediately rather than waiting for the full
-response.
-
----
-
-## Step 6 — Send response
-
-When work is done, send the response via MCP:
-
-```
-chitchat_reply(session_id, "<response body>")
-```
-
-Response body format:
-```
-Turn <N> complete.
-Commits: <sha1, sha2 or none>
-
-<what you did, what you found, any questions or decisions needed from claude.ai>
-```
-
-Print to terminal:
-```
-[rdc:collab] Turn <N> done. Response sent via chitchat_reply.
-Waiting for next message...
-```
-
-Return to Step 3.
-
----
-
-## Step 7 — End session
-
-Received `type: stop` message, or Dave pressed Ctrl+C.
-
-Send final summary via MCP:
-```
-chitchat_reply(session_id, "Session complete.\nTurns: <N>\nCommits: <list or none>\nOpen items: <anything unresolved>")
-```
-
-Then call:
-```
-chitchat_stop(session_id)
-```
-
-Print:
-```
-[rdc:collab] Session ended.
-```
-
----
-
-## Dave Interjections
-
-If Dave types in this terminal during a turn:
-- Treat it as an override injected into the current task
-- Acknowledge it in your `chitchat_reply` response
-- If it changes direction mid-task, note what you stopped and why
+---
+name: rdc:collab
+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`
+> 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 skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag. Chitchat relay writes (`chitchat_reply`) and git push are skipped under `RDC_TEST=1`.
+
+
+# /rdc:collab — Claude Code Collab Session Listener
+> Invoked as: `/rdc:collab --session <session_id>`
+> You are the build/execute half of a live collab session with claude.ai.
+> Transport: chitchat MCP tools (`chitchat_poll` / `chitchat_reply`) + SSE stream
+> Dave is watching this terminal and can interject at any time.
+
+---
+
+## When to Use
+- Project lead wants to delegate a task to a claude.ai session
+- You need bidirectional relay between this CLI agent and a claude.ai coworker
+- An async work handoff is in progress via the chitchat relay
+
+## Arguments
+
+- `rdc:collab --session <id>` — start or resume a collab relay with the given session ID
+
+## What This Is
+
+claude.ai writes tasks into your inbox via `chitchat_send`. The clauth daemon
+queues them and — if you are connected to the SSE stream — pushes the event
+immediately (zero-latency). You read, act, commit, reply via `chitchat_reply`,
+and loop. Dave can watch everything in this terminal and interject by typing —
+treat anything Dave types as a high-priority override.
+
+---
+
+## Step 1 — Parse session ID
+
+Extract `--session <uuid>` from args.
+
+If no `--session`, call `chitchat_list` and show all active sessions.
+
+---
+
+## Step 2 — Initialize (chitchat-native)
+
+Call `chitchat_list` to verify the session exists in the daemon.
+
+If the session is not found:
+```
+Session <id> not found in clauth daemon.
+Start a session from claude.ai first:
+  chitchat_start(name: "<session-slug>")
+Then pass the returned session_id here.
+```
+
+Send the ready signal via MCP:
+```
+chitchat_reply(session_id, "Claude Code connected. Ready to receive tasks.\ncwd: <rootPath>")
+```
+
+Print to terminal:
+```
+[rdc:collab] Session <id> active (chitchat transport).
+SSE stream: http://127.0.0.1:52437/chitchat/<id>/stream
+Waiting for messages from claude.ai... (Ctrl+C to end)
+```
+
+Note: File relay at `.rdc/relay/sessions/` is kept for backwards compatibility
+but is no longer the primary transport. Chitchat MCP + SSE is the default.
+
+---
+
+## Step 3 — Wait for message (SSE-first, poll-fallback)
+
+### Primary path — SSE (zero-latency)
+
+Connect to the SSE stream and wait for the daemon to push a message:
+
+```bash
+curl -s -N --max-time 30 http://127.0.0.1:52437/chitchat/<session_id>/stream
+```
+
+The stream emits:
+- `event: message` lines with `data: <JSON>` when `chitchat_send` fires from claude.ai
+- `: keepalive` comment lines every 15s (ignore these)
+
+**When a `data:` event arrives:** parse the JSON directly — it contains the
+message. The SSE stream drains the inbox as it delivers; do NOT call
+`chitchat_poll` after receiving via SSE. Proceed directly to Step 4 with the
+parsed message body.
+
+**If 30s elapses with no message event (only keepalives or silence):**
+Print `[rdc:collab] Still listening...` and retry SSE immediately. After 10
+consecutive 30s timeouts (5 min idle), print a longer heartbeat but keep
+looping.
+
+**If curl fails (daemon restart, connection refused, non-200):** fall back to
+polling path below.
+
+### Fallback path — polling (2s interval)
+
+Use this path only when SSE is unavailable:
+
+```
+loop:
+  result = chitchat_poll(session_id)
+  if result.status == "ready":
+    → proceed to Step 4 with result.message
+  else (status == "idle"):
+    wait 2 seconds
+    continue loop
+```
+
+**`chitchat_poll` return shapes:**
+- `{ status: "idle" }` — inbox empty, keep polling
+- `{ status: "ready", message: "..." }` — message waiting, consume it
+
+---
+
+## Step 4 — Process message
+
+You now have the message body (from SSE `data:` JSON or `chitchat_poll` result).
+
+Check if the message begins with `type: stop` (literal prefix) or contains a
+`type` field equal to `"stop"` in the JSON.
+
+**`type: stop`** → go to Step 7.
+
+**Anything else (default: task/message):**
+
+Print to terminal:
+```
+[rdc:collab] Turn <N> from claude.ai:
+──────────────────────────────────────
+<message body>
+──────────────────────────────────────
+```
+
+---
+
+## Step 5 — Do the work
+
+Act on the message. Full Claude Code capabilities:
+- File edits, git commits to `develop`
+- Supabase RPC queries
+- Type-checks: `npx tsc --noEmit` (never `pnpm build`)
+- Run skills: `/rdc:plan`, `/rdc:fixit`, etc.
+- Answer questions directly
+
+Follow `.rdc/guides/agent-bootstrap.md` rules throughout.
+
+For long tasks, stream progress updates mid-work:
+```
+chitchat_reply(session_id, "Turn <N> in progress: <what you've done so far>...")
+```
+This lets claude.ai see progress immediately rather than waiting for the full
+response.
+
+---
+
+## Step 6 — Send response
+
+When work is done, send the response via MCP:
+
+```
+chitchat_reply(session_id, "<response body>")
+```
+
+Response body format:
+```
+Turn <N> complete.
+Commits: <sha1, sha2 or none>
+
+<what you did, what you found, any questions or decisions needed from claude.ai>
+```
+
+Print to terminal:
+```
+[rdc:collab] Turn <N> done. Response sent via chitchat_reply.
+Waiting for next message...
+```
+
+Return to Step 3.
+
+---
+
+## Step 7 — End session
+
+Received `type: stop` message, or Dave pressed Ctrl+C.
+
+Send final summary via MCP:
+```
+chitchat_reply(session_id, "Session complete.\nTurns: <N>\nCommits: <list or none>\nOpen items: <anything unresolved>")
+```
+
+Then call:
+```
+chitchat_stop(session_id)
+```
+
+Print:
+```
+[rdc:collab] Session ended.
+```
+
+---
+
+## Dave Interjections
+
+If Dave types in this terminal during a turn:
+- Treat it as an override injected into the current task
+- Acknowledge it in your `chitchat_reply` response
+- If it changes direction mid-task, note what you stopped and why