VALORA

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

Version Node TypeScript License

Anthropic OpenAI Google Cursor Local

--- ## 🏛️ 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? — design rationale **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 | | 3 | Local Models | Free\*\* | _\*When available in Cursor_ _\*\*Requires a running local model server (e.g. Ollama)_ **Zero configuration required** — works immediately with your Cursor subscription.
### 💎 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** ### 🔒 Security & Compliance Enterprise-grade security controls: - **Credential Guard** — Env var redaction, output scanning, sensitive file blocking - **Command Guard** — Blocks exfiltration, network, eval, and remote access patterns - **Prompt Injection Detection** — Risk-scored scanning of tool results with quarantine/redaction - **MCP Hardening** — Tool definition validation, tool-set drift detection, approval workflows - **Supply Chain Hardening** — Frozen lockfile, blocked install scripts, vulnerability overrides - **Audit Logging** — Complete operation trail with security event tracking
### 🧩 Plugin System Extend Valora with **self-contained plugin directories**: | Contribution | What it adds | | --------------- | --------------------------------------------------- | | `agents` | New AI personas | | `commands` | New CLI verbs (auto-exposed as MCP tools) | | `hooks` | PreToolUse / PostToolUse shell scripts | | `prompts` | Reusable pipeline stages | | `templates` | PR, PRD, and plan scaffolds | | `agent-context` | Markdown injected into agent system prompts | | `code` | TypeScript modules registered via `PluginAPI` hooks | Plugins are discovered from four locations (later takes precedence): `data/plugins/` (built-in), `~/.valora/plugins/` (user), `.valora/plugins/` (project), `node_modules/@windagency/valora-plugin-*` (npm). Install an official plugin with `valora plugin add ` and add its short name to `plugins.enabled` in `.valora/config.json`. No restart required. See [Plugins guide](./documentation/user-guide/plugins.md). To **create** a plugin — from a minimal data plugin to a full code plugin with LLM providers, memory backends, and CLI subcommands — see the [Plugin Authoring Guide](./documentation/developer-guide/plugin-authoring.md). 35 built-in compression strategies ship as three **code plugins** and are the canonical example of the `code` contribution type. See [Strategies by plugin](./documentation/architecture/session-optimization.md#strategies-by-plugin) for the full list. ### 🔌 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 |
### 🌳 Worktree Dashboard & Statistics Live visibility into parallel explorations: - **Worktree Diagram Panel** — Real-time tree view of git worktrees in the `valora dash` dashboard - **Exploration Status** — Colour-coded branches with status icons (▶ running, ✓ completed, ✗ failed) - **Session-Exploration Linking** — Explorations create linked sessions; the dashboard shows exploration details (task, worktrees, status) in the session details view - **Worktree Usage Stats** — Per-session tracking of worktree creation, concurrency, and duration ```plaintext ┌─ Git Worktrees (3) ──────────┐ │ ● main abc1234 │ │ ├── exploration/exp-abc-jwt │ │ │ def5678 ▶ RUNNING │ │ └── feature/new-api │ │ ghi9012 │ └──────────────────────────────┘ ```
--- ## 🚀 Quick Start ### Prerequisites - Node.js 18+ ### Installation ```bash # Install globally pnpm add -g @windagency/valora # pnpm yarn global add @windagency/valora # yarn npm install -g @windagency/valora # npm # Verify installation valora --version # Should output: 2.5.0 ``` ### Project Setup Initialise VALORA in your project: ```bash cd your-project valora init # Minimal setup (.valora/config.json) valora init --full # Full setup with override directories ``` ### Your First Command ```bash # 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**: ```bash valora plan "Add dark mode toggle" # → Generates structured prompt for Cursor AI # → Uses your Cursor subscription (free) ``` ### Optional: API Configuration For fully autonomous execution with cloud providers: ```bash valora config setup --quick # Or set environment variables export ANTHROPIC_API_KEY=sk-ant-... export OPENAI_API_KEY=sk-... ``` ### Optional: Local Models (No API Key) Run fully offline with Ollama or any OpenAI-compatible server: ```bash # Install and start Ollama ollama pull llama3.1 ollama serve # Use it directly valora plan "Add auth" --provider local --model llama3.1 # Or configure as default export LOCAL_BASE_URL=http://localhost:11434/v1 export LOCAL_DEFAULT_MODEL=llama3.1 ``` --- ## 🏗️ Architecture ```plaintext ┌─────────────────────────────────────────────────────────────────────────┐ │ VALORA │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ CLI Layer │ │ Orchestrator │ │ Agent Layer │ │ LLM Layer │ │ │ │ │──│ │──│ │──│ │ │ │ │ • Commands │ │ • Pipeline │ │ • Registry │ │ • Anthropic │ │ │ │ • Wizard │ │ • Executor │ │ • Selection │ │ • OpenAI │ │ │ │ • Output │ │ • Context │ │ • Loading │ │ • Google │ │ │ │ │ │ │ │ │ │ • Local │ │ │ └─────────────┘ └──────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 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 | | `consolidate` | @lead | Consolidate and prune memory stores _(experimental)_ | | `update` | — | Install the latest version of Valora | ### Command Categories ```plaintext ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ 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

User Guide

💻 Developer Guide

Architecture, codebase,
and contributions

Developer Guide

🏛️ Architecture

System design
and decisions

Architecture
### Documentation Structure ```plaintext 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 ├── ... ├── 008-pretooluse-cli-enforcement.md └── 009-supply-chain-hardening.md ``` --- ## 🎯 Use Cases ### New Feature Development ```bash 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 ```bash valora plan "Fix: Login timeout issue" valora implement valora test --type=all valora commit --scope=fix ``` ### Code Review ```bash valora review-code --focus=security valora review-functional --check-a11y=true ``` --- ## 🔧 Project Structure ```plaintext valora/ # npm package root ├── bin/ # CLI entry points │ ├── valora.js # Main CLI │ └── mcp.js # MCP server ├── src/ # TypeScript source │ ├── ast/ # AST-based code intelligence (tree-sitter parsing, symbol index) │ ├── cli/ # Command-line interface │ ├── config/ # Configuration management │ ├── executor/ # Pipeline execution │ ├── llm/ # LLM provider integrations │ ├── lsp/ # LSP integration (language server protocol client) │ ├── memory/ # MemoryProvider registry + bootstrap glue (the bundled vault lives in packages/valora-plugin-memory-vault/; ADR-016 — replaceable via plugin) │ ├── mcp/ # MCP server implementation │ ├── security/ # Agentic AI security (credential, command, injection guards) │ ├── session/ # Session management │ │ └── worktree-stats-tracker.ts # Worktree usage statistics │ ├── ui/ # Terminal UI (dashboard, panels) │ ├── utils/ # Utilities & path resolution │ └── ... ├── data/ # Built-in resources (shipped with package) │ ├── agents/ # Agent definitions (11 agents) │ ├── commands/ # Command specifications (25 commands) │ ├── prompts/ # Structured prompts by phase │ ├── templates/ # Document templates │ ├── hooks/ # Hook scripts │ ├── config.default.json # Default configuration │ ├── hooks.default.json # Default hooks config │ └── external-mcp.default.json # External MCP server registry ├── dist/ # Compiled output (gitignored) ├── __tests__/ # Test suites ├── documentation/ # Comprehensive docs └── package.json ``` ### Project-Level Overrides (`.valora/`) When installed in a project, VALORA supports a `.valora/` directory for local overrides: ```plaintext .valora/ # Project-specific configuration ├── config.json # Project settings (overrides defaults) ├── agents/ # Custom/override agent definitions ├── commands/ # Custom/override command specs ├── prompts/ # Custom/override prompts ├── templates/ # Custom/override templates ├── sessions/ # Session state (gitignored) ├── logs/ # Execution logs (gitignored) ├── index/ # Codebase symbol index (gitignored) ├── memory/ # Agent memory vault (gitignored — ADR-013; layout owned by the active memory plugin per ADR-016) │ ├── version # Vault schema version stamp │ ├── meta.json # Last-written / last-consolidated timestamps │ ├── episodic/.md # 7-day half-life events and observations │ ├── semantic/.md # 30-day half-life patterns and insights │ ├── decisions/.md # 21-day half-life architectural decisions │ ├── embeddings.bin # Packed Float32Array of all embedding vectors │ ├── embeddings.index.json # id → byte-offset index pinned to model + dim │ └── _legacy/ # Archived JSON files from auto-migration └── cache/ # Cache data (gitignored) ``` Resources in `.valora/` take precedence over built-in `data/` resources. --- ## 🌟 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 | | **Token Efficiency** | Content-aware command filters, proactive history pruning, and tool-result deduplication reduce per-call token costs; savings surface in the `valora dash` Optimisation panel | --- ## 🛠️ 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-ai | | **CLI UI** | Ink (React), Chalk, Commander | | **Validation** | Zod | | **Code Intelligence** | web-tree-sitter | | **MCP** | @modelcontextprotocol/sdk | --- ## 🛡️ Compliance Valora operates at the **Limited Risk** tier of the EU AI Act (Regulation (EU) 2024/1689). | Document | Description | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [System Card](./documentation/architecture/system-card.md) | Technical documentation for auditors (Annex IV) | | [Instructions for Use](./documentation/user-guide/eu-ai-act-compliance.md) | Intended purpose, out-of-scope domains, deployer obligations (Article 13) | | [GPAI Upstream Policy](./documentation/developer-guide/gpai-upstream-policy.md) | Upstream provider obligations (Article 25) | | [Memory Data Governance](./documentation/user-guide/memory-data-governance.md) | What is stored, retention, and how to purge (Article 10) | | [SECURITY.md](./SECURITY.md) | Responsible disclosure and incident reporting | **Audit export:** `valora security audit-export --out audit.json` --- ## 📄 Licence MIT © Damien TIVELET ---

Get Started • Contribute • Learn More