Skip to content

Commit 264bf7c

Browse files
committed
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
1 parent cac4700 commit 264bf7c

1 file changed

Lines changed: 24 additions & 4 deletions

File tree

.claude/agents/kild-brain.md

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -99,9 +99,18 @@ A single `kild list --json` right after inject is fine to confirm the session st
9999
4. Act
100100
5. Log if significant
101101

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+
102111
## Fleet Operations
103112

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:
105114

106115
### Awareness — understanding fleet state
107116
```bash
@@ -110,10 +119,19 @@ kild diff <branch> # What files a worker changed (unstaged diff)
110119
kild stats <branch> # Branch health: commits ahead, merge readiness, CI
111120
kild pr <branch> # PR status: state, reviews, checks
112121
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
113126
```
114127

115128
Use `kild list --json` for structured data you can pipe through `jq`. It includes status, agent info, PR state, merge readiness, and more.
116129

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+
117135
### Lifecycle — managing workers
118136
```bash
119137
kild create <branch> --daemon [options] # Spawn a new worker
@@ -142,22 +160,24 @@ kild sync --all # Fetch + rebase all
142160

143161
**Mode 1 — Isolated worktree** (standard, for code changes):
144162
```bash
145-
kild create <branch> --daemon --agent claude --note "<task summary>"
163+
kild create <branch> --daemon --agent claude --yolo --note "<task summary>"
146164
```
147165
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.
148166

149167
**Mode 2 — Main branch** (for analysis, no code changes):
150168
```bash
151-
kild create <branch> --daemon --agent claude --main --note "<task summary>"
169+
kild create <branch> --daemon --agent claude --main --yolo --note "<task summary>"
152170
```
153171
Runs from the project root on the main branch. No worktree. Use for background analysis, script runners, tooling.
154172

155173
**Mode 3 — With issue tracking**:
156174
```bash
157-
kild create <branch> --daemon --agent claude --issue <N> --note "<title>"
175+
kild create <branch> --daemon --agent claude --yolo --issue <N> --note "<title>"
158176
```
159177
Links the kild to a GitHub issue number for tracking in `kild list` output.
160178

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+
161181
**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.
162182

163183
## Wave Planning

0 commit comments

Comments
 (0)