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
|
||||
|
||||
303
docs/PHASE_SYSTEM.md
Normal file
303
docs/PHASE_SYSTEM.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# Vibn Phase-Based Project System
|
||||
|
||||
⚠️ **LEGACY DOCUMENTATION** - This document describes the old phase system.
|
||||
|
||||
**The new system is documented in `/lib/ai/types.ts` and uses a workflow-based architecture.**
|
||||
|
||||
New phases:
|
||||
1. **Collector** - Document intake (conversational)
|
||||
2. **Extractor** - Insight extraction (JSON)
|
||||
3. **Vision** - Vision synthesis (JSON)
|
||||
4. **MVP** - MVP planning (JSON)
|
||||
5. **Marketing** - Marketing strategy (JSON, parallel)
|
||||
|
||||
See `/lib/ai/orchestrator.ts` for the state machine implementation.
|
||||
|
||||
---
|
||||
|
||||
## The 5 Phases (Legacy)
|
||||
|
||||
### Phase 1: Gathering
|
||||
**Agent:** Gathering Agent
|
||||
**Goal:** Collect and analyze all project materials one item at a time
|
||||
|
||||
**What it does:**
|
||||
- Goes through each context source (docs, GitHub, sessions)
|
||||
- Extracts key insights from each
|
||||
- Confirms each insight with user
|
||||
- Stores confirmed insights
|
||||
|
||||
**Firestore Schema:**
|
||||
```javascript
|
||||
{
|
||||
currentPhase: 'gathering',
|
||||
phaseStatus: 'in_progress', // 'not_started' | 'in_progress' | 'completed'
|
||||
phaseData: {
|
||||
gathering: {
|
||||
startedAt: timestamp,
|
||||
insights: [
|
||||
{
|
||||
id: 'insight_1',
|
||||
source: 'Patient History Overview',
|
||||
sourceType: 'document',
|
||||
sourceId: 'QeC8EIDSkud1jrt6xSyF',
|
||||
insight: 'Using evidence-based diagnostic methods',
|
||||
extractedAt: timestamp,
|
||||
confirmed: true,
|
||||
confirmedAt: timestamp,
|
||||
usedInVision: false,
|
||||
category: 'feature'
|
||||
}
|
||||
],
|
||||
completedAt: timestamp
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Completion Criteria:**
|
||||
- All context sources analyzed
|
||||
- All insights confirmed by user
|
||||
- User says "That's everything" or "Ready to proceed"
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Vision
|
||||
**Agent:** Vision Agent
|
||||
**Goal:** Extract Product Vision Board from confirmed insights
|
||||
|
||||
**What it does:**
|
||||
- Reads all confirmed insights from Phase 1
|
||||
- Extracts the 8 vision nodes
|
||||
- Fills out 4-block Product Vision Board
|
||||
- Gets user approval
|
||||
|
||||
**Firestore Schema:**
|
||||
```javascript
|
||||
{
|
||||
currentPhase: 'vision',
|
||||
phaseStatus: 'in_progress',
|
||||
phaseData: {
|
||||
vision: {
|
||||
startedAt: timestamp,
|
||||
data: {
|
||||
vision: 'One-sentence vision',
|
||||
who: 'Target users',
|
||||
need: 'Problem they face',
|
||||
product: 'Solution features',
|
||||
validation: 'Go-to-market strategy'
|
||||
},
|
||||
approved: true,
|
||||
approvedAt: timestamp,
|
||||
completedAt: timestamp
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Completion Criteria:**
|
||||
- Vision board complete
|
||||
- User approves with "Yes" or "Looks good"
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Scope
|
||||
**Agent:** Scope Agent
|
||||
**Goal:** Define V1 MVP features
|
||||
|
||||
**What it does:**
|
||||
- Takes vision board from Phase 2
|
||||
- Helps user prioritize features (must-have, should-have, nice-to-have)
|
||||
- Defines timeline estimate
|
||||
- Creates V1 feature list
|
||||
|
||||
**Firestore Schema:**
|
||||
```javascript
|
||||
{
|
||||
currentPhase: 'scope',
|
||||
phaseStatus: 'in_progress',
|
||||
phaseData: {
|
||||
scope: {
|
||||
startedAt: timestamp,
|
||||
v1Features: ['Feature 1', 'Feature 2'],
|
||||
timeline: '3-6 months',
|
||||
priorities: {
|
||||
mustHave: [],
|
||||
shouldHave: [],
|
||||
niceToHave: []
|
||||
},
|
||||
completedAt: timestamp
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Blueprint
|
||||
**Agent:** Blueprint Agent
|
||||
**Goal:** Technical architecture design
|
||||
|
||||
**What it does:**
|
||||
- Takes V1 scope from Phase 3
|
||||
- Defines tech stack
|
||||
- Designs database schema
|
||||
- Plans API structure
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Build
|
||||
**Agent:** Build Agent (Future)
|
||||
**Goal:** Implementation guidance
|
||||
|
||||
---
|
||||
|
||||
## Why Phase Tracking?
|
||||
|
||||
### ✅ Prevents Repetition
|
||||
Once Phase 1 is complete, you never re-analyze documents. Phase 2 uses the stored insights.
|
||||
|
||||
### ✅ User Confidence
|
||||
User sees clear progress: "Gathering: ✅ | Vision: ✅ | Scope: 🔄"
|
||||
|
||||
### ✅ Resumable
|
||||
User can leave and come back. The agent knows exactly where they left off.
|
||||
|
||||
### ✅ Traceable
|
||||
Every insight is linked to its source. Vision board items trace back to specific documents.
|
||||
|
||||
---
|
||||
|
||||
## API Usage
|
||||
|
||||
### Get Current Phase
|
||||
```typescript
|
||||
GET /api/projects/phase?projectId=xxx
|
||||
|
||||
Response:
|
||||
{
|
||||
currentPhase: 'gathering',
|
||||
phaseStatus: 'in_progress',
|
||||
phaseData: { /* phase-specific data */ },
|
||||
phaseHistory: []
|
||||
}
|
||||
```
|
||||
|
||||
### Start a Phase
|
||||
```typescript
|
||||
POST /api/projects/phase
|
||||
{
|
||||
projectId: 'xxx',
|
||||
action: 'start',
|
||||
phase: 'gathering'
|
||||
}
|
||||
```
|
||||
|
||||
### Complete a Phase
|
||||
```typescript
|
||||
POST /api/projects/phase
|
||||
{
|
||||
projectId: 'xxx',
|
||||
action: 'complete'
|
||||
}
|
||||
```
|
||||
|
||||
### Save Phase Data
|
||||
```typescript
|
||||
POST /api/projects/phase
|
||||
{
|
||||
projectId: 'xxx',
|
||||
action: 'save_data',
|
||||
data: { /* phase-specific data */ }
|
||||
}
|
||||
```
|
||||
|
||||
### Add Gathering Insight
|
||||
```typescript
|
||||
POST /api/projects/phase
|
||||
{
|
||||
projectId: 'xxx',
|
||||
action: 'add_insight',
|
||||
data: {
|
||||
id: 'insight_1',
|
||||
source: 'Document Name',
|
||||
sourceType: 'document',
|
||||
sourceId: 'doc_id',
|
||||
insight: 'Key finding...',
|
||||
extractedAt: timestamp,
|
||||
confirmed: true,
|
||||
confirmedAt: timestamp,
|
||||
usedInVision: false,
|
||||
category: 'feature'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Selection Logic
|
||||
|
||||
```typescript
|
||||
// In /api/ai/chat/route.ts
|
||||
|
||||
// 1. Check project phase
|
||||
const projectPhase = project.currentPhase || 'gathering';
|
||||
const phaseStatus = project.phaseStatus || 'not_started';
|
||||
|
||||
// 2. Select appropriate agent
|
||||
let agentPrompt;
|
||||
switch (projectPhase) {
|
||||
case 'gathering':
|
||||
agentPrompt = GATHERING_AGENT_PROMPT;
|
||||
break;
|
||||
case 'vision':
|
||||
agentPrompt = VISION_AGENT_PROMPT;
|
||||
break;
|
||||
case 'scope':
|
||||
agentPrompt = SCOPE_AGENT_PROMPT;
|
||||
break;
|
||||
// ... etc
|
||||
}
|
||||
|
||||
// 3. Pass phase data to agent
|
||||
const contextPayload = {
|
||||
...existingContext,
|
||||
currentPhase: projectPhase,
|
||||
phaseStatus: phaseStatus,
|
||||
phaseData: project.phaseData || {}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Plan
|
||||
|
||||
### For Existing Projects
|
||||
Run a migration script to add phase fields:
|
||||
|
||||
```javascript
|
||||
// scripts/add-phase-tracking.ts
|
||||
const projects = await adminDb.collection('projects').get();
|
||||
|
||||
for (const doc of projects.docs) {
|
||||
await doc.ref.update({
|
||||
currentPhase: 'gathering',
|
||||
phaseStatus: 'not_started',
|
||||
phaseData: {},
|
||||
phaseHistory: []
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Phase tracking schema created
|
||||
2. ✅ Phase API endpoints created
|
||||
3. ✅ New projects auto-initialize with gathering phase
|
||||
4. ⏳ Create Gathering Agent prompt
|
||||
5. ⏳ Update chat route to use phase-based agent selection
|
||||
6. ⏳ Build UI to show phase progress
|
||||
7. ⏳ Create migration script for existing projects
|
||||
|
||||
Reference in New Issue
Block a user