Skip to content

Commit e73c399

Browse files
UsernameUsername
Username
authored and
Username
committed
docs(skills): make coding-agent completion parent-owned
1 parent 96dff27 commit e73c399

1 file changed

Lines changed: 56 additions & 87 deletions

File tree

‎skills/coding-agent/SKILL.md‎

Lines changed: 56 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: coding-agent
3-
description: 'Delegate coding tasks to Codex, Claude Code, OpenCode, or Pi agents via immediate background processes. Use when: (1) building or creating features/apps, (2) reviewing PRs in a temp clone/worktree, (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-line fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). All coding-agent runs start with background:true immediately. Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required. Completion notification must use openclaw message send, not system event/heartbeat.'
3+
description: 'Delegate coding tasks to Codex, Claude Code, OpenCode, or Pi agents via immediate background processes. Use when: (1) building or creating features/apps, (2) reviewing PRs in a temp clone/worktree, (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-line fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). All coding-agent runs start with background:true immediately. Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required. Parent assistant owns completion reporting: capture sessionId, use automatic completion wake/process logs, and report completion or failure itself.'
44
metadata:
55
{
66
"openclaw":
@@ -36,7 +36,7 @@ metadata:
3636

3737
Use **bash** with **background:true** for all coding-agent work.
3838
Do not use a foreground one-shot path here.
39-
Start the agent, get the `sessionId`, monitor with `process`, and require the worker to notify the user directly when it finishes.
39+
Start the agent, capture the returned `sessionId`, monitor with `process`, and report completion or failure yourself as the parent assistant.
4040

4141
## ⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no
4242

@@ -88,104 +88,71 @@ bash pty:true command:"claude --dangerously-skip-permissions 'task'"
8888

8989
Every coding-agent run follows this pattern:
9090

91-
1. Capture the notification route from the current conversation before spawning:
92-
- `notifyChannel`
93-
- `notifyTarget`
94-
- `notifyAccount` (if applicable)
95-
- `notifyReplyTo` (if replying to a specific message is desired)
96-
- `notifyThreadId` (Telegram topic / Slack thread when applicable)
97-
2. Start the coding CLI with `background:true` immediately.
98-
3. Include the notification route in the worker prompt and require the worker to call `openclaw message send` on completion.
99-
4. Monitor with `process action:log` / `poll`.
100-
5. If the worker needs input or fails before notifying, handle that explicitly yourself. Do not rely on heartbeat.
91+
1. Start the coding CLI with `background:true` immediately.
92+
2. Use the correct execution mode:
93+
- Codex/Pi/OpenCode: `pty:true`
94+
- Claude Code: `--print --permission-mode bypassPermissions` without PTY
95+
3. Capture the returned `sessionId` from the background process result.
96+
4. Tell the worker to print a clear final summary block to stdout (see template below), not to send external messages.
97+
5. Rely on automatic completion wake if available. When woken, or when the user asks for status, use `process action:log` / `poll` to inspect the session.
98+
6. Report completion or failure yourself from the parent assistant, using the worker's final summary and any relevant logs.
99+
7. If automatic completion wake is unavailable or unclear, create a watchdog/check-back (cron) when appropriate, or tell the user that completion requires manual checking.
101100

102-
If you do not have a trustworthy notification route, say so and do not claim that completion will notify the user automatically.
101+
Do not pass channel IDs, account IDs, reply targets, or other routing details into worker prompts unless the user explicitly asks the worker itself to interact externally.
102+
Do not require workers to use `openclaw message send` for completion; completion reporting belongs to the parent assistant.
103103

104104
---
105105

106-
## Notification Route
107-
108-
Do not rely on:
109-
110-
- `openclaw system event`
111-
- `tools.exec.notifyOnExit`
112-
- heartbeat delivery
113-
- `HEARTBEAT.md`
114-
115-
Use a direct outbound completion message instead:
116-
117-
```bash
118-
openclaw message send --channel <channel> --target '<target>' --message '<text>'
119-
```
120-
121-
Add optional routing flags only when they are real and applicable:
122-
123-
- `--account <id>`
124-
- `--reply-to <messageId>`
125-
- `--thread-id <threadId>`
126-
127-
`openclaw message send` is a direct outbound send. It does not depend on heartbeat being enabled.
106+
## Worker Final Summary Block
128107

129-
### Completion Prompt Snippet
130-
131-
Append something like this to every worker prompt:
108+
Append instructions like this to every worker prompt:
132109

133110
```text
134-
Notification route for completion:
135-
- channel: <notifyChannel>
136-
- target: <notifyTarget>
137-
- account: <notifyAccount or omit>
138-
- reply_to: <notifyReplyTo or omit>
139-
- thread_id: <notifyThreadId or omit>
140-
141-
When the task is completely finished, send exactly one completion message back to the user with openclaw message send using that route.
142-
If the task fails fatally, send exactly one failure message back to the user with openclaw message send using that route.
143-
Do not use openclaw system event. Do not rely on heartbeat. Do not skip the completion/failure message.
144-
```
145-
146-
### Completion Command Template
147-
148-
```bash
149-
openclaw message send \
150-
--channel <notifyChannel> \
151-
--target '<notifyTarget>' \
152-
--message 'Done: <brief summary>'
111+
When finished, print exactly one final result block to stdout using this format:
112+
113+
CODING_AGENT_RESULT_START
114+
status: success | failure | blocked
115+
summary: <brief human-readable summary>
116+
tests: <commands run and results, or "not run: <reason>">
117+
changed_files:
118+
- <path>: <brief change>
119+
blockers:
120+
- <blocker or "none">
121+
CODING_AGENT_RESULT_END
122+
123+
Do not send external messages or call notification tools unless explicitly requested.
153124
```
154125

155-
Optional additions:
156-
157-
```bash
158-
--account <notifyAccount> \
159-
--reply-to <notifyReplyTo> \
160-
--thread-id <notifyThreadId>
161-
```
126+
The parent assistant should read this block with `process action:log` and use it to compose the user-facing completion/failure report.
162127

163128
---
164129

165130
## Quick Start
166131

167-
For scratch Codex work, create a temp git repo first, then start the worker in the background with the completion route injected into the prompt:
132+
For scratch Codex work, create a temp git repo first, then start the worker in the background and capture the `sessionId`:
168133

169134
```bash
170135
SCRATCH=$(mktemp -d)
171136
cd "$SCRATCH" && git init
172137

173138
bash pty:true workdir:$SCRATCH background:true command:"codex exec 'Your prompt here.
174139
175-
Notification route for completion:
176-
- channel: <notifyChannel>
177-
- target: <notifyTarget>
178-
- account: <notifyAccount or omit>
179-
- reply_to: <notifyReplyTo or omit>
180-
- thread_id: <notifyThreadId or omit>
181-
182-
When the task is completely finished, send exactly one completion message back to the user with openclaw message send using that route.
183-
If the task fails fatally, send exactly one failure message back to the user with openclaw message send using that route.
184-
Do not use openclaw system event. Do not rely on heartbeat. Do not skip the completion/failure message.'"
140+
When finished, print exactly one final result block to stdout:
141+
CODING_AGENT_RESULT_START
142+
status: success | failure | blocked
143+
summary: <brief human-readable summary>
144+
tests: <commands run and results, or not run: reason>
145+
changed_files:
146+
- <path>: <brief change>
147+
blockers:
148+
- <blocker or none>
149+
CODING_AGENT_RESULT_END
150+
151+
Do not send external messages unless explicitly requested.'"
185152
```
186153

187154
Codex refuses to run outside a trusted git directory.
188-
Reuse this same notify-route injection block in every example below; only the task-specific prompt body should change.
155+
Reuse this same final-summary instruction block in every worker prompt; only the task-specific prompt body should change.
189156

190157
---
191158

@@ -282,8 +249,8 @@ bash pty:true workdir:~/project background:true command:"pi --provider openai --
282249
git worktree add -b fix/issue-78 /tmp/issue-78 main
283250
git worktree add -b fix/issue-99 /tmp/issue-99 main
284251

285-
bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push after review. Send the completion message with openclaw message send using the provided notify route.'"
286-
bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits. Send the completion message with openclaw message send using the provided notify route.'"
252+
bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push after review. Print the final CODING_AGENT_RESULT block to stdout.'"
253+
bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits. Print the final CODING_AGENT_RESULT block to stdout.'"
287254

288255
process action:list
289256
process action:log sessionId:XXX
@@ -306,22 +273,22 @@ process action:log sessionId:XXX
306273
7. **Parallel is OK** - run many Codex processes at once for batch work
307274
8. **NEVER start Codex inside your OpenClaw state directory** (`$OPENCLAW_STATE_DIR`, default `~/.openclaw`) - it'll read your soul docs and get weird ideas about the org chart!
308275
9. **NEVER checkout branches in ~/Projects/openclaw/** - that's the LIVE OpenClaw instance!
309-
10. **Always inject the Completion Prompt Snippet** into the worker prompt before spawning. The simplified examples below omit it for brevity — never spawn a worker without it.
276+
10. **Always include the final summary block instruction** in the worker prompt before spawning. The simplified examples below omit it for brevity — never spawn a worker without it.
310277

311278
---
312279

313280
## Progress Updates (Critical)
314281

315282
When you spawn a coding agent in the background, keep the user in the loop.
316283

317-
- Send 1 short message when you start: what is running and where.
284+
- Send 1 short message when you start: what is running, where it is running, and the captured `sessionId`.
318285
- Update only when something changes:
319286
- a milestone completes
320287
- the worker asks a question
321288
- you hit an error or need user action
322289
- the worker finishes
323290
- If you kill a session, immediately say you killed it and why.
324-
- If you are expecting the worker to self-notify with `openclaw message send`, say that clearly in your start update.
291+
- If automatic completion wake is unavailable or unclear, say whether you created a watchdog/check-back or whether the user must ask for a manual status check.
325292

326293
This prevents the user from seeing only a missing reply and having no idea what happened.
327294

@@ -338,11 +305,11 @@ This prevents the user from seeing only a missing reply and having no idea what
338305
3. **Respect tool choice.**
339306
- If the user asked for Codex, use Codex.
340307
- Orchestrator mode: do not hand-code the patch yourself instead of using the requested coding agent.
341-
4. **Capture notify routing before spawn.**
342-
- Completion messaging must have a real route.
343-
5. **Use direct completion messaging.**
344-
- Require `openclaw message send`.
345-
- Do not rely on `openclaw system event` or heartbeat.
308+
4. **Capture the `sessionId` before moving on.**
309+
- The parent assistant uses it for `process` log/poll checks and completion reporting.
310+
5. **Make workers report to stdout.**
311+
- Require a `CODING_AGENT_RESULT_START` / `CODING_AGENT_RESULT_END` final block.
312+
- Do not require or use `openclaw message send` for routine completion reporting.
346313
6. **Do not silently take over.**
347314
- If a worker fails or hangs, respawn it or ask for direction. Do not quietly switch to hand-editing.
348315
7. **Monitor with `process`.**
@@ -353,6 +320,8 @@ This prevents the user from seeing only a missing reply and having no idea what
353320
- Many background Codex sessions can run at once.
354321
10. **Never start Codex in `~/.openclaw/`.**
355322
11. **Never checkout branches in `~/Projects/openclaw/`.**
323+
12. **Keep routing out of worker prompts by default.**
324+
- Do not pass channel/account/reply IDs unless the user explicitly asks the worker to interact externally.
356325

357326
---
358327

@@ -362,4 +331,4 @@ This prevents the user from seeing only a missing reply and having no idea what
362331
- **Git repo required**: Codex needs a trusted git directory.
363332
- **Use `exec` under background orchestration**: short and long tasks follow the same path now.
364333
- **`submit` vs `write`**: use `submit` to send input plus Enter.
365-
- **Direct message send beats heartbeat for completion notification** when the user must be told immediately and heartbeat may be disabled.
334+
- **Parent-owned completion reporting beats worker self-notification** for routine coding-agent delegation: capture `sessionId`, inspect stdout/logs, and report the result yourself.

0 commit comments

Comments
 (0)