diff --git a/README.md b/README.md
index a9875c4..98c8f43 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,17 @@
-- ๐ Cloud-native project management with AI agents
-- ๐ฏ Kanban workflows with glassmorphism UI
-- ๐ค Unified agent runtime powered by MCP
-- โก Built with Rust from backend to frontend
+* ๐ Intelligent Development Orchestration Platform
+* ๐ฏ Specialized agents orchestrate pipelines for your team
+* ๐ค Multi-IA router (Claude, OpenAI, Gemini, Ollama)
+* โก Built with Rust from backend to frontend
[](LICENSE)
[](https://www.rust-lang.org)
[](https://kubernetes.io)
[](https://istio.io)
+[](PROJECT_COMPLETION_REPORT.md)
+[](.coder/summaries/fase-5-deployment.md)
[Features](#-features) โข [Quick Start](#-quick-start) โข [Architecture](#-architecture) โข [Docs](docs/) โข [Contributing](#-contributing)
@@ -27,19 +29,29 @@
Where ideas vaporize into reality
```
- ## ๐ What is Vapora?
+ ## ๐ What is Vapora v2.0?
- **Vapora** is a next-generation project management platform that combines elegant Kanban workflows with intelligent AI agents. Built entirely in Rust, it offers a cloud-native
- architecture designed for teams that demand both beauty and performance.
+ **VAPORA** is an **intelligent development orchestration platform** where teams and AI agents collaborate seamlessly to solve the 4 critical problems in parallel:
+
+ - โ
**Context Switching** (Developers unified in one system instead of jumping between tools)
+ - โ
**Knowledge Fragmentation** (Team decisions, code, and docs discoverable with RAG)
+ - โ
**Manual Coordination** (Specialized agents orchestrate pipelines automatically)
+ - โ
**Dev-Ops Friction** (Unified visibility from code changes through deployment)
+
+ Additional capabilities:
+ - ๐ค **Specialized agents** (Architect, Developer, Reviewer, Tester, Documenter, Marketer, Presenter, DevOps, Monitor, Security, ProjectManager, DecisionMaker - customizable & extensible)
+ - ๐ง **Multi-IA intelligent routing** (Claude, OpenAI, Gemini, Ollama selected per task)
+ - โ๏ธ **Self-hosted on Kubernetes** (no SaaS, complete control, Provisioning-based deployment)
### Key Highlights
- - **๐จ Tron-Inspired UI**: Glassmorphism design with vaporwave aesthetics powered by UnoCSS
- - **๐ค AI-First**: Unified agent runtime using Model Context Protocol (MCP)
- - **๐ Full-Stack Rust**: From frontend (Leptos WASM) to backend (Axum) to infrastructure
- - **โ๏ธ Cloud-Agnostic**: Runs on any Kubernetes cluster with Istio service mesh
- - **๐ Extensible**: Plugin system for custom agents and integrations
- - **๐ Multi-Tenant**: Enterprise-grade isolation with namespace-level security
+ - **๐จ Glassmorphism UI**: Vaporwave aesthetics with UnoCSS, Leptos reactive WASM
+ - **๐ค Specialized Agent Orchestration**: NATS JetStream coordination, parallel pipeline execution with approval gates
+ - **๐ง Multi-IA Router**: Hybrid routing (rules + dynamic + manual override) for optimal LLM per task
+ - **๐ Full-Stack Rust**: Frontend (Leptos), Backend (Axum), Agents, Infrastructure
+ - **โ๏ธ K8s Native**: Istio service mesh, Rook Ceph storage, Cedar policy engine RBAC
+ - **๐ RAG Integration**: Semantic search over Vapora docs, guides, code, and project materials
+ - **๐ Multi-Tenant**: SurrealDB scope isolation, fine-grained Cedar policies, complete audit trails
---
@@ -52,15 +64,29 @@
- **Smart Organization**: Feature tags, priority levels, task ordering
- **Responsive Design**: Works seamlessly from mobile to ultra-wide displays
- ### ๐ค AI Agent Runtime
+ ### ๐ค Specialized AI Agents (Customizable & Extensible)
- - **MCP Gateway Integration**: Unified interface for OpenAI, Claude, and custom agents
- - **Plugin Architecture**: Extend functionality with MCP-compatible plugins
- - **Built-in Capabilities**:
- - ๐ **Code Analysis**: Tree-sitter parsing + LLM semantic review
- - ๐ **RAG Search**: Semantic search over knowledge base with local embeddings
- - ๐ **Doc Generation**: Auto-generate technical documentation from code
- - โ๏ธ **Task Execution**: Automate GitHub PRs, Jira updates, webhooks
+ Select, tune, or extend agents for your pipeline orchestration needs. Default agents include:
+
+ **Parallel Agent Coordination**:
+ - ๐๏ธ **Architect** (Claude Opus): System design & ADRs
+ - ๐ป **Developer** (Claude Sonnet): Code implementation [scales 5-20]
+ - ๐ **CodeReviewer** (Claude Sonnet): Quality assurance & CR
+ - ๐งช **Tester** (Claude Sonnet): Tests & benchmarks
+ - ๐ **Documenter** (GPT-4): Docs & root files
+ - ๐ข **Marketer** (Claude Sonnet): Marketing content
+ - ๐ค **Presenter** (Claude Sonnet): Presentations & slides
+ - โ๏ธ **DevOps** (Claude Sonnet): CI/CD & deployment
+ - ๐๏ธ **Monitor** (Gemini Flash): Health & alerting [real-time]
+ - ๐ **Security** (Claude Opus): Audit & compliance [can block]
+ - ๐ **ProjectManager** (Claude Sonnet): Roadmap & tracking
+ - ๐ฏ **DecisionMaker** (Claude Opus): Conflict resolution
+
+ **Multi-IA Router**: Transparent LLM selection per task context
+ - โ
Automatic selection based on task complexity/latency/cost
+ - โ
Manual override capability with audit logging
+ - โ
Fallback chains (e.g., Claude Opus โ GPT-4 โ Claude Sonnet)
+ - โ
Cost tracking & budget alerts per agent role
### ๐๏ธ Infrastructure
@@ -84,6 +110,7 @@
SurrealDB Multi-model database with scopes
NATS JetStream Message queue for agent jobs
Rig AI agent framework
+ fastembed Local embeddings for RAG
### Frontend
@@ -107,14 +134,18 @@
Gitea Self-hosted Git
- ### Agents
+ ### Agents & LLM
- MCP Gateway Docker MCP gateway for unified agents
- OpenAI AgentKit OpenAI agent integration
- Claude Agent SDK Anthropic Claude integration
- fastembed Local embeddings (privacy-first)
- tree-sitter Code parsing
+ Rig LLM agent framework with tool calling
+ fastembed Local embeddings for semantic search (RAG)
+ NATS JetStream Message queue for async agent coordination
+ Cedar Policy engine for fine-grained RBAC
+ MCP Gateway Model Context Protocol plugin system
+ Claude API Anthropic Claude (Opus, Sonnet, Haiku)
+ OpenAI API GPT-4, GPT-4o, GPT-3.5-turbo
+ Gemini API Google Gemini (2.0 Pro, Flash, 1.5 Pro)
+ Ollama Local LLMs (Llama 2, Mistral, etc.)
---
@@ -165,6 +196,25 @@
```
+### Production Deployment (Kubernetes)
+
+```bash
+# Build and push Docker images
+nu scripts/build-docker.nu --registry docker.io --tag v0.2.0 --push
+
+# Update secrets
+edit kubernetes/03-secrets.yaml # Add your API keys
+
+# Deploy to Kubernetes
+nu scripts/deploy-k8s.nu
+
+# Or use Provisioning (advanced)
+cd provisioning/vapora-wrksp
+provisioning workflow run workflows/deploy-full-stack.yaml
+```
+
+**See full deployment guide**: [`DEPLOYMENT.md`](DEPLOYMENT.md)
+
---
๐๏ธ Architecture
@@ -261,10 +311,10 @@
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ ๐ RAG Search Plugin โ โ
- โ โ Semantic search over knowledge base โ โ
+ โ โ Semantic search over Vapora docs & code โ โ
โ โ โข Local embeddings (fastembed) โ โ
- โ โ โข Top-k retrieval โ โ
- โ โ [Install] โ โ
+ โ โ โข Indexes: guides/, FEATURES, .coder/ โ โ
+ โ โ [โ Installed] โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
@@ -340,22 +390,38 @@
See docs/mcp-plugins.md for full guide.
---
- ๐ข Deployment
+ ๐ข Deployment with Provisioning
- Kubernetes (Production)
+ Using Provisioning (not Helm) for declarative K8s infrastructure:
```bash
- # Setup cluster with Istio + Rook Ceph
- ./scripts/setup-cluster.sh
+ # Navigate to Provisioning workspace
+ cd provisioning/vapora-wrksp
- # Deploy platform services (Vault, Gitea, Zot, etc.)
- ./scripts/deploy-platform.sh
+ # Deploy full VAPORA stack (KCL + Taskservs + Workflows)
+ provisioning workflow run workflows/deploy-full-stack.yaml
- # Deploy Vapora application
- kubectl apply -k kubernetes/overlays/production
+ # This creates:
+ # - K8s cluster (K3s/RKE2) with Cilium CNI
+ # - Istio service mesh with mTLS
+ # - Rook Ceph storage
+ # - SurrealDB (3 replicas, 50Gi storage)
+ # - Redis (3 replicas, 20Gi storage)
+ # - NATS JetStream (3 replicas, 30Gi storage)
+ # - Axum backend (3-10 replicas)
+ # - Leptos frontend (2 replicas)
+ # - Agent runtime (3-50 replicas, HPA enabled)
+ # - LLM Router (2-5 replicas)
+ # - MCP Gateway (2-5 replicas)
- # Create a tenant
- ./scripts/create-tenant.sh acme
+ # Access UI
+ open https://vapora.example.com
+
+ # Scale developer agents
+ provisioning taskserv scale vapora-agents --agent developer --replicas 15
+
+ # Monitor health
+ provisioning health-check --services all
Environment Variables
@@ -406,6 +472,47 @@
- Istio Service Mesh: Traffic flows, mTLS status
- Ceph Storage: Capacity, IOPS, health
+ ---
+ ๐ Documentation & Specifications
+
+ VAPORA v2.0 is built on comprehensive specifications organized by domain:
+
+ **Core Specifications** (guides/core/):
+ - **VAPORA-ARCHITECTURE-V2.md**: 4-layer architecture (Frontend, API, Service, Data, Infrastructure)
+ - **AGENT-REGISTRY-COORDINATION.md**: 12 agent roles, NATS message patterns, health checking
+ - **MULTI-IA-ROUTER.md**: Hybrid routing system (rules + dynamic + override), cost tracking
+ - **MULTI-AGENT-WORKFLOWS.md**: End-to-end workflows with parallel execution & approval gates
+ - **ROLES-PERMISSIONS-PROFILES.md**: Cedar policy engine, team profiles, fine-grained RBAC
+ - **TASK-AGENT-DOC-MANAGER-V2.md**: Multi-agent task orchestration & decision extraction
+
+ **Integration Specifications** (guides/integration/):
+ - **DOC-LIFECYCLE-INTEGRATION.md**: Dual-mode (plugin + standalone) documentation management
+ - **PROVISIONING-INTEGRATION.md**: KCL schemas, taskservs, workflows for K8s deployment
+ - **RAG-INTEGRATION.md**: Semantic search with hybrid retrieval & embedding strategy
+
+ **Component Specifications** (guides/):
+ - **SESSION-LIFECYCLE-MANAGER.md**: .coder/ organization, metadata extraction, decision capture
+ - **ROOT-FILES-KEEPER.md**: Keep README, CHANGELOG, ROADMAP always updated
+ - **MIGRATION-PLAN.md**: Gradual migration path for existing projects
+
+ **Deployment Guide** (provisioning/vapora-wrksp/):
+ - workspace.toml: Master configuration (agents, LLM, monitoring, backup)
+ - taskservs/: Service definitions for backend, frontend, agents, LLM router, MCP gateway
+ - kcl/: Infrastructure as Code schemas (cluster, services, storage, agents, multi-ia)
+ - workflows/: Batch operations (deploy, scale, upgrade, disaster-recovery)
+ - README.md: Quick start and operation guide
+
+ **Implementation Roadmap**:
+ - Phase 1 (Weeks 1-4): Foundation (Axum backend, SurrealDB, JWT auth, Leptos frontend)
+ - Phase 2 (Weeks 5-8): Agents (Registry, NATS, 12 agent implementations)
+ - Phase 3 (Weeks 9-10): Multi-IA (LLM Router, cost tracking, fallback logic)
+ - Phase 4 (Weeks 11-13): Workflows (Orchestrator, parallel execution, dashboard)
+ - Phase 5 (Weeks 14-16): K8s & Provisioning (KCL, taskservs, CI/CD)
+
+ **References**:
+ - CLAUDE.md: Complete project overview with version history
+ - guides/archive/v1-single-agent/: Legacy v1.0 specifications for historical reference
+
---
๐ค Contributing