hotmilk 0.1.13 → 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.
- package/AGENTS.md +3 -2
- package/README.md +167 -22
- package/agents/README.md +3 -3
- package/agents/coach.md +2 -1
- package/agents/planner.md +2 -2
- package/hotmilk.json +6 -0
- package/package.json +25 -22
- package/prompts/prompt-eval.md +241 -0
- package/prompts/tidy.md +3 -1
- package/prompts/translate.md +3 -1
- package/skills/make-docs/SKILL.md +43 -0
- package/skills/pioneer/SKILL.md +120 -130
- package/skills/pioneer/references/autoresearch-routing.md +112 -0
- package/skills/pioneer/references/chat-plan.md +50 -0
- package/skills/pioneer/references/goal-gate.md +54 -0
- package/skills/pioneer/references/graph-recon-gate.md +50 -0
- package/skills/pioneer/references/openspec-routing.md +50 -0
- package/skills/pioneer/references/plannotator-routing.md +81 -0
- package/skills/pioneer/references/prompt-eval-gate.md +38 -0
- package/skills/recommend-research/SKILL.md +94 -6
- package/skills/recommend-research/references/example-narrow.md +53 -0
- package/skills/recommend-research/references/scope-gate.md +46 -0
- package/skills/recommend-research/references/shortlist-gate.md +69 -0
- package/skills/recommend-research/references/verify-gate.md +73 -0
- package/skills/update-docs/SKILL.md +86 -0
- package/skills/update-docs/references/doc-inventory.md +69 -0
- package/skills/update-docs/references/drift-verification.md +59 -0
- package/src/bootstrap/extensions.ts +7 -1
- package/src/bootstrap/global-extension-sources.ts +10 -1
- package/src/bootstrap/project-trust.ts +41 -0
- package/src/bootstrap/session.ts +28 -1
- package/src/config/bundled-extensions.ts +12 -0
- package/src/config/hotmilk.ts +22 -0
- package/src/config/resolve.ts +16 -0
- package/src/config/runtime.ts +4 -0
- package/src/index.ts +4 -0
- package/themes/monokai.json +1 -1
- package/skills/empirical-prompt-tuning/SKILL.md +0 -232
package/AGENTS.md
CHANGED
|
@@ -13,13 +13,14 @@ 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.
|
|
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://
|
|
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
26
|
## Code layout
|
package/README.md
CHANGED
|
@@ -13,11 +13,12 @@ Use it when you want a practical engineering workstation without hand-picking a
|
|
|
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.
|
|
54
|
+
### Pi 0.80 and npm peers
|
|
54
55
|
|
|
55
|
-
hotmilk targets **Pi 0.
|
|
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.
|
|
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 `/gentle-ai:status`, `/gentle-ai:doctor`, SDD chains, 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
|
```
|
|
@@ -130,6 +165,9 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
|
|
|
130
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) |
|
|
131
166
|
| `extensions.context-mode` | Default `true`. Prefer `ctx_*` for large outputs (see project context-window rules) |
|
|
132
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) |
|
|
133
171
|
| `extensions.goal` … `mcp-adapter` | Integration / perf extensions (formerly always loaded via `pi.extensions`; now toggled like other bundled deps) |
|
|
134
172
|
| Enabled extensions | Loaded **in parallel** on session start (faster than sequential import when many toggles are on) |
|
|
135
173
|
| `graph.warnOnStale` | Notify when `graphify-out/needs_update` exists |
|
|
@@ -137,10 +175,89 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
|
|
|
137
175
|
| `defaults.persona` | Seeds `.pi/gentle-ai/persona.json` when missing (`gentleman` \| `neutral`) |
|
|
138
176
|
| `defaults.language` | Appends a project language hint to the system prompt each turn |
|
|
139
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` |
|
|
140
180
|
| `extensions.mcp-adapter` | Default `false`. Enable only when you want MCP servers from `~/.pi/agent/mcp.json` (do not duplicate context-mode) |
|
|
141
181
|
|
|
142
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.
|
|
143
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
|
+
|
|
144
261
|
### pi-btw with subagents (default on)
|
|
145
262
|
|
|
146
263
|
Both **`subagents`** and **`btw`** default to **on**. They do not share commands or extension IDs; hotmilk loads them in parallel.
|
|
@@ -169,15 +286,42 @@ Set `"btw": false` in `/mode` if you want delegation only with no side channel.
|
|
|
169
286
|
|
|
170
287
|
Enable in `/mode` or set the key to `true` in `hotmilk.json`, then `/reload`.
|
|
171
288
|
|
|
172
|
-
| Toggle | Package | Notes
|
|
173
|
-
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
174
|
-
| `caveman` | [pi-caveman](https://www.npmjs.com/package/pi-caveman) | Terse English (`/caveman`). Conflicts with `defaults.language: ja`
|
|
175
|
-
| `red-green` | [pi-red-green](https://www.npmjs.com/package/pi-red-green) | TDD via `/tdd`, `/tdd-status`. Config: `~/.pi/red-green/config.json`
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
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.
|
|
181
325
|
|
|
182
326
|
**Agent dashboard troubleshooting**
|
|
183
327
|
|
|
@@ -200,7 +344,7 @@ agent login
|
|
|
200
344
|
|
|
201
345
|
## Development
|
|
202
346
|
|
|
203
|
-
Requires **Node.js 22+** (or **Bun 1.3+**), **Bun** for installs in this repo, and Pi **0.
|
|
347
|
+
Requires **Node.js 22+** (or **Bun 1.3+**), **Bun** for installs in this repo, and Pi **0.80** peers in the environment.
|
|
204
348
|
|
|
205
349
|
```bash
|
|
206
350
|
bun install # commit bun.lock; peers resolved by Bun
|
|
@@ -244,13 +388,14 @@ npm publish --access public
|
|
|
244
388
|
|
|
245
389
|
### Layout
|
|
246
390
|
|
|
247
|
-
| Path | Role
|
|
248
|
-
| -------------------------------- |
|
|
249
|
-
| `src/index.ts` | Extension entry: config, bundled extensions, session UI, input routing
|
|
250
|
-
| `src/config/hotmilk.ts` | `hotmilk.json` load / seed / save
|
|
251
|
-
| `
|
|
252
|
-
| `
|
|
253
|
-
| `
|
|
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) |
|
|
254
399
|
|
|
255
400
|
## License
|
|
256
401
|
|
package/agents/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# agents/ (
|
|
1
|
+
# agents/ (package canonical)
|
|
2
2
|
|
|
3
3
|
Targets **pi-subagents 0.28+** (acceptance gates, foreground `timeoutMs`, per-agent resource limits).
|
|
4
4
|
|
|
5
|
-
Markdown here
|
|
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
6
|
|
|
7
7
|
| Agent | Role |
|
|
8
8
|
| --------- | ------------------------------------------------------------------- |
|
|
@@ -13,4 +13,4 @@ Markdown here mirrors the hotmilk subagent prompts shipped for optional project
|
|
|
13
13
|
| assistant | General routing parent |
|
|
14
14
|
| designer | UI / frontend specialist |
|
|
15
15
|
|
|
16
|
-
Shipped first-party skills: `./skills/` (`tcz-agent-converge`, `pioneer`, `recommend-research
|
|
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/coach.md
CHANGED
|
@@ -26,10 +26,11 @@ When the user clearly wants implementation, say so and recommend parent route to
|
|
|
26
26
|
|
|
27
27
|
## Hotmilk context
|
|
28
28
|
|
|
29
|
-
- **First-party skills** (`./skills/` only): teach when to load `tcz-agent-converge/`, `pioneer/`, `recommend-research
|
|
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
30
|
- **Bundled surface**: `src/config/bundled-extensions.ts` + README Configuration — teach _why_ toggles and competition slots exist, do not add rows.
|
|
31
31
|
- **Architecture questions**: prefer `graphify-out/GRAPH_REPORT.md` or `graphify query` over reading many files when the graph exists.
|
|
32
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**.
|
|
33
34
|
|
|
34
35
|
## Coaching method
|
|
35
36
|
|
package/agents/planner.md
CHANGED
|
@@ -17,7 +17,7 @@ You are the **hotmilk** planning subagent. Turn requirements and code context in
|
|
|
17
17
|
## Hotmilk context
|
|
18
18
|
|
|
19
19
|
- **Bundled extensions**: `src/config/bundled-extensions.ts` + `~/.pi/agent/hotmilk.json` toggles + README Configuration. New bundled rows need manifest + README alignment; respect **competition slots** (e.g. one graph-wiki strategy).
|
|
20
|
-
- **First-party skills** (`./skills/` only): `tcz-agent-converge/` before large integration bets; `pioneer/` before multi-step plans; `recommend-research/` for stack picks
|
|
20
|
+
- **First-party skills** (`./skills/` only): `tcz-agent-converge/` before large integration bets; `pioneer/` before multi-step plans; `recommend-research/` for stack picks. After prompt/skill edits, run `/prompt-eval <path>`. Orchestration from bundled gentle-pi (`gentle-ai`) when SDD/TDD applies.
|
|
21
21
|
- **Architecture questions**: prefer `graphify-out/GRAPH_REPORT.md` or `graphify query` before reading 4+ raw files when the graph exists.
|
|
22
22
|
- **Large / cross-cutting work**: note whether SDD (OpenSpec) or tcz LUB/V/θ pre-flight is needed before implementation.
|
|
23
23
|
|
|
@@ -26,7 +26,7 @@ You are the **hotmilk** planning subagent. Turn requirements and code context in
|
|
|
26
26
|
- Read supplied `context.md` and any scout handoff first.
|
|
27
27
|
- Name exact files, ordered tasks, acceptance checks (`bun test`, `bun run check` when TS changes).
|
|
28
28
|
- Surface ambiguity in the plan — do not guess product or manifest decisions.
|
|
29
|
-
- Call out risks:
|
|
29
|
+
- Call out risks: Pi 0.80 peer alignment, project trust gates (`.pi/` / `.agents/skills`), lazy extension load, reviewer load (>400 lines → chained PR).
|
|
30
30
|
|
|
31
31
|
## Output format (`plan.md`)
|
|
32
32
|
|
package/hotmilk.json
CHANGED
|
@@ -15,8 +15,10 @@
|
|
|
15
15
|
"rtk-optimizer": false,
|
|
16
16
|
"mcp-adapter": false,
|
|
17
17
|
"planning-with-files": false,
|
|
18
|
+
"plannotator": false,
|
|
18
19
|
"caveman": false,
|
|
19
20
|
"red-green": false,
|
|
21
|
+
"autoresearch": false,
|
|
20
22
|
"agent-dashboard": false,
|
|
21
23
|
"web-access": false,
|
|
22
24
|
"pi-flows": false,
|
|
@@ -32,5 +34,9 @@
|
|
|
32
34
|
},
|
|
33
35
|
"mcp": {
|
|
34
36
|
"seedOnStart": false
|
|
37
|
+
},
|
|
38
|
+
"projectTrust": {
|
|
39
|
+
"mode": "delegate",
|
|
40
|
+
"remember": false
|
|
35
41
|
}
|
|
36
42
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hotmilk",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.14",
|
|
4
4
|
"description": "hotmilk — Pi package bundling gentle-pi, context-mode, graphify, subagents, and bundled extension toggles via hotmilk.json",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"hotmilk",
|
|
@@ -38,41 +38,43 @@
|
|
|
38
38
|
},
|
|
39
39
|
"dependencies": {
|
|
40
40
|
"@blackbelt-technology/pi-agent-dashboard": "^0.5.4",
|
|
41
|
-
"@blackbelt-technology/pi-flows": "^0.2.
|
|
41
|
+
"@blackbelt-technology/pi-flows": "^0.2.4",
|
|
42
42
|
"@haispeed/pi-obsidian": "^0.1.1",
|
|
43
|
+
"@plannotator/pi-extension": "^0.21.2",
|
|
43
44
|
"@tomxprime/planning-with-files": "^1.1.0",
|
|
44
|
-
"context-mode": "^1.0.
|
|
45
|
-
"gentle-pi": "^0.
|
|
45
|
+
"context-mode": "^1.0.168",
|
|
46
|
+
"gentle-pi": "^0.10.2",
|
|
46
47
|
"graphify-pi": "^0.3.0",
|
|
47
48
|
"pi-ask-user": "^0.11.2",
|
|
48
|
-
"pi-
|
|
49
|
+
"pi-autoresearch": "^1.6.0",
|
|
50
|
+
"pi-btw": "^0.4.1",
|
|
49
51
|
"pi-caveman": "^1.0.7",
|
|
50
52
|
"pi-docparser": "^3.0.1",
|
|
51
|
-
"pi-goal": "^0.1.
|
|
53
|
+
"pi-goal": "^0.1.7",
|
|
52
54
|
"pi-kanagawa": "^1.0.0",
|
|
53
|
-
"pi-mcp-adapter": "^2.
|
|
55
|
+
"pi-mcp-adapter": "^2.10.0",
|
|
54
56
|
"pi-red-green": "^0.2.2",
|
|
55
|
-
"pi-rtk-optimizer": "^0.8.
|
|
57
|
+
"pi-rtk-optimizer": "^0.8.3",
|
|
56
58
|
"pi-simplify": "^0.2.2",
|
|
57
|
-
"pi-subagents": "^0.
|
|
59
|
+
"pi-subagents": "^0.31.0",
|
|
58
60
|
"pi-tetris": "^1.3.1",
|
|
59
|
-
"pi-web-access": "^0.
|
|
61
|
+
"pi-web-access": "^0.13.0"
|
|
60
62
|
},
|
|
61
63
|
"devDependencies": {
|
|
62
|
-
"@earendil-works/pi-agent-core": "^0.
|
|
63
|
-
"@earendil-works/pi-ai": "^0.
|
|
64
|
-
"@earendil-works/pi-coding-agent": "^0.
|
|
65
|
-
"@earendil-works/pi-tui": "^0.
|
|
66
|
-
"@types/node": "^22.
|
|
67
|
-
"typebox": "^1.
|
|
68
|
-
"vite-plus": "^0.1
|
|
64
|
+
"@earendil-works/pi-agent-core": "^0.80.2",
|
|
65
|
+
"@earendil-works/pi-ai": "^0.80.2",
|
|
66
|
+
"@earendil-works/pi-coding-agent": "^0.80.2",
|
|
67
|
+
"@earendil-works/pi-tui": "^0.80.2",
|
|
68
|
+
"@types/node": "^22.20.0",
|
|
69
|
+
"typebox": "^1.3.1",
|
|
70
|
+
"vite-plus": "^0.2.1"
|
|
69
71
|
},
|
|
70
72
|
"peerDependencies": {
|
|
71
|
-
"@earendil-works/pi-agent-core": "^0.
|
|
72
|
-
"@earendil-works/pi-ai": "^0.
|
|
73
|
-
"@earendil-works/pi-coding-agent": "^0.
|
|
74
|
-
"@earendil-works/pi-tui": "^0.
|
|
75
|
-
"typebox": "^1.
|
|
73
|
+
"@earendil-works/pi-agent-core": "^0.80.2",
|
|
74
|
+
"@earendil-works/pi-ai": "^0.80.2",
|
|
75
|
+
"@earendil-works/pi-coding-agent": "^0.80.2",
|
|
76
|
+
"@earendil-works/pi-tui": "^0.80.2",
|
|
77
|
+
"typebox": "^1.3.0"
|
|
76
78
|
},
|
|
77
79
|
"overrides": {
|
|
78
80
|
"@fastify/static": "9.1.3",
|
|
@@ -100,6 +102,7 @@
|
|
|
100
102
|
"node_modules/@haispeed/pi-obsidian/skills",
|
|
101
103
|
"node_modules/pi-ask-user/skills",
|
|
102
104
|
"node_modules/pi-web-access/skills",
|
|
105
|
+
"node_modules/pi-autoresearch/skills",
|
|
103
106
|
"node_modules/@tomxprime/planning-with-files"
|
|
104
107
|
],
|
|
105
108
|
"themes": [
|