How It Works

Understanding the VirtualBoard feature specification workflow

Feature Status Workflow

backlog → in-progress → done

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

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

This interactively shows changes and prompts for confirmation before applying updates.

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

Backlog

New features start in the backlog directory. They include:

In Progress

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

Done

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

Validation Rules

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

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.