@srinnov/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 (Claude, Cursor, Copilot, or the next one) can read them, continue where the last session left off, and keep the project moving.

The project owns the context, not the AI vendor.

Why it exists

AI coding sessions are stateless. Close the chat and the plan, decisions, and progress evaporate. VibeCoding fixes this by persisting 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.

Installation

No install required — run it directly with npx:

npx @srinnov/vibecoding init

Or install it as a dev dependency:

npm install --save-dev @srinnov/vibecoding

Requires Node.js 18+.

Usage

From the root of your project:

npx @srinnov/vibecoding init

This creates any of the five core files that don't already exist:

@srinnov/vibecoding
Project Initialization

✓ project.md
✓ projectPlan.md
✓ projectStatus.md
✓ projectTest.md
✓ projectContext.md

VibeCoding initialized with 5 new files.

init is safe to run repeatedly — existing files are preserved and reported as skipped, never overwritten:

⚠ project.md already exists — skipped
✓ projectPlan.md
...

Commands

| Command | Description | | ------------------- | ----------------------------------------------------------------- | | init | Create the five core files. --force, --only <a,b>, --agent-instructions. | | sync | Generate AI-agent instruction files. --force. | | status | Project dashboard: phase, tasks, tests, coverage. --json. | | check / doctor | Validate files and traceability. --strict, --json. | | trace [REQ-ID] | Requirement traceability matrix, or trace a single requirement. | | mcp | Run the MCP server (stdio) exposing the files as tools. | | help, -h | Show usage. | | -v, --version | Show the installed version. |

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

Make your AI agent read the files (sync)

The core files only help if your AI agent actually reads them. sync writes small adapter files that point every major agent at the VibeCoding workflow:

npx @srinnov/vibecoding sync

This creates AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules, GEMINI.md, and .github/copilot-instructions.md (existing files are skipped unless you pass --force). Commit them so your whole team's agents stay aligned. You can also do this during init with npx @srinnov/vibecoding init --agent-instructions.

Requirements & traceability

You don't have to write requirements formally. Paste them into project.md in your own words — a description of what you want and, optionally, the expected behavior. Your AI agent then converts them into structured requirements with stable IDs (like REQ-AUTH-001, with titles and acceptance criteria) in projectPlan.md. From there the AI references those IDs in projectTest.md test cases and in code comments (e.g. // impl: REQ-AUTH-001), and VibeCoding links it all together:

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:

ID              TEST  CODE  TITLE
REQ-AUTH-001     ✓     ✓    User Login
REQ-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/update the files as tools)

Instead of hoping an agent reads the files, an MCP-capable agent can query and update them through tools. Start the server:

npx @srinnov/vibecoding mcp

It speaks the Model Context Protocol over stdio and exposes: get_project_context, get_all_files, get_status, list_requirements, trace_requirement, update_status, add_test_case, and update_context.

You don't run the server yourself in day-to-day use — you register it once with your AI tool, and the tool launches it automatically each session. Pick your agent below.

Claude Code (VS Code extension or CLI)

Run this once in your project (the VS Code extension shares the same config as the claude CLI, so the integrated terminal works):

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

Everything after -- is the command Claude runs, so your --dir . flag is passed to VibeCoding, not to Claude. Add --scope project to write a shared .mcp.json your teammates get on clone. Reload the VS Code window, then verify with claude mcp list (look for ✔ Connected) or /mcp inside a session.

Alternatively, commit a .mcp.json at the project root:

{
  "mcpServers": {
    "vibecoding": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@srinnov/vibecoding", "mcp", "--dir", "."]
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "vibecoding": {
      "command": "npx",
      "args": ["-y", "@srinnov/vibecoding", "mcp", "--dir", "."]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json, then restart the app:

{
  "mcpServers": {
    "vibecoding": {
      "command": "npx",
      "args": ["-y", "@srinnov/vibecoding", "mcp", "--dir", "/absolute/path/to/project"]
    }
  }
}

Once registered, just talk to the agent (e.g. "what's the project status?") and it calls the tools itself. The MCP SDK is loaded only when the server runs — every other command stays dependency-light. If you don't set up MCP at all, sync still lets any agent read and update the files as text.

The five files

| File | Answers | Primary owner | | ------------------- | ------------------------ | -------------- | | project.md | What are we building? | Developer | | projectPlan.md | How will we build it? | AI + Developer | | projectStatus.md | Where are we? | AI + Developer | | projectTest.md | What needs to be tested? | AI + Developer | | projectContext.md | What should AI remember? | AI |

• project.md — 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 — where the AI turns your raw requirements into structured requirements (with IDs like REQ-AUTH-001 and acceptance criteria), plus the plan: features, tasks, architecture, and technical decisions.
• projectStatus.md — a short snapshot of overall status, what's done, what's in progress, and the next recommended task. A dashboard, not a diary.
• projectTest.md — the test plan: strategy and per-feature test cases with their status.
• projectContext.md — a concise, always-current briefing so an AI agent can get up to speed without rediscovering everything. Keep it short.

Example workflow

1. Run npx @srinnov/vibecoding init in your project.
2. Fill in your requirements in project.md.
3. Point your AI coding agent at the VibeCoding files and ask it to:
   • read project.md, projectContext.md, and projectPlan.md,
   • update projectPlan.md with a plan,
   • implement the work,
   • add/update test cases in projectTest.md,
   • update projectStatus.md and projectContext.md when done.
4. Next session (same or different AI tool), the agent reads the files and continues — no lost context.

Development

npm install       # install dev dependencies
npm run build     # compile src/ -> dist/
npm test          # run the test suite (vitest)
npm run dev       # run the CLI from source

To inspect exactly what would be published:

npm pack --dry-run

Project structure

src/
├── cli.ts              # argument parsing & command routing
├── constants.ts        # core file list, ID patterns, template dir, exit codes
├── commands/           # init, sync, status, check, trace, mcp
├── core/               # parsing & domain logic (transport-agnostic)
│   ├── markdown.ts     # section get/replace, checklist & table parsing
│   ├── project.ts      # readers: requirements, tests, traceability
│   ├── mutations.ts    # safe edits used by MCP write tools
│   ├── adapters.ts     # AI-agent instruction adapters
│   └── mcpTools.ts     # MCP tool definitions + runner
└── utils/
    ├── filesystem.ts   # safe file ops (never-overwrite, force+backup, walk)
    ├── projectRoot.ts  # resolves the target directory
    ├── args.ts         # tiny argument parser
    └── logger.ts       # dependency-free colored output
templates/              # the five Markdown templates (shipped with the package)
tests/                  # vitest suite

Roadmap

Shipped in v0.2:

• ✅ 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/tests drift from committed code)
• Config file for teams (custom files, ID formats, rules)
• Template/preset packs per stack

Contributing

Contributions are welcome. Please:

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

License

MIT