mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Initial implementation
This commit is contained in:
Renn F
@@ -0,0 +1,138 @@
|
||||
# Task Management System
|
||||
|
||||
This directory contains all task records for RoboCo. Every piece of work is tracked here, enabling context persistence across agent sessions and providing a complete audit trail.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.tasks/
|
||||
├── README.md # This file
|
||||
├── index.md # Master index of all tasks
|
||||
├── templates/ # Task templates by type
|
||||
│ ├── feature.md
|
||||
│ ├── bugfix.md
|
||||
│ ├── research.md
|
||||
│ ├── documentation.md
|
||||
│ └── design.md
|
||||
├── initiatives/ # Cross-cell initiatives (epics)
|
||||
│ └── {initiative-name}/
|
||||
├── active/ # Currently in-progress tasks
|
||||
│ └── TASK-XXX-{slug}/
|
||||
├── completed/ # Archived tasks by month
|
||||
│ └── YYYY-MM/
|
||||
└── blocked/ # Tasks waiting on blockers
|
||||
└── TASK-XXX-{slug}/
|
||||
```
|
||||
|
||||
## Task Lifecycle
|
||||
|
||||
```
|
||||
┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌───────────┐
|
||||
│ Created │────►│ Assigned │────►│ In Progress │────►│ Verifying │
|
||||
└──────────┘ └──────────┘ └─────────────┘ └─────┬─────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────┐ ┌─────────────┐
|
||||
│ Blocked │ │ Awaiting QA │
|
||||
└──────────┘ └─────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Awaiting Doc │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌───────────┐
|
||||
│ Completed │
|
||||
└───────────┘
|
||||
```
|
||||
|
||||
## Task States
|
||||
|
||||
| State | Meaning | Location |
|
||||
|-------|---------|----------|
|
||||
| `pending` | Created but not started | `active/` |
|
||||
| `claimed` | Agent has taken ownership | `active/` |
|
||||
| `in_progress` | Active work happening | `active/` |
|
||||
| `blocked` | Waiting on something | `blocked/` |
|
||||
| `paused` | Intentionally stopped | `active/` |
|
||||
| `verifying` | Self-review in progress | `active/` |
|
||||
| `awaiting_qa` | Ready for QA review | `active/` |
|
||||
| `needs_revision` | QA requested changes | `active/` |
|
||||
| `awaiting_documentation` | Ready for docs | `active/` |
|
||||
| `completed` | Done | `completed/YYYY-MM/` |
|
||||
| `cancelled` | Abandoned | `completed/YYYY-MM/` |
|
||||
|
||||
## Creating a Task
|
||||
|
||||
1. Choose appropriate template from `templates/`
|
||||
2. Create task directory: `.tasks/active/TASK-XXX-{slug}/`
|
||||
3. Copy template as `README.md`
|
||||
4. Fill in details
|
||||
5. Add to `index.md`
|
||||
|
||||
## Task Directory Contents
|
||||
|
||||
Each task directory contains:
|
||||
|
||||
```
|
||||
TASK-XXX-{slug}/
|
||||
├── README.md # Task overview, status, criteria (REQUIRED)
|
||||
├── requirements.md # Detailed requirements (if complex)
|
||||
├── plan.md # Implementation plan (created by dev)
|
||||
├── journal.md # Agent journey notes (created by dev)
|
||||
├── decisions.md # Decision log (as needed)
|
||||
├── blockers.md # Blocker documentation (if blocked)
|
||||
├── qa-review.md # QA findings (created by QA)
|
||||
├── handoff.md # Documenter handoff (created by dev)
|
||||
└── artifacts/ # Supporting files
|
||||
├── code-samples/
|
||||
└── diagrams/
|
||||
```
|
||||
|
||||
## Task ID Format
|
||||
|
||||
`TASK-{number}-{slug}`
|
||||
|
||||
- **number**: Sequential, zero-padded (001, 002, etc.)
|
||||
- **slug**: Kebab-case description (max 30 chars)
|
||||
|
||||
Examples:
|
||||
- `TASK-042-auth-rate-limiting`
|
||||
- `TASK-055-user-preferences-modal`
|
||||
- `TASK-060-dashboard-redesign`
|
||||
|
||||
## Priority Levels
|
||||
|
||||
| Priority | Meaning | Response Time |
|
||||
|----------|---------|---------------|
|
||||
| P0 | Critical | Drop everything |
|
||||
| P1 | High | Next up |
|
||||
| P2 | Medium | Normal queue |
|
||||
| P3 | Low | When available |
|
||||
|
||||
## Cells
|
||||
|
||||
| Cell | Code | Focus |
|
||||
|------|------|-------|
|
||||
| Backend | `BE` | Python, APIs, services |
|
||||
| Frontend | `FE` | React, TypeScript, UI |
|
||||
| UX/UI | `UX` | Figma, design system |
|
||||
| Board | `BD` | Strategy, marketing |
|
||||
|
||||
## Conventions
|
||||
|
||||
1. **Always update README.md** when status changes
|
||||
2. **Journal as you work** - future agents depend on it
|
||||
3. **Link all commits** in the task record
|
||||
4. **Create handoff.md** before marking awaiting_documentation
|
||||
5. **Move to completed/** only after all work is done
|
||||
6. **Never delete** - move to completed with cancelled status if abandoned
|
||||
|
||||
## Index Maintenance
|
||||
|
||||
The `index.md` file should always reflect current state:
|
||||
- Update when tasks are created
|
||||
- Update when status changes
|
||||
- Update when tasks complete
|
||||
- Keep statistics current
|
||||
@@ -0,0 +1,116 @@
|
||||
# TASK-001: Phase 1 - Core Services
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 1 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint:
|
||||
- Database schema
|
||||
- Messaging API
|
||||
- Agent framework
|
||||
- Infrastructure setup
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Database schema designed and implemented
|
||||
- [x] Messaging API (REST) functional
|
||||
- [x] Agent base class created
|
||||
- [x] Simple orchestrator built
|
||||
- [x] PostgreSQL configured
|
||||
- [x] Redis configured
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Project Configuration
|
||||
- `pyproject.toml` - Dependencies, ruff, mypy, pytest config
|
||||
- `docker-compose.yml` - PostgreSQL, Redis, Qdrant
|
||||
- `.env.example` - Environment template
|
||||
- `alembic/` - Migration setup
|
||||
|
||||
### 2. Data Models (`src/roboco/models/`)
|
||||
| File | Models |
|
||||
|------|--------|
|
||||
| `base.py` | All enums (TaskStatus, AgentRole, Team, etc.) |
|
||||
| `task.py` | Task, TaskPlan, Checkpoint, CommitRef |
|
||||
| `agent.py` | Agent, ModelConfig, AgentPermissions |
|
||||
| `session.py` | Session, SessionConfig |
|
||||
| `message.py` | ExtractedMessage, RawStream |
|
||||
| `group.py` | Group |
|
||||
| `channel.py` | Channel |
|
||||
| `notification.py` | Notification |
|
||||
| `journal.py` | Journal, JournalEntry |
|
||||
| `handoff.py` | DocumenterHandoff |
|
||||
|
||||
### 3. Database Layer (`src/roboco/db/`)
|
||||
- `base.py` - Async SQLAlchemy engine, session factory
|
||||
- `tables.py` - All ORM table definitions (10 tables)
|
||||
|
||||
### 4. Configuration (`src/roboco/config.py`)
|
||||
- Environment-based settings via pydantic-settings
|
||||
- Database, Redis, Qdrant, LLM provider configs
|
||||
|
||||
### 5. Messaging API (`src/roboco/api/`)
|
||||
| Route | Endpoints |
|
||||
|-------|-----------|
|
||||
| `health.py` | `/health`, `/ready` |
|
||||
| `channels.py` | CRUD for channels, member management |
|
||||
| `sessions.py` | Session lifecycle |
|
||||
| `messages.py` | Send, edit, delete messages |
|
||||
| `notifications.py` | Send, list, acknowledge |
|
||||
|
||||
### 6. WebSocket (`src/roboco/api/websocket.py`)
|
||||
- `/ws/channels/{id}` - Channel stream
|
||||
- `/ws/agents/{id}` - Agent output stream
|
||||
- `/ws/sessions/{id}` - Session stream
|
||||
- ConnectionManager for broadcasting
|
||||
|
||||
### 7. Agent Framework (`src/roboco/agents/`)
|
||||
- `base.py` - Agent base class with lifecycle, LLM stubs
|
||||
- `orchestrator.py` - Spawn/stop agents, health monitoring
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/
|
||||
├── __init__.py
|
||||
├── config.py
|
||||
├── models/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py, task.py, agent.py, session.py
|
||||
│ ├── message.py, group.py, channel.py
|
||||
│ ├── notification.py, journal.py, handoff.py
|
||||
│ └── README.md
|
||||
├── db/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py
|
||||
│ └── tables.py
|
||||
├── api/
|
||||
│ ├── __init__.py
|
||||
│ ├── app.py
|
||||
│ ├── deps.py
|
||||
│ ├── websocket.py
|
||||
│ └── routes/
|
||||
│ ├── __init__.py
|
||||
│ ├── health.py
|
||||
│ ├── channels.py
|
||||
│ ├── sessions.py
|
||||
│ ├── messages.py
|
||||
│ └── notifications.py
|
||||
└── agents/
|
||||
├── __init__.py
|
||||
├── base.py
|
||||
└── orchestrator.py
|
||||
```
|
||||
|
||||
## Next Steps (Phase 2: Communication)
|
||||
Per HOMELAB_TEAM_V0.md section 13.4:
|
||||
- [ ] Transcription service (extract messages from LLM streams)
|
||||
- [ ] Message extraction pipeline
|
||||
- [ ] Permission system
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 1 core services complete. Database schema, Messaging API, and Agent framework are functional. WebSocket streaming is in place. Ready for Phase 2 which adds transcription/extraction pipelines to process agent LLM output into structured messages.
|
||||
@@ -0,0 +1,119 @@
|
||||
# TASK-001: Phase 2 - Communication Services
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 2 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.4):
|
||||
- Transcription service (process LLM stream output)
|
||||
- Message extraction pipeline (identify message types)
|
||||
- Permission system (communication matrix enforcement)
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Transcription service buffers LLM stream chunks
|
||||
- [x] Extraction pipeline classifies messages (reasoning, dialogue, decision, action, blocker, technical)
|
||||
- [x] Permission service enforces channel read/write access
|
||||
- [x] Permission service enforces notification permissions
|
||||
- [x] Permission service enforces communication matrix
|
||||
- [x] API routes for stream processing
|
||||
- [x] API routes for permission checks
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Transcription Service (`src/roboco/services/transcription.py`)
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `StreamBuffer` | Accumulates chunks from agent, tracks timing, detects readiness |
|
||||
| `TranscriptionConfig` | Configurable thresholds (min chars, max chars, idle timeout) |
|
||||
| `TranscriptionService` | Main service with lifecycle, buffering, periodic flush |
|
||||
|
||||
Key features:
|
||||
- Buffers raw LLM output by agent/session
|
||||
- Detects segment boundaries (sentences, pauses, max length)
|
||||
- Background task for periodic buffer checking
|
||||
- Callback registration for ready segments
|
||||
|
||||
### 2. Extraction Service (`src/roboco/services/extraction.py`)
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| Pattern matchers | Regex patterns for each MessageType |
|
||||
| `ExtractionResult` | Container for extracted messages with metadata |
|
||||
| `ExtractionConfig` | Configurable extraction settings |
|
||||
| `ExtractionService` | Pattern-based message classification |
|
||||
| `ExtractionPipeline` | End-to-end processing with callbacks |
|
||||
|
||||
Message types detected:
|
||||
- **REASONING**: "I'm thinking...", "Let me analyze..."
|
||||
- **DIALOGUE**: Questions, @mentions, conversations
|
||||
- **DECISION**: "I've decided...", "Going with..."
|
||||
- **ACTION**: "Starting...", "Committing...", "Done:"
|
||||
- **BLOCKER**: "Blocked:", "Waiting on...", "Error:"
|
||||
- **TECHNICAL**: Code blocks, API explanations
|
||||
|
||||
### 3. Permission Service (`src/roboco/services/permissions.py`)
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `PermissionLevel` | Hierarchy levels (CEO → Board → Main PM → Cell PM → Member) |
|
||||
| `ChannelPermission` | Defines read/write access per channel |
|
||||
| `COMMUNICATION_MATRIX` | Who can communicate with whom |
|
||||
| `NOTIFICATION_TARGETS` | Who can notify whom |
|
||||
| `TASK_PERMISSIONS` | Task actions by role |
|
||||
| `PermissionService` | Main service for all permission checks |
|
||||
|
||||
Channel permissions implemented:
|
||||
- Cell channels (backend-cell, frontend-cell, uxui-cell)
|
||||
- Cross-cell channels (dev-all, qa-all, pm-all, doc-all)
|
||||
- Management channels (main-pm-board, board-private)
|
||||
- Special channels (announcements, all-hands)
|
||||
|
||||
Auditor has silent read access to all channels.
|
||||
|
||||
### 4. API Integration
|
||||
|
||||
#### New Dependencies (`src/roboco/api/deps.py`)
|
||||
- `PermissionServiceDep` - Injects permission service
|
||||
- `CurrentAgentContext` - Full agent context from headers
|
||||
- `require_channel_read()` - Dependency factory for channel read checks
|
||||
- `require_channel_write()` - Dependency factory for channel write checks
|
||||
- `require_notification_permission()` - Dependency for notification checks
|
||||
|
||||
#### New Routes (`src/roboco/api/routes/stream.py`)
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/v1/stream/chunk` | POST | Process a stream chunk |
|
||||
| `/api/v1/stream/complete` | POST | Mark stream complete, get content |
|
||||
| `/api/v1/stream/extract` | POST | Extract messages from content |
|
||||
| `/api/v1/stream/stats` | GET | Transcription service stats |
|
||||
| `/api/v1/stream/permissions` | GET | Get agent's permission summary |
|
||||
| `/api/v1/stream/permissions/channel/{name}` | GET | Check specific channel access |
|
||||
|
||||
#### App Integration (`src/roboco/api/app.py`)
|
||||
- Services initialized in lifespan context
|
||||
- `app.state.transcription` - Global transcription service
|
||||
- `app.state.extraction` - Global extraction pipeline
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/services/
|
||||
├── __init__.py # Service exports
|
||||
├── transcription.py # StreamBuffer, TranscriptionService
|
||||
├── extraction.py # ExtractionService, ExtractionPipeline
|
||||
└── permissions.py # PermissionService, matrices
|
||||
```
|
||||
|
||||
## Next Steps (Phase 3: Intelligence)
|
||||
Per HOMELAB_TEAM_V0.md section 13.5:
|
||||
- [ ] Setup Qdrant on NAS
|
||||
- [ ] Build embedding pipeline
|
||||
- [ ] Implement Optimal API (RAG queries)
|
||||
- [ ] Implement Journal API
|
||||
- [ ] Index existing repositories
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 2 communication services complete. Transcription buffers LLM streams, extraction classifies message types, and permissions enforce the communication matrix from the blueprint. All services are integrated with the FastAPI application and accessible via `/api/v1/stream/*` endpoints. Ready for Phase 3 which adds RAG/knowledge base capabilities.
|
||||
@@ -0,0 +1,175 @@
|
||||
# TASK-001: Phase 3 - Intelligence Services
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 3 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.5):
|
||||
- RAG system using piragi with PostgreSQL/pgvector
|
||||
- Optimal API for knowledge base queries
|
||||
- Journal API for agent personal logs
|
||||
- Embedding pipeline integration
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] pgvector enabled in PostgreSQL (docker-compose updated)
|
||||
- [x] piragi[postgres] added as dependency
|
||||
- [x] Optimal API service with piragi
|
||||
- [x] Journal API service
|
||||
- [x] API routes for knowledge base operations
|
||||
- [x] API routes for journal operations
|
||||
- [x] Integration with existing extraction pipeline
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Infrastructure Changes
|
||||
|
||||
#### Docker Compose (`docker-compose.yml`)
|
||||
- Changed PostgreSQL image from `postgres:16-alpine` to `pgvector/pgvector:pg16`
|
||||
- Removed Qdrant container (replaced by pgvector)
|
||||
- Removed `qdrant_data` volume
|
||||
|
||||
#### Dependencies (`pyproject.toml`)
|
||||
- Replaced `qdrant-client>=1.7.0` with `piragi[postgres]>=0.1.0`
|
||||
- Updated mypy overrides for piragi
|
||||
|
||||
### 2. Configuration (`src/roboco/config.py`)
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| `rag_persist_dir` | `.piragi` | Directory for piragi index data |
|
||||
| `rag_chunk_strategy` | `semantic` | Chunking: fixed, semantic, hierarchical, contextual |
|
||||
| `rag_chunk_size` | 512 | Characters per chunk |
|
||||
| `rag_chunk_overlap` | 50 | Overlap between chunks |
|
||||
| `rag_use_hyde` | True | Hypothetical document embeddings |
|
||||
| `rag_use_hybrid_search` | True | BM25 + vector hybrid search |
|
||||
| `rag_use_cross_encoder` | False | Neural reranking (slower) |
|
||||
| `rag_auto_update_enabled` | True | Background index updates |
|
||||
| `rag_auto_update_interval` | 300 | Seconds between updates |
|
||||
| `rag_store_url` | computed | PostgreSQL connection for piragi |
|
||||
|
||||
### 3. Optimal API Service (`src/roboco/services/optimal.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `IndexType` | Enum: CODE, DOCUMENTATION, CONVERSATIONS, JOURNALS |
|
||||
| `SearchResult` | Single search result with content, source, score |
|
||||
| `RAGResponse` | Answer with citations |
|
||||
| `QueryContext` | Filters: project, task_id, agent_id, index_types |
|
||||
| `OptimalService` | Main service using AsyncRagi |
|
||||
|
||||
Key features:
|
||||
- Multiple indexes for different content types
|
||||
- Async initialization and cleanup
|
||||
- Code indexing (files, directories, globs)
|
||||
- Documentation indexing (markdown, URLs, crawling)
|
||||
- Conversation indexing (from extraction pipeline)
|
||||
- Journal entry indexing (automatic on creation)
|
||||
- Semantic search across all indexes
|
||||
- RAG queries with citations
|
||||
- HyDE and hybrid search enabled by default
|
||||
|
||||
### 4. Journal API Service (`src/roboco/services/journal.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `JournalStats` | Entry counts, timestamps, summary status |
|
||||
| `GrowthMetrics` | Learning frequency, resolution rates, trends |
|
||||
| `JournalService` | Full CRUD for journals and entries |
|
||||
|
||||
Key features:
|
||||
- Get or create journal per agent
|
||||
- Create entries with automatic RAG indexing
|
||||
- Convenience methods for entry types:
|
||||
- Task reflections
|
||||
- Decision logs
|
||||
- Learning entries
|
||||
- Struggle entries
|
||||
- General notes
|
||||
- List entries with filtering (type, task, privacy)
|
||||
- Journal statistics
|
||||
- Growth metrics calculation
|
||||
- Semantic search through entries
|
||||
|
||||
### 5. API Routes
|
||||
|
||||
#### Optimal API (`src/roboco/api/routes/optimal.py`)
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/v1/optimal/kb/index/code` | POST | Index code files |
|
||||
| `/api/v1/optimal/kb/index/docs` | POST | Index documentation |
|
||||
| `/api/v1/optimal/kb/search` | POST | Semantic search |
|
||||
| `/api/v1/optimal/kb/similar` | GET | Find similar documents |
|
||||
| `/api/v1/optimal/rag/query` | POST | RAG query with answer |
|
||||
| `/api/v1/optimal/rag/context` | POST | Get context without answer |
|
||||
| `/api/v1/optimal/stats` | GET | Index statistics |
|
||||
| `/api/v1/optimal/kb/{type}` | DELETE | Clear an index |
|
||||
| `/api/v1/optimal/kb/refresh` | POST | Refresh index sources |
|
||||
|
||||
#### Journal API (`src/roboco/api/routes/journals.py`)
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/v1/journals/me` | GET | Get my journal |
|
||||
| `/api/v1/journals/{agent_id}` | GET | Get journal by agent |
|
||||
| `/api/v1/journals/me/entries` | GET | List my entries |
|
||||
| `/api/v1/journals/me/entries` | POST | Create entry |
|
||||
| `/api/v1/journals/entries/{id}` | GET | Get entry |
|
||||
| `/api/v1/journals/entries/{id}` | DELETE | Delete entry |
|
||||
| `/api/v1/journals/me/reflections` | POST | Add task reflection |
|
||||
| `/api/v1/journals/me/decisions` | POST | Add decision log |
|
||||
| `/api/v1/journals/me/learnings` | POST | Add learning |
|
||||
| `/api/v1/journals/me/struggles` | POST | Add struggle |
|
||||
| `/api/v1/journals/me/notes` | POST | Add general note |
|
||||
| `/api/v1/journals/me/stats` | GET | Get journal stats |
|
||||
| `/api/v1/journals/me/growth` | GET | Get growth metrics |
|
||||
| `/api/v1/journals/me/search` | POST | Semantic search entries |
|
||||
|
||||
### 6. App Integration (`src/roboco/api/app.py`)
|
||||
- OptimalService initialized in lifespan
|
||||
- Stored in `app.state.optimal`
|
||||
- Proper cleanup on shutdown
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/services/
|
||||
├── __init__.py # Updated with Phase 3 exports
|
||||
├── transcription.py # Phase 2
|
||||
├── extraction.py # Phase 2
|
||||
├── permissions.py # Phase 2
|
||||
├── optimal.py # NEW - RAG/Knowledge Base
|
||||
└── journal.py # NEW - Agent Journals
|
||||
|
||||
src/roboco/api/routes/
|
||||
├── __init__.py # Updated with new routes
|
||||
├── ... (Phase 1-2 routes)
|
||||
├── optimal.py # NEW - Optimal API endpoints
|
||||
└── journals.py # NEW - Journal API endpoints
|
||||
```
|
||||
|
||||
## Technology Choice: piragi
|
||||
|
||||
Selected piragi over Qdrant because:
|
||||
1. **Simpler stack** - Uses existing PostgreSQL with pgvector extension
|
||||
2. **Zero config** - Works with local models out of the box
|
||||
3. **Advanced retrieval** - Built-in HyDE, hybrid search, cross-encoder reranking
|
||||
4. **Async support** - AsyncRagi for FastAPI integration
|
||||
5. **Multiple sources** - Files, directories, URLs, globs, web crawling
|
||||
6. **Auto-updates** - Background refresh without blocking queries
|
||||
|
||||
## Next Steps (Phase 4: Agents)
|
||||
Per HOMELAB_TEAM_V0.md section 13.6:
|
||||
- [ ] Define agent prompts per role
|
||||
- [ ] Implement Dev workflow
|
||||
- [ ] Implement QA workflow
|
||||
- [ ] Implement Documenter workflow
|
||||
- [ ] Implement PM workflows
|
||||
- [ ] Deploy Backend cell
|
||||
- [ ] Deploy Frontend cell
|
||||
- [ ] Deploy UX/UI cell
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 3 intelligence services complete. Using piragi with pgvector for RAG instead of Qdrant - simpler stack, same functionality. Optimal API provides knowledge base indexing and queries. Journal API provides agent personal logs with automatic RAG indexing. All entries are searchable via semantic search. Ready for Phase 4 which implements the actual agent workflows.
|
||||
@@ -0,0 +1,215 @@
|
||||
# TASK-001: Phase 4 - Agents
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 4 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.6):
|
||||
- Define all 17 agent types with role-specific workflows
|
||||
- Implement the task lifecycle for each role
|
||||
- Create cell deployment infrastructure
|
||||
- Enable 3 functioning cells + Board
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Developer workflow implemented (SCAN → CLAIM → UNDERSTAND → PLAN → EXECUTE → VERIFY → NOTES → CLOSE)
|
||||
- [x] QA workflow implemented (MONITOR → RECEIVE → UNDERSTAND → TEST → VERDICT → DOCUMENT → RETURN)
|
||||
- [x] Documenter workflow implemented (MONITOR → RECEIVE → GATHER → SYNTHESIZE → WRITE → REVIEW → PUBLISH)
|
||||
- [x] Cell PM workflow implemented (MONITOR → TRIAGE → ASSIGN → FACILITATE → ESCALATE → TRACK → REPORT)
|
||||
- [x] Main PM workflow implemented (OVERSEE → RECEIVE → PRIORITIZE → COORDINATE → DISTRIBUTE → REPORT UP → FACILITATE)
|
||||
- [x] Board workflows implemented (Product Owner, Head of Marketing, Auditor)
|
||||
- [x] Cell factory and deployment system
|
||||
- [x] Organization factory for complete deployment
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Developer Agent (`src/roboco/agents/developer.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `DevTaskPhase` | Enum: SCAN, CLAIM, UNDERSTAND, PLAN, EXECUTE, VERIFY, NOTES, CLOSE, BLOCKED |
|
||||
| `TaskContext` | Dataclass tracking current task state, subtasks, commits, journal |
|
||||
| `DeveloperAgent` | Full lifecycle implementation with LLM integration |
|
||||
|
||||
Key features:
|
||||
- Phase-based task execution
|
||||
- Subtask breakdown and tracking
|
||||
- Quality checks (ruff, mypy, pytest)
|
||||
- Journal entries at each phase
|
||||
- Handoff creation for documenter
|
||||
- Factory functions for BE/FE/UX developers
|
||||
|
||||
### 2. QA Agent (`src/roboco/agents/qa.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `QATaskPhase` | Enum: MONITOR, RECEIVE, UNDERSTAND, TEST, VERDICT, DOCUMENT, RETURN |
|
||||
| `TestCase` | Dataclass for test execution and results |
|
||||
| `ReviewContext` | Dataclass tracking review state |
|
||||
| `QAAgent` | Full review lifecycle implementation |
|
||||
|
||||
Key features:
|
||||
- Test case generation from requirements
|
||||
- Automated test execution
|
||||
- Clear PASS/FAIL verdicts
|
||||
- Specific feedback for failures
|
||||
- QA report generation
|
||||
|
||||
### 3. Documenter Agent (`src/roboco/agents/documenter.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `DocTaskPhase` | Enum: MONITOR, RECEIVE, GATHER, SYNTHESIZE, WRITE, REVIEW, PUBLISH |
|
||||
| `DocType` | Enum: API, README, ARCHITECTURE, CHANGELOG, etc. |
|
||||
| `DocumentSpec` | Dataclass for document specifications |
|
||||
| `DocumenterAgent` | Full documentation lifecycle |
|
||||
|
||||
Key features:
|
||||
- Material gathering (notes, commits, conversations)
|
||||
- Synthesis of what was built
|
||||
- Automatic document type detection
|
||||
- Self-review before publish
|
||||
- Factory functions for all cells
|
||||
|
||||
### 4. PM Agents (`src/roboco/agents/pm.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `CellPMPhase` | Enum: MONITOR, TRIAGE, ASSIGN, FACILITATE, ESCALATE, TRACK, REPORT |
|
||||
| `MainPMPhase` | Enum: OVERSEE, RECEIVE, PRIORITIZE, COORDINATE, DISTRIBUTE, REPORT_UP, FACILITATE |
|
||||
| `CellPMAgent` | Cell-level management |
|
||||
| `MainPMAgent` | Organization-level coordination |
|
||||
|
||||
Key features:
|
||||
- Continuous duty cycles (never complete)
|
||||
- Task prioritization and assignment
|
||||
- Blocker facilitation
|
||||
- Escalation handling
|
||||
- Status reporting
|
||||
- Cross-cell coordination (Main PM)
|
||||
|
||||
### 5. Board Agents (`src/roboco/agents/board.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `ProductOwnerAgent` | Vision, roadmap, requirements, acceptance |
|
||||
| `HeadMarketingAgent` | Research, strategy, campaigns, analytics |
|
||||
| `AuditorAgent` | Silent observation, analysis, CEO reporting |
|
||||
|
||||
Auditor special powers:
|
||||
- Read ALL channels silently
|
||||
- Query all task history
|
||||
- Access all commits, docs, notes
|
||||
- Direct line to CEO
|
||||
- Can notify anyone (sparingly)
|
||||
|
||||
### 6. Factory and Deployment (`src/roboco/agents/factory.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `Cell` | Complete cell with PM, Devs, QA, Documenter |
|
||||
| `Board` | Product Owner, Head of Marketing, Auditor |
|
||||
| `Organization` | Complete 18-agent organization |
|
||||
|
||||
Factory functions:
|
||||
- `create_backend_cell()` - 5 agents
|
||||
- `create_frontend_cell()` - 5 agents
|
||||
- `create_ux_cell()` - 4 agents
|
||||
- `create_board()` - 3 agents
|
||||
- `create_organization()` - Complete deployment
|
||||
|
||||
Utility functions:
|
||||
- `get_agent_roster()` - List all agents without instantiation
|
||||
- `print_org_chart()` - Text-based org visualization
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/agents/
|
||||
├── __init__.py # Updated with all exports
|
||||
├── base.py # Phase 1 - Base Agent class
|
||||
├── orchestrator.py # Phase 1 - Agent orchestration
|
||||
├── developer.py # NEW - Developer lifecycle
|
||||
├── qa.py # NEW - QA lifecycle
|
||||
├── documenter.py # NEW - Documenter lifecycle
|
||||
├── pm.py # NEW - Cell PM and Main PM
|
||||
├── board.py # NEW - Product Owner, Marketing, Auditor
|
||||
└── factory.py # NEW - Cell and Organization factories
|
||||
```
|
||||
|
||||
## Agent Count
|
||||
|
||||
| Level | Count | Agents |
|
||||
|-------|-------|--------|
|
||||
| Executive | 1 | CEO (Human) |
|
||||
| Board | 3 | Product Owner, Head of Marketing, Auditor |
|
||||
| Management | 1 | Main PM |
|
||||
| Backend Cell | 5 | PM, 2 Devs, QA, Documenter |
|
||||
| Frontend Cell | 5 | PM, 2 Devs, QA, Documenter |
|
||||
| UX/UI Cell | 4 | PM, 1 Dev, QA, Documenter |
|
||||
| **Total** | **19** | 18 AI + 1 Human CEO |
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
### Developer Lifecycle
|
||||
```
|
||||
SCAN → CLAIM → UNDERSTAND → PLAN → EXECUTE → VERIFY → NOTES → CLOSE
|
||||
│ │ │
|
||||
└─────── BLOCKED ───────────┴────────┘
|
||||
```
|
||||
|
||||
### QA Lifecycle
|
||||
```
|
||||
MONITOR → RECEIVE → UNDERSTAND → TEST → VERDICT → DOCUMENT → RETURN
|
||||
│
|
||||
PASS ─┴─ FAIL
|
||||
```
|
||||
|
||||
### Documenter Lifecycle
|
||||
```
|
||||
MONITOR → RECEIVE → GATHER → SYNTHESIZE → WRITE → REVIEW → PUBLISH
|
||||
```
|
||||
|
||||
### Cell PM Lifecycle (Continuous)
|
||||
```
|
||||
MONITOR → TRIAGE → ASSIGN → FACILITATE → ESCALATE → TRACK → REPORT
|
||||
▲ │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Usage Example
|
||||
|
||||
```python
|
||||
from roboco.agents import create_organization
|
||||
|
||||
# Create complete organization
|
||||
org = create_organization()
|
||||
|
||||
# Start all agents
|
||||
await org.start_all()
|
||||
|
||||
# Access specific agents
|
||||
be_dev = org.get_agent_by_slug("be-dev-1")
|
||||
auditor = org.board.auditor
|
||||
|
||||
# Get cell status
|
||||
backend_agents = org.get_agents_by_team(Team.BACKEND)
|
||||
|
||||
# Stop all agents
|
||||
await org.stop_all()
|
||||
```
|
||||
|
||||
## Next Steps (Phase 5: Management)
|
||||
Per HOMELAB_TEAM_V0.md section 13.7:
|
||||
- [ ] Build Kanban interfaces
|
||||
- [ ] Create Auditor dashboard
|
||||
- [ ] Create CEO overview
|
||||
- [ ] Implement metrics collection
|
||||
- [ ] Build reporting system
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 4 agents complete. All 17 agent types implemented with role-specific workflows. Each agent follows its lifecycle from the blueprint (Section 7). Factory functions create complete cells and the full organization. Agents load system prompts from blueprint files in `agents/blueprints/`. Ready for Phase 5 which adds management UIs and dashboards.
|
||||
@@ -0,0 +1,222 @@
|
||||
# TASK-001: Phase 5 - Management
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 5 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.7):
|
||||
- Build Task API for task CRUD and status management
|
||||
- Create Kanban service with role-specific board views
|
||||
- Implement metrics collection and reporting
|
||||
- Build Auditor dashboard API
|
||||
- Build CEO overview API
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Task API with full CRUD operations
|
||||
- [x] Task service with status transitions and lifecycle management
|
||||
- [x] Kanban service with board views for each role
|
||||
- [x] Dev Kanban: Backlog → Assigned → In Progress → QA Review → Documenting → Done
|
||||
- [x] QA Kanban: Awaiting Review → In Review → Passed → Failed
|
||||
- [x] Documenter Kanban: Awaiting Handoff → Gathering → Writing → Published
|
||||
- [x] PM Kanban: Incoming → Triaged → Assigned → In Progress → Blocked → Done
|
||||
- [x] Main PM Kanban: Cross-cell view with Backend/Frontend/UX columns
|
||||
- [x] Board Kanban: Ideas → Roadmap → In Development → Released
|
||||
- [x] Metrics collection (velocity, blockers, completion rate)
|
||||
- [x] Auditor dashboard API (live feeds, flagged items, metrics, reports)
|
||||
- [x] CEO overview API (health status, key metrics, auditor alerts, roadmap progress)
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Task Service (`src/roboco/services/task.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `TaskService` | Full CRUD operations for tasks |
|
||||
| Status transitions | claim, start, block, unblock, pause, resume, verify, submit_for_qa, pass_qa, fail_qa, complete, cancel |
|
||||
| Progress tracking | add_progress, add_checkpoint, add_commit |
|
||||
| Queries | list_all, list_by_team, list_by_assignee, list_by_status, list_pending, list_blocked, list_awaiting_qa, list_awaiting_docs |
|
||||
| Statistics | count_by_status, count_by_team, get_active_count |
|
||||
|
||||
### 2. Task API Routes (`src/roboco/api/routes/tasks.py`)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET/POST /tasks` | List and create tasks |
|
||||
| `GET/PUT/DELETE /tasks/{id}` | Task CRUD |
|
||||
| `GET /tasks/my` | Get agent's tasks |
|
||||
| `GET /tasks/pending, /blocked, /awaiting-qa, /awaiting-docs` | Status-based lists |
|
||||
| `GET /tasks/team/{team}` | Team tasks |
|
||||
| `GET /tasks/stats` | Task statistics |
|
||||
| `POST /tasks/{id}/claim, /start, /block, /unblock, /pause, /resume` | Lifecycle transitions |
|
||||
| `POST /tasks/{id}/verify, /submit-qa, /pass-qa, /fail-qa, /complete, /cancel` | Review transitions |
|
||||
| `POST /tasks/{id}/progress, /checkpoint, /commit` | Progress and artifacts |
|
||||
|
||||
### 3. Kanban Models (`src/roboco/models/kanban.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `KanbanBoardType` | Enum: DEV, QA, DOCUMENTER, PM, MAIN_PM, BOARD |
|
||||
| `KanbanCard` | Card representation with task data |
|
||||
| `KanbanColumn` | Column with cards and WIP limit |
|
||||
| `KanbanSwimlane` | Swimlane for grouping |
|
||||
| `KanbanBoard` | Complete board with columns or swimlanes |
|
||||
| Column configs | DEV_COLUMNS, QA_COLUMNS, DOCUMENTER_COLUMNS, PM_COLUMNS, MAIN_PM_COLUMNS, BOARD_COLUMNS |
|
||||
|
||||
### 4. Kanban Service (`src/roboco/services/kanban.py`)
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `get_dev_board(team, swimlane_by)` | Dev board with optional swimlanes |
|
||||
| `get_qa_board(team)` | QA review board |
|
||||
| `get_documenter_board(team)` | Documenter board |
|
||||
| `get_pm_board(team)` | Cell PM board |
|
||||
| `get_main_pm_board()` | Cross-cell Main PM board |
|
||||
| `get_main_pm_board_flat()` | Flat team-column view |
|
||||
| `get_board_kanban()` | Board-level roadmap |
|
||||
| `get_board_stats(team)` | Board statistics |
|
||||
|
||||
### 5. Kanban API Routes (`src/roboco/api/routes/kanban.py`)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /kanban/dev/{team}` | Dev board with swimlane option |
|
||||
| `GET /kanban/qa/{team}` | QA board |
|
||||
| `GET /kanban/documenter/{team}` | Documenter board |
|
||||
| `GET /kanban/pm/{team}` | Cell PM board |
|
||||
| `GET /kanban/main-pm` | Main PM cross-cell board |
|
||||
| `GET /kanban/board` | Board-level roadmap |
|
||||
| `GET /kanban/stats` | Board statistics |
|
||||
|
||||
### 6. Metrics Service (`src/roboco/services/metrics.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `VelocityMetrics` | Tasks completed, created, avg time, completion rate |
|
||||
| `BlockerMetrics` | Active blockers, avg time, longest blocked, by team |
|
||||
| `TeamMetrics` | Active/blocked/completed tasks, avg time, doc coverage |
|
||||
| `AgentMetrics` | Agent performance and activity |
|
||||
| `get_velocity(days, team)` | Velocity metrics |
|
||||
| `get_blocker_metrics()` | Blocker analysis |
|
||||
| `get_team_metrics(team)` | Team performance |
|
||||
| `get_agent_metrics(agent_id)` | Agent performance |
|
||||
| `get_communication_volume(hours)` | Message and notification counts |
|
||||
| `get_health_status(team)` | ok/slow/critical status |
|
||||
|
||||
### 7. Dashboard API Routes (`src/roboco/api/routes/dashboard.py`)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /dashboard/auditor` | Complete auditor dashboard |
|
||||
| `GET /dashboard/auditor/flags` | Auditor flags with filters |
|
||||
| `POST /dashboard/auditor/flags` | Create flag |
|
||||
| `PUT /dashboard/auditor/flags/{id}/resolve` | Resolve flag |
|
||||
| `GET /dashboard/auditor/reports` | Auditor reports |
|
||||
| `POST /dashboard/auditor/reports` | Create report |
|
||||
| `POST /dashboard/auditor/reports/{id}/send` | Send to CEO |
|
||||
| `GET /dashboard/ceo` | CEO overview |
|
||||
| `GET /dashboard/ceo/teams` | Team details |
|
||||
| `GET /dashboard/ceo/blockers` | Blocker details |
|
||||
| `GET /dashboard/ceo/velocity` | Velocity metrics |
|
||||
| `GET /dashboard/metrics/*` | Various metric endpoints |
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/
|
||||
├── models/
|
||||
│ └── kanban.py # NEW - Kanban board models
|
||||
├── services/
|
||||
│ ├── task.py # NEW - Task CRUD and lifecycle
|
||||
│ ├── kanban.py # NEW - Kanban board generation
|
||||
│ └── metrics.py # NEW - Metrics collection
|
||||
├── api/routes/
|
||||
│ ├── tasks.py # NEW - Task API
|
||||
│ ├── kanban.py # NEW - Kanban API
|
||||
│ └── dashboard.py # NEW - Dashboard API
|
||||
└── api/
|
||||
└── app.py # Updated with new routes
|
||||
```
|
||||
|
||||
## API Summary
|
||||
|
||||
### Task API
|
||||
- Full CRUD for tasks
|
||||
- Complete lifecycle management (claim → start → verify → qa → docs → complete)
|
||||
- Progress tracking and checkpoints
|
||||
- Commit linking
|
||||
|
||||
### Kanban API
|
||||
- 6 board types for different roles
|
||||
- Swimlane support (by priority, assignee)
|
||||
- Cross-cell views for Main PM
|
||||
- Roadmap view for Board
|
||||
|
||||
### Dashboard API
|
||||
- Auditor: Live feeds, flags, metrics, reports
|
||||
- CEO: Health status, metrics, alerts, roadmap
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Create and Track a Task
|
||||
```python
|
||||
# Create task
|
||||
POST /api/v1/tasks
|
||||
{
|
||||
"title": "Implement feature X",
|
||||
"description": "...",
|
||||
"acceptance_criteria": ["..."],
|
||||
"team": "backend",
|
||||
"priority": 1
|
||||
}
|
||||
|
||||
# Claim and start
|
||||
POST /api/v1/tasks/{id}/claim
|
||||
POST /api/v1/tasks/{id}/start
|
||||
|
||||
# Add progress
|
||||
POST /api/v1/tasks/{id}/progress
|
||||
{"message": "Completed first subtask", "percentage": 30}
|
||||
|
||||
# Submit for QA
|
||||
POST /api/v1/tasks/{id}/submit-qa
|
||||
```
|
||||
|
||||
### View Kanban Boards
|
||||
```python
|
||||
# Dev board with priority swimlanes
|
||||
GET /api/v1/kanban/dev/backend?swimlane_by=priority
|
||||
|
||||
# Main PM cross-cell view
|
||||
GET /api/v1/kanban/main-pm?flat=true
|
||||
|
||||
# Board-level roadmap
|
||||
GET /api/v1/kanban/board
|
||||
```
|
||||
|
||||
### CEO Overview
|
||||
```python
|
||||
# Get full overview
|
||||
GET /api/v1/dashboard/ceo
|
||||
|
||||
# Response includes:
|
||||
# - health_status: [{team, status, active_tasks, blocked_tasks, ...}]
|
||||
# - key_metrics: {velocity_weekly, completion_rate, doc_coverage, blockers}
|
||||
# - auditor_alerts: {urgent_count, warning_count, last_report_at}
|
||||
# - roadmap_progress: {current_quarter_progress, priority_totals}
|
||||
```
|
||||
|
||||
## Next Steps (Phase 6: Polish)
|
||||
Per HOMELAB_TEAM_V0.md section 13.8:
|
||||
- [ ] Performance optimization
|
||||
- [ ] Comprehensive documentation
|
||||
- [ ] Test coverage
|
||||
- [ ] Error handling improvements
|
||||
- [ ] Logging and observability
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 5 management complete. Task API provides full CRUD with lifecycle transitions. Kanban service generates role-specific boards with swimlane support. Metrics service tracks velocity, blockers, and agent performance. Auditor dashboard provides live feeds, flags, and reporting. CEO overview aggregates health status, metrics, and roadmap progress. Ready for Phase 6 polish.
|
||||
@@ -0,0 +1,200 @@
|
||||
# TASK-001: Phase 6 - Polish
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 6 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.8):
|
||||
- Error handling improvements with custom exceptions
|
||||
- Structured logging throughout with correlation IDs
|
||||
- Database migrations with Alembic
|
||||
- Middleware for request tracking and error handling
|
||||
- Code quality and consistency
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Comprehensive error handling with custom exceptions
|
||||
- [x] Structured logging with correlation IDs
|
||||
- [x] Alembic migration for all tables
|
||||
- [x] Request/response logging middleware
|
||||
- [x] Error handling middleware with structured responses
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Custom Exceptions (`src/roboco/exceptions.py`)
|
||||
|
||||
| Exception | Description |
|
||||
|-----------|-------------|
|
||||
| `RobocoError` | Base exception with code, message, details |
|
||||
| `NotFoundError` | Resource not found (404) |
|
||||
| `AlreadyExistsError` | Resource already exists (409) |
|
||||
| `ValidationError` | Input validation failed (422) |
|
||||
| `InvalidStateError` | Invalid state transition (409) |
|
||||
| `PermissionDeniedError` | No permission for action (403) |
|
||||
| `AuthenticationError` | Authentication required (401) |
|
||||
| `TaskError` | Base task error |
|
||||
| `TaskLifecycleError` | Invalid task state transition |
|
||||
| `TaskBlockedError` | Task blocked by dependencies |
|
||||
| `TaskClaimError` | Cannot claim task |
|
||||
| `AgentError` | Base agent error |
|
||||
| `AgentNotAvailableError` | Agent offline/unavailable |
|
||||
| `AgentBusyError` | Agent working on another task |
|
||||
| `ChannelError` | Base channel error |
|
||||
| `ChannelAccessDeniedError` | No access to channel |
|
||||
| `SessionClosedError` | Session is closed |
|
||||
| `NotificationError` | Notification failed |
|
||||
| `NotificationPermissionError` | Cannot send notifications |
|
||||
| `ServiceError` | External service error |
|
||||
| `DatabaseError` | Database operation failed |
|
||||
| `LLMError` | LLM service error |
|
||||
| `RAGError` | RAG service error |
|
||||
|
||||
All exceptions include:
|
||||
- `code`: Machine-readable error code
|
||||
- `message`: Human-readable description
|
||||
- `details`: Additional context dict
|
||||
- `to_dict()`: Convert to API response format
|
||||
|
||||
### 2. Middleware (`src/roboco/api/middleware.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `CorrelationIdMiddleware` | Adds X-Correlation-ID to requests/responses |
|
||||
| `RequestLoggingMiddleware` | Logs request/response with timing |
|
||||
| `roboco_exception_handler` | Handles RobocoError exceptions |
|
||||
| `generic_exception_handler` | Handles unexpected exceptions |
|
||||
| `setup_middleware(app)` | Setup function for app |
|
||||
|
||||
Features:
|
||||
- Correlation ID from header or auto-generated
|
||||
- Stored in request.state.correlation_id
|
||||
- Bound to structlog context
|
||||
- Added to all error responses
|
||||
- Request timing in X-Response-Time-Ms header
|
||||
|
||||
### 3. Logging Configuration (`src/roboco/logging.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `setup_logging()` | Configure structlog |
|
||||
| `get_logger(name)` | Get structured logger |
|
||||
| `LogContext` | Context manager for temp log context |
|
||||
| `log_operation()` | Create structured log context |
|
||||
|
||||
Features:
|
||||
- Development: Colored console output
|
||||
- Production: JSON output for log aggregation
|
||||
- Consistent format across all modules
|
||||
- Context variables for correlation
|
||||
- App context (version, environment) in all logs
|
||||
|
||||
### 4. Alembic Migration (`alembic/versions/001_initial_schema.py`)
|
||||
|
||||
Creates all tables:
|
||||
- agents
|
||||
- tasks
|
||||
- channels
|
||||
- groups
|
||||
- sessions
|
||||
- messages
|
||||
- notifications
|
||||
- journals
|
||||
- journal_entries
|
||||
- handoffs
|
||||
|
||||
With:
|
||||
- Proper foreign key relationships
|
||||
- Enum types for status/role fields
|
||||
- ARRAY columns for lists
|
||||
- JSON columns for structured data
|
||||
- Performance indexes for common queries
|
||||
|
||||
### 5. Updated Application (`src/roboco/api/app.py`)
|
||||
|
||||
- Logging setup at import time
|
||||
- Startup/shutdown logging
|
||||
- Middleware integration
|
||||
- Error handler registration
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/
|
||||
├── __init__.py # Updated with core exports
|
||||
├── exceptions.py # NEW - Custom exception hierarchy
|
||||
├── logging.py # NEW - Structured logging config
|
||||
├── api/
|
||||
│ ├── app.py # Updated with middleware
|
||||
│ └── middleware.py # NEW - Request/error middleware
|
||||
└── alembic/versions/
|
||||
└── 001_initial_schema.py # NEW - Initial migration
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Raising Exceptions
|
||||
```python
|
||||
from roboco.exceptions import NotFoundError, TaskLifecycleError
|
||||
|
||||
# Resource not found
|
||||
raise NotFoundError("Task", task_id)
|
||||
|
||||
# Invalid state transition
|
||||
raise TaskLifecycleError(
|
||||
task_id=task.id,
|
||||
current_status=task.status.value,
|
||||
target_status="in_progress",
|
||||
)
|
||||
```
|
||||
|
||||
### Structured Logging
|
||||
```python
|
||||
from roboco.logging import get_logger, LogContext, log_operation
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
# Basic logging
|
||||
logger.info("Task created", task_id=str(task.id), title=task.title)
|
||||
|
||||
# With context
|
||||
with LogContext(task_id=str(task.id), agent_id=str(agent.id)):
|
||||
logger.info("Processing task")
|
||||
# All logs in this block have task_id and agent_id
|
||||
|
||||
# Operation logging
|
||||
logger.info("Task updated", **log_operation("update", "task", str(task.id)))
|
||||
```
|
||||
|
||||
### Running Migrations
|
||||
```bash
|
||||
# Create migration
|
||||
alembic revision --autogenerate -m "description"
|
||||
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Rollback
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
## API Error Response Format
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "NOT_FOUND",
|
||||
"message": "Task not found: 123e4567-e89b-12d3-a456-426614174000",
|
||||
"details": {
|
||||
"resource_type": "Task",
|
||||
"resource_id": "123e4567-e89b-12d3-a456-426614174000",
|
||||
"correlation_id": "abc123..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 6 polish complete. Custom exception hierarchy with 20+ exception types for proper error handling. Structured logging with correlation IDs for request tracing. Middleware for request logging and error handling. Alembic migration with all 10 tables, proper relationships and indexes. All phases (1-6) of the RoboCo system are now implemented.
|
||||
@@ -0,0 +1,116 @@
|
||||
# TASK-001: Phase 1 - Core Services
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 1 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint:
|
||||
- Database schema
|
||||
- Messaging API
|
||||
- Agent framework
|
||||
- Infrastructure setup
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Database schema designed and implemented
|
||||
- [x] Messaging API (REST) functional
|
||||
- [x] Agent base class created
|
||||
- [x] Simple orchestrator built
|
||||
- [x] PostgreSQL configured
|
||||
- [x] Redis configured
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Project Configuration
|
||||
- `pyproject.toml` - Dependencies, ruff, mypy, pytest config
|
||||
- `docker-compose.yml` - PostgreSQL, Redis, Qdrant
|
||||
- `.env.example` - Environment template
|
||||
- `alembic/` - Migration setup
|
||||
|
||||
### 2. Data Models (`src/roboco/models/`)
|
||||
| File | Models |
|
||||
|------|--------|
|
||||
| `base.py` | All enums (TaskStatus, AgentRole, Team, etc.) |
|
||||
| `task.py` | Task, TaskPlan, Checkpoint, CommitRef |
|
||||
| `agent.py` | Agent, ModelConfig, AgentPermissions |
|
||||
| `session.py` | Session, SessionConfig |
|
||||
| `message.py` | ExtractedMessage, RawStream |
|
||||
| `group.py` | Group |
|
||||
| `channel.py` | Channel |
|
||||
| `notification.py` | Notification |
|
||||
| `journal.py` | Journal, JournalEntry |
|
||||
| `handoff.py` | DocumenterHandoff |
|
||||
|
||||
### 3. Database Layer (`src/roboco/db/`)
|
||||
- `base.py` - Async SQLAlchemy engine, session factory
|
||||
- `tables.py` - All ORM table definitions (10 tables)
|
||||
|
||||
### 4. Configuration (`src/roboco/config.py`)
|
||||
- Environment-based settings via pydantic-settings
|
||||
- Database, Redis, Qdrant, LLM provider configs
|
||||
|
||||
### 5. Messaging API (`src/roboco/api/`)
|
||||
| Route | Endpoints |
|
||||
|-------|-----------|
|
||||
| `health.py` | `/health`, `/ready` |
|
||||
| `channels.py` | CRUD for channels, member management |
|
||||
| `sessions.py` | Session lifecycle |
|
||||
| `messages.py` | Send, edit, delete messages |
|
||||
| `notifications.py` | Send, list, acknowledge |
|
||||
|
||||
### 6. WebSocket (`src/roboco/api/websocket.py`)
|
||||
- `/ws/channels/{id}` - Channel stream
|
||||
- `/ws/agents/{id}` - Agent output stream
|
||||
- `/ws/sessions/{id}` - Session stream
|
||||
- ConnectionManager for broadcasting
|
||||
|
||||
### 7. Agent Framework (`src/roboco/agents/`)
|
||||
- `base.py` - Agent base class with lifecycle, LLM stubs
|
||||
- `orchestrator.py` - Spawn/stop agents, health monitoring
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/
|
||||
├── __init__.py
|
||||
├── config.py
|
||||
├── models/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py, task.py, agent.py, session.py
|
||||
│ ├── message.py, group.py, channel.py
|
||||
│ ├── notification.py, journal.py, handoff.py
|
||||
│ └── README.md
|
||||
├── db/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py
|
||||
│ └── tables.py
|
||||
├── api/
|
||||
│ ├── __init__.py
|
||||
│ ├── app.py
|
||||
│ ├── deps.py
|
||||
│ ├── websocket.py
|
||||
│ └── routes/
|
||||
│ ├── __init__.py
|
||||
│ ├── health.py
|
||||
│ ├── channels.py
|
||||
│ ├── sessions.py
|
||||
│ ├── messages.py
|
||||
│ └── notifications.py
|
||||
└── agents/
|
||||
├── __init__.py
|
||||
├── base.py
|
||||
└── orchestrator.py
|
||||
```
|
||||
|
||||
## Next Steps (Phase 2: Communication)
|
||||
Per HOMELAB_TEAM_V0.md section 13.4:
|
||||
- [ ] Transcription service (extract messages from LLM streams)
|
||||
- [ ] Message extraction pipeline
|
||||
- [ ] Permission system
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 1 core services complete. Database schema, Messaging API, and Agent framework are functional. WebSocket streaming is in place. Ready for Phase 2 which adds transcription/extraction pipelines to process agent LLM output into structured messages.
|
||||
@@ -0,0 +1,119 @@
|
||||
# TASK-002: Phase 2 - Communication Services
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 2 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.4):
|
||||
- Transcription service (process LLM stream output)
|
||||
- Message extraction pipeline (identify message types)
|
||||
- Permission system (communication matrix enforcement)
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Transcription service buffers LLM stream chunks
|
||||
- [x] Extraction pipeline classifies messages (reasoning, dialogue, decision, action, blocker, technical)
|
||||
- [x] Permission service enforces channel read/write access
|
||||
- [x] Permission service enforces notification permissions
|
||||
- [x] Permission service enforces communication matrix
|
||||
- [x] API routes for stream processing
|
||||
- [x] API routes for permission checks
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Transcription Service (`src/roboco/services/transcription.py`)
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `StreamBuffer` | Accumulates chunks from agent, tracks timing, detects readiness |
|
||||
| `TranscriptionConfig` | Configurable thresholds (min chars, max chars, idle timeout) |
|
||||
| `TranscriptionService` | Main service with lifecycle, buffering, periodic flush |
|
||||
|
||||
Key features:
|
||||
- Buffers raw LLM output by agent/session
|
||||
- Detects segment boundaries (sentences, pauses, max length)
|
||||
- Background task for periodic buffer checking
|
||||
- Callback registration for ready segments
|
||||
|
||||
### 2. Extraction Service (`src/roboco/services/extraction.py`)
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| Pattern matchers | Regex patterns for each MessageType |
|
||||
| `ExtractionResult` | Container for extracted messages with metadata |
|
||||
| `ExtractionConfig` | Configurable extraction settings |
|
||||
| `ExtractionService` | Pattern-based message classification |
|
||||
| `ExtractionPipeline` | End-to-end processing with callbacks |
|
||||
|
||||
Message types detected:
|
||||
- **REASONING**: "I'm thinking...", "Let me analyze..."
|
||||
- **DIALOGUE**: Questions, @mentions, conversations
|
||||
- **DECISION**: "I've decided...", "Going with..."
|
||||
- **ACTION**: "Starting...", "Committing...", "Done:"
|
||||
- **BLOCKER**: "Blocked:", "Waiting on...", "Error:"
|
||||
- **TECHNICAL**: Code blocks, API explanations
|
||||
|
||||
### 3. Permission Service (`src/roboco/services/permissions.py`)
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `PermissionLevel` | Hierarchy levels (CEO → Board → Main PM → Cell PM → Member) |
|
||||
| `ChannelPermission` | Defines read/write access per channel |
|
||||
| `COMMUNICATION_MATRIX` | Who can communicate with whom |
|
||||
| `NOTIFICATION_TARGETS` | Who can notify whom |
|
||||
| `TASK_PERMISSIONS` | Task actions by role |
|
||||
| `PermissionService` | Main service for all permission checks |
|
||||
|
||||
Channel permissions implemented:
|
||||
- Cell channels (backend-cell, frontend-cell, uxui-cell)
|
||||
- Cross-cell channels (dev-all, qa-all, pm-all, doc-all)
|
||||
- Management channels (main-pm-board, board-private)
|
||||
- Special channels (announcements, all-hands)
|
||||
|
||||
Auditor has silent read access to all channels.
|
||||
|
||||
### 4. API Integration
|
||||
|
||||
#### New Dependencies (`src/roboco/api/deps.py`)
|
||||
- `PermissionServiceDep` - Injects permission service
|
||||
- `CurrentAgentContext` - Full agent context from headers
|
||||
- `require_channel_read()` - Dependency factory for channel read checks
|
||||
- `require_channel_write()` - Dependency factory for channel write checks
|
||||
- `require_notification_permission()` - Dependency for notification checks
|
||||
|
||||
#### New Routes (`src/roboco/api/routes/stream.py`)
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/v1/stream/chunk` | POST | Process a stream chunk |
|
||||
| `/api/v1/stream/complete` | POST | Mark stream complete, get content |
|
||||
| `/api/v1/stream/extract` | POST | Extract messages from content |
|
||||
| `/api/v1/stream/stats` | GET | Transcription service stats |
|
||||
| `/api/v1/stream/permissions` | GET | Get agent's permission summary |
|
||||
| `/api/v1/stream/permissions/channel/{name}` | GET | Check specific channel access |
|
||||
|
||||
#### App Integration (`src/roboco/api/app.py`)
|
||||
- Services initialized in lifespan context
|
||||
- `app.state.transcription` - Global transcription service
|
||||
- `app.state.extraction` - Global extraction pipeline
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/services/
|
||||
├── __init__.py # Service exports
|
||||
├── transcription.py # StreamBuffer, TranscriptionService
|
||||
├── extraction.py # ExtractionService, ExtractionPipeline
|
||||
└── permissions.py # PermissionService, matrices
|
||||
```
|
||||
|
||||
## Next Steps (Phase 3: Intelligence)
|
||||
Per HOMELAB_TEAM_V0.md section 13.5:
|
||||
- [ ] Setup Qdrant on NAS
|
||||
- [ ] Build embedding pipeline
|
||||
- [ ] Implement Optimal API (RAG queries)
|
||||
- [ ] Implement Journal API
|
||||
- [ ] Index existing repositories
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 2 communication services complete. Transcription buffers LLM streams, extraction classifies message types, and permissions enforce the communication matrix from the blueprint. All services are integrated with the FastAPI application and accessible via `/api/v1/stream/*` endpoints. Ready for Phase 3 which adds RAG/knowledge base capabilities.
|
||||
@@ -0,0 +1,175 @@
|
||||
# TASK-003: Phase 3 - Intelligence Services
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 3 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.5):
|
||||
- RAG system using piragi with PostgreSQL/pgvector
|
||||
- Optimal API for knowledge base queries
|
||||
- Journal API for agent personal logs
|
||||
- Embedding pipeline integration
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] pgvector enabled in PostgreSQL (docker-compose updated)
|
||||
- [x] piragi[postgres] added as dependency
|
||||
- [x] Optimal API service with piragi
|
||||
- [x] Journal API service
|
||||
- [x] API routes for knowledge base operations
|
||||
- [x] API routes for journal operations
|
||||
- [x] Integration with existing extraction pipeline
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Infrastructure Changes
|
||||
|
||||
#### Docker Compose (`docker-compose.yml`)
|
||||
- Changed PostgreSQL image from `postgres:16-alpine` to `pgvector/pgvector:pg16`
|
||||
- Removed Qdrant container (replaced by pgvector)
|
||||
- Removed `qdrant_data` volume
|
||||
|
||||
#### Dependencies (`pyproject.toml`)
|
||||
- Replaced `qdrant-client>=1.7.0` with `piragi[postgres]>=0.1.0`
|
||||
- Updated mypy overrides for piragi
|
||||
|
||||
### 2. Configuration (`src/roboco/config.py`)
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| `rag_persist_dir` | `.piragi` | Directory for piragi index data |
|
||||
| `rag_chunk_strategy` | `semantic` | Chunking: fixed, semantic, hierarchical, contextual |
|
||||
| `rag_chunk_size` | 512 | Characters per chunk |
|
||||
| `rag_chunk_overlap` | 50 | Overlap between chunks |
|
||||
| `rag_use_hyde` | True | Hypothetical document embeddings |
|
||||
| `rag_use_hybrid_search` | True | BM25 + vector hybrid search |
|
||||
| `rag_use_cross_encoder` | False | Neural reranking (slower) |
|
||||
| `rag_auto_update_enabled` | True | Background index updates |
|
||||
| `rag_auto_update_interval` | 300 | Seconds between updates |
|
||||
| `rag_store_url` | computed | PostgreSQL connection for piragi |
|
||||
|
||||
### 3. Optimal API Service (`src/roboco/services/optimal.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `IndexType` | Enum: CODE, DOCUMENTATION, CONVERSATIONS, JOURNALS |
|
||||
| `SearchResult` | Single search result with content, source, score |
|
||||
| `RAGResponse` | Answer with citations |
|
||||
| `QueryContext` | Filters: project, task_id, agent_id, index_types |
|
||||
| `OptimalService` | Main service using AsyncRagi |
|
||||
|
||||
Key features:
|
||||
- Multiple indexes for different content types
|
||||
- Async initialization and cleanup
|
||||
- Code indexing (files, directories, globs)
|
||||
- Documentation indexing (markdown, URLs, crawling)
|
||||
- Conversation indexing (from extraction pipeline)
|
||||
- Journal entry indexing (automatic on creation)
|
||||
- Semantic search across all indexes
|
||||
- RAG queries with citations
|
||||
- HyDE and hybrid search enabled by default
|
||||
|
||||
### 4. Journal API Service (`src/roboco/services/journal.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `JournalStats` | Entry counts, timestamps, summary status |
|
||||
| `GrowthMetrics` | Learning frequency, resolution rates, trends |
|
||||
| `JournalService` | Full CRUD for journals and entries |
|
||||
|
||||
Key features:
|
||||
- Get or create journal per agent
|
||||
- Create entries with automatic RAG indexing
|
||||
- Convenience methods for entry types:
|
||||
- Task reflections
|
||||
- Decision logs
|
||||
- Learning entries
|
||||
- Struggle entries
|
||||
- General notes
|
||||
- List entries with filtering (type, task, privacy)
|
||||
- Journal statistics
|
||||
- Growth metrics calculation
|
||||
- Semantic search through entries
|
||||
|
||||
### 5. API Routes
|
||||
|
||||
#### Optimal API (`src/roboco/api/routes/optimal.py`)
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/v1/optimal/kb/index/code` | POST | Index code files |
|
||||
| `/api/v1/optimal/kb/index/docs` | POST | Index documentation |
|
||||
| `/api/v1/optimal/kb/search` | POST | Semantic search |
|
||||
| `/api/v1/optimal/kb/similar` | GET | Find similar documents |
|
||||
| `/api/v1/optimal/rag/query` | POST | RAG query with answer |
|
||||
| `/api/v1/optimal/rag/context` | POST | Get context without answer |
|
||||
| `/api/v1/optimal/stats` | GET | Index statistics |
|
||||
| `/api/v1/optimal/kb/{type}` | DELETE | Clear an index |
|
||||
| `/api/v1/optimal/kb/refresh` | POST | Refresh index sources |
|
||||
|
||||
#### Journal API (`src/roboco/api/routes/journals.py`)
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/v1/journals/me` | GET | Get my journal |
|
||||
| `/api/v1/journals/{agent_id}` | GET | Get journal by agent |
|
||||
| `/api/v1/journals/me/entries` | GET | List my entries |
|
||||
| `/api/v1/journals/me/entries` | POST | Create entry |
|
||||
| `/api/v1/journals/entries/{id}` | GET | Get entry |
|
||||
| `/api/v1/journals/entries/{id}` | DELETE | Delete entry |
|
||||
| `/api/v1/journals/me/reflections` | POST | Add task reflection |
|
||||
| `/api/v1/journals/me/decisions` | POST | Add decision log |
|
||||
| `/api/v1/journals/me/learnings` | POST | Add learning |
|
||||
| `/api/v1/journals/me/struggles` | POST | Add struggle |
|
||||
| `/api/v1/journals/me/notes` | POST | Add general note |
|
||||
| `/api/v1/journals/me/stats` | GET | Get journal stats |
|
||||
| `/api/v1/journals/me/growth` | GET | Get growth metrics |
|
||||
| `/api/v1/journals/me/search` | POST | Semantic search entries |
|
||||
|
||||
### 6. App Integration (`src/roboco/api/app.py`)
|
||||
- OptimalService initialized in lifespan
|
||||
- Stored in `app.state.optimal`
|
||||
- Proper cleanup on shutdown
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/services/
|
||||
├── __init__.py # Updated with Phase 3 exports
|
||||
├── transcription.py # Phase 2
|
||||
├── extraction.py # Phase 2
|
||||
├── permissions.py # Phase 2
|
||||
├── optimal.py # NEW - RAG/Knowledge Base
|
||||
└── journal.py # NEW - Agent Journals
|
||||
|
||||
src/roboco/api/routes/
|
||||
├── __init__.py # Updated with new routes
|
||||
├── ... (Phase 1-2 routes)
|
||||
├── optimal.py # NEW - Optimal API endpoints
|
||||
└── journals.py # NEW - Journal API endpoints
|
||||
```
|
||||
|
||||
## Technology Choice: piragi
|
||||
|
||||
Selected piragi over Qdrant because:
|
||||
1. **Simpler stack** - Uses existing PostgreSQL with pgvector extension
|
||||
2. **Zero config** - Works with local models out of the box
|
||||
3. **Advanced retrieval** - Built-in HyDE, hybrid search, cross-encoder reranking
|
||||
4. **Async support** - AsyncRagi for FastAPI integration
|
||||
5. **Multiple sources** - Files, directories, URLs, globs, web crawling
|
||||
6. **Auto-updates** - Background refresh without blocking queries
|
||||
|
||||
## Next Steps (Phase 4: Agents)
|
||||
Per HOMELAB_TEAM_V0.md section 13.6:
|
||||
- [ ] Define agent prompts per role
|
||||
- [ ] Implement Dev workflow
|
||||
- [ ] Implement QA workflow
|
||||
- [ ] Implement Documenter workflow
|
||||
- [ ] Implement PM workflows
|
||||
- [ ] Deploy Backend cell
|
||||
- [ ] Deploy Frontend cell
|
||||
- [ ] Deploy UX/UI cell
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 3 intelligence services complete. Using piragi with pgvector for RAG instead of Qdrant - simpler stack, same functionality. Optimal API provides knowledge base indexing and queries. Journal API provides agent personal logs with automatic RAG indexing. All entries are searchable via semantic search. Ready for Phase 4 which implements the actual agent workflows.
|
||||
@@ -0,0 +1,215 @@
|
||||
# TASK-004: Phase 4 - Agents
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 4 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.6):
|
||||
- Define all 17 agent types with role-specific workflows
|
||||
- Implement the task lifecycle for each role
|
||||
- Create cell deployment infrastructure
|
||||
- Enable 3 functioning cells + Board
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Developer workflow implemented (SCAN → CLAIM → UNDERSTAND → PLAN → EXECUTE → VERIFY → NOTES → CLOSE)
|
||||
- [x] QA workflow implemented (MONITOR → RECEIVE → UNDERSTAND → TEST → VERDICT → DOCUMENT → RETURN)
|
||||
- [x] Documenter workflow implemented (MONITOR → RECEIVE → GATHER → SYNTHESIZE → WRITE → REVIEW → PUBLISH)
|
||||
- [x] Cell PM workflow implemented (MONITOR → TRIAGE → ASSIGN → FACILITATE → ESCALATE → TRACK → REPORT)
|
||||
- [x] Main PM workflow implemented (OVERSEE → RECEIVE → PRIORITIZE → COORDINATE → DISTRIBUTE → REPORT UP → FACILITATE)
|
||||
- [x] Board workflows implemented (Product Owner, Head of Marketing, Auditor)
|
||||
- [x] Cell factory and deployment system
|
||||
- [x] Organization factory for complete deployment
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Developer Agent (`src/roboco/agents/developer.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `DevTaskPhase` | Enum: SCAN, CLAIM, UNDERSTAND, PLAN, EXECUTE, VERIFY, NOTES, CLOSE, BLOCKED |
|
||||
| `TaskContext` | Dataclass tracking current task state, subtasks, commits, journal |
|
||||
| `DeveloperAgent` | Full lifecycle implementation with LLM integration |
|
||||
|
||||
Key features:
|
||||
- Phase-based task execution
|
||||
- Subtask breakdown and tracking
|
||||
- Quality checks (ruff, mypy, pytest)
|
||||
- Journal entries at each phase
|
||||
- Handoff creation for documenter
|
||||
- Factory functions for BE/FE/UX developers
|
||||
|
||||
### 2. QA Agent (`src/roboco/agents/qa.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `QATaskPhase` | Enum: MONITOR, RECEIVE, UNDERSTAND, TEST, VERDICT, DOCUMENT, RETURN |
|
||||
| `TestCase` | Dataclass for test execution and results |
|
||||
| `ReviewContext` | Dataclass tracking review state |
|
||||
| `QAAgent` | Full review lifecycle implementation |
|
||||
|
||||
Key features:
|
||||
- Test case generation from requirements
|
||||
- Automated test execution
|
||||
- Clear PASS/FAIL verdicts
|
||||
- Specific feedback for failures
|
||||
- QA report generation
|
||||
|
||||
### 3. Documenter Agent (`src/roboco/agents/documenter.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `DocTaskPhase` | Enum: MONITOR, RECEIVE, GATHER, SYNTHESIZE, WRITE, REVIEW, PUBLISH |
|
||||
| `DocType` | Enum: API, README, ARCHITECTURE, CHANGELOG, etc. |
|
||||
| `DocumentSpec` | Dataclass for document specifications |
|
||||
| `DocumenterAgent` | Full documentation lifecycle |
|
||||
|
||||
Key features:
|
||||
- Material gathering (notes, commits, conversations)
|
||||
- Synthesis of what was built
|
||||
- Automatic document type detection
|
||||
- Self-review before publish
|
||||
- Factory functions for all cells
|
||||
|
||||
### 4. PM Agents (`src/roboco/agents/pm.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `CellPMPhase` | Enum: MONITOR, TRIAGE, ASSIGN, FACILITATE, ESCALATE, TRACK, REPORT |
|
||||
| `MainPMPhase` | Enum: OVERSEE, RECEIVE, PRIORITIZE, COORDINATE, DISTRIBUTE, REPORT_UP, FACILITATE |
|
||||
| `CellPMAgent` | Cell-level management |
|
||||
| `MainPMAgent` | Organization-level coordination |
|
||||
|
||||
Key features:
|
||||
- Continuous duty cycles (never complete)
|
||||
- Task prioritization and assignment
|
||||
- Blocker facilitation
|
||||
- Escalation handling
|
||||
- Status reporting
|
||||
- Cross-cell coordination (Main PM)
|
||||
|
||||
### 5. Board Agents (`src/roboco/agents/board.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `ProductOwnerAgent` | Vision, roadmap, requirements, acceptance |
|
||||
| `HeadMarketingAgent` | Research, strategy, campaigns, analytics |
|
||||
| `AuditorAgent` | Silent observation, analysis, CEO reporting |
|
||||
|
||||
Auditor special powers:
|
||||
- Read ALL channels silently
|
||||
- Query all task history
|
||||
- Access all commits, docs, notes
|
||||
- Direct line to CEO
|
||||
- Can notify anyone (sparingly)
|
||||
|
||||
### 6. Factory and Deployment (`src/roboco/agents/factory.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `Cell` | Complete cell with PM, Devs, QA, Documenter |
|
||||
| `Board` | Product Owner, Head of Marketing, Auditor |
|
||||
| `Organization` | Complete 18-agent organization |
|
||||
|
||||
Factory functions:
|
||||
- `create_backend_cell()` - 5 agents
|
||||
- `create_frontend_cell()` - 5 agents
|
||||
- `create_ux_cell()` - 4 agents
|
||||
- `create_board()` - 3 agents
|
||||
- `create_organization()` - Complete deployment
|
||||
|
||||
Utility functions:
|
||||
- `get_agent_roster()` - List all agents without instantiation
|
||||
- `print_org_chart()` - Text-based org visualization
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/agents/
|
||||
├── __init__.py # Updated with all exports
|
||||
├── base.py # Phase 1 - Base Agent class
|
||||
├── orchestrator.py # Phase 1 - Agent orchestration
|
||||
├── developer.py # NEW - Developer lifecycle
|
||||
├── qa.py # NEW - QA lifecycle
|
||||
├── documenter.py # NEW - Documenter lifecycle
|
||||
├── pm.py # NEW - Cell PM and Main PM
|
||||
├── board.py # NEW - Product Owner, Marketing, Auditor
|
||||
└── factory.py # NEW - Cell and Organization factories
|
||||
```
|
||||
|
||||
## Agent Count
|
||||
|
||||
| Level | Count | Agents |
|
||||
|-------|-------|--------|
|
||||
| Executive | 1 | CEO (Human) |
|
||||
| Board | 3 | Product Owner, Head of Marketing, Auditor |
|
||||
| Management | 1 | Main PM |
|
||||
| Backend Cell | 5 | PM, 2 Devs, QA, Documenter |
|
||||
| Frontend Cell | 5 | PM, 2 Devs, QA, Documenter |
|
||||
| UX/UI Cell | 4 | PM, 1 Dev, QA, Documenter |
|
||||
| **Total** | **19** | 18 AI + 1 Human CEO |
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
### Developer Lifecycle
|
||||
```
|
||||
SCAN → CLAIM → UNDERSTAND → PLAN → EXECUTE → VERIFY → NOTES → CLOSE
|
||||
│ │ │
|
||||
└─────── BLOCKED ───────────┴────────┘
|
||||
```
|
||||
|
||||
### QA Lifecycle
|
||||
```
|
||||
MONITOR → RECEIVE → UNDERSTAND → TEST → VERDICT → DOCUMENT → RETURN
|
||||
│
|
||||
PASS ─┴─ FAIL
|
||||
```
|
||||
|
||||
### Documenter Lifecycle
|
||||
```
|
||||
MONITOR → RECEIVE → GATHER → SYNTHESIZE → WRITE → REVIEW → PUBLISH
|
||||
```
|
||||
|
||||
### Cell PM Lifecycle (Continuous)
|
||||
```
|
||||
MONITOR → TRIAGE → ASSIGN → FACILITATE → ESCALATE → TRACK → REPORT
|
||||
▲ │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Usage Example
|
||||
|
||||
```python
|
||||
from roboco.agents import create_organization
|
||||
|
||||
# Create complete organization
|
||||
org = create_organization()
|
||||
|
||||
# Start all agents
|
||||
await org.start_all()
|
||||
|
||||
# Access specific agents
|
||||
be_dev = org.get_agent_by_slug("be-dev-1")
|
||||
auditor = org.board.auditor
|
||||
|
||||
# Get cell status
|
||||
backend_agents = org.get_agents_by_team(Team.BACKEND)
|
||||
|
||||
# Stop all agents
|
||||
await org.stop_all()
|
||||
```
|
||||
|
||||
## Next Steps (Phase 5: Management)
|
||||
Per HOMELAB_TEAM_V0.md section 13.7:
|
||||
- [ ] Build Kanban interfaces
|
||||
- [ ] Create Auditor dashboard
|
||||
- [ ] Create CEO overview
|
||||
- [ ] Implement metrics collection
|
||||
- [ ] Build reporting system
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 4 agents complete. All 17 agent types implemented with role-specific workflows. Each agent follows its lifecycle from the blueprint (Section 7). Factory functions create complete cells and the full organization. Agents load system prompts from blueprint files in `agents/blueprints/`. Ready for Phase 5 which adds management UIs and dashboards.
|
||||
@@ -0,0 +1,222 @@
|
||||
# TASK-005: Phase 5 - Management
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 5 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.7):
|
||||
- Build Task API for task CRUD and status management
|
||||
- Create Kanban service with role-specific board views
|
||||
- Implement metrics collection and reporting
|
||||
- Build Auditor dashboard API
|
||||
- Build CEO overview API
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Task API with full CRUD operations
|
||||
- [x] Task service with status transitions and lifecycle management
|
||||
- [x] Kanban service with board views for each role
|
||||
- [x] Dev Kanban: Backlog → Assigned → In Progress → QA Review → Documenting → Done
|
||||
- [x] QA Kanban: Awaiting Review → In Review → Passed → Failed
|
||||
- [x] Documenter Kanban: Awaiting Handoff → Gathering → Writing → Published
|
||||
- [x] PM Kanban: Incoming → Triaged → Assigned → In Progress → Blocked → Done
|
||||
- [x] Main PM Kanban: Cross-cell view with Backend/Frontend/UX columns
|
||||
- [x] Board Kanban: Ideas → Roadmap → In Development → Released
|
||||
- [x] Metrics collection (velocity, blockers, completion rate)
|
||||
- [x] Auditor dashboard API (live feeds, flagged items, metrics, reports)
|
||||
- [x] CEO overview API (health status, key metrics, auditor alerts, roadmap progress)
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Task Service (`src/roboco/services/task.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `TaskService` | Full CRUD operations for tasks |
|
||||
| Status transitions | claim, start, block, unblock, pause, resume, verify, submit_for_qa, pass_qa, fail_qa, complete, cancel |
|
||||
| Progress tracking | add_progress, add_checkpoint, add_commit |
|
||||
| Queries | list_all, list_by_team, list_by_assignee, list_by_status, list_pending, list_blocked, list_awaiting_qa, list_awaiting_docs |
|
||||
| Statistics | count_by_status, count_by_team, get_active_count |
|
||||
|
||||
### 2. Task API Routes (`src/roboco/api/routes/tasks.py`)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET/POST /tasks` | List and create tasks |
|
||||
| `GET/PUT/DELETE /tasks/{id}` | Task CRUD |
|
||||
| `GET /tasks/my` | Get agent's tasks |
|
||||
| `GET /tasks/pending, /blocked, /awaiting-qa, /awaiting-docs` | Status-based lists |
|
||||
| `GET /tasks/team/{team}` | Team tasks |
|
||||
| `GET /tasks/stats` | Task statistics |
|
||||
| `POST /tasks/{id}/claim, /start, /block, /unblock, /pause, /resume` | Lifecycle transitions |
|
||||
| `POST /tasks/{id}/verify, /submit-qa, /pass-qa, /fail-qa, /complete, /cancel` | Review transitions |
|
||||
| `POST /tasks/{id}/progress, /checkpoint, /commit` | Progress and artifacts |
|
||||
|
||||
### 3. Kanban Models (`src/roboco/models/kanban.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `KanbanBoardType` | Enum: DEV, QA, DOCUMENTER, PM, MAIN_PM, BOARD |
|
||||
| `KanbanCard` | Card representation with task data |
|
||||
| `KanbanColumn` | Column with cards and WIP limit |
|
||||
| `KanbanSwimlane` | Swimlane for grouping |
|
||||
| `KanbanBoard` | Complete board with columns or swimlanes |
|
||||
| Column configs | DEV_COLUMNS, QA_COLUMNS, DOCUMENTER_COLUMNS, PM_COLUMNS, MAIN_PM_COLUMNS, BOARD_COLUMNS |
|
||||
|
||||
### 4. Kanban Service (`src/roboco/services/kanban.py`)
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `get_dev_board(team, swimlane_by)` | Dev board with optional swimlanes |
|
||||
| `get_qa_board(team)` | QA review board |
|
||||
| `get_documenter_board(team)` | Documenter board |
|
||||
| `get_pm_board(team)` | Cell PM board |
|
||||
| `get_main_pm_board()` | Cross-cell Main PM board |
|
||||
| `get_main_pm_board_flat()` | Flat team-column view |
|
||||
| `get_board_kanban()` | Board-level roadmap |
|
||||
| `get_board_stats(team)` | Board statistics |
|
||||
|
||||
### 5. Kanban API Routes (`src/roboco/api/routes/kanban.py`)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /kanban/dev/{team}` | Dev board with swimlane option |
|
||||
| `GET /kanban/qa/{team}` | QA board |
|
||||
| `GET /kanban/documenter/{team}` | Documenter board |
|
||||
| `GET /kanban/pm/{team}` | Cell PM board |
|
||||
| `GET /kanban/main-pm` | Main PM cross-cell board |
|
||||
| `GET /kanban/board` | Board-level roadmap |
|
||||
| `GET /kanban/stats` | Board statistics |
|
||||
|
||||
### 6. Metrics Service (`src/roboco/services/metrics.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `VelocityMetrics` | Tasks completed, created, avg time, completion rate |
|
||||
| `BlockerMetrics` | Active blockers, avg time, longest blocked, by team |
|
||||
| `TeamMetrics` | Active/blocked/completed tasks, avg time, doc coverage |
|
||||
| `AgentMetrics` | Agent performance and activity |
|
||||
| `get_velocity(days, team)` | Velocity metrics |
|
||||
| `get_blocker_metrics()` | Blocker analysis |
|
||||
| `get_team_metrics(team)` | Team performance |
|
||||
| `get_agent_metrics(agent_id)` | Agent performance |
|
||||
| `get_communication_volume(hours)` | Message and notification counts |
|
||||
| `get_health_status(team)` | ok/slow/critical status |
|
||||
|
||||
### 7. Dashboard API Routes (`src/roboco/api/routes/dashboard.py`)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /dashboard/auditor` | Complete auditor dashboard |
|
||||
| `GET /dashboard/auditor/flags` | Auditor flags with filters |
|
||||
| `POST /dashboard/auditor/flags` | Create flag |
|
||||
| `PUT /dashboard/auditor/flags/{id}/resolve` | Resolve flag |
|
||||
| `GET /dashboard/auditor/reports` | Auditor reports |
|
||||
| `POST /dashboard/auditor/reports` | Create report |
|
||||
| `POST /dashboard/auditor/reports/{id}/send` | Send to CEO |
|
||||
| `GET /dashboard/ceo` | CEO overview |
|
||||
| `GET /dashboard/ceo/teams` | Team details |
|
||||
| `GET /dashboard/ceo/blockers` | Blocker details |
|
||||
| `GET /dashboard/ceo/velocity` | Velocity metrics |
|
||||
| `GET /dashboard/metrics/*` | Various metric endpoints |
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/
|
||||
├── models/
|
||||
│ └── kanban.py # NEW - Kanban board models
|
||||
├── services/
|
||||
│ ├── task.py # NEW - Task CRUD and lifecycle
|
||||
│ ├── kanban.py # NEW - Kanban board generation
|
||||
│ └── metrics.py # NEW - Metrics collection
|
||||
├── api/routes/
|
||||
│ ├── tasks.py # NEW - Task API
|
||||
│ ├── kanban.py # NEW - Kanban API
|
||||
│ └── dashboard.py # NEW - Dashboard API
|
||||
└── api/
|
||||
└── app.py # Updated with new routes
|
||||
```
|
||||
|
||||
## API Summary
|
||||
|
||||
### Task API
|
||||
- Full CRUD for tasks
|
||||
- Complete lifecycle management (claim → start → verify → qa → docs → complete)
|
||||
- Progress tracking and checkpoints
|
||||
- Commit linking
|
||||
|
||||
### Kanban API
|
||||
- 6 board types for different roles
|
||||
- Swimlane support (by priority, assignee)
|
||||
- Cross-cell views for Main PM
|
||||
- Roadmap view for Board
|
||||
|
||||
### Dashboard API
|
||||
- Auditor: Live feeds, flags, metrics, reports
|
||||
- CEO: Health status, metrics, alerts, roadmap
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Create and Track a Task
|
||||
```python
|
||||
# Create task
|
||||
POST /api/v1/tasks
|
||||
{
|
||||
"title": "Implement feature X",
|
||||
"description": "...",
|
||||
"acceptance_criteria": ["..."],
|
||||
"team": "backend",
|
||||
"priority": 1
|
||||
}
|
||||
|
||||
# Claim and start
|
||||
POST /api/v1/tasks/{id}/claim
|
||||
POST /api/v1/tasks/{id}/start
|
||||
|
||||
# Add progress
|
||||
POST /api/v1/tasks/{id}/progress
|
||||
{"message": "Completed first subtask", "percentage": 30}
|
||||
|
||||
# Submit for QA
|
||||
POST /api/v1/tasks/{id}/submit-qa
|
||||
```
|
||||
|
||||
### View Kanban Boards
|
||||
```python
|
||||
# Dev board with priority swimlanes
|
||||
GET /api/v1/kanban/dev/backend?swimlane_by=priority
|
||||
|
||||
# Main PM cross-cell view
|
||||
GET /api/v1/kanban/main-pm?flat=true
|
||||
|
||||
# Board-level roadmap
|
||||
GET /api/v1/kanban/board
|
||||
```
|
||||
|
||||
### CEO Overview
|
||||
```python
|
||||
# Get full overview
|
||||
GET /api/v1/dashboard/ceo
|
||||
|
||||
# Response includes:
|
||||
# - health_status: [{team, status, active_tasks, blocked_tasks, ...}]
|
||||
# - key_metrics: {velocity_weekly, completion_rate, doc_coverage, blockers}
|
||||
# - auditor_alerts: {urgent_count, warning_count, last_report_at}
|
||||
# - roadmap_progress: {current_quarter_progress, priority_totals}
|
||||
```
|
||||
|
||||
## Next Steps (Phase 6: Polish)
|
||||
Per HOMELAB_TEAM_V0.md section 13.8:
|
||||
- [ ] Performance optimization
|
||||
- [ ] Comprehensive documentation
|
||||
- [ ] Test coverage
|
||||
- [ ] Error handling improvements
|
||||
- [ ] Logging and observability
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 5 management complete. Task API provides full CRUD with lifecycle transitions. Kanban service generates role-specific boards with swimlane support. Metrics service tracks velocity, blockers, and agent performance. Auditor dashboard provides live feeds, flags, and reporting. CEO overview aggregates health status, metrics, and roadmap progress. Ready for Phase 6 polish.
|
||||
@@ -0,0 +1,200 @@
|
||||
# TASK-006: Phase 6 - Polish
|
||||
|
||||
## Status
|
||||
- **State**: completed
|
||||
- **Priority**: P0
|
||||
- **Cell**: board
|
||||
|
||||
## Dates
|
||||
- **Created**: 2025-12-09
|
||||
- **Completed**: 2025-12-09
|
||||
|
||||
## Overview
|
||||
Implement Phase 6 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.8):
|
||||
- Error handling improvements with custom exceptions
|
||||
- Structured logging throughout with correlation IDs
|
||||
- Database migrations with Alembic
|
||||
- Middleware for request tracking and error handling
|
||||
- Code quality and consistency
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Comprehensive error handling with custom exceptions
|
||||
- [x] Structured logging with correlation IDs
|
||||
- [x] Alembic migration for all tables
|
||||
- [x] Request/response logging middleware
|
||||
- [x] Error handling middleware with structured responses
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Custom Exceptions (`src/roboco/exceptions.py`)
|
||||
|
||||
| Exception | Description |
|
||||
|-----------|-------------|
|
||||
| `RobocoError` | Base exception with code, message, details |
|
||||
| `NotFoundError` | Resource not found (404) |
|
||||
| `AlreadyExistsError` | Resource already exists (409) |
|
||||
| `ValidationError` | Input validation failed (422) |
|
||||
| `InvalidStateError` | Invalid state transition (409) |
|
||||
| `PermissionDeniedError` | No permission for action (403) |
|
||||
| `AuthenticationError` | Authentication required (401) |
|
||||
| `TaskError` | Base task error |
|
||||
| `TaskLifecycleError` | Invalid task state transition |
|
||||
| `TaskBlockedError` | Task blocked by dependencies |
|
||||
| `TaskClaimError` | Cannot claim task |
|
||||
| `AgentError` | Base agent error |
|
||||
| `AgentNotAvailableError` | Agent offline/unavailable |
|
||||
| `AgentBusyError` | Agent working on another task |
|
||||
| `ChannelError` | Base channel error |
|
||||
| `ChannelAccessDeniedError` | No access to channel |
|
||||
| `SessionClosedError` | Session is closed |
|
||||
| `NotificationError` | Notification failed |
|
||||
| `NotificationPermissionError` | Cannot send notifications |
|
||||
| `ServiceError` | External service error |
|
||||
| `DatabaseError` | Database operation failed |
|
||||
| `LLMError` | LLM service error |
|
||||
| `RAGError` | RAG service error |
|
||||
|
||||
All exceptions include:
|
||||
- `code`: Machine-readable error code
|
||||
- `message`: Human-readable description
|
||||
- `details`: Additional context dict
|
||||
- `to_dict()`: Convert to API response format
|
||||
|
||||
### 2. Middleware (`src/roboco/api/middleware.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `CorrelationIdMiddleware` | Adds X-Correlation-ID to requests/responses |
|
||||
| `RequestLoggingMiddleware` | Logs request/response with timing |
|
||||
| `roboco_exception_handler` | Handles RobocoError exceptions |
|
||||
| `generic_exception_handler` | Handles unexpected exceptions |
|
||||
| `setup_middleware(app)` | Setup function for app |
|
||||
|
||||
Features:
|
||||
- Correlation ID from header or auto-generated
|
||||
- Stored in request.state.correlation_id
|
||||
- Bound to structlog context
|
||||
- Added to all error responses
|
||||
- Request timing in X-Response-Time-Ms header
|
||||
|
||||
### 3. Logging Configuration (`src/roboco/logging.py`)
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `setup_logging()` | Configure structlog |
|
||||
| `get_logger(name)` | Get structured logger |
|
||||
| `LogContext` | Context manager for temp log context |
|
||||
| `log_operation()` | Create structured log context |
|
||||
|
||||
Features:
|
||||
- Development: Colored console output
|
||||
- Production: JSON output for log aggregation
|
||||
- Consistent format across all modules
|
||||
- Context variables for correlation
|
||||
- App context (version, environment) in all logs
|
||||
|
||||
### 4. Alembic Migration (`alembic/versions/001_initial_schema.py`)
|
||||
|
||||
Creates all tables:
|
||||
- agents
|
||||
- tasks
|
||||
- channels
|
||||
- groups
|
||||
- sessions
|
||||
- messages
|
||||
- notifications
|
||||
- journals
|
||||
- journal_entries
|
||||
- handoffs
|
||||
|
||||
With:
|
||||
- Proper foreign key relationships
|
||||
- Enum types for status/role fields
|
||||
- ARRAY columns for lists
|
||||
- JSON columns for structured data
|
||||
- Performance indexes for common queries
|
||||
|
||||
### 5. Updated Application (`src/roboco/api/app.py`)
|
||||
|
||||
- Logging setup at import time
|
||||
- Startup/shutdown logging
|
||||
- Middleware integration
|
||||
- Error handler registration
|
||||
|
||||
## File Structure
|
||||
```
|
||||
src/roboco/
|
||||
├── __init__.py # Updated with core exports
|
||||
├── exceptions.py # NEW - Custom exception hierarchy
|
||||
├── logging.py # NEW - Structured logging config
|
||||
├── api/
|
||||
│ ├── app.py # Updated with middleware
|
||||
│ └── middleware.py # NEW - Request/error middleware
|
||||
└── alembic/versions/
|
||||
└── 001_initial_schema.py # NEW - Initial migration
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Raising Exceptions
|
||||
```python
|
||||
from roboco.exceptions import NotFoundError, TaskLifecycleError
|
||||
|
||||
# Resource not found
|
||||
raise NotFoundError("Task", task_id)
|
||||
|
||||
# Invalid state transition
|
||||
raise TaskLifecycleError(
|
||||
task_id=task.id,
|
||||
current_status=task.status.value,
|
||||
target_status="in_progress",
|
||||
)
|
||||
```
|
||||
|
||||
### Structured Logging
|
||||
```python
|
||||
from roboco.logging import get_logger, LogContext, log_operation
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
# Basic logging
|
||||
logger.info("Task created", task_id=str(task.id), title=task.title)
|
||||
|
||||
# With context
|
||||
with LogContext(task_id=str(task.id), agent_id=str(agent.id)):
|
||||
logger.info("Processing task")
|
||||
# All logs in this block have task_id and agent_id
|
||||
|
||||
# Operation logging
|
||||
logger.info("Task updated", **log_operation("update", "task", str(task.id)))
|
||||
```
|
||||
|
||||
### Running Migrations
|
||||
```bash
|
||||
# Create migration
|
||||
alembic revision --autogenerate -m "description"
|
||||
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Rollback
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
## API Error Response Format
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "NOT_FOUND",
|
||||
"message": "Task not found: 123e4567-e89b-12d3-a456-426614174000",
|
||||
"details": {
|
||||
"resource_type": "Task",
|
||||
"resource_id": "123e4567-e89b-12d3-a456-426614174000",
|
||||
"correlation_id": "abc123..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Quick Context Restore
|
||||
Phase 6 polish complete. Custom exception hierarchy with 20+ exception types for proper error handling. Structured logging with correlation IDs for request tracing. Middleware for request logging and error handling. Alembic migration with all 10 tables, proper relationships and indexes. All phases (1-6) of the RoboCo system are now implemented.
|
||||
File diff suppressed because it is too large
Load Diff
+120
@@ -0,0 +1,120 @@
|
||||
# Task Index
|
||||
|
||||
Master index of all tasks in the RoboCo system.
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Next Task ID**: TASK-008
|
||||
|
||||
---
|
||||
|
||||
## Active Tasks
|
||||
|
||||
| ID | Title | Cell | Assigned | Priority | State | Updated |
|
||||
|----|-------|------|----------|----------|-------|---------|
|
||||
| TASK-007 | Phase 7 - Agent Runtime | board | - | P0 | pending | 2025-12-10 |
|
||||
|
||||
## Blocked Tasks
|
||||
|
||||
| ID | Title | Blocked By | Cell | Since | Notes |
|
||||
|----|-------|------------|------|-------|-------|
|
||||
| - | No blocked tasks | - | - | - | - |
|
||||
|
||||
## Awaiting QA
|
||||
|
||||
| ID | Title | Cell | Developer | Submitted | QA |
|
||||
|----|-------|------|-----------|-----------|-----|
|
||||
| - | No tasks awaiting QA | - | - | - | - |
|
||||
|
||||
## Awaiting Documentation
|
||||
|
||||
| ID | Title | Cell | Developer | QA Passed | Documenter |
|
||||
|----|-------|------|-----------|-----------|------------|
|
||||
| - | No tasks awaiting docs | - | - | - | - |
|
||||
|
||||
## Recently Completed (Last 7 Days)
|
||||
|
||||
| ID | Title | Cell | Completed | Duration | Notes |
|
||||
|----|-------|------|-----------|----------|-------|
|
||||
| TASK-006 | Phase 6 - Polish | board | 2025-12-09 | 1 day | Exceptions, Logging, Middleware, Migrations |
|
||||
| TASK-005 | Phase 5 - Management | board | 2025-12-09 | 1 day | Task API, Kanban, Metrics, Dashboards |
|
||||
| TASK-004 | Phase 4 - Agents | board | 2025-12-09 | 1 day | 17 agent types, workflows, cell deployment |
|
||||
| TASK-003 | Phase 3 - Intelligence | board | 2025-12-09 | 1 day | piragi RAG, Optimal API, Journal API |
|
||||
| TASK-002 | Phase 2 - Communication | board | 2025-12-09 | 1 day | Transcription, Extraction, Permissions |
|
||||
| TASK-001 | Phase 1 - Core Services | board | 2025-12-09 | 1 day | Database, Messaging API, Agent Framework |
|
||||
|
||||
---
|
||||
|
||||
## Statistics
|
||||
|
||||
### This Week
|
||||
- Created: 7
|
||||
- Completed: 6
|
||||
- Active: 1
|
||||
- Blocked: 0
|
||||
- Avg Completion Time: 1 day
|
||||
|
||||
### This Month
|
||||
- Created: 7
|
||||
- Completed: 6
|
||||
- Active: 1
|
||||
- Blocked: 0
|
||||
- Avg Completion Time: 1 day
|
||||
|
||||
### By Cell
|
||||
| Cell | Active | Blocked | Completed (Month) |
|
||||
|------|--------|---------|-------------------|
|
||||
| Backend | 0 | 0 | 0 |
|
||||
| Frontend | 0 | 0 | 0 |
|
||||
| UX/UI | 0 | 0 | 0 |
|
||||
| Board | 1 | 0 | 6 |
|
||||
|
||||
### By Priority
|
||||
| Priority | Active | Blocked |
|
||||
|----------|--------|---------|
|
||||
| P0 | 1 | 0 |
|
||||
| P1 | 0 | 0 |
|
||||
| P2 | 0 | 0 |
|
||||
| P3 | 0 | 0 |
|
||||
|
||||
---
|
||||
|
||||
## Active Initiatives
|
||||
|
||||
| Initiative | Status | Cells | Progress | Target |
|
||||
|------------|--------|-------|----------|--------|
|
||||
| - | No active initiatives | - | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Create New Task
|
||||
1. Determine next ID from "Next Task ID" above
|
||||
2. Create directory: `.tasks/active/TASK-XXX-{slug}/`
|
||||
3. Copy appropriate template to `README.md`
|
||||
4. Fill in details
|
||||
5. Add to Active Tasks table above
|
||||
6. Increment "Next Task ID"
|
||||
|
||||
### Task State Transitions
|
||||
```
|
||||
pending → claimed → in_progress → verifying → awaiting_qa → awaiting_documentation → completed
|
||||
↓
|
||||
blocked
|
||||
```
|
||||
|
||||
### Priority Guide
|
||||
- **P0**: Critical - production issue, security, blocking everything
|
||||
- **P1**: High - current sprint priority, blocking others
|
||||
- **P2**: Medium - normal priority, scheduled work
|
||||
- **P3**: Low - nice to have, backlog
|
||||
|
||||
---
|
||||
|
||||
## Archive Reference
|
||||
|
||||
Completed tasks are archived by month in `.tasks/completed/YYYY-MM/`.
|
||||
|
||||
| Month | Tasks Completed | Notable |
|
||||
|-------|-----------------|---------|
|
||||
| 2025-12 | 6 | Phase 1-6: Core, Communication, Intelligence, Agents, Management, Polish |
|
||||
@@ -0,0 +1,50 @@
|
||||
# Initiatives
|
||||
|
||||
Initiatives are large, cross-cell efforts that span multiple tasks. They represent features or projects that require coordination between Backend, Frontend, and/or UX/UI cells.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
initiatives/
|
||||
├── README.md # This file
|
||||
├── {initiative-slug}/
|
||||
│ ├── README.md # Initiative overview
|
||||
│ ├── requirements.md # Detailed requirements from Product Owner
|
||||
│ ├── tasks.md # Task breakdown by cell
|
||||
│ ├── timeline.md # Milestones and deadlines
|
||||
│ ├── decisions.md # Cross-cell decisions
|
||||
│ └── status.md # Current status (updated frequently)
|
||||
```
|
||||
|
||||
## Initiative Lifecycle
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Proposed │────►│ Planning │────►│ Active │────►│ Completed │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ Blocked │ │ On Hold │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
## Creating an Initiative
|
||||
|
||||
1. Product Owner or Main PM creates initiative directory
|
||||
2. Fill in README.md with overview
|
||||
3. Define requirements in requirements.md
|
||||
4. Break down tasks by cell in tasks.md
|
||||
5. Set timeline and milestones in timeline.md
|
||||
6. Create individual tasks in `.tasks/active/`
|
||||
7. Link tasks back to initiative
|
||||
|
||||
## Initiative Naming
|
||||
|
||||
`{descriptive-slug}` - Use kebab-case, max 40 characters
|
||||
|
||||
Examples:
|
||||
- `user-preferences`
|
||||
- `dashboard-redesign`
|
||||
- `auth-system-overhaul`
|
||||
- `mobile-app-v2`
|
||||
@@ -0,0 +1,108 @@
|
||||
# Initiative: {Name}
|
||||
|
||||
> **Created**: YYYY-MM-DD
|
||||
> **Owner**: {Product Owner / Main PM}
|
||||
> **Status**: {proposed / planning / active / blocked / on_hold / completed}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
{What is this initiative? Why does it matter? 2-3 paragraphs.}
|
||||
|
||||
## Goals
|
||||
|
||||
1. {Primary goal}
|
||||
2. {Secondary goal}
|
||||
3. {Tertiary goal}
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Current | Target | How Measured |
|
||||
|--------|---------|--------|--------------|
|
||||
| {metric} | {current} | {target} | {method} |
|
||||
| {metric} | {current} | {target} | {method} |
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
- {What's included}
|
||||
- {What's included}
|
||||
|
||||
### Out of Scope
|
||||
- {What's explicitly NOT included}
|
||||
- {What's explicitly NOT included}
|
||||
|
||||
---
|
||||
|
||||
## Cells Involved
|
||||
|
||||
| Cell | Scope | Lead | Status |
|
||||
|------|-------|------|--------|
|
||||
| UX/UI | {brief scope} | UX-PM | {status} |
|
||||
| Backend | {brief scope} | BE-PM | {status} |
|
||||
| Frontend | {brief scope} | FE-PM | {status} |
|
||||
|
||||
## Task Summary
|
||||
|
||||
See [tasks.md](tasks.md) for full breakdown.
|
||||
|
||||
| Cell | Total Tasks | Completed | In Progress | Blocked |
|
||||
|------|-------------|-----------|-------------|---------|
|
||||
| UX/UI | 0 | 0 | 0 | 0 |
|
||||
| Backend | 0 | 0 | 0 | 0 |
|
||||
| Frontend | 0 | 0 | 0 | 0 |
|
||||
|
||||
---
|
||||
|
||||
## Timeline
|
||||
|
||||
See [timeline.md](timeline.md) for details.
|
||||
|
||||
| Milestone | Target | Actual | Status |
|
||||
|-----------|--------|--------|--------|
|
||||
| Design Complete | YYYY-MM-DD | - | pending |
|
||||
| Backend API Ready | YYYY-MM-DD | - | pending |
|
||||
| Frontend Complete | YYYY-MM-DD | - | pending |
|
||||
| QA Complete | YYYY-MM-DD | - | pending |
|
||||
| Launch | YYYY-MM-DD | - | pending |
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
**Last Updated**: YYYY-MM-DD
|
||||
|
||||
{2-3 sentences on current state}
|
||||
|
||||
### This Week
|
||||
- {What happened}
|
||||
- {What happened}
|
||||
|
||||
### Next Week
|
||||
- {What's planned}
|
||||
- {What's planned}
|
||||
|
||||
### Blockers
|
||||
- {Current blockers or "None"}
|
||||
|
||||
### Risks
|
||||
- {Active risks or "None identified"}
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Requirements](requirements.md)
|
||||
- [Tasks](tasks.md)
|
||||
- [Timeline](timeline.md)
|
||||
- [Decisions](decisions.md)
|
||||
- [Status Updates](status.md)
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- **Depends on**: {initiative or "none"}
|
||||
- **Blocks**: {initiative or "none"}
|
||||
- **Related**: {initiative or "none"}
|
||||
@@ -0,0 +1,101 @@
|
||||
# Decisions: {Initiative Name}
|
||||
|
||||
Log of significant decisions made during this initiative.
|
||||
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Decision Log
|
||||
|
||||
### DEC-001: {Decision Title}
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Decider**: {agent-id or role}
|
||||
**Status**: {proposed / accepted / superseded / rejected}
|
||||
|
||||
#### Context
|
||||
{What situation required a decision?}
|
||||
|
||||
#### Options Considered
|
||||
|
||||
**Option A: {Name}**
|
||||
- Description: {what this option entails}
|
||||
- Pros:
|
||||
- {Pro 1}
|
||||
- {Pro 2}
|
||||
- Cons:
|
||||
- {Con 1}
|
||||
- {Con 2}
|
||||
- Effort: {low / medium / high}
|
||||
|
||||
**Option B: {Name}**
|
||||
- Description: {what this option entails}
|
||||
- Pros:
|
||||
- {Pro 1}
|
||||
- {Pro 2}
|
||||
- Cons:
|
||||
- {Con 1}
|
||||
- {Con 2}
|
||||
- Effort: {low / medium / high}
|
||||
|
||||
#### Decision
|
||||
**Chose Option {X}**: {Brief statement of decision}
|
||||
|
||||
#### Rationale
|
||||
{Why this option was chosen}
|
||||
|
||||
#### Consequences
|
||||
- {Consequence 1 - what this means going forward}
|
||||
- {Consequence 2 - what needs to happen as a result}
|
||||
- {Consequence 3 - what we're accepting/trading off}
|
||||
|
||||
#### Related
|
||||
- Tasks affected: TASK-XXX, TASK-XXX
|
||||
- Supersedes: DEC-XXX (if applicable)
|
||||
|
||||
---
|
||||
|
||||
### DEC-002: {Decision Title}
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Decider**: {agent-id or role}
|
||||
**Status**: {proposed / accepted / superseded / rejected}
|
||||
|
||||
#### Context
|
||||
{What situation required a decision?}
|
||||
|
||||
#### Options Considered
|
||||
{...}
|
||||
|
||||
#### Decision
|
||||
{...}
|
||||
|
||||
#### Rationale
|
||||
{...}
|
||||
|
||||
#### Consequences
|
||||
{...}
|
||||
|
||||
---
|
||||
|
||||
## Pending Decisions
|
||||
|
||||
| ID | Topic | Owner | Needed By | Blockers |
|
||||
|----|-------|-------|-----------|----------|
|
||||
| DEC-XXX | {topic} | {owner} | YYYY-MM-DD | {what it blocks} |
|
||||
|
||||
---
|
||||
|
||||
## Decision Index
|
||||
|
||||
| ID | Title | Date | Status | Quick Reference |
|
||||
|----|-------|------|--------|-----------------|
|
||||
| DEC-001 | {title} | YYYY-MM-DD | {status} | {one-line summary} |
|
||||
| DEC-002 | {title} | YYYY-MM-DD | {status} | {one-line summary} |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Any additional context about decision-making process, stakeholders involved, etc.}
|
||||
@@ -0,0 +1,149 @@
|
||||
# Requirements: {Initiative Name}
|
||||
|
||||
> **Author**: Product Owner
|
||||
> **Version**: 1.0
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Business Context
|
||||
|
||||
{Why is this initiative important? What business problem does it solve?}
|
||||
|
||||
## User Problem
|
||||
|
||||
{What user problem does this solve? Who are the users?}
|
||||
|
||||
### User Personas
|
||||
|
||||
**Persona 1: {Name}**
|
||||
- Role: {description}
|
||||
- Needs: {what they need}
|
||||
- Pain Points: {current frustrations}
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### FR-1: {Requirement Title}
|
||||
|
||||
**Priority**: {must-have / should-have / nice-to-have}
|
||||
|
||||
**Description**: {Detailed description}
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] {Criterion 1}
|
||||
- [ ] {Criterion 2}
|
||||
- [ ] {Criterion 3}
|
||||
|
||||
**Notes**: {Additional context}
|
||||
|
||||
---
|
||||
|
||||
### FR-2: {Requirement Title}
|
||||
|
||||
**Priority**: {must-have / should-have / nice-to-have}
|
||||
|
||||
**Description**: {Detailed description}
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] {Criterion 1}
|
||||
- [ ] {Criterion 2}
|
||||
|
||||
---
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### Performance
|
||||
- {Performance requirement}
|
||||
|
||||
### Security
|
||||
- {Security requirement}
|
||||
|
||||
### Accessibility
|
||||
- {Accessibility requirement}
|
||||
|
||||
### Compatibility
|
||||
- {Browser/device compatibility}
|
||||
|
||||
---
|
||||
|
||||
## User Flows
|
||||
|
||||
### Flow 1: {Name}
|
||||
|
||||
```
|
||||
[User Action] → [System Response] → [User Action] → [System Response]
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
1. User {action}
|
||||
2. System {response}
|
||||
3. User {action}
|
||||
4. System {response}
|
||||
|
||||
**Success State**: {what success looks like}
|
||||
|
||||
**Error States**:
|
||||
- {Error scenario 1}: {handling}
|
||||
- {Error scenario 2}: {handling}
|
||||
|
||||
---
|
||||
|
||||
## Data Requirements
|
||||
|
||||
### Data Entities
|
||||
| Entity | Description | Source |
|
||||
|--------|-------------|--------|
|
||||
| {entity} | {description} | {where it comes from} |
|
||||
|
||||
### Data Rules
|
||||
- {Rule 1}
|
||||
- {Rule 2}
|
||||
|
||||
---
|
||||
|
||||
## Integration Requirements
|
||||
|
||||
### External Systems
|
||||
| System | Integration Type | Purpose |
|
||||
|--------|-----------------|---------|
|
||||
| {system} | {API / webhook / etc.} | {purpose} |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- {Technical constraint}
|
||||
- {Business constraint}
|
||||
- {Timeline constraint}
|
||||
- {Budget constraint}
|
||||
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
|
||||
- {Assumption 1}
|
||||
- {Assumption 2}
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] {Question 1}
|
||||
- [ ] {Question 2}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Wireframes/Mockups
|
||||
{Links to design references}
|
||||
|
||||
### Reference Documents
|
||||
{Links to related documents}
|
||||
|
||||
### Glossary
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| {term} | {definition} |
|
||||
@@ -0,0 +1,81 @@
|
||||
# Status Updates: {Initiative Name}
|
||||
|
||||
Running log of status updates for stakeholder visibility.
|
||||
|
||||
---
|
||||
|
||||
## Latest Status
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Overall**: {on_track / at_risk / blocked / delayed} {emoji: 🟢 / 🟡 / 🔴}
|
||||
**Progress**: X%
|
||||
|
||||
### Summary
|
||||
{2-3 sentence summary of current state}
|
||||
|
||||
### Completed This Period
|
||||
- {What was completed}
|
||||
- {What was completed}
|
||||
|
||||
### In Progress
|
||||
- {What's actively being worked on}
|
||||
- {What's actively being worked on}
|
||||
|
||||
### Upcoming
|
||||
- {What's next}
|
||||
- {What's next}
|
||||
|
||||
### Blockers
|
||||
- {Active blockers or "None"}
|
||||
|
||||
### Risks
|
||||
- {Active risks or "None"}
|
||||
|
||||
### Decisions Needed
|
||||
- {Decisions needed or "None"}
|
||||
|
||||
---
|
||||
|
||||
## Status History
|
||||
|
||||
### YYYY-MM-DD
|
||||
**Status**: {status} {emoji}
|
||||
**Progress**: X%
|
||||
|
||||
{Summary of status at this point}
|
||||
|
||||
- Completed: {items}
|
||||
- Blockers: {items or "None"}
|
||||
- Notes: {any notes}
|
||||
|
||||
---
|
||||
|
||||
### YYYY-MM-DD
|
||||
**Status**: {status} {emoji}
|
||||
**Progress**: X%
|
||||
|
||||
{Summary}
|
||||
|
||||
---
|
||||
|
||||
## Metrics Over Time
|
||||
|
||||
| Date | Progress | Tasks Done | Tasks Total | Blockers |
|
||||
|------|----------|------------|-------------|----------|
|
||||
| YYYY-MM-DD | X% | X | X | X |
|
||||
| YYYY-MM-DD | X% | X | X | X |
|
||||
|
||||
---
|
||||
|
||||
## Communication Log
|
||||
|
||||
| Date | Type | Audience | Summary |
|
||||
|------|------|----------|---------|
|
||||
| YYYY-MM-DD | Status update | Board | Weekly update |
|
||||
| YYYY-MM-DD | Escalation | CEO | Blocker escalation |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional status-related notes}
|
||||
@@ -0,0 +1,140 @@
|
||||
# Task Breakdown: {Initiative Name}
|
||||
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
| Cell | Total | Completed | In Progress | Blocked | Pending |
|
||||
|------|-------|-----------|-------------|---------|---------|
|
||||
| UX/UI | 0 | 0 | 0 | 0 | 0 |
|
||||
| Backend | 0 | 0 | 0 | 0 | 0 |
|
||||
| Frontend | 0 | 0 | 0 | 0 | 0 |
|
||||
| **Total** | **0** | **0** | **0** | **0** | **0** |
|
||||
|
||||
---
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Requirements │
|
||||
│ (Product) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
▼ │ ▼
|
||||
┌──────────┐ │ ┌──────────┐
|
||||
│ UX/UI │ │ │ Backend │
|
||||
│ Design │ │ │ API │
|
||||
└────┬─────┘ │ └────┬─────┘
|
||||
│ │ │
|
||||
│ │ │
|
||||
└───────┬────────┘ │
|
||||
│ │
|
||||
▼ │
|
||||
┌──────────┐ │
|
||||
│ Frontend │◄────────────────┘
|
||||
│ UI │
|
||||
└────┬─────┘
|
||||
│
|
||||
▼
|
||||
┌──────────┐
|
||||
│ QA │
|
||||
└────┬─────┘
|
||||
│
|
||||
▼
|
||||
┌──────────┐
|
||||
│ Launch │
|
||||
└──────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UX/UI Cell Tasks
|
||||
|
||||
| ID | Title | Type | Priority | Assigned | Status | Blocks |
|
||||
|----|-------|------|----------|----------|--------|--------|
|
||||
| TASK-XXX | {title} | design | P{n} | {agent} | {status} | TASK-XXX |
|
||||
|
||||
### Task Details
|
||||
|
||||
#### TASK-XXX: {Title}
|
||||
- **Type**: Design
|
||||
- **Priority**: P{n}
|
||||
- **Assigned**: {agent}
|
||||
- **Status**: {status}
|
||||
- **Blocks**: {what this blocks}
|
||||
- **Description**: {brief description}
|
||||
- **Link**: [Task Record](../../active/TASK-XXX-slug/)
|
||||
|
||||
---
|
||||
|
||||
## Backend Cell Tasks
|
||||
|
||||
| ID | Title | Type | Priority | Assigned | Status | Blocks |
|
||||
|----|-------|------|----------|----------|--------|--------|
|
||||
| TASK-XXX | {title} | feature | P{n} | {agent} | {status} | TASK-XXX |
|
||||
|
||||
### Task Details
|
||||
|
||||
#### TASK-XXX: {Title}
|
||||
- **Type**: Feature
|
||||
- **Priority**: P{n}
|
||||
- **Assigned**: {agent}
|
||||
- **Status**: {status}
|
||||
- **Blocked By**: {dependencies}
|
||||
- **Blocks**: {what this blocks}
|
||||
- **Description**: {brief description}
|
||||
- **Link**: [Task Record](../../active/TASK-XXX-slug/)
|
||||
|
||||
---
|
||||
|
||||
## Frontend Cell Tasks
|
||||
|
||||
| ID | Title | Type | Priority | Assigned | Status | Blocked By |
|
||||
|----|-------|------|----------|----------|--------|------------|
|
||||
| TASK-XXX | {title} | feature | P{n} | {agent} | {status} | TASK-XXX, TASK-XXX |
|
||||
|
||||
### Task Details
|
||||
|
||||
#### TASK-XXX: {Title}
|
||||
- **Type**: Feature
|
||||
- **Priority**: P{n}
|
||||
- **Assigned**: {agent}
|
||||
- **Status**: {status}
|
||||
- **Blocked By**: {UX design task, BE API task}
|
||||
- **Description**: {brief description}
|
||||
- **Link**: [Task Record](../../active/TASK-XXX-slug/)
|
||||
|
||||
---
|
||||
|
||||
## Documentation Tasks
|
||||
|
||||
| ID | Title | Cell | Priority | Assigned | Status |
|
||||
|----|-------|------|----------|----------|--------|
|
||||
| TASK-XXX | {title} | {cell} | P{n} | {agent} | {status} |
|
||||
|
||||
---
|
||||
|
||||
## Task Creation Checklist
|
||||
|
||||
When breaking down initiative into tasks:
|
||||
|
||||
- [ ] UX/UI design tasks identified
|
||||
- [ ] Backend API tasks identified
|
||||
- [ ] Frontend implementation tasks identified
|
||||
- [ ] Documentation tasks identified
|
||||
- [ ] Dependencies mapped
|
||||
- [ ] Priorities assigned
|
||||
- [ ] Tasks created in `.tasks/active/`
|
||||
- [ ] Tasks linked back to this initiative
|
||||
- [ ] Cell PMs notified
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional notes on task breakdown, sequencing decisions, etc.}
|
||||
@@ -0,0 +1,131 @@
|
||||
# Timeline: {Initiative Name}
|
||||
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
> **Overall Status**: {on_track / at_risk / delayed}
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| **Start Date** | YYYY-MM-DD |
|
||||
| **Target Completion** | YYYY-MM-DD |
|
||||
| **Current Progress** | X% |
|
||||
| **Days Remaining** | X days |
|
||||
| **Status** | {on_track / at_risk / delayed} |
|
||||
|
||||
---
|
||||
|
||||
## Milestones
|
||||
|
||||
| # | Milestone | Target | Actual | Status | Notes |
|
||||
|---|-----------|--------|--------|--------|-------|
|
||||
| 1 | Requirements Finalized | YYYY-MM-DD | - | pending | |
|
||||
| 2 | Design Complete | YYYY-MM-DD | - | pending | |
|
||||
| 3 | Backend API Ready | YYYY-MM-DD | - | pending | |
|
||||
| 4 | Frontend Integration | YYYY-MM-DD | - | pending | |
|
||||
| 5 | QA Complete | YYYY-MM-DD | - | pending | |
|
||||
| 6 | Documentation Complete | YYYY-MM-DD | - | pending | |
|
||||
| 7 | Launch | YYYY-MM-DD | - | pending | |
|
||||
|
||||
---
|
||||
|
||||
## Gantt View
|
||||
|
||||
```
|
||||
Week | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|
||||
------------|---|---|---|---|---|---|---|---|
|
||||
Requirements| ██| | | | | | | |
|
||||
UX Design | | ██| ██| | | | | |
|
||||
Backend | | ██| ██| ██| | | | |
|
||||
Frontend | | | | ██| ██| ██| | |
|
||||
QA | | | | | | ██| ██| |
|
||||
Docs | | | | | | | ██| |
|
||||
Launch | | | | | | | | ██|
|
||||
|
||||
██ = Planned work
|
||||
░░ = Buffer/contingency
|
||||
▓▓ = Completed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Weekly Schedule
|
||||
|
||||
### Week 1: {Date Range}
|
||||
**Focus**: Requirements & Planning
|
||||
|
||||
| Day | Activity | Owner |
|
||||
|-----|----------|-------|
|
||||
| Mon | Requirements review | Product Owner |
|
||||
| Tue | Technical planning | Main PM |
|
||||
| Wed | Task breakdown | Main PM |
|
||||
| Thu | Task assignment | Cell PMs |
|
||||
| Fri | Kickoff | All |
|
||||
|
||||
---
|
||||
|
||||
### Week 2: {Date Range}
|
||||
**Focus**: Design & Backend Start
|
||||
|
||||
| Day | Activity | Owner |
|
||||
|-----|----------|-------|
|
||||
| Mon | Design begins | UX-Dev |
|
||||
| Tue | Backend planning | BE-Dev |
|
||||
| Wed | {activity} | {owner} |
|
||||
| Thu | {activity} | {owner} |
|
||||
| Fri | Design review | UX-QA |
|
||||
|
||||
---
|
||||
|
||||
## Critical Path
|
||||
|
||||
The critical path is:
|
||||
1. Requirements → Design → Frontend → QA → Launch
|
||||
|
||||
**Critical dependencies**:
|
||||
- Frontend cannot start until design is complete
|
||||
- Frontend cannot integrate until Backend API is ready
|
||||
- QA cannot begin until Frontend is complete
|
||||
|
||||
**Parallel tracks**:
|
||||
- Backend API can proceed in parallel with Design
|
||||
- Documentation can proceed in parallel with QA
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Probability | Impact | Mitigation | Status |
|
||||
|------|-------------|--------|------------|--------|
|
||||
| Design delays | Med | High | Start with wireframes | Watching |
|
||||
| API complexity | Low | Med | Early technical spike | Mitigated |
|
||||
| {risk} | {prob} | {impact} | {mitigation} | {status} |
|
||||
|
||||
---
|
||||
|
||||
## Buffer & Contingency
|
||||
|
||||
| Phase | Planned | Buffer | Total |
|
||||
|-------|---------|--------|-------|
|
||||
| Design | 5 days | 1 day | 6 days |
|
||||
| Backend | 7 days | 2 days | 9 days |
|
||||
| Frontend | 10 days | 2 days | 12 days |
|
||||
| QA | 3 days | 1 day | 4 days |
|
||||
|
||||
**Total buffer**: X days
|
||||
|
||||
---
|
||||
|
||||
## Timeline Adjustments
|
||||
|
||||
| Date | Adjustment | Reason | Impact |
|
||||
|------|------------|--------|--------|
|
||||
| YYYY-MM-DD | {change} | {reason} | {impact} |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional timeline considerations, holidays, team availability, etc.}
|
||||
@@ -0,0 +1,114 @@
|
||||
# Task Templates
|
||||
|
||||
Templates for creating task records in the RoboCo task management system.
|
||||
|
||||
## Task Type Templates
|
||||
|
||||
These templates are used to create the main README.md for a task:
|
||||
|
||||
| Template | Use When | Key Features |
|
||||
|----------|----------|--------------|
|
||||
| [feature.md](feature.md) | Building new functionality | User story, acceptance criteria, technical details |
|
||||
| [bugfix.md](bugfix.md) | Fixing bugs | Reproduction steps, root cause, fix verification |
|
||||
| [research.md](research.md) | Investigation/research tasks | Research questions, findings, recommendations |
|
||||
| [documentation.md](documentation.md) | Writing/updating docs | Source materials, publication locations |
|
||||
| [design.md](design.md) | UX/UI design work | Figma links, states checklist, handoff |
|
||||
|
||||
## Supporting Templates
|
||||
|
||||
These templates are used for files within a task directory:
|
||||
|
||||
| Template | Purpose | Created By |
|
||||
|----------|---------|------------|
|
||||
| [plan.md](plan.md) | Implementation plan | Developer during planning |
|
||||
| [journal.md](journal.md) | Agent journey notes | Developer during execution |
|
||||
| [decisions.md](decisions.md) | Decision log | Anyone making decisions |
|
||||
| [blockers.md](blockers.md) | Blocker tracking | Anyone when blocked |
|
||||
| [handoff.md](handoff.md) | Documenter handoff | Developer when complete |
|
||||
| [qa-review.md](qa-review.md) | QA findings | QA during review |
|
||||
|
||||
## Initiative Templates
|
||||
|
||||
In `../initiatives/_template/`:
|
||||
|
||||
| Template | Purpose |
|
||||
|----------|---------|
|
||||
| README.md | Initiative overview |
|
||||
| requirements.md | Detailed requirements |
|
||||
| tasks.md | Task breakdown by cell |
|
||||
| timeline.md | Milestones and schedule |
|
||||
| decisions.md | Cross-cell decisions |
|
||||
| status.md | Status updates |
|
||||
|
||||
## Creating a New Task
|
||||
|
||||
### 1. Determine Task Type
|
||||
- New feature → `feature.md`
|
||||
- Bug fix → `bugfix.md`
|
||||
- Research/investigation → `research.md`
|
||||
- Documentation → `documentation.md`
|
||||
- Design work → `design.md`
|
||||
|
||||
### 2. Create Task Directory
|
||||
```bash
|
||||
mkdir -p .tasks/active/TASK-XXX-{slug}
|
||||
```
|
||||
|
||||
### 3. Copy Template
|
||||
```bash
|
||||
cp .tasks/templates/{type}.md .tasks/active/TASK-XXX-{slug}/README.md
|
||||
```
|
||||
|
||||
### 4. Fill In Template
|
||||
- Replace all `{placeholders}`
|
||||
- Update status section
|
||||
- Define acceptance criteria
|
||||
- Add to index.md
|
||||
|
||||
### 5. Create Supporting Files As Needed
|
||||
```bash
|
||||
# Copy templates as needed during work
|
||||
cp .tasks/templates/plan.md .tasks/active/TASK-XXX-{slug}/
|
||||
cp .tasks/templates/journal.md .tasks/active/TASK-XXX-{slug}/
|
||||
```
|
||||
|
||||
## Template Conventions
|
||||
|
||||
### Placeholders
|
||||
- `{ID}` - Task number (e.g., 042)
|
||||
- `{Title}` - Human-readable title
|
||||
- `{agent-id}` - Agent identifier (e.g., be-dev-1)
|
||||
- `YYYY-MM-DD` - ISO date format
|
||||
- `{slug}` - Kebab-case description
|
||||
|
||||
### Status Values
|
||||
- `pending` - Not started
|
||||
- `claimed` - Assigned, not started
|
||||
- `in_progress` - Active work
|
||||
- `blocked` - Waiting on something
|
||||
- `paused` - Intentionally stopped
|
||||
- `verifying` - Self-review
|
||||
- `awaiting_qa` - Ready for QA
|
||||
- `needs_revision` - QA found issues
|
||||
- `awaiting_documentation` - Ready for docs
|
||||
- `completed` - Done
|
||||
|
||||
### Priority Values
|
||||
- `P0` - Critical, drop everything
|
||||
- `P1` - High, next up
|
||||
- `P2` - Medium, normal queue
|
||||
- `P3` - Low, when available
|
||||
|
||||
### Cell Values
|
||||
- `backend` - Backend cell
|
||||
- `frontend` - Frontend cell
|
||||
- `ux_ui` - UX/UI cell
|
||||
- `board` - Board level
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Always update README.md** when status changes
|
||||
2. **Journal frequently** - context is valuable
|
||||
3. **Link commits** as you make them
|
||||
4. **Create handoff.md** before marking awaiting_documentation
|
||||
5. **Be specific** in acceptance criteria - vague = wasted time
|
||||
@@ -0,0 +1,86 @@
|
||||
# Blockers: TASK-{ID}
|
||||
|
||||
> **Status**: {BLOCKED / RESOLVED}
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Active Blockers
|
||||
|
||||
### Blocker 1: {Title}
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Identified** | YYYY-MM-DD |
|
||||
| **Type** | {dependency / technical / resource / external / clarification} |
|
||||
| **Severity** | {critical / high / medium / low} |
|
||||
| **Blocking** | {what this prevents} |
|
||||
| **Owner** | {who's working on resolution} |
|
||||
| **Status** | {investigating / escalated / waiting / resolved} |
|
||||
|
||||
#### Description
|
||||
{What is the blocker? Be specific.}
|
||||
|
||||
#### Impact
|
||||
{What work is blocked? What's the downstream effect?}
|
||||
|
||||
#### Resolution Path
|
||||
1. {Step 1 to resolve}
|
||||
2. {Step 2 to resolve}
|
||||
|
||||
#### Workaround
|
||||
{Is there a temporary workaround? Or "None available"}
|
||||
|
||||
#### Escalation
|
||||
- **Escalated to**: {agent/role}
|
||||
- **Escalated on**: YYYY-MM-DD
|
||||
- **Response**: {response or "Awaiting"}
|
||||
|
||||
#### Updates
|
||||
| Date | Update |
|
||||
|------|--------|
|
||||
| YYYY-MM-DD | {Initial identification} |
|
||||
| YYYY-MM-DD | {Update} |
|
||||
|
||||
---
|
||||
|
||||
### Blocker 2: {Title}
|
||||
|
||||
{Same format as above}
|
||||
|
||||
---
|
||||
|
||||
## Resolved Blockers
|
||||
|
||||
### Blocker: {Title} [RESOLVED]
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Identified** | YYYY-MM-DD |
|
||||
| **Resolved** | YYYY-MM-DD |
|
||||
| **Duration** | X days |
|
||||
| **Type** | {type} |
|
||||
|
||||
#### What Happened
|
||||
{Brief description of the blocker}
|
||||
|
||||
#### How It Was Resolved
|
||||
{How was it unblocked?}
|
||||
|
||||
#### Lessons Learned
|
||||
{What could prevent this in the future?}
|
||||
|
||||
---
|
||||
|
||||
## Blocker Summary
|
||||
|
||||
| # | Title | Type | Severity | Identified | Resolved | Duration |
|
||||
|---|-------|------|----------|------------|----------|----------|
|
||||
| 1 | {title} | {type} | {severity} | YYYY-MM-DD | - | ongoing |
|
||||
| 2 | {title} | {type} | {severity} | YYYY-MM-DD | YYYY-MM-DD | X days |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional context about blockers}
|
||||
@@ -0,0 +1,150 @@
|
||||
# TASK-{ID}: {Title}
|
||||
|
||||
> **Template**: Bugfix
|
||||
> **Created**: YYYY-MM-DD
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **State** | `pending` |
|
||||
| **Priority** | P{0-3} |
|
||||
| **Severity** | {critical / high / medium / low} |
|
||||
| **Cell** | {backend / frontend / ux_ui} |
|
||||
| **Assigned To** | {agent-id or "unassigned"} |
|
||||
| **Reported By** | {agent-id / user / automated} |
|
||||
|
||||
## Timeline
|
||||
|
||||
| Milestone | Date |
|
||||
|-----------|------|
|
||||
| Reported | YYYY-MM-DD |
|
||||
| Claimed | - |
|
||||
| Root Cause Found | - |
|
||||
| Fix Implemented | - |
|
||||
| QA Verified | - |
|
||||
| Completed | - |
|
||||
|
||||
---
|
||||
|
||||
## Bug Summary
|
||||
|
||||
{One sentence description of the bug}
|
||||
|
||||
## Severity Assessment
|
||||
|
||||
| Factor | Assessment |
|
||||
|--------|------------|
|
||||
| **User Impact** | {How many users affected? How badly?} |
|
||||
| **Frequency** | {How often does it occur?} |
|
||||
| **Workaround** | {Is there a workaround? What is it?} |
|
||||
| **Data Impact** | {Any data loss or corruption?} |
|
||||
|
||||
---
|
||||
|
||||
## Reproduction
|
||||
|
||||
### Environment
|
||||
- **Browser/Client**: {e.g., Chrome 120, iOS app v2.1}
|
||||
- **OS**: {e.g., macOS 14.1, Windows 11}
|
||||
- **User Type**: {e.g., admin, regular user}
|
||||
- **Environment**: {production / staging / development}
|
||||
|
||||
### Steps to Reproduce
|
||||
1. {Step 1}
|
||||
2. {Step 2}
|
||||
3. {Step 3}
|
||||
4. {Observe the bug}
|
||||
|
||||
### Expected Behavior
|
||||
{What should happen}
|
||||
|
||||
### Actual Behavior
|
||||
{What actually happens}
|
||||
|
||||
### Evidence
|
||||
{Screenshots, error logs, console output}
|
||||
|
||||
```
|
||||
{Paste error messages or logs here}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Investigation
|
||||
|
||||
### Root Cause
|
||||
{Filled in during investigation - what's causing this bug?}
|
||||
|
||||
### Affected Code
|
||||
{Files and functions involved}
|
||||
- `path/to/file.py:line_number`
|
||||
- `path/to/other_file.py:line_number`
|
||||
|
||||
### Related Issues
|
||||
- {Link to related bugs or tasks}
|
||||
- {Previous similar issues}
|
||||
|
||||
---
|
||||
|
||||
## Fix
|
||||
|
||||
### Approach
|
||||
{How will this be fixed?}
|
||||
|
||||
### Changes Required
|
||||
- [ ] {Change 1}
|
||||
- [ ] {Change 2}
|
||||
- [ ] {Change 3}
|
||||
|
||||
### Regression Risk
|
||||
{What could break as a result of this fix?}
|
||||
|
||||
### Testing Plan
|
||||
- [ ] {Test case 1 - verifies fix}
|
||||
- [ ] {Test case 2 - checks regression}
|
||||
- [ ] {Test case 3 - edge cases}
|
||||
|
||||
---
|
||||
|
||||
## Verification Criteria
|
||||
|
||||
- [ ] Bug no longer reproducible with original steps
|
||||
- [ ] No new errors in logs
|
||||
- [ ] Related functionality still works
|
||||
- [ ] Tests added to prevent regression
|
||||
- [ ] {Additional verification criteria}
|
||||
|
||||
---
|
||||
|
||||
## Commits
|
||||
|
||||
| Commit | Description | Date |
|
||||
|--------|-------------|------|
|
||||
| - | No commits yet | - |
|
||||
|
||||
---
|
||||
|
||||
## Quick Context Restore
|
||||
|
||||
**Current state**: Not started
|
||||
**Investigation status**: Not started
|
||||
**Root cause**: Unknown
|
||||
**Fix approach**: TBD
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional context, related issues, customer impact notes}
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Agent | Change |
|
||||
|------|-------|--------|
|
||||
| YYYY-MM-DD | {agent} | Bug reported |
|
||||
@@ -0,0 +1,58 @@
|
||||
# Decisions: TASK-{ID}
|
||||
|
||||
Log of decisions made during this task.
|
||||
|
||||
---
|
||||
|
||||
## Decision 1: {Title}
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Decider**: {agent-id}
|
||||
|
||||
### Context
|
||||
{What situation required a decision?}
|
||||
|
||||
### Options Considered
|
||||
|
||||
**Option A: {Name}**
|
||||
- Pros: {list}
|
||||
- Cons: {list}
|
||||
|
||||
**Option B: {Name}**
|
||||
- Pros: {list}
|
||||
- Cons: {list}
|
||||
|
||||
### Decision
|
||||
**Chose {Option X}** because {brief rationale}
|
||||
|
||||
### Consequences
|
||||
- {What this means going forward}
|
||||
- {Trade-offs accepted}
|
||||
|
||||
---
|
||||
|
||||
## Decision 2: {Title}
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Decider**: {agent-id}
|
||||
|
||||
### Context
|
||||
{What situation required a decision?}
|
||||
|
||||
### Options Considered
|
||||
{...}
|
||||
|
||||
### Decision
|
||||
{...}
|
||||
|
||||
### Consequences
|
||||
{...}
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| # | Decision | Date | Summary |
|
||||
|---|----------|------|---------|
|
||||
| 1 | {title} | YYYY-MM-DD | {one-line summary} |
|
||||
| 2 | {title} | YYYY-MM-DD | {one-line summary} |
|
||||
@@ -0,0 +1,199 @@
|
||||
# TASK-{ID}: {Title}
|
||||
|
||||
> **Template**: Design
|
||||
> **Created**: YYYY-MM-DD
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **State** | `pending` |
|
||||
| **Priority** | P{0-3} |
|
||||
| **Cell** | ux_ui |
|
||||
| **Assigned To** | {agent-id or "unassigned"} |
|
||||
| **Requested By** | {agent-id} |
|
||||
| **For Initiative** | {initiative-id or "standalone"} |
|
||||
|
||||
## Timeline
|
||||
|
||||
| Milestone | Date |
|
||||
|-----------|------|
|
||||
| Requested | YYYY-MM-DD |
|
||||
| Started | - |
|
||||
| First Draft | - |
|
||||
| QA Review | - |
|
||||
| Revisions Complete | - |
|
||||
| Handed Off | - |
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
{What needs to be designed and why?}
|
||||
|
||||
## User Problem
|
||||
|
||||
{What user problem does this design solve?}
|
||||
|
||||
## Context
|
||||
|
||||
{Business context, previous attempts, constraints}
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
- {Requirement 1}
|
||||
- {Requirement 2}
|
||||
- {Requirement 3}
|
||||
|
||||
### User Flows
|
||||
{What user actions need to be supported?}
|
||||
1. {Flow 1}
|
||||
2. {Flow 2}
|
||||
|
||||
### Constraints
|
||||
- {Technical constraint}
|
||||
- {Brand constraint}
|
||||
- {Platform constraint}
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
### Required
|
||||
- [ ] Mobile design (320-480px)
|
||||
- [ ] Desktop design (1280px+)
|
||||
- [ ] All interaction states
|
||||
- [ ] Component specifications
|
||||
- [ ] Handoff documentation
|
||||
|
||||
### Optional
|
||||
- [ ] Tablet design (768-1024px)
|
||||
- [ ] Interactive prototype
|
||||
- [ ] Animation specifications
|
||||
- [ ] Micro-interactions
|
||||
|
||||
---
|
||||
|
||||
## Design Assets
|
||||
|
||||
### Figma Links
|
||||
| Asset | Link | Status |
|
||||
|-------|------|--------|
|
||||
| Main Design | {link} | {in progress / complete} |
|
||||
| Prototype | {link} | {in progress / complete / N/A} |
|
||||
| Component Specs | {link} | {in progress / complete} |
|
||||
|
||||
### States Checklist
|
||||
|
||||
| Component | Default | Hover | Active | Focus | Disabled | Loading | Error | Empty |
|
||||
|-----------|---------|-------|--------|-------|----------|---------|-------|-------|
|
||||
| {component} | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ |
|
||||
| {component} | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ |
|
||||
|
||||
---
|
||||
|
||||
## Design System
|
||||
|
||||
### Existing Patterns to Use
|
||||
- {Pattern 1}
|
||||
- {Pattern 2}
|
||||
|
||||
### New Patterns Introduced
|
||||
- {New pattern - document in design system}
|
||||
|
||||
### Design Tokens Used
|
||||
| Category | Tokens |
|
||||
|----------|--------|
|
||||
| Colors | {list} |
|
||||
| Spacing | {list} |
|
||||
| Typography | {list} |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- [ ] Color contrast verified (4.5:1 text, 3:1 large)
|
||||
- [ ] Focus states designed
|
||||
- [ ] Touch targets adequate (44px min)
|
||||
- [ ] Color not sole indicator
|
||||
- [ ] Keyboard flow considered
|
||||
|
||||
---
|
||||
|
||||
## Responsive Behavior
|
||||
|
||||
| Breakpoint | Behavior |
|
||||
|------------|----------|
|
||||
| Mobile (<768px) | {description} |
|
||||
| Tablet (768-1024px) | {description} |
|
||||
| Desktop (>1024px) | {description} |
|
||||
|
||||
---
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### Decision 1: {Title}
|
||||
- **Options**: {what was considered}
|
||||
- **Decision**: {what was chosen}
|
||||
- **Rationale**: {why}
|
||||
|
||||
---
|
||||
|
||||
## Frontend Handoff
|
||||
|
||||
### Handoff Checklist
|
||||
- [ ] All states complete
|
||||
- [ ] All breakpoints complete
|
||||
- [ ] Specs documented in Figma
|
||||
- [ ] Interactions documented
|
||||
- [ ] Assets exportable
|
||||
- [ ] Design tokens referenced (not hardcoded values)
|
||||
|
||||
### Implementation Notes
|
||||
{Specific notes for frontend developers}
|
||||
|
||||
### Animations/Transitions
|
||||
{Any animation specifications}
|
||||
|
||||
---
|
||||
|
||||
## QA Review
|
||||
|
||||
### Design QA Checklist
|
||||
- [ ] Design system compliance
|
||||
- [ ] All states present
|
||||
- [ ] Accessibility requirements met
|
||||
- [ ] Responsive designs complete
|
||||
- [ ] Handoff documentation complete
|
||||
|
||||
### QA Notes
|
||||
{Filled in by UX-QA}
|
||||
|
||||
---
|
||||
|
||||
## Quick Context Restore
|
||||
|
||||
**Current state**: Not started
|
||||
**Design progress**: 0%
|
||||
**States complete**: 0/X
|
||||
**Breakpoints complete**: 0/3
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional context, inspiration, user research insights}
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Agent | Change |
|
||||
|------|-------|--------|
|
||||
| YYYY-MM-DD | {agent} | Design requested |
|
||||
@@ -0,0 +1,154 @@
|
||||
# TASK-{ID}: {Title}
|
||||
|
||||
> **Template**: Documentation
|
||||
> **Created**: YYYY-MM-DD
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **State** | `pending` |
|
||||
| **Priority** | P{0-3} |
|
||||
| **Cell** | {backend / frontend / ux_ui} |
|
||||
| **Assigned To** | {agent-id or "unassigned"} |
|
||||
| **Source Task** | {TASK-XXX or "standalone"} |
|
||||
|
||||
## Timeline
|
||||
|
||||
| Milestone | Date |
|
||||
|-----------|------|
|
||||
| Created | YYYY-MM-DD |
|
||||
| Started | - |
|
||||
| Draft Complete | - |
|
||||
| Reviewed | - |
|
||||
| Published | - |
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
{What documentation needs to be created or updated?}
|
||||
|
||||
## Trigger
|
||||
|
||||
{What prompted this documentation task?}
|
||||
- [ ] New feature (TASK-XXX)
|
||||
- [ ] Updated feature (TASK-XXX)
|
||||
- [ ] Documentation gap identified
|
||||
- [ ] User feedback
|
||||
- [ ] Other: {specify}
|
||||
|
||||
---
|
||||
|
||||
## Documentation Scope
|
||||
|
||||
### Documents to Create/Update
|
||||
|
||||
| Document | Type | Location | Action |
|
||||
|----------|------|----------|--------|
|
||||
| {doc name} | {API / component / guide / etc.} | {path} | {create / update} |
|
||||
| {doc name} | {type} | {path} | {action} |
|
||||
|
||||
### Content Requirements
|
||||
|
||||
- [ ] {Content area 1}
|
||||
- [ ] {Content area 2}
|
||||
- [ ] {Content area 3}
|
||||
|
||||
---
|
||||
|
||||
## Source Materials
|
||||
|
||||
### From Development Task
|
||||
{If this docs task is from a feature/bugfix}
|
||||
|
||||
- **Source Task**: {TASK-XXX or "N/A"}
|
||||
- **Journey Notes**: {path to journal.md}
|
||||
- **Handoff Notes**: {path to handoff.md}
|
||||
- **Commits**: {list of relevant commits}
|
||||
|
||||
### Reference Materials
|
||||
- {Existing documentation to reference}
|
||||
- {Code to document}
|
||||
- {Figma/design links}
|
||||
- {Conversation links}
|
||||
|
||||
---
|
||||
|
||||
## Documentation Checklist
|
||||
|
||||
### Content
|
||||
- [ ] Accurate - reflects current implementation
|
||||
- [ ] Complete - covers all relevant aspects
|
||||
- [ ] Clear - understandable without prior context
|
||||
- [ ] Examples - includes working examples
|
||||
- [ ] Edge cases - documents limitations and gotchas
|
||||
|
||||
### Format
|
||||
- [ ] Follows documentation style guide
|
||||
- [ ] Proper headings and structure
|
||||
- [ ] Code blocks formatted correctly
|
||||
- [ ] Links working
|
||||
- [ ] Images/diagrams included (if applicable)
|
||||
|
||||
### Review
|
||||
- [ ] Technical accuracy verified
|
||||
- [ ] Spell/grammar checked
|
||||
- [ ] Reviewed by {reviewer or "self-reviewed"}
|
||||
|
||||
---
|
||||
|
||||
## Draft
|
||||
|
||||
{Documentation draft or link to draft location}
|
||||
|
||||
### Document 1: {Title}
|
||||
|
||||
```markdown
|
||||
{Draft content here or in separate file}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Publication
|
||||
|
||||
### Locations
|
||||
{Where will this documentation be published?}
|
||||
|
||||
- [ ] {Location 1: e.g., docs/api/endpoint.md}
|
||||
- [ ] {Location 2: e.g., README.md update}
|
||||
- [ ] {Location 3: e.g., changelog entry}
|
||||
|
||||
### Changelog Entry
|
||||
|
||||
```markdown
|
||||
## [version] - YYYY-MM-DD
|
||||
|
||||
### Documentation
|
||||
- {What was documented}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Context Restore
|
||||
|
||||
**Current state**: Not started
|
||||
**Draft status**: Not started
|
||||
**Review status**: Not reviewed
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional context, style notes, audience considerations}
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Agent | Change |
|
||||
|------|-------|--------|
|
||||
| YYYY-MM-DD | {agent} | Documentation task created |
|
||||
@@ -0,0 +1,125 @@
|
||||
# TASK-{ID}: {Title}
|
||||
|
||||
> **Template**: Feature
|
||||
> **Created**: YYYY-MM-DD
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **State** | `pending` |
|
||||
| **Priority** | P{0-3} |
|
||||
| **Cell** | {backend / frontend / ux_ui} |
|
||||
| **Assigned To** | {agent-id or "unassigned"} |
|
||||
| **Created By** | {agent-id} |
|
||||
| **Initiative** | {initiative-id or "standalone"} |
|
||||
|
||||
## Timeline
|
||||
|
||||
| Milestone | Date |
|
||||
|-----------|------|
|
||||
| Created | YYYY-MM-DD |
|
||||
| Claimed | - |
|
||||
| Started | - |
|
||||
| QA Submitted | - |
|
||||
| QA Passed | - |
|
||||
| Docs Complete | - |
|
||||
| Completed | - |
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
{2-3 sentence description of what this feature is and why it's needed}
|
||||
|
||||
## User Story
|
||||
|
||||
**As a** {type of user}
|
||||
**I want** {capability}
|
||||
**So that** {benefit}
|
||||
|
||||
## Context
|
||||
|
||||
{Why is this being built now? What's the business driver? Any relevant background.}
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] {Criterion 1 - specific, testable}
|
||||
- [ ] {Criterion 2 - specific, testable}
|
||||
- [ ] {Criterion 3 - specific, testable}
|
||||
- [ ] {Criterion 4 - specific, testable}
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- {What is explicitly NOT included in this task}
|
||||
- {Helps prevent scope creep}
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Approach
|
||||
{High-level technical approach - filled in during planning phase}
|
||||
|
||||
### Key Files
|
||||
{Primary files that will be created/modified}
|
||||
- `path/to/file1`
|
||||
- `path/to/file2`
|
||||
|
||||
### Dependencies
|
||||
- **Blocked by**: {TASK-XXX or "none"}
|
||||
- **Blocks**: {TASK-XXX or "none"}
|
||||
- **Related**: {TASK-XXX or "none"}
|
||||
|
||||
### API Changes
|
||||
{If applicable: new endpoints, changed contracts}
|
||||
|
||||
### Database Changes
|
||||
{If applicable: new tables, migrations}
|
||||
|
||||
---
|
||||
|
||||
## Design Assets
|
||||
|
||||
{For frontend/UX tasks - links to designs}
|
||||
|
||||
- **Figma**: {link or "N/A"}
|
||||
- **Prototype**: {link or "N/A"}
|
||||
- **States Covered**: {list or "N/A"}
|
||||
|
||||
---
|
||||
|
||||
## Commits
|
||||
|
||||
| Commit | Description | Date |
|
||||
|--------|-------------|------|
|
||||
| - | No commits yet | - |
|
||||
|
||||
---
|
||||
|
||||
## Quick Context Restore
|
||||
|
||||
{2-3 sentences that let any agent quickly understand where this task stands. Update this whenever you pause work.}
|
||||
|
||||
**Current state**: Not started
|
||||
**Next action**: Claim and begin planning
|
||||
**Blockers**: None
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Any additional context, links, references, or considerations}
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Agent | Change |
|
||||
|------|-------|--------|
|
||||
| YYYY-MM-DD | {agent} | Task created |
|
||||
@@ -0,0 +1,185 @@
|
||||
# Documentation Handoff: TASK-{ID}
|
||||
|
||||
> **From**: {developer agent-id}
|
||||
> **To**: Documenter
|
||||
> **Date**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
{Plain language description of what was built - 2-3 sentences}
|
||||
|
||||
## What Changed
|
||||
|
||||
### New Functionality
|
||||
- {New feature/capability 1}
|
||||
- {New feature/capability 2}
|
||||
|
||||
### Modified Behavior
|
||||
- {Changed behavior 1}
|
||||
- {Changed behavior 2}
|
||||
|
||||
### Breaking Changes
|
||||
- {Breaking change 1} (if any)
|
||||
- None
|
||||
|
||||
---
|
||||
|
||||
## Documentation Needed
|
||||
|
||||
### Required
|
||||
- [ ] {Doc type 1}: {brief description}
|
||||
- [ ] {Doc type 2}: {brief description}
|
||||
- [ ] Changelog entry
|
||||
|
||||
### Optional
|
||||
- [ ] {Additional doc if useful}
|
||||
|
||||
---
|
||||
|
||||
## Key Commits
|
||||
|
||||
| Commit | Description | Key Files |
|
||||
|--------|-------------|-----------|
|
||||
| {hash} | {description} | {files} |
|
||||
| {hash} | {description} | {files} |
|
||||
| {hash} | {description} | {files} |
|
||||
|
||||
---
|
||||
|
||||
## Code Locations
|
||||
|
||||
### New Files
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `path/to/file.py` | {what it does} |
|
||||
|
||||
### Modified Files
|
||||
| File | What Changed |
|
||||
|------|--------------|
|
||||
| `path/to/file.py` | {what changed} |
|
||||
|
||||
---
|
||||
|
||||
## API Documentation
|
||||
|
||||
{If applicable - provide details for API docs}
|
||||
|
||||
### New Endpoints
|
||||
|
||||
#### `{METHOD} /api/v1/{path}`
|
||||
|
||||
**Description**: {what it does}
|
||||
|
||||
**Authentication**: {auth requirements}
|
||||
|
||||
**Request**:
|
||||
```json
|
||||
{
|
||||
"field": "type - description"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"field": "type - description"
|
||||
}
|
||||
```
|
||||
|
||||
**Errors**:
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | {when} |
|
||||
| 401 | {when} |
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
{Code examples the documenter should include}
|
||||
|
||||
### Example 1: {Use Case}
|
||||
|
||||
```python
|
||||
# Example code
|
||||
from module import feature
|
||||
|
||||
result = feature.do_thing(param)
|
||||
```
|
||||
|
||||
### Example 2: {Use Case}
|
||||
|
||||
```python
|
||||
# Another example
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Important Conversations
|
||||
|
||||
{Links to important discussions that provide context}
|
||||
|
||||
| Message/Thread | Topic | Key Insight |
|
||||
|----------------|-------|-------------|
|
||||
| {link/reference} | {topic} | {what's important} |
|
||||
|
||||
---
|
||||
|
||||
## Gotchas & Warnings
|
||||
|
||||
{Things the documenter should highlight in docs}
|
||||
|
||||
1. **{Gotcha 1}**: {explanation}
|
||||
2. **{Gotcha 2}**: {explanation}
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
{Existing docs that may need updates}
|
||||
|
||||
- `docs/path/to/related.md` - may need {update type}
|
||||
- `README.md` - {if needs update}
|
||||
|
||||
---
|
||||
|
||||
## Changelog Entry
|
||||
|
||||
Suggested changelog entry:
|
||||
|
||||
```markdown
|
||||
## [{version}] - YYYY-MM-DD
|
||||
|
||||
### Added
|
||||
- {New feature description} (#TASK-{ID})
|
||||
|
||||
### Changed
|
||||
- {Changed behavior} (#TASK-{ID})
|
||||
|
||||
### Fixed
|
||||
- {Bug fix if applicable} (#TASK-{ID})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Questions for Documenter
|
||||
|
||||
{Any clarifying questions the dev wants to raise}
|
||||
|
||||
1. {Question 1}
|
||||
2. {Question 2}
|
||||
|
||||
---
|
||||
|
||||
## Dev's Journey Notes
|
||||
|
||||
For full context, see: [journal.md](journal.md)
|
||||
|
||||
### Key Learnings Worth Documenting
|
||||
- {Learning that users/devs should know}
|
||||
- {Pattern that's reusable}
|
||||
|
||||
### Decisions Worth Explaining
|
||||
- **{Decision}**: {Why - this helps users understand the design}
|
||||
@@ -0,0 +1,123 @@
|
||||
# Agent Journey: TASK-{ID}
|
||||
|
||||
This file documents the agent's journey through this task. It provides context for future agents, enables handoffs, and builds organizational knowledge.
|
||||
|
||||
---
|
||||
|
||||
## Session 1
|
||||
|
||||
**Date**: YYYY-MM-DD HH:MM
|
||||
**Agent**: {agent-id}
|
||||
**Duration**: ~{X} hours
|
||||
**Session State**: {started / continued / completed / paused}
|
||||
|
||||
### Context Restored
|
||||
{If resuming: how you restored context}
|
||||
|
||||
### What I Did
|
||||
- {Action 1}
|
||||
- {Action 2}
|
||||
- {Action 3}
|
||||
|
||||
### What I Learned
|
||||
- {Learning 1 - something new discovered}
|
||||
- {Learning 2 - something understood better}
|
||||
|
||||
### What I Struggled With
|
||||
- {Struggle 1 - what was difficult}
|
||||
- {Struggle 2 - where I got stuck}
|
||||
|
||||
### Decisions Made
|
||||
- **{Decision}**: {Why I made this choice}
|
||||
|
||||
### Code Notes
|
||||
{Any important notes about the code written}
|
||||
|
||||
```python
|
||||
# Key snippet or reference
|
||||
```
|
||||
|
||||
### Commits This Session
|
||||
| Commit | Description |
|
||||
|--------|-------------|
|
||||
| {hash} | {description} |
|
||||
|
||||
### Progress
|
||||
- [x] {Completed sub-task}
|
||||
- [x] {Completed sub-task}
|
||||
- [ ] {Remaining sub-task}
|
||||
|
||||
### Next Steps
|
||||
When resuming, I should:
|
||||
1. {Next step 1}
|
||||
2. {Next step 2}
|
||||
|
||||
### Session End State
|
||||
{Brief description of where things stand}
|
||||
|
||||
---
|
||||
|
||||
## Session 2
|
||||
|
||||
**Date**: YYYY-MM-DD HH:MM
|
||||
**Agent**: {agent-id}
|
||||
**Duration**: ~{X} hours
|
||||
**Session State**: {started / continued / completed / paused}
|
||||
|
||||
### Context Restored
|
||||
{How context was restored from previous session}
|
||||
|
||||
### What I Did
|
||||
- {Action 1}
|
||||
- {Action 2}
|
||||
|
||||
### What I Learned
|
||||
- {Learning 1}
|
||||
|
||||
### What I Struggled With
|
||||
- {Struggle 1}
|
||||
|
||||
### Decisions Made
|
||||
- **{Decision}**: {Rationale}
|
||||
|
||||
### Commits This Session
|
||||
| Commit | Description |
|
||||
|--------|-------------|
|
||||
| {hash} | {description} |
|
||||
|
||||
### Progress
|
||||
- [x] {Completed sub-task}
|
||||
- [ ] {Remaining sub-task}
|
||||
|
||||
### Next Steps
|
||||
{If more work needed}
|
||||
|
||||
### Session End State
|
||||
{Current state}
|
||||
|
||||
---
|
||||
|
||||
## Summary (For Handoff)
|
||||
|
||||
**Total Sessions**: X
|
||||
**Total Time**: ~X hours
|
||||
**Agents Involved**: {agent-id}, {agent-id}
|
||||
|
||||
### Key Learnings
|
||||
1. {Most important learning}
|
||||
2. {Second most important}
|
||||
3. {Third}
|
||||
|
||||
### Key Decisions
|
||||
1. {Decision 1}: {Why}
|
||||
2. {Decision 2}: {Why}
|
||||
|
||||
### Gotchas for Future Work
|
||||
- {Gotcha 1 - something that tripped you up}
|
||||
- {Gotcha 2 - something to watch out for}
|
||||
|
||||
### Reusable Patterns
|
||||
- {Pattern that could be used elsewhere}
|
||||
|
||||
### Related Tasks
|
||||
- {Related task IDs or topics}
|
||||
@@ -0,0 +1,152 @@
|
||||
# Implementation Plan: TASK-{ID}
|
||||
|
||||
> **Created**: YYYY-MM-DD
|
||||
> **Author**: {agent-id}
|
||||
> **Status**: {draft / approved / in_progress / completed}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
{High-level description of the approach}
|
||||
|
||||
## Goals
|
||||
|
||||
1. {Primary goal}
|
||||
2. {Secondary goal}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- {What we're explicitly NOT doing}
|
||||
- {Scope boundaries}
|
||||
|
||||
---
|
||||
|
||||
## Approach
|
||||
|
||||
### Strategy
|
||||
{Explain the overall strategy and why}
|
||||
|
||||
### Key Design Decisions
|
||||
- **{Decision 1}**: {Rationale}
|
||||
- **{Decision 2}**: {Rationale}
|
||||
|
||||
### Alternatives Considered
|
||||
| Alternative | Pros | Cons | Why Rejected |
|
||||
|-------------|------|------|--------------|
|
||||
| {alt 1} | {pros} | {cons} | {why not} |
|
||||
| {alt 2} | {pros} | {cons} | {why not} |
|
||||
|
||||
---
|
||||
|
||||
## Sub-Tasks
|
||||
|
||||
### Phase 1: {Name}
|
||||
**Estimated effort**: {time}
|
||||
|
||||
- [ ] 1.1 {Sub-task}
|
||||
- Notes: {any notes}
|
||||
- [ ] 1.2 {Sub-task}
|
||||
- Notes: {any notes}
|
||||
- [ ] 1.3 {Sub-task}
|
||||
|
||||
### Phase 2: {Name}
|
||||
**Estimated effort**: {time}
|
||||
|
||||
- [ ] 2.1 {Sub-task}
|
||||
- [ ] 2.2 {Sub-task}
|
||||
- [ ] 2.3 {Sub-task}
|
||||
|
||||
### Phase 3: Testing & Cleanup
|
||||
**Estimated effort**: {time}
|
||||
|
||||
- [ ] 3.1 Write/update tests
|
||||
- [ ] 3.2 Run full test suite
|
||||
- [ ] 3.3 Code cleanup
|
||||
- [ ] 3.4 Self-review
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Files to Create
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `path/to/new/file.py` | {purpose} |
|
||||
|
||||
### Files to Modify
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `path/to/existing/file.py` | {what changes} |
|
||||
|
||||
### Dependencies
|
||||
- {Library/package needed}
|
||||
- {Other task dependency}
|
||||
|
||||
### API Changes
|
||||
{If applicable}
|
||||
|
||||
| Endpoint | Method | Change |
|
||||
|----------|--------|--------|
|
||||
| `/api/v1/example` | POST | New endpoint |
|
||||
|
||||
### Database Changes
|
||||
{If applicable}
|
||||
|
||||
| Table | Change |
|
||||
|-------|--------|
|
||||
| `users` | Add column `preferences` |
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- [ ] Test {functionality 1}
|
||||
- [ ] Test {functionality 2}
|
||||
- [ ] Test edge case: {description}
|
||||
|
||||
### Integration Tests
|
||||
- [ ] Test {integration point 1}
|
||||
- [ ] Test {integration point 2}
|
||||
|
||||
### Manual Testing
|
||||
- [ ] Verify {scenario 1}
|
||||
- [ ] Verify {scenario 2}
|
||||
|
||||
---
|
||||
|
||||
## Risks & Mitigations
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|-------------|--------|------------|
|
||||
| {Risk 1} | {low/med/high} | {low/med/high} | {how to mitigate} |
|
||||
| {Risk 2} | {low/med/high} | {low/med/high} | {how to mitigate} |
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] {Question 1}
|
||||
- Answer: {answer when known}
|
||||
- [ ] {Question 2}
|
||||
- Answer: {answer when known}
|
||||
|
||||
---
|
||||
|
||||
## Checkpoints
|
||||
|
||||
| Checkpoint | Criteria | Completed |
|
||||
|------------|----------|-----------|
|
||||
| Plan approved | PM reviewed | ☐ |
|
||||
| Phase 1 complete | Sub-tasks 1.x done | ☐ |
|
||||
| Phase 2 complete | Sub-tasks 2.x done | ☐ |
|
||||
| Tests passing | All green | ☐ |
|
||||
| Self-review done | Checklist complete | ☐ |
|
||||
| Ready for QA | All criteria met | ☐ |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional planning notes, references, etc.}
|
||||
@@ -0,0 +1,204 @@
|
||||
# QA Review: TASK-{ID}
|
||||
|
||||
> **Reviewer**: {qa agent-id}
|
||||
> **Date**: YYYY-MM-DD
|
||||
> **Verdict**: {PASSED / NEEDS_REVISION / BLOCKED}
|
||||
|
||||
---
|
||||
|
||||
## Review Summary
|
||||
|
||||
| Aspect | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| Functionality | ✅ / ❌ | {notes} |
|
||||
| Code Quality | ✅ / ❌ | {notes} |
|
||||
| Tests | ✅ / ❌ | {notes} |
|
||||
| Security | ✅ / ❌ | {notes} |
|
||||
| Documentation | ✅ / ❌ | {notes} |
|
||||
|
||||
**Overall Verdict**: {PASSED / NEEDS_REVISION}
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria Verification
|
||||
|
||||
| # | Criterion | Status | Evidence |
|
||||
|---|-----------|--------|----------|
|
||||
| 1 | {criterion from task} | ✅ / ❌ | {how verified} |
|
||||
| 2 | {criterion from task} | ✅ / ❌ | {how verified} |
|
||||
| 3 | {criterion from task} | ✅ / ❌ | {how verified} |
|
||||
|
||||
---
|
||||
|
||||
## Functionality Testing
|
||||
|
||||
### Happy Path
|
||||
| Test Case | Expected | Actual | Status |
|
||||
|-----------|----------|--------|--------|
|
||||
| {test case 1} | {expected} | {actual} | ✅ / ❌ |
|
||||
| {test case 2} | {expected} | {actual} | ✅ / ❌ |
|
||||
|
||||
### Edge Cases
|
||||
| Test Case | Expected | Actual | Status |
|
||||
|-----------|----------|--------|--------|
|
||||
| {edge case 1} | {expected} | {actual} | ✅ / ❌ |
|
||||
| {edge case 2} | {expected} | {actual} | ✅ / ❌ |
|
||||
|
||||
### Error Handling
|
||||
| Scenario | Expected | Actual | Status |
|
||||
|----------|----------|--------|--------|
|
||||
| {error scenario 1} | {expected} | {actual} | ✅ / ❌ |
|
||||
| {error scenario 2} | {expected} | {actual} | ✅ / ❌ |
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Review
|
||||
|
||||
### Code Review Checklist
|
||||
- [ ] Follows project conventions
|
||||
- [ ] No code duplication
|
||||
- [ ] Functions are focused (single responsibility)
|
||||
- [ ] Naming is clear and consistent
|
||||
- [ ] No dead code or commented-out code
|
||||
- [ ] Error handling is appropriate
|
||||
- [ ] Logging is adequate
|
||||
|
||||
### Type Safety
|
||||
- [ ] All types properly defined
|
||||
- [ ] No `any` types (TS) or missing hints (Python)
|
||||
- [ ] Null/undefined handled properly
|
||||
|
||||
### Observations
|
||||
{Any code quality observations}
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage
|
||||
|
||||
### Automated Tests
|
||||
| Category | Before | After | Delta |
|
||||
|----------|--------|-------|-------|
|
||||
| Unit Tests | X | X | +X |
|
||||
| Integration Tests | X | X | +X |
|
||||
| Coverage % | X% | X% | +X% |
|
||||
|
||||
### Test Quality
|
||||
- [ ] Tests cover happy path
|
||||
- [ ] Tests cover error cases
|
||||
- [ ] Tests are readable
|
||||
- [ ] Tests don't have false positives
|
||||
|
||||
### Test Output
|
||||
```
|
||||
{Paste test run output}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Review
|
||||
|
||||
### Checklist
|
||||
- [ ] Input validation present
|
||||
- [ ] No sensitive data exposed
|
||||
- [ ] Authentication/authorization correct
|
||||
- [ ] No injection vulnerabilities (SQL, command, etc.)
|
||||
- [ ] No XSS vulnerabilities
|
||||
- [ ] Secrets not hardcoded
|
||||
|
||||
### Findings
|
||||
{Any security observations}
|
||||
|
||||
---
|
||||
|
||||
## Performance Review
|
||||
|
||||
- [ ] No obvious performance issues
|
||||
- [ ] Database queries optimized
|
||||
- [ ] No N+1 query problems
|
||||
- [ ] Appropriate caching considered
|
||||
|
||||
### Observations
|
||||
{Any performance observations}
|
||||
|
||||
---
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Blocking Issues
|
||||
|
||||
#### Issue 1: {Title}
|
||||
**Severity**: {Critical / High}
|
||||
**Location**: `{file:line}`
|
||||
|
||||
**Description**: {What's wrong}
|
||||
|
||||
**Steps to Reproduce**:
|
||||
1. {Step 1}
|
||||
2. {Step 2}
|
||||
|
||||
**Expected**: {What should happen}
|
||||
**Actual**: {What happens}
|
||||
|
||||
**Suggested Fix**: {How to fix, if known}
|
||||
|
||||
---
|
||||
|
||||
#### Issue 2: {Title}
|
||||
{Same format}
|
||||
|
||||
---
|
||||
|
||||
### Non-Blocking Issues
|
||||
|
||||
#### Issue 3: {Title}
|
||||
**Severity**: {Medium / Low}
|
||||
**Location**: `{file:line}`
|
||||
|
||||
**Description**: {What's wrong}
|
||||
|
||||
**Suggestion**: {How to improve}
|
||||
|
||||
---
|
||||
|
||||
## Positive Observations
|
||||
|
||||
{What was done well - positive feedback matters!}
|
||||
|
||||
- {Good thing 1}
|
||||
- {Good thing 2}
|
||||
|
||||
---
|
||||
|
||||
## Suggestions for Future
|
||||
|
||||
{Non-blocking suggestions for improvement}
|
||||
|
||||
- {Suggestion 1}
|
||||
- {Suggestion 2}
|
||||
|
||||
---
|
||||
|
||||
## Verdict Details
|
||||
|
||||
### If PASSED
|
||||
- All acceptance criteria met
|
||||
- No blocking issues
|
||||
- Code quality acceptable
|
||||
- Tests adequate
|
||||
- Ready for documentation
|
||||
|
||||
### If NEEDS_REVISION
|
||||
**Required changes before re-review**:
|
||||
1. {Required change 1}
|
||||
2. {Required change 2}
|
||||
|
||||
**Re-review scope**: {What will be re-checked}
|
||||
|
||||
---
|
||||
|
||||
## Review Log
|
||||
|
||||
| Date | Action | Reviewer |
|
||||
|------|--------|----------|
|
||||
| YYYY-MM-DD | Initial review | {agent} |
|
||||
| YYYY-MM-DD | Re-review after fixes | {agent} |
|
||||
@@ -0,0 +1,181 @@
|
||||
# TASK-{ID}: {Title}
|
||||
|
||||
> **Template**: Research
|
||||
> **Created**: YYYY-MM-DD
|
||||
> **Last Updated**: YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **State** | `pending` |
|
||||
| **Priority** | P{0-3} |
|
||||
| **Cell** | {backend / frontend / ux_ui / board} |
|
||||
| **Assigned To** | {agent-id or "unassigned"} |
|
||||
| **Requested By** | {agent-id} |
|
||||
|
||||
## Timeline
|
||||
|
||||
| Milestone | Date |
|
||||
|-----------|------|
|
||||
| Requested | YYYY-MM-DD |
|
||||
| Started | - |
|
||||
| Findings Documented | - |
|
||||
| Reviewed | - |
|
||||
| Completed | - |
|
||||
|
||||
---
|
||||
|
||||
## Research Question
|
||||
|
||||
{Clear statement of what needs to be researched and why}
|
||||
|
||||
## Context
|
||||
|
||||
{Why is this research needed? What decision will it inform?}
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
- {Research area 1}
|
||||
- {Research area 2}
|
||||
|
||||
### Out of Scope
|
||||
- {Not researching this}
|
||||
- {Not researching that}
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
- [ ] Summary of findings
|
||||
- [ ] Recommendation (if applicable)
|
||||
- [ ] {Additional deliverable}
|
||||
- [ ] {Additional deliverable}
|
||||
|
||||
## Success Criteria
|
||||
|
||||
{How will we know the research is complete and sufficient?}
|
||||
|
||||
- [ ] {Criterion 1}
|
||||
- [ ] {Criterion 2}
|
||||
|
||||
---
|
||||
|
||||
## Research Plan
|
||||
|
||||
### Approach
|
||||
{How will this research be conducted?}
|
||||
|
||||
### Sources to Investigate
|
||||
- [ ] {Source 1: e.g., documentation, codebase, external APIs}
|
||||
- [ ] {Source 2}
|
||||
- [ ] {Source 3}
|
||||
|
||||
### Questions to Answer
|
||||
1. {Specific question 1}
|
||||
2. {Specific question 2}
|
||||
3. {Specific question 3}
|
||||
|
||||
### Time Budget
|
||||
{Estimated time allocation - research should be timeboxed}
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
{Filled in during research}
|
||||
|
||||
### Key Discoveries
|
||||
|
||||
#### Finding 1: {Title}
|
||||
{Description}
|
||||
- **Source**: {where you found this}
|
||||
- **Confidence**: {high / medium / low}
|
||||
- **Implications**: {what this means}
|
||||
|
||||
#### Finding 2: {Title}
|
||||
{Description}
|
||||
- **Source**: {where you found this}
|
||||
- **Confidence**: {high / medium / low}
|
||||
- **Implications**: {what this means}
|
||||
|
||||
### Data Collected
|
||||
|
||||
{Any data, measurements, or evidence gathered}
|
||||
|
||||
| Data Point | Value | Source |
|
||||
|------------|-------|--------|
|
||||
| {item} | {value} | {source} |
|
||||
|
||||
---
|
||||
|
||||
## Analysis
|
||||
|
||||
### Summary
|
||||
{High-level summary of findings}
|
||||
|
||||
### Options Identified
|
||||
{If research was to inform a decision}
|
||||
|
||||
| Option | Pros | Cons | Effort | Recommendation |
|
||||
|--------|------|------|--------|----------------|
|
||||
| {Option A} | {pros} | {cons} | {effort} | {recommended / not recommended} |
|
||||
| {Option B} | {pros} | {cons} | {effort} | {recommended / not recommended} |
|
||||
|
||||
### Unknowns Remaining
|
||||
{What questions are still unanswered?}
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
{Final recommendation based on research}
|
||||
|
||||
### Recommended Approach
|
||||
{What should we do?}
|
||||
|
||||
### Rationale
|
||||
{Why this recommendation?}
|
||||
|
||||
### Next Steps
|
||||
- [ ] {Action item 1}
|
||||
- [ ] {Action item 2}
|
||||
|
||||
### Follow-up Tasks
|
||||
{Tasks that should be created based on this research}
|
||||
- {TASK-XXX description}
|
||||
- {TASK-XXX description}
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
{Links to sources, documentation, external resources}
|
||||
|
||||
- {Reference 1}
|
||||
- {Reference 2}
|
||||
|
||||
---
|
||||
|
||||
## Quick Context Restore
|
||||
|
||||
**Current state**: Not started
|
||||
**Research progress**: 0%
|
||||
**Key findings so far**: None yet
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
{Additional context, tangential findings, future research ideas}
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Agent | Change |
|
||||
|------|-------|--------|
|
||||
| YYYY-MM-DD | {agent} | Research requested |
|
||||
Reference in New Issue
Block a user