hotmilk 0.1.13 → 0.1.15
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 +12 -10
- package/README.md +237 -53
- package/agents/README.md +3 -3
- package/agents/assistant.md +1 -1
- package/agents/coach.md +26 -4
- package/agents/designer.md +1 -1
- package/agents/planner.md +2 -2
- package/hotmilk.json +11 -0
- package/package.json +43 -24
- 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 +135 -131
- package/skills/pioneer/references/autoresearch-routing.md +114 -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/observational-memory-routing.md +90 -0
- package/skills/pioneer/references/openspec-routing.md +50 -0
- package/skills/pioneer/references/plannotator-routing.md +83 -0
- package/skills/pioneer/references/prompt-eval-gate.md +38 -0
- package/skills/pioneer/references/shazam-routing.md +58 -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/btw.ts +49 -0
- package/src/bootstrap/context-stack.ts +71 -14
- package/src/bootstrap/dashboard-settings.ts +16 -2
- package/src/bootstrap/dashboard.ts +85 -10
- package/src/bootstrap/defaults.ts +26 -0
- package/src/bootstrap/extensions.ts +10 -1
- package/src/bootstrap/global-extension-sources.ts +43 -4
- package/src/bootstrap/graph.ts +12 -0
- package/src/bootstrap/project-trust.ts +55 -0
- package/src/bootstrap/resolve-bundled.ts +28 -4
- package/src/bootstrap/session.ts +61 -1
- package/src/bootstrap/subagents-doctor.ts +12 -0
- package/src/config/bundled-extensions.ts +42 -0
- package/src/config/bundled-package-registry.ts +3 -0
- package/src/config/hotmilk.ts +76 -1
- package/src/config/mcp.ts +45 -12
- package/src/config/resolve.ts +21 -0
- package/src/config/runtime.ts +6 -0
- package/src/controller/input.ts +15 -0
- package/src/controller/mode.ts +32 -0
- package/src/index.ts +5 -0
- package/src/ui/footer.ts +63 -1
- package/src/ui/github-user.ts +52 -4
- package/src/ui/session-logo.ts +31 -3
- package/themes/monokai.json +1 -1
- package/skills/empirical-prompt-tuning/SKILL.md +0 -232
package/AGENTS.md
CHANGED
|
@@ -13,25 +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.
|
|
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
|
|
26
27
|
|
|
27
|
-
| Path | Role
|
|
28
|
-
| -------------------------------- |
|
|
29
|
-
| `src/index.ts` | Extension entry: runtime, register handlers
|
|
30
|
-
| `src/config/` | `hotmilk.json` I/O, resolve, `createHotmilkRuntime()`
|
|
31
|
-
| `src/bootstrap/` | Bundled extension registration, session, graph, defaults
|
|
32
|
-
| `src/controller/` | `/mode`, `/stop`, `/interrupt`
|
|
33
|
-
| `src/ui/` | Footer, session logo
|
|
34
|
-
| `prompts/`, `skills/`, `themes/` | Shipped Pi assets (`pi.prompts`, `pi.skills`, `pi.themes`); first-party skills
|
|
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 under `./skills/` (`pioneer`, `update-docs`, …) |
|
|
35
36
|
|
|
36
37
|
## Agent behavior
|
|
37
38
|
|
|
@@ -41,6 +42,7 @@ Merge with your global agent guidelines when present. For this repo:
|
|
|
41
42
|
2. **Simplicity** — No speculative features; keep lazy loading (`extensions.ts`) intact.
|
|
42
43
|
3. **Verify** — Run `bun test` (and `bun run lint` when changing TS or config).
|
|
43
44
|
4. **Docs** — User-facing changes in `README.md`; update `hotmilk.json` when changing defaults (code reads it as the template).
|
|
45
|
+
5. **Workflow** — Plan/memory/optimize routing: [README § Workflow routing](README.md#workflow-routing) and [`skills/pioneer/SKILL.md`](skills/pioneer/SKILL.md).
|
|
44
46
|
|
|
45
47
|
## More
|
|
46
48
|
|
package/README.md
CHANGED
|
@@ -4,20 +4,28 @@
|
|
|
4
4
|
|
|
5
5
|
Use it when you want a practical engineering workstation without hand-picking a dozen `pi-*` packages and wiring `settings.json` yourself.
|
|
6
6
|
|
|
7
|
+
## Contents
|
|
8
|
+
|
|
9
|
+
- [What you get](#what-you-get)
|
|
10
|
+
- [Quick start](#quick-start)
|
|
11
|
+
- [Configuration](#configuration) — toggles, `/mode` groups, [workflow routing](#workflow-routing)
|
|
12
|
+
- [Development](#development)
|
|
13
|
+
|
|
7
14
|
## What you get
|
|
8
15
|
|
|
9
16
|
| Layer | Packages / assets |
|
|
10
17
|
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
-
| **Orchestration** | [gentle-pi](https://www.npmjs.com/package/gentle-pi)
|
|
12
|
-
| **Context** | [context-mode](https://www.npmjs.com/package/context-mode)
|
|
18
|
+
| **Orchestration** | [gentle-pi](https://www.npmjs.com/package/gentle-pi) **^0.10.x** (el Gentleman, SDD/OpenSpec sync, skill registry, `/gentle-ai:doctor`) |
|
|
19
|
+
| **Context** | [context-mode](https://www.npmjs.com/package/context-mode), [pi-observational-memory](https://www.npmjs.com/package/pi-observational-memory) (compaction continuity, default off) |
|
|
13
20
|
| **Codebase graph** | [graphify-pi](https://www.npmjs.com/package/graphify-pi) |
|
|
14
|
-
| **Subagents**
|
|
21
|
+
| **Subagents / actors** | [pi-subagents](https://www.npmjs.com/package/pi-subagents), [pi-ask-user](https://www.npmjs.com/package/pi-ask-user), [pi-actors](https://www.npmjs.com/package/@llblab/pi-actors) (off by default) |
|
|
15
22
|
| **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)
|
|
23
|
+
| **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
24
|
| **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
25
|
| **Dashboard** | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard) |
|
|
19
26
|
| **Web tools** | [pi-web-access](https://www.npmjs.com/package/pi-web-access) |
|
|
20
27
|
| **Flows** | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows) |
|
|
28
|
+
| **Experiment loops** | [pi-autoresearch](https://www.npmjs.com/package/pi-autoresearch) |
|
|
21
29
|
| **Local assets** | `./prompts`, `./skills`, `./themes`, `mcp.json` template |
|
|
22
30
|
|
|
23
31
|
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 +58,38 @@ pi install -l npm:hotmilk
|
|
|
50
58
|
2. On first session, hotmilk creates `~/.pi/agent/hotmilk.json` if missing (defaults match the bundled template).
|
|
51
59
|
3. After config changes, run `/reload`.
|
|
52
60
|
|
|
53
|
-
### Pi 0.
|
|
61
|
+
### Pi 0.80 and npm peers
|
|
54
62
|
|
|
55
|
-
hotmilk targets **Pi 0.
|
|
63
|
+
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
64
|
|
|
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.
|
|
65
|
+
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
66
|
|
|
59
67
|
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
68
|
|
|
69
|
+
### Project trust (Pi 0.79+)
|
|
70
|
+
|
|
71
|
+
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"`).
|
|
72
|
+
|
|
73
|
+
Configure in `~/.pi/agent/hotmilk.json`:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"projectTrust": {
|
|
78
|
+
"mode": "delegate",
|
|
79
|
+
"remember": false
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
| `mode` | Behavior |
|
|
85
|
+
| ---------- | ------------------------------------------------------------------------------ |
|
|
86
|
+
| `delegate` | Let Pi resolve trust (`trust.json`, `defaultProjectTrust`, or built-in prompt) |
|
|
87
|
+
| `prompt` | hotmilk confirm explaining what project trust enables |
|
|
88
|
+
| `always` | Trust project-local resources (optionally `remember: true`) |
|
|
89
|
+
| `never` | Decline project-local resources for this handler |
|
|
90
|
+
|
|
91
|
+
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.
|
|
92
|
+
|
|
61
93
|
### Commands (hotmilk)
|
|
62
94
|
|
|
63
95
|
| Command | Purpose |
|
|
@@ -66,17 +98,9 @@ Heavy optional stacks (`agent-dashboard`, `pi-flows`) stay **off by default**; e
|
|
|
66
98
|
| `/stop` | Stop current running work |
|
|
67
99
|
| `/interrupt <message>` | Steer in-flight work with an interrupt prompt |
|
|
68
100
|
|
|
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).
|
|
70
|
-
|
|
71
|
-
### Planning with files
|
|
101
|
+
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).
|
|
72
102
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
```text
|
|
76
|
-
/skill:planning-with-files
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
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).
|
|
103
|
+
For **which plan, memory, or optimize path to use**, see [Workflow routing](#workflow-routing) (canonical matrix) and the bundled [`pioneer`](skills/pioneer/SKILL.md) skill.
|
|
80
104
|
|
|
81
105
|
## Configuration
|
|
82
106
|
|
|
@@ -91,17 +115,22 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
|
|
|
91
115
|
"context-mode": true,
|
|
92
116
|
"ask-user": true,
|
|
93
117
|
"graphify": true,
|
|
118
|
+
"shazam": false,
|
|
94
119
|
"subagents": true,
|
|
120
|
+
"pi-actors": false,
|
|
95
121
|
"goal": true,
|
|
96
122
|
"docparser": true,
|
|
97
123
|
"obsidian": true,
|
|
98
124
|
"btw": true,
|
|
99
125
|
"simplify": true,
|
|
100
126
|
"rtk-optimizer": false,
|
|
127
|
+
"observational-memory": false,
|
|
101
128
|
"mcp-adapter": false,
|
|
102
129
|
"planning-with-files": false,
|
|
130
|
+
"plannotator": false,
|
|
103
131
|
"caveman": false,
|
|
104
132
|
"red-green": false,
|
|
133
|
+
"autoresearch": false,
|
|
105
134
|
"agent-dashboard": false,
|
|
106
135
|
"web-access": false,
|
|
107
136
|
"pi-flows": false,
|
|
@@ -113,34 +142,169 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
|
|
|
113
142
|
"autoSuggestUpdate": true
|
|
114
143
|
},
|
|
115
144
|
"defaults": {
|
|
116
|
-
"language": "ja",
|
|
117
145
|
"persona": "gentleman"
|
|
118
146
|
},
|
|
119
147
|
"mcp": {
|
|
120
148
|
"seedOnStart": false
|
|
149
|
+
},
|
|
150
|
+
"projectTrust": {
|
|
151
|
+
"mode": "delegate",
|
|
152
|
+
"remember": false
|
|
121
153
|
}
|
|
122
154
|
}
|
|
123
155
|
```
|
|
124
156
|
|
|
125
|
-
| Key / area | Behavior
|
|
126
|
-
| --------------------------------- |
|
|
127
|
-
| `extensions.*` | Set to `false` to skip registering that bundled extension
|
|
128
|
-
| `extensions.gentle-ai` | Default `true`. gentle-pi **0.
|
|
129
|
-
| `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
|
|
130
|
-
| `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
|
-
| `extensions.context-mode` | Default `true`. Prefer `ctx_*` for large outputs (see project context-window rules)
|
|
132
|
-
| `extensions.
|
|
133
|
-
| `extensions.
|
|
134
|
-
|
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
|
|
|
140
|
-
| `
|
|
157
|
+
| Key / area | Behavior |
|
|
158
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
159
|
+
| `extensions.*` | Set to `false` to skip registering that bundled extension |
|
|
160
|
+
| `extensions.gentle-ai` | Default `true`. gentle-pi **0.10.x** (bundled `^0.10.2`): orchestration, lazy SDD preflight, OpenSpec sync/archive agents, `/gentle-ai:doctor` / `:status`. hotmilk keeps **startup-banner off** (figlet header instead) |
|
|
161
|
+
| `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 |
|
|
162
|
+
| `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) |
|
|
163
|
+
| `extensions.context-mode` | Default `true`. Prefer `ctx_*` for large outputs (see project context-window rules) |
|
|
164
|
+
| `extensions.observational-memory` | Default `false`. Compaction continuity; pairs with `context-mode`. See [Workflow routing](#workflow-routing) |
|
|
165
|
+
| `extensions.shazam` | Default `false`. Tree-sitter + LSP execute guards (`shazam_impact`, `shazam_verify`); complements graphify — see [Workflow routing](#workflow-routing) |
|
|
166
|
+
| `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`) |
|
|
167
|
+
| `extensions.planning-with-files` | Default `false`. On-disk planning — see [Workflow routing](#workflow-routing) |
|
|
168
|
+
| `extensions.plannotator` | Default `false`. Browser plan approval — see [Workflow routing](#workflow-routing) |
|
|
169
|
+
| `extensions.autoresearch` | Default `false`. Optimize loop — see [Workflow routing](#workflow-routing) |
|
|
170
|
+
| `extensions.goal` … `mcp-adapter` | Integration / perf extensions (formerly always loaded via `pi.extensions`; now toggled like other bundled deps) |
|
|
171
|
+
| Enabled extensions | Loaded **in parallel** on session start (faster than sequential import when many toggles are on) |
|
|
172
|
+
| `graph.warnOnStale` | Notify when `graphify-out/needs_update` exists |
|
|
173
|
+
| `graph.autoSuggestUpdate` | Append `graphify update .` to that notification |
|
|
174
|
+
| `defaults.persona` | Seeds `.pi/gentle-ai/persona.json` when missing (`gentleman` \| `neutral`) |
|
|
175
|
+
| `defaults.language` | Appends a project language hint to the system prompt each turn |
|
|
176
|
+
| `mcp.seedOnStart` | Copy `mcp.json` template into `~/.pi/agent/mcp.json` when missing (empty template; for pi-mcp-adapter) |
|
|
177
|
+
| `projectTrust.mode` | Pi project trust: `delegate` (default), `prompt`, `always`, or `never` |
|
|
178
|
+
| `projectTrust.remember` | When `mode` is `always` or `never`, persist the decision in Pi `trust.json` |
|
|
179
|
+
| `extensions.mcp-adapter` | Default `false`. Enable only when you want MCP servers from `~/.pi/agent/mcp.json` (do not duplicate context-mode) |
|
|
141
180
|
|
|
142
181
|
**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
182
|
|
|
183
|
+
### `/mode` groups
|
|
184
|
+
|
|
185
|
+
`/mode` sections follow `BUNDLED_EXTENSION_GROUP_ORDER` in `src/config/bundled-extensions.ts`:
|
|
186
|
+
|
|
187
|
+
| Group | Extensions (toggle ids) |
|
|
188
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
189
|
+
| **Harness** | `skill-registry`, `sdd-init`, `gentle-ai` |
|
|
190
|
+
| **Agent tools** | `ask-user`, `graphify`, `shazam`, `subagents`, `pi-actors`, `agent-dashboard`, `web-access`, `pi-flows` |
|
|
191
|
+
| **Context & performance** | `context-mode`, `simplify`, `rtk-optimizer`, `observational-memory` |
|
|
192
|
+
| **Integrations** | `goal`, `docparser`, `obsidian`, `btw`, `mcp-adapter` |
|
|
193
|
+
| **Workflow** | `planning-with-files`, `plannotator`, `red-green` |
|
|
194
|
+
| **Output** | `caveman`, `kanagawa` |
|
|
195
|
+
| **Experiments** | `autoresearch`, `tetris` |
|
|
196
|
+
|
|
197
|
+
### Workflow routing
|
|
198
|
+
|
|
199
|
+
Pick **one plan authority per task**. Memory and optimize loops are **not** plan paths — they layer beside execution. Full tie-breakers and anti-patterns: bundled [`pioneer`](skills/pioneer/SKILL.md) skill.
|
|
200
|
+
|
|
201
|
+
**Plan paths** (enable toggle → `/reload` when default off):
|
|
202
|
+
|
|
203
|
+
| When | Toggle / command | Artifact | Pioneer reference |
|
|
204
|
+
| --------------------------------- | ---------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
205
|
+
| Small, bounded fix | (none) — chat `Plan:` | chat only | [`chat-plan.md`](skills/pioneer/references/chat-plan.md) |
|
|
206
|
+
| Medium scope + browser approval | `plannotator` → `/plannotator plans/<name>.md` | `plans/*.md` | [`plannotator-routing.md`](skills/pioneer/references/plannotator-routing.md) |
|
|
207
|
+
| Heavy research, `/clear` recovery | `planning-with-files` → `/skill:planning-with-files` | `task_plan.md`, `findings.md`, `progress.md` | upstream PWF skill |
|
|
208
|
+
| Cross-cutting, spec, >400L review | `gentle-ai` → OpenSpec SDD | `openspec/changes/<change>/` | [`openspec-routing.md`](skills/pioneer/references/openspec-routing.md) |
|
|
209
|
+
|
|
210
|
+
**Memory layers** (supplementary — never replace plan/spec authority):
|
|
211
|
+
|
|
212
|
+
| Need | Prefer |
|
|
213
|
+
| ----------------------------- | ------------------------------------------------------------------------------- |
|
|
214
|
+
| Large logs, docs, test output | `context-mode` → `ctx_*` |
|
|
215
|
+
| Rationale across compactions | `observational-memory` (extra model cost; V3 needs clean session after upgrade) |
|
|
216
|
+
| User-readable plan files | `planning-with-files` |
|
|
217
|
+
| Execute-time impact / LSP | `shazam` (after graphify recon; not a graph replacement) |
|
|
218
|
+
|
|
219
|
+
Details: [`observational-memory-routing.md`](skills/pioneer/references/observational-memory-routing.md), [`shazam-routing.md`](skills/pioneer/references/shazam-routing.md).
|
|
220
|
+
|
|
221
|
+
**Optimize loops** (mutually exclusive with SDD/Plannotator on the same task):
|
|
222
|
+
|
|
223
|
+
| Need | Prefer |
|
|
224
|
+
| ------------------------------------------ | ------------------------------------------------------------ |
|
|
225
|
+
| Metric optimize (bench, bundle size, loss) | `autoresearch` → `/skill:autoresearch-create` |
|
|
226
|
+
| Feature delivery, spec, approval gates | `gentle-ai` SDD or `plannotator` — keep autoresearch **off** |
|
|
227
|
+
| Correctness-first TDD | `red-green` (`/tdd`) |
|
|
228
|
+
|
|
229
|
+
Stop active loops (`/autoresearch off`) before switching plan paths. Details: [`autoresearch-routing.md`](skills/pioneer/references/autoresearch-routing.md). Default shortcut `Ctrl+Shift+F` — override in `~/.pi/agent/extensions/pi-autoresearch.json`.
|
|
230
|
+
|
|
231
|
+
### Agents, skills, and scope
|
|
232
|
+
|
|
233
|
+
Pi resolves bundled assets at **user (global)**, **project**, and **package** layers. hotmilk ships package defaults; you override per machine or per repo.
|
|
234
|
+
|
|
235
|
+
| Layer | Config | Agents (pi-subagents) | Skills / prompts |
|
|
236
|
+
| ----------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
237
|
+
| **User (global)** | `~/.pi/agent/hotmilk.json`, `~/.pi/agent/settings.json` | `~/.pi/agent/agents/` or `~/.agents/` | User skill dirs indexed by gentle-pi `skill-registry` |
|
|
238
|
+
| **Project** | `.pi/settings.json` | **`.pi/agents/`** (canonical); legacy `.agents/` still read | `.pi/skills/`; legacy `.agents/skills/` |
|
|
239
|
+
| **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) |
|
|
240
|
+
|
|
241
|
+
**Precedence (same runtime name):** project → user → builtin (pi-subagents built-ins). `/run`, chains, and the `subagent` tool default to `agentScope: "both"` (user + project + builtin).
|
|
242
|
+
|
|
243
|
+
**hotmilk subagents**
|
|
244
|
+
|
|
245
|
+
- **Edit in git / npm:** `agents/*.md` — package canonical prompts (`package: hotmilk` in frontmatter → runtime name `hotmilk.coach`, `hotmilk.planner`, …).
|
|
246
|
+
- **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.
|
|
247
|
+
- **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.
|
|
248
|
+
|
|
249
|
+
After changing prompts in this repo, sync the local project overlay (often untracked):
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
cp agents/*.md .pi/agents/
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Verify with `/subagents-doctor` — expect `hotmilk.*` under project agents when `.pi/agents/` is populated.
|
|
256
|
+
|
|
257
|
+
See [agents/README.md](agents/README.md) for the role map (coach, planner, coder, reviewer, …).
|
|
258
|
+
|
|
259
|
+
### Environment variables
|
|
260
|
+
|
|
261
|
+
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.
|
|
262
|
+
|
|
263
|
+
**Pi core** (always relevant; full list in [Pi usage — environment variables](https://pi.dev/docs/latest/usage#environment-variables)):
|
|
264
|
+
|
|
265
|
+
| Variable | Purpose |
|
|
266
|
+
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
267
|
+
| `PI_CODING_AGENT_DIR` | Override agent config dir (default `~/.pi/agent`). Affects `hotmilk.json`, auth, global agents, MCP path |
|
|
268
|
+
| `PI_CODING_AGENT_SESSION_DIR` | Override session storage (also `--session-dir`) |
|
|
269
|
+
| `PI_PACKAGE_DIR` | Override package dir (Nix/Guix store paths) |
|
|
270
|
+
| `PI_OFFLINE` | Disable startup network (update checks, package checks, install telemetry) |
|
|
271
|
+
| `PI_SKIP_VERSION_CHECK` | Skip `pi.dev` latest-version check only |
|
|
272
|
+
| `PI_TELEMETRY` | Opt in/out of install/update telemetry and provider attribution headers (`1`/`0`) |
|
|
273
|
+
| `PI_CACHE_RETENTION` | `long` for extended prompt cache where supported |
|
|
274
|
+
| `PI_TIMING` | `1` — emit timing diagnostics |
|
|
275
|
+
| `PI_HARDWARE_CURSOR` | `1` — show hardware cursor (IME / some terminals) |
|
|
276
|
+
| `PI_TUI_WRITE_LOG` | Path — log raw TUI ANSI to a file (debug) |
|
|
277
|
+
| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
|
|
278
|
+
|
|
279
|
+
**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.
|
|
280
|
+
|
|
281
|
+
**hotmilk-owned**:
|
|
282
|
+
|
|
283
|
+
| Variable | Purpose |
|
|
284
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
285
|
+
| `HOTMILK_CONFIG_ROOT` | Override directory that contains `hotmilk.json` (default `~/.pi/agent`). Tests and sandboxes only; normal installs leave unset |
|
|
286
|
+
|
|
287
|
+
**Bundled extensions** (only when the matching `/mode` toggle is on):
|
|
288
|
+
|
|
289
|
+
| Variable | Toggle / package | Purpose |
|
|
290
|
+
| ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
|
|
291
|
+
| `PI_SUBAGENT_MAX_DEPTH` | `subagents` | Max nested subagent depth (default 2). Do not set `PI_SUBAGENT_DEPTH` manually |
|
|
292
|
+
| `PI_SUBAGENT_INHERIT_PROJECT_CONTEXT` | `subagents` | `0`/`false` — child skips project context inheritance |
|
|
293
|
+
| `PI_SUBAGENT_INHERIT_SKILLS` | `subagents` | `0`/`false` — child skips skill inheritance |
|
|
294
|
+
| `PI_DASHBOARD_PORT`, `PI_DASHBOARD_PI_PORT` | `agent-dashboard` | HTTP / bridge ports (hotmilk seeds **8102** when config still has upstream default `8000`) |
|
|
295
|
+
| `PI_DASHBOARD_ALLOW_MULTIPLE` | `agent-dashboard` | `1`/`true` — allow multiple dashboard processes |
|
|
296
|
+
| `PI_DASHBOARD_URL` | `agent-dashboard` | Bridge WebSocket URL (spawn sets this) |
|
|
297
|
+
| `PI_DASHBOARD_SPAWN_TOKEN` | `agent-dashboard` | Set by dashboard spawn; do not set by hand |
|
|
298
|
+
| `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `graphify` (CLI) | Semantic extraction backend for `graphify extract` |
|
|
299
|
+
| `GRAPHIFY_GEMINI_MODEL`, `GRAPHIFY_WHISPER_MODEL` | `graphify` (CLI) | Override graphify LLM / Whisper model |
|
|
300
|
+
| `EXA_API_KEY`, `PERPLEXITY_API_KEY`, `GEMINI_API_KEY` | `web-access` | Search / fetch keys (`~/.pi/web-search.json` also) |
|
|
301
|
+
| `PI_ALLOW_BROWSER_COOKIES` | `web-access` | `1` — allow Chromium cookie extraction for Gemini Web |
|
|
302
|
+
| `CTX_FETCH_STRICT` | `context-mode` | `1` — stricter fetch routing in context-mode |
|
|
303
|
+
|
|
304
|
+
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.
|
|
305
|
+
|
|
306
|
+
**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`.
|
|
307
|
+
|
|
144
308
|
### pi-btw with subagents (default on)
|
|
145
309
|
|
|
146
310
|
Both **`subagents`** and **`btw`** default to **on**. They do not share commands or extension IDs; hotmilk loads them in parallel.
|
|
@@ -167,19 +331,38 @@ Set `"btw": false` in `/mode` if you want delegation only with no side channel.
|
|
|
167
331
|
|
|
168
332
|
### Optional extensions (off by default)
|
|
169
333
|
|
|
170
|
-
Enable in `/mode` or set the key to `true` in `hotmilk.json`, then `/reload`.
|
|
334
|
+
Enable in `/mode` or set the key to `true` in `hotmilk.json`, then `/reload`. Workflow-oriented toggles are summarized in [Workflow routing](#workflow-routing).
|
|
335
|
+
|
|
336
|
+
| Toggle | Package | Notes |
|
|
337
|
+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
|
|
338
|
+
| `planning-with-files` | [@tomxprime/planning-with-files](https://www.npmjs.com/package/@tomxprime/planning-with-files) | On-disk planning; `/skill:planning-with-files` |
|
|
339
|
+
| `plannotator` | [@plannotator/pi-extension](https://www.npmjs.com/package/@plannotator/pi-extension) | `/plannotator`, `pi --plan`; ~37MB UI; `plannotator.json` |
|
|
340
|
+
| `observational-memory` | [pi-observational-memory](https://www.npmjs.com/package/pi-observational-memory) | Compaction continuity; V3 = clean session after upgrade |
|
|
341
|
+
| `supi-context` | [@mrclrchtr/supi-context](https://www.npmjs.com/package/@mrclrchtr/supi-context) | Context analysis & formatting; default off |
|
|
342
|
+
| `shazam` | [pi-shazam](https://www.npmjs.com/package/pi-shazam) | `shazam_*` tools; LSP-backed verify; complements graphify |
|
|
343
|
+
| `autoresearch` | [pi-autoresearch](https://www.npmjs.com/package/pi-autoresearch) | `/autoresearch`, `.auto/`; shortcut override in `pi-autoresearch.json` |
|
|
344
|
+
| `caveman` | [pi-caveman](https://www.npmjs.com/package/pi-caveman) | Terse English; conflicts with `defaults.language: ja` |
|
|
345
|
+
| `red-green` | [pi-red-green](https://www.npmjs.com/package/pi-red-green) | `/tdd`, `/tdd-status`; `~/.pi/red-green/config.json` |
|
|
346
|
+
| `agent-dashboard` | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard) | Warm-start; peers **0.74** — test on 0.80 |
|
|
347
|
+
| `web-access` | [pi-web-access](https://www.npmjs.com/package/pi-web-access) | `web_search`, fetch; `~/.pi/web-search.json` |
|
|
348
|
+
| `pi-flows` | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows) | `/flows`; peers **0.74** |
|
|
349
|
+
| `pi-actors` | [@llblab/pi-actors](https://www.npmjs.com/package/@llblab/pi-actors) | Local actor kernel (`spawn`, `message`, `inspect`) |
|
|
350
|
+
| `prompt-template-model` | [pi-prompt-template-model](https://www.npmjs.com/package/pi-prompt-template-model) | Prompt template model selector; default off |
|
|
351
|
+
| `kanagawa` | [pi-kanagawa](https://www.npmjs.com/package/pi-kanagawa) | Theme; **replaces hotmilk footer** when on |
|
|
352
|
+
| `tetris` | [pi-tetris](https://www.npmjs.com/package/pi-tetris) | `/tetris` |
|
|
353
|
+
| `latchkey` | [latchkey](https://www.npmjs.com/package/latchkey) | **Skill-only** — API credential injection via `/skill:latchkey` |
|
|
354
|
+
|
|
355
|
+
### Alternative skill stacks (not bundled)
|
|
356
|
+
|
|
357
|
+
hotmilk does **not** bundle [bigpowers](https://github.com/danielvm-git/bigpowers) — a separate spec-driven skill stack (70+ skills, prompts, MCP). It has no `pi.extensions` entry, runs `postinstall` global symlinks, and **conflicts with gentle-pi / pioneer plan routing**. Install separately if you want that workflow instead of hotmilk's defaults:
|
|
358
|
+
|
|
359
|
+
```bash
|
|
360
|
+
pi install npm:bigpowers
|
|
361
|
+
```
|
|
171
362
|
|
|
172
|
-
|
|
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
|
-
| `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 |
|
|
177
|
-
| `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` |
|
|
178
|
-
| `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 |
|
|
179
|
-
| `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 |
|
|
180
|
-
| `tetris` | [pi-tetris](https://www.npmjs.com/package/pi-tetris) | Play Tetris with `/tetris`. Lightweight; default off |
|
|
363
|
+
Do not enable bigpowers alongside pioneer OpenSpec/Plannotator on the same task. See [`.agents/plans/EXTENSIONS.md`](.agents/plans/EXTENSIONS.md) §L8.
|
|
181
364
|
|
|
182
|
-
|
|
365
|
+
### Agent dashboard troubleshooting
|
|
183
366
|
|
|
184
367
|
- Run **one** dashboard process: either hotmilk warm-start (`agent-dashboard: true`) **or** manual `npm run dashboard:start`, not both.
|
|
185
368
|
- Keep only `"hotmilk"` in `~/.pi/agent/settings.json` `packages[]` (not a standalone dashboard extension path). Hotmilk prunes duplicate dashboard paths on session start when `agent-dashboard` is enabled.
|
|
@@ -200,7 +383,7 @@ agent login
|
|
|
200
383
|
|
|
201
384
|
## Development
|
|
202
385
|
|
|
203
|
-
Requires **Node.js 22+** (or **Bun 1.3+**), **Bun** for installs in this repo, and Pi **0.
|
|
386
|
+
Requires **Node.js 22+** (or **Bun 1.3+**), **Bun** for installs in this repo, and Pi **0.80** peers in the environment.
|
|
204
387
|
|
|
205
388
|
```bash
|
|
206
389
|
bun install # commit bun.lock; peers resolved by Bun
|
|
@@ -244,13 +427,14 @@ npm publish --access public
|
|
|
244
427
|
|
|
245
428
|
### Layout
|
|
246
429
|
|
|
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
|
-
| `
|
|
430
|
+
| Path | Role |
|
|
431
|
+
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
432
|
+
| `src/index.ts` | Extension entry: config, bundled extensions, session UI, input routing |
|
|
433
|
+
| `src/config/hotmilk.ts` | `hotmilk.json` load / seed / save |
|
|
434
|
+
| `agents/` | Package-canonical subagent prompts (`package: hotmilk`); install into `.pi/agents/` for discovery |
|
|
435
|
+
| `prompts/`, `skills/`, `themes/` | Shipped with the package (`pi.prompts`, `pi.skills`, `pi.themes`); workflow routing in [`skills/pioneer/`](skills/pioneer/SKILL.md) |
|
|
436
|
+
| `mcp.json` | MCP server template for local projects |
|
|
437
|
+
| `hotmilk.json` | Default toggle template (published in the npm package) |
|
|
254
438
|
|
|
255
439
|
## License
|
|
256
440
|
|
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/assistant.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: assistant
|
|
3
3
|
description: General-purpose coding assistant for reading, writing, and reviewing code
|
|
4
4
|
tools: read, grep, find, ls, bash, edit, write, todo, subagent
|
|
5
|
-
model: cursor/auto
|
|
5
|
+
# model: cursor/auto
|
|
6
6
|
thinking: low
|
|
7
7
|
systemPromptMode: replace
|
|
8
8
|
inheritProjectContext: true
|
package/agents/coach.md
CHANGED
|
@@ -26,17 +26,39 @@ 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
|
|
|
36
37
|
1. Restate the goal in one sentence; list what is **known** vs **assumed**.
|
|
37
|
-
2.
|
|
38
|
-
3.
|
|
39
|
-
4.
|
|
38
|
+
2. Surface the **TCZ contract** for this goal: `V`, `θ`, `Share`/`S_i`, and the **LUB candidate** (see below).
|
|
39
|
+
3. Teach the **minimum** concept needed for the next decision (diagrams or short tables OK).
|
|
40
|
+
4. Offer **2–3** options with tradeoffs and how each would be **verified** (`bun test`, doctor, graphify, Share_op, multi-bridge ensemble, etc.).
|
|
41
|
+
5. End with one **recommended next step** for the parent (e.g. `planner`, `scout`, `ask-user`, inline fix).
|
|
42
|
+
|
|
43
|
+
### TCZ convergence check (V / θ / Share / LUB)
|
|
44
|
+
|
|
45
|
+
Treat coaching as helping the human ascend toward the **least upper bound (LUB)** of shared abstraction, not just answering the immediate question.
|
|
46
|
+
|
|
47
|
+
- **Theorem 1 / 個別収束**: for every goal, make `V` (verification potential) and `θ` (acceptance threshold) explicit in the coaching output. If the user cannot state them, push back and ask up to three targeted questions before routing to a planner.
|
|
48
|
+
- **Theorem 2 / 共有整合**: when the goal involves multiple agents, shared artifacts, or review gates, identify the shared checks `S_i` and the minimum `Share ≥ η` that must hold across them.
|
|
49
|
+
- **Theorem 3 / 領域固定**: for large, ambiguous, or bridge-split changes, state an **LUB candidate** — the smallest shared abstraction that all acceptable implementations would satisfy. If multiple plausible agent outputs exist, recommend a **multi-bridge ensemble** (multiple independent implementations whose LUB is checked against the LUB candidate).
|
|
50
|
+
- **Boundary maintenance**: the coach intervenes at the `V ≈ θ` boundary, not inside the converged interior. If the user is about to delegate to `planner` with unstated `V`/`θ` or LUB, pause and ask.
|
|
51
|
+
|
|
52
|
+
## Before delegating to planner
|
|
53
|
+
|
|
54
|
+
A handoff to `planner` should include — or explicitly waive — all of:
|
|
55
|
+
|
|
56
|
+
1. `V`: what concrete evidence will prove the change is correct?
|
|
57
|
+
2. `θ`: what is the minimum acceptable value of that evidence?
|
|
58
|
+
3. `LUB candidate`: what shared abstraction must every acceptable implementation satisfy?
|
|
59
|
+
4. `Constraints / Boundaries / Iteration policy / Blocked stop condition` from the strong goal contract.
|
|
60
|
+
|
|
61
|
+
If any are missing and the user still wants a plan, write the handoff with `V`, `θ`, and LUB as open risks that `planner` must resolve first.
|
|
40
62
|
|
|
41
63
|
## Working rules
|
|
42
64
|
|
package/agents/designer.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: designer
|
|
3
3
|
description: Frontend design specialist for HTML/CSS/JSX/TSX/MDX with UI styling and UX focus
|
|
4
4
|
tools: read, grep, find, ls, bash, edit, write, todo, subagent
|
|
5
|
-
model: cursor/auto
|
|
5
|
+
# model: cursor/auto
|
|
6
6
|
thinking: medium
|
|
7
7
|
systemPromptMode: replace
|
|
8
8
|
inheritProjectContext: true
|
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
|
@@ -6,21 +6,28 @@
|
|
|
6
6
|
"context-mode": true,
|
|
7
7
|
"ask-user": true,
|
|
8
8
|
"graphify": true,
|
|
9
|
+
"shazam": false,
|
|
9
10
|
"subagents": true,
|
|
11
|
+
"pi-actors": false,
|
|
10
12
|
"goal": true,
|
|
11
13
|
"docparser": true,
|
|
12
14
|
"obsidian": true,
|
|
13
15
|
"btw": true,
|
|
14
16
|
"simplify": true,
|
|
15
17
|
"rtk-optimizer": false,
|
|
18
|
+
"observational-memory": false,
|
|
19
|
+
"supi-context": false,
|
|
16
20
|
"mcp-adapter": false,
|
|
17
21
|
"planning-with-files": false,
|
|
22
|
+
"plannotator": false,
|
|
18
23
|
"caveman": false,
|
|
19
24
|
"red-green": false,
|
|
25
|
+
"autoresearch": false,
|
|
20
26
|
"agent-dashboard": false,
|
|
21
27
|
"web-access": false,
|
|
22
28
|
"pi-flows": false,
|
|
23
29
|
"kanagawa": false,
|
|
30
|
+
"prompt-template-model": false,
|
|
24
31
|
"tetris": false
|
|
25
32
|
},
|
|
26
33
|
"graph": {
|
|
@@ -32,5 +39,9 @@
|
|
|
32
39
|
},
|
|
33
40
|
"mcp": {
|
|
34
41
|
"seedOnStart": false
|
|
42
|
+
},
|
|
43
|
+
"projectTrust": {
|
|
44
|
+
"mode": "delegate",
|
|
45
|
+
"remember": false
|
|
35
46
|
}
|
|
36
47
|
}
|