Core Concepts

Understanding the fundamental concepts behind Codemus.

The Actor Hierarchy

Codemus uses a three-tier actor model: 

┌─────────────────────────────────────┐
│          OWNER (You)                 │
│  • Creates projects and defines goals│
│  • Approves crew proposals           │
│  • Reviews sprint deliverables       │
│  • Handles escalations               │
└──────────────┬───────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│        PM AGENT (AI)                │
│  • Proposes crew composition        │
│  • Decomposes backlog into tasks    │
│  • Dispatches tasks to specialists  │
│  • Manages revision loops           │
│  • Synthesizes results              │
└──────────────┬───────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    SPECIALIST AGENTS (AI)           │
│  • Developer    • Designer          │
│  • QA Engineer  • Custom Roles      │
│                                     │
│  ⚠️ Specialists NEVER contact       │
│     Owner directly. All             │
│     communication goes through PM   │
└─────────────────────────────────────┘

Key Entities

Entity Description Example
Project Top-level container for all work "Weather App v1.0"
Backlog Item A feature or requirement "User can view current weather"
Sprint A goal-based iteration "Deliver MVP with core features"
Task Atomic unit of work for one agent "Implement API client"
Artifact Output produced by a task Code file, design mockup
Document Input material for context Requirements PDF, API docs
Message Communication between actors PM to Specialist dispatch

Event Sourcing

Every action in Codemus creates an immutable event: 

{
  "id": "evt_12345",
  "type": "TASK_DISPATCHED",
  "timestamp": "2024-01-15T10:30:00Z",
  "actorType": "PM",
  "actorId": "role_pm_001",
  "entityType": "TASK",
  "entityId": "task_456",
  "payload": {
    "assignedTo": "role_dev_002",
    "taskTitle": "Implement Weather API client"
  }
}

This enables:

  • Complete auditability: Know exactly what happened, when, and why
  • Time travel: Go back to any point in history
  • Branching: Create "what-if" alternate timelines

Project Lifecycle

Every project follows a strict lifecycle enforced by the Agile State Machine: 

DRAFT → BACKLOG_READY → SPRINT_PLANNING → SPRINT_ACTIVE
                                                      ↓
                                    SPRINT_REVIEW → SPRINT_RETRO
                                                      ↓
                                                 COMPLETED → ARCHIVED

You cannot skip states — each transition has guard conditions that must be met. For example, you cannot start a sprint without backlog items, and you cannot review a sprint that hasn't been completed.

Visual Graph

The Graph View is the centerpiece of Codemus — a real-time visualization of your project showing:

  • All entities (projects, sprints, tasks, agents, artifacts, documents)
  • Relationships between entities (edges)
  • Real-time status updates (colors, badges, animations)
  • Message flows between agents
  • Failure chains and error propagation

The graph uses SpriteKit for smooth performance and physics-based layout algorithms.

Next Steps