VIBN Frontend for Coolify deployment
This commit is contained in:
295
docs/GATHERING_AGENT.md
Normal file
295
docs/GATHERING_AGENT.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 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):
|
||||
```typescript
|
||||
{
|
||||
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:
|
||||
```typescript
|
||||
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:
|
||||
```typescript
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
Reference in New Issue
Block a user