@agent-facets/viper-plans-mcp 1.3.0 → 1.3.1
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/README.md +215 -62
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,93 +1,246 @@
|
|
|
1
1
|
# VIPER Plans
|
|
2
2
|
|
|
3
|
-
VIPER
|
|
3
|
+
A VIPER plan is a saved sequence of typed steps for an AI coding agent. Each step declares what the
|
|
4
|
+
agent is allowed to do at that point: investigate without writing, stop and ask you, write files,
|
|
5
|
+
verify its work, or pause so you can switch models.
|
|
6
|
+
|
|
7
|
+
```md
|
|
8
|
+
### Step 1 - Explore: Understand the authentication flow
|
|
9
|
+
### Step 2 - Propose: Present the safest session-timeout fix
|
|
10
|
+
### Step 3 - Pause: Switch model for implementation
|
|
11
|
+
### Step 4 - Implement: Fix session timeout handling
|
|
12
|
+
### Step 5 - Verify: Run the authentication tests
|
|
13
|
+
```
|
|
4
14
|
|
|
5
|
-
|
|
6
|
-
|
|
15
|
+
That plan is not a suggestion the agent may reinterpret. Step 1 cannot edit a file. Step 2 must stop
|
|
16
|
+
and wait for your answer. Step 4 may only make the change you approved. Step 5 must run the tests and
|
|
17
|
+
stop the run if they fail. Step 3 ends the turn so you can move from a research-strong model to an
|
|
18
|
+
implementation-strong one before any code is written.
|
|
7
19
|
|
|
8
|
-
##
|
|
20
|
+
## What this is for
|
|
9
21
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
22
|
+
An agent asked to "add rate limiting" will usually start editing before it understands the codebase,
|
|
23
|
+
and will usually report success without running anything. The common workaround — asking it to write
|
|
24
|
+
a plan first — produces a checklist with no authority: nothing stops the agent from skipping ahead,
|
|
25
|
+
and the plan disappears with the conversation.
|
|
13
26
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
}
|
|
22
|
-
}
|
|
23
|
-
```
|
|
27
|
+
VIPER plans are different in two ways:
|
|
28
|
+
|
|
29
|
+
- **The step type is binding.** `Explore` cannot write. `Implement` cannot run without an approved
|
|
30
|
+
`Propose` after the last `Explore`. An `Implement` block cannot be followed by more exploration
|
|
31
|
+
until a `Verify` has run.
|
|
32
|
+
- **The plan is a file.** It lives at `.opencode/plans/<name>/plan.md` in your workspace. You can
|
|
33
|
+
read it, edit it, run it tomorrow, or hand it to a different agent in a fresh session.
|
|
24
34
|
|
|
25
|
-
|
|
35
|
+
## Use it
|
|
26
36
|
|
|
27
37
|
```sh
|
|
28
|
-
facet add viper-plans
|
|
38
|
+
facet add viper-plans
|
|
29
39
|
```
|
|
30
40
|
|
|
31
|
-
|
|
41
|
+
Then, in your agent:
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
/viper-plan Add request IDs to API error responses
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The planning command explores the repository, asks you clarifying questions, and shows you the
|
|
48
|
+
finished plan. You approve it — with or without model-switch pauses — and it is written to disk.
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
/viper-continue
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Execution begins immediately: one TODO per step, in order, with the gates the plan declares.
|
|
55
|
+
|
|
56
|
+
## The step types
|
|
57
|
+
|
|
58
|
+
VIPER names the vocabulary, not the order. Plans run in the order their steps are written, and most
|
|
59
|
+
plans use only some of these types.
|
|
60
|
+
|
|
61
|
+
| Step | The agent... |
|
|
62
|
+
|---------------|---------------------------------------------------------------------------------|
|
|
63
|
+
| **Explore** | Reads and searches. Writing anything is forbidden. |
|
|
64
|
+
| **Propose** | Presents a concrete approach and stops until you approve, reject, or revise it. |
|
|
65
|
+
| **Implement** | Makes the approved change, and nothing beyond it. |
|
|
66
|
+
| **Verify** | Runs tests, lint, or type checks. Any failure halts the run. |
|
|
67
|
+
| **Review** | Presents findings and stops for your feedback. |
|
|
68
|
+
| **Pause** | Ends the turn at a phase boundary so you can switch models. |
|
|
69
|
+
|
|
70
|
+
Two structural rules hold in every plan:
|
|
71
|
+
|
|
72
|
+
1. **No `Explore` straight to `Implement`.** A `Propose` must come after the last `Explore` and
|
|
73
|
+
before any writing. Research is never allowed to slide silently into edits.
|
|
74
|
+
2. **No `Implement` without a following `Verify`.** A plan cannot end, or turn back to exploration,
|
|
75
|
+
on unverified changes.
|
|
76
|
+
|
|
77
|
+
## Common shapes
|
|
78
|
+
|
|
79
|
+
A typo fix does not need research or approval:
|
|
80
|
+
|
|
81
|
+
```md
|
|
82
|
+
### Step 1 - Implement: Fix the typo in the error message
|
|
83
|
+
### Step 2 - Verify: Run the lint check
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
A change that needs understanding first:
|
|
87
|
+
|
|
88
|
+
```md
|
|
89
|
+
### Step 1 - Explore: Find every caller of the deprecated client
|
|
90
|
+
### Step 2 - Propose: Replace the deprecated calls across four files
|
|
91
|
+
### Step 3 - Pause: Switch model for implementation
|
|
92
|
+
### Step 4 - Implement: Update the four call sites
|
|
93
|
+
### Step 5 - Verify: Run the API test suite
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Research where you want to weigh in before a direction is chosen:
|
|
97
|
+
|
|
98
|
+
```md
|
|
99
|
+
### Step 1 - Explore: Map the session timeout paths
|
|
100
|
+
### Step 2 - Review: Present the gaps found in session handling
|
|
101
|
+
### Step 3 - Propose: Fix the timeout in the OAuth callback
|
|
102
|
+
### Step 4 - Pause: Switch model for implementation
|
|
103
|
+
### Step 5 - Implement: Fix the timeout in the OAuth callback
|
|
104
|
+
### Step 6 - Verify: Run the auth test suite
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The same plan without pauses, for a run that stays on one model:
|
|
32
108
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
109
|
+
```md
|
|
110
|
+
### Step 1 - Explore: Map the session timeout paths
|
|
111
|
+
### Step 2 - Propose: Fix the timeout in the OAuth callback
|
|
112
|
+
### Step 3 - Implement: Fix the timeout in the OAuth callback
|
|
113
|
+
### Step 4 - Verify: Run the auth test suite
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
A plan is **pause-enabled** if it contains any `Pause` step, in which case every
|
|
117
|
+
exploration⇄implementation boundary must have one. A plan with no `Pause` steps at all is
|
|
118
|
+
**pause-free** and simply runs straight through. Both are valid; `/viper-plan` lets you choose when
|
|
119
|
+
you approve.
|
|
120
|
+
|
|
121
|
+
## A full run
|
|
122
|
+
|
|
123
|
+
```text
|
|
124
|
+
/viper-plan Add rate limiting to login attempts
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The agent reads your auth code and asks what it cannot infer — the limit, the window, whether
|
|
128
|
+
lockout is per-account or per-IP. It then shows you a plan and asks how to save it: keeping the
|
|
129
|
+
`Pause` steps, dropping them, or changing something first. On approval it writes
|
|
130
|
+
`.opencode/plans/login-rate-limit/plan.md` and stops. Planning never implements.
|
|
131
|
+
|
|
132
|
+
```text
|
|
133
|
+
/viper-continue
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The run starts. `Explore` reads the login handler and the existing middleware. `Propose` then shows
|
|
137
|
+
you the actual approach it found — which middleware to extend, where the counter lives, what happens
|
|
138
|
+
on a cold start — and waits.
|
|
139
|
+
|
|
140
|
+
This second gate is not a repeat of the first. When you approved the plan, you approved *what would
|
|
141
|
+
be investigated and in what order*. The `Propose` step asks about *the specific change the
|
|
142
|
+
investigation turned up*, which nobody knew at planning time.
|
|
143
|
+
|
|
144
|
+
You approve. The next step is a `Pause`, so the agent prints one line and ends its turn:
|
|
145
|
+
|
|
146
|
+
```text
|
|
147
|
+
Switch models if desired, then send any message to continue.
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Switch your model if you want to, then send any message — `continue` is enough. Do not re-run a
|
|
151
|
+
command; the run is already in progress and picks up at the next step.
|
|
152
|
+
|
|
153
|
+
`Implement` writes the change. `Verify` runs the test suite. If anything fails the run stops there
|
|
154
|
+
and tells you, rather than pressing on. When the plan finishes, the agent offers to delete it.
|
|
155
|
+
|
|
156
|
+
## The commands
|
|
157
|
+
|
|
158
|
+
| Command | What it does |
|
|
159
|
+
|------------------------|----------------------------------------------------------------------------------|
|
|
160
|
+
| `/viper-plan <goal>` | Explores, asks, composes, shows you the plan, and saves it once you approve. |
|
|
161
|
+
| `/viper-continue` | Runs the plan you just created, with no re-confirmation. Takes an optional name. |
|
|
162
|
+
| `/viper-run [name]` | Lists saved plans, lets you pick and review one, then executes it. |
|
|
40
163
|
|
|
41
|
-
`
|
|
42
|
-
|
|
164
|
+
Use `/viper-continue` right after planning. Use `/viper-run` for a plan from an earlier session — or
|
|
165
|
+
after a compaction, when the agent no longer remembers which plan is current.
|
|
43
166
|
|
|
44
|
-
|
|
45
|
-
results carrying `success: false` and a specific `reason`, so a model can read and recover from them.
|
|
167
|
+
## Why the MCP server
|
|
46
168
|
|
|
47
|
-
|
|
169
|
+
The facet works without it: the commands fall back to ordinary file operations. The server is what
|
|
170
|
+
makes plan storage dependable rather than improvised.
|
|
48
171
|
|
|
49
|
-
-
|
|
50
|
-
|
|
51
|
-
-
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
-
|
|
172
|
+
- **Plans are real workspace state.** They persist across turns, sessions, compactions, and agents,
|
|
173
|
+
and can be listed later instead of remembered.
|
|
174
|
+
- **The agent gets plan operations, not path guesswork.** Five explicit tools replace an agent
|
|
175
|
+
assembling `.opencode/plans/...` paths by hand and hoping it got the layout right.
|
|
176
|
+
- **Edits cannot clobber what the agent has not seen.** `viper-edit-plan` refuses to touch an
|
|
177
|
+
artifact this server has not read or written, and refuses again if the bytes changed since. A plan
|
|
178
|
+
you edited by hand mid-run stops the agent instead of being silently overwritten.
|
|
179
|
+
- **Ambiguity fails loudly.** An `oldString` matching more than once is rejected unless you asked for
|
|
180
|
+
`replaceAll`, so a "fix one step" edit cannot quietly rewrite three.
|
|
181
|
+
- **Failures are recoverable.** Every failure comes back as a tool error carrying a structured reason
|
|
182
|
+
— `not_found`, `stale_read`, `ambiguous_match`, `invalid_name` — that an agent can read and act on,
|
|
183
|
+
rather than an opaque protocol fault.
|
|
184
|
+
- **Storage is protected.** Writes are atomic, concurrent operations on one artifact are serialized,
|
|
185
|
+
and every path is containment-checked after symlink resolution so nothing outside
|
|
186
|
+
`<workspace>/.opencode/plans/` is read, written, or deleted.
|
|
56
187
|
|
|
57
|
-
|
|
188
|
+
### Tools
|
|
189
|
+
|
|
190
|
+
| Tool | Purpose |
|
|
191
|
+
|---------------------|----------------------------------------------------------------|
|
|
192
|
+
| `viper-write-plan` | Create or replace a plan artifact |
|
|
193
|
+
| `viper-read-plan` | Read an artifact — and license a later edit of it |
|
|
194
|
+
| `viper-edit-plan` | Exact-string replacement, guarded against stale or ambiguous edits |
|
|
195
|
+
| `viper-list-plans` | Every plan in the workspace and the artifacts it holds |
|
|
196
|
+
| `viper-delete-plan` | Remove a plan directory and everything in it |
|
|
197
|
+
|
|
198
|
+
Artifacts live at `<workspace>/.opencode/plans/<plan>/<artifact>.md`, where `artifact` defaults to
|
|
199
|
+
`plan`. Plan and artifact names must match `^[A-Za-z0-9][A-Za-z0-9_-]*$` — the grammar that makes a
|
|
200
|
+
name safe to join onto a path.
|
|
58
201
|
|
|
59
|
-
|
|
60
|
-
`viper-run`, and `viper-continue` commands. The commands prefer the MCP tools above and fall back to
|
|
61
|
-
ordinary file operations when they are unavailable, so the facet works with or without the server.
|
|
202
|
+
## Install
|
|
62
203
|
|
|
63
|
-
|
|
204
|
+
From the registry:
|
|
64
205
|
|
|
65
206
|
```sh
|
|
66
|
-
|
|
67
|
-
mise exec -- bun run format
|
|
68
|
-
mise exec -- bun check
|
|
207
|
+
facet add viper-plans
|
|
69
208
|
```
|
|
70
209
|
|
|
71
|
-
|
|
210
|
+
From a local checkout:
|
|
72
211
|
|
|
73
|
-
|
|
212
|
+
```sh
|
|
213
|
+
facet add ./path/to/viper-plans
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Because this facet declares an MCP server, `facet` asks you to approve that configuration. In CI or
|
|
217
|
+
any run without a terminal, approve it up front with `facet add viper-plans --accept-mcp`.
|
|
218
|
+
|
|
219
|
+
To configure the server yourself instead, point your client at the published package. It runs on
|
|
220
|
+
**Node 20 or newer**, launched on demand by `npx`, so nothing is installed into your project:
|
|
221
|
+
|
|
222
|
+
```jsonc
|
|
223
|
+
{
|
|
224
|
+
"mcp": {
|
|
225
|
+
"viper-plans": {
|
|
226
|
+
"type": "local",
|
|
227
|
+
"command": ["npx", "-y", "@agent-facets/viper-plans-mcp@1.3.1"]
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
```
|
|
74
232
|
|
|
75
|
-
|
|
76
|
-
server declaration launches, and the README example — by `bun run check:version`.
|
|
233
|
+
## Reference
|
|
77
234
|
|
|
78
|
-
|
|
79
|
-
every check, packs one tarball, prints its contents, and publishes that exact file. npm authenticates
|
|
80
|
-
the workflow through OIDC trusted publishing and attaches a provenance attestation, so no npm token
|
|
81
|
-
exists anywhere in the repository.
|
|
235
|
+
The binding rules the agent follows live in the skills themselves:
|
|
82
236
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
237
|
+
- [`skills/viper-planning/SKILL.md`](skills/viper-planning/SKILL.md) — how a well-formed plan is
|
|
238
|
+
composed.
|
|
239
|
+
- [`skills/viper-execution-rules/SKILL.md`](skills/viper-execution-rules/SKILL.md) — how each step
|
|
240
|
+
type is executed and how the rules are enforced.
|
|
87
241
|
|
|
88
|
-
|
|
89
|
-
declared package version is already on npm.
|
|
242
|
+
Working on this repository? See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
90
243
|
|
|
91
244
|
## License
|
|
92
245
|
|
|
93
|
-
MIT
|
|
246
|
+
[MIT](LICENSE)
|