Vapora/docs/architecture/task-agent-doc-manager.md

Task, Agent & Documentation Manager

Multi-Agent Task Orchestration & Documentation Sync

Status: Production Ready (v1.2.0) Date: January 2026

---

🎯 Overview

System that:

1. Manages tasks in multi-agent workflow
2. Assigns agents automatically based on expertise
3. Coordinates execution in parallel with approval gates
4. Extracts decisions as Architecture Decision Records (ADRs)
5. Maintains documentation automatically synchronized

---

📋 Task Structure

Task Metadata

Tasks are stored in SurrealDB with the following structure:

[task]
id = "task-089"
type = "feature"                    # feature | bugfix | enhancement | tech-debt
title = "Implement learning profiles"
description = "Agent expertise tracking with recency bias"

[status]
state = "in-progress"               # todo | in-progress | review | done | archived
progress = 60                        # 0-100%
created_at = "2026-01-11T10:15:30Z"
updated_at = "2026-01-11T14:30:22Z"

[assignment]
priority = "high"                   # high | medium | low
assigned_agent = "developer"        # Or null if unassigned
assigned_team = "infrastructure"

[estimation]
estimated_hours = 8
actual_hours = null                 # Updated when complete

[context]
related_tasks = ["task-087", "task-088"]
blocking_tasks = []
blocked_by = []

Task Lifecycle

┌─────────┐     ┌──────────────┐     ┌────────┐     ┌──────────┐
│  TODO   │────▶│ IN-PROGRESS  │────▶│ REVIEW │────▶│   DONE   │
└─────────┘     └──────────────┘     └────────┘     └──────────┘
       △                                   │
       │                                   │
       └───────────── ARCHIVED ◀───────────┘

---

🤖 Agent Assignment

Automatic Selection

When a task is created, SwarmCoordinator assigns the best agent:

1. Capability Matching: Filter agents by role matching task type
2. Learning Profile Lookup: Get expertise scores for task-type
3. Load Balancing: Check current agent load (tasks in progress)
4. Scoring: final_score = 0.3*load + 0.5*expertise + 0.2*confidence
5. Notification: Agent receives job via NATS JetStream

Agent Roles

Role	Specialization	Primary Tasks
Architect	System design	Feature planning, ADRs, design reviews
Developer	Implementation	Code generation, refactoring, debugging
Reviewer	Quality assurance	Code review, test coverage, style checks
Tester	QA & Benchmarks	Test suite, performance benchmarks
Documenter	Documentation	Guides, API docs, README updates
Marketer	Marketing content	Blog posts, case studies, announcements
Presenter	Presentations	Slides, deck creation, demo scripts
DevOps	Infrastructure	CI/CD setup, deployment, monitoring
Monitor	Health & Alerting	System monitoring, alerts, incident response
Security	Compliance & Audit	Code security, access control, compliance
ProjectManager	Coordination	Roadmap, tracking, milestone management
DecisionMaker	Conflict Resolution	Tie-breaking, escalation, ADR creation

---

🔄 Multi-Agent Workflow Execution

Sequential Workflow (Phases)

Phase 1: Design
  └─ Architect creates ADR
     └─ Move to Phase 2 (auto on completion)

Phase 2: Development
  └─ Developer implements
  └─ (Parallel) Documenter writes guide
     └─ Move to Phase 3

Phase 3: Review
  └─ Reviewer checks code quality
  └─ Security audits for compliance
     └─ If approved: Move to Phase 4
     └─ If rejected: Back to Phase 2

Phase 4: Testing
  └─ Tester creates test suite
  └─ Tester runs benchmarks
     └─ If passing: Move to Phase 5
     └─ If failing: Back to Phase 2

Phase 5: Completion
  └─ DevOps deploys
  └─ Monitor sets up alerts
  └─ ProjectManager marks done

Parallel Coordination

Multiple agents work simultaneously when independent:

Task: "Add learning profiles"

├─ Architect (ADR)          ▶ Created in 2h
├─ Developer (Code)         ▶ Implemented in 8h
│  ├─ Reviewer (Review)     ▶ Reviewed in 1h (parallel)
│  └─ Documenter (Guide)    ▶ Documented in 2h (parallel)
│
└─ Tester (Tests)           ▶ Tests in 3h
   └─ Security (Audit)      ▶ Audited in 1h (parallel)

Approval Gates

Critical decision points require manual approval:

• Security Gate: Must approve if code touches auth/secrets
• Breaking Changes: Architect approval required
• Production Deployment: DevOps + ProjectManager approval
• Major Refactoring: Architect + Lead Developer approval

---

📝 Decision Extraction (ADRs)

Every design decision is automatically captured:

ADR Template

# ADR-042: Learning-Based Agent Selection

## Context

Previous agent assignment used simple load balancing (min tasks),
ignoring historical performance data. This led to poor agent-task matches.

## Decision

Implement per-task-type learning profiles with recency bias.

### Key Points
- Success rate weighted by recency (7-day window, 3× weight)
- Confidence scoring prevents small-sample overfitting
- Supports adaptive recovery from temporary degradation

## Consequences

**Positive**:
- 30-50% improvement in task success rate
- Agents improve continuously

**Negative**:
- Requires KG data collection (startup period)
- Learning period ~20 tasks per task-type

## Alternatives Considered

1. Rule-based routing (rejected: no learning)
2. Pure random assignment (rejected: no improvement)
3. Rolling average (rejected: no recency bias)

## Decision Made

Option A: Learning profiles with recency bias

ADR Extraction Process

1. Automatic: Each task completion generates execution record
2. Learning: If decision had trade-offs, extract as ADR candidate
3. Curation: ProjectManager/Architect reviews and approves
4. Archival: Stored in docs/architecture/adr/ (numbered, immutable)

---

📚 Documentation Synchronization

Automatic Updates

When tasks complete, documentation is auto-updated:

Task Type	Auto-Updates
Feature	CHANGELOG.md, feature overview, API docs
Bugfix	CHANGELOG.md, troubleshooting guide
Tech-Debt	Architecture docs, refactoring guide
Enhancement	Feature docs, user guide
Documentation	Indexed in RAG, updated in search

Documentation Lifecycle

Task Created
    │
    ▼
Documentation Context Extracted
    │
    ├─ Decision/ADR created
    ├─ Related docs identified
    └─ Change summary prepared
    │
    ▼
Task Execution
    │
    ├─ Code generated
    ├─ Tests created
    └─ Examples documented
    │
    ▼
Task Complete
    │
    ├─ ADR finalized
    ├─ Docs auto-generated
    ├─ CHANGELOG entry created
    └─ Search index updated (RAG)
    │
    ▼
Archival (if stale)
    │
    └─ Moved to docs/archive/
       (kept for historical reference)

---

🔍 Search & Retrieval (RAG Integration)

Document Indexing

All generated documentation is indexed for semantic search:

• Architecture decisions (ADRs)
• Feature guides (how-tos)
• Code examples (patterns)
• Execution history (knowledge graph)

Query Examples

User asks: "How do I implement learning profiles?"

System searches:

1. ADRs mentioning "learning"
2. Implementation guides with "learning"
3. Execution history with similar task type
4. Code examples for "learning profiles"

Returns ranked results with sources.

---

📊 Metrics & Monitoring

Task Metrics

• Success Rate: % of tasks completed successfully
• Cycle Time: Average time from todo → done
• Agent Utilization: Tasks per agent per role
• Decision Quality: ADRs implemented vs. abandoned

Agent Metrics (per role)

• Task Success Rate: % tasks completed successfully
• Learning Curve: Expert improvement over time
• Cost per Task: Average LLM spend per completed task
• Task Coverage: Breadth of task-types handled

Documentation Metrics

• Coverage: % of features documented
• Freshness: Days since last update
• Usage: Search queries hitting each doc
• Accuracy: User feedback on doc correctness

---

🏗️ Implementation Details

SurrealDB Schema

-- Tasks table
DEFINE TABLE tasks SCHEMAFULL;
DEFINE FIELD id ON tasks TYPE string;
DEFINE FIELD type ON tasks TYPE string;
DEFINE FIELD state ON tasks TYPE string;
DEFINE FIELD assigned_agent ON tasks TYPE option<string>;

-- Executions (for learning)
DEFINE TABLE executions SCHEMAFULL;
DEFINE FIELD task_id ON executions TYPE string;
DEFINE FIELD agent_id ON executions TYPE string;
DEFINE FIELD success ON executions TYPE bool;
DEFINE FIELD duration_ms ON executions TYPE number;
DEFINE FIELD cost_cents ON executions TYPE number;

-- ADRs table
DEFINE TABLE adrs SCHEMAFULL;
DEFINE FIELD id ON adrs TYPE string;
DEFINE FIELD task_id ON adrs TYPE string;
DEFINE FIELD title ON adrs TYPE string;
DEFINE FIELD status ON adrs TYPE string; -- draft|approved|archived

NATS Topics

• tasks.{type}.{priority} — Task assignments
• agents.{role}.ready — Agent heartbeats
• agents.{role}.complete — Task completion
• adrs.created — New ADR events
• docs.updated — Documentation changes

---

🎯 Key Design Patterns

1. Event-Driven Coordination

• Task creation → Agent assignment (async via NATS)
• Task completion → Documentation update (eventual consistency)
• No direct API calls between services (loosely coupled)

2. Learning from Execution History

• Every task stores execution metadata (success, duration, cost)
• Learning profiles updated from execution data
• Better assignments improve continuously

3. Decision Extraction

• Design decisions captured as ADRs
• Immutable record of architectural rationale
• Serves as organizational memory

4. Graceful Degradation

• NATS offline: In-memory queue fallback
• Agent unavailable: Task re-assigned to next best
• Doc generation failed: Manual entry allowed

---

📚 Related Documentation

• VAPORA Architecture — System overview
• Agent Registry & Coordination — Agent patterns
• Multi-Agent Workflows — Workflow execution
• Multi-IA Router — LLM provider selection
• Roles, Permissions & Profiles — RBAC

---

Status: ✅ Production Ready Version: 1.2.0 Last Updated: January 2026