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:

```toml
[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

```markdown
# 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

```sql
-- 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](vapora-architecture.md)** — System overview
- **[Agent Registry & Coordination](agent-registry-coordination.md)** — Agent patterns
- **[Multi-Agent Workflows](multi-agent-workflows.md)** — Workflow execution
- **[Multi-IA Router](multi-ia-router.md)** — LLM provider selection
- **[Roles, Permissions & Profiles](roles-permissions-profiles.md)** — RBAC

---

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