A VIPER plan is a saved sequence of typed steps for an AI coding agent. Each step declares what the
agent is allowed to do at that point: investigate without writing, stop and ask you, write files,
verify its work, or pause so you can switch models.
### Step 1 - Explore: Understand the authentication flow
### Step 2 - Propose: Present the safest session-timeout fix
### Step 3 - Pause: Switch model for implementation
### Step 4 - Implement: Fix session timeout handling
### Step 5 - Verify: Run the authentication tests
MCP server exposing VIPER plan storage tools (write, read, edit, list, delete) over stdio
2026-11-16
Estrelas
—
Ferramentas
—
Disponibilidade
—
That plan is not a suggestion the agent may reinterpret. Step 1 cannot edit a file. Step 2 must stop
and wait for your answer. Step 4 may only make the change you approved. Step 5 must run the tests and
stop the run if they fail. Step 3 ends the turn so you can move from a research-strong model to an
implementation-strong one before any code is written.
What this is for
An agent asked to "add rate limiting" will usually start editing before it understands the codebase,
and will usually report success without running anything. The common workaround — asking it to write
a plan first — produces a checklist with no authority: nothing stops the agent from skipping ahead,
and the plan disappears with the conversation.
VIPER plans are different in two ways:
The step type is binding.Explore cannot write. Implement cannot run without an approved
Propose after the last Explore. An Implement block cannot be followed by more exploration
until a Verify has run.
The plan is a file. It lives at .opencode/plans/<name>/plan.md in your workspace. You can
read it, edit it, run it tomorrow, or hand it to a different agent in a fresh session.
Use it
facet add viper-plans
Then, in your agent:
/viper-plan Add request IDs to API error responses
The planning command explores the repository, asks you clarifying questions, and shows you the
finished plan. You approve it — with or without model-switch pauses — and it is written to disk.
/viper-continue
Execution begins immediately: one TODO per step, in order, with the gates the plan declares.
The step types
VIPER names the vocabulary, not the order. Plans run in the order their steps are written, and most
plans use only some of these types.
Step
The agent...
Explore
Reads and searches. Writing anything is forbidden.
Propose
Presents a concrete approach and stops until you approve, reject, or revise it.
Implement
Makes the approved change, and nothing beyond it.
Verify
Runs tests, lint, or type checks. Any failure halts the run.
Review
Presents findings and stops for your feedback.
Pause
Ends the turn at a phase boundary so you can switch models.
Two structural rules hold in every plan:
No Explore straight to Implement. A Propose must come after the last Explore and
before any writing. Research is never allowed to slide silently into edits.
No Implement without a following Verify. A plan cannot end, or turn back to exploration,
on unverified changes.
Common shapes
A typo fix does not need research or approval:
### Step 1 - Implement: Fix the typo in the error message
### Step 2 - Verify: Run the lint check
A change that needs understanding first:
### Step 1 - Explore: Find every caller of the deprecated client
### Step 2 - Propose: Replace the deprecated calls across four files
### Step 3 - Pause: Switch model for implementation
### Step 4 - Implement: Update the four call sites
### Step 5 - Verify: Run the API test suite
Research where you want to weigh in before a direction is chosen:
### Step 1 - Explore: Map the session timeout paths
### Step 2 - Review: Present the gaps found in session handling
### Step 3 - Propose: Fix the timeout in the OAuth callback
### Step 4 - Pause: Switch model for implementation
### Step 5 - Implement: Fix the timeout in the OAuth callback
### Step 6 - Verify: Run the auth test suite
The same plan without pauses, for a run that stays on one model:
### Step 1 - Explore: Map the session timeout paths
### Step 2 - Propose: Fix the timeout in the OAuth callback
### Step 3 - Implement: Fix the timeout in the OAuth callback
### Step 4 - Verify: Run the auth test suite
A plan is pause-enabled if it contains any Pause step, in which case every
exploration⇄implementation boundary must have one. A plan with no Pause steps at all is
pause-free and simply runs straight through. Both are valid; /viper-plan lets you choose when
you approve.
A full run
/viper-plan Add rate limiting to login attempts
The agent reads your auth code and asks what it cannot infer — the limit, the window, whether
lockout is per-account or per-IP. It then shows you a plan and asks how to save it: keeping the
Pause steps, dropping them, or changing something first. On approval it writes
.opencode/plans/login-rate-limit/plan.md and stops. Planning never implements.
/viper-continue
The run starts. Explore reads the login handler and the existing middleware. Propose then shows
you the actual approach it found — which middleware to extend, where the counter lives, what happens
on a cold start — and waits.
This second gate is not a repeat of the first. When you approved the plan, you approved what would
be investigated and in what order. The Propose step asks about the specific change the
investigation turned up, which nobody knew at planning time.
You approve. The next step is a Pause, so the agent prints one line and ends its turn:
Switch models if desired, then send any message to continue.
Switch your model if you want to, then send any message — continue is enough. Do not re-run a
command; the run is already in progress and picks up at the next step.
Implement writes the change. Verify runs the test suite. If anything fails the run stops there
and tells you, rather than pressing on. When the plan finishes, the agent offers to delete it.
The commands
Command
What it does
/viper-plan <goal>
Explores, asks, composes, shows you the plan, and saves it once you approve.
/viper-continue
Runs the plan you just created, with no re-confirmation. Takes an optional name.
/viper-run [name]
Lists saved plans, lets you pick and review one, then executes it.
Use /viper-continue right after planning. Use /viper-run for a plan from an earlier session — or
after a compaction, when the agent no longer remembers which plan is current.
Why the MCP server
The facet works without it: the commands fall back to ordinary file operations. The server is what
makes plan storage dependable rather than improvised.
Plans are real workspace state. They persist across turns, sessions, compactions, and agents,
and can be listed later instead of remembered.
The agent gets plan operations, not path guesswork. Five explicit tools replace an agent
assembling .opencode/plans/... paths by hand and hoping it got the layout right.
Edits cannot clobber what the agent has not seen.viper-edit-plan refuses to touch an
artifact this server has not read or written, and refuses again if the bytes changed since. A plan
you edited by hand mid-run stops the agent instead of being silently overwritten.
Ambiguity fails loudly. An oldString matching more than once is rejected unless you asked for
replaceAll, so a "fix one step" edit cannot quietly rewrite three.
Failures are recoverable. Every failure comes back as a tool error carrying a structured reason
— not_found, stale_read, ambiguous_match, invalid_name — that an agent can read and act on,
rather than an opaque protocol fault.
Storage is protected. Writes are atomic, concurrent operations on one artifact are serialized,
and every path is containment-checked after symlink resolution so nothing outside
<workspace>/.opencode/plans/ is read, written, or deleted.
Tools
Tool
Purpose
viper-write-plan
Create or replace a plan artifact
viper-read-plan
Read an artifact — and license a later edit of it
viper-edit-plan
Exact-string replacement, guarded against stale or ambiguous edits
viper-list-plans
Every plan in the workspace and the artifacts it holds
viper-delete-plan
Remove a plan directory and everything in it
Artifacts live at <workspace>/.opencode/plans/<plan>/<artifact>.md, where artifact defaults to
plan. Plan and artifact names must match ^[A-Za-z0-9][A-Za-z0-9_-]*$ — the grammar that makes a
name safe to join onto a path.
Install
From the registry:
facet add viper-plans
From a local checkout:
facet add ./path/to/viper-plans
Because this facet declares an MCP server, facet asks you to approve that configuration. In CI or
any run without a terminal, approve it up front with facet add viper-plans --accept-mcp.
To configure the server yourself instead, point your client at the published package. It runs on
Node 20 or newer, launched on demand by npx, so nothing is installed into your project:
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo @agent Facets/viper Plans?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
@agent Facets/viper Plans precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte @agent Facets/viper Plans usa?
@agent Facets/viper Plans roda localmente via stdio.
Quando @agent Facets/viper Plans foi verificado pela última vez?
Última verificação: 2026-11-16. MCP server exposing VIPER plan storage tools (write, read, edit, list, delete) over stdio