Nexus-Prime is a cutting-edge, high-performance orchestration framework designed to automate complex software engineering workflows. Built on a unified Node.js/TypeScript core, it manages a specialized swarm of 28 domain-expert agents that collaborate through a deterministic 4-phase state machine.
By combining a reactive Ink (React) CLI with an intelligent Execution Bus, Nexus-Prime provides a professional-grade environment where AI agents can research, plan, implement, and verify tasks with unprecedented precision and cost-efficiency.
- State-Machine Orchestration: A robust 4-phase engine (DESIGN, PLAN, EXECUTE, COMPLETE) that ensures deterministic transitions and reliable task execution.
- Mandatory QA Gates: Automated quality assurance reviews for every implementation task, enforced by the
qa_engineeragent. - Flash-First Model Tiering: Defaulting to Gemini 3.1 Flash for maximum speed and cost-efficiency, with automated upgrades to Gemini 3.1 Pro for complex architectural and security tasks.
- 3-Handoff Sliding Window: A high-efficiency execution bus that maintains a focused context window of the last 3 task handoffs, preventing token bloat and reducing latency.
- Reactive Ink UI: A modern, interactive CLI built with React and Ink, featuring real-time progress tracking, task logs, and a dedicated interactivity gate for user input.
- 28 Domain Experts: A comprehensive swarm of specialized agents covering everything from API design and cloud architecture to security auditing and performance engineering.
- Interactivity First: A core mandate that ensures agents always ask for clarification when encountering ambiguity via the InteractivityGate.
- O(1) Efficiency: Optimized performance path using pre-mapped dependencies and byte-counting context management.
Nexus-Prime leverages a sophisticated state-machine-driven architecture to ensure reliability and scalability in autonomous workflows.
graph TD
User[User] --> CLI[CLIApp Ink/React]
CLI --> Orchestrator[Orchestrator Core]
subgraph StateMachine [4-Phase State Machine]
DESIGN[DESIGN] --> PLAN[PLAN]
PLAN --> EXECUTE[EXECUTE]
EXECUTE --> COMPLETE[COMPLETE]
end
Orchestrator --> StateMachine
EXECUTE --> TaskStore[Task Store Immer]
TaskStore --> SmartRouter[Smart Router]
SmartRouter -- Complex Task --> Pro[Gemini 3.1 Pro]
SmartRouter -- Standard Task --> Flash[Gemini 3.1 Flash]
Pro --> ExecutionBus[Execution Bus]
Flash --> ExecutionBus
ExecutionBus -- Sliding Window --> Agent[Specialized Agent]
Agent -- ask_user --> Gate[Interactivity Gate]
Gate --> CLI
Agent -- Task Finished --> QA[QA Gate: qa_engineer]
QA -- Pass --> NextTask[Next Task]
| Component | Description |
|---|---|
| Orchestrator | The state machine engine. It manages transitions between DESIGN, PLAN, EXECUTE, and COMPLETE phases. |
| InteractivityGate | A blocking mechanism that pauses execution when an agent requires user input, ensuring human-in-the-loop alignment. |
| QA Gates | Mandatory review cycles where the qa_engineer validates the output of every implementation task before downstream tasks proceed. |
| TaskStore | An immutable state management system powered by Immer. It tracks the status, results, and history of every task. |
| ExecutionBus | The communication layer that manages agent dispatch, context pruning (8k limit), and result collection. |
| SmartRouter | An intelligent routing engine that selects the optimal model (Flash vs Pro) based on task complexity. |
| SkillFactory | A dynamic generator that assembles agent capabilities from modular skill definitions. |
Nexus-Prime comes pre-equipped with a modular library of Specialized Skills. These skills provide the underlying logic and best practices that agents use to execute their tasks.
- Automated Documentation: Native ability to generate OpenAPI/Swagger specs, JSDoc/TypeDoc references, and maintain synchronized READMEs.
- CI/CD Integration: Pre-configured workflows for GitHub Actions, Jenkins, and Docker-based deployment automation.
- Performance Optimization: Advanced profiling, database query analysis, and multi-level caching strategies (Redis/CDN).
- Web Scraping: High-fidelity extraction using Playwright/Puppeteer for dynamic content and Cheerio for static parsing.
- Code Investigation: Deep AST-based mapping and dependency analysis for large-scale architecture recovery.
Each of the 28 agents has a dedicated skill definition (e.g., nexus-architect/SKILL.md) that defines its unique methodology:
- Architect Skill: High-level component design and pattern selection.
- Security Skill: Vulnerability scanning and secure coding enforcement.
- Tester Skill: Comprehensive unit and E2E test implementation using Vitest.
- SRE Skill: Reliability monitoring and incident response procedures.
Nexus-Prime features 28 specialized autonomous agents, each a domain expert in a specific area of the software development lifecycle.
| Agent | Role | Core Expertise |
|---|---|---|
| nexus-api-designer | API Architect | OpenAPI/Swagger, REST/GraphQL design, API documentation. |
| nexus-architect | System Designer | High-level architecture, component diagrams, design patterns. |
| nexus-cli-help | CLI Specialist | Command-line interface design, help text, and usage guides. |
| nexus-cloud-architect | Cloud Expert | AWS/GCP/Azure infrastructure, serverless, and containerization. |
| nexus-codebase-investigator | Code Analyst | Deep-dive analysis of large codebases, pattern discovery. |
| nexus-coder | Lead Developer | Feature implementation, bug fixes, and code optimization. |
| nexus-copywriter | Content Creator | Technical writing, marketing copy, and brand voice. |
| nexus-data-engineer | Data Architect | ETL pipelines, data modeling, and big data processing. |
| nexus-database-admin | DB Specialist | Schema design, query optimization, and migration scripts. |
| nexus-debugger | Bug Hunter | Root cause analysis, stack trace debugging, and hotfixing. |
| nexus-devops-engineer | CI/CD Expert | GitHub Actions, Jenkins, Docker, and deployment automation. |
| nexus-evolution-agent | Self-Improver | System refactoring, tool updates, and autonomous upgrades. |
| nexus-generalist | Versatile Assistant | General-purpose tasks, research, and coordination. |
| nexus-huggingface-skills | AI Integrator | Hugging Face Transformers, datasets, and model deployment. |
| nexus-ml-engineer | ML Specialist | Model training, evaluation, and inference optimization. |
| nexus-nexus-prime | Lead Orchestrator | Project management, phase planning, and agent delegation. |
| nexus-orchestrator-manager | Logic Architect | Orchestration engine maintenance and strategy updates. |
| nexus-performance-engineer | Perf Specialist | Benchmarking, profiling, and latency reduction. |
| nexus-qa-engineer | Quality Lead | Mandatory QA gates, test strategy, and bug reporting. |
| nexus-refactor | Debt Reducer | Code cleanup, modularization, and technical debt removal. |
| nexus-security-auditor | Security Reviewer | Vulnerability scanning, penetration testing, and audits. |
| nexus-security-engineer | Security Builder | Encryption, authentication, and secure coding practices. |
| nexus-seo-specialist | SEO Expert | Search engine optimization, metadata, and web performance. |
| nexus-sre-engineer | Reliability Lead | Monitoring, alerting, and incident response procedures. |
| nexus-technical-writer | Doc Specialist | READMEs, API docs, runbooks, and changelogs. |
| nexus-tester | Test Implementer | Unit, integration, and E2E test development (Vitest). |
| nexus-ui-designer | UI/UX Designer | Component design, styling, and user experience optimization. |
| nexus-validation-agent | Compliance Lead | Final verification, linting, and standard enforcement. |
To install Nexus-Prime as a Gemini CLI extension, run:
gemini extension install https://github.com/MDHaarith/nexus-primeWe welcome contributions to the Nexus-Prime framework! To maintain high quality, we follow a strict 4-Phase State Machine Workflow.
- DESIGN: Requirements gathering, architectural convergence, and initial feasibility analysis.
- PLAN: Component breakdown, agent assignment, and dependency mapping.
- EXECUTE: Implementation of tasks with mandatory QA gates and real-time progress tracking.
- COMPLETE: Final validation, documentation synchronization, and session cleanup.
All contributors must adhere to the Interactivity First mandate. If a task is ambiguous or requires a critical decision:
- Do NOT guess.
- Use the
ask_usertool. - The InteractivityGate will pause execution until the user provides confirmation.
- Tech Stack: Node.js v20+, TypeScript (strict), Ink (React), Immer.
- Testing: We aim for 100% coverage on core logic using Vitest.
- Performance: Startup latency must remain <30ms.
npm install # Install dependencies
npm run build # Build production bundle (esbuild)
npm run type-check # Verify type safety (tsc)- Startup Latency: <30ms (optimized Node.js bundle).
- Test Coverage: 100% statement, line, and function coverage confirmed.
- Accuracy: LLM-driven smart routing with O(1) state transitions.
This project is licensed under the MIT License - see the LICENSE file for details.