hotmilk 0.1.13 → 0.1.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +3 -2
- package/README.md +167 -22
- package/agents/README.md +3 -3
- package/agents/coach.md +2 -1
- package/agents/planner.md +2 -2
- package/hotmilk.json +6 -0
- package/package.json +25 -22
- package/prompts/prompt-eval.md +241 -0
- package/prompts/tidy.md +3 -1
- package/prompts/translate.md +3 -1
- package/skills/make-docs/SKILL.md +43 -0
- package/skills/pioneer/SKILL.md +120 -130
- package/skills/pioneer/references/autoresearch-routing.md +112 -0
- package/skills/pioneer/references/chat-plan.md +50 -0
- package/skills/pioneer/references/goal-gate.md +54 -0
- package/skills/pioneer/references/graph-recon-gate.md +50 -0
- package/skills/pioneer/references/openspec-routing.md +50 -0
- package/skills/pioneer/references/plannotator-routing.md +81 -0
- package/skills/pioneer/references/prompt-eval-gate.md +38 -0
- package/skills/recommend-research/SKILL.md +94 -6
- package/skills/recommend-research/references/example-narrow.md +53 -0
- package/skills/recommend-research/references/scope-gate.md +46 -0
- package/skills/recommend-research/references/shortlist-gate.md +69 -0
- package/skills/recommend-research/references/verify-gate.md +73 -0
- package/skills/update-docs/SKILL.md +86 -0
- package/skills/update-docs/references/doc-inventory.md +69 -0
- package/skills/update-docs/references/drift-verification.md +59 -0
- package/src/bootstrap/extensions.ts +7 -1
- package/src/bootstrap/global-extension-sources.ts +10 -1
- package/src/bootstrap/project-trust.ts +41 -0
- package/src/bootstrap/session.ts +28 -1
- package/src/config/bundled-extensions.ts +12 -0
- package/src/config/hotmilk.ts +22 -0
- package/src/config/resolve.ts +16 -0
- package/src/config/runtime.ts +4 -0
- package/src/index.ts +4 -0
- package/themes/monokai.json +1 -1
- package/skills/empirical-prompt-tuning/SKILL.md +0 -232
package/skills/pioneer/SKILL.md
CHANGED
|
@@ -1,176 +1,166 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pioneer
|
|
3
|
-
description: End-to-end
|
|
3
|
+
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, or autoresearch optimize loops, then execute. Use for pioneer, architecture planning, bundled extension manifest work, hotmilk.json defaults, bundled-extensions.ts, /grill, /goal, /plannotator, /autoresearch, graphify-out questions, openspec work, chat plan, or before multi-step implementation.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Pioneer (graph → goal → grill → plan → execute)
|
|
7
7
|
|
|
8
|
-
Single orchestration skill for **
|
|
8
|
+
Single orchestration skill for **hotmilk** planning and execution.
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
| ----------- | ----------------------------------------- | ------------------------------------------------------------------- |
|
|
12
|
-
| **Graph** | `/skill:graphify` (bundled `graphify-pi`) | Codebase map before broad search |
|
|
13
|
-
| **Goal** | pion `/goal`, `get_goal`, `update_goal` | Multi-turn objective (optional) |
|
|
14
|
-
| **Grill** | `/skill:grill-with-docs` | One question, CONTEXT/ADR, recommended answers |
|
|
15
|
-
| **Plan** | pion `Plan:` + `[DONE:n]` | Structured steps with verification |
|
|
16
|
-
| **Execute** | `/pion-execute` | Writes + doc proposals; `/skill:tdd-guard` + `/skill:tdd` for tests |
|
|
10
|
+
## Scenario router (read first)
|
|
17
11
|
|
|
18
|
-
|
|
12
|
+
| User signal | Route |
|
|
13
|
+
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
14
|
+
| Turn-1 plan request, non-trivial scope | Phase 0 → Phase 3; skip grill unless one blocking term |
|
|
15
|
+
| One-file typo / known single-file fix | Chat Plan; skip Phase 0–2 |
|
|
16
|
+
| Medium scope + human plan approval | Phase 0 → Plannotator (`extensions.plannotator: true`) |
|
|
17
|
+
| Heavy research, long session, `/clear` recovery | planning-with-files (`extensions.planning-with-files: true`) |
|
|
18
|
+
| SDD request, cross-cutting, or medium+ bundled manifest work | Phase 0 → OpenSpec (`gentle-ai` required) — see **Bundled extension scope** |
|
|
19
|
+
| 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 |
|
|
20
|
+
| Skill or prompt edit just completed | `/prompt-eval <path>` before ship |
|
|
19
21
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
4. Execute — /pion-execute, [DONE:n], apply Proposed docs
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
Skip phases that do not apply. Do not grill when the graph + CONTEXT already answer the question.
|
|
22
|
+
| Layer | Delegate to | Role |
|
|
23
|
+
| ----------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
|
|
24
|
+
| **Graph** | `/skill:graphify` | Codebase map before broad search |
|
|
25
|
+
| **Goal** | pi-goal (bundled) | Multi-turn objective (optional) |
|
|
26
|
+
| **Grill** | `/skill:grill-with-docs` | One question, CONTEXT/ADR, recommended answers |
|
|
27
|
+
| **Plan** | chat `Plan:` **or** Plannotator **or** planning-with-files **or** OpenSpec SDD | Light chat; approval gate; file memory; substantial spec work |
|
|
28
|
+
| **Execute** | **`/skill:gentle-ai`** + subagents | Implement, verify; SDD phases when active |
|
|
31
29
|
|
|
32
|
-
|
|
30
|
+
**References:** Do **not** read `references/` unless a phase below applies. Each reference states its load trigger at the top.
|
|
33
31
|
|
|
34
|
-
##
|
|
32
|
+
## Runtime
|
|
35
33
|
|
|
36
|
-
**
|
|
34
|
+
hotmilk bundles **gentle-ai**, **graphify**, **pi-goal**, **pi-subagents**. Toggle via `/mode` + `/reload`. Verify commands: **`AGENTS.md`** (`bun test`, `bun run check`).
|
|
37
35
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
36
|
+
| Toggle | Pioneer note |
|
|
37
|
+
| -------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
38
|
+
| `extensions.graphify` | Phase 0; `graphify-out/` when built — off → graph-recon-gate fallback |
|
|
39
|
+
| `extensions.goal` | Phase 1; `/goal`, `get_goal`, `update_goal` |
|
|
40
|
+
| `extensions.gentle-ai` | OpenSpec path; off → Chat Plan + direct execute only |
|
|
41
|
+
| `extensions.plannotator` | Phase 3 approval gate; `/plannotator`, `--plan`; off → Chat Plan or OpenSpec |
|
|
42
|
+
| `extensions.planning-with-files` | On-disk `task_plan` / `findings` / `progress`; off → skip file-memory path |
|
|
43
|
+
| `extensions.autoresearch` | Optimize loop (`/autoresearch`, `.auto/`); off → one-shot Chat Plan + benchmark in `verify:` |
|
|
44
|
+
| `extensions.subagents` | Phase 4 delegation; off → inline execute |
|
|
41
45
|
|
|
42
|
-
**
|
|
46
|
+
**Skill dependencies** (`/skill:graphify`, `/skill:grill-with-docs`, `/skill:tdd`, `/skill:gentle-ai`) may live in bundled packages or global Pi config.
|
|
43
47
|
|
|
44
|
-
|
|
45
|
-
| ------------------------ | ------------------------------------------------------- |
|
|
46
|
-
| How does X relate to Y? | `graphify query "…" --graph graphify-out/graph.json` |
|
|
47
|
-
| Shortest dependency path | `graphify path "A" "B" --graph graphify-out/graph.json` |
|
|
48
|
-
| What is node X? | `graphify explain "X" --graph graphify-out/graph.json` |
|
|
48
|
+
### Skill resolution ladder
|
|
49
49
|
|
|
50
|
-
|
|
50
|
+
When a `/skill:*` path is missing, resolve in order — stop at first hit. Announce which step forced a behavior change.
|
|
51
51
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
52
|
+
| Step | Check | Action |
|
|
53
|
+
| ---- | ------------------- | ------------------------------------------------------------------------- |
|
|
54
|
+
| 1 | Hotmilk first-party | Search `./skills/*/SKILL.md` for the same skill name |
|
|
55
|
+
| 2 | Bundled package | Search `node_modules/*/skills/` and `.pi/skills/` for the same skill name |
|
|
56
|
+
| 3 | Global Pi config | `~/.pi/agent/skills/`, `~/.claude/skills/`, `~/.agents/skills/` |
|
|
57
|
+
| 4 | Project fallback | `AGENTS.md` commands only; say which `/skill:*` was unavailable |
|
|
56
58
|
|
|
57
|
-
|
|
59
|
+
Path-specific fallbacks when step 4 hits:
|
|
58
60
|
|
|
59
|
-
|
|
61
|
+
- **`/skill:gentle-ai`** + `extensions.gentle-ai: false` → Chat Plan + direct execute only (OpenSpec forbidden)
|
|
62
|
+
- **`/skill:graphify`** → [`graph-recon-gate.md`](references/graph-recon-gate.md) **Fallback when graph is missing**
|
|
63
|
+
- **`/skill:grill-with-docs`** → skip Phase 2; fix terms in Phase 3 **Assumptions**; one blocking chat question max
|
|
60
64
|
|
|
61
|
-
|
|
65
|
+
### Toggle-off ladder
|
|
62
66
|
|
|
63
|
-
|
|
67
|
+
When a capability is disabled via `/mode`, fall back — do not invoke missing tools or paths.
|
|
64
68
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
|
|
|
69
|
+
| Toggle off | Phase impact | Fallback |
|
|
70
|
+
| --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
|
|
71
|
+
| `extensions.graphify: false` | Phase 0 | [`graph-recon-gate.md`](references/graph-recon-gate.md) **Fallback when graph is missing** ladder |
|
|
72
|
+
| `extensions.goal: false` | Phase 1 | Skip `/goal`; objective in Assumptions or proposal — see [`goal-gate.md`](references/goal-gate.md) |
|
|
73
|
+
| `extensions.gentle-ai: false` | OpenSpec path | **Forbidden** — Chat Plan + direct execute only; say SDD requires gentle-ai |
|
|
74
|
+
| `extensions.plannotator: false` | Plannotator path | Chat Plan or OpenSpec per routing; say approval gate skipped |
|
|
75
|
+
| `extensions.planning-with-files: false` | File-memory path | Skip PWF; use Chat Plan, Plannotator, or OpenSpec |
|
|
76
|
+
| `extensions.autoresearch: false` | Optimize loop | Chat Plan + explicit benchmark `verify:`; say autoresearch unavailable |
|
|
77
|
+
| `extensions.subagents: false` | Phase 4 | Inline execute; no `subagent` tool — say delegation skipped |
|
|
78
|
+
| grill-with-docs unavailable | Phase 2 | Skip grill; terms in **Assumptions**; one blocking chat question max |
|
|
71
79
|
|
|
72
|
-
|
|
80
|
+
### Composite toggle-off matrix
|
|
73
81
|
|
|
74
|
-
|
|
82
|
+
When **multiple** toggles are off, apply rows in order — first matching row wins. Announce which composite row forced the path.
|
|
75
83
|
|
|
76
|
-
|
|
84
|
+
| Toggles off | Plan path | Phase impact | Fallback |
|
|
85
|
+
| -------------------------------------- | ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
86
|
+
| `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 |
|
|
87
|
+
| `gentle-ai` + `subagents` | Chat Plan only | Phase 4 inline only; OpenSpec forbidden | No SDD; no `subagent` tool — say both skipped |
|
|
88
|
+
| `graphify` + `subagents` | Either plan path | Phase 0 fallback; Phase 4 inline | Graph ladder + inline execute; say delegation skipped |
|
|
89
|
+
| `goal` + `graphify` | Either plan path | Skip Phase 1; Phase 0 fallback | Objective in Assumptions; graph-recon fallback ladder |
|
|
90
|
+
| `graphify` + `gentle-ai` + `subagents` | Chat Plan only | Phase 0 fallback; Phase 4 inline | Graph ladder + inline execute; OpenSpec forbidden |
|
|
77
91
|
|
|
78
|
-
|
|
92
|
+
Say which toggle or missing skill forced the fallback when it changes the chosen path.
|
|
79
93
|
|
|
80
|
-
|
|
94
|
+
## Plan routing (one authority per task)
|
|
81
95
|
|
|
82
|
-
|
|
96
|
+
Choose **one** plan target per task:
|
|
83
97
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
98
|
+
| Path | When | Artifact | Reference |
|
|
99
|
+
| ----------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
100
|
+
| **Chat Plan** | Small, bounded, known context, single area, quick fix | `Plan:` in chat | [`references/chat-plan.md`](references/chat-plan.md) |
|
|
101
|
+
| **Plannotator** | Medium scope, human browser approval, bounded checklist execution | `plans/*.md` + approval | [`references/plannotator-routing.md`](references/plannotator-routing.md) |
|
|
102
|
+
| **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) |
|
|
103
|
+
| **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`** |
|
|
89
104
|
|
|
90
|
-
|
|
105
|
+
Say which path you chose and why. Do not mix plan authorities unless the user explicitly layers them (e.g. SDD tasks → Plannotator gate).
|
|
91
106
|
|
|
92
|
-
|
|
107
|
+
**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.
|
|
93
108
|
|
|
94
|
-
|
|
109
|
+
**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.
|
|
95
110
|
|
|
96
|
-
|
|
111
|
+
**MANDATORY - READ ENTIRE FILE** the reference for your chosen path before emitting `Plan:`, starting `/plannotator`, or starting SDD work.
|
|
97
112
|
|
|
98
|
-
###
|
|
113
|
+
### Bundled extension scope
|
|
99
114
|
|
|
100
|
-
|
|
101
|
-
## Context
|
|
115
|
+
When the task adds, removes, or reconfigures a bundled extension, resolve in Assumptions (chat) or proposal (SDD):
|
|
102
116
|
|
|
103
|
-
|
|
117
|
+
| Topic | Pin |
|
|
118
|
+
| ------------------------ | -------------------------------------------------------------------------------------------------- |
|
|
119
|
+
| Extension id | kebab-case row in `src/config/bundled-extensions.ts` — **not** `package.json` → `pi.extensions` |
|
|
120
|
+
| Edit scope | Manifest row + `hotmilk.json` default + `package.json` dep + README; lazy load via `extensions.ts` |
|
|
121
|
+
| Auth / integration scope | OAuth, MCP, external API: state secrets, env, approval — default **no** new auth unless required |
|
|
122
|
+
| Missing package | Dependency install/version as explicit step; no speculative toggle defaults |
|
|
104
123
|
|
|
105
|
-
##
|
|
124
|
+
## Phase map
|
|
106
125
|
|
|
107
|
-
|
|
126
|
+
Skip phases that do not apply. Do not grill when graph + CONTEXT already answer the question.
|
|
108
127
|
|
|
109
|
-
Plan
|
|
128
|
+
**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.
|
|
110
129
|
|
|
111
|
-
|
|
112
|
-
|
|
130
|
+
```text
|
|
131
|
+
0. Graph recon → **MANDATORY - READ ENTIRE FILE** graph-recon-gate.md
|
|
132
|
+
1. Goal (optional) → **MANDATORY - READ ENTIRE FILE** goal-gate.md (when Phase 1 applies)
|
|
133
|
+
2. Grill (if unclear) → /skill:grill-with-docs; one question/turn
|
|
134
|
+
skip when graph+CONTEXT suffice or grill-with-docs unavailable
|
|
135
|
+
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)
|
|
136
|
+
4. Execute → gentle-ai Work Routing Ladder (chat-plan Execute or SDD /sdd-continue)
|
|
137
|
+
Alt: Optimize loop → **MANDATORY - READ ENTIRE FILE** autoresearch-routing.md + `/skill:autoresearch-create` (replaces Phase 3–4 for metric loops)
|
|
138
|
+
5. Prompt hardening → **MANDATORY - READ ENTIRE FILE** prompt-eval-gate.md (edits-only: before ship; mixed: after Phase 4)
|
|
113
139
|
```
|
|
114
140
|
|
|
115
|
-
### Step ordering
|
|
116
|
-
|
|
117
|
-
1. Apply any `## Proposed CONTEXT.md` / `## Proposed ADR` from grill (or reference them as first steps).
|
|
118
|
-
2. Recon / design steps informed by graph paths and communities.
|
|
119
|
-
3. Implementation steps with concrete `verify:` checks (test, command, file exists, behavior).
|
|
120
|
-
|
|
121
|
-
### Persist plan file (chezmoi / multi-context repos)
|
|
122
|
-
|
|
123
|
-
When the chezmoi repo (or any project with `CONTEXT-MAP.md`) is the cwd:
|
|
124
|
-
|
|
125
|
-
- At **plan finalization**, write **`docs/plans/<slug>.md`** with the same `## Context` … `Plan:` content (kebab-case slug).
|
|
126
|
-
- Chat `Plan:` remains the pion step tracker (`[DONE:n]` after `/pion-execute`).
|
|
127
|
-
- Only `docs/plans/*.md` may be written while plan mode is ON; CONTEXT / ADR / code wait for `/pion-execute`.
|
|
128
|
-
|
|
129
|
-
While pion is ON: **no** `edit`; **no** `write` except `docs/plans/<slug>.md` at finalize. Refine with `/pion-refine`.
|
|
130
|
-
|
|
131
|
-
---
|
|
132
|
-
|
|
133
|
-
## Phase 4 — Execute
|
|
134
|
-
|
|
135
|
-
**Start:** `/pion-execute` (restores write tools; may enable `get_goal` / `update_goal` in tool set).
|
|
136
|
-
|
|
137
|
-
- Work steps in order; tag completed steps with `[DONE:n]` in the response.
|
|
138
|
-
- Sync CONTEXT/ADR and **doc patches** from grill (bootstrap or drift fixes) before code when proposed.
|
|
139
|
-
- For test work: load **`/skill:tdd`** then **`/skill:tdd-guard`** (plan testlist if missing, then one cycle at a time).
|
|
140
|
-
- After large code changes, mention `graphify update .` if the project uses graphify.
|
|
141
|
-
- Interrupt: `/pion-interrupt` (steer). Stop: `/pion-stop` (abort, exit execute mode).
|
|
142
|
-
- Unfinished steps: `/pion-todos`.
|
|
143
|
-
|
|
144
141
|
---
|
|
145
142
|
|
|
146
|
-
## Commands (quick reference)
|
|
147
|
-
|
|
148
|
-
| Command | Phase |
|
|
149
|
-
| -------------------------------------- | ------------------------------------------------ |
|
|
150
|
-
| `/pion` | Toggle plan mode (read-only) |
|
|
151
|
-
| `/pion-grill`, `/grill <task>` | Grill only |
|
|
152
|
-
| `/pion-refine` | Adjust plan (read-only) |
|
|
153
|
-
| `/pion-execute` | Execute |
|
|
154
|
-
| `/pion-stop`, `/pion-interrupt` | Control during execute |
|
|
155
|
-
| `/pion-todos` | Remaining plan steps |
|
|
156
|
-
| `/goal`, `/goal pause`, `/goal resume` | Goal |
|
|
157
|
-
| `/graphify …` | Delegates to graphify skill (build/query/update) |
|
|
158
|
-
|
|
159
143
|
## Anti-patterns
|
|
160
144
|
|
|
161
|
-
| Do not
|
|
162
|
-
|
|
|
163
|
-
| `
|
|
164
|
-
|
|
|
165
|
-
|
|
|
166
|
-
|
|
|
167
|
-
|
|
|
168
|
-
| `
|
|
169
|
-
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
145
|
+
| Do not | Why | Do instead |
|
|
146
|
+
| ---------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
|
|
147
|
+
| Read `references/` without a matching path | Wastes tokens; loads wrong workflow | Load only when Phase 0, Phase 1, Chat Plan, Plannotator, OpenSpec, autoresearch, or Phase 5 prompt-eval applies |
|
|
148
|
+
| Ship skill/prompt edits without prompt-eval | Author blind spot; stale triggers survive | Phase 5 → prompt-eval-gate → `/prompt-eval <path>` |
|
|
149
|
+
| 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** |
|
|
150
|
+
| OpenSpec when `gentle-ai` is off | SDD commands unavailable; path breaks mid-flow | Chat Plan only; say toggle must enable gentle-ai for SDD |
|
|
151
|
+
| Ignore toggle-off ladder | Calls missing tools; false confidence in SDD/subagents | Use toggle-off table; announce fallback |
|
|
152
|
+
| `Plan:` before scope stable (user did not ask) | Premature plan hides glossary gaps | Keep grilling; user asks → Plan with open items in Assumptions |
|
|
153
|
+
| OpenSpec for a one-file typo | SDD overhead wastes review budget | Chat Plan + direct implement |
|
|
154
|
+
| Chat Plan for cross-cutting architecture | Chat plan lacks artifact gates | OpenSpec SDD + `/sdd-continue` |
|
|
155
|
+
| Plannotator + OpenSpec as dual plan authorities | Two sources of truth | SDD for spec; Plannotator gates tasks or execution only |
|
|
156
|
+
| Plannotator + planning-with-files same plan file | Schema and hook conflict | Separate paths: `plans/` vs `.planning/` |
|
|
157
|
+
| Chat Plan mid-task then Plannotator for same scope | Context split | Pick one path at Phase 3 |
|
|
158
|
+
| Autoresearch + SDD or Plannotator same task | Conflicting authorities (loop vs gates) | Pick autoresearch **or** plan path; `/autoresearch off` before switching |
|
|
159
|
+
| OpenSpec or Plannotator mid-active autoresearch loop | Metric loop never converges to shippable contract | Stop loop; finalize or clear `.auto/`; then start plan path |
|
|
160
|
+
| Multiple grill questions in one message | User cannot answer precisely; violates grill-with-docs | One question + recommended answer |
|
|
161
|
+
| Grill without grill-with-docs loaded | Skill rules violated; multi-question drift | Skip Phase 2 or load skill; terms in Assumptions |
|
|
162
|
+
| Broad grep ignoring `graphify-out/` | Misses graph-cached structure | Graph recon first (graph-recon-gate) |
|
|
163
|
+
| Invent graph edges or paths | False architecture confidence | `graphify query` / say "graph lacks …" |
|
|
164
|
+
| Implementation detail in proposed CONTEXT | CONTEXT is glossary/decisions, not design doc | Glossary and decisions only |
|
|
165
|
+
| Skip SDD verify/sync | Artifacts drift from shipped code | OpenSpec path → **`/skill:gentle-ai`** through archive |
|
|
166
|
+
| Ignore active `/goal` | Session objective diverges from work | Read `get_goal`; update when done |
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Autoresearch (optimize loop)
|
|
2
|
+
|
|
3
|
+
**Load when:** the task is a **measure → edit → benchmark → keep/discard** loop, not a one-shot feature or spec-driven build.
|
|
4
|
+
|
|
5
|
+
**Do NOT load when:** Chat Plan, Plannotator, planning-with-files, or OpenSpec SDD is the chosen plan authority — use the matching reference instead.
|
|
6
|
+
|
|
7
|
+
## When to use
|
|
8
|
+
|
|
9
|
+
| Signal | Route here |
|
|
10
|
+
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
11
|
+
| User asks to optimize, benchmark, tune, or run experiments in a loop | `/skill:autoresearch-create` |
|
|
12
|
+
| Success = measurable metric (test time, bundle size, loss, Lighthouse, build time) | Autoresearch |
|
|
13
|
+
| User invokes `/autoresearch`, mentions `.auto/`, or wants keep/discard iterations | Autoresearch |
|
|
14
|
+
| Feature delivery, spec, architecture, cross-cutting change | OpenSpec / gentle-ai — **not** autoresearch |
|
|
15
|
+
| Human plan approval before any writes | Plannotator — **not** autoresearch as plan authority |
|
|
16
|
+
| Strict RED→GREEN test-first for a known fix | `/skill:tdd` or `/tdd` — **not** autoresearch unless optimizing the test suite itself |
|
|
17
|
+
|
|
18
|
+
**Tie-breaker vs plan paths:** optimization target with a metric → autoresearch; delivery with acceptance criteria and review gates → plan path (Chat / Plannotator / PWF / SDD).
|
|
19
|
+
|
|
20
|
+
## 向く / 向かない (suited vs not suited)
|
|
21
|
+
|
|
22
|
+
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.
|
|
23
|
+
|
|
24
|
+
| 向く (use autoresearch) | Why | 向かない (use another path) | Why |
|
|
25
|
+
| ---------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
|
|
26
|
+
| 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** |
|
|
27
|
+
| 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** |
|
|
28
|
+
| 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** |
|
|
29
|
+
| 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** |
|
|
30
|
+
| 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 |
|
|
31
|
+
| 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 |
|
|
32
|
+
|
|
33
|
+
**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.
|
|
34
|
+
|
|
35
|
+
## Prerequisites
|
|
36
|
+
|
|
37
|
+
| Requirement | Check |
|
|
38
|
+
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
39
|
+
| Toggle | `extensions.autoresearch: true` — if off, say loop unavailable; do not fake the workflow |
|
|
40
|
+
| Extension | `pi-autoresearch` loaded via `/reload` after `/mode` |
|
|
41
|
+
| Skills | `autoresearch-create` (start), `autoresearch-finalize` (clean branches), `autoresearch-hooks` (optional side effects) |
|
|
42
|
+
| Workspace | Writes under `.auto/` (`prompt.md`, `log.jsonl`, session state) — add `.auto/` to `.gitignore` if missing |
|
|
43
|
+
|
|
44
|
+
## Workflow
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
1. Confirm metric, direction (lower/higher), and measure command
|
|
48
|
+
2. /skill:autoresearch-create → init_experiment + session files
|
|
49
|
+
3. Loop: propose change → run_experiment → log_experiment (keep or revert)
|
|
50
|
+
4. /autoresearch export for live dashboard (optional)
|
|
51
|
+
5. When done: /skill:autoresearch-finalize for reviewable branches
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Coexistence matrix
|
|
55
|
+
|
|
56
|
+
| Layer | Autoresearch | Notes |
|
|
57
|
+
| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| **gentle-ai SDD** | **Mutually exclusive** for the same task | SDD = phased spec/apply/verify; autoresearch = unbounded optimize loop. Pick one authority. |
|
|
59
|
+
| **gentle-ai inline/worker** | OK after loop | Use subagents for isolated tries; do not run SDD phases mid-loop |
|
|
60
|
+
| **Plannotator** | **Do not combine** as dual authority | Approve a plan, then autoresearch only if metric loop is a separate follow-up task |
|
|
61
|
+
| **planning-with-files** | Rare overlap | PWF for research notes; autoresearch for benchmark loop — separate dirs (`.planning/` vs `.auto/`) |
|
|
62
|
+
| **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 |
|
|
63
|
+
| **pi-goal** | OK | Goal = north star; autoresearch = tactical iterations toward metric |
|
|
64
|
+
| **graphify** | OK before loop | Phase 0 recon still applies when codebase map reduces bad experiments |
|
|
65
|
+
|
|
66
|
+
## Execute (vs Phase 4)
|
|
67
|
+
|
|
68
|
+
Autoresearch **replaces** pioneer Phase 3–4 when the task is optimize-only:
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
Phase 0 graph (optional) → autoresearch-create → loop until metric plateaus or user stops
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Do **not** emit `Plan:` or start SDD for the same scope unless the user pivots to feature delivery.
|
|
75
|
+
|
|
76
|
+
## gentle-ai guardrails
|
|
77
|
+
|
|
78
|
+
When `extensions.gentle-ai: true` and autoresearch is active:
|
|
79
|
+
|
|
80
|
+
- Do not start `/sdd-continue` or OpenSpec apply for the same change name.
|
|
81
|
+
- Prefer **inline or worker** execution inside the loop; avoid review-budget gates every iteration.
|
|
82
|
+
- Turn autoresearch **off** (`/autoresearch off`) before switching to SDD or Plannotator on the same task.
|
|
83
|
+
|
|
84
|
+
## Shortcuts and UI
|
|
85
|
+
|
|
86
|
+
Default shortcut: `Ctrl+Shift+F` (fullscreen dashboard). Override in `~/.pi/agent/extensions/pi-autoresearch.json`:
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"shortcuts": {
|
|
91
|
+
"fullscreenDashboard": "ctrl+shift+y"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Use `null` to disable a shortcut. Off by default in hotmilk — widget + shortcuts add session weight.
|
|
97
|
+
|
|
98
|
+
## Fallback when autoresearch is off
|
|
99
|
+
|
|
100
|
+
- Say **"Autoresearch skipped: extension off"**
|
|
101
|
+
- One-shot optimize → Chat Plan with explicit `verify:` benchmark commands
|
|
102
|
+
- Feature + metric → OpenSpec or Plannotator first; enable autoresearch only for a follow-up optimization slice
|
|
103
|
+
|
|
104
|
+
## Anti-patterns
|
|
105
|
+
|
|
106
|
+
| Do not | Do instead |
|
|
107
|
+
| --------------------------------------------- | ---------------------------------------------------- |
|
|
108
|
+
| SDD proposal + autoresearch loop same task | Pick SDD **or** autoresearch |
|
|
109
|
+
| Plannotator plan + `/autoresearch` same scope | Finish approval path; start autoresearch as new task |
|
|
110
|
+
| Autoresearch without a defined metric | `init_experiment` with measure command first |
|
|
111
|
+
| Leave autoresearch on during manual SDD apply | `/autoresearch off` before phase work |
|
|
112
|
+
| Ignore `.auto/log.jsonl` growth | `/autoresearch clear` or finalize when pivoting |
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Chat Plan (Phase 3a)
|
|
2
|
+
|
|
3
|
+
**Load when:** Plan routing chose **Chat Plan** (light path).
|
|
4
|
+
|
|
5
|
+
**Do NOT load when:** OpenSpec SDD path is chosen — use [`openspec-routing.md`](openspec-routing.md) instead.
|
|
6
|
+
|
|
7
|
+
## Template
|
|
8
|
+
|
|
9
|
+
```markdown
|
|
10
|
+
## Context
|
|
11
|
+
|
|
12
|
+
## Assumptions
|
|
13
|
+
|
|
14
|
+
## Tradeoffs
|
|
15
|
+
|
|
16
|
+
## Risks
|
|
17
|
+
|
|
18
|
+
Plan:
|
|
19
|
+
|
|
20
|
+
1. … — verify: …
|
|
21
|
+
2. …
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Persist
|
|
25
|
+
|
|
26
|
+
Chat only — do not create `docs/plans/` unless the repo already uses that convention.
|
|
27
|
+
|
|
28
|
+
## Step ordering
|
|
29
|
+
|
|
30
|
+
1. Apply grill doc proposals (CONTEXT/ADR patches) when proposed.
|
|
31
|
+
2. Recon/design from graph output when available.
|
|
32
|
+
3. Implementation steps with concrete `verify:` checks per **`AGENTS.md`** commands.
|
|
33
|
+
|
|
34
|
+
## Execute (Phase 4 chat path)
|
|
35
|
+
|
|
36
|
+
Work plan steps in order. Each step ends with its `verify:` check before the next step starts.
|
|
37
|
+
|
|
38
|
+
**Delegation:** load **`/skill:gentle-ai`** and follow its Work Routing Ladder. When `extensions.subagents: false`, execute inline and say delegation was skipped.
|
|
39
|
+
|
|
40
|
+
**When gentle-ai is unavailable** (toggle off or skill resolution step 3): pioneer inline execute — no SDD, no subagents.
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
1. Implement step N inline (single writer thread).
|
|
44
|
+
2. Run verify from AGENTS.md (e.g. bun test) — record pass/fail.
|
|
45
|
+
3. Say: "gentle-ai unavailable — inline execute; SDD and delegation skipped."
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Verify:** use repo commands from **`AGENTS.md`** (`bun test`, `bun run check`, lint/format when defined). Record pass/fail per step.
|
|
49
|
+
|
|
50
|
+
**Control:** `/stop` halts the current turn cleanly; `/interrupt` cancels mid-stream. Say which control was used if execution pauses before plan completion.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Goal gate
|
|
2
|
+
|
|
3
|
+
**Load when:** Phase 1 runs — before grill or plan when session objective may span turns.
|
|
4
|
+
|
|
5
|
+
## Enter (mandatory)
|
|
6
|
+
|
|
7
|
+
Run Phase 1 when **any** of:
|
|
8
|
+
|
|
9
|
+
- Work spans multiple turns or sessions (migration, refactor, feature arc)
|
|
10
|
+
- Objective is ambiguous and drift would waste grill/plan cycles
|
|
11
|
+
- User sets `/goal` or asks for persistent pursuit
|
|
12
|
+
- Grill/plan would benefit from a single north-star sentence
|
|
13
|
+
|
|
14
|
+
## Skip
|
|
15
|
+
|
|
16
|
+
Skip Phase 1 when **all** of:
|
|
17
|
+
|
|
18
|
+
- One-shot, bounded task (typo, single-file fix, known location)
|
|
19
|
+
- User asked for a plan on turn 1 with trivial scope
|
|
20
|
+
- Active goal already exists — read `get_goal` and align instead of creating a new one
|
|
21
|
+
|
|
22
|
+
Say **"Goal skipped: …"** with reason when skipping.
|
|
23
|
+
|
|
24
|
+
## Active goal check
|
|
25
|
+
|
|
26
|
+
Before Phase 2 or 3:
|
|
27
|
+
|
|
28
|
+
1. If `extensions.goal: true` and goal tools are available → call `get_goal`
|
|
29
|
+
2. Active goal → align grill topics and plan steps to it; do not replace unless user asks
|
|
30
|
+
3. Work complete → `update_goal({ status: "complete" })` only with verify evidence per pi-goal
|
|
31
|
+
|
|
32
|
+
## Commands
|
|
33
|
+
|
|
34
|
+
Full CLI: bundled **pi-goal** docs.
|
|
35
|
+
|
|
36
|
+
| Action | Command |
|
|
37
|
+
| -------------- | ------------------------------------------------------- |
|
|
38
|
+
| Set / replace | `/goal <objective>` or `/goal --tokens 50k <objective>` |
|
|
39
|
+
| Read state | `/goal status` or `get_goal` tool |
|
|
40
|
+
| Pause / resume | `/goal pause`, `/goal resume` |
|
|
41
|
+
| Clear | `/goal clear` |
|
|
42
|
+
|
|
43
|
+
## Fallback when goal is off
|
|
44
|
+
|
|
45
|
+
`extensions.goal: false` or goal tools unavailable?
|
|
46
|
+
|
|
47
|
+
- Say **"Goal skipped: goal extension off"**
|
|
48
|
+
- Capture objective in chat **Assumptions** (Chat Plan) or proposal **executive_summary** (OpenSpec)
|
|
49
|
+
- Do not invoke `/goal`, `get_goal`, or `update_goal`
|
|
50
|
+
|
|
51
|
+
## Goal + grill + plan
|
|
52
|
+
|
|
53
|
+
- Goal sets the north star; grill resolves terms/trade-offs; plan lists steps that advance the goal
|
|
54
|
+
- Do not grill unrelated scope when an active goal exists — flag conflict to the user first
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Graph recon gate
|
|
2
|
+
|
|
3
|
+
**Load when:** Phase 0 runs — before wide `grep` or reading many files.
|
|
4
|
+
|
|
5
|
+
## Artifact order
|
|
6
|
+
|
|
7
|
+
1. `graphify-out/wiki/index.md` — prefer for navigation when sufficient
|
|
8
|
+
2. `graphify-out/GRAPH_REPORT.md` — god nodes, surprising connections, suggested questions
|
|
9
|
+
3. `graphify-out/graph.json` — fallback for paths and communities
|
|
10
|
+
|
|
11
|
+
## Graph commands
|
|
12
|
+
|
|
13
|
+
Full CLI: `/skill:graphify`.
|
|
14
|
+
|
|
15
|
+
| Question type | Command |
|
|
16
|
+
| ------------------------ | ------------------------------------------------------- |
|
|
17
|
+
| How does X relate to Y? | `graphify query "…" --graph graphify-out/graph.json` |
|
|
18
|
+
| Shortest dependency path | `graphify path "A" "B" --graph graphify-out/graph.json` |
|
|
19
|
+
| What is node X? | `graphify explain "X" --graph graphify-out/graph.json` |
|
|
20
|
+
|
|
21
|
+
## Rules
|
|
22
|
+
|
|
23
|
+
- Answer from graph output; do not invent edges or source paths.
|
|
24
|
+
- If the graph gives an exact path, use it; otherwise one narrow lookup, then read that file.
|
|
25
|
+
- If `graphify-out/needs_update` exists or code changed this session, say the graph may be stale; suggest `graphify update .` before trusting modified areas.
|
|
26
|
+
|
|
27
|
+
## When graph update fails
|
|
28
|
+
|
|
29
|
+
`graphify update .` failed, graphify unavailable, or toggle `extensions.graphify: false` after stale detection?
|
|
30
|
+
|
|
31
|
+
1. Say **"Graph stale — update failed: …"** with command + short error summary
|
|
32
|
+
2. Fall through to **Fallback when graph is missing** ladder — do not retry update in a loop
|
|
33
|
+
3. Prefer narrow reads of files changed this session over stale graph edges
|
|
34
|
+
4. Offer `graphify .` or enable graphify only if the user wants a fresh map
|
|
35
|
+
|
|
36
|
+
Leave the stale warning visible in chat before Phase 2+ work.
|
|
37
|
+
|
|
38
|
+
## Fallback when graph is missing
|
|
39
|
+
|
|
40
|
+
No `graphify-out/` or artifacts unreadable? Say **"Graph recon skipped: …"** with reason, then use this ladder **before** repo-wide grep:
|
|
41
|
+
|
|
42
|
+
1. `AGENTS.md` / `README.md` for the topic
|
|
43
|
+
2. One narrow path lookup (glob or single grep) to find the canonical file
|
|
44
|
+
3. Read that file only — no broad grep until steps 1–2 fail
|
|
45
|
+
|
|
46
|
+
Offer `graphify .` only if the user wants a map built first.
|
|
47
|
+
|
|
48
|
+
## Graph + grill
|
|
49
|
+
|
|
50
|
+
Use GRAPH_REPORT god nodes / surprising connections as grill fuel ("this edge implies X — is that still true?").
|