@agent-facets/viper-plans-mcp 1.3.0 → 2.0.0

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