@webpresso/plugin-opencode 0.0.5 → 0.0.7
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/package.json +1 -1
- package/plugin-skill-ownership.json +21 -15
- package/skills/ai-deslop/SKILL.md +6 -1
- package/skills/autopilot/SKILL.md +6 -1
- package/skills/best-practice-research/SKILL.md +6 -1
- package/skills/deep-interview/SKILL.md +5 -4
- package/skills/delivery-program/SKILL.md +5 -0
- package/skills/fix/SKILL.md +15 -3
- package/skills/handoff/SKILL.md +68 -0
- package/skills/hooks-doctor/SKILL.md +35 -9
- package/skills/plan-refine/SKILL.md +89 -19
- package/skills/plan-refine/references/full-methodology.md +99 -90
- package/skills/ralplan/SKILL.md +155 -28
- package/skills/team/SKILL.md +1 -1
- package/skills/tech-debt/SKILL.md +7 -2
- package/skills/testing-philosophy/SKILL.md +1 -1
- package/skills/tooling-friction/SKILL.md +159 -0
- package/skills/ultragoal/SKILL.md +126 -8
- package/skills/verify/SKILL.md +102 -25
package/package.json
CHANGED
|
@@ -2,20 +2,20 @@
|
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"host": "opencode",
|
|
4
4
|
"packageName": "@webpresso/plugin-opencode",
|
|
5
|
-
"packageVersion": "0.0.
|
|
5
|
+
"packageVersion": "0.0.7",
|
|
6
6
|
"runtimeDirs": [],
|
|
7
7
|
"skills": {
|
|
8
8
|
"ai-deslop": {
|
|
9
|
-
"digest": "sha256:
|
|
9
|
+
"digest": "sha256:cf07df5835037f10401400e220c1c923f5325a6149d59c231ce316e10595fdfc"
|
|
10
10
|
},
|
|
11
11
|
"autopilot": {
|
|
12
|
-
"digest": "sha256:
|
|
12
|
+
"digest": "sha256:aeace230b2443b5e531179fa5bb5a7a9214d341c72199d8ada0211999627cbb8"
|
|
13
13
|
},
|
|
14
14
|
"autoresearch": {
|
|
15
15
|
"digest": "sha256:b4d51cd53beb4a3271827172dfbd0b1d27bd58761ca07a35d49a5d6324b87fdf"
|
|
16
16
|
},
|
|
17
17
|
"best-practice-research": {
|
|
18
|
-
"digest": "sha256:
|
|
18
|
+
"digest": "sha256:a46010d48ca2c9b4e04815ea84a45d100e032c5a4f08b919eeefb5be37d87749"
|
|
19
19
|
},
|
|
20
20
|
"browse": {
|
|
21
21
|
"digest": "sha256:21fd24862e7f7c8a1feadea6bc376492b136b99fc381cf1b8927c9db80615431"
|
|
@@ -27,13 +27,13 @@
|
|
|
27
27
|
"digest": "sha256:9cf714ed78dafbb2370e8f6e4bee5f22db7d540444c4dd96540c8b8dd22bd4a4"
|
|
28
28
|
},
|
|
29
29
|
"deep-interview": {
|
|
30
|
-
"digest": "sha256:
|
|
30
|
+
"digest": "sha256:79fbf86a86024a311583a1500bb6960c82ad1383cc9f8ed3f04bbace41848ff7"
|
|
31
31
|
},
|
|
32
32
|
"deep-research": {
|
|
33
33
|
"digest": "sha256:01dafd194066a2936db0b437fd5c3beef6d7ff82478d0d995393093d89496f18"
|
|
34
34
|
},
|
|
35
35
|
"delivery-program": {
|
|
36
|
-
"digest": "sha256:
|
|
36
|
+
"digest": "sha256:ebd6b35036c12fa26ff98649ac57ede607b7b3526c401784670a5ce68369a691"
|
|
37
37
|
},
|
|
38
38
|
"design-review": {
|
|
39
39
|
"digest": "sha256:5b213735e2842568774572f36b198bccf03c03a54b2732484aadd023f04acb23"
|
|
@@ -42,13 +42,16 @@
|
|
|
42
42
|
"digest": "sha256:306355888da0827e3523022077f731845726bbaaf595ca12515cc91d8605b5e6"
|
|
43
43
|
},
|
|
44
44
|
"fix": {
|
|
45
|
-
"digest": "sha256:
|
|
45
|
+
"digest": "sha256:1fdbda9972b9d9452b1705cefcdb46c3eaf02090b8d3af1d653ae69c8731c949"
|
|
46
46
|
},
|
|
47
47
|
"grok": {
|
|
48
48
|
"digest": "sha256:796104b04f70c8dd48cf1056c8d72d9492648f89486a35515e00af1d0de42f0a"
|
|
49
49
|
},
|
|
50
|
+
"handoff": {
|
|
51
|
+
"digest": "sha256:eb34b39fc6d416fe8203eea979b4b99ab3150c44da6dad3ca4afb8fe8fb75b85"
|
|
52
|
+
},
|
|
50
53
|
"hooks-doctor": {
|
|
51
|
-
"digest": "sha256:
|
|
54
|
+
"digest": "sha256:273bdb0ce597604301648c8c149f20bb92bfa64c9015f4a89e88e932c6501a9e"
|
|
52
55
|
},
|
|
53
56
|
"investigate": {
|
|
54
57
|
"digest": "sha256:778b3a1f38323e8dd6101c6ace26ff8aada1246b20952b3641d5d1049bc50055"
|
|
@@ -72,28 +75,31 @@
|
|
|
72
75
|
"digest": "sha256:b728dad90254d4c9f81b3818321d34ab53519b79ce20ff3bfe08bfacb2aa3e86"
|
|
73
76
|
},
|
|
74
77
|
"plan-refine": {
|
|
75
|
-
"digest": "sha256:
|
|
78
|
+
"digest": "sha256:ff848de26414f9b0d015c75051d872db7d2c4de1893a9d5cd55b640392e3f836"
|
|
76
79
|
},
|
|
77
80
|
"ralplan": {
|
|
78
|
-
"digest": "sha256:
|
|
81
|
+
"digest": "sha256:36d54cf48f92f16cf23362b6616646f883651f0cf8d8ce1b98a386f0021bfe22"
|
|
79
82
|
},
|
|
80
83
|
"team": {
|
|
81
|
-
"digest": "sha256:
|
|
84
|
+
"digest": "sha256:c27107b46e0cd7b9c264a6f51f74f505920d63e7ee2a2d26d2f288592fd10bd2"
|
|
82
85
|
},
|
|
83
86
|
"tech-debt": {
|
|
84
|
-
"digest": "sha256:
|
|
87
|
+
"digest": "sha256:a34fa1039d68adc4c875af75cb79ddedcee3414a98b63194a9d8eca4671b5264"
|
|
85
88
|
},
|
|
86
89
|
"testing-philosophy": {
|
|
87
|
-
"digest": "sha256:
|
|
90
|
+
"digest": "sha256:22533e26549b60494f042b5f4d7c97abf2019fc0a60697f84a395fa48ef0147f"
|
|
91
|
+
},
|
|
92
|
+
"tooling-friction": {
|
|
93
|
+
"digest": "sha256:92cc6825c222ad3f8dfe43c4a83a28e59f7a4d0179c886e276246f36670d3d0e"
|
|
88
94
|
},
|
|
89
95
|
"tph": {
|
|
90
96
|
"digest": "sha256:bed3684a850651534f315d355cdeae50d951c429817df0f105cccdb7f4e1561b"
|
|
91
97
|
},
|
|
92
98
|
"ultragoal": {
|
|
93
|
-
"digest": "sha256:
|
|
99
|
+
"digest": "sha256:9470e59bd1aeca64aaa24f6b4276235ebbffbf5f817817093458e80a5fffc31a"
|
|
94
100
|
},
|
|
95
101
|
"verify": {
|
|
96
|
-
"digest": "sha256:
|
|
102
|
+
"digest": "sha256:7f431a63e611c9f47d5edf87a889d4527658d2dd0c68f9dffd0924c1cd0dd028"
|
|
97
103
|
}
|
|
98
104
|
}
|
|
99
105
|
}
|
|
@@ -9,7 +9,7 @@ related: [fix, verify, investigate]
|
|
|
9
9
|
created: "2026-07-16"
|
|
10
10
|
last_reviewed: "2026-07-16"
|
|
11
11
|
name: ai-deslop
|
|
12
|
-
description: "
|
|
12
|
+
description: "Anti-slop cleanup after green. Use for elegance, simplify, deslop, trim noise."
|
|
13
13
|
license: MIT
|
|
14
14
|
upstream:
|
|
15
15
|
source: https://github.com/Yeachan-Heo/oh-my-claudecode/tree/590fb988931d34a12604be0ca4215c818079018e/skills/ai-slop-cleaner
|
|
@@ -19,6 +19,11 @@ argument-hint: "[--review] <files|path|scope>"
|
|
|
19
19
|
|
|
20
20
|
# AI Deslop
|
|
21
21
|
|
|
22
|
+
## Use when (freeform)
|
|
23
|
+
|
|
24
|
+
- "deslop", "elegance", "simplify", "cleanup slop", "trim noise"
|
|
25
|
+
- after `verify` finds green behavior with leftover machine-shaped debt
|
|
26
|
+
|
|
22
27
|
Use this skill after behavior is already correct but the resulting code or docs
|
|
23
28
|
still feel bloated, repetitive, over-scaffolded, or obviously machine-shaped.
|
|
24
29
|
|
|
@@ -9,12 +9,17 @@ related: [goal, plan-refine, verify, testing-philosophy, ultragoal, fix]
|
|
|
9
9
|
created: "2026-07-10"
|
|
10
10
|
last_reviewed: "2026-07-21"
|
|
11
11
|
name: autopilot
|
|
12
|
-
description: "
|
|
12
|
+
description: "Bounded goal/autopilot pipeline with budgets. Use for full autopilot, /goal, parallel ready-set."
|
|
13
13
|
argument-hint: "<brief|force: brief>"
|
|
14
14
|
---
|
|
15
15
|
|
|
16
16
|
# Autopilot
|
|
17
17
|
|
|
18
|
+
## Use when (freeform)
|
|
19
|
+
|
|
20
|
+
- "/goal", "autopilot", "full autopilot" **with** scope + budgets
|
|
21
|
+
- parallel ready-set execution under ultragoal controller
|
|
22
|
+
|
|
18
23
|
Drive an approved brief through `plan -> execute -> qa -> validate -> land -> complete`
|
|
19
24
|
using `wp_ultragoal_run` / `wp ultragoal run` and the current handoff.
|
|
20
25
|
|
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: best-practice-research
|
|
3
|
-
description: "
|
|
3
|
+
description: "Upstream best-practice research with citations. Use for SOTA, what others do, official guidance."
|
|
4
4
|
argument-hint: "<technology|decision|practice question>"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Best-Practice Research
|
|
8
8
|
|
|
9
|
+
## Use when (freeform)
|
|
10
|
+
|
|
11
|
+
- "best practice", "SOTA", "what do others do", "official guidance", "web research" for external practice
|
|
12
|
+
- Prefer **early** when correctness depends on upstream behavior — not only after thrashing
|
|
13
|
+
|
|
9
14
|
Use this skill when a task depends on current external best practices, version-aware guidance, standards, official recommendations, or upstream behavior. This is a workflow wrapper: it routes evidence gathering and synthesis; it is not a new research authority and it does not replace the `deep-research` skill.
|
|
10
15
|
|
|
11
16
|
## Purpose
|
|
@@ -5,11 +5,11 @@ title: Deep Interview
|
|
|
5
5
|
status: active
|
|
6
6
|
scope: repo
|
|
7
7
|
applies_to: [agents]
|
|
8
|
-
related: [ralplan, autopilot, deep-research]
|
|
8
|
+
related: [ralplan, autopilot, deep-research, handoff]
|
|
9
9
|
created: "2026-07-17"
|
|
10
10
|
last_reviewed: "2026-07-17"
|
|
11
11
|
name: deep-interview
|
|
12
|
-
description: "Socratic requirements interview
|
|
12
|
+
description: "Socratic requirements interview before plan/exec. Use for don't assume, clarify, grill requirements."
|
|
13
13
|
license: MIT
|
|
14
14
|
upstream:
|
|
15
15
|
source: https://github.com/Yeachan-Heo/oh-my-codex/tree/0e00a6ebdd12a6674f5a4735942940b9bdcdb8c0/skills/deep-interview
|
|
@@ -24,9 +24,10 @@ Deep Interview is an intent-first Socratic clarification loop that runs before p
|
|
|
24
24
|
<Use_When>
|
|
25
25
|
|
|
26
26
|
- The request is broad, ambiguous, or missing concrete acceptance criteria
|
|
27
|
-
- The user says "deep interview", "interview me", "ask me everything",
|
|
27
|
+
- The user says "deep interview", "interview me", "ask me everything", "don't assume", "clarify requirements", or "grill me"
|
|
28
|
+
- Pre-code "100% confidence architecture" or "critically evaluate" without a plan yet
|
|
28
29
|
- You want to avoid misaligned implementation from underspecified requirements
|
|
29
|
-
- You need a requirements artifact before handing off to `ralplan`, `autopilot`, `ultragoal`, `team`, or a new blueprint
|
|
30
|
+
- You need a requirements artifact before handing off to `ralplan`, `autopilot`, `ultragoal`, `team`, `handoff`, or a new blueprint
|
|
30
31
|
</Use_When>
|
|
31
32
|
|
|
32
33
|
<Do_Not_Use_When>
|
|
@@ -55,3 +55,8 @@ Child membership comes only from `parent_roadmap`; do not maintain a second list
|
|
|
55
55
|
timeouts or bypass guards.
|
|
56
56
|
|
|
57
57
|
Fallback when MCP is unavailable: `wp pr merge` uses the same exact-SHA service.
|
|
58
|
+
|
|
59
|
+
## After final land (optional)
|
|
60
|
+
|
|
61
|
+
If delivery gates burned medium+ tokens on tooling (not product code), consider
|
|
62
|
+
`/tooling-friction` once. Never required for program complete.
|
package/skills/fix/SKILL.md
CHANGED
|
@@ -9,12 +9,18 @@ related: [verify, testing-philosophy]
|
|
|
9
9
|
created: "2026-05-13"
|
|
10
10
|
last_reviewed: "2026-07-21"
|
|
11
11
|
name: fix
|
|
12
|
-
description: "Root-cause fix
|
|
12
|
+
description: "Root-cause fix (investigate first if proof missing). Use for fix, blockers, root cause not symptom."
|
|
13
13
|
argument-hint: '<target> where target is: file|symptom|error|test|"free-text description"'
|
|
14
14
|
---
|
|
15
15
|
|
|
16
16
|
# Fix Command
|
|
17
17
|
|
|
18
|
+
## Use when (freeform)
|
|
19
|
+
|
|
20
|
+
- "fix", "root cause not symptom", "blockers", "pre-existing issue"
|
|
21
|
+
- "tooling inefficiency", "MCP not bin/wp", "hook resistance" (bounded — see opportunistic budget)
|
|
22
|
+
- diagnosis already done or `investigate` will run inline first
|
|
23
|
+
|
|
18
24
|
Fix the issue at its root, future-proof, aligned with repo philosophy.
|
|
19
25
|
|
|
20
26
|
**Arguments**: $ARGUMENTS
|
|
@@ -52,6 +58,11 @@ the blast radius is broader than a local fix.
|
|
|
52
58
|
- Each must have: named invariant, failing proof, owning path.
|
|
53
59
|
- If the repair needs its own blueprint or expands epic scope → **handoff backlog**, do not inline.
|
|
54
60
|
- Additional discoveries: list in the final report; do not thrash.
|
|
61
|
+
- **Tooling / harness findings** ("fix inefficiency you come across", MCP vs shell,
|
|
62
|
+
hook thrash) honor the same budget. Excess → record via the `tech-debt` skill
|
|
63
|
+
(or backlog handoff); do not expand the current epic unbounded.
|
|
64
|
+
- Prefer MCP `wp_*` and session-memory tools over `bin/wp` / raw shell for
|
|
65
|
+
quality and discovery paths (see tooling map).
|
|
55
66
|
|
|
56
67
|
## Protocol
|
|
57
68
|
|
|
@@ -123,8 +134,9 @@ Run the narrowest checks that prove the repaired behavior on the real repo surfa
|
|
|
123
134
|
- `wp_lint` / `wp_typecheck` for changed surfaces
|
|
124
135
|
- `wp_qa` only when the blast radius needs the bookend
|
|
125
136
|
- Before push: `wp_ci_preflight` (use global `wp ci-preflight` only when MCP is
|
|
126
|
-
unavailable).
|
|
127
|
-
|
|
137
|
+
unavailable). Run it after the final commit and do not edit or commit again
|
|
138
|
+
before pushing: success records the exact-state receipt checked by pre-push.
|
|
139
|
+
Do not use remote CI re-runs as the primary fix loop (`ci-cost-local-first`).
|
|
128
140
|
|
|
129
141
|
Rules:
|
|
130
142
|
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: skill
|
|
3
|
+
slug: handoff
|
|
4
|
+
title: Handoff
|
|
5
|
+
status: active
|
|
6
|
+
scope: repo
|
|
7
|
+
applies_to: [agents]
|
|
8
|
+
related: [ultragoal, team, plan-refine, fix, verify]
|
|
9
|
+
created: "2026-08-03"
|
|
10
|
+
last_reviewed: "2026-08-03"
|
|
11
|
+
name: handoff
|
|
12
|
+
description: "Cross-session handoff via session_context. Use for continue, take over, resume other host."
|
|
13
|
+
argument-hint: "[--host <claude|codex|grok|opencode>] [session-id|brief]"
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Handoff
|
|
17
|
+
|
|
18
|
+
Produce a **context-light continuation** for another agent, host, or fresh
|
|
19
|
+
session. Do **not** paste full transcripts.
|
|
20
|
+
|
|
21
|
+
## Use when (freeform)
|
|
22
|
+
|
|
23
|
+
- "give me a continuation prompt", "take over where you left off"
|
|
24
|
+
- "resume", "continue from other host", "hand off to Codex/Claude/Grok"
|
|
25
|
+
- cross-session or cross-worktree continuity without history walls
|
|
26
|
+
|
|
27
|
+
## Tooling map
|
|
28
|
+
|
|
29
|
+
| Need | Prefer |
|
|
30
|
+
| ---------------------- | ----------------------------------------------------------------------------------- |
|
|
31
|
+
| Capture decisions | `wp_session_capture` |
|
|
32
|
+
| Context-light manifest | `wp_session_context` (required for subagents) |
|
|
33
|
+
| Prior evidence | `wp_session_search` / `wp_session_retrieve` / `wp_session_restore` |
|
|
34
|
+
| Other-host chat | `wp_conversation_search` / `wp_conversation_get` / `wp_conversation_read` (bounded) |
|
|
35
|
+
| Ultragoal block | `wp_ultragoal_handoff` (≤40 lines) when a controller is active |
|
|
36
|
+
|
|
37
|
+
## Protocol
|
|
38
|
+
|
|
39
|
+
1. **State the objective** in one sentence (what the next agent must finish).
|
|
40
|
+
2. **Capture** short pointers via `wp_session_capture`: done, blockers, decisions,
|
|
41
|
+
evidence refs (log paths, test commands, PR numbers) — not full reports.
|
|
42
|
+
3. **Build** a bounded manifest with `wp_session_context` (objective, constraints,
|
|
43
|
+
evidenceRefs, remainingSteps, validation, exclusions). Never copy parent history.
|
|
44
|
+
4. **Optional cross-host:** resolve the conversation with conversation MCP tools;
|
|
45
|
+
read only a **bounded tail** (`maxMessages` / `maxBytes`). Prefer resume
|
|
46
|
+
commands from `wp_conversation_get` over paste.
|
|
47
|
+
5. **Emit ≤40 lines** covering:
|
|
48
|
+
- goal / non-goals
|
|
49
|
+
- done + evidence refs
|
|
50
|
+
- blockers
|
|
51
|
+
- next 3 concrete commands or skill invocations
|
|
52
|
+
- suggested next skill: `plan-refine` | `fix` | `verify` | `ultragoal` | `land`
|
|
53
|
+
6. Stop. Do not implement the next phase inside handoff unless the user
|
|
54
|
+
explicitly switched the task to execution.
|
|
55
|
+
|
|
56
|
+
## Anti-patterns
|
|
57
|
+
|
|
58
|
+
- Pasting full transcripts or multi-thousand-token "continuation prompts"
|
|
59
|
+
- Claiming resume without a session_context / capture pointer
|
|
60
|
+
- Expanding scope ("also fix everything else") without budgets
|
|
61
|
+
- Using handoff as a substitute for `investigate` / `fix` / `verify`
|
|
62
|
+
|
|
63
|
+
## Done looks like
|
|
64
|
+
|
|
65
|
+
- [ ] ≤40-line handoff with evidence refs
|
|
66
|
+
- [ ] `wp_session_context` (or capture ids) for the next agent
|
|
67
|
+
- [ ] Next skill named
|
|
68
|
+
- [ ] No transcript wall
|
|
@@ -9,7 +9,7 @@ related: []
|
|
|
9
9
|
created: "2026-05-07"
|
|
10
10
|
last_reviewed: "2026-05-07"
|
|
11
11
|
name: hooks-doctor
|
|
12
|
-
description: "
|
|
12
|
+
description: "Hook/plugin doctor for install health. Use for hook blocked, pretooluse, plugin broken."
|
|
13
13
|
argument-hint: "[--skip-mcp]"
|
|
14
14
|
allowed-tools:
|
|
15
15
|
- Bash
|
|
@@ -19,7 +19,7 @@ allowed-tools:
|
|
|
19
19
|
|
|
20
20
|
Verify the webpresso plugin hooks installation is healthy. Run this first when:
|
|
21
21
|
|
|
22
|
-
- A hook seems not to be firing
|
|
22
|
+
- A hook seems not to be firing, is blocked, or PreToolUse denies unexpectedly
|
|
23
23
|
- The plugin was just installed or updated
|
|
24
24
|
- Claude Code can't find expected tools
|
|
25
25
|
- Any plugin integration issue arises
|
|
@@ -55,13 +55,39 @@ Each check prints `[x]` (pass) or `[ ]` (fail) with a detail line:
|
|
|
55
55
|
|
|
56
56
|
## Failure Remediation
|
|
57
57
|
|
|
58
|
-
| Check
|
|
59
|
-
|
|
|
60
|
-
| `pretool-guard` / `post-tool` / etc. — not found
|
|
61
|
-
| `pretool-guard` / etc. — not executable
|
|
62
|
-
| `plugin.json integrity` — missing
|
|
63
|
-
| `MCP server liveness` — timeout
|
|
64
|
-
|
|
|
58
|
+
| Check | Likely Cause | Fix |
|
|
59
|
+
| ---------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `pretool-guard` / `post-tool` / etc. — not found | `wp run build` not run after install | `wp run build` |
|
|
61
|
+
| `pretool-guard` / etc. — not executable | `chmod +x` not persisted | Re-run `wp run prepare` or `wp run build` which runs `chmod-bins` |
|
|
62
|
+
| `plugin.json integrity` — missing | Claude adapter manifest absent from `@webpresso/plugin-claude` | Re-run `wp setup --host claude` or reinstall the Claude plugin |
|
|
63
|
+
| `MCP server liveness` — timeout | MCP server cold-start too slow | Wait and retry, or run `wp hooks doctor --skip-mcp` |
|
|
64
|
+
| `host runtime MCP freshness` — WARNING missing/older | Host `dist/runtime/<target>/wp` missing or older than MCP sources | `pnpm run build:runtime-binaries -- --target host`, then reconnect webpresso MCP / quit host |
|
|
65
|
+
| Any check — not found at `dist/esm/...` | Build artifacts missing | Run `wp run build` in the webpresso repo |
|
|
66
|
+
|
|
67
|
+
### Updating the webpresso MCP server (monorepo authors)
|
|
68
|
+
|
|
69
|
+
`mcp` is **runtime-required**: hosts do not auto-JIT MCP code. After changing
|
|
70
|
+
`src/mcp/**`, conversation catalog, or pretool routing that MCP hosts must run:
|
|
71
|
+
|
|
72
|
+
1. `pnpm run build:runtime-binaries -- --target host`
|
|
73
|
+
2. Reconnect webpresso MCP in the agent host (or full host quit). Optional:
|
|
74
|
+
`pkill -f 'dist/runtime/.*/wp mcp'` if a long-lived process sticks.
|
|
75
|
+
3. Smoke a tool only available in the new code.
|
|
76
|
+
|
|
77
|
+
Chat-only restart is **not** enough. Doctor **MCP liveness** may spawn
|
|
78
|
+
`dist/esm/mcp/cli.js` while the host still runs a stale compiled binary —
|
|
79
|
+
prefer the **host runtime MCP freshness** advisory for monorepo checkouts.
|
|
80
|
+
|
|
81
|
+
**Offline shell allowlist** when webpresso MCP tools are unavailable (must
|
|
82
|
+
match `dev-routing-bounded-read.ts`):
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
rg -n pattern path | head -n 120
|
|
86
|
+
head -n 200 path/to/file
|
|
87
|
+
git log --oneline -n 50
|
|
88
|
+
git show --stat HEAD
|
|
89
|
+
git diff --stat
|
|
90
|
+
```
|
|
65
91
|
|
|
66
92
|
After fixing, re-run `wp hooks doctor` to confirm.
|
|
67
93
|
|
|
@@ -5,46 +5,116 @@ title: Plan Refinement Methodology
|
|
|
5
5
|
status: active
|
|
6
6
|
scope: repo
|
|
7
7
|
applies_to: [agents]
|
|
8
|
-
related:
|
|
8
|
+
related:
|
|
9
|
+
[
|
|
10
|
+
best-practice-research,
|
|
11
|
+
deep-research,
|
|
12
|
+
plan-eng-review,
|
|
13
|
+
plan-ceo-review,
|
|
14
|
+
plan-design-review,
|
|
15
|
+
plan-devex-review,
|
|
16
|
+
ralplan,
|
|
17
|
+
]
|
|
9
18
|
created: "2026-05-07"
|
|
10
|
-
last_reviewed: "2026-
|
|
19
|
+
last_reviewed: "2026-08-02"
|
|
11
20
|
name: plan-refine
|
|
12
|
-
description: "
|
|
21
|
+
description: "Plan hardening to 100% confidence. Use for plan-refine, step back, evaluate plan, don't implement yet."
|
|
13
22
|
---
|
|
14
23
|
|
|
15
24
|
# Plan Refinement Methodology
|
|
16
25
|
|
|
26
|
+
## Use when (freeform)
|
|
27
|
+
|
|
28
|
+
- "take a step back", "evaluate", "don't thrash", "parallel plan"
|
|
29
|
+
- "plan-refine", "fact check the plan", "don't implement yet"
|
|
30
|
+
- hardening a draft blueprint before promotion or execution
|
|
31
|
+
|
|
32
|
+
## Phase 0 — Sync and isolation preflight
|
|
33
|
+
|
|
34
|
+
Before deep plan surgery: confirm intended base (e.g. fetch/align with
|
|
35
|
+
`origin/main` when the user said sync), and do not plan implementation that
|
|
36
|
+
will thrash a dirty primary checkout — bind a managed worktree/blueprint owner
|
|
37
|
+
first when edits will follow.
|
|
38
|
+
|
|
17
39
|
Use when a blueprint or implementation plan needs fact-checking, architecture hardening, parallel task shaping, or review consolidation before execution.
|
|
18
40
|
|
|
41
|
+
## Non-negotiable bar
|
|
42
|
+
|
|
43
|
+
Refine until the plan hits **all four targets** — not “good enough to start”:
|
|
44
|
+
|
|
45
|
+
| Target | Meaning |
|
|
46
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
47
|
+
| **100% confidence** | Every material claim is verified. No residual “we think / probably / should work”. Unverified → **blocked** or rewrite. |
|
|
48
|
+
| **Elegance** | Smallest coherent design that solves the real problem. Prefer delete/reuse over add; reject heavier options that merely work. |
|
|
49
|
+
| **Durability** | Survives version upgrades, ownership boundaries, and the next adjacent change without a rewrite. Record _why_ the shape lasts. |
|
|
50
|
+
| **Efficiency** | Critical path is minimal; wall-clock is maximized via true parallel waves; no speculative layers or busywork tasks. |
|
|
51
|
+
|
|
52
|
+
**Zero assumptions.** Every path, symbol, API, version, env var, and “existing pattern” is either proven with evidence or removed from the plan. Model memory is not evidence.
|
|
53
|
+
|
|
19
54
|
## Core principle
|
|
20
55
|
|
|
21
|
-
A plan is only as strong as its weakest unchecked
|
|
56
|
+
A plan is only as strong as its weakest unchecked claim, only as elegant as what it refuses to add, and only as fast as its coarsest task granularity.
|
|
57
|
+
|
|
58
|
+
## Required workflow (parallel by default)
|
|
22
59
|
|
|
23
|
-
|
|
60
|
+
Run **1–3 (and relevant review lenses) in parallel** whenever tools allow. Do not serialize independent verification. Phases 5–6 wait on their inputs only.
|
|
24
61
|
|
|
25
|
-
1. **Technology fact-check
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
62
|
+
1. **Technology fact-check (official, latest).**
|
|
63
|
+
- Enumerate every external claim (API, package, runtime, platform limit, protocol, CLI flag).
|
|
64
|
+
- Verify each against **official/upstream docs for the exact latest (or pinned) version** in use: vendor docs, release notes, changelogs, package registry metadata — not blogs, Stack Overflow, or model recall.
|
|
65
|
+
- Record version + source URL (or registry identity) next to the claim. Stale or mismatched version → fix the plan.
|
|
66
|
+
- Use `best-practice-research` / official-doc fetch; escalate to `deep-research` only when multi-source depth is required.
|
|
67
|
+
|
|
68
|
+
2. **Codebase verification (pinpoint to code).**
|
|
69
|
+
- Confirm file paths, exports, signatures, call sites, config keys, and conventions with **exact anchors**: `path` + symbol and, when useful, line range.
|
|
70
|
+
- Prefer `rg`/grep + read of the real definition over summaries. “Likely exists” is a fail.
|
|
71
|
+
- Correct every plan statement that does not match the repo **as it is today**.
|
|
72
|
+
|
|
73
|
+
3. **Architecture review.**
|
|
74
|
+
- Adversarial: races, TOCTOU, error cascades, auth/session edges, ownership boundaries, public-package leakage, unnecessary abstractions.
|
|
75
|
+
- Score alternatives on elegance, durability, and efficiency; keep only the winner and write the rejection rationale for heavier options.
|
|
76
|
+
|
|
77
|
+
4. **Plan-review lenses (skip when the caller already ran them).** Folded `/autoplan`: run relevant CEO/founder, design, engineering, and DevEx lenses **in parallel when independent**; consolidate keep/change/drop, unresolved taste calls, tests, go/no-go.
|
|
78
|
+
- **Skip condition.** If the caller states `plan-* reviews complete for this pass`, do **not** re-run the lenses. `ralplan` runs them before handing off, so re-running them here is duplicated spend, not a second opinion.
|
|
79
|
+
- **Re-entry.** If refinement itself **materially changes scope**, re-run only the affected lens — never the full set — then continue applying.
|
|
80
|
+
|
|
81
|
+
5. **Blueprint enforcement (max parallel).**
|
|
82
|
+
- Split for independent execution; declare `Depends`; file-conflict CP = 0 per wave; TDD/proof steps; preserve acceptance criteria.
|
|
83
|
+
- Target high ready-width and CPR; break false dependencies (interface extraction); front-load Wave 0.
|
|
84
|
+
|
|
85
|
+
6. **Apply and record.** Update edge cases, risks, technology choices, cross-plan refs, verification gates. **Do not edit implementation code** during plan refinement.
|
|
31
86
|
|
|
32
87
|
## Mandatory gates
|
|
33
88
|
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
89
|
+
- **0 assumptions** — stop on any material claim without a code pinpoint or official-doc citation at the stated version.
|
|
90
|
+
- **Code pinpoints** — paths/symbols in tasks, risks, and corrections; no floating advice.
|
|
91
|
+
- **Official latest docs** — third-party behavior only from primary sources at the version the plan pins or the latest stable the repo already depends on.
|
|
92
|
+
- Apply DRY, SOLID, YAGNI, KISS; reject speculative abstractions.
|
|
93
|
+
- Choose the most elegant and durable solution constraints allow, not merely a correct one; record why that shape is durable.
|
|
37
94
|
- Prefer deletion/reuse over new layers or dependencies.
|
|
38
|
-
-
|
|
95
|
+
- Package/catalog/generated-surface/release changes → package-surface and public-content checks.
|
|
96
|
+
- Unverified external claims, unresolved shared-file conflicts, or missing authority for destructive work → **blocked**, not “ready with hope”.
|
|
97
|
+
|
|
98
|
+
## Parallel execution of refinement itself
|
|
99
|
+
|
|
100
|
+
| Lane | Work | Tools |
|
|
101
|
+
| ---- | ------------------------- | ------------------------------------------------ |
|
|
102
|
+
| A | Official-doc fact-check | Web/doc fetch, Context7, registry, release notes |
|
|
103
|
+
| B | Code pinpoints | Grep, Read, package exports, config |
|
|
104
|
+
| C | Architecture + elegance | Blueprint only + evidence from A/B |
|
|
105
|
+
| D | Review lenses (as needed) | plan-*-review skills |
|
|
106
|
+
|
|
107
|
+
A/B/C(/D) concurrent → then dependency graph / waves → then single coherent blueprint write.
|
|
39
108
|
|
|
40
109
|
## Output
|
|
41
110
|
|
|
42
111
|
Return a concise plan review with:
|
|
43
112
|
|
|
44
|
-
- verdict
|
|
45
|
-
- material
|
|
46
|
-
-
|
|
113
|
+
- **verdict:** ready / ready with edits / blocked
|
|
114
|
+
- **confidence:** only `ready` when residual material unknowns are **None** (every claim pinned or dropped)
|
|
115
|
+
- material corrections with **evidence** (code pinpoints and/or official doc URL + version)
|
|
116
|
+
- task/dependency changes for **maximum parallel** execution (waves, CPR/RW/CP if non-trivial)
|
|
47
117
|
- required tests and audits
|
|
48
|
-
- residual risks or
|
|
118
|
+
- residual risks only as closed Material Decisions or tech-debt with owner — never open prose in Residual Unknowns (`None.` at promotion)
|
|
49
119
|
|
|
50
120
|
For the full historical checklist and examples, read `references/full-methodology.md` only when deeper plan surgery is needed.
|