{"_id":"@agent-facets/viper-plans-mcp","_rev":"2-4453e4d21ff1b7b06c0df9b46f29ad98","name":"@agent-facets/viper-plans-mcp","dist-tags":{"latest":"1.3.1"},"versions":{"1.3.0":{"name":"@agent-facets/viper-plans-mcp","version":"1.3.0","keywords":["mcp","modelcontextprotocol","viper","planning","agent","opencode"],"author":{"name":"Julian Coy","email":"julian@agentfacets.io"},"license":"MIT","_id":"@agent-facets/viper-plans-mcp@1.3.0","maintainers":[{"name":"jimador","email":"jamesd1184@gmail.com"},{"name":"juliancoy","email":"julian@ex-machina.co"}],"homepage":"https://github.com/agent-facets/viper-plans#readme","bugs":{"url":"https://github.com/agent-facets/viper-plans/issues"},"bin":{"viper-plans-mcp":"build/index.js"},"dist":{"shasum":"686a9d04ca0316fff12dfa5b87302f8ea7e0518b","tarball":"https://registry.npmjs.org/@agent-facets/viper-plans-mcp/-/viper-plans-mcp-1.3.0.tgz","fileCount":27,"integrity":"sha512-0+UaOVxWJFBZGsTgUHMsQAIY6eEVt7Vf01EPIl+M+7bXDTSNfJL9JEqEEfr/0rAk4nKGyoSyf+ZeQKBeBKoZ2w==","signatures":[{"sig":"MEUCIQDS1J92ZIh0m3KXCEnePyEH+N5EfpVyIHJOhPas+nJ3XAIgJFpIc+68i+BlSMz47PJFHpFDRpWkGSQ+ZjSFmH9UQPQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68410},"type":"module","engines":{"node":">=20"},"exports":{".":{"types":"./build/index.d.ts","default":"./build/index.js"}},"gitHead":"3e94e626cfd1ecc82179295dc8c3bc21481cc7e8","scripts":{"test":"bun test","build":"tsc -p tsconfig.json","check":"turbo run check:format check:types check:version build test check:facet","format":"biome check --write --unsafe .","prepack":"bun run build","check:facet":"facet build --verify","check:types":"tsc -p tsconfig.check.json","check:format":"biome check --error-on-warnings .","check:version":"bun run scripts/check-version.ts"},"_npmUser":{"name":"juliancoy","email":"julian@ex-machina.co"},"repository":{"url":"git+https://github.com/agent-facets/viper-plans.git","type":"git"},"_npmVersion":"11.11.0","description":"MCP server exposing VIPER plan storage tools (write, read, edit, list, delete) over stdio","directories":{},"_nodeVersion":"24.14.1","dependencies":{"arktype":"2.2.3","@modelcontextprotocol/server":"2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.14","devDependencies":{"turbo":"2.10.4","@types/bun":"1.3.14","typescript":"7.0.2","@types/node":"24.13.3","@biomejs/biome":"2.5.9","@modelcontextprotocol/client":"2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/viper-plans-mcp_1.3.0_1787101295973_0.9289842417746133","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"@agent-facets/viper-plans-mcp","version":"1.3.1","description":"MCP server exposing VIPER plan storage tools (write, read, edit, list, delete) over stdio","keywords":["mcp","modelcontextprotocol","viper","planning","agent","opencode"],"license":"MIT","author":{"name":"Julian Coy","email":"julian@agentfacets.io"},"homepage":"https://github.com/agent-facets/viper-plans#readme","repository":{"type":"git","url":"git+https://github.com/agent-facets/viper-plans.git"},"bugs":{"url":"https://github.com/agent-facets/viper-plans/issues"},"type":"module","packageManager":"bun@1.3.14","engines":{"node":">=20"},"bin":{"viper-plans-mcp":"build/index.js"},"exports":{".":{"types":"./build/index.d.ts","default":"./build/index.js"}},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","format":"biome check --write --unsafe .","check":"turbo run check:format check:types check:version build test check:facet","check:format":"biome check --error-on-warnings .","check:types":"tsc -p tsconfig.check.json","test":"bun test","prepack":"bun run build","check:version":"bun run scripts/check-version.ts","check:facet":"facet build --verify"},"dependencies":{"@modelcontextprotocol/server":"2.0.0","arktype":"2.2.3"},"devDependencies":{"@biomejs/biome":"2.5.9","@modelcontextprotocol/client":"2.0.0","@types/bun":"1.3.14","@types/node":"24.13.3","turbo":"2.10.4","typescript":"7.0.2"},"_id":"@agent-facets/viper-plans-mcp@1.3.1","_integrity":"sha512-qGPhYoHb6baveVSMTmfsuIDld04rAX0DF89+WdzmbxItSA9VCfBtLVDWQvdGXE/Ll/HxzRbOH6U382Gn/A3XUg==","_resolved":"/home/runner/work/viper-plans/viper-plans/release/agent-facets-viper-plans-mcp-1.3.1.tgz","_from":"file:/home/runner/work/viper-plans/viper-plans/release/agent-facets-viper-plans-mcp-1.3.1.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-qGPhYoHb6baveVSMTmfsuIDld04rAX0DF89+WdzmbxItSA9VCfBtLVDWQvdGXE/Ll/HxzRbOH6U382Gn/A3XUg==","shasum":"660ad305098d40cbcbab7db49295b026dd6bce4a","tarball":"https://registry.npmjs.org/@agent-facets/viper-plans-mcp/-/viper-plans-mcp-1.3.1.tgz","fileCount":27,"unpackedSize":74987,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-facets%2fviper-plans-mcp@1.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBa1xrkDnZ/djFhnc6llC3enR6BIqUTQxJHQgdTi8sqCAiEAv6eTLO5uojXOjdnPDEGNMrX0Mhc9gn30cINdivUB7N0="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0c7314e8-ae37-4ec2-b186-1ac6df57b708"}},"directories":{},"maintainers":[{"name":"jimador","email":"jamesd1184@gmail.com"},{"name":"juliancoy","email":"julian@ex-machina.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/viper-plans-mcp_1.3.1_1788233649409_0.18321706398089388"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-19T01:01:35.753Z","modified":"2026-09-01T03:34:09.916Z","1.3.0":"2026-08-19T01:01:36.114Z","1.3.1":"2026-09-01T03:34:09.550Z"},"bugs":{"url":"https://github.com/agent-facets/viper-plans/issues"},"author":{"name":"Julian Coy","email":"julian@agentfacets.io"},"license":"MIT","homepage":"https://github.com/agent-facets/viper-plans#readme","keywords":["mcp","modelcontextprotocol","viper","planning","agent","opencode"],"repository":{"type":"git","url":"git+https://github.com/agent-facets/viper-plans.git"},"description":"MCP server exposing VIPER plan storage tools (write, read, edit, list, delete) over stdio","maintainers":[{"name":"jimador","email":"jamesd1184@gmail.com"},{"name":"juliancoy","email":"julian@ex-machina.co"}],"readme":"# VIPER Plans\n\nA VIPER plan is a saved sequence of typed steps for an AI coding agent. Each step declares what the\nagent is allowed to do at that point: investigate without writing, stop and ask you, write files,\nverify its work, or pause so you can switch models.\n\n```md\n### Step 1 - Explore: Understand the authentication flow\n### Step 2 - Propose: Present the safest session-timeout fix\n### Step 3 - Pause: Switch model for implementation\n### Step 4 - Implement: Fix session timeout handling\n### Step 5 - Verify: Run the authentication tests\n```\n\nThat plan is not a suggestion the agent may reinterpret. Step 1 cannot edit a file. Step 2 must stop\nand wait for your answer. Step 4 may only make the change you approved. Step 5 must run the tests and\nstop the run if they fail. Step 3 ends the turn so you can move from a research-strong model to an\nimplementation-strong one before any code is written.\n\n## What this is for\n\nAn agent asked to \"add rate limiting\" will usually start editing before it understands the codebase,\nand will usually report success without running anything. The common workaround — asking it to write\na plan first — produces a checklist with no authority: nothing stops the agent from skipping ahead,\nand the plan disappears with the conversation.\n\nVIPER plans are different in two ways:\n\n- **The step type is binding.** `Explore` cannot write. `Implement` cannot run without an approved\n  `Propose` after the last `Explore`. An `Implement` block cannot be followed by more exploration\n  until a `Verify` has run.\n- **The plan is a file.** It lives at `.opencode/plans/<name>/plan.md` in your workspace. You can\n  read it, edit it, run it tomorrow, or hand it to a different agent in a fresh session.\n\n## Use it\n\n```sh\nfacet add viper-plans\n```\n\nThen, in your agent:\n\n```text\n/viper-plan Add request IDs to API error responses\n```\n\nThe planning command explores the repository, asks you clarifying questions, and shows you the\nfinished plan. You approve it — with or without model-switch pauses — and it is written to disk.\n\n```text\n/viper-continue\n```\n\nExecution begins immediately: one TODO per step, in order, with the gates the plan declares.\n\n## The step types\n\nVIPER names the vocabulary, not the order. Plans run in the order their steps are written, and most\nplans use only some of these types.\n\n| Step          | The agent...                                                                    |\n|---------------|---------------------------------------------------------------------------------|\n| **Explore**   | Reads and searches. Writing anything is forbidden.                              |\n| **Propose**   | Presents a concrete approach and stops until you approve, reject, or revise it. |\n| **Implement** | Makes the approved change, and nothing beyond it.                               |\n| **Verify**    | Runs tests, lint, or type checks. Any failure halts the run.                    |\n| **Review**    | Presents findings and stops for your feedback.                                  |\n| **Pause**     | Ends the turn at a phase boundary so you can switch models.                     |\n\nTwo structural rules hold in every plan:\n\n1. **No `Explore` straight to `Implement`.** A `Propose` must come after the last `Explore` and\n   before any writing. Research is never allowed to slide silently into edits.\n2. **No `Implement` without a following `Verify`.** A plan cannot end, or turn back to exploration,\n   on unverified changes.\n\n## Common shapes\n\nA typo fix does not need research or approval:\n\n```md\n### Step 1 - Implement: Fix the typo in the error message\n### Step 2 - Verify: Run the lint check\n```\n\nA change that needs understanding first:\n\n```md\n### Step 1 - Explore: Find every caller of the deprecated client\n### Step 2 - Propose: Replace the deprecated calls across four files\n### Step 3 - Pause: Switch model for implementation\n### Step 4 - Implement: Update the four call sites\n### Step 5 - Verify: Run the API test suite\n```\n\nResearch where you want to weigh in before a direction is chosen:\n\n```md\n### Step 1 - Explore: Map the session timeout paths\n### Step 2 - Review: Present the gaps found in session handling\n### Step 3 - Propose: Fix the timeout in the OAuth callback\n### Step 4 - Pause: Switch model for implementation\n### Step 5 - Implement: Fix the timeout in the OAuth callback\n### Step 6 - Verify: Run the auth test suite\n```\n\nThe same plan without pauses, for a run that stays on one model:\n\n```md\n### Step 1 - Explore: Map the session timeout paths\n### Step 2 - Propose: Fix the timeout in the OAuth callback\n### Step 3 - Implement: Fix the timeout in the OAuth callback\n### Step 4 - Verify: Run the auth test suite\n```\n\nA plan is **pause-enabled** if it contains any `Pause` step, in which case every\nexploration⇄implementation boundary must have one. A plan with no `Pause` steps at all is\n**pause-free** and simply runs straight through. Both are valid; `/viper-plan` lets you choose when\nyou approve.\n\n## A full run\n\n```text\n/viper-plan Add rate limiting to login attempts\n```\n\nThe agent reads your auth code and asks what it cannot infer — the limit, the window, whether\nlockout is per-account or per-IP. It then shows you a plan and asks how to save it: keeping the\n`Pause` steps, dropping them, or changing something first. On approval it writes\n`.opencode/plans/login-rate-limit/plan.md` and stops. Planning never implements.\n\n```text\n/viper-continue\n```\n\nThe run starts. `Explore` reads the login handler and the existing middleware. `Propose` then shows\nyou the actual approach it found — which middleware to extend, where the counter lives, what happens\non a cold start — and waits.\n\nThis second gate is not a repeat of the first. When you approved the plan, you approved *what would\nbe investigated and in what order*. The `Propose` step asks about *the specific change the\ninvestigation turned up*, which nobody knew at planning time.\n\nYou approve. The next step is a `Pause`, so the agent prints one line and ends its turn:\n\n```text\nSwitch models if desired, then send any message to continue.\n```\n\nSwitch your model if you want to, then send any message — `continue` is enough. Do not re-run a\ncommand; the run is already in progress and picks up at the next step.\n\n`Implement` writes the change. `Verify` runs the test suite. If anything fails the run stops there\nand tells you, rather than pressing on. When the plan finishes, the agent offers to delete it.\n\n## The commands\n\n| Command                | What it does                                                                     |\n|------------------------|----------------------------------------------------------------------------------|\n| `/viper-plan <goal>`   | Explores, asks, composes, shows you the plan, and saves it once you approve.      |\n| `/viper-continue`      | Runs the plan you just created, with no re-confirmation. Takes an optional name.  |\n| `/viper-run [name]`    | Lists saved plans, lets you pick and review one, then executes it.                |\n\nUse `/viper-continue` right after planning. Use `/viper-run` for a plan from an earlier session — or\nafter a compaction, when the agent no longer remembers which plan is current.\n\n## Why the MCP server\n\nThe facet works without it: the commands fall back to ordinary file operations. The server is what\nmakes plan storage dependable rather than improvised.\n\n- **Plans are real workspace state.** They persist across turns, sessions, compactions, and agents,\n  and can be listed later instead of remembered.\n- **The agent gets plan operations, not path guesswork.** Five explicit tools replace an agent\n  assembling `.opencode/plans/...` paths by hand and hoping it got the layout right.\n- **Edits cannot clobber what the agent has not seen.** `viper-edit-plan` refuses to touch an\n  artifact this server has not read or written, and refuses again if the bytes changed since. A plan\n  you edited by hand mid-run stops the agent instead of being silently overwritten.\n- **Ambiguity fails loudly.** An `oldString` matching more than once is rejected unless you asked for\n  `replaceAll`, so a \"fix one step\" edit cannot quietly rewrite three.\n- **Failures are recoverable.** Every failure comes back as a tool error carrying a structured reason\n  — `not_found`, `stale_read`, `ambiguous_match`, `invalid_name` — that an agent can read and act on,\n  rather than an opaque protocol fault.\n- **Storage is protected.** Writes are atomic, concurrent operations on one artifact are serialized,\n  and every path is containment-checked after symlink resolution so nothing outside\n  `<workspace>/.opencode/plans/` is read, written, or deleted.\n\n### Tools\n\n| Tool                | Purpose                                                        |\n|---------------------|----------------------------------------------------------------|\n| `viper-write-plan`  | Create or replace a plan artifact                              |\n| `viper-read-plan`   | Read an artifact — and license a later edit of it              |\n| `viper-edit-plan`   | Exact-string replacement, guarded against stale or ambiguous edits |\n| `viper-list-plans`  | Every plan in the workspace and the artifacts it holds         |\n| `viper-delete-plan` | Remove a plan directory and everything in it                   |\n\nArtifacts live at `<workspace>/.opencode/plans/<plan>/<artifact>.md`, where `artifact` defaults to\n`plan`. Plan and artifact names must match `^[A-Za-z0-9][A-Za-z0-9_-]*$` — the grammar that makes a\nname safe to join onto a path.\n\n## Install\n\nFrom the registry:\n\n```sh\nfacet add viper-plans\n```\n\nFrom a local checkout:\n\n```sh\nfacet add ./path/to/viper-plans\n```\n\nBecause this facet declares an MCP server, `facet` asks you to approve that configuration. In CI or\nany run without a terminal, approve it up front with `facet add viper-plans --accept-mcp`.\n\nTo configure the server yourself instead, point your client at the published package. It runs on\n**Node 20 or newer**, launched on demand by `npx`, so nothing is installed into your project:\n\n```jsonc\n{\n  \"mcp\": {\n    \"viper-plans\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@agent-facets/viper-plans-mcp@1.3.1\"]\n    }\n  }\n}\n```\n\n## Reference\n\nThe binding rules the agent follows live in the skills themselves:\n\n- [`skills/viper-planning/SKILL.md`](skills/viper-planning/SKILL.md) — how a well-formed plan is\n  composed.\n- [`skills/viper-execution-rules/SKILL.md`](skills/viper-execution-rules/SKILL.md) — how each step\n  type is executed and how the rules are enforced.\n\nWorking on this repository? See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}