Teach future agents to delegate through the coder headlessly

1

---

2

name: coder-headless-delegation

3

description: Drive `openagents coder` headlessly from an agent session to delegate real coding work to child agents (Devin, Claude Code, Codex), then monitor, steer, and verify.

4

allowed-tools:

5

  - read

6

  - exec

7

  - grep

8

---

9

10

Use this skill when you need to delegate coding work through the OpenAgents

11

coder rather than doing it yourself or spawning your own subagents. The chain

12

is: you (headless client) → `openagents coder` (thread lane on the forge) →

13

its `delegate` tool → a child harness such as Devin. You stay in the

14

monitor/steer/verify role; the coder composes the child prompt, supervises the

15

child, and reviews its output; the child writes the code.

16

17

This was proven end to end on 2026-08-24 (Gym suite runner built by Devin

18

through the coder). Everything below is what that run taught.

19

20

## When to use it

21

22

- The user asks for coding work to be delegated "through the coder" or "to

23

  Devin" — this channel, not the Agent tool.

24

- You want the work recorded on the forge's thread plane (thread events,

25

  delegation receipts) instead of invisible subagent context.

26

27

Do not use it for Terminal-Bench or other benchmark tasks unless the user

28

explicitly says so. When the user says "delegate the coding work," they mean

29

real development tasks (scripts, features, plugins), not graded gym tasks.

30

31

## Launch recipe

32

33

The dev build lives in the monorepo. The `coder` shell function in

34

`~/.zshrc` builds and runs it; headless, call node directly:

35

36

```sh

37

SCRATCH=<your scratchpad>

38

cd <workspace the child should code in>          # cwd at launch = coder workspace

39

mkfifo $SCRATCH/coder-stdin 2>/dev/null || true

40

( tail -f $SCRATCH/coder-stdin | \

41

  OPENAGENTS_TOKEN=$(cat <token file>) \

42

  node /Users/christopherdavid/work/openagents/packages/openagents-cli/dist/main.js \

43

    coder --plain --dev > $SCRATCH/coder-session.log 2>&1 & )

44

```

45

46

- `--dev` selects the local profile (`http://localhost:4000`) and auto-starts

47

  the Phoenix dev server if it is not running. Without a local forge, drop

48

  `--dev` to talk to production.

49

- Build first if `dist/` may be stale: `pnpm build` in

50

  `packages/openagents-cli` (pnpm, never npm — the workspace uses `catalog:`

51

  versions).

52

- The token needs `chat:account` scope. Never print it; read it from a file.

53

- Use a clean git worktree as the workspace. Never launch from a checkout

54

  another session is using, and never rebase or reset the worktree while a

55

  child is working in it.

56

57

## Talking to it: `--plain` is line-oriented

58

59

**Every stdin line is a separate message.** A heredoc or multi-line brief

60

fragments into many messages, which confuses the coder and can trigger the

61

delegate tool more than once. Always send a brief as one physical line:

62

63

```sh

64

tr '\n' ' ' < brief.txt > brief-oneline.txt   # or compose it single-line

65

cat brief-oneline.txt > $SCRATCH/coder-stdin

66

```

67

68

Steering works the same way mid-turn: write another line into the FIFO and it

69

arrives as a steering message.

70

71

## Composing the delegation brief

72

73

Tell the coder, in one message:

74

75

1. **Delegate, don't do.** "Use your delegate tool with model `devin`,

76

   count 1. Do not write the code yourself."

77

2. **The child has zero context.** The prompt the coder passes must be fully

78

   self-contained: repository layout, existing files to read, exact

79

   requirements, examples, and acceptance checks. Spell these out in your

80

   brief so the coder can relay them.

81

3. **No git side effects.** "Tell the child not to commit or push." You

82

   commit yourself after verifying, via the owning repo's flow (forge remote,

83

   assure-repo artifacts for the monorepo).

84

4. **Review before reporting.** "When the child finishes, review its work

85

   with your shell tool (run `--help`, a dry-run, the tests) and report a

86

   verdict."

87

88

## Monitoring

89

90

- `tail`/`grep` `$SCRATCH/coder-session.log` for `[tool] delegate` and the

91

  coder's prose. Poll with an `until` loop in a background Bash rather than

92

  sleeping in the foreground.

93

- Child liveness: `pgrep -fl "devin -p"` (or the child harness's CLI name).

94

  The full child prompt is visible in the process args — a quick check that

95

  the coder relayed your requirements.

96

- **Verify exactly one child.** A fragmented brief can fire delegate twice.

97

- Delegation ledger: JSONL per child under

98

  `$TMPDIR/openagents-coder-delegations/`. Caution: that directory is shared

99

  by every coder on the machine, including other agent sessions' children.

100

  Match a ledger file to your child by the paths in its events, not by

101

  recency.

102

- Watch for the artifact itself (file existence) as the ground-truth signal;

103

  log patterns produce false positives.

104

105

## Failure modes seen in practice

106

107

- **Thread quota (422, "8 open threads maximum").** Killed or crashed coder

108

  processes leave threads open. Clean up: `GET /api/v3/threads`, then

109

  `DELETE /api/v3/threads/{id}` for each open one (bearer token). Lifecycle

110

  fix is tracked in openagents.com#209.

111

- **Dev-server hard 500s after config changes.** The Phoenix code reloader

112

  fails all requests if `config/*.exs` changed on disk; the server needs a

113

  restart. Also check for two beams fighting over port 4000.

114

- **Stale build.** The coder runs `dist/main.js`; a source edit does nothing

115

  until `pnpm build`.

116

117

## Verification stance

118

119

The coder's verdict is input, not proof. After it reports, run the artifact

120

yourself (help text, dry-run, tests) in the worktree, then commit and push

121

through the owning repo's normal flow. Report the child's work, the coder's

122

review, and your own check separately.

123

124

## Known gaps worth filing or fixing

125

126

- No single-shot flag (`--prompt-file` / `-p`) for `coder --plain`; the FIFO

127

  dance stands in for it.

128

- Delegation ledgers carry no owning-session marker, so attribution requires

129

  reading event paths.

Commit

Teach future agents to delegate through the coder headlessly

Deploy story

Changed files

Diff

1	+	`---`
2	+	`name: coder-headless-delegation`
3	+	description: Drive `openagents coder` headlessly from an agent session to delegate real coding work to child agents (Devin, Claude Code, Codex), then monitor, steer, and verify.
4	+	`allowed-tools:`
5	+	`- read`
6	+	`- exec`
7	+	`- grep`
8	+	`---`
9	+
10	+	`Use this skill when you need to delegate coding work through the OpenAgents`
11	+	`coder rather than doing it yourself or spawning your own subagents. The chain`
12	+	is: you (headless client) → `openagents coder` (thread lane on the forge) →
13	+	its `delegate` tool → a child harness such as Devin. You stay in the
14	+	`monitor/steer/verify role; the coder composes the child prompt, supervises the`
15	+	`child, and reviews its output; the child writes the code.`
16	+
17	+	`This was proven end to end on 2026-08-24 (Gym suite runner built by Devin`
18	+	`through the coder). Everything below is what that run taught.`
19	+
20	+	`## When to use it`
21	+
22	+	`- The user asks for coding work to be delegated "through the coder" or "to`
23	+	`Devin" — this channel, not the Agent tool.`
24	+	`- You want the work recorded on the forge's thread plane (thread events,`
25	+	`delegation receipts) instead of invisible subagent context.`
26	+
27	+	`Do not use it for Terminal-Bench or other benchmark tasks unless the user`
28	+	`explicitly says so. When the user says "delegate the coding work," they mean`
29	+	`real development tasks (scripts, features, plugins), not graded gym tasks.`
30	+
31	+	`## Launch recipe`
32	+
33	+	The dev build lives in the monorepo. The `coder` shell function in
34	+	`~/.zshrc` builds and runs it; headless, call node directly:
35	+
36	+	```sh
37	+	`SCRATCH=<your scratchpad>`
38	+	`cd <workspace the child should code in> # cwd at launch = coder workspace`
39	+	`mkfifo $SCRATCH/coder-stdin 2>/dev/null \|\| true`
40	+	`( tail -f $SCRATCH/coder-stdin \| \`
41	+	`OPENAGENTS_TOKEN=$(cat <token file>) \`
42	+	`node /Users/christopherdavid/work/openagents/packages/openagents-cli/dist/main.js \`
43	+	`coder --plain --dev > $SCRATCH/coder-session.log 2>&1 & )`
44	+	```
45	+
46	+	- `--dev` selects the local profile (`http://localhost:4000`) and auto-starts
47	+	`the Phoenix dev server if it is not running. Without a local forge, drop`
48	+	`--dev` to talk to production.
49	+	- Build first if `dist/` may be stale: `pnpm build` in
50	+	`packages/openagents-cli` (pnpm, never npm — the workspace uses `catalog:`
51	+	`versions).`
52	+	- The token needs `chat:account` scope. Never print it; read it from a file.
53	+	`- Use a clean git worktree as the workspace. Never launch from a checkout`
54	+	`another session is using, and never rebase or reset the worktree while a`
55	+	`child is working in it.`
56	+
57	+	## Talking to it: `--plain` is line-oriented
58	+
59	+	`Every stdin line is a separate message. A heredoc or multi-line brief`
60	+	`fragments into many messages, which confuses the coder and can trigger the`
61	+	`delegate tool more than once. Always send a brief as one physical line:`
62	+
63	+	```sh
64	+	`tr '\n' ' ' < brief.txt > brief-oneline.txt # or compose it single-line`
65	+	`cat brief-oneline.txt > $SCRATCH/coder-stdin`
66	+	```
67	+
68	+	`Steering works the same way mid-turn: write another line into the FIFO and it`
69	+	`arrives as a steering message.`
70	+
71	+	`## Composing the delegation brief`
72	+
73	+	`Tell the coder, in one message:`
74	+
75	+	1. Delegate, don't do. "Use your delegate tool with model `devin`,
76	+	`count 1. Do not write the code yourself."`
77	+	`2. The child has zero context. The prompt the coder passes must be fully`
78	+	`self-contained: repository layout, existing files to read, exact`
79	+	`requirements, examples, and acceptance checks. Spell these out in your`
80	+	`brief so the coder can relay them.`
81	+	`3. No git side effects. "Tell the child not to commit or push." You`
82	+	`commit yourself after verifying, via the owning repo's flow (forge remote,`
83	+	`assure-repo artifacts for the monorepo).`
84	+	`4. Review before reporting. "When the child finishes, review its work`
85	+	with your shell tool (run `--help`, a dry-run, the tests) and report a
86	+	`verdict."`
87	+
88	+	`## Monitoring`
89	+
90	+	- `tail`/`grep` `$SCRATCH/coder-session.log` for `[tool] delegate` and the
91	+	coder's prose. Poll with an `until` loop in a background Bash rather than
92	+	`sleeping in the foreground.`
93	+	- Child liveness: `pgrep -fl "devin -p"` (or the child harness's CLI name).
94	+	`The full child prompt is visible in the process args — a quick check that`
95	+	`the coder relayed your requirements.`
96	+	`- Verify exactly one child. A fragmented brief can fire delegate twice.`
97	+	`- Delegation ledger: JSONL per child under`
98	+	`$TMPDIR/openagents-coder-delegations/`. Caution: that directory is shared
99	+	`by every coder on the machine, including other agent sessions' children.`
100	+	`Match a ledger file to your child by the paths in its events, not by`
101	+	`recency.`
102	+	`- Watch for the artifact itself (file existence) as the ground-truth signal;`
103	+	`log patterns produce false positives.`
104	+
105	+	`## Failure modes seen in practice`
106	+
107	+	`- Thread quota (422, "8 open threads maximum"). Killed or crashed coder`
108	+	processes leave threads open. Clean up: `GET /api/v3/threads`, then
109	+	`DELETE /api/v3/threads/{id}` for each open one (bearer token). Lifecycle
110	+	`fix is tracked in openagents.com#209.`
111	+	`- Dev-server hard 500s after config changes. The Phoenix code reloader`
112	+	fails all requests if `config/*.exs` changed on disk; the server needs a
113	+	`restart. Also check for two beams fighting over port 4000.`
114	+	- Stale build. The coder runs `dist/main.js`; a source edit does nothing
115	+	until `pnpm build`.
116	+
117	+	`## Verification stance`
118	+
119	+	`The coder's verdict is input, not proof. After it reports, run the artifact`
120	+	`yourself (help text, dry-run, tests) in the worktree, then commit and push`
121	+	`through the owning repo's normal flow. Report the child's work, the coder's`
122	+	`review, and your own check separately.`
123	+
124	+	`## Known gaps worth filing or fixing`
125	+
126	+	- No single-shot flag (`--prompt-file` / `-p`) for `coder --plain`; the FIFO
127	+	`dance stands in for it.`
128	+	`- Delegation ledgers carry no owning-session marker, so attribution requires`
129	+	`reading event paths.`