Syntax
vectra-guard roadmap <subcommand> [options]
vg roadmap <subcommand> [options]
Description
Manage a development roadmap with tracked items, status updates, and session-linked logs. Useful for tracking feature development, technical debt, and project milestones.
Subcommands
roadmap add
Add a new roadmap item.
vg roadmap add --title <text> [--summary <text>] [--status <state>] [--tags <list>]
Title of the roadmap item
Detailed summary or description of the item
Initial status: planned, in-progress, completed, blocked, cancelled
Comma-separated tags for categorization (e.g., “feature,security,backend”)
roadmap list
List all roadmap items.
vg roadmap list [--status <state>]
Filter by status (e.g., in-progress, planned)
roadmap show
Show detailed information about a roadmap item.
vg roadmap show <item-id>
item-id: Unique identifier of the roadmap item
roadmap status
Update the status of a roadmap item.
vg roadmap status <item-id> <new-status>
item-id: Unique identifier of the roadmap itemnew-status: New status value (planned, in-progress, completed, blocked, cancelled)
roadmap log
Add a log entry to a roadmap item.
vg roadmap log <item-id> --note <text> [--session <id>] [--source <name>]
item-id: Unique identifier of the roadmap item
Log note or update message
Reference a session ID to link this log entry to session activity
Source of the log entry (e.g., manual, agent, ci)
Examples
Add a new feature
vg roadmap add \
--title "Add OAuth authentication" \
--summary "Implement OAuth 2.0 for GitHub and Google login" \
--status planned \
--tags "feature,auth,security"
# Roadmap item created: rm-abc123
List all items
vg roadmap list
# Output (JSON format):
# {
# "id": "rm-abc123",
# "title": "Add OAuth authentication",
# "status": "planned",
# "summary": "Implement OAuth 2.0 for GitHub and Google login",
# "tags": ["feature", "auth", "security"],
# "updated": "2026-03-03"
# }
Filter by status
vg roadmap list --status in-progress
# Shows only items currently in progress
Show item details
vg roadmap show rm-abc123
# {
# "id": "rm-abc123",
# "title": "Add OAuth authentication",
# "status": "in-progress",
# "summary": "Implement OAuth 2.0 for GitHub and Google login",
# "tags": ["feature", "auth", "security"],
# "created": "2026-03-01 10:00:00",
# "updated": "2026-03-03 14:30:00",
# "logs": [
# {
# "time": "2026-03-03 14:30:00",
# "note": "OAuth flow implemented for GitHub",
# "session": "session-xyz789",
# "source": "manual"
# }
# ]
# }
Update status
vg roadmap status rm-abc123 in-progress
# Status updated: planned → in-progress
vg roadmap status rm-abc123 completed
# Status updated: in-progress → completed
Add progress logs
vg roadmap log rm-abc123 \
--note "Completed OAuth integration for GitHub" \
--session $VECTRAGUARD_SESSION_ID \
--source manual
vg roadmap log rm-abc123 \
--note "Added tests for OAuth flows" \
--session $VECTRAGUARD_SESSION_ID
Track during development session
# Start session
SESSION=$(vg session start --agent "cursor-ai")
export VECTRAGUARD_SESSION_ID=$SESSION
# Create roadmap item
ITEM=$(vg roadmap add --title "Fix auth bug" --status in-progress | jq -r '.id')
# Do work...
vg exec -- npm run test
vg exec -- git commit -m "fix: auth validation"
# Log progress
vg roadmap log $ITEM \
--note "Fixed auth validation bug" \
--session $SESSION
# Mark complete
vg roadmap status $ITEM completed
Track technical debt
vg roadmap add \
--title "Refactor authentication module" \
--summary "Current auth code needs cleanup and better error handling" \
--status planned \
--tags "tech-debt,refactor,auth"
Manage blocked items
vg roadmap status rm-def456 blocked
vg roadmap log rm-def456 \
--note "Blocked waiting for API key from vendor"
Storage
Roadmap data is stored in:
.vectra-guard/roadmap.json
Use Cases
- Track feature development progress
- Log technical debt items
- Link code changes to roadmap items via sessions
- Review project milestones
- Generate progress reports
- session - Track execution sessions (can be linked to roadmap)
- audit - Audit session activity