g3/docs/ACCUMULATIVE_MODE.md

Accumulative Autonomous Mode

Overview

Accumulative Autonomous Mode is the new default interactive mode for G3. It combines the ease of interactive chat with the power of autonomous implementation, allowing you to build projects iteratively by describing what you want, one requirement at a time.

How It Works

The Flow

1. Start G3 in any directory (no arguments needed)
2. Describe what you want to build
3. G3 automatically:
   • Adds your input to accumulated requirements
   • Runs autonomous mode (coach-player feedback loop)
   • Implements your requirements with quality checks
4. Continue adding more requirements or refinements
5. Repeat until your project is complete

Example Session

$ cd ~/projects/my-new-app
$ g3

🪿 G3 AI Coding Agent - Accumulative Mode
      >> describe what you want, I'll build it iteratively

📁 Workspace: /Users/you/projects/my-new-app

💡 Each input you provide will be added to requirements
   and I'll automatically work on implementing them.

   Type 'exit' or 'quit' to stop, Ctrl+D to finish

============================================================
📝 What would you like me to build? (describe your requirements)
============================================================
requirement> create a simple web server in Python with Flask that serves a homepage

📋 Current instructions and requirements (Turn 1):
   create a simple web server in Python with Flask that serves a homepage

🚀 Starting autonomous implementation...

🤖 G3 AI Coding Agent - Autonomous Mode
📁 Using workspace: /Users/you/projects/my-new-app
📋 Requirements loaded from --requirements flag
🔄 Starting coach-player feedback loop...
📂 No existing implementation files detected
🎯 Starting with player implementation

=== TURN 1/5 - PLAYER MODE ===
🎯 Starting player implementation...
📋 Player starting initial implementation (no prior coach feedback)

[Player creates files, writes code...]

=== TURN 1/5 - COACH MODE ===
🎓 Starting coach review...
🎓 Coach review completed
Coach feedback:
The Flask server is implemented correctly with a homepage route. 
The code follows best practices and meets the requirements.
IMPLEMENTATION_APPROVED

=== SESSION COMPLETED - IMPLEMENTATION APPROVED ===
✅ Coach approved the implementation!

============================================================
📊 AUTONOMOUS MODE SESSION REPORT
============================================================
⏱️  Total Duration: 12.34s
🔄 Turns Taken: 1/5
📝 Final Status: ✅ APPROVED
...
============================================================

✅ Autonomous run completed

============================================================
📝 Turn 2 - What's next? (add more requirements or refinements)
============================================================
requirement> add a /api/users endpoint that returns a list of users as JSON

📋 Current instructions and requirements (Turn 2):
   add a /api/users endpoint that returns a list of users as JSON

🚀 Starting autonomous implementation...

[Autonomous mode runs again with BOTH requirements...]

============================================================
📝 Turn 3 - What's next? (add more requirements or refinements)
============================================================
requirement> exit

👋 Goodbye!

Key Features

1. Requirement Accumulation

Each input you provide is:

• Numbered sequentially (1, 2, 3, ...)
• Stored in memory for the session
• Included in all subsequent runs

This means the agent always has the full context of what you've asked for.

2. Automatic Requirements Document

G3 automatically generates a structured requirements document:

# Project Requirements

## Current Instructions and Requirements:

1. create a simple web server in Python with Flask that serves a homepage
2. add a /api/users endpoint that returns a list of users as JSON
3. add error handling for 404 and 500 errors

## Latest Requirement (Turn 3):

add error handling for 404 and 500 errors

This document is passed to autonomous mode, ensuring the agent:

• Knows all previous requirements
• Focuses on the latest addition
• Maintains consistency across iterations

3. Full Autonomous Quality

Each requirement triggers a complete autonomous run with:

• Coach-Player Feedback Loop: Quality assurance built-in
• Multiple Turns: Up to 5 iterations per requirement (configurable with --max-turns)
• Compilation Checks: Ensures code actually works
• Testing: Coach can run tests to verify functionality

4. Error Recovery

If an autonomous run fails:

• You're notified of the error
• You can provide additional requirements to fix issues
• The session continues (doesn't crash)

5. Workspace Management

• Uses current directory as workspace
• All files created in current directory
• No need to specify workspace path
• Works with existing projects or empty directories

Command-Line Options

Default (Accumulative Mode)

g3

Starts accumulative autonomous mode in the current directory.

With Options

# Use a specific workspace
g3 --workspace ~/projects/my-app

# Limit autonomous turns per requirement
g3 --max-turns 3

# Enable macOS Accessibility tools
g3 --macax

# Enable WebDriver browser automation
g3 --webdriver

# Use a specific provider/model
g3 --provider anthropic --model claude-3-5-sonnet-20241022

# Show prompts and code during execution
g3 --show-prompt --show-code

# Disable log files
g3 --quiet

Disable Accumulative Mode

To use the traditional interactive chat mode:

g3 --accumulative

This gives you the old behavior where you chat with the agent without automatic autonomous runs.

Use Cases

1. Rapid Prototyping

requirement> create a REST API for a todo app
requirement> add SQLite database storage
requirement> add authentication with JWT
requirement> add rate limiting

2. Iterative Refinement

requirement> create a data visualization dashboard
requirement> make the charts interactive
requirement> add dark mode support
requirement> optimize for mobile devices

3. Bug Fixing

requirement> fix the login form validation
requirement> handle edge case when username is empty
requirement> add better error messages

4. Feature Addition

requirement> add export to CSV functionality
requirement> add email notifications
requirement> add admin dashboard

Tips and Best Practices

1. Start Simple

Begin with a basic requirement, let it be implemented, then add complexity:

✅ Good:
requirement> create a basic Flask web server
requirement> add a homepage with a form
requirement> add form validation

❌ Too Complex:
requirement> create a full-stack web app with authentication, database, API, and frontend

2. Be Specific

The more specific you are, the better the results:

✅ Good:
requirement> add a /api/users endpoint that returns JSON with id, name, and email fields

❌ Vague:
requirement> add users

3. One Thing at a Time

Focus each requirement on a single feature or fix:

✅ Good:
requirement> add error handling for database connections
requirement> add logging for all API requests

❌ Multiple Things:
requirement> add error handling and logging and monitoring and alerts

4. Review Between Turns

After each autonomous run completes:

• Check the generated files
• Test the functionality
• Decide what to add or fix next

5. Use Exit Commands

When done:

• Type exit or quit
• Press Ctrl+D (EOF)
• Press Ctrl+C to cancel current input

Comparison with Other Modes

Feature	Accumulative (Default)	Traditional Interactive	Autonomous	Single-Shot
Command	g3	g3 --accumulative	g3 --autonomous	g3 "task"
Input Style	Iterative prompts	Chat messages	requirements.md file	Command-line arg
Auto-Autonomous	✅ Yes	❌ No	✅ Yes	❌ No
Coach-Player Loop	✅ Yes	❌ No	✅ Yes	❌ No
Accumulates Requirements	✅ Yes	❌ No	❌ No	❌ No
Multiple Iterations	✅ Yes	✅ Yes	✅ Yes	❌ No
Best For	Iterative development	Quick questions	Pre-planned projects	One-off tasks

Technical Details

Requirements Storage

• Stored in memory (not persisted to disk)
• Numbered sequentially starting from 1
• Formatted as markdown list
• Passed to autonomous mode as --requirements override

History

• Saved to ~/.g3_accumulative_history
• Separate from traditional interactive history
• Persists across sessions
• Uses rustyline for readline support

Workspace

• Defaults to current directory
• Can be overridden with --workspace
• All files created in workspace
• Logs saved to workspace/logs/

Autonomous Execution

• Full coach-player feedback loop
• Configurable max turns (default: 5)
• Respects all CLI flags (--macax, --webdriver, etc.)
• Error handling allows continuation

Troubleshooting

"No requirements provided"

This shouldn't happen in accumulative mode, but if it does:

• Check that you entered a requirement
• Ensure the requirement isn't empty
• Try restarting G3

"Autonomous run failed"

If an autonomous run fails:

• Read the error message
• Provide a new requirement to fix the issue
• Or type exit and investigate manually

"Context window full"

If you hit token limits:

• The agent will auto-summarize
• Or you can start a new session
• Consider using --max-turns to limit iterations

"Coach never approves"

If the coach keeps rejecting:

• Check the coach feedback for specific issues
• Provide more specific requirements
• Consider increasing --max-turns

Future Enhancements

Planned improvements:

1. Persistence: Save accumulated requirements to disk
2. Editing: Edit or remove previous requirements
3. Branching: Try different approaches
4. Templates: Pre-defined requirement sets
5. Review: Show all accumulated requirements
6. Export: Save to requirements.md
7. Undo: Remove last requirement
8. Replay: Re-run with same requirements

Feedback

This is a new feature! Please provide feedback:

• What works well?
• What's confusing?
• What features would you like?
• Any bugs or issues?

Open an issue on GitHub or contribute improvements!