@@@  @@@  @@@  @@@@@@@   @@@@@@@@  @@@@@@@
   @@@  @@@  @@@  @@@@@@@@  @@@@@@@@  @@@@@@@@
   @@!  @@@  @@!  @@!  @@@  @@!       @@!  @@@
   !@!  @!@  !@!  !@!  @!@  !@!       !@!  @!@
   @!@  !@!  !!@  @!@@!@!   @!!!:!    @!@!!@!
   !@!  !!!  !!!  !!@!!!    !!!!!:    !!@!@!
   :!:  !!:  !!:  !!:       !!:       !!: :!!
    ::!!:!   :!:  :!:       :!:       :!:  !:!
     ::::     ::   ::        :: ::::  ::   :::
      :      :     :        : :: ::    :   : :
                                          ____
     ____________________________________/ O  \__
    <_/_\_/_\_/_\_/_\_/_\_/_\_/_\_/_\_/_______/

VIPER

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

VIPER structures complex work across five canonical phases — Vision, 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 11 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 init

This puts two bins on your PATH:

| Bin | Purpose | | ----------- | ---------------------------------------------------------------------------- | | viper | The CLI: init, new, list, status, validate, migrate, uninstall | | viper-mcp | The MCP stdio server. Claude Code spawns this via .mcp.json |

On npx: the package has two bins (viper, viper-mcp), and npx can't auto-resolve which one to run when the unscoped package name (cli) doesn't match either. So npx @viper-ai/cli viper init fails with could not determine executable to run. Use:

npx -y -p @viper-ai/cli viper init

The -p (= --package) is the workaround. That said, global install is the recommended path — the MCP integration writes command: "viper-mcp" into .mcp.json, which assumes viper-mcp is on PATH. A one-off npx install won't satisfy that.

Local dev (hacking on VIPER itself)

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

npm run package rebuilds the publishable bundle at dist/publish/; npm link puts the linked bins on your PATH. Subsequent npm run package runs refresh the linked bins in place.

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 vision,plan,…] [--author email] [--non-interactive]

Atomically scaffold .viper/NNN-<slug>/ with the selected phase files. 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 11 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_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 the upstream phase isn't status: complete
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: 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: 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: [[email protected]]
  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.mjs    # esbuild bundle → dist/publish/ for npm link / npm 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). At publish time tools/package.mjs bundles both apps via esbuild into a single CJS file each, with React + @wolf-tui/* kept external (native addon resolution needs real Node module resolution).

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 dist/publish
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/templates — 5 phase scaffolds, 6 skill stubs, 3 agent stubs, hooks + MCP snippets
• 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 → dist/publish/ ready for npm link or npm 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.