## 🌟 Development flows
when teams and AI agents **orchestrate**
Vapora is an **intelligent development orchestration platform** where teams and AI agents work together in continuous flow. It automates and coordinates software development lifecycle—from design and implementation through testing, documentation, and deployment—while maintaining full context and enabling intelligent decision-making at every step.
Unlike fragmented tool ecosystems, Vapora is a single, self-contained system where developers and AI agents collaborate seamlessly, complexity evaporates, and development flows naturally.
### Core Value Proposition
- ✅ **Unifies task management** with intelligent code context (all in one place)
- ✅ **Reduces context switching** for developers (no tool jumping)
- ✅ **Makes team knowledge** discoverable and actionable (searchable, organized)
- ✅ **Enables AI agents** as first-class team members (12 specialized roles)
- ✅ **Self-hosted** with cloud-agnostic deployment (own your data)
- ✅ **Multi-tenant by design** with fine-grained access control (shared platforms)
### Target Users
- **Development teams** needing better coordination and visibility
- **Organizations** wanting AI assistance embedded in workflow
- **Platform engineers** managing shared development infrastructure
- **Enterprise teams** requiring on-premise deployment and data control
- **Teams at scale** needing fine-grained permissions and multi-tenancy
---
## Table of Contents
1. [Project Management](#project-management)
2. [AI-Powered Intelligence](#ai-powered-intelligence)
3. [Multi-Agent Coordination](#multi-agent-coordination)
- [Learning-Based Agent Selection (Phase 5.3)](#learning-based-agent-selection-phase-53)
- [Budget Enforcement & Cost Optimization (Phase 5.4)](#budget-enforcement--cost-optimization-phase-54)
- [Workflow Orchestrator (v1.2.0)](#workflow-orchestrator-v120)
4. [Knowledge Management](#knowledge-management)
5. [Cloud-Native & Deployment](#cloud-native--deployment)
6. [Security & Multi-Tenancy](#security--multi-tenancy)
7. [Technology Stack](#technology-stack)
8. [Optional Integrations](#optional-integrations)
---
## Project Management
### Kanban Board (Glassmorphism UI)
**Solves**: Context Switching Infinito
The centerpiece of Vapora is a beautiful, responsive Kanban board with real-time collaboration:
- **Intuitive columns**: Todo → Doing → Review → Done (customizable)
- **Drag & drop** task reordering with instant sync across team
- **Glassmorphism design** with vaporwave aesthetics (modern, beautiful UX)
- **Optimistic updates** (UI responds instantly, server syncs in background)
- **Rich task cards** featuring:
- Title, description, priority levels, tags
- Assigned team members (developers + AI agents)
- Subtasks and dependency chains
- Comments and threaded discussions
- Time estimates and actual time spent
- Code snippets and inline documentation
### Unified Task Lifecycle
**Solves**: Task Management Sin Inteligencia
Manage all project work from a single source of truth:
- **Work items** (tasks, bugs, features, chores)
- **Developers + AI agents** treated equally as team members
- **Task templates** for recurring workflow patterns
- **Bulk operations** (reorder, assign, tag, bulk updates)
- **Advanced search & filters**:
- By assignee, status, priority, tags, due date
- Custom filters (created by, mentioned in, blocked by)
- Saved search queries
- **Multiple views**:
- Kanban view (visual workflow)
- List view (text-focused)
- Timeline/Gantt (dependencies and critical path)
- Calendar view (deadline-focused)
- Table view (spreadsheet-like)
### Real-Time Collaboration
- **Live presence** (see who's viewing/editing in real-time)
- **Collaborative comments** with threads and mentions
- **Notifications** (task assigned, commented, updated, blocked)
- **Activity timeline** (audit trail of who did what, when)
- **@mentions** for developers and agents
- **Task watchers** (subscribe to updates)
### Team & Project Organization
- **Multiple projects** per workspace
- **Team members** (both humans and AI agents)
- **Custom roles** with granular permissions
- **Team dashboards** with metrics and burndown
- **Sprint planning** (if using Agile workflow)
- **Backlog management** with story points estimation
---
## AI-Powered Intelligence
### Intelligent Code Context
**Solves**: Knowledge Fragmentado, Task Management Sin Inteligencia
Tasks are more than descriptions—they carry full code context:
- **Automatic code analysis** when tasks reference files or modules
- **Code snippets** displayed inline with syntax highlighting
- **Complexity metrics**:
- Cyclomatic complexity
- Cognitive complexity
- Test coverage by module
- **Pattern detection**:
- Detect anti-patterns and suggest improvements
- Identify code duplication
- Highlight risky changes
- **Dependency visualization**:
- Module dependency graphs
- Impact analysis (what breaks if this changes?)
- Circular dependency detection
- **Architecture insights**:
- Layer violations
- Service coupling analysis
- Component relationships
### Universal Search with RAG
**Solves**: Knowledge Fragmentado
Find any information across your entire knowledge base instantly:
- **Semantic search** powered by RAG (Retrieval-Augmented Generation):
- Search task descriptions, comments, discussions
- Find design decisions and ADRs
- Locate relevant code snippets
- Find previous solutions to similar problems
- Natural language queries: "How do we handle user authentication?"
- **Local embeddings** (fastembed) - privacy-first, no data sent to external services
- **Smart ranking**:
- By relevance (semantic similarity)
- By recency (most recent first)
- By authority (who wrote it, how many references)
- **Context-aware results**:
- Related tasks automatically suggested
- Similar solutions from past projects
- Relevant team members who worked on similar issues
### AI Agent Capabilities
Every team member is empowered by AI assistance:
- **Code-level AI suggestions**:
- Refactoring recommendations
- Performance optimization hints
- Test case suggestions
- Documentation generation
- **Task-level automation**:
- Auto-generate task descriptions
- Suggest related tasks and dependencies
- Estimate effort based on complexity
- Recommend assignees based on expertise
- **Workflow intelligence**:
- Predict blockers before they happen
- Suggest task ordering for efficiency
- Identify bottlenecks in workflow
- Recommend process improvements
---
## Multi-Agent Coordination
### Specialized Agents (Customizable & Tunable)
**Solves**: Task Management Sin Inteligencia, Dev-Ops Handoff Manual, Pipeline Orchestration
Vapora comes with specialized agents that can be customized, extended, or selected based on your team's needs. Default roles include:
| Agent | Role | Specialization |
|-------|------|---|
| **Architect** | System design | Architecture decisions, ADRs, design reviews |
| **Developer** | Implementation | Code writing, refactoring, feature building |
| **CodeReviewer** | Quality gate | Code review, quality checks, suggestions |
| **Tester** | Quality assurance | Test writing, test execution, QA automation |
| **Documenter** | Knowledge keeper | Documentation, guides, API docs, root files |
| **Marketer** | Communications | Release notes, announcements, messaging |
| **Presenter** | Visualization | Presentations, demos, slide decks |
| **DevOps** | Deployment | Pipelines, deployment automation, infrastructure |
| **Monitor** | Operations | Health checks, alerting, observability |
| **Security** | Compliance | Security reviews, vulnerability scanning |
| **ProjectManager** | Planning | Roadmapping, tracking, prioritization |
| **DecisionMaker** | Resolution | Conflict resolution, decision arbitration |
### Agent Orchestration & Workflows
**Solves**: Dev-Ops Handoff Manual, Task Management Sin Inteligencia, Excessive LLM Costs
Agents work together seamlessly without manual coordination through the **Workflow Orchestrator** (`vapora-workflow-engine`):
- **Multi-stage workflow execution**:
- Pre-configured templates (feature_development, bugfix, documentation_update, security_audit)
- Sequential and parallel stage execution
- Approval gates for governance and compliance
- Artifact passing between stages (ADR, Code, TestResults, Review, Documentation)
- **Cost-efficient agent coordination**:
- Short-lived agent contexts (terminate after task completion)
- Context isolation (agents receive only what they need)
- Artifact passing instead of conversation accumulation
- **~95% reduction in cache token costs** vs monolithic sessions
- $840/month → ~$110/month for equivalent workload
- **Parallel execution**: Multiple agents work on different aspects simultaneously
- Developer writes code while Tester writes tests
- Documenter updates docs while DevOps prepares deployment
- **Smart task assignment**:
- Based on agent expertise and availability
- Consider agent workload and queue depth
- Respect skill requirements of the task
- **Dependency management**:
- Automatic task ordering based on dependencies
- Deadlock detection and resolution
- Critical path highlighting
- **Approval gates**:
- Security agent approval for sensitive changes
- Lead review approval before deployment
- Multi-stage review workflows
- API/CLI approval commands
- **Intelligent fallback**:
- If agent fails, escalate or reassign
- Use backup LLM model if primary fails
- Retry with exponential backoff
- **Learning & cost optimization** (Phase 5.3 + 5.4):
- Agents learn from execution history (per-task-type expertise)
- Recent performance weighted 3x (last 7 days) for adaptive selection
- Budget enforcement per role with automatic fallback
- Cost-efficient routing with quality/cost ratio optimization
- Real-time metrics and alerts via Prometheus/Grafana
- **Kogral integration**:
- Context enrichment with guidelines, patterns, and ADRs
- Persistent knowledge reduces session context bloat
- Filesystem-based retrieval from `.kogral/` directory
### Learning-Based Agent Selection (Phase 5.3)
**Solves**: Inefficient agent assignment, static task routing
Agents improve continuously from execution history:
- **Per-task-type learning profiles**:
- Each agent builds expertise scores for different task types
- Success rate calculated from Knowledge Graph execution history
- Confidence scoring prevents small-sample overfitting
- **Recency bias for adaptive selection**:
- Recent executions weighted 3x (last 7 days)
- Exponential decay prevents "permanent reputation"
- Allows agents to recover from bad performance periods
- **Intelligent scoring formula**:
- `final_score = 0.3*load + 0.5*expertise + 0.2*confidence`
- Balances current workload with historical success
- Confidence dampens high variance from few executions
- **Learning curve visualization**:
- Track expertise improvement over time
- Time-series analysis with daily/weekly aggregation
- Identify agents needing additional training or tuning
### Budget Enforcement & Cost Optimization (Phase 5.4)
**Solves**: Runaway LLM costs, unpredictable spending
Control costs with intelligent budget management:
- **Per-role budget limits**:
- Configure monthly and weekly spending caps (in cents)
- Separate budgets for Architect, Developer, Reviewer, etc.
- Automatic weekly/monthly resets with carry-over option
- **Three-tier enforcement**:
1. **Normal operation**: Rule-based routing with cost awareness
2. **Near threshold (>80%)**: Prefer cost-efficient providers
3. **Budget exceeded**: Automatic fallback to cheaper alternatives
- **Cost-efficient provider ranking**:
- Calculate quality/cost ratio: `(quality * 100) / (cost + 1)`
- Quality from historical success rates per provider
- Optimizes for value, not just lowest cost
- **Fallback chain ordering**:
- Ollama (free local) → Gemini (cheap cloud) → OpenAI → Claude
- Ensures tasks complete even when budget exhausted
- Maintains quality at acceptable degradation level
- **Real-time monitoring**:
- Prometheus metrics: budget remaining, utilization, fallback triggers
### Workflow Orchestrator (v1.2.0)
**Solves**: Excessive LLM cache token costs, monolithic session patterns
Execute multi-stage pipelines with short-lived agent contexts for cost-efficient workflows:
- **~95% reduction in cache token costs**:
- Monolithic session: ~$840/month (3.82B cache tokens)
- Multi-stage workflow: ~$110/month (640K cache tokens)
- Agents terminate after task completion, context discarded
- **Pre-configured workflow templates**:
- `feature_development` (5 stages): architecture → implementation (parallel) → testing → review (approval) → deployment (approval)
- `bugfix` (4 stages): investigation → fix → testing → deployment
- `documentation_update` (3 stages): content → review (approval) → publish
- `security_audit` (4 stages): analysis → pentesting → remediation → verification (approval)
- **Artifact passing between stages**:
- ADR (Architecture Decision Record)
- Code (source files)
- TestResults (execution output)
- Review (feedback)
- Documentation (generated docs)
- Custom (user-defined)
- **Approval gates for governance**:
- Stage pauses until manual approval
- API/CLI approval commands
- Approver name logged in audit trail
- NATS events published (`vapora.workflow.approval_required`)
- **Kogral integration for context enrichment**:
- Guidelines from `.kogral/guidelines/{workflow}.md`
- Patterns from `.kogral/patterns/*.md`
- Recent ADRs from `.kogral/adrs/*.md` (5 most recent)
- Reduces session context by storing knowledge persistently
- **REST API & CLI**:
- Start workflow: `POST /api/v1/workflow_orchestrator` or `vapora workflow start`
- List workflows: `GET /api/v1/workflow_orchestrator` or `vapora workflow list`
- Get status: `GET /api/v1/workflow_orchestrator/:id` or `vapora workflow status