virtualboard

VirtualBoard Feature Spec Workflow

This directory contains the complete implementation of the Feature Spec Workflow system for managing features with multiple AI agents.

Claude Code Plugin

VirtualBoard is now available as a Claude Code plugin! Install it directly in Claude Code:

claude plugin marketplace add virtualboard/template-base
claude plugin install virtualboard

Or use the plugin marketplace. See .claude-plugin/README.md for full plugin documentation.

/work-on Skill

The plugin includes a /work-on skill for working on features in isolated git worktrees:

# Basic usage - work on a feature interactively
/work-on FTR-0042

# Autonomous mode (no clarifying questions)
/work-on FTR-0042 --autonomous

# Custom worktree location
/work-on FTR-0042 --worktree-path ~/worktrees

# Branch from develop instead of main
/work-on FTR-0042 --base-branch develop

# Create PR after pushing
/work-on FTR-0042 --create-pr

The skill:

• Creates a git worktree with branch feature/FTR-XXXX/feature-slug
• Detects and resumes existing work on the branch
• Spawns a new Claude Code session in the worktree
• Commits with footer: FTR-XXXX implemented using the @virtualboard /work-on skill
• Pushes the branch (and optionally creates a PR)

See skills/work-on/config.md for configuration options.

Cursor IDE Integration

VirtualBoard includes a .cursor/rules/virtualboard.mdc file that enables automatic integration with Cursor IDE. This rule tells Cursor to use the VirtualBoard workflow and agent system.

Option 1: Project-Level Installation (Recommended)

Copy the .cursor folder to your project root to enable VirtualBoard for that specific project:

# If you're using this template
cp -r .cursor /path/to/your/project/

# Or if you're cloning this repository
git clone https://github.com/virtualboard/template-base.git
cp -r template-base/.cursor /path/to/your/project/

Option 2: Global Installation

To enable VirtualBoard across all your projects in Cursor, add the rule globally:

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to "Cursor Settings" → "Rules for AI"
3. Click "Edit in settings.json"
4. Add the VirtualBoard rule:

{
  "cursor.rules": [
    {
      "description": "Virtualboard Task Tracker",
      "alwaysApply": true,
      "content": "You will use the Virtualboard strategy defined on @.virtualboard/AGENTS.md to keep track of tasks and progress\n\nWorkspace for the Virtualboard is the @.virtualboard/features folder"
    }
  ]
}

Note: Project-level rules (.cursor/rules/) take precedence over global rules. If you have both, the project-level rule will be used.

OpenCode Integration

VirtualBoard agents can be easily integrated into OpenCode, an open source AI coding tool.

To enable VirtualBoard agents in OpenCode:

1. Copy agent files to OpenCode directory:

   mkdir -p .opencode/agent && cp -Rf .virtualboard/agents .opencode/agent
   

2. Reload OpenCode: Restart your OpenCode session to load the agents.

3. Use agents: Once reloaded, the VirtualBoard agents (PM, Architect, Frontend Dev, Backend Dev, QA, etc.) will be available in OpenCode.

What gets copied:

• All agent role definitions (agents/*.md)
• Agent command system (prompts/agents/)
• Shared rules of engagement (agents/RULES.md)

Benefits:

• Native agent integration
• Quick access to specialized agent commands
• Consistent agent behavior
• No additional configuration needed

Implementation

All workflow operations run through the vb CLI — a single static binary with no runtime dependencies (no Node.js, npm, or Python). This approach provides:

• Zero runtime dependencies: A single binary for macOS/Linux on amd64/arm64
• Universal compatibility: Works on any Unix-like system
• Consistent behavior: One canonical implementation of validation, moves, indexing, and locks
• CI/CD friendly: Install once, then invoke vb commands directly

CLI Tool Requirement: The vb CLI is required. Agents and CI must run ./scripts/install-vb-cli.sh --ensure-latest before any vb command — that single call installs vb if missing, upgrades it via vb upgrade (with sudo vb upgrade fallback) if outdated, and is a no-op if already on the latest release. There are no shell-script fallbacks for feature operations.

System Specification Templates

Beyond feature files, the template ships with a /templates/specs catalog of reusable system blueprints. Copy any Markdown file to your project's /specs directory to document foundational decisions before (or alongside) feature work: