How It Works

Understanding the VirtualBoard feature specification workflow

Feature Status Workflow

Features move through three distinct states

📋

backlog

New features

→
⚙️

in-progress

Active work

→
✓

done

Completed

Features move through three distinct states, each with its own directory under .virtualboard/features/. The CLI enforces workflow transitions and validates that dependencies are satisfied before moving features to in-progress.

Getting Started

Four simple steps to manage your feature specifications

1

Initialize Workspace

Start by creating a .virtualboard/ directory structure in your repository:

vb init

This downloads the template archive and sets up the workspace with schema, directories, and example features.

To update an existing workspace to the latest template version:

vb init --update
2

Create Features

Scaffold new feature specs with consistent structure:

vb new "User Authentication" security auth

Each feature gets a unique ID, YAML frontmatter, and standard sections for documentation.

3

Validate & Move

Check for issues and move features through the workflow: 

vb validate all
vb move FEAT-001 in-progress --owner=alice

Validation ensures schema compliance, dependency resolution, and workflow consistency.

4

Generate Indexes

Create stakeholder-friendly views of all features:

vb index

Outputs Markdown, JSON, and HTML indexes sorted by status and priority.

Feature Lifecycle

Understanding each stage of the feature workflow

Backlog

New features start in the backlog directory. They include:

  • • Unique feature ID (FEAT-XXX)
  • • Title, labels, and metadata
  • • Overview and acceptance criteria sections
  • • Status set to backlog

In Progress

When work begins, features move to in-progress. Requirements:

  • • All dependencies must be in done status
  • • Owner must be assigned (can be set during move)
  • • No circular dependency chains

Done

Completed features are archived in done. They can serve as dependencies for other features and remain as documentation of delivered functionality.

Validation Rules

Ensuring quality and consistency across all features

📋

Schema Validation

All features must conform to the JSON schema in .virtualboard/schema.json. The validator checks:

  • • Required frontmatter fields
  • • Valid status values
  • • Proper date formats
  • • Allowed priority and complexity levels
🔄

Workflow Rules

Features must be in the correct directory for their status:

  • • File path must match status value
  • • Dependencies must exist and be valid
  • • No dependency cycles allowed
  • • Filename format: {id}-{slug}.md

Collaborative Workflows

Tools for team coordination and automation

Locking Features

Use vb lock to coordinate edits across team members: 

vb lock acquire FEAT-001
# Edit the feature...
vb lock release FEAT-001

Locks are TTL-based and can be checked or force-overridden when needed.

CI/CD Integration

The CLI's JSON output mode makes it perfect for automation: 

vb validate all --json | jq '.errors'
vb index --json

Combine with --dry-run to preview changes before applying them.