git clone https://github.com/HuntsDesk/ve-vibe-board.git
cd ve-vibe-board
npm install
npm run build

# From the ve-vibe-board repo root (contains firebase.json + firestore.indexes.json)
firebase use YOUR_PROJECT_ID
firebase deploy --only firestore:indexes

gcloud firestore indexes composite create \
  --project=YOUR_PROJECT_ID \
  --collection-group=sessions \
  --field-config field-path=project_id,order=ascending \
  --field-config field-path=status,order=ascending \
  --field-config field-path=ended_at,order=descending

gcloud firestore indexes composite create \
  --project=YOUR_PROJECT_ID \
  --collection-group=tasks \
  --field-config field-path=project_id,order=ascending \
  --field-config field-path=status,order=ascending

gcloud firestore indexes composite create \
  --project=YOUR_PROJECT_ID \
  --collection-group=tasks \
  --field-config field-path=project_id,order=ascending \
  --field-config field-path=assigned_agent,order=ascending \
  --field-config field-path=status,order=ascending

gcloud firestore indexes composite create \
  --project=YOUR_PROJECT_ID \
  --collection-group=projects \
  --field-config field-path=status,order=ascending \
  --field-config field-path=updated_at,order=descending

gcloud firestore indexes composite create \
  --project=YOUR_PROJECT_ID \
  --collection-group=activity_log \
  --field-config field-path=task_id,order=ascending \
  --field-config field-path=created_at,order=descending

{
  "mcpServers": {
    "vibe-board": {
      "command": "node",
      "args": ["/absolute/path/to/ve-vibe-board/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/your-key.json"
      }
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__vibe-board__board_get_projects",
      "mcp__vibe-board__board_create_project",
      "mcp__vibe-board__board_update_project",
      "mcp__vibe-board__board_get_tasks",
      "mcp__vibe-board__board_get_task",
      "mcp__vibe-board__board_create_task",
      "mcp__vibe-board__board_update_task",
      "mcp__vibe-board__board_bulk_update_tasks",
      "mcp__vibe-board__board_delete_task",
      "mcp__vibe-board__board_create_session",
      "mcp__vibe-board__board_end_session",
      "mcp__vibe-board__board_get_handoff",
      "mcp__vibe-board__board_log_activity",
      "mcp__vibe-board__board_get_activity"
    ]
  },
  "enabledMcpjsonServers": ["vibe-board"]
}

## Vibe Board

Persistent task tracking across sessions via Firebase Firestore MCP tools (`board_*`).
**Mandatory for every substantive session** (any session where you read, write, plan, debug, or deploy code).

### Use Board Tasks, NOT TodoWrite

TodoWrite is ephemeral — it dies when the session ends. Board tasks persist forever and enable cross-session handoff. When you would reach for TodoWrite to track multi-step work, use `board_create_task` instead.

**Nothing exists unless it's on the board.** If an action item, future phase, recommendation, or follow-up is mentioned in conversation or discovered in a document but has no board task, it WILL be forgotten. The board is the single source of truth for "what needs to be done." Conversation text, plan docs, and strategy docs are reference material — the board is the task list. When in doubt, create the task. A redundant board task costs nothing; a forgotten action item costs real work.

### Proactive Triggers

These are condition → action pairs. When the condition is true, take the action immediately.

| Condition | Action |
|-----------|--------|
| Session starts (substantive work) | `board_create_session` before any other work |
| Context compacted / continuation session | `board_create_session` IMMEDIATELY — compaction loses the active session ID |
| Multi-step task (3+ steps) | `board_create_task` for each step |
| Batch of items (fix 5 bugs, review 3 files) | Parent task + subtask per item via `board_create_task` |
| New work discovered during execution | `board_create_task` immediately |
| Significant decision or blocker | `board_log_activity` |
| Start working on a task | `board_update_task` → `in_progress` + set `assigned_agent` to your name |
| Finish a task | `board_update_task` → `done` |
| Review/audit produces findings | Parent task per severity tier + subtask per finding |
| Deploying a new service for the first time | `board_create_task` for: verify deployment, create CI/CD trigger, push to prod |
| Committing + pushing code | `board_log_activity` with commit hash; update related tasks |
| Read a doc/plan with unbuilt phases or pending items | `board_create_task` for each actionable item not already on the board |
| Mention a future action item in conversation | `board_create_task` immediately — conversation text is ephemeral, board tasks are permanent |
| A sub-agent reports a finding or recommendation | `board_create_task` if it requires future work (don't let it exist only in conversation) |
| User says "handoff" or signals session end | Create board tasks for ALL pending next steps, THEN `board_end_session` |
| Session ending OR context getting long | `board_end_session` with handoff notes |

**The test**: If this session died right now, could the next session reconstruct what you were doing from the board alone? If not, you haven't been proactive enough.

**The second test**: If a documented plan has unchecked items, unbuilt phases, or "pending" status markers — and there's no corresponding board task — that's a gap. Every actionable item in every plan doc should have a board task. Plans without board tasks get forgotten.

### Session Lifecycle

**Starting a session** (before any other work — **including after context compaction**):

**Context compaction destroys the active session ID.** If you're continuing from a compacted conversation, you MUST call `board_create_session` before doing anything else. This is the #1 failure mode — compaction preserves your behavioral patterns but loses board state.

1. Call `board_get_projects` to see all active projects
2. **Match work to the correct project** — read project names/descriptions and pick the best fit. Do NOT default to one project for everything. Use a general catch-all project only when no specific project fits.
3. Call `board_create_session` with the matched `project_id`
   - This auto-abandons any stale sessions and returns handoff context
   - Read the handoff carefully — it contains what the last session accomplished and what's next
4. Review active tasks via the handoff response or `board_get_tasks`

**During a session:**
- **Planning**: Create all tasks on the board immediately with status `todo`. This ensures the plan survives even if the session crashes before execution.
- **Reviewing**: Review the *task list on the board*, not just prose. Call `board_get_tasks`, then use `board_log_activity` with `task_id` and `action: "commented"` to attach review comments to specific tasks. ALL review output MUST go through the board — conversation text disappears when sessions end.
- **Review findings → board tasks**: When a review produces findings, every finding must become a board task — not just an activity log comment. Create one parent task per severity tier (e.g., "Tier 1: BLOCKING items"), then subtasks for each finding using `parent_task_id`. Map priorities: BLOCKING/FAIL → `critical`, HIGH/WARN → `high`, LOW/INFO → `low`. Include enough context in each subtask's description to fix the issue without re-reading the review.
- **Executing**: Move tasks to `in_progress` as work begins, then `done` when complete. `started_at` is set automatically on first move to `in_progress` — work duration = `completed_at - started_at`.
- **Committing**: Log the commit hash via `board_log_activity` on related tasks. When deploying a new service for the first time, create follow-up tasks: (1) verify deployment, (2) create CI/CD trigger, (3) push to production. These are predictable follow-ups — don't wait for the user to ask.
- **Tracking your own work**: The board isn't just for project plans — it tracks what YOU are doing right now. When you receive a batch of items, create a **parent task** for the batch and **subtasks** for each item using `parent_task_id`. Move each subtask to `in_progress` → `done` as you work. This creates a recoverable checkpoint: if the session dies mid-batch, the next agent sees exactly which items are done and which remain.
- **Sub-agent delegation**: When spawning specialist sub-agents that produce detailed findings, instruct them to write results directly to the board. Include the `project_id` and parent task ID in the prompt. The sub-agent returns only a brief summary. This keeps the main agent's context lean while preserving full detail on the board. Pattern: `"Write all findings to the Vibe Board (project: PROJECT_ID, parent task: TASK_ID). Return only a 1-sentence summary to me."`
- **All modes**: Log notable events via `board_log_activity`. Create additional tasks as new work is discovered — the board should always reflect the current state of work.

**Ending a session** (before the session ends or when the user signals they're done):
1. **Scan your tasks**: Check for any tasks still `in_progress` that you own — mark them `done` if complete, or add a `board_log_activity` comment explaining what remains.
2. **Create tasks for all next steps**: Every pending follow-up must exist as a board task BEFORE ending. Do not list future work only in handoff prose — if it's worth mentioning as a next step, it's worth tracking as a task.
3. Call `board_end_session` with progress_summary, handoff_notes (referencing task IDs, not just prose), and context_artifacts.

**This is the most critical step.** A session without handoff notes is a session whose context is lost forever.

**Proactive ending**: If you sense the conversation is getting long or you are approaching context limits, call `board_end_session` immediately — even a partial handoff is infinitely better than an abandoned session with no notes.

### Task Status Flow

backlog → todo → in_progress → review → done
                       ↓
                    blocked

### Priority Levels

- **critical**: Blocking other work, needs immediate attention
- **high**: Important, should be next
- **medium**: Standard priority (default)
- **low**: Nice to have, do when time allows