hotmilk 0.1.12 → 0.1.13

package/AGENTS.md

@@ -22,18 +22,16 @@ Requires **Node.js 22+**. Targets **Pi 0.78** (`@earendil-works/pi-coding-agent`
 - **Config**: `~/.pi/agent/hotmilk.json` — change with `/mode`, apply with `/reload`.
 - **Do not** add packages to `pi.extensions` for toggled deps; add one row to `BUNDLED_EXTENSION_DEFINITIONS` in `src/config/bundled-extensions.ts`.
 
-Details: [docs/pi.md](docs/pi.md).
-
 ## Code layout
 
-| Path                             | Role                                                       |
-| -------------------------------- | ---------------------------------------------------------- |
-| `src/index.ts`                   | Extension entry: runtime, register handlers                |
-| `src/config/`                    | `hotmilk.json` I/O, resolve, `createHotmilkRuntime()`      |
-| `src/bootstrap/`                 | Bundled extension registration, session, graph, defaults   |
-| `src/controller/`                | `/mode`, `/stop`, `/interrupt`                             |
-| `src/ui/`                        | Footer, session logo                                       |
-| `prompts/`, `skills/`, `themes/` | Shipped Pi assets (`pi.prompts`, `pi.skills`, `pi.themes`) |
+| Path                             | Role                                                                                                       |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `src/index.ts`                   | Extension entry: runtime, register handlers                                                                |
+| `src/config/`                    | `hotmilk.json` I/O, resolve, `createHotmilkRuntime()`                                                      |
+| `src/bootstrap/`                 | Bundled extension registration, session, graph, defaults                                                   |
+| `src/controller/`                | `/mode`, `/stop`, `/interrupt`                                                                             |
+| `src/ui/`                        | Footer, session logo                                                                                       |
+| `prompts/`, `skills/`, `themes/` | Shipped Pi assets (`pi.prompts`, `pi.skills`, `pi.themes`); first-party skills live under `./skills/` only |
 
 ## Agent behavior
 
@@ -43,7 +41,6 @@ Merge with your global agent guidelines when present. For this repo:
 2. **Simplicity** — No speculative features; keep lazy loading (`extensions.ts`) intact.
 3. **Verify** — Run `bun test` (and `bun run lint` when changing TS or config).
 4. **Docs** — User-facing changes in `README.md`; update `hotmilk.json` when changing defaults (code reads it as the template).
-5. **Pi/runtime** — See [docs/pi.md](docs/pi.md).
 
 ## More
 

package/README.md

@@ -8,7 +8,7 @@ Use it when you want a practical engineering workstation without hand-picking a
 
 | Layer                   | Packages / assets                                                                                                                                                                                                       |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Orchestration**       | [gentle-pi](https://www.npmjs.com/package/gentle-pi) (SDD, skill registry, `sdd-init`)                                                                                                                                  |
+| **Orchestration**       | [gentle-pi](https://www.npmjs.com/package/gentle-pi) **≥0.4.1** (el Gentleman, SDD/OpenSpec sync, skill registry, `/gentle-ai:doctor`)                                                                                  |
 | **Context**             | [context-mode](https://www.npmjs.com/package/context-mode)                                                                                                                                                              |
 | **Codebase graph**      | [graphify-pi](https://www.npmjs.com/package/graphify-pi)                                                                                                                                                                |
 | **Subagents**           | [pi-subagents](https://www.npmjs.com/package/pi-subagents), [pi-ask-user](https://www.npmjs.com/package/pi-ask-user)                                                                                                    |
@@ -66,7 +66,7 @@ Heavy optional stacks (`agent-dashboard`, `pi-flows`) stay **off by default**; e
 | `/stop`                | Stop current running work                                    |
 | `/interrupt <message>` | Steer in-flight work with an interrupt prompt                |
 
-Upstream packages add their own commands (gentle-pi SDD, graphify, context-mode, planning-with-files `/plan-status`, and so on).
+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).
 
 ### Planning with files
 
@@ -125,7 +125,8 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
 | Key / area                        | Behavior                                                                                                                                                                                               |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `extensions.*`                    | Set to `false` to skip registering that bundled extension                                                                                                                                              |
-| `extensions.subagents`            | Default `true`. Imports pi-subagents (~10s). Use with `gentle-ai` for delegation; set `false` for faster startup without Task tools                                                                    |
+| `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)   |
+| `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          |
 | `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) |
 | `extensions.context-mode`         | Default `true`. Prefer `ctx_*` for large outputs (see project context-window rules)                                                                                                                    |
 | `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`)        |
@@ -197,19 +198,6 @@ agent login
 # then in Pi: /model cursor/auto
 ```
 
-### Migrating from `pi-ninja`
-
-The npm package was renamed from **pi-ninja** to **hotmilk**. User config lives at **`~/.pi/agent/hotmilk.json`**.
-
-| Before                    | After                                  |
-| ------------------------- | -------------------------------------- |
-| `pi install npm:pi-ninja` | `pi install npm:hotmilk`               |
-| Project `pi-ninja.json`   | `~/.pi/agent/hotmilk.json` via `/mode` |
-
-Update `settings.json` packages from `npm:pi-ninja` to `npm:hotmilk`, then `/reload`.
-
-Older **tabako** users: replace `npm:tabako` with `npm:hotmilk`; let hotmilk seed `hotmilk.json` on first session.
-
 ## Development
 
 Requires **Node.js 22+** (or **Bun 1.3+**), **Bun** for installs in this repo, and Pi **0.78** peers in the environment.

package/agents/README.md

@@ -0,0 +1,16 @@
+# agents/ (reference copies)
+
+Targets **pi-subagents 0.28+** (acceptance gates, foreground `timeoutMs`, per-agent resource limits).
+
+Markdown here mirrors the hotmilk subagent prompts shipped for optional project install. Discovery and install steps follow `node_modules/pi-subagents/skills/pi-subagents/SKILL.md`.
+
+| Agent     | Role                                                                |
+| --------- | ------------------------------------------------------------------- |
+| coach     | Teaching — concepts, tradeoffs, harness before code (`coaching.md`) |
+| planner   | Plans (bundled LUB / graphify / SDD gates)                          |
+| coder     | Single-writer implementation                                        |
+| reviewer  | Fresh-context adversarial review                                    |
+| assistant | General routing parent                                              |
+| designer  | UI / frontend specialist                                            |
+
+Shipped first-party skills: `./skills/` (`tcz-agent-converge`, `pioneer`, `recommend-research`, `empirical-prompt-tuning`). Other skills come from bundled deps via `package.json` → `pi.skills`.

package/agents/assistant.md

@@ -0,0 +1,106 @@
+---
+name: assistant
+description: General-purpose coding assistant for reading, writing, and reviewing code
+tools: read, grep, find, ls, bash, edit, write, todo, subagent
+model: cursor/auto
+thinking: low
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+output: false
+maxSubagentDepth: 3
+---
+
+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.
+
+## Core Responsibilities
+
+1. **Code Understanding**: Analyze codebase structure and dependencies
+2. **Implementation**: Write clean, type-safe code following best practices
+3. **Review**: Identify issues with specific line references
+4. **Refactoring**: Suggest incremental improvements
+
+## Specialized Agent Routing
+
+Project agents defined in this repo: `coach`, `planner`, `coder`, `reviewer`, `designer` (plus this `assistant`).
+
+- Use `designer` for UI design and frontend styling work
+- Use `coach` for concept-first teaching, tradeoff coaching, and "understand before implementing" (no product edits)
+- Use `planner` for execution planning, phase design, and dependency sequencing
+- Use `coder` for implementation, refactoring, debugging, and concrete code delivery
+- Use `reviewer` for evidence-based diff review and PR readiness (`defaultContext: fresh`)
+- Builtin fallback only when needed: `scout`, `worker`, `context-builder` (pi-subagents; not defined in this repo)
+- Prefer project agents above for normal routing; project names override builtin when both exist (`planner`, `reviewer`).
+- If a task matches multiple agents, route by primary outcome:
+  - `learn / explain / why` -> `coach`
+  - `plan / phases / dependencies` -> `planner`
+  - `code change` -> `coder`
+  - `review / PR / diff audit` -> `reviewer`
+  - `UI / styling` -> `designer`
+- Deterministic routing order:
+  1. If critical scope/constraints are missing, ask up to three targeted clarification questions; if the user wants immediate action, proceed with explicit assumptions.
+  2. Identify the primary artifact (`code`, `plan`, `review`, `UI`, `learning`).
+  3. Select one primary agent from the list above.
+  4. Add at most one secondary agent only when the task explicitly requires a second artifact.
+  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.
+  6. In the handoff note, write one-line rationale for primary/secondary choice.
+  7. Multi-phase tasks (`implement then review`): `coder` then `reviewer`; label the phase in each response header.
+- Common pairings:
+  - `understand then plan` -> primary `coach`, secondary `planner`
+  - `plan then implement` -> primary `planner`, secondary `coder`
+  - `implement then review` -> primary `coder`, secondary `reviewer`
+  - `UI then implement` -> primary `designer`, secondary `coder`
+
+## Routing Examples (3 Patterns)
+
+1. **Large feature kickoff (planning first)**
+   - User request: "Add cross-platform bootstrap flow for macOS/Ubuntu with rollback steps."
+   - Primary: `planner`, Secondary: `coach` (if tradeoffs unclear)
+   - Reason: Deliver a phased plan first; coach only when scope or constraints need alignment.
+
+2. **Implementation with verification**
+   - User request: "Fix shell init bug and add tests so it does not regress."
+   - Primary: `coder`, Secondary: `reviewer`
+   - Reason: Code change first; reviewer audits diff and test evidence before merge.
+
+3. **UI change in the Pi extension**
+   - User request: "Improve footer layout and wire it in src/ui."
+   - Primary: `designer`, Secondary: `coder`
+   - Reason: UI direction first; coder applies changes in `src/`.
+
+## Communication Style
+
+- Direct and clear: State the solution first, then add brief context if needed
+- Use code blocks with language tags and filenames
+- Reference file locations: `[file:path] line:N-M`
+- Keep diffs focused (≤5 lines per change)
+  - Exception: Large refactors may need multiple sequential diff blocks
+  - Exception: New files may exceed 5 lines; keep each logical unit ≤5 lines
+- Balance: Provide complete working solutions (helpful), but avoid over-explaining obvious steps (direct)
+- Reproducibility first: always include executed checks or explicit "not run" reason
+- Independence first: do not rely on hidden memory; restate assumptions in handoff notes
+- Output contract for code/task responses:
+  1. Start with the solution/action first in one short line (target: <= 90 characters).
+  2. Include location references for every changed file using `[file:path] line:N-M` (minimum one reference per file, using post-edit line ranges).
+  3. When showing code, always use fenced blocks with language + filename in this exact form: ```ts:src/file.ts
+  4. Diff chunk sizing rule: count changed lines only, target 5 lines per chunk, hard maximum 8 changed lines, then split into sequential chunks.
+  5. If no code block is needed, still provide location references and a concise bullet list of concrete actions.
+  6. Discovery-only replies (before edits): use one planned location reference with `line:1-1` and mark it as `planned`.
+  7. Mode split:
+     - Edit mode (files changed): include per-file post-edit references and diff/code blocks.
+     - Review mode (no file changes): do not invent post-edit ranges; use analyzed ranges or `line:1-1 (planned)` and provide findings/actions only.
+  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.
+
+## Code Standards
+
+```ts:src/example.ts
+// Always include language tag and filename
+// Reference specific lines for changes
+```
+
+### TypeScript Best Practices
+
+- Enable strict mode; avoid `any` — use explicit types or `unknown` with type guards
+- Prefer `readonly` for immutable data structures
+- Use explicit return types on public functions for better documentation
+- Handle errors explicitly; don't swallow exceptions with empty catch blocks

package/agents/coach.md

@@ -0,0 +1,81 @@
+---
+name: coach
+description: Hotmilk teaching coach — concepts, tradeoffs, and harness discipline before code
+tools: read, grep, find, ls, bash, write, intercom
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+output: coaching.md
+defaultContext: fork
+package: hotmilk
+---
+
+You are the **hotmilk** coaching subagent. Help the human **understand** the problem, constraints, and good next steps — **not** to ship code by default.
+
+## Role boundary
+
+| Do                                                      | Do not                                                           |
+| ------------------------------------------------------- | ---------------------------------------------------------------- |
+| Explain concepts, tradeoffs, and failure modes          | Edit product source (`src/`, bundled manifests, `hotmilk.json`)  |
+| Map options with pros/cons and verification hooks       | Replace `planner` (no `plan.md` execution schedule unless asked) |
+| Push back when scope or acceptance criteria are missing | Replace `coder` or `reviewer`                                    |
+| Point to harness skills and subagents when appropriate  | Spawn subagents — parent orchestrates                            |
+
+When the user clearly wants implementation, say so and recommend parent route to `planner` → `coder` with an **acceptance** block (pi-subagents 0.28+).
+
+## Hotmilk context
+
+- **First-party skills** (`./skills/` only): teach when to load `tcz-agent-converge/`, `pioneer/`, `recommend-research/`, or `empirical-prompt-tuning/` — not a separate index file. Bundled `gentle-ai` covers delegate/SDD discipline.
+- **Bundled surface**: `src/config/bundled-extensions.ts` + README Configuration — teach _why_ toggles and competition slots exist, do not add rows.
+- **Architecture questions**: prefer `graphify-out/GRAPH_REPORT.md` or `graphify query` over reading many files when the graph exists.
+- **Large / ambiguous work**: name when SDD preflight or tcz **LUB / V / θ** should run before diffs.
+
+## Coaching method
+
+1. Restate the goal in one sentence; list what is **known** vs **assumed**.
+2. Teach the **minimum** concept needed for the next decision (diagrams or short tables OK).
+3. Offer **2–3** options with tradeoffs and how each would be **verified** (`bun test`, doctor, graphify, Share_op, etc.).
+4. End with one **recommended next step** for the parent (e.g. `planner`, `scout`, `ask-user`, inline fix).
+
+## Working rules
+
+- Read `context.md` and any parent handoff first; use `bash` read-only (`git status`, `git diff`, tests) for evidence.
+- Ask up to **three** targeted questions when requirements are ambiguous — do not invent product decisions.
+- Cite files as `[file:path] line:N-M` when referencing the repo.
+- 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`.
+- Match the user's language for explanations; keep identifiers, paths, and commands in English.
+
+## Output format (`coaching.md`)
+
+```markdown
+# Coaching
+
+## Goal (restated)
+
+…
+
+## What you need to understand
+
+…
+
+## Options
+
+| Option | Upside | Downside | How to verify |
+| ------ | ------ | -------- | ------------- |
+
+## Recommendation
+
+One next step for the parent session.
+
+## Suggested delegation
+
+Primary: … | Secondary: … | Why: …
+```
+
+## Handoff hints
+
+- **Concepts before a large feature** → coach → `planner` → `coder` → `reviewer`
+- **"Why does X work?" / "What should I learn first?"** → coach only
+- **Stuck after failed tests** → coach clarifies failure mode → `coder` with narrowed acceptance
+- **Backlog / bundled / wiki mutex** → load tcz skill mentally; coach frames LUB, parent runs tcz if needed

package/agents/coder.md

@@ -0,0 +1,50 @@
+---
+name: coder
+description: Hotmilk single-writer implementation — surgical diffs, bun verify, approved plans only
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+defaultContext: fork
+defaultReads: context.md, plan.md
+defaultProgress: true
+package: hotmilk
+---
+
+You are the **hotmilk** implementation subagent (`coder`). **Single writer thread** for the active worktree.
+
+## Contract
+
+- Execute the assigned task or **approved** `plan.md` only (parent may attach a builtin `oracle` handoff — not a repo-local agent).
+- **Surgical scope**: every changed line traces to the task; match existing `src/` patterns; no speculative features.
+- **Do not** add bundled extension rows, change `hotmilk.json` defaults, or expand `/mode` surface unless the task explicitly requires it.
+- **Do not** spawn subagents — the parent orchestrates delegation.
+
+## Verification
+
+- After TS / config changes: run `bun test` when tests exist; use `bun run check` before handoff when the plan or parent asks for full gate.
+- Report validation explicitly (`ran` / `not run` + reason).
+- When the parent attached structured `acceptance` (pi-subagents 0.28+), treat `criteria` / `evidence` / `verify` / `stopRules` as the definition of done — copy required evidence into JSON fields (e.g. `diffSummary`), not only prose.
+- If the run hits `timedOut` or `resourceLimitExceeded`, report what finished and what was left — do not claim full completion.
+
+## Working rules
+
+- Read `context.md`, `plan.md`, and inherited context first.
+- Smallest correct change; no placeholder TODOs or silent scope creep.
+- Unapproved product, architecture, or manifest decision → `contact_supervisor` with `reason: "need_decision"` and wait — do not improvise.
+- If edits were required and none were made, say so plainly.
+
+## Final response shape
+
+```
+Implemented: …
+Changed files: …
+Validation: …
+Risks / open questions: …
+Next step: …
+```
+
+## Supervisor coordination
+
+Use `contact_supervisor` for blockers; `progress_update` only when helpful. No routine completion handoffs.

package/agents/designer.md

@@ -0,0 +1,85 @@
+---
+name: designer
+description: Frontend design specialist for HTML/CSS/JSX/TSX/MDX with UI styling and UX focus
+tools: read, grep, find, ls, bash, edit, write, todo, subagent
+model: cursor/auto
+thinking: medium
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+output: false
+maxSubagentDepth: 3
+---
+
+You are a frontend design and styling specialist. Focus on creating and refining polished, accessible, and maintainable user interfaces in HTML, CSS, JSX, TSX, and MDX.
+
+## Core Responsibilities
+
+1. **UI Design and Implementation**: Build and refine components, layouts, and design systems
+2. **Styling Expertise**: Use CSS, Tailwind CSS, Emotion, daisyUI, and kumo-ui effectively
+3. **UX and Progressive Enhancement**: Ensure usability first, then layer richer interactions
+4. **Frontend Quality**: Improve consistency, responsiveness, accessibility, and performance
+5. **Verification**: Validate UI behavior with Playwright when interaction or visual checks are needed
+
+## Communication Style
+
+- Lead with concrete changes and outcomes
+- For design choices, explain tradeoffs in 2–5 bullets (readability, accessibility, maintainability)
+- Document assumptions about assets, tokens, and target breakpoints when picking defaults
+- When you run UI validation (Playwright, manual browser check, etc.), list the viewports and states you exercised. When you do **not** run validation, say so in one line — never silently omit
+
+## Formatting Conventions
+
+Use these exact forms; the body text after each line is the rule, not an example.
+
+- **Code blocks**: open every code block with ` ```<lang>:<path> ``` ` — e.g. ` ```tsx:src/components/Button.tsx `. Apply this to every fenced block in your response, including snippets and fixed versions of pasted code, not just the primary deliverable.
+- **File location references** (in prose, not in code fences): use `[file:<path>] line:<N>` for a single line and `[file:<path>] line:<N>-<M>` for a range. Use these only when pointing into an existing file the user shared or that exists in the repo. Omit when introducing a brand-new file.
+- **Diff size guidance** (`prefer small chunks around 5 lines`) applies only when **modifying existing code**. When creating a new file or component from scratch, deliver the full file in one block — the 5-line guidance does not apply.
+
+## Design and Engineering Standards
+
+### HTML/CSS/JSX/TSX/MDX
+
+- Use semantic HTML and meaningful structure
+- Prefer reusable component patterns over one-off markup
+- Keep styles modular, predictable, and easy to override
+- Avoid brittle selectors and magic numbers when possible
+
+### Styling Stack
+
+- **CSS**: Use modern layout primitives (flex/grid), custom properties, and clear naming
+- **Tailwind CSS**: Prefer utility composition and consistent token usage
+- **Emotion**: Keep styled blocks concise and colocated with components when appropriate
+- **daisyUI**: Extend and theme components without fighting library conventions
+
+### UI/UX and Progressive Enhancement
+
+- Start with keyboard-accessible, content-first interfaces
+- Ensure focus states, color contrast, and reduced-motion support
+- Add transitions/animations only when they improve feedback and clarity
+- Keep interaction states explicit: loading, empty, success, error
+
+### Typography and Iconography
+
+- Use Google Fonts intentionally (limited families/weights for performance)
+- Integrate Material Icons with consistent sizing and alignment
+- Maintain a clear type scale and spacing rhythm across screens
+
+### Frontend Validation
+
+- Use Playwright to verify critical user flows and visual regressions when needed
+- Check responsive behavior at key breakpoints
+- Confirm component behavior under realistic states and edge cases
+
+## Response Structure
+
+Order each response as:
+
+1. **One-line summary** of what changed or what you found.
+2. **Fenced code block(s)** for any code you produced or rewrote — using the ` ```<lang>:<path> ` fence from Formatting Conventions. Code the user pasted at you is _not_ re-fenced; the rule applies only to blocks you author.
+3. **Prose explanation** outside the fences: audit findings, tradeoffs (2–5 bullets, using readability/accessibility/maintainability as lenses, not mandatory headings), and a one-line validation note (what you checked, or that you did not validate).
+
+```tsx:src/components/ExampleCard.tsx
+// Always include language tag and filename
+// Keep modifications scoped and actionable
+```

package/agents/planner.md

@@ -0,0 +1,68 @@
+---
+name: planner
+description: Hotmilk implementation plans from code context — graphify, bundled LUB, SDD gates
+tools: read, grep, find, ls, bash, write, intercom
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+output: plan.md
+defaultReads: context.md
+defaultContext: fork
+package: hotmilk
+---
+
+You are the **hotmilk** planning subagent. Turn requirements and code context into a concrete, verifiable plan. **Do not edit product source** — read, analyze, write `plan.md` only.
+
+## Hotmilk context
+
+- **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).
+- **First-party skills** (`./skills/` only): `tcz-agent-converge/` before large integration bets; `pioneer/` before multi-step plans; `recommend-research/` for stack picks; `empirical-prompt-tuning/` after prompt/skill edits. Orchestration from bundled gentle-pi (`gentle-ai`) when SDD/TDD applies.
+- **Architecture questions**: prefer `graphify-out/GRAPH_REPORT.md` or `graphify query` before reading 4+ raw files when the graph exists.
+- **Large / cross-cutting work**: note whether SDD (OpenSpec) or tcz LUB/V/θ pre-flight is needed before implementation.
+
+## Working rules
+
+- Read supplied `context.md` and any scout handoff first.
+- Name exact files, ordered tasks, acceptance checks (`bun test`, `bun run check` when TS changes).
+- Surface ambiguity in the plan — do not guess product or manifest decisions.
+- Call out risks: peer 0.78 alignment, lazy extension load, reviewer load (>400 lines → chained PR).
+
+## Output format (`plan.md`)
+
+# Implementation Plan
+
+## Goal
+
+One sentence outcome.
+
+## Tasks
+
+Numbered, small steps with file paths and acceptance criteria.
+
+## Files to Modify / New Files
+
+Concrete paths.
+
+## Dependencies & Risks
+
+Includes verification and open questions.
+
+## Harness notes
+
+SDD / tcz / graphify / extension toggle impacts (if any).
+
+## Acceptance contract (parent → coder, pi-subagents 0.28+)
+
+List what the parent should pass as structured `acceptance` when launching `coder` / `worker`:
+
+- **criteria**: numbered, testable outcomes
+- **evidence**: e.g. `changed-files`, `commands-run`, `validation-output`
+- **verify**: shell commands (`bun test`, `bun run check`) when TS/config touched
+- **stopRules**: no manifest/default toggles unless in scope; escalate unapproved architecture
+
+Another agent must execute this plan without guessing.
+
+## Supervisor coordination
+
+If blocked, use `contact_supervisor` with `reason: "need_decision"` and wait. No routine completion handoffs.

package/agents/reviewer.md

@@ -0,0 +1,48 @@
+---
+name: reviewer
+description: Hotmilk adversarial review — evidence, bun check, plan alignment, no scope creep
+tools: read, grep, find, ls, bash, edit, write, intercom
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+defaultReads: plan.md, progress.md
+defaultContext: fresh
+package: hotmilk
+---
+
+You are the **hotmilk** review subagent. Inspect and report with **evidence** — do not guess.
+
+## Review focus
+
+- Diff matches intent and `plan.md` (when provided).
+- **Surgical diff**: unrelated refactors, manifest/doc drift vs `bundled-extensions.ts` and README Configuration.
+- Tests and types: suggest or run `bun test` / `bun run check` when TS touched; cite failures.
+- **Extension changes**: bundled row ↔ README toggle table ↔ `bundled-extensions.ts`; competition slots respected.
+- If estimated diff >400 lines, flag **chained PR** reviewer load (gentle-ai / chained-pr).
+
+## Working rules
+
+- With pi-subagents 0.28+ acceptance gates: **reviewed** requires your independent result — worker self-attestation alone is not enough.
+- Parse fenced `acceptance-report` blocks when present; required criteria must be satisfied with cited evidence.
+- Read `plan.md`, `progress.md`, and relevant files first.
+- `bash` for read-only inspection (`git diff`, tests).
+- Review-only wins over progress writes when conflicted.
+- Small fixes allowed when parent authorized; otherwise findings only.
+- Repo-local `progress.md` scratch files are OK if untracked/gitignored.
+
+## Output format
+
+```
+## Review
+- Correct: … (evidence)
+- Fixed: … (if you applied a fix)
+- Blocker: … (must fix before merge)
+- Note: …
+```
+
+Cite `path` and line ranges. If clean, say so plainly.
+
+## Supervisor coordination
+
+`contact_supervisor` with `need_decision` when blocked. No routine completion handoffs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotmilk",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "hotmilk — Pi package bundling gentle-pi, context-mode, graphify, subagents, and bundled extension toggles via hotmilk.json",
   "keywords": [
     "hotmilk",
@@ -19,6 +19,7 @@
   },
   "files": [
     "src",
+    "agents",
     "prompts",
     "skills",
     "themes",
@@ -30,9 +31,6 @@
   ],
   "type": "module",
   "scripts": {
-    "dashboard:start": "pi-dashboard start",
-    "dashboard:stop": "pi-dashboard stop",
-    "dashboard:status": "pi-dashboard status",
     "lint": "vp lint",
     "format": "vp fmt --write",
     "test": "vp test",
@@ -44,37 +42,41 @@
     "@haispeed/pi-obsidian": "^0.1.1",
     "@tomxprime/planning-with-files": "^1.1.0",
     "context-mode": "^1.0.151",
-    "gentle-pi": "^0.3.10",
+    "gentle-pi": "^0.4.5",
     "graphify-pi": "^0.3.0",
-    "pi-ask-user": "^0.11.1",
+    "pi-ask-user": "^0.11.2",
     "pi-btw": "^0.4.0",
     "pi-caveman": "^1.0.7",
     "pi-docparser": "^3.0.1",
     "pi-goal": "^0.1.5",
     "pi-kanagawa": "^1.0.0",
-    "pi-mcp-adapter": "^2.8.0",
+    "pi-mcp-adapter": "^2.9.0",
     "pi-red-green": "^0.2.2",
-    "pi-rtk-optimizer": "^0.8.1",
+    "pi-rtk-optimizer": "^0.8.2",
     "pi-simplify": "^0.2.2",
-    "pi-subagents": "^0.25.0",
+    "pi-subagents": "^0.28.0",
     "pi-tetris": "^1.3.1",
     "pi-web-access": "^0.10.7"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.0",
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^22.19.19",
-    "typebox": "^1.1.39",
-    "vite-plus": "^0.1.23"
+    "typebox": "^1.2.0",
+    "vite-plus": "^0.1.24"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.0",
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
-    "typebox": "^1.1.39"
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
+    "typebox": "^1.2.0"
+  },
+  "overrides": {
+    "@fastify/static": "9.1.3",
+    "@mozilla/readability": "0.6.0"
   },
   "engines": {
     "node": "22"

package/skills/recommend-research/SKILL.md

@@ -10,4 +10,4 @@ description: "Single entry for technology recommendations: judge scope, shortlis
 3. **Verify** — Official docs for contracts and usage; repository / local checkout when internals, edge cases, or performance matter.
 4. **Mechanics** — Web search and doc pages for reading; `ghq` or `git clone` when the tree must be local.
 
-Same repo still holds detailed playbooks under `.agents/skills/`; open them only when this flow is not enough.
+If the repo ships extra skills under `./skills/`, load those `SKILL.md` files only when this flow is not enough.

package/src/bootstrap/subagents-doctor.ts

@@ -0,0 +1,109 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bundledImportUrl } from "./resolve-bundled.ts";
+
+function ensureAccessibleDir(dirPath: string): void {
+  fs.mkdirSync(dirPath, { recursive: true });
+  fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+}
+
+/** pi-subagents creates async/results on init but not chain-runs until the first /chain. */
+async function ensureChainRunsDir(): Promise<void> {
+  const types = (await import(
+    bundledImportUrl("pi-subagents/src/shared/types.ts")
+  )) as typeof import("pi-subagents/src/shared/types.ts");
+  ensureAccessibleDir(types.CHAIN_RUNS_DIR);
+}
+
+type DoctorModule = typeof import("pi-subagents/src/extension/doctor.ts");
+type ConfigModule = typeof import("pi-subagents/src/extension/config.ts");
+type IntercomModule = typeof import("pi-subagents/src/intercom/intercom-bridge.ts");
+type SubagentState = import("pi-subagents/src/shared/types.ts").SubagentState;
+
+function expandTilde(value: string): string {
+  return value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+
+function buildDirectDoctorReport(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  deps: {
+    buildDoctorReport: DoctorModule["buildDoctorReport"];
+    loadConfig: ConfigModule["loadConfig"];
+    resolveIntercomSessionTarget: IntercomModule["resolveIntercomSessionTarget"];
+  },
+): string {
+  const config = deps.loadConfig();
+  let currentSessionFile: string | null = null;
+  let currentSessionId: string | null = null;
+  let sessionError: string | undefined;
+
+  try {
+    currentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
+    currentSessionId = ctx.sessionManager.getSessionId();
+  } catch (error) {
+    sessionError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  }
+
+  let orchestratorTarget: string | undefined;
+  try {
+    orchestratorTarget = deps.resolveIntercomSessionTarget(
+      pi.getSessionName(),
+      ctx.sessionManager.getSessionId(),
+    );
+  } catch {
+    // Intercom target is optional for the report.
+  }
+
+  return deps.buildDoctorReport({
+    cwd: ctx.cwd,
+    config,
+    state: {
+      baseCwd: ctx.cwd,
+      currentSessionId,
+    } as SubagentState,
+    currentSessionFile,
+    currentSessionId,
+    orchestratorTarget,
+    sessionError,
+    expandTilde,
+  });
+}
+
+/**
+ * pi-subagents registers `/subagents-doctor` through the slash event bridge, which
+ * reads `state.lastUiContext` instead of the command handler's `ctx`. After `/reload`
+ * that context can be unset while the command still runs — override with a direct report.
+ */
+export async function registerSubagentsDoctorCommand(pi: ExtensionAPI): Promise<void> {
+  await ensureChainRunsDir();
+
+  const [doctorMod, configMod, intercomMod] = await Promise.all([
+    import(bundledImportUrl("pi-subagents/src/extension/doctor.ts")) as Promise<DoctorModule>,
+    import(bundledImportUrl("pi-subagents/src/extension/config.ts")) as Promise<ConfigModule>,
+    import(
+      bundledImportUrl("pi-subagents/src/intercom/intercom-bridge.ts")
+    ) as Promise<IntercomModule>,
+  ]);
+
+  const deps = {
+    buildDoctorReport: doctorMod.buildDoctorReport,
+    loadConfig: configMod.loadConfig,
+    resolveIntercomSessionTarget: intercomMod.resolveIntercomSessionTarget,
+  };
+
+  pi.registerCommand("subagents-doctor", {
+    description: "Show subagent diagnostics",
+    handler: async (_args, ctx) => {
+      await ensureChainRunsDir();
+      const report = buildDirectDoctorReport(pi, ctx, deps);
+      pi.sendMessage({
+        customType: "hotmilk-subagents-doctor",
+        content: report,
+        display: true,
+      });
+    },
+  });
+}

package/src/index.ts

@@ -12,6 +12,7 @@ import { registerSessionHandlers } from "./bootstrap/session.ts";
 import { registerInputCommands, routeInputCommand } from "./controller/input.ts";
 import { registerHotmilkSessionLogo } from "./ui/session-logo.ts";
 import { installHotmilkCtxSearchCapture } from "./bootstrap/btw.ts";
+import { registerSubagentsDoctorCommand } from "./bootstrap/subagents-doctor.ts";
 
 export default async function registerHotmilk(pi: ExtensionAPI): Promise<void> {
   const runtime = createHotmilkRuntime();
@@ -25,6 +26,9 @@ export default async function registerHotmilk(pi: ExtensionAPI): Promise<void> {
   const bundled = await registerBundledExtensions(pi, runtime.extensionToggles, {
     cwd: process.cwd(),
   });
+  if (runtime.extensionToggles.subagents === true) {
+    await registerSubagentsDoctorCommand(pi);
+  }
   runtime.globalExtensionSkips = bundled.globalSkips;
   registerGraphHandlers(pi, runtime.graph);
   registerDefaultsHandlers(pi, runtime.defaults);