@@@  @@@  @@@  @@@@@@@   @@@@@@@@  @@@@@@@
   @@@  @@@  @@@  @@@@@@@@  @@@@@@@@  @@@@@@@@
   @@!  @@@  @@!  @@!  @@@  @@!       @@!  @@@
   !@!  @!@  !@!  !@!  @!@  !@!       !@!  @!@
   @!@  !@!  !!@  @!@@!@!   @!!!:!    @!@!!@!
   !@!  !!!  !!!  !!@!!!    !!!!!:    !!@!@!
   :!:  !!:  !!:  !!:       !!:       !!: :!!
    ::!!:!   :!:  :!:       :!:       :!:  !:!
     ::::     ::   ::        :: ::::  ::   :::
      :      :     :        : :: ::    :   : :

VIPER

A phased development workflow for Claude Code that combats context rot.

Docs: https://syncrea.ch/viper-ai/

VIPER structures complex work across five canonical phases — Vision (optional), Investigate, Plan, Execute, Review — and keeps each phase's reasoning in a single addressable artifact under .viper/NNN-<slug>/. The whole workflow ships as a CLI + MCP server + Claude Code skills, with deterministic validation so structural drift gets caught immediately.

A core principle is maximizing ownership. The human stays the author at every phase: the agent does legwork (subagent fan-out, codebase reads, plan validation, parallel execution) but the human owns every decision branch. The guided Review walkthrough at the end is what closes that loop — it forces the creator to re-internalize what actually shipped before they ship it, and turns the resulting docs into a paced narrative that human PR reviewers can follow instead of doing grep-the-diff archaeology. Without that step, both creator and reviewer lose the thread.

.claude/
  skills/
    viper/SKILL.md                # /viper          — discovery entry
    viper-1-vision/SKILL.md         # /viper-1-vision   — fan out 4–8 ideators, converge
    viper-2-investigate/SKILL.md    # /viper-2-investigate
    viper-3-plan/SKILL.md           # /viper-3-plan
    viper-4-execute/SKILL.md        # /viper-4-execute
    viper-5-review/SKILL.md         # /viper-5-review
  agents/
    viper-ideator.md              # spawned in parallel during Vision
    viper-investigator.md         # spawned in parallel during Investigate
    viper-executor.md             # one per agent slot during Execute
  settings.local.json             # PostToolUse hook (optional)

.viper/
  001-<slug>/
    vision.md
    investigation.md
    plan.md
    execution.md
    review.md

---

Status

Early pre-release on npm (@viper-ai/cli). The CLI, MCP server, all 12 MCP tools, all five phase skills, both subagents, and the four TUI wizards are functional. See Project status for what's still TODO.

---

Install

npm i -g @viper-ai/cli @viper-ai/mcp
viper init

Package	Bin	Purpose
@viper-ai/cli	viper	init, new, list, status, validate, migrate, uninstall
@viper-ai/mcp	viper-mcp	MCP stdio server (also spawnable via npx; see below)

Without global install, viper init writes .mcp.json to run MCP via:

"command": "npx",
"args": ["-y", "@viper-ai/mcp", "viper-mcp"]

For one-off CLI use:

npx -y @viper-ai/cli viper init

Local dev (hacking on VIPER itself)

See docs/LOCAL_DEV.md. Quick path — publish-shaped bins on your PATH:

git clone https://github.com/syncrea/viper-ai.git && cd viper-ai
npm install
npm run package
npm run link:cli && npm run link:mcp

npm run package rebuilds bundled apps/viper-cli/dist and apps/viper-mcp/dist; link scripts register global viper and viper-mcp.

---

Quick start

mkdir my-project && cd my-project
git init -q

# 1. Install VIPER skills + MCP server into the project
viper init                       # interactive wizard
# or: viper init --non-interactive --with-hooks

# 2. Create your first idea (interactive)
viper new

# 3. Start Claude Code in this project
#    The MCP server (viper-mcp) auto-connects via .mcp.json
#    Type /viper to see the phase skills

# 4. Validate the .viper tree any time
viper validate

# 5. See progress
viper list
viper status 001-<slug>

---

Commands

All commands support --json (or non-TTY stdout) for machine-readable output. Interactive wizards launch automatically in a TTY; pass --non-interactive to skip them.

viper init [--with-hooks] [--strict-hooks] [--force] [--non-interactive]

Install skills, agents, and MCP server config into the current project:

• .claude/skills/viper*/SKILL.md — five phase skills + master
• .claude/agents/viper-{ideator,investigator,executor}.md
• .mcp.json — merges in a viper entry (preserves others)
• .viper/.viper-state.json, .viper/.gitignore
• Appends .viper/**/.viper-runtime/ to the repo's .gitignore
• With --with-hooks: writes a PostToolUse hook that runs viper validate on every Write/Edit under .viper/
• With --strict-hooks: the hook fails the tool call on validation errors (default: warn-only)
• With --force: overwrites existing skill/agent files (use to refresh after a viper upgrade)

viper new [slug] [--phases investigation,plan,…] [--author email] [--non-interactive]

Atomically scaffold .viper/NNN-<slug>/ with the selected phase files. Defaults to the four required phases (Investigate → Plan → Execute → Review); add vision when you want the ideation phase. Numbering is derived deterministically from existing directories. Author defaults to git config user.email.

viper list [--json] [--status draft|in-progress|complete]

List ideas with their current-phase status. TUI table in a terminal; JSON in pipes or with --json.

viper status <idea> [--json] [--phase vision|…]

Detailed per-phase view: status, task progress (for plan), error/warning counts, deviation + note counts. The <idea> argument accepts full dirName (001-add-streaming), number (001 or 1), or slug (add-streaming).

viper validate [path] [--json] [--strict]

Run the same validator engine that the MCP server exposes. Three modes:

• viper validate — walk every .viper/**/*.md
• viper validate path/to/file.md — single file
• viper validate .viper/001-foo — single idea directory

Output: text (OK/ERROR/WARN <path>:<line> <CODE> <message>) or JSON. Exit codes: 0 ok, 1 errors, 2 warnings with --strict. Cross-file checks include PHASE_DIR_MISMATCH, UPSTREAM_NOT_FOUND, UPSTREAM_INCOMPLETE.

viper migrate [--dry-run] [--json]

Walk every phase doc and run the schema migration framework. v1 is the current schema — docs at v1 report OK (no-op). Future-schema docs error. The framework is wired so future v2+ transforms only need to be added in libs/schema/src/migrate.ts.

viper uninstall [--no-keep-docs]

Remove skills, agents, the viper entry from .mcp.json, and the PostToolUse hook. Preserves unrelated .mcp.json servers and other hooks. By default keeps .viper/ (the artifacts you wrote); pass --no-keep-docs to remove that too.

---

MCP tools

Spawned via .mcp.json after viper init. All 12 tools are thin adapters over the same library code the CLI uses.

Tool	What it does
viper_ping	Capability probe. Returns { ok, version, cwd }.
viper_validate	Validate a phase file, idea dir, or the whole tree.
viper_list_ideas	List ideas with per-phase status.
viper_get_phase	Read a single phase doc; returns parsed frontmatter, sections, tasks, validation issues.
viper_create_idea	Atomically create a new idea scaffold from templates.
viper_set_status	Set viper.status on a phase doc, refresh updated.
viper_advance_phase	Verify from.status == complete, create to.md from template if missing.
viper_ensure_phase	Create a phase doc from template if missing (supports bootstrapping Investigate without Vision).
viper_search_tasks	Cross-idea task search by query / agent / idea / depends / status.
viper_record_event	Append a task_start / task_done / deviation / note event to the per-agent JSONL log.
viper_merge_execution	Project all per-agent JSONL events into the canonical execution.md. Idempotent.
viper_detect_spec_tools	Detect OpenSpec / SpecKit / GSD in the current project.

Skills probe viper_ping at boot and shell out to viper <subcommand> if the MCP server isn't reachable — graceful degradation.

---

Skills + agents

Each phase skill is one SKILL.md shipped to .claude/skills/viper-<phase>/. They all:

1. Probe MCP at boot
2. Refuse to run if a required upstream phase isn't status: complete (Vision is optional)
3. Apply a recap-then-ask-then-cross-pollinate UX for every multi-option decision
4. Suggest /clear + the next phase on close-out

Key per-phase behaviors:

• viper-1-vision (optional): Spawns 4-8 viper-ideator subagents in parallel exploring distinct angles. Recaps every variant before asking. Cross-pollination prompt always runs, even if the pick was decisive.
• viper-2-investigate: Confirms with the user before skipping Vision. Splits questions into codebase / external / human piles, fans out viper-investigator subagents for the first two, writes a Vocabulary glossary in investigation.md.
• viper-3-plan: Detects OpenSpec/SpecKit/GSD first; offers handoff. Otherwise produces a Feature → Story → Task tree with agent:N / depends: metadata, validates the DAG, and shows a Parallel Execution Map.
• viper-4-execute: Pure orchestrator. Spawns one viper-executor per agent slot, projects JSONL events into execution.md after every return. Never reads the codebase itself.
• viper-5-review: Reads all four upstreams + git diff, builds a numbered Demo Walkthrough with [PAUSE] markers, walks the user through interactively.

---

Document schema

Every phase artifact starts with:

---
viper:
  schema: 1
  phase: vision # vision | investigation | plan | execution | review
  idea: 001-add-streaming # must equal containing dir name
  status: draft # draft | in-progress | complete
  created: 2026-05-17T10:30:00Z
  updated: 2026-05-17T11:45:00Z
  authors: [you@example.com]
  related: []
  upstream: # paths to prior-phase docs
    - .viper/001-add-streaming/vision.md
  tags: []
---

Section skeletons per phase are enforced by the validator (libs/schema/src/sections.ts):

Phase	Required sections
vision	Summary · Problem & Motivation · Explored Variants · Selected Direction · Key Decisions · Open Questions for Next Phase · References
investigation	Vocabulary · Current State · Constraints & Dependencies · External Dependencies · Risks & Unknowns · Recommendations for Plan
plan	Scope · Strategy · Backwards Compatibility & Migration · Feature Flags / Isolation · Features · Parallel Execution Map · Acceptance Criteria
execution	Status · Plan Deviations · Notes
review	Summary · Demo Walkthrough · Deviations from Plan · Loose Ends / Follow-ups

Plan tasks parse as:

- [ ] **T1.2.3**: short imperative — agent:2 depends:T1.2.1,T1.1.4 est:30m tags:io,perf

The DAG validator runs Tarjan's SCC and rejects cycles or self-loops.

---

Project structure

Nx monorepo with the TS-solution preset:

viper-cli/
├── apps/
│   ├── viper-cli/     # Commander CLI (CJS)
│   └── viper-mcp/     # MCP stdio server (CJS)
├── libs/
│   ├── schema/        # Zod schemas, parser, task DAG validator, migration framework (CJS)
│   ├── core/          # fs, ideas, events, install/uninstall, validate, summarize, idea-detail, search-tasks (CJS)
│   ├── templates/     # bundled .md content + loader (CJS)
│   └── tui/           # React (wolf-tui) wizards — init, new, list, status (ESM)
├── tools/
│   └── package-app.mjs # bundle apps/*/dist for npm link / publish
└── docs/
    ├── high-level-plan.md
    └── implementation-plan.md

CJS libs use @nx/node:lib and require no .js extensions on internal imports. The ESM TUI lib uses @nx/react:lib --bundler=none and imports with .js (Node ESM rule). tools/package-app.mjs bundles each app to apps/*/dist/main.js for publish, with React + @wolf-tui/* external on the CLI only.

---

Development

Standard verification chain after any change:

npx nx format && npx nx run-many -t lint,test,build

To exercise everything end-to-end:

npm run package           # rebuilds apps/*/dist publish trees
cd /tmp && rm -rf demo && mkdir demo && cd demo && git init -q
viper init --non-interactive
viper new add-streaming --non-interactive
viper validate
viper list --json
viper status add-streaming
viper uninstall --no-keep-docs

To trace TUI errors:

VIPER_DEBUG=1 viper init

To smoke-test the MCP server:

(printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n'; sleep 0.3) | viper-mcp

---

Project status

✅ Shipped

• libs/schema — frontmatter schema, sections, task parser + DAG validator, migration framework
• libs/core — paths, ideas, events, merge, install, summarize, validate, search-tasks, idea-detail
• libs/core/src/templates — 5 phase scaffolds, 6 skill stubs, 3 agent stubs, hooks + MCP snippets (loaded via @viper-ai/core)
• apps/viper-cli — all 7 commands with both TUI and non-interactive paths
• apps/viper-mcp — 11 MCP tools
• Phase skills (viper, viper-1-vision, viper-2-investigate, viper-3-plan, viper-4-execute, viper-5-review) and subagents (viper-ideator, viper-investigator, viper-executor)
• libs/tui — wolf-tui-react wizards for init, new, list, status
• Publishing pipeline — npm run package → apps/viper-cli/dist + apps/viper-mcp/dist; nx release publish

🚧 TODO

• E2E harness — apps/viper-cli-e2e recreate (T2.2)
• MCP resources + subscriptions — passive discovery via viper://ideas/… URIs (plan §587-606)
• Publishing to npm under @viper-ai/cli

---

License

MIT.