@lifeaitools/rdc-skills 0.9.33 → 0.9.35

package/skills/fixit/SKILL.md

@@ -1,132 +1,136 @@
----
-name: rdc:fixit
-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`).
-
-> **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
-
-Do the minimal work. 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
-```
-
-### 6. Close and clean up
-
-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":[],"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'
-);
-```
-
-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
-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
+---
+name: rdc:fixit
+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`), 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.
+
+
+# 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
+
+Do the minimal work. 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
+
+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
+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
+```
+
+### 6. Close and clean up
+
+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":[],"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'
+);
+```
+
+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
+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

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>
+```