docs: add code claw delegation guide

code-claw-delegation.md

@@ -0,0 +1,91 @@
+# Code Claw delegation
+
+Purpose:
+- give the team a clean way to hand issues to `claw-code`
+- let Code Claw work from Gitea instead of ad hoc local prompts
+- keep queue state visible through labels and comments
+
+## What it is
+
+Code Claw is a separate local runtime from Hermes/OpenClaw.
+
+Current lane:
+- runtime: local patched `~/code-claw`
+- backend: OpenRouter
+- model: `qwen/qwen3.6-plus:free`
+- Gitea identity: `claw-code`
+- dispatch style: assign in Gitea, heartbeat picks it up every 15 minutes
+
+## Trigger methods
+
+Either of these is enough:
+- assign the issue to `claw-code`
+- add label `assigned-claw-code`
+
+## Label lifecycle
+
+- `assigned-claw-code` — queued
+- `claw-code-in-progress` — picked up by heartbeat
+- `claw-code-done` — Code Claw completed a pass
+
+## Repo coverage
+
+Currently wired:
+- `Timmy_Foundation/timmy-home`
+- `Timmy_Foundation/timmy-config`
+- `Timmy_Foundation/the-nexus`
+- `Timmy_Foundation/hermes-agent`
+
+## Operational flow
+
+1. Team assigns issue to `claw-code` or adds `assigned-claw-code`
+2. launchd heartbeat runs every 15 minutes
+3. Timmy posts a pickup comment
+4. worker clones the target repo
+5. worker creates branch `claw-code/issue-<num>`
+6. worker runs Code Claw against the issue context
+7. if work exists, worker pushes and opens a PR
+8. issue is marked `claw-code-done`
+9. completion comment links branch + PR
+
+## Logs and files
+
+Local files:
+- heartbeat script: `~/.timmy/uniwizard/codeclaw_qwen_heartbeat.py`
+- worker script: `~/.timmy/uniwizard/codeclaw_qwen_worker.py`
+- launchd job: `~/Library/LaunchAgents/ai.timmy.codeclaw-qwen-heartbeat.plist`
+
+Logs:
+- heartbeat log: `/tmp/codeclaw-qwen-heartbeat.log`
+- worker log: `/tmp/codeclaw-qwen-worker-<issue>.log`
+
+## Best-fit work
+
+Use Code Claw for:
+- small code/config/doc issues
+- repo hygiene
+- isolated bugfixes
+- narrow CI and `.gitignore` work
+- quick issue-driven patches where a PR is the desired output
+
+Do not use it first for:
+- giant epics
+- broad architecture KT
+- local game embodiment tasks
+- complex multi-repo archaeology
+
+## Proof of life
+
+Smoke-tested on:
+- `Timmy_Foundation/timmy-config#232`
+
+Observed:
+- pickup comment posted
+- branch `claw-code/issue-232` created
+- PR opened by `claw-code`
+
+## Notes
+
+- Exact PR matching matters. Do not trust broad Gitea PR queries without post-filtering by branch.
+- This lane is intentionally simple and issue-driven.
+- Treat it like a specialized intern: useful, fast, and bounded.