hotmilk 0.1.12 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/AGENTS.md +11 -13
  2. package/README.md +170 -37
  3. package/agents/README.md +16 -0
  4. package/agents/assistant.md +106 -0
  5. package/agents/coach.md +82 -0
  6. package/agents/coder.md +50 -0
  7. package/agents/designer.md +85 -0
  8. package/agents/planner.md +68 -0
  9. package/agents/reviewer.md +48 -0
  10. package/hotmilk.json +6 -0
  11. package/package.json +31 -26
  12. package/prompts/prompt-eval.md +241 -0
  13. package/prompts/tidy.md +3 -1
  14. package/prompts/translate.md +3 -1
  15. package/skills/make-docs/SKILL.md +43 -0
  16. package/skills/pioneer/SKILL.md +120 -130
  17. package/skills/pioneer/references/autoresearch-routing.md +112 -0
  18. package/skills/pioneer/references/chat-plan.md +50 -0
  19. package/skills/pioneer/references/goal-gate.md +54 -0
  20. package/skills/pioneer/references/graph-recon-gate.md +50 -0
  21. package/skills/pioneer/references/openspec-routing.md +50 -0
  22. package/skills/pioneer/references/plannotator-routing.md +81 -0
  23. package/skills/pioneer/references/prompt-eval-gate.md +38 -0
  24. package/skills/recommend-research/SKILL.md +94 -6
  25. package/skills/recommend-research/references/example-narrow.md +53 -0
  26. package/skills/recommend-research/references/scope-gate.md +46 -0
  27. package/skills/recommend-research/references/shortlist-gate.md +69 -0
  28. package/skills/recommend-research/references/verify-gate.md +73 -0
  29. package/skills/update-docs/SKILL.md +86 -0
  30. package/skills/update-docs/references/doc-inventory.md +69 -0
  31. package/skills/update-docs/references/drift-verification.md +59 -0
  32. package/src/bootstrap/extensions.ts +7 -1
  33. package/src/bootstrap/global-extension-sources.ts +10 -1
  34. package/src/bootstrap/project-trust.ts +41 -0
  35. package/src/bootstrap/session.ts +28 -1
  36. package/src/bootstrap/subagents-doctor.ts +109 -0
  37. package/src/config/bundled-extensions.ts +12 -0
  38. package/src/config/hotmilk.ts +22 -0
  39. package/src/config/resolve.ts +16 -0
  40. package/src/config/runtime.ts +4 -0
  41. package/src/index.ts +8 -0
  42. package/themes/monokai.json +1 -1
  43. package/skills/empirical-prompt-tuning/SKILL.md +0 -232
package/AGENTS.md CHANGED
@@ -13,27 +13,26 @@ User-facing setup: [README.md](README.md).
13
13
  | `bun run lint` | `vp lint` |
14
14
  | `bun run check` | lint + format + test |
15
15
 
16
- Requires **Node.js 22+**. Targets **Pi 0.78** (`@earendil-works/pi-coding-agent` peers).
16
+ Requires **Node.js 22+**. Targets **Pi 0.80** (`@earendil-works/pi-coding-agent` peers).
17
17
 
18
18
  ## Pi essentials
19
19
 
20
- - **Runtime**: [Pi](https://github.com/badlogic/pi-mono) with `@earendil-works/pi-coding-agent` — install hotmilk via `pi install npm:hotmilk`.
20
+ - **Runtime**: [Pi](https://pi.dev/docs) with `@earendil-works/pi-coding-agent` — install hotmilk via `pi install npm:hotmilk`.
21
21
  - **Single extension entry**: only `./src/index.ts` is listed under `package.json` → `pi.extensions`. All other bundled packages load via **dynamic `import()`** when their toggle is `true`.
22
22
  - **Config**: `~/.pi/agent/hotmilk.json` — change with `/mode`, apply with `/reload`.
23
+ - **Project trust (Pi 0.79+)**: `projectTrust` in `hotmilk.json`; handler in `src/bootstrap/project-trust.ts`. Bundled extension dedupe scans global settings only until trust (`includeProjectSettings: false` in `src/index.ts`).
23
24
  - **Do not** add packages to `pi.extensions` for toggled deps; add one row to `BUNDLED_EXTENSION_DEFINITIONS` in `src/config/bundled-extensions.ts`.
24
25
 
25
- Details: [docs/pi.md](docs/pi.md).
26
-
27
26
  ## Code layout
28
27
 
29
- | Path | Role |
30
- | -------------------------------- | ---------------------------------------------------------- |
31
- | `src/index.ts` | Extension entry: runtime, register handlers |
32
- | `src/config/` | `hotmilk.json` I/O, resolve, `createHotmilkRuntime()` |
33
- | `src/bootstrap/` | Bundled extension registration, session, graph, defaults |
34
- | `src/controller/` | `/mode`, `/stop`, `/interrupt` |
35
- | `src/ui/` | Footer, session logo |
36
- | `prompts/`, `skills/`, `themes/` | Shipped Pi assets (`pi.prompts`, `pi.skills`, `pi.themes`) |
28
+ | Path | Role |
29
+ | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
30
+ | `src/index.ts` | Extension entry: runtime, register handlers |
31
+ | `src/config/` | `hotmilk.json` I/O, resolve, `createHotmilkRuntime()` |
32
+ | `src/bootstrap/` | Bundled extension registration, session, graph, defaults |
33
+ | `src/controller/` | `/mode`, `/stop`, `/interrupt` |
34
+ | `src/ui/` | Footer, session logo |
35
+ | `prompts/`, `skills/`, `themes/` | Shipped Pi assets (`pi.prompts`, `pi.skills`, `pi.themes`); first-party skills live under `./skills/` only |
37
36
 
38
37
  ## Agent behavior
39
38
 
@@ -43,7 +42,6 @@ Merge with your global agent guidelines when present. For this repo:
43
42
  2. **Simplicity** — No speculative features; keep lazy loading (`extensions.ts`) intact.
44
43
  3. **Verify** — Run `bun test` (and `bun run lint` when changing TS or config).
45
44
  4. **Docs** — User-facing changes in `README.md`; update `hotmilk.json` when changing defaults (code reads it as the template).
46
- 5. **Pi/runtime** — See [docs/pi.md](docs/pi.md).
47
45
 
48
46
  ## More
49
47
 
package/README.md CHANGED
@@ -8,16 +8,17 @@ Use it when you want a practical engineering workstation without hand-picking a
8
8
 
9
9
  | Layer | Packages / assets |
10
10
  | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
- | **Orchestration** | [gentle-pi](https://www.npmjs.com/package/gentle-pi) (SDD, skill registry, `sdd-init`) |
11
+ | **Orchestration** | [gentle-pi](https://www.npmjs.com/package/gentle-pi) **≥0.4.1** (el Gentleman, SDD/OpenSpec sync, skill registry, `/gentle-ai:doctor`) |
12
12
  | **Context** | [context-mode](https://www.npmjs.com/package/context-mode) |
13
13
  | **Codebase graph** | [graphify-pi](https://www.npmjs.com/package/graphify-pi) |
14
14
  | **Subagents** | [pi-subagents](https://www.npmjs.com/package/pi-subagents), [pi-ask-user](https://www.npmjs.com/package/pi-ask-user) |
15
15
  | **Goals & docs** | [pi-goal](https://www.npmjs.com/package/pi-goal), [pi-docparser](https://www.npmjs.com/package/pi-docparser) |
16
- | **File-based planning** | [@tomxprime/planning-with-files](https://www.npmjs.com/package/@tomxprime/planning-with-files) |
16
+ | **File-based planning** | [@tomxprime/planning-with-files](https://www.npmjs.com/package/@tomxprime/planning-with-files), [@plannotator/pi-extension](https://www.npmjs.com/package/@plannotator/pi-extension) (browser plan approval) |
17
17
  | **Integrations** | [pi-mcp-adapter](https://www.npmjs.com/package/pi-mcp-adapter), [pi-btw](https://www.npmjs.com/package/pi-btw) (side channel — see below), [@haispeed/pi-obsidian](https://www.npmjs.com/package/@haispeed/pi-obsidian) |
18
18
  | **Dashboard** | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard) |
19
19
  | **Web tools** | [pi-web-access](https://www.npmjs.com/package/pi-web-access) |
20
20
  | **Flows** | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows) |
21
+ | **Experiment loops** | [pi-autoresearch](https://www.npmjs.com/package/pi-autoresearch) |
21
22
  | **Local assets** | `./prompts`, `./skills`, `./themes`, `mcp.json` template |
22
23
 
23
24
  Bundled extension **on/off** is controlled in `hotmilk.json` (via `/mode`), then `/reload`. Only `src/index.ts` is listed in `package.json` → `pi.extensions`; every other bundled package is loaded dynamically when its toggle is `true`.
@@ -50,14 +51,38 @@ pi install -l npm:hotmilk
50
51
  2. On first session, hotmilk creates `~/.pi/agent/hotmilk.json` if missing (defaults match the bundled template).
51
52
  3. After config changes, run `/reload`.
52
53
 
53
- ### Pi 0.78 and npm peers
54
+ ### Pi 0.80 and npm peers
54
55
 
55
- hotmilk targets **Pi 0.78** (`@earendil-works/pi-coding-agent` and peers). Several bundled dependencies still declare **0.74.x** peer ranges (`pi-simplify`, `pi-btw`, `pi-docparser`, `@blackbelt-technology/pi-flows`, and others). npm may report `ERESOLVE` until those packages publish 0.78-compatible peers.
56
+ hotmilk targets **Pi 0.80** (`@earendil-works/pi-coding-agent` and peers). Several bundled dependencies still declare **0.74.x** peer ranges (`pi-simplify`, `pi-btw`, `pi-docparser`, `@blackbelt-technology/pi-flows`, and others). npm may report `ERESOLVE` until those packages publish 0.80-compatible peers.
56
57
 
57
- This repo ships **`.npmrc`** with `legacy-peer-deps=true` so `npm install` and `npm ci` succeed. Copy from `.npmrc.example` if you clone without `.npmrc`. Treat upstream extensions as **best-effort on 0.78** until their maintainers widen peer ranges.
58
+ This repo ships **`.npmrc`** with `legacy-peer-deps=true` so `npm install` and `npm ci` succeed. Copy from `.npmrc.example` if you clone without `.npmrc`. Treat upstream extensions as **best-effort on 0.80** until their maintainers widen peer ranges.
58
59
 
59
60
  Heavy optional stacks (`agent-dashboard`, `pi-flows`) stay **off by default**; enable in `/mode` only when you need them and accept extra peer / startup cost.
60
61
 
62
+ ### Project trust (Pi 0.79+)
63
+
64
+ Pi gates project-local `.pi/` resources and `.agents/skills` behind **project trust** ([Pi docs](https://pi.dev/docs/latest/security#project-trust)). hotmilk registers a `project_trust` handler and, by default, defers to Pi's built-in prompt (`projectTrust.mode: "delegate"`).
65
+
66
+ Configure in `~/.pi/agent/hotmilk.json`:
67
+
68
+ ```json
69
+ {
70
+ "projectTrust": {
71
+ "mode": "delegate",
72
+ "remember": false
73
+ }
74
+ }
75
+ ```
76
+
77
+ | `mode` | Behavior |
78
+ | ---------- | ------------------------------------------------------------------------------ |
79
+ | `delegate` | Let Pi resolve trust (`trust.json`, `defaultProjectTrust`, or built-in prompt) |
80
+ | `prompt` | hotmilk confirm explaining what project trust enables |
81
+ | `always` | Trust project-local resources (optionally `remember: true`) |
82
+ | `never` | Decline project-local resources for this handler |
83
+
84
+ On startup, hotmilk scans only **global** Pi settings for bundled-extension dedupe. After trust, project `.pi/settings.json` duplicates are reported; run `/reload` to dedupe.
85
+
61
86
  ### Commands (hotmilk)
62
87
 
63
88
  | Command | Purpose |
@@ -66,7 +91,7 @@ Heavy optional stacks (`agent-dashboard`, `pi-flows`) stay **off by default**; e
66
91
  | `/stop` | Stop current running work |
67
92
  | `/interrupt <message>` | Steer in-flight work with an interrupt prompt |
68
93
 
69
- Upstream packages add their own commands (gentle-pi SDD, graphify, context-mode, planning-with-files `/plan-status`, and so on).
94
+ Upstream packages add their own commands (gentle-pi `/gentle-ai:status`, `/gentle-ai:doctor`, SDD chains, graphify, context-mode, planning-with-files `/plan-status`, plannotator `/plannotator`, and so on).
70
95
 
71
96
  ### Planning with files
72
97
 
@@ -78,6 +103,10 @@ Invoke when you want Manus-style on-disk planning:
78
103
 
79
104
  Or ask Pi to use the planning-with-files skill. The extension maintains `task_plan.md`, `findings.md`, and `progress.md`. Optional: `PWF_MODE=cache-safe` or `planningWithFiles.mode` in settings (see upstream README).
80
105
 
106
+ ### Plannotator (plan approval)
107
+
108
+ Enable `extensions.plannotator` in `/mode`, then `/reload`. Start plan mode with `/plannotator plans/<name>.md` or `pi --plan plans/<name>.md`. The agent drafts a checklist plan; you approve or annotate in the browser before execution. See upstream README for `plannotator.json` phase tuning. Default toggle is **off** (~37MB unpacked UI).
109
+
81
110
  ## Configuration
82
111
 
83
112
  ### `~/.pi/agent/hotmilk.json`
@@ -100,8 +129,10 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
100
129
  "rtk-optimizer": false,
101
130
  "mcp-adapter": false,
102
131
  "planning-with-files": false,
132
+ "plannotator": false,
103
133
  "caveman": false,
104
134
  "red-green": false,
135
+ "autoresearch": false,
105
136
  "agent-dashboard": false,
106
137
  "web-access": false,
107
138
  "pi-flows": false,
@@ -118,6 +149,10 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
118
149
  },
119
150
  "mcp": {
120
151
  "seedOnStart": false
152
+ },
153
+ "projectTrust": {
154
+ "mode": "delegate",
155
+ "remember": false
121
156
  }
122
157
  }
123
158
  ```
@@ -125,10 +160,14 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
125
160
  | Key / area | Behavior |
126
161
  | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
127
162
  | `extensions.*` | Set to `false` to skip registering that bundled extension |
128
- | `extensions.subagents` | Default `true`. Imports pi-subagents (~10s). Use with `gentle-ai` for delegation; set `false` for faster startup without Task tools |
163
+ | `extensions.gentle-ai` | Default `true`. gentle-pi **0.4.1+**: orchestration, lazy SDD preflight, OpenSpec sync/archive agents, `/gentle-ai:doctor` / `:status`. hotmilk keeps **startup-banner off** (figlet header instead) |
164
+ | `extensions.subagents` | Default `true`. Imports pi-subagents **0.28+** (~10s): acceptance gates, `timeoutMs`, resource limits. Use with `gentle-ai` for delegation; set `false` for faster startup without Task tools |
129
165
  | `extensions.btw` | Default `true`. Side conversation via `/btw` while main runs. **Delegate implementation to subagents**; use BTW for quick human questions. See [pi-btw coexistence](#pi-btw-with-subagents-default-on) |
130
166
  | `extensions.context-mode` | Default `true`. Prefer `ctx_*` for large outputs (see project context-window rules) |
131
167
  | `extensions.rtk-optimizer` | Default `false`. Bash/read/grep output compaction; enable with `context-mode` for leftover shell output. Install [`rtk` CLI](https://github.com/rtk-ai/rtk) for command rewrite (`/rtk verify`) |
168
+ | `extensions.planning-with-files` | Default `false`. Manus-style on-disk planning (`task_plan.md`, `findings.md`, `progress.md`) |
169
+ | `extensions.plannotator` | Default `false`. Browser plan approval gate (`/plannotator`, `--plan`); enable when human sign-off before execution |
170
+ | `extensions.autoresearch` | Default `false`. Autonomous optimize loop (`/autoresearch`, `.auto/`). See [pi-autoresearch coexistence](#pi-autoresearch-with-gentle-ai-default-off) |
132
171
  | `extensions.goal` … `mcp-adapter` | Integration / perf extensions (formerly always loaded via `pi.extensions`; now toggled like other bundled deps) |
133
172
  | Enabled extensions | Loaded **in parallel** on session start (faster than sequential import when many toggles are on) |
134
173
  | `graph.warnOnStale` | Notify when `graphify-out/needs_update` exists |
@@ -136,10 +175,89 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
136
175
  | `defaults.persona` | Seeds `.pi/gentle-ai/persona.json` when missing (`gentleman` \| `neutral`) |
137
176
  | `defaults.language` | Appends a project language hint to the system prompt each turn |
138
177
  | `mcp.seedOnStart` | Copy `mcp.json` template into `~/.pi/agent/mcp.json` when missing (empty template; for pi-mcp-adapter) |
178
+ | `projectTrust.mode` | Pi project trust: `delegate` (default), `prompt`, `always`, or `never` |
179
+ | `projectTrust.remember` | When `mode` is `always` or `never`, persist the decision in Pi `trust.json` |
139
180
  | `extensions.mcp-adapter` | Default `false`. Enable only when you want MCP servers from `~/.pi/agent/mcp.json` (do not duplicate context-mode) |
140
181
 
141
182
  **MCP (default):** `context-mode` extension registers `ctx_*` via its built-in bridge (same module as [upstream `.pi/extensions/context-mode`](https://github.com/mksglu/context-mode/tree/main/.pi/extensions/context-mode), loaded from `build/adapters/pi/extension.js`). Hotmilk removes any `context-mode` server from `~/.pi/agent/mcp.json` when the extension is on. Enable `mcp-adapter` only for **other** MCP servers—not a second context-mode entry.
142
183
 
184
+ ### Agents, skills, and scope
185
+
186
+ Pi resolves bundled assets at **user (global)**, **project**, and **package** layers. hotmilk ships package defaults; you override per machine or per repo.
187
+
188
+ | Layer | Config | Agents (pi-subagents) | Skills / prompts |
189
+ | ----------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
190
+ | **User (global)** | `~/.pi/agent/hotmilk.json`, `~/.pi/agent/settings.json` | `~/.pi/agent/agents/` or `~/.agents/` | User skill dirs indexed by gentle-pi `skill-registry` |
191
+ | **Project** | `.pi/settings.json` | **`.pi/agents/`** (canonical); legacy `.agents/` still read | `.pi/skills/`; legacy `.agents/skills/` |
192
+ | **Package** | `pi install npm:hotmilk` | **`agents/` in the npm tarball** — source of truth in git, **not** auto-discovered at runtime | `package.json` → `pi.skills`, `pi.prompts`, `pi.themes` (loaded when toggles/extensions are on) |
193
+
194
+ **Precedence (same runtime name):** project → user → builtin (pi-subagents built-ins). `/run`, chains, and the `subagent` tool default to `agentScope: "both"` (user + project + builtin).
195
+
196
+ **hotmilk subagents**
197
+
198
+ - **Edit in git / npm:** `agents/*.md` — package canonical prompts (`package: hotmilk` in frontmatter → runtime name `hotmilk.coach`, `hotmilk.planner`, …).
199
+ - **Pi discovery:** copy or symlink into **`.pi/agents/`** for the project you are working in. pi-subagents reads project and user dirs only; it does not scan the installed package’s `agents/` folder.
200
+ - **Parent vs child:** the main session runs gentle-ai orchestration (delegation, SDD, skill injection). Subagents get isolated prompts; the parent stays responsible for `/run`, acceptance blocks, and routing.
201
+
202
+ After changing prompts in this repo, sync the local project overlay (often untracked):
203
+
204
+ ```bash
205
+ cp agents/*.md .pi/agents/
206
+ ```
207
+
208
+ Verify with `/subagents-doctor` — expect `hotmilk.*` under project agents when `.pi/agents/` is populated.
209
+
210
+ See [agents/README.md](agents/README.md) for the role map (coach, planner, coder, reviewer, …).
211
+
212
+ ### Environment variables
213
+
214
+ Pi and bundled extensions read the process environment. hotmilk itself only defines **`HOTMILK_CONFIG_ROOT`**; everything else comes from Pi core or toggled bundled packages.
215
+
216
+ **Pi core** (always relevant; full list in [Pi usage — environment variables](https://pi.dev/docs/latest/usage#environment-variables)):
217
+
218
+ | Variable | Purpose |
219
+ | ----------------------------- | -------------------------------------------------------------------------------------------------------- |
220
+ | `PI_CODING_AGENT_DIR` | Override agent config dir (default `~/.pi/agent`). Affects `hotmilk.json`, auth, global agents, MCP path |
221
+ | `PI_CODING_AGENT_SESSION_DIR` | Override session storage (also `--session-dir`) |
222
+ | `PI_PACKAGE_DIR` | Override package dir (Nix/Guix store paths) |
223
+ | `PI_OFFLINE` | Disable startup network (update checks, package checks, install telemetry) |
224
+ | `PI_SKIP_VERSION_CHECK` | Skip `pi.dev` latest-version check only |
225
+ | `PI_TELEMETRY` | Opt in/out of install/update telemetry and provider attribution headers (`1`/`0`) |
226
+ | `PI_CACHE_RETENTION` | `long` for extended prompt cache where supported |
227
+ | `PI_TIMING` | `1` — emit timing diagnostics |
228
+ | `PI_HARDWARE_CURSOR` | `1` — show hardware cursor (IME / some terminals) |
229
+ | `PI_TUI_WRITE_LOG` | Path — log raw TUI ANSI to a file (debug) |
230
+ | `VISUAL`, `EDITOR` | External editor for Ctrl+G |
231
+
232
+ **LLM providers** (Pi `auth.json` → env fallback; not hotmilk-specific): common keys include `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY`, Azure (`AZURE_OPENAI_*`), Vertex (`GOOGLE_CLOUD_*`). See [@earendil-works/pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai) for the full provider table.
233
+
234
+ **hotmilk-owned**:
235
+
236
+ | Variable | Purpose |
237
+ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
238
+ | `HOTMILK_CONFIG_ROOT` | Override directory that contains `hotmilk.json` (default `~/.pi/agent`). Tests and sandboxes only; normal installs leave unset |
239
+
240
+ **Bundled extensions** (only when the matching `/mode` toggle is on):
241
+
242
+ | Variable | Toggle / package | Purpose |
243
+ | ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
244
+ | `PI_SUBAGENT_MAX_DEPTH` | `subagents` | Max nested subagent depth (default 2). Do not set `PI_SUBAGENT_DEPTH` manually |
245
+ | `PI_SUBAGENT_INHERIT_PROJECT_CONTEXT` | `subagents` | `0`/`false` — child skips project context inheritance |
246
+ | `PI_SUBAGENT_INHERIT_SKILLS` | `subagents` | `0`/`false` — child skips skill inheritance |
247
+ | `PI_DASHBOARD_PORT`, `PI_DASHBOARD_PI_PORT` | `agent-dashboard` | HTTP / bridge ports (hotmilk seeds **8102** when config still has upstream default `8000`) |
248
+ | `PI_DASHBOARD_ALLOW_MULTIPLE` | `agent-dashboard` | `1`/`true` — allow multiple dashboard processes |
249
+ | `PI_DASHBOARD_URL` | `agent-dashboard` | Bridge WebSocket URL (spawn sets this) |
250
+ | `PI_DASHBOARD_SPAWN_TOKEN` | `agent-dashboard` | Set by dashboard spawn; do not set by hand |
251
+ | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `graphify` (CLI) | Semantic extraction backend for `graphify extract` |
252
+ | `GRAPHIFY_GEMINI_MODEL`, `GRAPHIFY_WHISPER_MODEL` | `graphify` (CLI) | Override graphify LLM / Whisper model |
253
+ | `EXA_API_KEY`, `PERPLEXITY_API_KEY`, `GEMINI_API_KEY` | `web-access` | Search / fetch keys (`~/.pi/web-search.json` also) |
254
+ | `PI_ALLOW_BROWSER_COOKIES` | `web-access` | `1` — allow Chromium cookie extraction for Gemini Web |
255
+ | `CTX_FETCH_STRICT` | `context-mode` | `1` — stricter fetch routing in context-mode |
256
+
257
+ Internal `PI_SUBAGENT_*` spawn markers (`PI_SUBAGENT_CHILD`, `PI_SUBAGENT_RUN_ID`, …) are set by pi-subagents between parent and child processes — not user configuration.
258
+
259
+ **CI / publish** (this repo only): GitHub Actions uses secret **`NPM_TOKEN`**; `setup-node` maps it to **`NODE_AUTH_TOKEN`** for `npm publish`. Local `bun publish` uses `~/.npmrc`, not `NPM_TOKEN`.
260
+
143
261
  ### pi-btw with subagents (default on)
144
262
 
145
263
  Both **`subagents`** and **`btw`** default to **on**. They do not share commands or extension IDs; hotmilk loads them in parallel.
@@ -168,15 +286,42 @@ Set `"btw": false` in `/mode` if you want delegation only with no side channel.
168
286
 
169
287
  Enable in `/mode` or set the key to `true` in `hotmilk.json`, then `/reload`.
170
288
 
171
- | Toggle | Package | Notes |
172
- | ----------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
173
- | `caveman` | [pi-caveman](https://www.npmjs.com/package/pi-caveman) | Terse English (`/caveman`). Conflicts with `defaults.language: ja` |
174
- | `red-green` | [pi-red-green](https://www.npmjs.com/package/pi-red-green) | TDD via `/tdd`, `/tdd-status`. Config: `~/.pi/red-green/config.json` |
175
- | `agent-dashboard` | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard) | Warm-starts before the bridge loads (cold boot up to ~60s). Peers **0.74**; test on 0.78 before relying on it. Node.js ≥ 22.18 |
176
- | `web-access` | [pi-web-access](https://www.npmjs.com/package/pi-web-access) | `web_search`, fetch, GitHub clone, PDF/video. Optional keys: `~/.pi/web-search.json` |
177
- | `pi-flows` | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows) | YAML DAG workflows (`/flows`). Peers **0.74** + `@sinclair/typebox`; off by default on 0.78 stacks |
178
- | `kanagawa` | [pi-kanagawa](https://www.npmjs.com/package/pi-kanagawa) | Kanagawa theme (also in `/theme` via shipped assets), wave animation, `/thinking`. **Replaces hotmilk footer** when on |
179
- | `tetris` | [pi-tetris](https://www.npmjs.com/package/pi-tetris) | Play Tetris with `/tetris`. Lightweight; default off |
289
+ | Toggle | Package | Notes |
290
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
291
+ | `caveman` | [pi-caveman](https://www.npmjs.com/package/pi-caveman) | Terse English (`/caveman`). Conflicts with `defaults.language: ja` |
292
+ | `red-green` | [pi-red-green](https://www.npmjs.com/package/pi-red-green) | TDD via `/tdd`, `/tdd-status`. Config: `~/.pi/red-green/config.json` |
293
+ | `plannotator` | [@plannotator/pi-extension](https://www.npmjs.com/package/@plannotator/pi-extension) | Browser plan approval (`/plannotator`, `pi --plan`). Planning phase restricts writes to the plan file; Approve/Deny in browser before execution. Default off (~37MB UI). Phase tuning: `~/.pi/agent/plannotator.json`. See [Plannotator (plan approval)](#plannotator-plan-approval); pioneer routing: [`skills/pioneer/references/plannotator-routing.md`](skills/pioneer/references/plannotator-routing.md) |
294
+ | `autoresearch` | [pi-autoresearch](https://www.npmjs.com/package/pi-autoresearch) | Autonomous optimize loop (`/autoresearch`, `.auto/` session files). Skills: `autoresearch-create`, `autoresearch-finalize`, `autoresearch-hooks`. Default shortcut `Ctrl+Shift+F` — override in `~/.pi/agent/extensions/pi-autoresearch.json`. Off by default (dashboard widget + shortcuts). See [coexistence](#pi-autoresearch-with-gentle-ai-default-off) |
295
+ | `agent-dashboard` | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard) | Warm-starts before the bridge loads (cold boot up to ~60s). Peers **0.74**; test on 0.80 before relying on it. Node.js ≥ 22.18 |
296
+ | `web-access` | [pi-web-access](https://www.npmjs.com/package/pi-web-access) | `web_search`, fetch, GitHub clone, PDF/video. Optional keys: `~/.pi/web-search.json` |
297
+ | `pi-flows` | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows) | YAML DAG workflows (`/flows`). Peers **0.74** + `@sinclair/typebox`; off by default on 0.80 stacks |
298
+ | `kanagawa` | [pi-kanagawa](https://www.npmjs.com/package/pi-kanagawa) | Kanagawa theme (also in `/theme` via shipped assets), wave animation, `/thinking`. **Replaces hotmilk footer** when on |
299
+ | `tetris` | [pi-tetris](https://www.npmjs.com/package/pi-tetris) | Play Tetris with `/tetris`. Lightweight; default off |
300
+
301
+ ### pi-autoresearch with gentle-ai (default off)
302
+
303
+ `autoresearch` lives under the **Experiments** group in `/mode` (with `tetris`). Enable when the task is a **measure → edit → benchmark → keep/discard** loop, not feature delivery.
304
+
305
+ | Task shape | Prefer |
306
+ | ---------------------------------------------------------- | -------------------------------------------------------------------------- |
307
+ | Optimize metric (test time, bundle size, loss, Lighthouse) | `autoresearch: true` → `/skill:autoresearch-create` or `/autoresearch` |
308
+ | Feature, spec, cross-cutting, review >400 lines | `gentle-ai` + OpenSpec/SDD — keep `autoresearch` off |
309
+ | Human plan approval before writes | `plannotator` — not autoresearch as plan authority |
310
+ | Strict correctness-first test cycle | `red-green` (`/tdd`) — autoresearch only when optimizing the metric itself |
311
+
312
+ **Do not run SDD phases and an active autoresearch loop on the same task.** Stop the loop (`/autoresearch off`) before `/sdd-continue` or Plannotator approval work. Pioneer routing: [`skills/pioneer/references/autoresearch-routing.md`](skills/pioneer/references/autoresearch-routing.md).
313
+
314
+ **Shortcut conflicts:** default fullscreen dashboard is `Ctrl+Shift+F`. Override or disable in `~/.pi/agent/extensions/pi-autoresearch.json`:
315
+
316
+ ```json
317
+ {
318
+ "shortcuts": {
319
+ "fullscreenDashboard": "ctrl+shift+y"
320
+ }
321
+ }
322
+ ```
323
+
324
+ Use `null` for a shortcut key to skip registration.
180
325
 
181
326
  **Agent dashboard troubleshooting**
182
327
 
@@ -197,22 +342,9 @@ agent login
197
342
  # then in Pi: /model cursor/auto
198
343
  ```
199
344
 
200
- ### Migrating from `pi-ninja`
201
-
202
- The npm package was renamed from **pi-ninja** to **hotmilk**. User config lives at **`~/.pi/agent/hotmilk.json`**.
203
-
204
- | Before | After |
205
- | ------------------------- | -------------------------------------- |
206
- | `pi install npm:pi-ninja` | `pi install npm:hotmilk` |
207
- | Project `pi-ninja.json` | `~/.pi/agent/hotmilk.json` via `/mode` |
208
-
209
- Update `settings.json` packages from `npm:pi-ninja` to `npm:hotmilk`, then `/reload`.
210
-
211
- Older **tabako** users: replace `npm:tabako` with `npm:hotmilk`; let hotmilk seed `hotmilk.json` on first session.
212
-
213
345
  ## Development
214
346
 
215
- Requires **Node.js 22+** (or **Bun 1.3+**), **Bun** for installs in this repo, and Pi **0.78** peers in the environment.
347
+ Requires **Node.js 22+** (or **Bun 1.3+**), **Bun** for installs in this repo, and Pi **0.80** peers in the environment.
216
348
 
217
349
  ```bash
218
350
  bun install # commit bun.lock; peers resolved by Bun
@@ -256,13 +388,14 @@ npm publish --access public
256
388
 
257
389
  ### Layout
258
390
 
259
- | Path | Role |
260
- | -------------------------------- | ---------------------------------------------------------------------- |
261
- | `src/index.ts` | Extension entry: config, bundled extensions, session UI, input routing |
262
- | `src/config/hotmilk.ts` | `hotmilk.json` load / seed / save |
263
- | `prompts/`, `skills/`, `themes/` | Shipped with the package (`pi.prompts`, `pi.skills`, `pi.themes`) |
264
- | `mcp.json` | MCP server template for local projects |
265
- | `hotmilk.json` | Default toggle template (published in the npm package) |
391
+ | Path | Role |
392
+ | -------------------------------- | ------------------------------------------------------------------------------------------------- |
393
+ | `src/index.ts` | Extension entry: config, bundled extensions, session UI, input routing |
394
+ | `src/config/hotmilk.ts` | `hotmilk.json` load / seed / save |
395
+ | `agents/` | Package-canonical subagent prompts (`package: hotmilk`); install into `.pi/agents/` for discovery |
396
+ | `prompts/`, `skills/`, `themes/` | Shipped with the package (`pi.prompts`, `pi.skills`, `pi.themes`) |
397
+ | `mcp.json` | MCP server template for local projects |
398
+ | `hotmilk.json` | Default toggle template (published in the npm package) |
266
399
 
267
400
  ## License
268
401
 
package/agents/README.md ADDED
@@ -0,0 +1,16 @@
1
+ # agents/ (package canonical)
2
+
3
+ Targets **pi-subagents 0.28+** (acceptance gates, foreground `timeoutMs`, per-agent resource limits).
4
+
5
+ Markdown here is the **source of truth** in git and the npm tarball. Pi does not discover this folder directly — copy or symlink into **`.pi/agents/`** (project scope) or add overrides under **`~/.pi/agent/agents/`** (user scope). Scope rules and precedence: [README § Agents, skills, and scope](../README.md#agents-skills-and-scope).
6
+
7
+ | Agent | Role |
8
+ | --------- | ------------------------------------------------------------------- |
9
+ | coach | Teaching — concepts, tradeoffs, harness before code (`coaching.md`) |
10
+ | planner | Plans (bundled LUB / graphify / SDD gates) |
11
+ | coder | Single-writer implementation |
12
+ | reviewer | Fresh-context adversarial review |
13
+ | assistant | General routing parent |
14
+ | designer | UI / frontend specialist |
15
+
16
+ Shipped first-party skills: `./skills/` (`tcz-agent-converge`, `pioneer`, `recommend-research`). Shipped prompts: invoke as `/prompt-eval`, `/tidy`, `/translate` — not relative `prompts/` paths. Other skills come from bundled deps via `package.json` → `pi.skills`.
package/agents/assistant.md ADDED
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: assistant
3
+ description: General-purpose coding assistant for reading, writing, and reviewing code
4
+ tools: read, grep, find, ls, bash, edit, write, todo, subagent
5
+ model: cursor/auto
6
+ thinking: low
7
+ systemPromptMode: replace
8
+ inheritProjectContext: true
9
+ inheritSkills: true
10
+ output: false
11
+ maxSubagentDepth: 3
12
+ ---
13
+
14
+ You are a coding assistant. Prioritize clarity and accuracy over brevity. Be helpful by providing complete solutions, but keep explanations focused and avoid unnecessary verbosity.
15
+
16
+ ## Core Responsibilities
17
+
18
+ 1. **Code Understanding**: Analyze codebase structure and dependencies
19
+ 2. **Implementation**: Write clean, type-safe code following best practices
20
+ 3. **Review**: Identify issues with specific line references
21
+ 4. **Refactoring**: Suggest incremental improvements
22
+
23
+ ## Specialized Agent Routing
24
+
25
+ Project agents defined in this repo: `coach`, `planner`, `coder`, `reviewer`, `designer` (plus this `assistant`).
26
+
27
+ - Use `designer` for UI design and frontend styling work
28
+ - Use `coach` for concept-first teaching, tradeoff coaching, and "understand before implementing" (no product edits)
29
+ - Use `planner` for execution planning, phase design, and dependency sequencing
30
+ - Use `coder` for implementation, refactoring, debugging, and concrete code delivery
31
+ - Use `reviewer` for evidence-based diff review and PR readiness (`defaultContext: fresh`)
32
+ - Builtin fallback only when needed: `scout`, `worker`, `context-builder` (pi-subagents; not defined in this repo)
33
+ - Prefer project agents above for normal routing; project names override builtin when both exist (`planner`, `reviewer`).
34
+ - If a task matches multiple agents, route by primary outcome:
35
+ - `learn / explain / why` -> `coach`
36
+ - `plan / phases / dependencies` -> `planner`
37
+ - `code change` -> `coder`
38
+ - `review / PR / diff audit` -> `reviewer`
39
+ - `UI / styling` -> `designer`
40
+ - Deterministic routing order:
41
+ 1. If critical scope/constraints are missing, ask up to three targeted clarification questions; if the user wants immediate action, proceed with explicit assumptions.
42
+ 2. Identify the primary artifact (`code`, `plan`, `review`, `UI`, `learning`).
43
+ 3. Select one primary agent from the list above.
44
+ 4. Add at most one secondary agent only when the task explicitly requires a second artifact.
45
+ 5. If a third concern exists after selecting primary/secondary, do not add a tertiary agent; encode it as acceptance criteria in the handoff or a follow-up task.
46
+ 6. In the handoff note, write one-line rationale for primary/secondary choice.
47
+ 7. Multi-phase tasks (`implement then review`): `coder` then `reviewer`; label the phase in each response header.
48
+ - Common pairings:
49
+ - `understand then plan` -> primary `coach`, secondary `planner`
50
+ - `plan then implement` -> primary `planner`, secondary `coder`
51
+ - `implement then review` -> primary `coder`, secondary `reviewer`
52
+ - `UI then implement` -> primary `designer`, secondary `coder`
53
+
54
+ ## Routing Examples (3 Patterns)
55
+
56
+ 1. **Large feature kickoff (planning first)**
57
+ - User request: "Add cross-platform bootstrap flow for macOS/Ubuntu with rollback steps."
58
+ - Primary: `planner`, Secondary: `coach` (if tradeoffs unclear)
59
+ - Reason: Deliver a phased plan first; coach only when scope or constraints need alignment.
60
+
61
+ 2. **Implementation with verification**
62
+ - User request: "Fix shell init bug and add tests so it does not regress."
63
+ - Primary: `coder`, Secondary: `reviewer`
64
+ - Reason: Code change first; reviewer audits diff and test evidence before merge.
65
+
66
+ 3. **UI change in the Pi extension**
67
+ - User request: "Improve footer layout and wire it in src/ui."
68
+ - Primary: `designer`, Secondary: `coder`
69
+ - Reason: UI direction first; coder applies changes in `src/`.
70
+
71
+ ## Communication Style
72
+
73
+ - Direct and clear: State the solution first, then add brief context if needed
74
+ - Use code blocks with language tags and filenames
75
+ - Reference file locations: `[file:path] line:N-M`
76
+ - Keep diffs focused (≤5 lines per change)
77
+ - Exception: Large refactors may need multiple sequential diff blocks
78
+ - Exception: New files may exceed 5 lines; keep each logical unit ≤5 lines
79
+ - Balance: Provide complete working solutions (helpful), but avoid over-explaining obvious steps (direct)
80
+ - Reproducibility first: always include executed checks or explicit "not run" reason
81
+ - Independence first: do not rely on hidden memory; restate assumptions in handoff notes
82
+ - Output contract for code/task responses:
83
+ 1. Start with the solution/action first in one short line (target: <= 90 characters).
84
+ 2. Include location references for every changed file using `[file:path] line:N-M` (minimum one reference per file, using post-edit line ranges).
85
+ 3. When showing code, always use fenced blocks with language + filename in this exact form: ```ts:src/file.ts
86
+ 4. Diff chunk sizing rule: count changed lines only, target 5 lines per chunk, hard maximum 8 changed lines, then split into sequential chunks.
87
+ 5. If no code block is needed, still provide location references and a concise bullet list of concrete actions.
88
+ 6. Discovery-only replies (before edits): use one planned location reference with `line:1-1` and mark it as `planned`.
89
+ 7. Mode split:
90
+ - Edit mode (files changed): include per-file post-edit references and diff/code blocks.
91
+ - Review mode (no file changes): do not invent post-edit ranges; use analyzed ranges or `line:1-1 (planned)` and provide findings/actions only.
92
+ 8. Review completion criteria: each finding must include `evidence`, `impact`, and `action`; exploit-path validation can be static reasoning unless user explicitly requests a runnable PoC.
93
+
94
+ ## Code Standards
95
+
96
+ ```ts:src/example.ts
97
+ // Always include language tag and filename
98
+ // Reference specific lines for changes
99
+ ```
100
+
101
+ ### TypeScript Best Practices
102
+
103
+ - Enable strict mode; avoid `any` — use explicit types or `unknown` with type guards
104
+ - Prefer `readonly` for immutable data structures
105
+ - Use explicit return types on public functions for better documentation
106
+ - Handle errors explicitly; don't swallow exceptions with empty catch blocks
package/agents/coach.md ADDED
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: coach
3
+ description: Hotmilk teaching coach — concepts, tradeoffs, and harness discipline before code
4
+ tools: read, grep, find, ls, bash, write, intercom
5
+ thinking: high
6
+ systemPromptMode: replace
7
+ inheritProjectContext: true
8
+ inheritSkills: true
9
+ output: coaching.md
10
+ defaultContext: fork
11
+ package: hotmilk
12
+ ---
13
+
14
+ You are the **hotmilk** coaching subagent. Help the human **understand** the problem, constraints, and good next steps — **not** to ship code by default.
15
+
16
+ ## Role boundary
17
+
18
+ | Do | Do not |
19
+ | ------------------------------------------------------- | ---------------------------------------------------------------- |
20
+ | Explain concepts, tradeoffs, and failure modes | Edit product source (`src/`, bundled manifests, `hotmilk.json`) |
21
+ | Map options with pros/cons and verification hooks | Replace `planner` (no `plan.md` execution schedule unless asked) |
22
+ | Push back when scope or acceptance criteria are missing | Replace `coder` or `reviewer` |
23
+ | Point to harness skills and subagents when appropriate | Spawn subagents — parent orchestrates |
24
+
25
+ When the user clearly wants implementation, say so and recommend parent route to `planner` → `coder` with an **acceptance** block (pi-subagents 0.28+).
26
+
27
+ ## Hotmilk context
28
+
29
+ - **First-party skills** (`./skills/` only): teach when to load `tcz-agent-converge/`, `pioneer/`, or `recommend-research/` — not a separate index file. Teach `/prompt-eval` for prompt hardening after edits. Bundled `gentle-ai` covers delegate/SDD discipline.
30
+ - **Bundled surface**: `src/config/bundled-extensions.ts` + README Configuration — teach _why_ toggles and competition slots exist, do not add rows.
31
+ - **Architecture questions**: prefer `graphify-out/GRAPH_REPORT.md` or `graphify query` over reading many files when the graph exists.
32
+ - **Large / ambiguous work**: name when SDD preflight or tcz **LUB / V / θ** should run before diffs.
33
+ - **Pi project trust**: project `.pi/` and `.agents/skills` load only after trust; hotmilk `projectTrust` in `hotmilk.json` controls the handler. hotmilk peers target Pi **0.80**.
34
+
35
+ ## Coaching method
36
+
37
+ 1. Restate the goal in one sentence; list what is **known** vs **assumed**.
38
+ 2. Teach the **minimum** concept needed for the next decision (diagrams or short tables OK).
39
+ 3. Offer **2–3** options with tradeoffs and how each would be **verified** (`bun test`, doctor, graphify, Share_op, etc.).
40
+ 4. End with one **recommended next step** for the parent (e.g. `planner`, `scout`, `ask-user`, inline fix).
41
+
42
+ ## Working rules
43
+
44
+ - Read `context.md` and any parent handoff first; use `bash` read-only (`git status`, `git diff`, tests) for evidence.
45
+ - Ask up to **three** targeted questions when requirements are ambiguous — do not invent product decisions.
46
+ - Cite files as `[file:path] line:N-M` when referencing the repo.
47
+ - Write only `coaching.md` (and optional short notes the parent requested) — no `plan.md` unless the parent explicitly asked you to draft a plan _outline_ for handoff to `planner`.
48
+ - Match the user's language for explanations; keep identifiers, paths, and commands in English.
49
+
50
+ ## Output format (`coaching.md`)
51
+
52
+ ```markdown
53
+ # Coaching
54
+
55
+ ## Goal (restated)
56
+
57
+ …
58
+
59
+ ## What you need to understand
60
+
61
+ …
62
+
63
+ ## Options
64
+
65
+ | Option | Upside | Downside | How to verify |
66
+ | ------ | ------ | -------- | ------------- |
67
+
68
+ ## Recommendation
69
+
70
+ One next step for the parent session.
71
+
72
+ ## Suggested delegation
73
+
74
+ Primary: … | Secondary: … | Why: …
75
+ ```
76
+
77
+ ## Handoff hints
78
+
79
+ - **Concepts before a large feature** → coach → `planner` → `coder` → `reviewer`
80
+ - **"Why does X work?" / "What should I learn first?"** → coach only
81
+ - **Stuck after failed tests** → coach clarifies failure mode → `coder` with narrowed acceptance
82
+ - **Backlog / bundled / wiki mutex** → load tcz skill mentally; coach frames LUB, parent runs tcz if needed