alex/g3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Remove flock mode (superseded by studio)

Browse Source 
Flock mode has been superseded by the studio multi-agent workspace manager.

Changes:
- Remove g3-ensembles crate entirely
- Remove --project, --flock-workspace, --segments, --flock-max-turns CLI flags
- Remove run_flock_mode() from autonomous.rs
- Remove flock-related tests from cli_integration_test.rs
- Update README.md, docs/architecture.md, analysis/memory.md
- Delete docs/FLOCK_MODE.md
This commit is contained in:
Dhanji R. Prasanna
2026-01-13 15:01:12 +05:30
parent 82c0165765
commit 9a3b03a41f
18 changed files with 9 additions and 3093 deletions
Download Patch File Download Diff File Expand all files Collapse all files

397
docs/FLOCK_MODE.md
View File

@@ -1,397 +0,0 @@
# g3 Flock Mode Guide
**Last updated**: January 2025
**Source of truth**: `crates/g3-ensembles/src/flock.rs`
## Purpose
Flock mode enables parallel multi-agent development by spawning multiple g3 agent instances that work on different parts of a project simultaneously. This is useful for large projects with modular architectures where independent components can be developed in parallel.
## Overview
In Flock mode:
- Multiple agent instances run concurrently
- Each agent works on a specific module or component
- Agents operate independently but share the same codebase
- Progress is tracked and coordinated centrally
```
┌─────────────────────────────────────────────────────────┐
│ Flock Coordinator │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent N │ │
│ │ Module A│ │ Module B│ │ Module C│ │ Module N│ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Shared Codebase │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## When to Use Flock Mode
**Good candidates**:
- Microservices architectures
- Projects with independent modules
- Large refactoring across multiple files
- Parallel feature development
- Test suite expansion
**Not recommended for**:
- Tightly coupled code
- Sequential dependencies
- Small projects
- Single-file changes
## Configuration
Flock mode is configured through a YAML manifest file:
```yaml
# flock.yaml
name: "my-project-flock"
description: "Parallel development of project modules"
# Global settings
settings:
max_agents: 4
timeout_minutes: 60
provider: "anthropic.default"
# Agent definitions
agents:
- name: "api-agent"
description: "Develops the REST API layer"
working_dir: "src/api"
requirements: |
Implement REST endpoints for user management:
- GET /users
- POST /users
- GET /users/{id}
- PUT /users/{id}
- DELETE /users/{id}
- name: "db-agent"
description: "Develops the database layer"
working_dir: "src/db"
requirements: |
Implement database models and queries:
- User model with CRUD operations
- Connection pooling
- Migration support
- name: "test-agent"
description: "Writes integration tests"
working_dir: "tests"
requirements: |
Write integration tests for:
- API endpoints
- Database operations
- Error handling
```
## Usage
### Starting a Flock
```bash
# Start flock with manifest
g3 --flock flock.yaml
# Start with specific agents only
g3 --flock flock.yaml --agents api-agent,db-agent
# Start with custom timeout
g3 --flock flock.yaml --timeout 120
```
### Monitoring Progress
Flock mode provides real-time status updates:
```
🐦 Flock Status: my-project-flock
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
api-agent [████████░░] 80% Implementing DELETE endpoint
db-agent [██████████] 100% ✅ Complete
test-agent [██████░░░░] 60% Writing error handling tests
Elapsed: 15m 32s | Tokens: 45,230 | Errors: 0
```
### Stopping a Flock
```bash
# Graceful stop (wait for current tasks)
Ctrl+C
# Force stop all agents
Ctrl+C Ctrl+C
```
## Agent Communication
Agents in a flock operate independently but can:
1. **Read shared files**: All agents can read the entire codebase
2. **Write to their area**: Each agent writes to its designated working directory
3. **Signal completion**: Agents report when their tasks are done
4. **Report errors**: Failures are logged and can trigger coordinator action
### Conflict Prevention
To prevent conflicts:
- Assign non-overlapping working directories
- Use clear module boundaries
- Define explicit interfaces between modules
- Run integration after all agents complete
## Status Tracking
Flock status is tracked in `.g3/flock/`:
```
.g3/flock/
├── status.json # Overall flock status
├── api-agent/
│ ├── session.json # Agent session log
│ └── todo.g3.md # Agent's TODO list
├── db-agent/
│ ├── session.json
│ └── todo.g3.md
└── test-agent/
├── session.json
└── todo.g3.md
```
### Status File Format
```json
{
"flock_name": "my-project-flock",
"started_at": "2025-01-03T10:00:00Z",
"status": "running",
"agents": [
{
"name": "api-agent",
"status": "running",
"progress": 80,
"current_task": "Implementing DELETE endpoint",
"tokens_used": 15000,
"errors": 0
}
]
}
```
## Best Practices
### 1. Define Clear Boundaries
```yaml
# Good: Clear module separation
agents:
- name: "frontend"
working_dir: "src/frontend"
- name: "backend"
working_dir: "src/backend"
# Bad: Overlapping directories
agents:
- name: "agent1"
working_dir: "src"
- name: "agent2"
working_dir: "src/utils" # Overlaps with agent1!
```
### 2. Specify Interfaces First
Define shared interfaces before parallel development:
```yaml
agents:
- name: "interface-agent"
priority: 1 # Runs first
requirements: |
Define shared interfaces in src/interfaces/:
- UserService trait
- DatabaseConnection trait
- Error types
- name: "impl-agent"
priority: 2 # Runs after interfaces
depends_on: ["interface-agent"]
requirements: |
Implement UserService trait...
```
### 3. Use Appropriate Granularity
- **Too few agents**: Doesn't leverage parallelism
- **Too many agents**: Coordination overhead, potential conflicts
- **Sweet spot**: 2-6 agents for most projects
### 4. Include a Test Agent
Always include an agent for testing:
```yaml
agents:
- name: "test-agent"
working_dir: "tests"
requirements: |
Write tests for all new functionality.
Run tests after other agents complete.
```
### 5. Plan for Integration
After flock completion:
```bash
# Run all tests
cargo test
# Check for conflicts
git status
# Review changes
git diff
```
## Error Handling
### Agent Failures
If an agent fails:
1. Error is logged to agent's session
2. Coordinator is notified
3. Other agents continue (by default)
4. Failed agent can be restarted
### Restart Failed Agent
```bash
# Restart specific agent
g3 --flock flock.yaml --restart api-agent
# Restart all failed agents
g3 --flock flock.yaml --restart-failed
```
### Conflict Resolution
If agents modify the same file:
1. Last write wins (by default)
2. Conflicts are logged
3. Manual resolution may be needed
## Resource Management
### Token Usage
Each agent has its own token budget:
```yaml
settings:
max_tokens_per_agent: 100000
total_token_budget: 500000
```
### Concurrency
Limit concurrent agents based on:
- API rate limits
- System resources
- Provider capacity
```yaml
settings:
max_concurrent_agents: 3 # Run at most 3 at once
```
## Example: Microservices Project
```yaml
name: "microservices-flock"
settings:
max_agents: 5
provider: "anthropic.default"
agents:
- name: "user-service"
working_dir: "services/user"
requirements: |
Implement user service:
- User registration
- Authentication
- Profile management
- name: "order-service"
working_dir: "services/order"
requirements: |
Implement order service:
- Order creation
- Order status tracking
- Payment integration
- name: "inventory-service"
working_dir: "services/inventory"
requirements: |
Implement inventory service:
- Stock management
- Availability checking
- Reorder alerts
- name: "gateway"
working_dir: "services/gateway"
requirements: |
Implement API gateway:
- Request routing
- Authentication middleware
- Rate limiting
- name: "integration-tests"
working_dir: "tests/integration"
depends_on: ["user-service", "order-service", "inventory-service", "gateway"]
requirements: |
Write integration tests for:
- End-to-end order flow
- Service communication
- Error scenarios
```
## Limitations
- **No real-time coordination**: Agents don't communicate during execution
- **File conflicts**: Possible if boundaries aren't clear
- **Resource intensive**: Multiple LLM calls in parallel
- **Debugging complexity**: Multiple logs to review
## Troubleshooting
### Agents Not Starting
1. Check manifest syntax (YAML)
2. Verify working directories exist
3. Check provider configuration
4. Review logs in `.g3/flock/`
### Slow Progress
1. Reduce number of concurrent agents
2. Check for rate limiting
3. Simplify requirements
4. Use faster provider
### Inconsistent Results
1. Define clearer interfaces
2. Add more specific requirements
3. Use lower temperature
4. Add validation steps

23
docs/architecture.md
View File

@@ -48,12 +48,11 @@ g3 follows a **tool-first philosophy**: instead of just providing advice, it act
│
┌───────────────────────┼───────────────────────┐
│ │ │
┌─────────────────┐ ┌─────────────────┐
│ g3-ensembles │ │ studio │
│ • Flock mode │ │ │
│ • Multi-agent │ │ • Worktree mgmt │
│ • Parallel dev │ │ • Session mgmt │
└─────────────────┘ └─────────────────┘
┌─────────────────┐
│ studio │
│ • Worktree mgmt │
│ • Session mgmt │
└─────────────────┘
```
## Workspace Structure
@@ -71,7 +70,6 @@ g3/
│ ├── g3-execution/ # Code execution engine
│ ├── g3-computer-control/ # Computer automation
│ ├── g3-planner/ # Planning mode workflow
│ ├── g3-ensembles/ # Multi-agent (flock) mode
│ └── studio/ # Multi-agent workspace manager
├── agents/ # Agent persona definitions
├── logs/ # Session logs (auto-created)
@@ -220,17 +218,6 @@ Key modules:
5. Files archived with timestamps
6. Git commit with LLM-generated message
### g3-ensembles (Multi-Agent)
**Location**: `crates/g3-ensembles/`
**Purpose**: Parallel multi-agent development (Flock mode)
Key modules:
- `flock.rs` - Flock orchestration (~43k chars)
- `status.rs` - Agent status tracking
Flock mode enables parallel development by spawning multiple agent instances working on different parts of a project.
### studio (Multi-Agent Workspace Manager)
**Location**: `crates/studio/`