PackagesVibeCoding
Published on npm

@srinnov/vibecoding

VibeCoding

Structured, vendor-neutral project context for AI-assisted development

@srinnov/vibecoding bootstraps a project with five persistent Markdown files that hold your requirements, plan, status, tests, and AI context. These files live inside your repository and become the project's source of truth — so any AI coding agent can read them, continue where the last session left off, and keep the project moving.

$ npx @srinnov/vibecoding init
View on npmView sourceHow to use it
v0.3.0MITNode.js 18+No install required

5

Core files

8

CLI commands

6

Agent adapters

8

MCP tools

Why It Exists

The project owns the context, not the AI vendor

Without persistent context

AI coding sessions are stateless. Close the chat and the plan, decisions, and progress evaporate — so every new session starts by rediscovering the project from scratch.

With VibeCoding

VibeCoding persists project state in the project itself, in a simple format that is easy for both humans and AI agents to read and update. Switch tools freely — the context stays with the code.

Benefits

What you get from one command

A small CLI with a narrow job: keep the truth about your project next to the code, in a form both you and your agent can read.

Context Outlives The Chat

Requirements, plan, status, tests, and AI briefing live in your repo — not in a chat window that disappears when you close it.

Vendor Neutral By Design

The project owns the context, not the AI vendor. Move between Claude, Cursor, Copilot, or whatever ships next without losing a thing.

One Source Of Truth

Five clearly-scoped files, each answering one question, with a defined owner. No sprawling docs folder, no duplicated state.

Requirements You Don't Format

Paste requirements in your own words. Your AI agent converts them into structured requirements with stable IDs and acceptance criteria.

Full Traceability

Link every requirement to its tests and implementation, then print a coverage matrix to see exactly what is untested or unimplemented.

Safe To Re-Run

init never overwrites your work — existing files are reported as skipped. Passing --force creates .bak backups before it touches anything.

Agent Adapters In One Command

sync writes AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules, GEMINI.md, and copilot-instructions.md so your whole team's agents stay aligned.

MCP Server Built In

Register it once and MCP-capable agents query and update the files through real tools instead of hoping they read the right file.

The Flow

From blank repo to self-documenting project

You describe the work. The agent structures, implements, and records it. The next session starts where this one stopped.

  1. 01

    Initialize

    Run the init command in your project root. The five core files are created; anything that already exists is left untouched.

  2. 02

    Describe

    Write what you want to build in project.md — plain language, your own words. There is no formal requirement syntax to learn.

  3. 03

    Structure

    Your AI agent reads project.md and turns it into structured requirements with stable IDs like REQ-AUTH-001, plus a plan, in projectPlan.md.

  4. 04

    Build & Trace

    The agent implements the work, adds test cases to projectTest.md, and references requirement IDs in code comments — so trace can link it all together.

  5. 05

    Hand Off

    projectStatus.md and projectContext.md are updated when work completes. The next session — same tool or a different one — picks up with no lost context.

The Five Files

Each file answers exactly one question

Clear ownership is what keeps these files trustworthy. You own your requirements; the agent maintains the rest.

project.md
Developer

What are we building?

Your requirements in your own words. Paste what you want to build; structure and IDs are not your job. You own this file — the AI should not change it unless you ask.

projectPlan.md
AI + Developer

How will we build it?

Where the AI turns your raw requirements into structured requirements with IDs and acceptance criteria, plus the plan: features, tasks, architecture, and technical decisions.

projectStatus.md
AI + Developer

Where are we?

A short snapshot of overall status, what is done, what is in progress, and the next recommended task. A dashboard, not a diary.

projectTest.md
AI + Developer

What needs to be tested?

The test plan: strategy and per-feature test cases with their current status.

projectContext.md
AI

What should AI remember?

A concise, always-current briefing so an AI agent can get up to speed without rediscovering everything. Kept short by design.

How To Use

Up and running in one command

Requires Node.js 18+. No install step, no config file, no lock-in.

1. Initialize the project

Run it from the root of your project. Any of the five core files that do not already exist are created.

Prefer a pinned local copy? Add it as a dev dependency instead:

terminal
$ npm install --save-dev @srinnov/vibecoding
terminal
$ npx @srinnov/vibecoding init @srinnov/vibecodingProject Initialization ✓ project.md✓ projectPlan.md✓ projectStatus.md✓ projectTest.md✓ projectContext.md VibeCoding initialized with 5 new files.

2. Re-run it whenever you like

init is safe to run repeatedly. Existing files are preserved and reported as skipped — never overwritten.

If you do pass --force, a .bak backup is written first.
terminal
$ npx @srinnov/vibecoding init ⚠ project.md already exists — skipped✓ projectPlan.md...

3. Point your agents at the files

The core files only help if your AI agent actually reads them.syncwrites small adapter files that point every major agent at the VibeCoding workflow. Commit them so your whole team's agents stay aligned.

AGENTS.mdCLAUDE.md.cursorrules.windsurfrulesGEMINI.md.github/copilot-instructions.md

Existing files are skipped unless you pass --force. You can also do this during init with init --agent-instructions.

terminal
$ npx @srinnov/vibecoding sync AGENTS.mdCLAUDE.md.cursorrules.windsurfrulesGEMINI.md.github/copilot-instructions.md
Commands

The whole CLI, on one screen

Add --dir <path> to any command to target another project.

CommandDescriptionFlags
initCreate the five core files.--force, --only <a,b>, --agent-instructions
syncGenerate AI-agent instruction files.--force
statusProject dashboard: phase, tasks, tests, coverage.--json
check / doctorValidate files and traceability.--strict, --json
trace [REQ-ID]Requirement traceability matrix, or trace a single requirement.—
mcpRun the MCP server (stdio) exposing the files as tools.—
help, -hShow usage.—
-v, --versionShow the installed version.—
Traceability

Requirements linked to tests and code

You write requirements in plain words. The AI gives them stable IDs like REQ-AUTH-001, references those IDs in test cases and code comments such as // impl: REQ-AUTH-001, and VibeCoding links it all together.

terminal
$ npx @srinnov/vibecoding trace              # coverage matrix for all requirements$ npx @srinnov/vibecoding trace REQ-AUTH-001  # tests/code for one requirement$ npx @srinnov/vibecoding status             # high-level progress + coverage counts$ npx @srinnov/vibecoding check              # warns about untested/unimplemented reqs

Example matrix

trace output
ID              TEST  CODE  TITLEREQ-AUTH-001     ✓     ✓    User LoginREQ-AUTH-002     ✗     ✗    Logout

Requirement IDs are read from projectPlan.md, where the AI structures them. IDs defined in project.md are still recognized for backward compatibility.

MCP Server

Let agents read and update the files as tools

You don't run the server yourself day to day — you register it once and your AI tool launches it automatically each session. Then just ask, and the agent calls the tools itself.

Run this once in your project. The VS Code extension shares the same config as the claude CLI, so the integrated terminal works too.

terminal
$ claude mcp add vibecoding -- npx -y @srinnov/vibecoding mcp --dir .

Everything after -- is the command Claude runs, so --dir . is passed to VibeCoding, not to Claude. Add --scope project to write a shared .mcp.json your teammates get on clone. Reload the window, then verify with claude mcp list.

Exposed tools

Speaks the Model Context Protocol over stdio.

  • get_project_context
  • get_all_files
  • get_status
  • list_requirements
  • trace_requirement
  • update_status
  • add_test_case
  • update_context

The MCP SDK is loaded only when the server runs — every other command stays dependency-light.

Roadmap

Shipped, and what comes next

Shipped

Available today

  • Requirement IDs and requirement ↔ code ↔ test traceability (trace)
  • AI-agent instruction adapters (sync, --agent-instructions)
  • --force overwrite with .bak backups, and --only
  • Status dashboard and validation (status, check)
  • MCP server (mcp)

Future directions

Not yet implemented

  • Git integration — warn when status and tests drift from committed code
  • Config file for teams — custom files, ID formats, and rules
  • Template and preset packs per stack

Open source, contributions welcome

VibeCoding is MIT-licensed and developed in the open. If it is missing something you need, the fastest path is an issue describing the change.

Browse the repoOpen an issue

Contribution guidelines

  1. 1Open an issue describing the change.
  2. 2Keep runtime dependencies minimal and the MVP scope tight.
  3. 3Add tests for new behavior and ensure npm run build and npm test pass.
FAQ

Frequently asked questions

Still have questions? Contact our team.

Any agent that can read Markdown, which is all of them. The sync command ships ready-made adapter files for Claude Code, Claude Desktop, Cursor, Windsurf, Gemini, and GitHub Copilot, and the MCP server works with any MCP-capable client.

No. Paste requirements into project.md in your own words — a description of what you want and, optionally, the expected behavior. Your AI agent converts them into structured requirements with stable IDs and acceptance criteria in projectPlan.md.

Never. init is safe to run repeatedly — existing files are preserved and reported as skipped. If you explicitly pass --force, VibeCoding writes a .bak backup before overwriting.

No install required — run it directly with npx. You can also add it as a dev dependency with npm install --save-dev @srinnov/vibecoding. It requires Node.js 18 or newer.

No, it is optional. You register it once with your AI tool and the tool launches it automatically each session. If you skip MCP entirely, sync still lets any agent read and update the files as plain text. The MCP SDK is only loaded when the server actually runs — every other command stays dependency-light.

Requirement IDs are read from projectPlan.md, where the AI structures them. IDs defined in project.md are still recognized for backward compatibility.

Yes. Add --dir <path> to any command to operate on a project other than the current directory.

MIT. It is free to use in personal and commercial projects, and contributions are welcome.

Resources

npm registrySource on GitHubIssuesMIT licenceSupport

Stop losing context between sessions

One command, five files, and your project remembers itself. Free and open source under the MIT licence.

$ npx @srinnov/vibecoding init
View on npmGet support
Browse all packages