@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.
Files changed (2) hide show
  1. package/README.md +215 -62
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,93 +1,246 @@
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
+
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
- | 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 |
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
- `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_-]*$`.
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
- 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.
167
+ ## Why the MCP server
46
168
 
47
- ### Storage and safety
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
- - 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.
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
- ## The facet
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
- 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.
202
+ ## Install
62
203
 
63
- ## Development
204
+ From the registry:
64
205
 
65
206
  ```sh
66
- mise exec -- bun install
67
- mise exec -- bun run format
68
- mise exec -- bun check
207
+ facet add viper-plans
69
208
  ```
70
209
 
71
- `facet build --verify` validates the facet itself.
210
+ From a local checkout:
72
211
 
73
- ## Releasing
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
- `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`.
233
+ ## Reference
77
234
 
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.
235
+ The binding rules the agent follows live in the skills themselves:
82
236
 
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.
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
- Publishing the facet is separate: `facet build` then `facet publish`, from a merged commit whose
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)
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": "1.3.1",
4
4
  "description": "MCP server exposing VIPER plan storage tools (write, read, edit, list, delete) over stdio",
5
5
  "keywords": [
6
6
  "mcp",