Nerds Vibecoding Survivor Toolkit

🚧 Work in Progress: This toolkit is currently under active development.

Purpose

This repository contains nerds-vst (Nerd's Vibecoding Survivor Toolkit).

nerds-vst is a framework and command-line tool built on Bun, designed to help you create and develop projects from scratch using a specification-driven development pattern powered by AI coding—a process informally known as vibecoding. This repository is the toolkit implementation; usage and workflow documentation will be published with the package.

The framework is built on the following principles:

• Single source of truth — State is centralized, minimizing the risk of AI hallucination and reducing ambiguity.
• Context is everything — Leveraging diverse project context and specialized skills helps both AI and humans to better understand and reason about the project.
• Human in the loop — Mandatory review and decision points ensure that humans define and validate key steps in every iteration.
• Build fast / Fail fast — Developers can grant AI a controlled degree of autonomy to enable rapid prototyping, embodying the agile principle of building quickly and embracing early failure.
• Iterative development — Strongly encourages building software incrementally, block by block, allowing time to refactor and address technical debt during each iteration instead of all at once.
• Agnostic agent support — Whether you prefer Claude, Codex, Gemini, or another CLI-based agent, the toolkit is designed to easily integrate with most agent providers and lets you choose or combine the tools that best fit your workflow.

Features

nerds-vst is a package that provides:

• Scaffold tool — Running nvst init initializes the framework by copying the template to the target project, creating the core structure:

  AGENTS.md         # Entry point for agents
  .agents/          # Workflow state and artifacts
    state.json      # Current iteration state
    PROJECT_CONTEXT.md
    skills/         # Agent skills (populated when you install bundled skills during init)
    flow/           # Iteration artifacts (PRDs, etc.)
  

  Core template files live under scaffold/ and are copied to the target project; bundled skills ship from nvst-skills/ via nvst init (see nvst init and skill selection).

• Command-line tool — Prompts and orchestrates the development loop, keeping state in sync. Instead of internally calling an agent within the commands, it outputs instructions as prompts to be executed by your preferred AI environment (e.g., Cursor, Antigravity, Claude Code Web, GitHub Copilot).

  Command summary (see docs/nvst-flow/COMMANDS.md for the full reference):

  nvst start iteration → nvst define requirement → nvst refine requirement → nvst approve requirement → nvst create prototype → nvst audit prototype → nvst refactor prototype → nvst approve prototype

  Group	Commands
  Main loop	nvst start iteration, nvst define requirement, nvst refine requirement (optional), nvst approve requirement, nvst create prototype, nvst audit prototype, nvst refactor prototype, nvst approve prototype
  Utilities	nvst init, nvst destroy [--clean], nvst sync skills (maintainers), nvst write-json, nvst write-technical-debt

  Agent providers: claude, codex, gemini, cursor, copilot, ide — where ide prints skill prompts to stdout instead of invoking an agent subprocess.

  Typical iteration example:

  nvst start iteration
  nvst define requirement --agent [claude|gemini|codex]
  nvst refine requirement --agent [claude|gemini|codex] --challenge # optional
  nvst approve requirement
  nvst create prototype --agent [claude|gemini|codex] 
  nvst audit prototype --agent [claude|gemini|codex]
  nvst refactor prototype --agent [claude|gemini|codex]
  nvst approve prototype

  Note: Using CLI-based agents (claude, gemini, codex) is the recommended way to run NVST for a fully automated experience. You can also use --agent ide to output skill prompts directly to the terminal, which you can then copy into web-based agents or IDE tools (Cursor, Antigravity, ChatGPT).

• Standalone skill invocation — Every NVST workflow skill (define-requirement, refine-requirement, create-prototype, audit-prototype, refactor-prototype, approve-prototype) can be invoked directly from any AI agent CLI that loads skills via npx skills add, without needing the nvst binary or an active NVST iteration. When invoked standalone, each skill self-detects the absence of NVST state and interactively asks the user for any missing context (e.g. iteration number, PRD file path). See docs/nvst-flow/QUICK_USE.md for details.

Installation

Prerequisites: Bun v1 or later must be installed.

You can install the toolkit via standalone binaries (recommended for quick use), from the local file system, or from a registry. If you only want the NVST workflow skills (without the nvst CLI), see Skills only below.

nvst init and skill selection

When nvst init runs in an interactive terminal, it invokes npx skills add with the bundled skills from this package (sources live under nvst-skills/ in the repository). The installer may prompt you to choose which skills to add.

Recommendation: select all bundled skills. That avoids “skill not found” errors for every CLI command and gives the agent the Impeccable toolkit referenced inside audit-prototype and refactor-prototype for UI/UX work.

If you prefer a minimal install, include at least the required set below. Everything else is optional for strict CLI use but still recommended for parity with the full audit/refactor experience.

	Skill directories (folder names under .agents/skills/)
Required	define-requirement, refine-requirement, create-project-context, refine-project-context, ideate, create-prototype, audit-prototype, refactor-prototype, approve-prototype, execute-automated-fix
Optional (Impeccable / design & polish; used when agents follow audit/refactor guidance)	adapt, animate, audit, bolder, clarify, colorize, critique, delight, distill, extract, frontend-design, harden, normalize, onboard, optimize, polish, quieter, teach-impeccable

See docs/nvst-flow/COMMANDS.md for how bundled skills relate to nvst sync skills (maintainer workflow).

Skills only

If you prefer using AI agent CLIs directly (Claude Code, Cursor, etc.) without installing the nvst binary, you can add just the skills to your agent:

npx skills add nerds-vibecoding-survivor-toolkit

This installs the following slash commands into your agent CLI: /define-requirement, /refine-requirement, /create-prototype, /audit-prototype, /refactor-prototype, /approve-prototype. Each skill auto-detects whether NVST is active and asks for any missing context interactively.

See Standalone Skill Invocation in QUICK_USE.md for details on how the fallback behavior works.

Standalone Binaries (Recommended)

The easiest way to get started is to download the pre-compiled binary for your platform from the GitHub Releases:

1. Download the binary for your OS (e.g., nvst-linux-x64).
2. Make it executable: chmod +x nvst-linux-x64.
3. Move it to your path: sudo mv nvst-linux-x64 /usr/local/bin/nvst.

From local file system

Install from a local directory or a packed tarball:

# From project root
bun add /path/to/nerds-vibecoding-survivor-toolkit

# Or from a packed .tgz (run `bun run package` first, then install the generated file)
bun add ./quinteroac-agents-coding-toolkit-<version>.tgz

Verify installation

After installation, the nvst command should be available.

If you installed the standalone binary:

nvst --version
nvst --help

If you installed via Bun (local or npm): Prefer bun nvst so Bun resolves the binary from the local package:

# Check that the command works
bun nvst --help

# Verify installed version matches the package
bun nvst --version

If nvst is not found: add your project’s node_modules/.bin to your PATH, or run it explicitly:

# Add to PATH for the current shell (adjust path if your project root differs)
export PATH="$PATH:$(pwd)/node_modules/.bin"
nvst --help

# Or run the binary directly (from the project that has the toolkit as a dependency)
./node_modules/.bin/nvst --help

Build standalone binary

Build a single platform binary from this repository:

bun run build:binary

Optional flags:

bun run build:binary --target bun-linux-x64 --outdir dist --name nvst

Build all release binaries (macOS, Linux, Windows x64):

bun run build:binaries

The produced executables are standalone artifacts built with bun build --compile. They are intended to run on target machines without Bun or Node.js installed.

Quick verification for Linux in a clean environment (no Bun/Node installed in the container):

docker run --rm -v "$PWD/dist:/dist" debian:stable-slim /dist/nvst-linux-x64 --help

Acknowledgements

This toolkit draws inspiration from other excellent projects in the specification-driven development space. Special thanks to the following libraries and projects for their contribution to the agentic coding ecosystem:

• Impeccable (skills licensed under Apache 2.0)
• Ralph Loop
• GSD
• spec-kit

References

• docs/nvst-flow/COMMANDS.md — Full CLI command reference.
• docs/nvst-flow/QUICK_USE.md — Quick start and common workflows.
• process_design.md — Full process specification.

License

This project is licensed under the MIT License - see the LICENSE file for details.