OmniSolve is a local, role-based AI software orchestration system designed to plan, generate, validate, and incrementally extend software projects using a disciplined, multi-agent workflow.
The system simulates a structured software development team by coordinating specialized AI agents such as Architect, Planner, Developer, and QA each operating under strict responsibilities and handoff contracts. This approach prioritizes determinism, traceability, and safe continuation over one-shot code generation.
OmniSolve is intended for solo developers who want a persistent, local-first AI development environment that emphasizes architectural correctness, incremental evolution, and professional software engineering practices.
-
Deterministic Behavior
Ensure that given the same project state and request, the system produces predictable, inspectable outcomes rather than nondeterministic one-shot responses. -
Role-Based Separation of Concerns
Enforce strict boundaries between AI agents (Architect, Planner, Developer, QA) to reduce hallucination, scope drift, and unintended side effects. -
Incremental Continuation Over Regeneration
Treat existing project state as authoritative and evolve software incrementally instead of regenerating or overwriting prior work. -
Disk-Authoritative Project State
Use the on-disk file system as the single source of truth, avoiding reliance on implicit memory or assumed context. -
Local-First Execution
Operate entirely on local infrastructure without mandatory cloud dependencies, prioritizing privacy, portability, and offline use. -
Auditability and Traceability
Make all decisions, file changes, and agent outputs observable and reviewable to support debugging, learning, and trust. -
Professional Software Engineering Discipline
Favor correctness, clarity, and maintainability over speed or novelty, reflecting real-world development workflows rather than prompt experimentation.
OmniSolve is structured as a contract-driven, multi-agent system coordinated by a central orchestrator. Each agent operates under a clearly defined role with strict input and output expectations, mirroring the separation of responsibilities found in a professional software development team.
-
Orchestrator
Acts as the execution controller for each run. It sequences agent invocation, assembles context, enforces role boundaries, and governs retries, failure handling, and final persistence. -
Project State Interface (PSI)
A serialized snapshot of the current project derived directly from the file system. The PSI represents the single authoritative view of project structure and state and is treated as immutable for the duration of a run. -
Agent Roles
- Architect: Analyzes the current project state and determines structural changes such as file creation, modification, or preservation.
- Planner: Translates user intent and architectural decisions into a deterministic implementation plan.
- Developer: Produces executable code strictly within the constraints defined by the Architect and Planner.
- QA: Validates correctness, consistency, and adherence to the architectural contract, issuing a binary pass/fail decision.
-
Memory and Advisory Context
Optional, read-only contextual information used to reduce repetition and preserve intent across sessions. Memory is advisory only and never overrides the disk-derived project state.
- The orchestrator captures the current project state from disk and generates the Project State Interface.
- The Architect evaluates the PSI and produces a file-level change plan.
- The Planner converts the architectural plan into a structured logic blueprint.
- The Developer implements the plan without modifying unauthorized files.
- The QA agent reviews the result and either approves the changes or triggers a controlled repair loop.
- Upon QA approval, changes are written atomically to disk and the run is finalized.
This architecture prioritizes predictability, safety, and incremental evolution over raw generation speed, enabling OmniSolve to operate as a reliable development partner rather than a one-shot code generator.
See INSTALLATION_GUIDE.md for detailed setup instructions.
OmniSolve v3.0 includes comprehensive test coverage:
# Install test dependencies
pip install -r requirements.txt
# Run all tests
python -m pytest
# Run with coverage
python -m pytest --cov=Core --cov-report=htmlSee TESTING_GUIDE.md for detailed testing documentation.
The examples/ directory contains self-contained projects demonstrating incremental continuation:
- simple_calculator - Basic calculator with step-by-step enhancement guide
- todo_list - Todo application showing data persistence and CRUD operations
These examples include instructions for testing OmniSolve's continuation capabilities.
- README.md - This file: System overview and design goals
- INSTALLATION_GUIDE.md - Setup and configuration
- TESTING_GUIDE.md - Testing infrastructure and guidelines
- FILE_LIST_v3.0.md - Complete file reference
- DIRECTORY_STRUCTURE.md - Navigation guide
- REFACTORING_SUMMARY.md - v2.4 → v3.0 changes
- POST_INSTALL_CHECKLIST.md - Verification steps
- docs/ROADMAP.md - Future development plans
Current Version: 3.0
Recent Improvements:
- ✅ Modular architecture with 23 refactored modules
- ✅ Comprehensive test suite (30+ unit tests, integration tests)
- ✅ Performance optimizations (PSI caching, pre-compiled regex)
- ✅ Structured logging with JSON audit trails
- ✅ Custom exception hierarchy
- ✅ GitHub Actions CI/CD pipeline
- ✅ Example projects for testing continuation
Test Coverage: 36% (growing - focus on core utilities)
When contributing code:
- Write tests first (see TESTING_GUIDE.md)
- Ensure all tests pass:
python -m pytest - Check coverage:
python -m pytest --cov=Core - Follow existing code style and patterns
- Update documentation as needed
See project documentation for license information.