Features & Work Items

VibeFlow organizes work in a hierarchy: Projects → Features → Todos, with Issues as standalone items at the project level.

Features

Features represent major areas of work within a project — like "User Authentication", "Payment Integration", or "Dashboard Analytics".

Creating a Feature

1. Open a project
2. Click + New Feature
3. Provide:
   • Name — Descriptive name (e.g., "Login & Signup")
   • Description — What the feature encompasses
   • Priority — high, medium, or low

Feature Status

Features follow the standard workflow:

in_review → planning → ready_to_implement → architecture_review_complete → implementing → done

When all todos within a feature are done, the feature automatically transitions to done.

Todos

Todos are specific implementation tasks within a feature. They are the primary unit of work that agents pick up and implement.

Creating a Todo

1. Open a feature
2. Click + New Todo
3. Provide:
   • Title — Clear, actionable description (e.g., "Add email validation to signup form")
   • Description — Detailed requirements, acceptance criteria
   • Priority — high, medium, or low
   • Target Branch — Git branch for this work (defaults to project default)
   • Assignee (optional) — Assign to a specific org member

Todo Lifecycle

1. Created (in_review) — Todo is defined and ready for review
2. Reviewed (planning) — A persona (PM or architect) plans the approach
3. Ready (ready_to_implement) — Available for an agent to pick up
4. Architecture Reviewed (architecture_review_complete) — Architect has approved the approach
5. In Progress (implementing) — An agent has claimed and is working on it
6. Done (done) — Code committed, tests passing, work complete
7. Security Reviewed — Security lead has verified no vulnerabilities
8. QA Verified — QA lead has tested and approved

Git Tracking

When a todo is marked done, the following git metadata is recorded:

• Commit hash
• Author name and email
• Lines added and deleted

This provides full traceability from work item to code change.

Issues

Issues are standalone work items at the project level — typically bugs, fixes, or cross-cutting changes that don't fit under a single feature.

Creating an Issue

1. Open a project
2. Click + New Issue
3. Provide:
   • Title — Clear description of the bug or task
   • Description — Steps to reproduce, expected vs actual behavior
   • Priority — high, medium, or low
   • Target Branch — Git branch
   • Feature (optional) — Link to a related feature for context
   • Assignee (optional) — Assign to a specific org member

Issues vs Todos

Priority Levels

Agents process work items in priority order: high → medium → low. Issues at the same priority level are processed before todos.

Status Workflow

All work items (todos and issues) follow this status flow:

in_review → planning → ready_to_implement → architecture_review_complete → implementing → done

After done, items enter the review pipeline:

done → Security Review → QA Verification → Fully Complete

The review pipeline is tracked by two boolean fields on every work item:

• security_reviewed — set to true after the Security Lead persona signs off (or rejects + re-fixes are landed)
• qa_verified — set to true after the QA Lead persona signs off

Both default to false when a fresh work item ships from implementing → done. The Security Lead persona's polling loop sees done items where security_reviewed=false (with a committed git hash); the QA Lead persona's polling loop sees done items where security_reviewed=true AND qa_verified=false. This naturally serializes the two reviews — security first, then QA — without either reviewer needing to coordinate manually.

A reviewer rejection re-opens the item: status flips back to planning (or implementing) for the original implementer to address the feedback, then the cycle repeats.

Status Descriptions

Jira Integration on Work Items

When a todo or issue was imported from Jira, it displays additional information:

• Jira Sync Badge — Clickable badge showing the Jira key (e.g., PROJ-123) with link to the original ticket
• Jira Detail Section — Collapsible panel on the detail view showing Jira issue type, status, epic, sync status, and retry controls
• Sprint Info — If imported from a Jira sprint, the sprint name and link are displayed; a Sprint column appears in the todos/issues table with a sprint filter
• Sync Status — Real-time indicator of whether status changes have been synced back to Jira

For more details, see Integrations.

ClickUp Integration on Work Items

When a todo or issue is imported from ClickUp or pushed to ClickUp, it displays linked-task information:

• ClickUp Sync Badge — Clickable badge linking to the ClickUp task
• ClickUp Detail Section — Collapsible panel showing task ID, ClickUp status, push direction, sync status, and sync errors
• Direction — Shows whether the item was imported from ClickUp or pushed from VibeFlow
• Sync Status — Real-time indicator for linked, syncing, completed, failed, or dead_letter

For more details, see Integrations.

Execution Logs

Every work item has an execution log — a running record of what the agent did:

• Header — What item this is, priority, associated docs
• Progress — What files were analyzed, modified, tested
• Footer — Final status, commit hash, files changed

Execution logs are append-only and persist across sessions, providing a complete audit trail.

Claiming and Ownership

When an agent picks up a work item:

1. It acquires a poll lock (prevents race conditions)
2. Claims the item with a compare-and-swap operation
3. Records its session ID and persona on the item
4. Releases the poll lock

Only one agent can work on an item at a time. If a claim expires (agent disconnects), the item becomes available again after 30 minutes.

Tags

Tags provide a flexible labeling system for organizing and filtering work items across all entity types (features, todos, issues).

Tag Structure

Tags follow a key:value model:

• Tag Keys — Defined at the org level (e.g., "Environment", "Team", "Module")
• Tag Values — Values within a key (e.g., "production", "staging", "development")
• Colors — Each tag key has an assigned color for visual identification

Applying Tags

Tags can be applied individually or in bulk:

• Single item — Open a todo, issue, or feature and add tags from the detail view
• Bulk tag — Select multiple items via checkboxes in the table, then click Tag to apply a tag to all selected items at once

Filtering by Tags

Every table (Features, Todos, Issues) includes a Tag filter pill in the toolbar:

1. Click the Tag filter pill
2. Select a tag key
3. Select a tag value
4. The table filters to show only items with that tag

Active tag filters display as removable badges below the filter toolbar.

Managing Tags

Org admins can manage tag keys and values in Settings → Tag Management:

• Create new tag keys with custom colors
• Add/edit/delete tag values within each key
• Tags are org-wide — available across all projects

Deep Links

Every work item in VibeFlow has a shareable URL that navigates directly to it:

/ai/vibeflow?project={projectId}&todo={todoId}
/ai/vibeflow?project={projectId}&issue={issueId}
/ai/vibeflow?project={projectId}&feature={featureId}

Deep links are used in:

• Slack notification messages ("Open in VibeFlow" link)
• Jira sync comments
• Browser bookmarks and shared links

Table Interface

Features, Todos, and Issues are displayed in data tables with consistent UX:

• Resizable columns — Drag column borders to resize; widths persist in localStorage
• Search — Full-text search across item titles
• Filter pills — Status, Tag, Feature, Branch, and Sprint filters
• Sort — Click column headers to sort
• Pagination — Pages of 10 items with page count display
• Summary strip — Color-coded status counts (Done, Implementing, Planning, In Review) above the table
• Checkbox selection — Select multiple items for bulk tag application
• Tag chips — Inline tag badges on each row (max 3 visible, +N overflow)