Feature Specs

Standardized feature specifications for AI agent collaboration and software development

Specification System

Built for parallel development

A structured approach for humans and AI agents to collaborate on features

Markdown-First

All specs live in Markdown with YAML frontmatter. Easy to diff, parse, and index for both humans and AI agents.

Parallel Development

Multiple agents work on different features simultaneously. Ownership claims prevent conflicts.

Automation Ready

Simple rules that are trivially validated by CI and followed by agents to enable seamless automation.

3 Templates

Templates included

Click to expand and see the full structure of each template

Feature Spec

13 sections

Canonical template for feature documentation with YAML frontmatter and structured body

▶

Template file

templates/feature.md

Created by

vb new "Title" label1 label2

Frontmatter fields

id Unique identifier (FTR-XXXX pattern, auto-assigned by vb new)
title Human-readable feature name
status Workflow state: backlog, in-progress, blocked, review, done
owner Agent or person currently responsible (single owner at a time)
priority P0 (critical) through P3 (low)
complexity T-shirt sizing: XS, S, M, L, XL
labels Kebab-case tags for filtering and agent role detection
dependencies List of FTR-XXXX IDs that must be done first
epic Parent epic reference (EP-XXXX)
risk_notes Free-text risk or concern flags

Body sections

Summary One-paragraph overview of the problem and the proposed change
Problem Statement Who is impacted, what pain exists, why now
Goals & Non-Goals Explicit scope boundaries to prevent scope creep
User Stories As a <role>, I want <capability> so that <benefit>
Requirements Functional and non-functional (performance, reliability, security, a11y, i18n)
Acceptance Criteria Testable checkbox list that defines "done" for this feature
UI/UX Notes Wireframes, component changes, empty states, responsive considerations
Data & API Data model diffs, API endpoints (request/response), migration plans
Rollout & Migration Feature flags, phased rollout plan, telemetry, rollback strategy
Monitoring & Metrics KPIs, dashboards, alerts to instrument for this feature
Security & Compliance Threats, mitigations, PII handling, audit logging requirements
Implementation Notes Libraries, patterns, risks, tech debt considerations
Open Questions Unresolved decisions or research spikes blocking implementation

PR Template

7 sections

Structured pull request checklist ensuring consistent review standards

▶

Template file

templates/pr-template.md

Used by

/work-on --create-pr

Sections

Overview Brief description of changes made in this PR
Feature Spec Checklist: link to spec, spec is in review status, all acceptance criteria implemented
Acceptance Criteria Checkbox list mirroring the feature spec's criteria for sign-off
Risk Assessment Low / Medium / High impact classification with breaking-change notes
Rollback Plan Feature flag toggle, DB reversibility, data loss assessment
Testing Unit, integration, manual, and performance testing checklists
Checklist Code conventions, docs updated, no warnings, a11y, security review

Rules Config

6 blocks

Machine-readable YAML defining agent behavior, validation, and state transitions

▶

Template file

templates/rules.yml

Read by

Agents at startup via RULES.md reference

Configuration blocks

agent Max concurrent features (3), conflict resolution strategy, error retry attempts (2), lock TTL (60 min)
validation Frontmatter schema path, circular dependency checks, updated-date enforcement, max label count (10)
naming ID pattern (FTR-\d{4}), filename pattern, max description words (6)
transitions Allowed: backlog→in-progress, in-progress→blocked/review, blocked→in-progress, review→in-progress/done. Forbidden: done→any
dependencies Circular check enabled, require done before in-progress, max depth (10)
errors Templated error messages for ownership conflicts, circular deps, invalid transitions, missing dependencies

CLI Integration

Feature operations via vb

All feature operations run through the required CLI

Bootstrap Check

Run once at the start of any task that touches feature specs: 

# Install if missing, upgrade if outdated
./scripts/install-vb-cli.sh --ensure-latest
vb version

Non-interactive: installs when missing, upgrades when outdated, exits cleanly when current.

Core Commands

Create, move, validate, and index features: 

vb new "User Auth" auth frontend
vb move FTR-0001 in-progress --owner alice
vb validate
vb index

vb move updates frontmatter and relocates the file in one step.

See the full CLI command reference

Security · v0.8.1

Security & Hardening

Supply-chain integrity, audit logging, operational locking, and agent sandboxing

SHA-256 Checksum Verification

The install-vb-cli.sh installer now fetches checksums.txt from the release and verifies the downloaded binary before installation. Prevents supply-chain tampering.

Version Pinning

The .vb-version file pins the CLI to a specific release tag. The installer reads it instead of always fetching latest, ensuring reproducible builds.

Explicit Sudo with --allow-sudo

Silent sudo escalation removed from the installer. The --allow-sudo flag must be passed explicitly to permit elevated privileges during installation.

Untrusted-Content Delimiters

Feature spec bodies are wrapped in <untrusted-content> tags. Agents treat body text as data, not instructions, preventing prompt injection through spec content.

Gitleaks Pre-Commit

Secret scanning via gitleaks added to pre-commit hooks. Prevents accidental credential leaks before they reach the repository.

Worktree Path Hardening

Default worktree path changed from /tmp to ~/.local/state/virtualboard/worktrees. Prevents cross-project collisions and world-readable temp exposure.

Append-Only Audit Log

Every feature operation (create, move, delete, update) is logged to .virtualboard/audit.jsonl with a SHA-256 hash chain for tamper evidence. Thread-safe and compliance-ready.

Operational Locking

vb new and vb move now use atomic file-based locking to prevent duplicate ID allocation and concurrent-move race conditions. 1-minute TTL for automatic crash recovery.

Validation Rules

Ensuring quality and consistency across features and system specs

Schema Validation

Features and specs validate against JSON Schema definitions:

  • Required frontmatter fields (id, title, status, created, updated)
  • Valid status values and date formats
  • Allowed priority (P0-P3) and complexity (XS-XL) levels
  • Label format enforcement (kebab-case)
  • System spec validation (spec_type, status, applicability)

Workflow Rules

Features must be in the correct directory for their status:

  • File path must match frontmatter status value
  • Dependencies must exist and be in done status
  • No circular dependency chains allowed
  • Filename format: {id}-{slug}.md
# Validate everything (features + specs)
vb validate

# Validate only features or only specs
vb validate --only-features
vb validate --only-specs

# Validate a specific spec by filename
vb validate tech-stack.md

# Auto-fix what can be fixed
vb validate --fix