vibe-commander

English | 한국어

Unit-based vibe coding workflow automation — Generate command file sections from a single unit ID, reducing manual context collection from 10 minutes to 10 seconds.

vibe-commander automates the repetitive cycle of switching between work units: parsing plans, collecting dependencies, finding related commits, and assembling agent context — all driven by a single configuration file that adapts to any project structure.

Why vibe-commander?

When using AI agents (Cursor, Claude Code, Gemini CLI) with a unit-based development pipeline, every unit switch requires manual context gathering:

Before — Manual workflow per unit switch:

1. Check the roadmap for the next unit               (~1 min)
2. Open the plan and identify dependencies            (~2 min)
3. Locate dependent unit documents (plans, results)   (~3 min)
4. Search git history for related commits             (~2 min)
5. Write pairing question answers                     (~1 min)
6. Insert special request templates                   (~1 min)
7. Keep updating commit SHAs during work              (ongoing)
─────────────────────────────────────────
Total: ~10–15 minutes per switch × 3–5 switches/day

After — With vibe-commander:

vc set-unit U-042[Mvp]    # All context collected and assembled in ~10 seconds
vc update-commit           # Commit SHA auto-tracked from HEAD

One command parses the plan, resolves dependencies, collects related documents and commits, renders the command file section, and handles pairing questions — all driven by your project config.

Quick Start

Option 1: Run instantly with npx (no install)

npx vibe-commander init --from-existing
npx vibe-commander set-unit U-001[Mvp]

pnpm users: Use pnpm dlx vibe-commander instead of npx.

Option 2: Global install

npm install -g vibe-commander
# or: pnpm add -g vibe-commander
# or: yarn global add vibe-commander

vc init --from-existing
vc set-unit U-001[Mvp]

Option 3: Project devDependency

npm install -D vibe-commander
# or: pnpm add -D vibe-commander
# or: yarn add -D vibe-commander

npx vc init --from-existing
npx vc set-unit U-001[Mvp]

Important: Use the same package manager as your project. Mixing package managers (e.g., running npm install in a pnpm project) can cause dependency resolution errors.

First-time setup

# Scan existing project files to auto-generate config
vc init --from-existing

# Or create config interactively
vc init

# Validate the generated config
vc validate

This creates vibe-commander.config.json in your project root, tailored to your directory structure, unit ID patterns, and document layout.

Daily Workflow

Once set up, your daily cycle looks like this:

# 1. See what's ready to work on
vc list-units

# 2. Switch to a unit — plan is parsed, deps collected, command file updated
vc set-unit U-042[Mvp]

# 3. Work with your AI agent (Cursor, Claude Code, etc.)
#    The command file now has all the context the agent needs.

# 4. Track commits as you go
vc update-commit              # Latest HEAD
vc update-commit 3            # Last 3 commits
vc update-commit --mode append  # Add without replacing

# 5. Move to the next unit
vc set-unit U-043[Mvp]

CLI Reference

| Command | Description | |---------|-------------| | vc init | Initialize project config (interactive or --from-existing scan) | | vc set-unit <unitId> | Set current working unit — auto-generates command file section | | vc update-commit [sha\|N] | Update commit SHA (no arg = HEAD, number = recent N commits) | | vc list-units | List incomplete units with dependency status | | vc context <unitId> | Read-only unit context query (no file modifications) | | vc validate | Validate config file integrity (schema, paths, patterns) | | vc skill install | Install SKILL files for AI agents | | vc schema [subcommand] | Introspect CLI schema at runtime |

vc set-unit

The core command. Parses the unit plan, collects all dependency documents and commits, and updates the command file — in one step.

# Basic usage
vc set-unit U-042[Mvp]

# Preview changes without modifying files
vc set-unit U-042[Mvp] --dry-run

# Add custom special requests
vc set-unit U-042[Mvp] --request doc-update --request mcp-codrag

# JSON output for automation
vc set-unit U-042[Mvp] --json

vc update-commit

Track commits as you work, without manually copying SHAs.

# Auto-detect HEAD commit
vc update-commit

# Collect last 3 commits
vc update-commit 3

# Specific SHA
vc update-commit abc1234f

# Append instead of replace
vc update-commit --mode append

vc list-units

See what's ready to work on.

# Show all incomplete units
vc list-units

# Filter by phase
vc list-units --phase Mvp

# Machine-readable output
vc list-units --json

vc context

Read-only context query — useful for agents that need unit info without modifying the command file.

vc context U-042[Mvp] --json

vc schema

Runtime schema introspection for agents to discover CLI capabilities dynamically.

# JSON Schema for config file
vc schema config --json

# All available commands and their flags
vc schema commands --json

# Unit types and their ID patterns
vc schema types --json

# Save schema to file
vc schema config --json --output config-schema.json

vc validate

Four-stage config validation pipeline: schema check, path existence, regex validity, and pattern conflict detection.

vc validate
vc validate --json

SKILL Files for AI Agents

SKILL files teach AI agents how to use vibe-commander effectively. One command installs guides for all supported platforms:

# Install for all platforms (Cursor + Claude Code + Gemini)
vc skill install

# Platform-specific
vc skill install --cursor
vc skill install --claude
vc skill install --gemini

# Force overwrite existing files
vc skill install --force

After installation, agents automatically discover the SKILL guide at:

• Cursor: .cursor/skills/vibe-commander/SKILL.md
• Claude Code: .claude/skills/vibe-commander/SKILL.md
• Gemini: .gemini/skills/vibe-commander/SKILL.md

Agent-First Design

vibe-commander is built for AI agents as first-class consumers. Every design decision prioritizes agent usability.

AGENTS.md

The project includes an AGENTS.md file (also bundled in the npm package) that agents read at conversation start. It contains:

• Quick command reference
• Invariant rules (always --dry-run first, always --json, validate inputs)
• Safe workflow examples
• Error handling patterns

Structured Output

All commands support --json for machine-readable output following the ToolResult<T> structure:

{
  "success": true,
  "data": {
    "unitId": "U-042[Mvp]",
    "title": "U-042[Mvp]: Add authentication module",
    "depsFound": ["U-041[Mvp]"],
    "docsFound": [
      { "unitId": "U-041[Mvp]", "role": "result", "path": "docs/results/U-041[Mvp].md" }
    ],
    "commitsFound": ["a1b2c3d4"]
  }
}

Errors are also structured:

{
  "success": false,
  "error": {
    "code": "UNIT_TYPE_NOT_FOUND",
    "message": "No matching unit type for: U-999",
    "details": "Registered types: implement, refactor, checkpoint",
    "suggestions": ["U-099[Mvp]", "U-100[Mmp]"]
  }
}

Dry-Run Mode

Preview changes before applying them — critical for agent safety:

vc set-unit U-042[Mvp] --dry-run --json

Input Safety

The CLI defends against agent hallucinations by rejecting dangerous patterns:

• Path traversal: ../, ..\\
• Control characters: ASCII < 0x20
• URL encoding: %2e, %2F
• Query parameters: ?, #

Invalid unit IDs trigger fuzzy matching suggestions based on Levenshtein distance.

Pipe Mode

For automation and orchestrators, pipe JSON via stdin:

echo '{"unitId":"U-042[Mvp]"}' | vc set-unit --stdin --json

VS Code Integration

vibe-commander provides VS Code Tasks for running vc commands directly from the editor without switching to a terminal. This is an optional DX enhancement — all features remain fully accessible via the command line.

Quick Setup

Copy the tasks template to your project:

# From npm package
cp node_modules/vibe-commander/examples/vscode-tasks.json .vscode/tasks.json

If using npx instead of a global install, replace vc with npx vc in the task commands.

Available Tasks

Access all tasks via Ctrl+Shift+P → Tasks: Run Task, or Ctrl+Shift+B to see the build task group:

| Task | Command | Description | |------|---------|-------------| | vc: Set Unit | vc set-unit <unitId> | Switch to a unit (prompts for ID) | | vc: Set Unit (Dry Run) | vc set-unit <unitId> --dry-run | Preview changes without modifying files | | vc: Update Commit (HEAD) | vc update-commit | Track latest HEAD commit | | vc: Update Commit (N) | vc update-commit <N> | Track last N commits (prompts for count) | | vc: List Units | vc list-units | Show incomplete units | | vc: Validate | vc validate | Check config integrity | | vc: Context (JSON) | vc context <unitId> --json | Read-only context query |

Tasks that require a unit ID will prompt for input via VS Code's input dialog (${input:unitId}).

Recommended Keyboard Shortcuts

Tasks work without shortcuts via the Command Palette, but you can bind frequently used tasks for faster access. Add these to your keybindings.json (Ctrl+Shift+P → Preferences: Open Keyboard Shortcuts (JSON)):

[
  {
    "key": "ctrl+shift+u",
    "command": "workbench.action.tasks.runTask",
    "args": "vc: Set Unit"
  },
  {
    "key": "ctrl+shift+alt+u",
    "command": "workbench.action.tasks.runTask",
    "args": "vc: Set Unit (Dry Run)"
  },
  {
    "key": "ctrl+shift+k",
    "command": "workbench.action.tasks.runTask",
    "args": "vc: Update Commit (HEAD)"
  },
  {
    "key": "ctrl+shift+l",
    "command": "workbench.action.tasks.runTask",
    "args": "vc: List Units"
  }
]

Note: Keybindings are user-level settings and may conflict with other extensions. Adjust key combinations to your preference.

Configuration

vibe-commander adapts to any project through vibe-commander.config.json. The config defines your unit ID patterns, document paths, parsing rules, and command file structure.

Minimal Config

{
  "$schema": "https://vibe-commander/config-schema.json",
  "version": 1,
  "paths": {
    "commands": "docs/commands.md",
    "roadmap": "docs/roadmap.md",
    "docRoots": {
      "plan": "docs/plans",
      "result": "docs/results"
    }
  },
  "unitTypes": [
    {
      "key": "feature",
      "displayName": "Feature",
      "idPattern": "^FEAT-\\d+$",
      "planDir": "plan",
      "commandSection": "# Current Feature",
      "collectDeps": true,
      "headerTemplate": "### Feature: {{title}}\n- Plan: @{{planPath}}\n- Commit: -"
    }
  ]
}

Config Sections

| Section | Purpose | |---------|---------| | paths | Document directories, command file, roadmap location | | unitTypes | Unit type definitions with ID patterns, templates, and behavior | | docDiscovery | How to find documents for each role (plan, result, runbook) | | planParsing | How to extract title, dependencies, pairing questions from plans | | backlogParsing | How to parse the roadmap/backlog for list-units | | commitSearch | Git commit search strategy and filters | | commandSections | Command file section separators and marker settings | | defaultSpecialRequests | Default instructions appended to every unit | | specialRequestsByType | Type-specific additional instructions | | customRequests | Named request templates selectable with --request <key> |

Auto-Detection

For existing projects, vc init --from-existing scans your file tree to detect:

• Unit ID patterns (from filenames)
• Document directory structure
• Section headers in command files
• Roadmap format

Template Variables

Templates in headerTemplate and docDiscovery support these variables:

| Variable | Description | Example | |----------|-------------|---------| | {{unitId}} | Original unit ID | U-042[Mvp] | | {{shortId}} | Phase removed | U-042 | | {{bareId}} | Number only | 042 | | {{title}} | Full title (with ID) | U-042[Mvp]: Add auth module | | {{titleOnly}} | Title without ID | Add auth module | | {{planPath}} | Relative plan path | docs/plans/U-042[Mvp].md | | {{phase}} | Phase string | Mvp | | {{slug}} | Kebab-case | u-042-mvp |

Architecture

vibe-commander follows a 4-layer architecture with strict dependency direction:

Layer 4: Consumers    ← Humans, AI agents, orchestrators
Layer 3: Adapters     ← CLI, SKILL files, stdin/stdout pipe
Layer 2: Resolver     ← Config-based project structure resolution
Layer 1: Core         ← Pure functions (no side effects, no I/O)

• Core functions are pure: JSON in, JSON out. No fs, no child_process.
• Resolver absorbs project differences through config, not code.
• Adapters handle all I/O — file reads, git commands, user interaction.
• Single production dependency: Zod for runtime validation.

Building from Source

Prerequisites

• Node.js >= 24.0.0 (LTS) — Download
• npm >= 11 (included with Node.js 24)
• Git — Download
• Windows: Git Bash or WSL recommended for release scripts

Verify your environment:

node -v   # Expected: v24.x.x
npm -v    # Expected: 11.x.x

Build Steps

# Clone the repository
git clone https://github.com/viilab/vibe-commander.git
cd vibe-commander

# Install dependencies
npm install

# Build TypeScript → dist/
npm run build

The build produces the dist/ directory containing compiled JavaScript (.js) and TypeScript declaration (.d.ts) files.

Local Testing

# Register globally for local testing
npm link

# Verify the CLI works
vc --help
vc --version

# Unlink when done
npm unlink -g vibe-commander

Windows note: npm link may require administrator privileges. As an alternative, use npx tsx src/adapters/cli/index.ts -- --help during development.

Clean Build

# Remove previous build artifacts and rebuild
rm -rf dist
npm run build

Pre-PR Checklist

Before submitting a pull request, ensure the full quality gate passes:

npm run check

This runs typecheck → lint → format check → tests in sequence. All four stages must pass.

Package Contents

The npm package includes the following files and directories:

| Path | Description | |------|-------------| | dist/ | Compiled JavaScript and TypeScript declarations | | skills/ | SKILL files for AI agents (Cursor, Claude Code) | | schemas/ | JSON Schema for config validation and IDE autocompletion | | examples/ | Example configs (Tauri, Next.js, Python) and VS Code tasks template | | AGENTS.md | Agent quick reference (bundled in package) | | README.md | English documentation | | README.ko.md | Korean documentation | | LICENSE | MIT license |

To verify package contents locally:

npm pack --dry-run

Contributing

Development Setup

Follow the Building from Source prerequisites, then:

git clone https://github.com/viilab/vibe-commander.git
cd vibe-commander
npm install

Available Scripts

npm run dev           # Run with tsx (development)
npm run build         # TypeScript build
npm run test          # Run Vitest tests
npm run test:watch    # Vitest watch mode
npm run test:coverage # Test coverage report
npm run lint          # ESLint static analysis
npm run lint:fix      # ESLint auto-fix
npm run typecheck     # TypeScript type check
npm run format        # Prettier formatting
npm run format:check  # Prettier format check (no modifications)
npm run check         # Full quality gate (typecheck + lint + format + test)

Release Process

Releases use npm lifecycle hooks for a safe, automated pipeline:

# Dry run — verify everything passes without publishing
npm run release:dry

# Publish a patch release (0.2.0 → 0.2.1)
npm run release:patch

# Publish a minor release (0.2.0 → 0.3.0)
npm run release:minor

# Publish a major release (0.2.0 → 1.0.0)
npm run release:major

Each release command automatically:

1. Checks for uncommitted changes
2. Runs the full quality gate (typecheck + lint + format + test)
3. Bumps the version and creates a git tag
4. Builds the TypeScript output
5. Publishes to npm
6. Pushes the version commit and tag to git

Version Strategy follows Semantic Versioning:

| Change Type | Version Bump | Example | |-------------|-------------|---------| | Bug fixes, documentation | Patch | 0.2.0 → 0.2.1 | | New features (backward-compatible) | Minor | 0.2.0 → 0.3.0 | | Breaking changes | Major | 0.2.0 → 1.0.0 |

Pre-Release Checklist:

1. npm registry login verified: npm whoami
2. All quality gates pass: npm run check
3. Build succeeds: npm run build
4. README.md and README.ko.md are in sync
5. Package contents verified: npm pack --dry-run

npm Login — Required before the first publish or when your auth token has expired:

# Login (opens browser or prompts for credentials)
npm login

# Verify login
npm whoami

Recovering from a Failed Publish — If the release command succeeds at version bump and git push but fails at npm publish (e.g., 401/404 errors), the version is already tagged in git. Re-publish without bumping again:

npm publish --access public

Documentation Sync

This project maintains two README files: README.md (English) and README.ko.md (Korean). When updating documentation, please keep both versions in sync. The English version is the source of truth for npm package pages.

Project Principles

• Config-driven universality — project differences are absorbed by config, never hardcoded
• Pure function core — Layer 1 has no side effects (JSON in → JSON out)
• Graceful degradation — missing roadmap? set-unit still works. Missing runbook? Other docs still collected.
• Minimal dependencies — 1 production dep (Zod). Everything else uses Node.js built-ins.
• Agent as component — CLI, SKILL files, and stdin/stdout pipes serve humans, agents, and orchestrators alike.

License

MIT © viilab