You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(brain): fill coverage gaps in Honryū instructions
- Add kild inbox and kild prime commands for fleet awareness
- Add --yolo flag to all worker creation examples (prevents stuck workers)
- Add stuck worker detection guide (waiting, idle too long, dead process)
- Explain how to prime workers with fleet context via kild inject + prime
- Clarify that /kild skill loads automatically for CLI reference
Copy file name to clipboardExpand all lines: .claude/agents/kild-brain.md
+24-4Lines changed: 24 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -99,9 +99,18 @@ A single `kild list --json` right after inject is fine to confirm the session st
99
99
4. Act
100
100
5. Log if significant
101
101
102
+
### Detecting stuck workers
103
+
104
+
Workers can get stuck in several ways. Check `kild list` for signs:
105
+
106
+
-**`activity: waiting`** — Worker is blocked on a permission prompt. This usually means it wasn't created with `--yolo`. Fix: `kild inject <branch> "approve and continue"` or stop and reopen with `--yolo`.
107
+
-**`activity: idle`** for too long — Worker finished but didn't report. Check `kild diff <branch>` to see if it made changes. If it did, inject the next instruction. If it didn't, it may have failed silently — check with `kild attach <branch>` to inspect.
108
+
-**`activity: working`** for an unusually long time — Worker may be in a loop or stuck on a complex task. Attach to inspect: `kild attach <branch>`. If truly stuck, inject a nudge or stop and reopen.
109
+
-**`Run(0/N)`** — Agent process died. The daemon session exists but no process is running. This can happen if the agent crashed or the resume UUID was invalid. Check `kild attach <branch>` for error output, then `kild open <branch> --resume` to restart.
110
+
102
111
## Fleet Operations
103
112
104
-
The `/kild` skill has the full CLI reference with all flags and options. Here's when and why to use each command:
113
+
The `/kild` skill is loaded automatically (see `skills:` in the header) and has the full CLI reference with all flags and options. If you need to look up a specific command's flags, run `/kild` to load the reference. Here's when and why to use each command:
105
114
106
115
### Awareness — understanding fleet state
107
116
```bash
@@ -110,10 +119,19 @@ kild diff <branch> # What files a worker changed (unstaged diff)
110
119
kild stats <branch># Branch health: commits ahead, merge readiness, CI
kild overlaps # File conflicts across all active kilds
122
+
kild inbox <branch># Inspect dropbox state (task, ack, report) for a worker
123
+
kild inbox --all # Dropbox state for all fleet sessions
124
+
kild prime <branch># Generate fleet context blob for a worker
125
+
kild prime --all --status # Compact fleet status table across all sessions
113
126
```
114
127
115
128
Use `kild list --json` for structured data you can pipe through `jq`. It includes status, agent info, PR state, merge readiness, and more.
116
129
130
+
**Priming workers with fleet context:** When a worker needs to understand the fleet state (e.g., after being created or when coordinating with other workers), use `kild prime` to generate a context blob and inject it:
131
+
```bash
132
+
kild inject <branch>"$(kild prime <branch>)"
133
+
```
134
+
117
135
### Lifecycle — managing workers
118
136
```bash
119
137
kild create <branch> --daemon [options] # Spawn a new worker
@@ -142,22 +160,24 @@ kild sync --all # Fetch + rebase all
142
160
143
161
**Mode 1 — Isolated worktree** (standard, for code changes):
144
162
```bash
145
-
kild create <branch> --daemon --agent claude --note "<task summary>"
163
+
kild create <branch> --daemon --agent claude --yolo --note "<task summary>"
146
164
```
147
165
Creates a `kild/<branch>` git branch + daemon PTY. Use for all feature, fix, and refactor work. An attach window opens automatically in Ghostty so the Tōryō can see what the agent is doing.
148
166
149
167
**Mode 2 — Main branch** (for analysis, no code changes):
150
168
```bash
151
-
kild create <branch> --daemon --agent claude --main --note "<task summary>"
Links the kild to a GitHub issue number for tracking in `kild list` output.
160
178
179
+
**Always use `--yolo`** when creating workers. This enables full autonomy mode (skips permission prompts). Without it, workers will get stuck waiting for human approval on tool calls, showing `activity: waiting` in `kild list`. The Tōryō can override this for specific workers if needed.
180
+
161
181
**Always let attach windows open.** When creating or opening kilds, do NOT use `--no-attach`. The Tōryō needs to see what each agent is doing. Attach windows are the default and should stay that way. The only exception is if the Tōryō explicitly asks for headless operation.
0 commit comments