How It Works

Understanding the VirtualBoard feature specification workflow

Feature Status

Workflow

Features move through five distinct states

backlog New features in-progress Active work review QA / code review done Completed blocked Stalled work changes requested backlog → in-progress → review → done | in-progress ↔ blocked | review → in-progress

Each state maps to a directory under .virtualboard/features/. The CLI enforces transitions — dependencies must be satisfied before in-progress, work can be paused via blocked, and every feature passes through review before reaching done.

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

Downloads the template archive and sets up the workspace. Use vb init --update to update an existing workspace.

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
vb move FEAT-001 review

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

Transitions to: in-progress

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

Transitions to: blocked, review

Blocked

Features that cannot proceed due to unresolved dependencies, external blockers, or other issues move to blocked. This is a temporary holding state — once the blocker is resolved, the feature transitions back to in-progress.

Transitions to: in-progress

Review

When implementation is complete, features move to review for QA, code review, or stakeholder sign-off. If changes are requested, the feature moves back to in-progress. Once approved, it transitions to done.

Transitions to: in-progress, done

Done

Completed features are archived in done. This is a terminal state — no further transitions are allowed. Done features can serve as dependencies for other features and remain as documentation of delivered functionality.

Terminal state (no outgoing transitions)

Validation Rules

Ensuring quality and consistency across all features

Schema Validation

All features must conform to the JSON schema. 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 with atomic creation to prevent race conditions. They 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.