Workflow Management
Quick Reference
- Who: Alex the AI Architect
- Where: CLI Terminal
- Time: ~2-5 minutes per mission
- Prerequisites: Valid
GOOGLE_API_KEY
Prerequisites
- [ ] Python environment activated
- [ ] API keys exported in
.env - [ ] Database initialized
(storage/memory.db)
Step-by-Step Guide
Step 1: Execute a Mission
Open your terminal and navigate to the project root.
Run the entrypoint script with your request:
bashpython3 gemini-run.py "Implement a secure file upload module in Python."The system will start by loading memory context from similar past tasks.
TIP
Be as specific as possible in your request. Including technology preferences (e.g., "use FastAPI") reduces debate rounds.
Step 2: Monitor the Debate
- The Debate Engine will trigger automatically.
- Watch the terminal for the following rounds:
- Opening: Initial plan generation.
- Challenge: Critic and Security agents identify flaws.
- Mitigation: Solution agent fixes the plan.
- The final Consensus Decision will be printed.
Step 3: Verify the Result
- Once the DAG execution completes, the results are stored in the
workflowstable. - Check the output artifacts generated by the
CodingAgent.
Expected Results
- ✅ Plan approved by all 5 debate participants.
- ✅ Tasks executed in parallel according to dependencies.
- ✅ Final audit trace stored in SQLite.
Troubleshooting
🔴 Error: Workflow REJECTED
Cause: SecurityAgent detected a high-severity risk that couldn't be mitigated, or Critic confidence was too low.
Solution:
- Check
observability/orchestrator.logfor the specific "Veto" reason. - Refine your request to include specific security constraints.
- Rerun the workflow.
Source: debate/engine.py:120
🔴 Error: 429 Resource Exhausted
Cause: Hit Gemini API rate limits.
Solution:
- Wait for 1-2 minutes for the
ModelRoutercooldown. - The system will automatically fallback to Mistral if configured.
FAQ
Q: Can I skip the debate phase?
A: No. The system is designed for "Reasoning-First" execution to ensure production quality. (orchestrator/engine.py:95)