vibn-frontend/docs/GATHERING_AGENT.md

Gathering Agent - Implementation Summary

Overview

The Gathering Agent is the first phase in Vibn's multi-agent system. It's responsible for systematically going through each context item (documents, GitHub repos, coding sessions) one at a time, extracting key insights, confirming them with the user, and storing them for later phases.

Key Principle

"SHOW, DON'T GUESS"

Instead of the AI making assumptions about the project, it:

1. Lists what context is available
2. Goes through each item ONE AT A TIME
3. Shows what it found (with specific quotes/references)
4. Gets user confirmation
5. Stores confirmed insights
6. Moves to next item only after confirmation

Files Created/Modified

New Files

1. /prompts/GATHERING_AGENT.md

   • Complete system prompt for the Gathering Agent
   • Defines agent identity, goals, and process
   • Includes communication style guide
   • Provides edge case handling
   • Shows example flow

2. /lib/types/phases.ts (already created)

   • TypeScript definitions for project phases
   • Phase types: gathering, vision, scope, blueprint, execution
   • Status types: not_started, in_progress, completed, skipped, failed

3. /app/api/projects/phase/route.ts (already created)

   • API endpoint to update project phase and status
   • Handles phase transitions and history tracking

4. /docs/PHASE_SYSTEM.md (already created)

   • Documentation for the phase tracking system

Modified Files

1. /app/api/ai/chat/route.ts

   • Added GATHERING_AGENT_PROMPT import
   • Implemented phase-based agent selection logic
   • Reads currentPhase from project document
   • Selects appropriate agent prompt based on phase
   • Auto-marks phase as in_progress when first message is sent
   • Includes phase data in context payload

2. /app/[workspace]/project/[projectId]/v_ai_chat/page.tsx

   • Changed initial message from [VISION_AGENT_AUTO_START] to "Hi! I'm here to help."
   • Filters out auto-start messages from conversation history
   • Updated header from "Vision Agent" to "AI Assistant"
   • Updated description to "Building your project step-by-step"

How It Works

1. Project Initialization

When a project is created (or migrated):

{
  currentPhase: 'gathering',
  phaseStatus: 'not_started',
  phaseData: {},
  phaseHistory: []
}

2. User Opens Chat

1. Frontend loads conversation history from Firestore
2. If no history exists, sends initial greeting: "Hi! I'm here to help."
3. Backend receives message and checks project.currentPhase
4. Since currentPhase === 'gathering', it loads GATHERING_AGENT_PROMPT
5. If phaseStatus === 'not_started', marks it as in_progress

3. Agent Starts Process

The Gathering Agent follows this flow:

Step 1: Initial Greeting

Hi! I'm here to help you gather everything about your project.

I can see you've connected:
- GitHub repo: [repo name or "Not connected"]
- [X] documents
- [Y] coding sessions

Let me go through each item with you to extract the key insights. Ready?

Step 2: Go Through Items One-by-One

📄 [Item Name] ([size])

From this, I found:

✓ [Specific insight with quote or reference]
✓ [Specific insight with quote or reference]  
✓ [Specific insight with quote or reference]

Did I capture this correctly? Anything I missed or got wrong?

Wait for user confirmation before proceeding to next item.

Step 3: Store Insights

After user confirms, the agent calls:

POST /api/projects/phase
{
  projectId: "xxx",
  action: "add_insight",
  data: {
    id: "insight_[timestamp]",
    source: "Document Name",
    sourceType: "document",
    sourceId: "doc_id",
    insight: "Specific finding from document",
    extractedAt: timestamp,
    confirmed: true,
    confirmedAt: timestamp,
    usedInVision: false,
    category: "feature" | "user" | "problem" | "competitor" | "tech" | "progress"
  }
}

Step 4: Final Summary & Handoff

Perfect! I've analyzed everything you've connected:

From [X] documents:
- [Key theme 1 from multiple docs]
- [Key theme 2 from multiple docs]
- [Key theme 3 from multiple docs]

From GitHub:
- [Progress summary]

From Sessions:
- [Activity summary]

Total insights captured: [count]

Do you have anything else to add before I hand this off 
to the Vision Agent to build your Product Vision Board?

[Add more / No, proceed to Vision]

Step 5: Transition to Vision Phase

When user approves handoff:

POST /api/projects/phase
{
  projectId: "xxx",
  newPhase: "vision",
  newStatus: "in_progress",
  phaseSpecificData: {
    gatheredInsights: [...all confirmed insights],
    gatheredAt: timestamp
  }
}

Context Data Structure

The agent receives this JSON payload:

{
  "project": {
    "id": "string",
    "name": "string",
    "githubRepo": "string | null",
    "workspacePath": "string | null",
    "chatgptUrl": "string | null"
  },
  "phase": {
    "current": "gathering",
    "status": "in_progress",
    "data": {}
  },
  "contextSources": [
    {
      "id": "string",
      "name": "string",
      "type": "chat" | "document" | "file",
      "summary": "string",
      "contentPreview": "string (first 500 chars)",
      "contentLength": number,
      "connectedAt": "timestamp"
    }
  ],
  "sessions": [
    {
      "id": "string",
      "workspaceName": "string",
      "createdAt": "timestamp",
      "linkedToProject": boolean
    }
  ]
}

Communication Style

✅ Good Examples

✅ "In your 'User Stories' doc, you listed 15 EMR features..."
✅ "Your 'Canadian EMR' doc mentions TELUS Health, Accuro, OSCAR..."
✅ "I found these features in your SmartClinix doc. Sound right?"

❌ Bad Examples

❌ "I think you're building an EMR system..."
❌ "There are several competitors in this space..."
❌ "ANALYSIS COMPLETE. FEATURES EXTRACTED."

Critical Rules

1. ONE ITEM AT A TIME - Never jump ahead
2. SHOW WHAT YOU FOUND - Always cite specific content
3. GET CONFIRMATION - Never proceed without user approval
4. NEVER GUESS - Only extract what's explicitly stated
5. STORE SILENTLY - Don't tell user about data storage
6. CITE SOURCES - Always reference which doc/file/session
7. NO INTERPRETATION - Just extract facts, not conclusions

Edge Cases

No Context Available

I don't see any context sources yet. To help me understand your 
project, could you:

1. Add documents - Click 'Context' in sidebar to add:
   - ChatGPT conversations
   - Product docs
   - User research

2. Connect GitHub - If you have code

Once you've added materials, I'll go through each one with you!

User Says "Skip This"

Sure, moving on.

📄 [Next Item]...

User Says "That's Outdated"

Got it - I'll note this as outdated. What's the current status?

Testing

To test the Gathering Agent:

1. Reset your chat (click "Reset Chat" button)
2. Refresh the page at: http://localhost:3000/[workspace]/project/[projectId]/v_ai_chat
3. Send first message: "Ready"
4. Agent should start the gathering process

Next Steps

After gathering is complete and user approves:

1. Update project phase to vision
2. Load VISION_AGENT_PROMPT (to be created/updated)
3. Vision Agent uses gathered insights to fill out Product Vision Board
4. Process repeats for each subsequent phase

Benefits of This Approach

1. No More Guessing - AI only uses confirmed information
2. User Control - User approves every insight before it's stored
3. Transparency - User sees exactly what AI found and where
4. Accuracy - No hallucinations or assumptions
5. Progressive - Builds foundation for later phases
6. Resumable - Phase system prevents starting over on reload