hotmilk 0.1.13 → 0.1.15

package/skills/pioneer/SKILL.md

@@ -1,176 +1,180 @@
 ---
 name: pioneer
-description: End-to-end pion workflow — graphify recon, optional goal, grill-with-docs interview, structured Plan, then execute. Use for architecture planning, /grill, /goal, graphify-out questions, or before multi-step implementation.
+description: End-to-end pioneer hotmilk workflow — graphify recon (phase 0), optional goal, grill-with-docs interview, chat Plan, Plannotator, planning-with-files, OpenSpec/SDD, autoresearch optimize loops, observational-memory for long sessions, shazam execute-time structure guards, then execute. Use for pioneer, architecture planning, bundled extension manifest work, hotmilk.json defaults, bundled-extensions.ts, /grill, /goal, /plannotator, /autoresearch, shazam_impact, graphify-out questions, openspec work, chat plan, compaction continuity, or before multi-step implementation.
 ---
 
 # Pioneer (graph → goal → grill → plan → execute)
 
-Single orchestration skill for **pion** read-only planning and execution. It combines:
+Single orchestration skill for **hotmilk** planning and execution.
+
+## Scenario router (read first)
+
+| User signal                                                     | Route                                                                                                                                                                     |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Turn-1 plan request, non-trivial scope                          | Phase 0 → Phase 3; skip grill unless one blocking term                                                                                                                    |
+| One-file typo / known single-file fix                           | Chat Plan; skip Phase 0–2                                                                                                                                                 |
+| Medium scope + human plan approval                              | Phase 0 → Plannotator (`extensions.plannotator: true`)                                                                                                                    |
+| Heavy research, long session, `/clear` recovery                 | planning-with-files (`extensions.planning-with-files: true`)                                                                                                              |
+| SDD request, cross-cutting, or medium+ bundled manifest work    | Phase 0 → OpenSpec (`gentle-ai` required) — see **Bundled extension scope**                                                                                               |
+| Measure/optimize loop, benchmark regression, tune metric        | `/skill:autoresearch-create` (`extensions.autoresearch: true`); **not** a plan path — mutually exclusive with SDD/plan for same task                                      |
+| Long session, frequent compactions, preserve decision rationale | `extensions.observational-memory: true` — background memory; **not** plan authority — see [`observational-memory-routing.md`](references/observational-memory-routing.md) |
+| Shared-module edit, blast radius, post-edit LSP verify          | `extensions.shazam: true` — execute-time structure; **not** Phase 0 recon — see [`shazam-routing.md`](references/shazam-routing.md)                                       |
+| Skill or prompt edit just completed                             | `/prompt-eval <path>` before ship                                                                                                                                         |
 
-| Layer       | Source                                    | Role                                                                |
-| ----------- | ----------------------------------------- | ------------------------------------------------------------------- |
-| **Graph**   | `/skill:graphify` (bundled `graphify-pi`) | Codebase map before broad search                                    |
-| **Goal**    | pion `/goal`, `get_goal`, `update_goal`   | Multi-turn objective (optional)                                     |
-| **Grill**   | `/skill:grill-with-docs`                  | One question, CONTEXT/ADR, recommended answers                      |
-| **Plan**    | pion `Plan:` + `[DONE:n]`                 | Structured steps with verification                                  |
-| **Execute** | `/pion-execute`                           | Writes + doc proposals; `/skill:tdd-guard` + `/skill:tdd` for tests |
+| Layer         | Delegate to                                                                    | Role                                                          |
+| ------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| **Graph**     | `/skill:graphify`                                                              | Codebase map before broad search                              |
+| **Structure** | pi-shazam (bundled, default off)                                               | Impact / verify during execute — not graph replacement        |
+| **Goal**      | pi-goal (bundled)                                                              | Multi-turn objective (optional)                               |
+| **Grill**     | `/skill:grill-with-docs`                                                       | One question, CONTEXT/ADR, recommended answers                |
+| **Plan**      | chat `Plan:` **or** Plannotator **or** planning-with-files **or** OpenSpec SDD | Light chat; approval gate; file memory; substantial spec work |
+| **Execute**   | **`/skill:gentle-ai`** + subagents                                             | Implement, verify; SDD phases when active                     |
 
-Load this skill when the user plans work in pion, asks how modules relate, or runs `/grill` / `/pion-grill` / `/goal` in the same session.
+**References:** Do **not** read `references/` unless a phase below applies. Each reference states its load trigger at the top.
 
-## Phase map
+## Runtime
 
-```text
-0. Graph recon (if graphify-out exists)     — read-only
-1. Goal (optional)                          — /goal when work spans many turns
-2. Grill (when scope/terms unclear)         — /pion-grill or /grill <task>
-3. Plan                                     — Context / Assumptions / Tradeoffs / Risks + Plan:
-4. Execute                                  — /pion-execute, [DONE:n], apply Proposed docs
-```
+hotmilk bundles **gentle-ai**, **graphify**, **pi-goal**, **pi-subagents**. Toggle via `/mode` + `/reload`. Verify commands: **`AGENTS.md`** (`bun test`, `bun run check`).
 
-Skip phases that do not apply. Do not grill when the graph + CONTEXT already answer the question.
+| Toggle                            | Pioneer note                                                                                 |
+| --------------------------------- | -------------------------------------------------------------------------------------------- |
+| `extensions.graphify`             | Phase 0; `graphify-out/` when built — off → graph-recon-gate fallback                        |
+| `extensions.shazam`               | Phase 4 impact/verify (`shazam_*`); default off; complements graphify — not recon substitute |
+| `extensions.goal`                 | Phase 1; `/goal`, `get_goal`, `update_goal`                                                  |
+| `extensions.gentle-ai`            | OpenSpec path; off → Chat Plan + direct execute only                                         |
+| `extensions.plannotator`          | Phase 3 approval gate; `/plannotator`, `--plan`; off → Chat Plan or OpenSpec                 |
+| `extensions.planning-with-files`  | On-disk `task_plan` / `findings` / `progress`; off → skip file-memory path                   |
+| `extensions.autoresearch`         | Optimize loop (`/autoresearch`, `.auto/`); off → one-shot Chat Plan + benchmark in `verify:` |
+| `extensions.context-mode`         | Prefer `ctx_*` for large outputs; pairs with observational-memory for long sessions          |
+| `extensions.observational-memory` | Compaction continuity (observations/reflections); default off; not plan authority            |
+| `extensions.rtk-optimizer`        | Bash/read output compaction with context-mode                                                |
+| `extensions.subagents`            | Phase 4 delegation; off → inline execute                                                     |
 
----
+**Skill dependencies** (`/skill:graphify`, `/skill:grill-with-docs`, `/skill:tdd`, `/skill:gentle-ai`) may live in bundled packages or global Pi config.
 
-## Phase 0 — Graph recon (graphify)
+### Skill resolution ladder
 
-**Before** wide `grep` / reading many files, check graph artifacts in the project cwd:
+When a `/skill:*` path is missing, resolve in order — stop at first hit. Announce which step forced a behavior change.
 
-1. `graphify-out/wiki/index.md` — prefer for navigation when sufficient
-2. `graphify-out/GRAPH_REPORT.md` — god nodes, surprising connections, suggested questions
-3. `graphify-out/graph.json` — fallback for paths and communities
+| Step | Check               | Action                                                                    |
+| ---- | ------------------- | ------------------------------------------------------------------------- |
+| 1    | Hotmilk first-party | Search `./skills/*/SKILL.md` for the same skill name                      |
+| 2    | Bundled package     | Search `node_modules/*/skills/` and `.pi/skills/` for the same skill name |
+| 3    | Global Pi config    | `~/.pi/agent/skills/`, `~/.claude/skills/`, `~/.agents/skills/`           |
+| 4    | Project fallback    | `AGENTS.md` commands only; say which `/skill:*` was unavailable           |
 
-**When to use graph commands** (see `/skill:graphify` for full CLI):
+Path-specific fallbacks when step 4 hits:
 
-| Question type            | Command                                                 |
-| ------------------------ | ------------------------------------------------------- |
-| How does X relate to Y?  | `graphify query "…" --graph graphify-out/graph.json`    |
-| Shortest dependency path | `graphify path "A" "B" --graph graphify-out/graph.json` |
-| What is node X?          | `graphify explain "X" --graph graphify-out/graph.json`  |
+- **`/skill:gentle-ai`** + `extensions.gentle-ai: false` → Chat Plan + direct execute only (OpenSpec forbidden)
+- **`/skill:graphify`** → [`graph-recon-gate.md`](references/graph-recon-gate.md) **Fallback when graph is missing**
+- **`/skill:grill-with-docs`** → skip Phase 2; fix terms in Phase 3 **Assumptions**; one blocking chat question max
 
-Rules:
+### Toggle-off ladder
 
-- Answer from graph output; do not invent edges or source paths.
-- If the graph gives an exact path, use it; otherwise one narrow lookup, then read that file.
-- If `graphify-out/needs_update` exists or code changed this session, say the graph may be stale; suggest `graphify update .` before trusting modified areas.
-- No `graphify-out/`? Skip this phase or offer a build (`graphify .`) only if the user wants a map.
+When a capability is disabled via `/mode`, fall back — do not invoke missing tools or paths.
 
-Use graph **suggested questions** to seed grill topics (cross-community bridges).
+| Toggle off                               | Phase impact        | Fallback                                                                                           |
+| ---------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
+| `extensions.graphify: false`             | Phase 0             | [`graph-recon-gate.md`](references/graph-recon-gate.md) **Fallback when graph is missing** ladder  |
+| `extensions.goal: false`                 | Phase 1             | Skip `/goal`; objective in Assumptions or proposal — see [`goal-gate.md`](references/goal-gate.md) |
+| `extensions.gentle-ai: false`            | OpenSpec path       | **Forbidden** — Chat Plan + direct execute only; say SDD requires gentle-ai                        |
+| `extensions.plannotator: false`          | Plannotator path    | Chat Plan or OpenSpec per routing; say approval gate skipped                                       |
+| `extensions.planning-with-files: false`  | File-memory path    | Skip PWF; use Chat Plan, Plannotator, or OpenSpec                                                  |
+| `extensions.autoresearch: false`         | Optimize loop       | Chat Plan + explicit benchmark `verify:`; say autoresearch unavailable                             |
+| `extensions.observational-memory: false` | Long-session memory | Say OM unavailable; use PWF for `/clear` recovery or context-mode for corpus                       |
+| `extensions.shazam: false`               | Structure guards    | Say shazam unavailable; graphify + read/grep + tests in `verify:`                                  |
+| `extensions.subagents: false`            | Phase 4             | Inline execute; no `subagent` tool — say delegation skipped                                        |
+| grill-with-docs unavailable              | Phase 2             | Skip grill; terms in **Assumptions**; one blocking chat question max                               |
 
----
+### Composite toggle-off matrix
 
-## Phase 1 — Goal (optional)
+When **multiple** toggles are off, apply rows in order — first matching row wins. Announce which composite row forced the path.
 
-Use when the task is not a single plan but a **session-long objective** (feature, migration, investigation).
+| Toggles off                            | Plan path        | Phase impact                                              | Fallback                                                                                                   |
+| -------------------------------------- | ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `graphify` + `gentle-ai`               | Chat Plan only   | Phase 0 → graph-recon fallback ladder; OpenSpec forbidden | [`graph-recon-gate.md`](references/graph-recon-gate.md) **Fallback when graph is missing**; direct execute |
+| `gentle-ai` + `subagents`              | Chat Plan only   | Phase 4 inline only; OpenSpec forbidden                   | No SDD; no `subagent` tool — say both skipped                                                              |
+| `graphify` + `subagents`               | Either plan path | Phase 0 fallback; Phase 4 inline                          | Graph ladder + inline execute; say delegation skipped                                                      |
+| `goal` + `graphify`                    | Either plan path | Skip Phase 1; Phase 0 fallback                            | Objective in Assumptions; graph-recon fallback ladder                                                      |
+| `graphify` + `gentle-ai` + `subagents` | Chat Plan only   | Phase 0 fallback; Phase 4 inline                          | Graph ladder + inline execute; OpenSpec forbidden                                                          |
 
-| Action                  | Command / tool                                                                           |
-| ----------------------- | ---------------------------------------------------------------------------------------- |
-| Set objective           | `/goal <text>` or `update_goal`                                                          |
-| Check progress          | `get_goal`                                                                               |
-| Pause during plan/grill | automatic — pion suppresses `agent_end` auto-continue while plan/grill/execute is active |
-| Resume after plan work  | `/goal resume`                                                                           |
+Say which toggle or missing skill forced the fallback when it changes the chosen path.
 
-Align the goal text with what the grill and `Plan:` will deliver. After `/pion-execute`, mark goal progress in `update_goal` when milestones complete.
+## Plan routing (one authority per task)
 
----
+Choose **one** plan target per task:
 
-## Phase 2 — Grill (grill-with-docs)
+| Path                    | When                                                                               | Artifact                                     | Reference                                                                                   |
+| ----------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **Chat Plan**           | Small, bounded, known context, single area, quick fix                              | `Plan:` in chat                              | [`references/chat-plan.md`](references/chat-plan.md)                                        |
+| **Plannotator**         | Medium scope, human browser approval, bounded checklist execution                  | `plans/*.md` + approval                      | [`references/plannotator-routing.md`](references/plannotator-routing.md)                    |
+| **planning-with-files** | Heavy research, parallel tracks, session recovery after `/clear`                   | `task_plan.md`, `findings.md`, `progress.md` | `/skill:planning-with-files` (bundled when toggled on)                                      |
+| **OpenSpec SDD**        | Large, ambiguous, architectural, cross-cutting, high review risk, or user asks SDD | `openspec/changes/<change>/`                 | [`references/openspec-routing.md`](references/openspec-routing.md) + **`/skill:gentle-ai`** |
 
-Enter when terminology, scope, or trade-offs are unclear — even after graph recon.
+Say which path you chose and why. Do not mix plan authorities unless the user explicitly layers them (e.g. SDD tasks → Plannotator gate).
 
-**Start:** `/pion-grill`, `/grill <task>`, or `/pion` + load `/skill:grill-with-docs`.
+**Memory layers (not plan paths):** compaction rationale and session continuity → **`observational-memory`** when toggle on — see [`references/observational-memory-routing.md`](references/observational-memory-routing.md). Corpus / large output → **context-mode**. Execute-time structure (impact, LSP verify) → **`shazam`** when toggle on — see [`references/shazam-routing.md`](references/shazam-routing.md). Do not treat OM or shazam as spec or plan authority.
 
-**Strict rules** (details in grill-with-docs skill):
+**Optimize loop (not a plan path):** when success = measurable metric with keep/discard iterations → **`/skill:autoresearch-create`** — see [`references/autoresearch-routing.md`](references/autoresearch-routing.md). Do not start Chat Plan, Plannotator, or OpenSpec for the same task unless the user pivots to feature delivery.
 
-- **One question per turn** + **recommended answer**; wait for the user.
-- Recon: `CONTEXT-MAP.md` when present, then the relevant `CONTEXT.md`; ADRs under `docs/adr/` and `extensions/pion/docs/adr/` (formats in `skills/grill-with-docs/references/`).
-- Cross-check user claims against code; sharpen vague terms against the glossary.
-- Read-only: emit `## Proposed CONTEXT.md` / `## Proposed ADR` in chat — no `edit`/`write`.
-- Do **not** output `Plan:` until grilling is done or the user asks (e.g. "プラン出して").
+**Tie-breaker (gray zone):** scope is medium or ~2 files but not clearly trivial → **OpenSpec** when **any** of: cross-cutting, review budget >400 changed lines, 2+ areas/modules, architectural/product ambiguity, or **medium+ bundled manifest work** (new bundled row + dep + README + tests, or default toggle changes across `bundled-extensions.ts` and `hotmilk.json` — not a one-line typo). **Plannotator** when human approval is the primary goal and spec artifacts are not required. **planning-with-files** when research volume or `/clear` recovery dominates. Otherwise **Chat Plan**. If `extensions.gentle-ai: false`, OpenSpec is forbidden — Chat Plan or Plannotator only.
 
-**Graph + grill:** Use GRAPH_REPORT god nodes / surprising connections as grill fuel ("this edge implies X — is that still true?").
+**MANDATORY - READ ENTIRE FILE** the reference for your chosen path before emitting `Plan:`, starting `/plannotator`, or starting SDD work.
 
----
+### Bundled extension scope
 
-## Phase 3 — Plan
+When the task adds, removes, or reconfigures a bundled extension, resolve in Assumptions (chat) or proposal (SDD):
 
-Emit only when grill is sufficient or the user requests a plan.
+| Topic                    | Pin                                                                                                |
+| ------------------------ | -------------------------------------------------------------------------------------------------- |
+| Extension id             | kebab-case row in `src/config/bundled-extensions.ts` — **not** `package.json` → `pi.extensions`    |
+| Edit scope               | Manifest row + `hotmilk.json` default + `package.json` dep + README; lazy load via `extensions.ts` |
+| Auth / integration scope | OAuth, MCP, external API: state secrets, env, approval — default **no** new auth unless required   |
+| Missing package          | Dependency install/version as explicit step; no speculative toggle defaults                        |
 
-### Required shape
-
-```markdown
-## Context
-
-## Assumptions
-
-## Tradeoffs
+## Phase map
 
-## Risks
+Skip phases that do not apply. Do not grill when graph + CONTEXT already answer the question.
 
-Plan:
+**Plan on turn 1:** First message asks for a plan and scope is not trivial → Phase 3 after Phase 0; skip grill unless one blocking term remains.
 
-1. … — verify: …
-2. …
+```text
+0. Graph recon          → **MANDATORY - READ ENTIRE FILE** graph-recon-gate.md
+1. Goal (optional)      → **MANDATORY - READ ENTIRE FILE** goal-gate.md (when Phase 1 applies)
+2. Grill (if unclear)   → /skill:grill-with-docs; one question/turn
+   skip when graph+CONTEXT suffice or grill-with-docs unavailable
+3. Plan                 → **MANDATORY - READ ENTIRE FILE** chat-plan.md OR plannotator-routing.md OR planning-with-files skill OR openspec-routing.md (+ gentle-ai for SDD)
+4. Execute              → gentle-ai Work Routing Ladder (chat-plan Execute or SDD /sdd-continue)
+   When shazam on      → shared-module edits: shazam_impact → edit → shazam_verify (+ tests)
+   Alt: Optimize loop    → **MANDATORY - READ ENTIRE FILE** autoresearch-routing.md + `/skill:autoresearch-create` (replaces Phase 3–4 for metric loops)
+5. Prompt hardening     → **MANDATORY - READ ENTIRE FILE** prompt-eval-gate.md (edits-only: before ship; mixed: after Phase 4)
 ```
 
-### Step ordering
-
-1. Apply any `## Proposed CONTEXT.md` / `## Proposed ADR` from grill (or reference them as first steps).
-2. Recon / design steps informed by graph paths and communities.
-3. Implementation steps with concrete `verify:` checks (test, command, file exists, behavior).
-
-### Persist plan file (chezmoi / multi-context repos)
-
-When the chezmoi repo (or any project with `CONTEXT-MAP.md`) is the cwd:
-
-- At **plan finalization**, write **`docs/plans/<slug>.md`** with the same `## Context` … `Plan:` content (kebab-case slug).
-- Chat `Plan:` remains the pion step tracker (`[DONE:n]` after `/pion-execute`).
-- Only `docs/plans/*.md` may be written while plan mode is ON; CONTEXT / ADR / code wait for `/pion-execute`.
-
-While pion is ON: **no** `edit`; **no** `write` except `docs/plans/<slug>.md` at finalize. Refine with `/pion-refine`.
-
----
-
-## Phase 4 — Execute
-
-**Start:** `/pion-execute` (restores write tools; may enable `get_goal` / `update_goal` in tool set).
-
-- Work steps in order; tag completed steps with `[DONE:n]` in the response.
-- Sync CONTEXT/ADR and **doc patches** from grill (bootstrap or drift fixes) before code when proposed.
-- For test work: load **`/skill:tdd`** then **`/skill:tdd-guard`** (plan testlist if missing, then one cycle at a time).
-- After large code changes, mention `graphify update .` if the project uses graphify.
-- Interrupt: `/pion-interrupt` (steer). Stop: `/pion-stop` (abort, exit execute mode).
-- Unfinished steps: `/pion-todos`.
-
 ---
 
-## Commands (quick reference)
-
-| Command                                | Phase                                            |
-| -------------------------------------- | ------------------------------------------------ |
-| `/pion`                                | Toggle plan mode (read-only)                     |
-| `/pion-grill`, `/grill <task>`         | Grill only                                       |
-| `/pion-refine`                         | Adjust plan (read-only)                          |
-| `/pion-execute`                        | Execute                                          |
-| `/pion-stop`, `/pion-interrupt`        | Control during execute                           |
-| `/pion-todos`                          | Remaining plan steps                             |
-| `/goal`, `/goal pause`, `/goal resume` | Goal                                             |
-| `/graphify …`                          | Delegates to graphify skill (build/query/update) |
-
 ## Anti-patterns
 
-| Do not                                                      | Do instead                                                 |
-| ----------------------------------------------------------- | ---------------------------------------------------------- |
-| `Plan:` before glossary/scope stable                        | Keep grilling                                              |
-| Multiple grill questions in one message                     | One question + recommended answer                          |
-| Broad grep ignoring `graphify-out/`                         | Graph recon first                                          |
-| Invent graph edges or paths                                 | `graphify query` / say "graph lacks …"                     |
-| Implementation detail in proposed CONTEXT                   | Glossary and decisions only                                |
-| `edit` or `write` outside `docs/plans/` while plan/grill ON | `/pion-execute` (plan file at finalize is OK in plan mode) |
-| Ignore active `/goal`                                       | Read `get_goal`; update when done                          |
-
-## Related skills
-
-- **`/skill:grill-with-docs`** — grill + doc bootstrap/sync (replaces make-docs / update-docs)
-- **`/skill:tdd`** — canonical TDD philosophy (load first)
-- **`/skill:tdd-guard`** — test planning + cycle guardrails (replaces tdd-cycle / testcase)
-- **`/skill:graphify`** — build, update, query, MCP, watch, merge graphs
+| Do not                                                 | Why                                                    | Do instead                                                                                                                                    |
+| ------------------------------------------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Read `references/` without a matching path             | Wastes tokens; loads wrong workflow                    | Load only when Phase 0, Phase 1, Chat Plan, Plannotator, OpenSpec, autoresearch, observational-memory, shazam, or Phase 5 prompt-eval applies |
+| Ship skill/prompt edits without prompt-eval            | Author blind spot; stale triggers survive              | Phase 5 → prompt-eval-gate → `/prompt-eval <path>`                                                                                            |
+| Downgrade active SDD to Chat Plan mid-flow             | Artifact drift; verify/sync never run                  | Stop; tell user gentle-ai required; resume SDD after toggle on — see openspec-routing **Mid-flow recovery**                                   |
+| OpenSpec when `gentle-ai` is off                       | SDD commands unavailable; path breaks mid-flow         | Chat Plan only; say toggle must enable gentle-ai for SDD                                                                                      |
+| Ignore toggle-off ladder                               | Calls missing tools; false confidence in SDD/subagents | Use toggle-off table; announce fallback                                                                                                       |
+| `Plan:` before scope stable (user did not ask)         | Premature plan hides glossary gaps                     | Keep grilling; user asks → Plan with open items in Assumptions                                                                                |
+| OpenSpec for a one-file typo                           | SDD overhead wastes review budget                      | Chat Plan + direct implement                                                                                                                  |
+| Chat Plan for cross-cutting architecture               | Chat plan lacks artifact gates                         | OpenSpec SDD + `/sdd-continue`                                                                                                                |
+| Plannotator + OpenSpec as dual plan authorities        | Two sources of truth                                   | SDD for spec; Plannotator gates tasks or execution only                                                                                       |
+| Plannotator + planning-with-files same plan file       | Schema and hook conflict                               | Separate paths: `plans/` vs `.planning/`                                                                                                      |
+| Chat Plan mid-task then Plannotator for same scope     | Context split                                          | Pick one path at Phase 3                                                                                                                      |
+| Autoresearch + SDD or Plannotator same task            | Conflicting authorities (loop vs gates)                | Pick autoresearch **or** plan path; `/autoresearch off` before switching                                                                      |
+| OpenSpec or Plannotator mid-active autoresearch loop   | Metric loop never converges to shippable contract      | Stop loop; finalize or clear `.auto/`; then start plan path                                                                                   |
+| Multiple grill questions in one message                | User cannot answer precisely; violates grill-with-docs | One question + recommended answer                                                                                                             |
+| Grill without grill-with-docs loaded                   | Skill rules violated; multi-question drift             | Skip Phase 2 or load skill; terms in Assumptions                                                                                              |
+| Broad grep ignoring `graphify-out/`                    | Misses graph-cached structure                          | Graph recon first (graph-recon-gate)                                                                                                          |
+| `shazam_overview` instead of graphify for architecture | No persistent graph; wrong layer                       | Phase 0 graphify; shazam only in Phase 4 execute                                                                                              |
+| Treat OM reflections as SDD spec                       | Hidden plan authority                                  | OpenSpec artifacts remain source of truth                                                                                                     |
+| Invent graph edges or paths                            | False architecture confidence                          | `graphify query` / say "graph lacks …"                                                                                                        |
+| Implementation detail in proposed CONTEXT              | CONTEXT is glossary/decisions, not design doc          | Glossary and decisions only                                                                                                                   |
+| Skip SDD verify/sync                                   | Artifacts drift from shipped code                      | OpenSpec path → **`/skill:gentle-ai`** through archive                                                                                        |
+| Ignore active `/goal`                                  | Session objective diverges from work                   | Read `get_goal`; update when done                                                                                                             |

package/skills/pioneer/references/autoresearch-routing.md

@@ -0,0 +1,114 @@
+# Autoresearch (optimize loop)
+
+**Load when:** the task is a **measure → edit → benchmark → keep/discard** loop, not a one-shot feature or spec-driven build.
+
+**Do NOT load when:** Chat Plan, Plannotator, planning-with-files, or OpenSpec SDD is the chosen plan authority — use the matching reference instead.
+
+**Canonical matrix:** [README § Workflow routing](../../../README.md#workflow-routing).
+
+## When to use
+
+| Signal                                                                             | Route here                                                                            |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| User asks to optimize, benchmark, tune, or run experiments in a loop               | `/skill:autoresearch-create`                                                          |
+| Success = measurable metric (test time, bundle size, loss, Lighthouse, build time) | Autoresearch                                                                          |
+| User invokes `/autoresearch`, mentions `.auto/`, or wants keep/discard iterations  | Autoresearch                                                                          |
+| Feature delivery, spec, architecture, cross-cutting change                         | OpenSpec / gentle-ai — **not** autoresearch                                           |
+| Human plan approval before any writes                                              | Plannotator — **not** autoresearch as plan authority                                  |
+| Strict RED→GREEN test-first for a known fix                                        | `/skill:tdd` or `/tdd` — **not** autoresearch unless optimizing the test suite itself |
+
+**Tie-breaker vs plan paths:** optimization target with a metric → autoresearch; delivery with acceptance criteria and review gates → plan path (Chat / Plannotator / PWF / SDD).
+
+## 向く / 向かない (suited vs not suited)
+
+Inspired by [Armin Ronacher — _The Coming Loop_](https://lucumr.pocoo.org/2026/6/23/the-coming-loop/) (2026-06-23): agent loops excel when the harness can **measure** progress; they degrade long-lived code when judgment is outsourced to the loop alone.
+
+| 向く (use autoresearch)                                                      | Why                                               | 向かない (use another path)                      | Why                                                                      |
+| ---------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
+| Metric optimization (build time, bundle size, benchmark score, test runtime) | Machine-verifiable keep/discard signal            | Feature delivery with acceptance criteria        | Needs spec, review gates, human product judgment → **SDD / Plannotator** |
+| Mechanical transforms (port, migration, bulk rename) with binary pass/fail   | Clear invariant; loop replaces tedious repetition | Cross-cutting architecture or manifest work      | Many files + contract risk → **OpenSpec SDD**                            |
+| Experiment exploration (hyperparams, perf knobs, algorithm variants)         | Short-lived tries; best branch wins               | Long-lived production module, hands-off for days | Defensive layers stack; comprehension drops → **SDD + phased apply**     |
+| Security scan / dependency triage loops                                      | Verifiable findings; bounded artifact             | “Make it work” without a measure command         | No metric → **Chat Plan** with explicit `verify:` or **TDD**             |
+| Research / PoC where discard is cheap                                        | `.auto/` and branches are disposable              | Production bugfix with one known root cause      | Single shot + tests → **TDD** or inline fix                              |
+| Optimizing the test suite or CI itself                                       | Metric = test time, flake rate, coverage gate     | Same task also needs proposal/spec/design        | Dual authority → pick **SDD** _or_ autoresearch, not both                |
+
+**Harness takeaway:** autoresearch is the **outer optimize loop** (queue → measure → keep/revert). Pair with graphify recon before starting; return human judgment via **finalize** + PR review — do not treat the loop as “done” without a human or phase gate on merge.
+
+## Prerequisites
+
+| Requirement | Check                                                                                                                 |
+| ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| Toggle      | `extensions.autoresearch: true` — if off, say loop unavailable; do not fake the workflow                              |
+| Extension   | `pi-autoresearch` loaded via `/reload` after `/mode`                                                                  |
+| Skills      | `autoresearch-create` (start), `autoresearch-finalize` (clean branches), `autoresearch-hooks` (optional side effects) |
+| Workspace   | Writes under `.auto/` (`prompt.md`, `log.jsonl`, session state) — add `.auto/` to `.gitignore` if missing             |
+
+## Workflow
+
+```text
+1. Confirm metric, direction (lower/higher), and measure command
+2. /skill:autoresearch-create → init_experiment + session files
+3. Loop: propose change → run_experiment → log_experiment (keep or revert)
+4. /autoresearch export for live dashboard (optional)
+5. When done: /skill:autoresearch-finalize for reviewable branches
+```
+
+## Coexistence matrix
+
+| Layer                       | Autoresearch                             | Notes                                                                                                                             |
+| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **gentle-ai SDD**           | **Mutually exclusive** for the same task | SDD = phased spec/apply/verify; autoresearch = unbounded optimize loop. Pick one authority.                                       |
+| **gentle-ai inline/worker** | OK after loop                            | Use subagents for isolated tries; do not run SDD phases mid-loop                                                                  |
+| **Plannotator**             | **Do not combine** as dual authority     | Approve a plan, then autoresearch only if metric loop is a separate follow-up task                                                |
+| **planning-with-files**     | Rare overlap                             | PWF for research notes; autoresearch for benchmark loop — separate dirs (`.planning/` vs `.auto/`)                                |
+| **red-green / TDD**         | Different jobs                           | TDD = correctness-first test cycle; autoresearch = metric optimization. Use TDD inside a loop only when the metric is test-driven |
+| **pi-goal**                 | OK                                       | Goal = north star; autoresearch = tactical iterations toward metric                                                               |
+| **graphify**                | OK before loop                           | Phase 0 recon still applies when codebase map reduces bad experiments                                                             |
+
+## Execute (vs Phase 4)
+
+Autoresearch **replaces** pioneer Phase 3–4 when the task is optimize-only:
+
+```text
+Phase 0 graph (optional) → autoresearch-create → loop until metric plateaus or user stops
+```
+
+Do **not** emit `Plan:` or start SDD for the same scope unless the user pivots to feature delivery.
+
+## gentle-ai guardrails
+
+When `extensions.gentle-ai: true` and autoresearch is active:
+
+- Do not start `/sdd-continue` or OpenSpec apply for the same change name.
+- Prefer **inline or worker** execution inside the loop; avoid review-budget gates every iteration.
+- Turn autoresearch **off** (`/autoresearch off`) before switching to SDD or Plannotator on the same task.
+
+## Shortcuts and UI
+
+Default shortcut: `Ctrl+Shift+F` (fullscreen dashboard). Override in `~/.pi/agent/extensions/pi-autoresearch.json`:
+
+```json
+{
+  "shortcuts": {
+    "fullscreenDashboard": "ctrl+shift+y"
+  }
+}
+```
+
+Use `null` to disable a shortcut. Off by default in hotmilk — widget + shortcuts add session weight.
+
+## Fallback when autoresearch is off
+
+- Say **"Autoresearch skipped: extension off"**
+- One-shot optimize → Chat Plan with explicit `verify:` benchmark commands
+- Feature + metric → OpenSpec or Plannotator first; enable autoresearch only for a follow-up optimization slice
+
+## Anti-patterns
+
+| Do not                                        | Do instead                                           |
+| --------------------------------------------- | ---------------------------------------------------- |
+| SDD proposal + autoresearch loop same task    | Pick SDD **or** autoresearch                         |
+| Plannotator plan + `/autoresearch` same scope | Finish approval path; start autoresearch as new task |
+| Autoresearch without a defined metric         | `init_experiment` with measure command first         |
+| Leave autoresearch on during manual SDD apply | `/autoresearch off` before phase work                |
+| Ignore `.auto/log.jsonl` growth               | `/autoresearch clear` or finalize when pivoting      |

package/skills/pioneer/references/chat-plan.md

@@ -0,0 +1,50 @@
+# Chat Plan (Phase 3a)
+
+**Load when:** Plan routing chose **Chat Plan** (light path).
+
+**Do NOT load when:** OpenSpec SDD path is chosen — use [`openspec-routing.md`](openspec-routing.md) instead.
+
+## Template
+
+```markdown
+## Context
+
+## Assumptions
+
+## Tradeoffs
+
+## Risks
+
+Plan:
+
+1. … — verify: …
+2. …
+```
+
+## Persist
+
+Chat only — do not create `docs/plans/` unless the repo already uses that convention.
+
+## Step ordering
+
+1. Apply grill doc proposals (CONTEXT/ADR patches) when proposed.
+2. Recon/design from graph output when available.
+3. Implementation steps with concrete `verify:` checks per **`AGENTS.md`** commands.
+
+## Execute (Phase 4 chat path)
+
+Work plan steps in order. Each step ends with its `verify:` check before the next step starts.
+
+**Delegation:** load **`/skill:gentle-ai`** and follow its Work Routing Ladder. When `extensions.subagents: false`, execute inline and say delegation was skipped.
+
+**When gentle-ai is unavailable** (toggle off or skill resolution step 3): pioneer inline execute — no SDD, no subagents.
+
+```text
+1. Implement step N inline (single writer thread).
+2. Run verify from AGENTS.md (e.g. bun test) — record pass/fail.
+3. Say: "gentle-ai unavailable — inline execute; SDD and delegation skipped."
+```
+
+**Verify:** use repo commands from **`AGENTS.md`** (`bun test`, `bun run check`, lint/format when defined). Record pass/fail per step.
+
+**Control:** `/stop` halts the current turn cleanly; `/interrupt` cancels mid-stream. Say which control was used if execution pauses before plan completion.

package/skills/pioneer/references/goal-gate.md

@@ -0,0 +1,54 @@
+# Goal gate
+
+**Load when:** Phase 1 runs — before grill or plan when session objective may span turns.
+
+## Enter (mandatory)
+
+Run Phase 1 when **any** of:
+
+- Work spans multiple turns or sessions (migration, refactor, feature arc)
+- Objective is ambiguous and drift would waste grill/plan cycles
+- User sets `/goal` or asks for persistent pursuit
+- Grill/plan would benefit from a single north-star sentence
+
+## Skip
+
+Skip Phase 1 when **all** of:
+
+- One-shot, bounded task (typo, single-file fix, known location)
+- User asked for a plan on turn 1 with trivial scope
+- Active goal already exists — read `get_goal` and align instead of creating a new one
+
+Say **"Goal skipped: …"** with reason when skipping.
+
+## Active goal check
+
+Before Phase 2 or 3:
+
+1. If `extensions.goal: true` and goal tools are available → call `get_goal`
+2. Active goal → align grill topics and plan steps to it; do not replace unless user asks
+3. Work complete → `update_goal({ status: "complete" })` only with verify evidence per pi-goal
+
+## Commands
+
+Full CLI: bundled **pi-goal** docs.
+
+| Action         | Command                                                 |
+| -------------- | ------------------------------------------------------- |
+| Set / replace  | `/goal <objective>` or `/goal --tokens 50k <objective>` |
+| Read state     | `/goal status` or `get_goal` tool                       |
+| Pause / resume | `/goal pause`, `/goal resume`                           |
+| Clear          | `/goal clear`                                           |
+
+## Fallback when goal is off
+
+`extensions.goal: false` or goal tools unavailable?
+
+- Say **"Goal skipped: goal extension off"**
+- Capture objective in chat **Assumptions** (Chat Plan) or proposal **executive_summary** (OpenSpec)
+- Do not invoke `/goal`, `get_goal`, or `update_goal`
+
+## Goal + grill + plan
+
+- Goal sets the north star; grill resolves terms/trade-offs; plan lists steps that advance the goal
+- Do not grill unrelated scope when an active goal exists — flag conflict to the user first

package/skills/pioneer/references/graph-recon-gate.md

@@ -0,0 +1,50 @@
+# Graph recon gate
+
+**Load when:** Phase 0 runs — before wide `grep` or reading many files.
+
+## Artifact order
+
+1. `graphify-out/wiki/index.md` — prefer for navigation when sufficient
+2. `graphify-out/GRAPH_REPORT.md` — god nodes, surprising connections, suggested questions
+3. `graphify-out/graph.json` — fallback for paths and communities
+
+## Graph commands
+
+Full CLI: `/skill:graphify`.
+
+| Question type            | Command                                                 |
+| ------------------------ | ------------------------------------------------------- |
+| How does X relate to Y?  | `graphify query "…" --graph graphify-out/graph.json`    |
+| Shortest dependency path | `graphify path "A" "B" --graph graphify-out/graph.json` |
+| What is node X?          | `graphify explain "X" --graph graphify-out/graph.json`  |
+
+## Rules
+
+- Answer from graph output; do not invent edges or source paths.
+- If the graph gives an exact path, use it; otherwise one narrow lookup, then read that file.
+- If `graphify-out/needs_update` exists or code changed this session, say the graph may be stale; suggest `graphify update .` before trusting modified areas.
+
+## When graph update fails
+
+`graphify update .` failed, graphify unavailable, or toggle `extensions.graphify: false` after stale detection?
+
+1. Say **"Graph stale — update failed: …"** with command + short error summary
+2. Fall through to **Fallback when graph is missing** ladder — do not retry update in a loop
+3. Prefer narrow reads of files changed this session over stale graph edges
+4. Offer `graphify .` or enable graphify only if the user wants a fresh map
+
+Leave the stale warning visible in chat before Phase 2+ work.
+
+## Fallback when graph is missing
+
+No `graphify-out/` or artifacts unreadable? Say **"Graph recon skipped: …"** with reason, then use this ladder **before** repo-wide grep:
+
+1. `AGENTS.md` / `README.md` for the topic
+2. One narrow path lookup (glob or single grep) to find the canonical file
+3. Read that file only — no broad grep until steps 1–2 fail
+
+Offer `graphify .` only if the user wants a map built first.
+
+## Graph + grill
+
+Use GRAPH_REPORT god nodes / surprising connections as grill fuel ("this edge implies X — is that still true?").