VALORA

The future of software development is not about replacing developers, but amplifying their capabilities with intelligent AI collaboration.

Features • Quick Start • Architecture • Commands • Documentation

---

🏛️ About VALORA

VALORA (Versatile Agent Logic for Orchestrated Response Architecture) is a next-generation TypeScript-based platform designed to orchestrate a sophisticated network of AI agents to automate the complete software development lifecycle. By moving beyond simple "code generation", VALORA manages the delicate interplay between requirements, architecture, and deployment. VALORA provides intelligent automation while maintaining human oversight.

Why VALORA?

Intelligent Orchestration: VALORA coordinates 11 specialised AI agents, from @lead technical oversight to @secops-engineer compliance, ensuring the right expert is assigned to every task.

Three-Tier Flexibility: The engine adapts to your resources, offering MCP Sampling, Guided Completion, or API Fallback modes.

Phased Governance: Every project follows a rigorous 8-phase lifecycle, moving from initialisation and planning through implementation to validation and PR creation.

Strategic Optimisation: To balance depth and speed, VALORA assigns specific LLMs (like GPT-5 for planning or Claude Haiku for validation) based on the task's complexity.

VALORA is not a replacement for the developer; it is the high-fidelity instrument through which the developer conducts a full symphony of AI agents.

✨ Features

🤖 Multi-Agent Collaboration 11 specialised AI agents with distinct expertise: @lead — Technical oversight & architecture @product-manager — Requirements & prioritisation @software-engineer-* — Implementation specialists @platform-engineer — Infrastructure & DevOps @qa — Testing & quality assurance @secops-engineer — Security & compliance @ui-ux-designer — Design & accessibility	⚡ Three-Tier Execution Flexible execution modes for every use case: Tier Mode Cost 1 MCP Sampling Free* 2 Guided Completion Free 3 API Fallback Pay-per-use *When available in Cursor Zero configuration required — works immediately with your Cursor subscription.
🔄 8-Phase Development Lifecycle Complete workflow automation: Initialisation → Task Prep → Planning ↓ Implementation → Validation → Review ↓ Commit & PR → Feedback Loop Each phase has dedicated commands and agents optimised for the task.	💎 Model Optimisation Strategic AI model assignment for cost efficiency: Model Use Case GPT-5 Thinking Deep analysis, planning Claude Sonnet Implementation, reviews Claude Haiku Fast tasks, validation 31% strategic • 31% execution • 38% fast
🔌 External MCP Integration Connect to 15 external MCP servers with user approval: Category Servers Browser/Test Playwright, Chrome DevTools, BrowserStack Design Figma, Storybook Development GitHub, Serena, Context7 Infrastructure Terraform, Firebase, Google Cloud Data MongoDB, Elastic Observability Grafana, DeepResearch	🔒 Security & Compliance Enterprise-grade security controls: User Approval Flow — Interactive consent before connections Risk Assessment — Low/Medium/High/Critical classification Tool Filtering — Allowlist and blocklist per server Audit Logging — Complete operation trail Session Caching — Remember approvals per session

---

🚀 Quick Start

Prerequisites

• Docker
• ou
  • Node.js 20+
  • pnpm 10.x

Installation

# Navigate to the engine directory
cd .ai/.bin

# Install dependencies
pnpm install

# Build the project
pnpm build

# Install globally
pnpm link

# Verify installation
valora --version

Your First Command

# Create an implementation plan
valora plan "Add user authentication with OAuth"

The engine will:

1. Select the appropriate agent (@lead)
2. Gather codebase context
3. Generate a detailed implementation plan
4. Provide step-by-step guidance

Zero-Config Usage with Cursor subscription

No API keys? No problem. The engine works immediately using Guided Completion Mode:

valora plan "Add dark mode toggle"
# → Generates structured prompt for Cursor AI
# → Uses your Cursor subscription (free)

Optional: API Configuration

For fully autonomous execution:

valora config setup --quick

# Or set environment variables
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                                 VALORA                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────────┐  ┌──────────────┐  ┌─────────────┐  ┌─────────────┐   │
│   │ CLI Layer   │  │ Orchestrator │  │ Agent Layer │  │ LLM Layer   │   │
│   │             │──│              │──│             │──│             │   │
│   │ • Commands  │  │ • Pipeline   │  │ • Registry  │  │ • Anthropic │   │
│   │ • Wizard    │  │ • Executor   │  │ • Selection │  │ • OpenAI    │   │
│   │ • Output    │  │ • Context    │  │ • Loading   │  │ • Google    │   │
│   └─────────────┘  └──────────────┘  └─────────────┘  └─────────────┘   │
│                                                                         │
│   ┌─────────────┐  ┌──────────────┐  ┌─────────────┐  ┌─────────────┐   │
│   │ Session     │  │ Config       │  │ MCP         │  │ Services    │   │
│   │             │  │              │  │             │  │             │   │
│   │ • State     │  │ • Loader     │  │ • Server    │  │ • Logging   │   │
│   │ • Context   │  │ • Schema     │  │ • Tools     │  │ • Cleanup   │   │
│   │ • History   │  │ • Providers  │  │ • Prompts   │  │ • Utils     │   │
│   └─────────────┘  └──────────────┘  └─────────────┘  └─────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Key Design Principles

Principle	Implementation
Modularity	Loosely coupled components with clear interfaces
Extensibility	Plugin architecture for agents, commands, providers
Testability	Comprehensive test suites (unit, integration, e2e)
Observability	Structured logging and session tracking
Resilience	Graceful fallbacks and error recovery

---

📋 Commands

Complete Command Reference

Command	Agent	Description
refine-specs	@product-manager	Collaboratively refine specifications
create-prd	@product-manager	Generate Product Requirements Document
create-backlog	@product-manager	Decompose PRD into tasks
fetch-task	@product-manager	Retrieve next priority task
refine-task	@product-manager	Clarify task requirements
gather-knowledge	@lead	Analyse codebase context
plan	@lead	Create implementation plan
review-plan	@lead	Validate plan quality
implement	Dynamic	Execute code changes
assert	@asserter	Validate implementation
test	@qa	Execute test suites
review-code	@lead	Code quality review
review-functional	@lead	Functional review
commit	@lead	Create conventional commits
create-pr	@lead	Generate pull request
feedback	@product-manager	Capture outcomes

Command Categories

┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐
│ Planning            │  │ Implementation      │  │ Delivery            │
├─────────────────────┤  ├─────────────────────┤  ├─────────────────────┤
│ • refine-specs      │  │ • implement         │  │ • commit            │
│ • create-prd        │  │ • assert            │  │ • create-pr         │
│ • plan              │  │ • test              │  │ • feedback          │
│ • review-plan       │  │ • review-code       │  │                     │
│ • gather-knowledge  │  │ • review-functional │  │                     │
└─────────────────────┘  └─────────────────────┘  └─────────────────────┘

---

📚 Documentation

👤 User Guide Getting started, workflows, and daily usage

💻 Developer Guide Architecture, codebase, and contributions

🏛️ Architecture System design and decisions

Documentation Structure

documentation/
├── README.md                    # Documentation entry point
├── user-guide/                  # For users
│   ├── quick-start.md           # 5-minute getting started
│   ├── workflows.md             # Common patterns
│   └── commands.md              # Command reference
├── developer-guide/             # For developers
│   ├── setup.md                 # Development environment
│   ├── codebase.md              # Code structure
│   └── contributing.md          # How to contribute
├── architecture/                # For architects
│   ├── system-architecture.md   # C4 diagrams
│   ├── components.md            # Component design
│   └── data-flow.md             # Data flow patterns
└── adr/                         # Decision records
    ├── 001-multi-agent-architecture.md
    ├── 002-three-tier-execution.md
    ├── 003-session-based-state.md
    ├── 004-pipeline-execution-model.md
    └── 005-llm-provider-abstraction.md

---

🎯 Use Cases

New Feature Development

valora refine-specs "User authentication with OAuth"
valora create-prd
valora create-backlog
valora fetch-task && valora plan
valora implement
valora review-code && valora commit
valora create-pr

Bug Fix Workflow

valora plan "Fix: Login timeout issue"
valora implement
valora test --type=all
valora commit --scope=fix

Code Review

valora review-code --focus=security
valora review-functional --check-a11y=true

---

🔧 Project Structure

.ai/
├── .bin/                        # TypeScript implementation
│   ├── dist/                    # Built artefacts
│   ├── src/                     # Source code
│   └── tests/                   # Test suites
├── agents/                      # Agent definitions (11 agents)
│   ├── registry.json            # Agent definitions
│   ├── lead.md
│   ├── product-manager.md
│   ├── software-engineer-*.md
│   └── ...
├── commands/                    # Command specifications (16 commands)
│   ├── registry.json            # Command definitions
│   ├── implement.md
│   ├── plan.md
│   └── ...
├── documentation/               # Comprehensive docs
├── external-mcp.json            # External MCP server registry
├── logs/                        # Execution logs
├── prompts/                     # Structured prompts by phase
│   ├── 01_onboard/
│   ├── 02_context/
│   ├── 03_plan/
│   └── ...
├── sessions/                    # Persistent session state
├── templates/                   # Document templates
└── config.json                  # Engine configuration

---

🌟 Why VALORA?

Traditional Development ❌ Context switching between tools ❌ Manual documentation ❌ Inconsistent code reviews ❌ Repetitive commit messages ❌ Time-consuming PR creation

With AI Orchestration ✅ Unified workflow automation ✅ Auto-generated documentation ✅ Comprehensive AI-powered reviews ✅ Intelligent commit messages ✅ One-command PR creation

Innovation Highlights

Innovation	Impact
Multi-Agent Orchestration	Specialised agents produce expert-level output
Three-Tier Execution	Flexibility from free to fully automated
Session Persistence	Context flows naturally between commands
Dynamic Agent Selection	Right expert for every task
Quality Gates	Multiple checkpoints prevent technical debt

---

🚧 Future Improvements

There are still many improvements to be made. Contributions and suggestions are welcome!

Token & Context Management

• Reducing prompt sizes for efficiency
• Memory management optimisation
• Distributing context window occupancy across agents

Metrics & Observability

• Token usage tracking per agent/command
• Execution time metrics
• Cost analysis dashboards

UI & CLI Experience

• Buffer management improvements
• Animations and visual feedback
• Making the CLI fully autonomous
• Enhanced progress indicators

Agent & Command System

• Ability to add custom agents dynamically
• Override existing agent behaviours
• Plugin system for third-party commands
• Hot-reload for agent definitions

Have ideas or suggestions? Contributions are welcome!

---

🛠️ Technology Stack

Category	Technologies
Runtime	Node.js 18+, TypeScript 5.x
Package Manager	pnpm 10.x
Build	tsc, tsc-alias
Testing	Vitest, Playwright
LLM SDKs	@anthropic-ai/sdk, openai, @google/generative-valora
CLI UI	Ink (React), Chalk, Commander
Validation	Zod
MCP	@modelcontextprotocol/sdk

---

📄 Licence

MIT © Damien TIVELET

---

Get Started • Contribute • Learn More