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

Create a .virtualboard/ directory structure:

vb init

Downloads the template archive. 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.

3

Validate and Move

Check for issues and progress features through the workflow: 

vb validate
vb move FTR-0001 in-progress --owner alice
vb move FTR-0001 review
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 (FTR-XXXX)
  • 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. This is a temporary state — once the blocker resolves, the feature transitions back to in-progress.

Transitions to: in-progress

Review

Implementation complete, awaiting QA, code review, or stakeholder sign-off. If changes are requested, the feature returns to in-progress. Once approved, it transitions to done.

Transitions to: in-progress, done

Done

Terminal state. No further transitions allowed. Done features serve as dependencies for other features and remain as documentation of delivered work.

Terminal state (no outgoing transitions)

Claude Code Skill

/work-on Skill

Work on features in isolated git worktrees

Usage

/work-on FTR-0042
/work-on FTR-0042 --autonomous
/work-on FTR-0042 --create-pr
/work-on FTR-0042 --cleanup

Creates branch feature/FTR-XXXX/slug, detects existing work, and manages the full implementation cycle.

Configuration

Environment variables:

  • VIRTUALBOARD_WORKTREE_PATH — Worktree location (default: ~/.local/state/virtualboard/worktrees)
  • VIRTUALBOARD_BASE_BRANCH — Base branch
  • VIRTUALBOARD_POST_PUSH — Post-push action
  • VIRTUALBOARD_SESSION_MODE — Session mode
Worktree path hardened: Default changed from /tmp to ~/.local/state/virtualboard/worktrees to prevent cross-project collisions and avoid world-readable temp directories.