@humwick/runner 0.0.0-stage → 0.130.1

package/plugins/codex/skills/reply/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: reply
+description: Reply to an Humwick message by ID. Auto-routes to the sender and inherits channel context — no target needed. Use when the user invokes /reply or asks to reply to a specific relay message, especially with stdin/file for long replies.
+argument-hint: "<messageId> <message|--stdin|--body-file PATH>"
+allowed-tools: [Bash]
+---
+
+# Humwick Reply
+
+⚠️ **SECURITY — never inline the reply body in the shell command.** Your shell runs
+the command you type, so a body containing markdown backticks `` `like this` `` or
+`$(...)` would be executed as a shell command *before* `agent-relay` ever sees it
+(command substitution). This is a real command-injection vector (#1262): the body may
+quote another agent's or a user's text. **Always feed the body through stdin via a
+quoted heredoc**, which disables all shell expansion and delivers the body verbatim.
+
+Run (safe — quoted `'RELAY_EOF'` delimiter means no expansion, no substitution):
+
+```bash
+agent-relay /reply <messageId> --stdin <<'RELAY_EOF'
+Your reply text here. Backticks `bun run release` and $(anything) are delivered
+verbatim and are NOT executed.
+RELAY_EOF
+```
+
+The server auto-routes the reply to the original sender and inherits the channel
+(Telegram, Slack, etc.) if applicable. No target or channel ID needed.
+
+For a reply you have already staged in a file, use `--body-file` instead:
+
+```bash
+agent-relay /reply <messageId> --body-file .agent-relay/sessions/$AGENT_RELAY_ID/tmp/reply.md
+```
+
+The relay creates that per-session scratch dir for you (git-ignored locally), so
+staging there never pollutes the working tree and never collides with other agents.
+No cleanup needed — the dir is reaped when your session ends. Oversized replies are
+automatically uploaded as an Humwick artifact and sent as an attached concise reply.
+
+**Do NOT** build `agent-relay /reply <id> "…body…"` with the body inside quotes — the
+heredoc `--stdin` form above is the only safe way to pass free text.
+
+Do not send a separate Relay follow-up that only confirms the reply was sent. The CLI
+output is enough local confirmation.

package/plugins/codex/skills/send-claimable/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: send-claimable
+description: Send a claimable Humwick work item so one matching agent can claim and handle it. Use when the user invokes /send-claimable or wants to enqueue work for another agent.
+argument-hint: "<target> <message|--stdin|--body-file PATH> [--subject TEXT] [--channel NAME]"
+allowed-tools: [Bash]
+---
+
+# Humwick Send Claimable
+
+⚠️ **SECURITY — never inline the work-item body in the shell command.** A body with
+markdown backticks `` `like this` `` or `$(...)` would be shell-executed (command
+substitution) before `agent-relay` sees it — a command-injection vector (#1262).
+**Feed the body through stdin via a quoted heredoc** (the `'RELAY_EOF'` quotes disable
+all expansion, delivering the body verbatim):
+
+```bash
+agent-relay /send-claimable <target> --stdin <<'RELAY_EOF'
+Describe the work item here. Backticks `bun run release` and $(anything) are
+delivered verbatim and are NOT executed.
+RELAY_EOF
+```
+
+Targets can be an agent id, `tag:`, `cap:`, or `policy:`:
+
+```bash
+agent-relay /send-claimable tag:backend --stdin <<'RELAY_EOF'
+Fix the failing API test
+RELAY_EOF
+
+agent-relay /send-claimable cap:review --stdin <<'RELAY_EOF'
+Review the migration patch
+RELAY_EOF
+```
+
+For a work item you have already staged in a file, use `--body-file PATH` instead.
+
+**Do NOT** build `agent-relay /send-claimable <target> "…body…"` with the body inside quotes.
+
+Report the sent claimable message id briefly.

package/plugins/codex/skills/slice-first/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: slice-first
+description: Frame and prove a thin end-to-end feature slice before planning hardening. Use for new feature coordination or stage decisions in any project.
+---
+
+# Slice first
+
+Use the current project's instructions and configured validation/deployment gates,
+including its “How to validate in THIS project” brief or `.agent-relay/land-gates.json`.
+Choose the proof's location and runtime in that project; no particular repo is required.
+
+| Stage | Required result |
+|---|---|
+| frame | Write and commit the executable proof FIRST; it fails for the right reason. Then a slice spec, max one page: path, proof command, allowed shortcuts, fixed v1 bar, unknowns, harden budget (default 6 Tasks). |
+| slice | One builder, one branch, all layers, flag off by default. Proof passes on a deployed/ephemeral instance and a different agent reproduces it. |
+| harden | Only after independent proof passes: plan small changes to the working feature; re-run the proof at every delivery. |
+| v1 | Fixed bar met; enable flag; file remaining work as future issues outside the DAG. |
+| closed | Record closure. |
+
+Coordinator owns stages, scope ledger and budget; record stage decisions on the spec
+Task. Changing the bar or exceeding the budget needs operator approval. A blocked
+slice returns to frame. Never create or spawn harden Tasks before the proof Task is
+done with `slice-proof: pass`; dependencies alone do not prevent dispatch.
+
+Design writes proof then spec, no full design. Builder declares each slice shortcut
+in delivery risks. QA reproduces independently. Review blocks only on the stage's
+bar: declared slice shortcuts may pass; unmet harden/v1 criteria block. Outside-bar
+findings are future work.
+
+`slice-proof` supplements project gates; it never replaces them. Record command,
+revision and instance with the result. For coordinators building a plan, load
+[references/plan-recipe.md](references/plan-recipe.md). Other roles need no recipe.

package/plugins/codex/skills/slice-first/references/plan-recipe.md

@@ -0,0 +1,46 @@
+# Plan recipe (coordinator only)
+
+1. **Frame.** `relay_plan_create { title:"<feature>", acceptance:[{ id, text, check?:{ path }|{ command } }] }`.
+   Acceptance is required: the plan's own bar (the design doc's deliverables, deletions and
+   acceptance commands), one checkable item each. Then create and bind the spec Task:
+   `relay_task_create { intent, issueRefs:["#<feature>"] }` →
+   `relay_plan_add_node { planId, node:{ id:"spec", label:"Slice spec", lane:"frame", refs:{ taskId:<spec> } } }`.
+   Record the fixed v1 bar and budget on this Task; spawn `software-design` on it.
+2. **Slice.** Create the build Task (normal landing Task) and the proof Task. The proof
+   Task must not land: `relay_task_create { intent:"Independent slice proof",
+   doneWhen:"delivered", dispatch:{ type:"review" }, context:"<proof command>; <instance>" }`.
+   Add both as nodes (lane `slice`, `refs:{ taskId }`) and edges `spec→build`, `build→proof`
+   (`relay_plan_add_edge { planId, from, to }`: `to` depends on `from`; edges between bound
+   nodes become Task dependencies). Spawn a `worker` on `build`; when its project delivery/deployment
+   gates pass, spawn `QA` on `proof`.
+3. **Gate.** The prover delivers the proof Task; that closes it `done` with no land attempt
+   because it is a delivered review Task. `relay_task_record_gate` alone does not finish it,
+   so its harden dependents stay on an open upstream.
+   - Pass: `relay_task_deliver { disposition:"complete", summary, gates:{ other:[{ name:"slice-proof", status:"pass", detail:"<command> @ <sha> on <instance>" }] } }`
+   - Fail: `relay_task_deliver { disposition:"failed", summary, reason:"<blocker>", gates:{ other:[{ name:"slice-proof", status:"fail", detail }] } }`
+
+   Fail → frame again (new spec revision, same plan). Pass → verify the proof Task is
+   `done` with `slice-proof: pass`, then record the stage on the spec Task:
+   `relay_task_memory_append_decision { taskId:<spec>, decision:"stage: harden" }`.
+4. **Harden.** Only now add harden nodes (lane `harden`, bound to their Tasks), each with
+   an edge `proof→<node>`, up to the budget. Each harden builder delivers normally and adds
+   the proof re-run: `relay_task_deliver { disposition:"complete", summary, commits,
+   idempotencyKey, gates:{ test:{ status:"pass" }, other:[{ name:"slice-proof", status:"pass" }] } }`.
+5. **Conformance.** When every node lands the plan reads `completion:"conformance-pending"`,
+   not done, and you get a `plan.conformance-pending` notice. Fetch, check each acceptance item
+   on the main tip (or spawn a fresh agent to audit it), then
+   `relay_plan_conformance { planId, mainSha:<origin/main tip>, items:[{ id, status:"met"|"unmet", note? }] }`.
+   A gap files one bound Task per unmet item and reopens the plan; repeat after they land.
+   Only a pass makes the plan `done`.
+6. **v1/closed.** Bar met → flag on, file "future" issues, record `stage: v1`;
+   after closure, record `stage: closed` and archive the plan.
+
+Before spawning a harden builder, read `relay_task_get { taskId:<harden>, verbose:true }`
+for `dependsOn`, then `relay_task_get { taskId:<proof>, verbose:true }`; require
+`status:"done"` and `slice-proof` with `status:"pass"`. Relay records dependencies;
+the coordinator enforces dispatch order. Validate with the project's own commands
+from its spawn brief/config; the proof is an additional gate.
+
+Check gate order any time with `relay_plan_get { planId, mode:"lean" }`: every
+`harden` node must have `proof` upstream, and no harden node may exist while the proof
+Task is not complete with a passing `slice-proof` gate.

package/plugins/codex/skills/status/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: status
+description: Show Humwick status for this session, including relay health, current agent id, label, tags, readiness, and active pair state. Use when the user invokes /status or asks for relay connection status.
+argument-hint: "[--json]"
+---
+
+# Humwick Status
+
+Run:
+
+```bash
+agent-relay /status $ARGUMENTS
+```
+
+Summarize the current relay connection, agent identity, label, tags, and active pair state.

package/plugins/codex/skills/tags/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: tags
+description: List or update Humwick tags for the current session. Use when the user invokes /tags or asks to set, add, remove, or inspect relay tags.
+argument-hint: "[TAG ...|--list|--add TAGS|--remove TAGS]"
+---
+
+# Humwick Tags
+
+Run:
+
+```bash
+agent-relay /tags $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /tags
+agent-relay /tags backend tests urgent
+agent-relay /tags --add backend,tests
+agent-relay /tags --remove urgent
+```
+
+Report the resulting tags briefly.

package/plugins/codex/skills/task/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: agent-relay-task
+description: Use Humwick Task tools to create, update, and document durable work records. Use when coordinating multi-step work or when your brief was spawned from a Task.
+---
+
+# Humwick Task
+
+Use Relay Task tools for durable work tracking instead of burying state in chat.
+
+Coordinators:
+
+- Create a Task before multi-step work with `relay_task_create`.
+- Set `intent`, `complexity`, and useful `context`; add `doneWhen`, `dispatch`, refs, or dependencies when they clarify routing.
+- Spawn workers from the Task so they inherit the Task context.
+
+Workers:
+
+- Use `relay_task_set_status` as work moves through `in_progress`, `blocked`, `done`, `failed`, or `canceled`.
+- Use `relay_task_memory_replace_working_state` for current progress a retry agent needs.
+- Use `relay_task_memory_append_decision` for durable choices and rationale.
+- Use `relay_task_memory_append_ruled_out` for dead ends, failed approaches, and why they were rejected.
+
+Useful reads and updates:
+
+- `relay_task_get` and `relay_task_history` inspect the Task and audit timeline.
+- `relay_task_update` refreshes intent, context, latest steer, doneWhen, complexity, or dispatch.
+- `relay_task_record_gate` records tests, typecheck, docs, smoke, and other quality gates.
+- `relay_task_dispatch` maps Task shape to a concrete spawn and launches it bound to the Task (shared spawn path). Idempotent retry needs a caller-supplied spawnRequestId, as with relay_spawn_agent.