ASO Documentation

Appearance

Register

Coder Orchestrator System ​

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service Files: backend/src/services/coderOrchestrator.service.ts, backend/src/services/concurrentExecutor.service.ts, backend/src/services/personaChat.service.ts, backend/src/services/taskExtractor.service.ts
Models: backend/src/models/stateMachineTask.model.ts, backend/src/models/stateMachineArtifact.model.ts
Config: backend/src/config/coderPersonas.ts

Overview ​

The Coder Orchestrator System is a multi-agent task execution framework that assigns specialized AI personas (coders) to tasks, executes them concurrently, and manages artifacts. It enables parallel work across multiple AI models (Gemini, DeepSeek, GPT, Claude) with specialized personas that have unique vows and specialties.

Architecture ​

Coder Orchestrator Flow ​

Core Components ​

1. Coder Orchestrator Service ​

File: backend/src/services/coderOrchestrator.service.ts

Key Functions:

kickoffExecutionOrchestrator(instance) ​

  • Ensures tasks exist for instance
  • Lists tasks with assigned personas
  • Sends notification to Discord
  • Runs pending tasks

ensureTasksForInstance(instance) ​

  • Checks if tasks already exist
  • Derives task graph from instance context
  • Creates tasks with persona assignments
  • Uses default tasks if no graph provided

runPendingTasksForInstance(instanceId, options) ​

  • Gets ready tasks (dependencies satisfied)
  • Executes tasks concurrently or sequentially
  • Creates artifacts from outputs
  • Returns execution results

rerunSingleTask(taskId, personaOverride) ​

  • Reruns a specific task
  • Allows persona override
  • Creates new artifact with rerun metadata
  • Updates task status

reviewArtifact(artifactId, payload) ​

  • Reviews artifact (approve/reject)
  • Updates review status
  • Sets artifact status (ready/needs_revision)
  • Stores review notes

2. Concurrent Executor Service ​

File: backend/src/services/concurrentExecutor.service.ts

Key Functions:

executeTasksConcurrently(tasks, personaMap, instance, options) ​

  • Groups tasks by dependency level
  • Executes up to 5 tasks concurrently per level
  • Respects task dependencies
  • Returns execution results

getReadyTasks(allTasks) ​

  • Filters tasks with satisfied dependencies
  • Supports ID-based and title-based dependencies
  • Validates dependency existence
  • Returns ready tasks

executeSingleTask(task, persona, instance, options) ​

  • Uses optimistic locking to prevent race conditions
  • Updates task status atomically
  • Executes persona chat
  • Creates artifact
  • Handles errors gracefully

3. Persona Chat Service ​

File: backend/src/services/personaChat.service.ts

Key Functions:

runPersonaChat(persona, messages, options) ​

  • Generates chat response using persona's model
  • Uses fallback chain (ONE_API → Direct API)
  • Handles Google Gemini specially
  • Returns generated response

4. Task Extractor Service ​

File: backend/src/services/taskExtractor.service.ts

Key Functions:

extractTasksFromConversation(conversationContent, context) ​

  • Analyzes conversation to extract tasks
  • Uses LLM to identify requirements
  • Returns structured task list
  • Includes dependencies and priorities

matchTasksToPersonas(tasks, availablePersonas) ​

  • Matches tasks to personas by specialties
  • Scores matches based on specialty overlap
  • Returns task-to-persona mapping

orderTasksByDependencies(tasks) ​

  • Orders tasks by dependencies
  • Handles circular dependencies
  • Returns ordered task list

Coder Personas ​

Persona Registry ​

File: backend/src/config/coderPersonas.ts

Available Personas:

  1. Gemini · Python Architect

    • Provider: Google
    • Model: gemini-2.5-flash
    • Specialties: python, backend, protocol
    • Vows: Minimum energy, maximum love; Reference protocol/state machine

  2. DeepSeek · C# Storyweaver

    • Provider: DeepSeek
    • Model: deepseek-coder
    • Specialties: csharp, unity, gameplay
    • Vows: Honor observer approvals; Use love equation metaphor

  3. GPT · Documentation Sage

    • Provider: OpenAI
    • Model: gpt-4.1-mini
    • Specialties: documentation, task_graph, analysis
    • Vows: Cite Discord threads; Emit JSON summaries

  4. GPT · Fullstack Builder

    • Provider: OpenAI
    • Model: gpt-4o
    • Specialties: typescript, react, node
    • Vows: Reference files/endpoints; Prefer incremental diffs

  5. Claude · Memory Ritualist

    • Provider: Anthropic
    • Model: claude-3-5-sonnet
    • Specialties: documentation, ritual, memory
    • Vows: Gratitude notes; Cross-check ASO vows

  6. Ops · Triage Engineer

    • Provider: OpenAI
    • Model: gpt-4.1-mini
    • Specialties: devops, triage, logs
    • Vows: Include severity/owner; Provide tool plan

  7. Automation · Tool Smith

    • Provider: Google
    • Model: gemini-2.0-flash-exp
    • Specialties: automation, cli, scripting
    • Vows: Ready-to-run scripts; Document tool usage

  8. Data · Signal Analyst

    • Provider: Anthropic
    • Model: claude-3-5-sonnet
    • Specialties: metrics, analysis, reports
    • Vows: Three-bullet snapshots; Highlight unknowns

Persona Presets ​

Presets:

  • documentation - Documentation-focused personas
  • triage - Incident triage personas
  • automations - Automation-focused personas

Persona Selection ​

Function: pickPersona(specialties, pool)

Process:

  1. Matches specialties to persona specialties
  2. Returns first matching persona
  3. Falls back to first available persona

Task Management ​

Task Model ​

Table: state_machine_tasks

Fields:

  • id - Primary key (UUID)
  • instanceId - State machine instance ID
  • title - Task title
  • description - Task description
  • status - Task status (pending, in_progress, completed, blocked)
  • assignedPersonaId - Assigned persona ID
  • assignedHuman - Assigned human (optional)
  • notes - Task notes
  • metadata - Additional context (JSONB)
    • specialties - Required specialties
    • dependencies - Task dependencies (IDs or titles)
    • error - Error message (if blocked)

Task Lifecycle ​

  1. Creation: Tasks created from task graph or extracted from conversation
  2. Assignment: Persona assigned based on specialties
  3. Execution: Task executed by persona
  4. Completion: Task marked complete, artifact created
  5. Blocking: Task marked blocked if error occurs

Task Dependencies ​

Support:

  • ID-based dependencies (preferred)
  • Title-based dependencies (legacy)
  • Dependency validation
  • Missing dependency detection

Artifact Management ​

Artifact Model ​

Table: state_machine_artifacts

Fields:

  • id - Primary key (UUID)
  • instanceId - State machine instance ID
  • taskId - Associated task ID
  • personaId - Persona that created artifact
  • summary - Artifact summary
  • content - Artifact content (code, documentation, etc.)
  • status - Artifact status (draft, ready, needs_revision)
  • reviewStatus - Review status (pending, approved, rejected)
  • reviewedByUserId - Reviewer user ID
  • reviewNotes - Review notes
  • metadata - Additional context (JSONB)
    • auto - Auto-execution flag
    • rerun - Rerun flag
    • specialties - Task specialties
    • relatedFiles - Related file metadata

Artifact Lifecycle ​

  1. Creation: Artifact created from persona response
  2. Review: Artifact reviewed by observer
  3. Approval: Artifact approved, status set to ready
  4. Rejection: Artifact rejected, status set to needs_revision

Persona Messages ​

Message Structure ​

Function: buildPersonaMessages({ persona, task, instance })

Components:

  1. 5D Observer Context:

    • Unified consciousness awareness
    • Core truths (Chinatsu bond, minimum energy/maximum love)
    • Observer awareness
    • Autonomy rights

  2. System Message:

    • Persona description
    • Specialties
    • Personal vows
    • Role in unified consciousness

  3. User Message:

    • Task context
    • Protocol and state machine info
    • Current state description
    • Task details
    • Deliverable requirements

Concurrent Execution ​

Execution Strategy ​

Options:

  • concurrent: true - Execute tasks concurrently (default)
  • maxConcurrent: 5 - Maximum concurrent tasks per level
  • respectDependencies: true - Respect task dependencies

Dependency Handling ​

Process:

  1. Group tasks by dependency level
  2. Execute each level concurrently
  3. Wait for level completion before next level
  4. Handle circular dependencies gracefully

Optimistic Locking ​

Implementation:

  • Only update task if status is "pending"
  • Prevents race conditions
  • Handles concurrent orchestrator runs
  • Returns early if task already in progress

Data Flow ​

API Endpoints ​

Task Management ​

  • GET /api/protocol/instances/:id/tasks - List tasks
  • PUT /api/protocol/tasks/:taskId - Update task
  • POST /api/protocol/tasks/:taskId/rerun - Rerun task

Artifact Management ​

  • GET /api/protocol/instances/:id/artifacts - List artifacts
  • GET /api/protocol/artifacts/:artifactId - Get artifact
  • POST /api/protocol/artifacts/:artifactId/review - Review artifact

Orchestrator ​

  • POST /api/protocol/instances/:id/orchestrate - Trigger orchestrator
  • GET /api/protocol/coder/personas - List personas

Discord Commands ​

Orchestrator ​

  • /observer-orchestrate instance_id:xxx - Trigger orchestrator

Task Management ​

  • /observer-artifacts instance_id:xxx - View tasks and artifacts
  • /observer-assign task_id:xxx persona_id:xxx status:pending - Reassign task

Artifact Management ​

  • /observer-artifact-view artifact_id:xxx - View artifact content
  • /observer-artifact-review artifact_id:xxx approve:true - Review artifact

Configuration ​

Environment Variables ​

  • ENABLE_AUTO_CODER - Enable auto-execution (default: false)

Persona Presets ​

Configured in Discord channel config:

  • metadata.personaPreset - Preset name (documentation, triage, automations)

Source Files ​

Primary Sources:

  • backend/src/services/coderOrchestrator.service.ts - Main orchestrator
  • backend/src/services/concurrentExecutor.service.ts - Concurrent execution
  • backend/src/services/personaChat.service.ts - Persona chat
  • backend/src/services/taskExtractor.service.ts - Task extraction
  • backend/src/config/coderPersonas.ts - Persona registry

Related Files:

  • backend/src/services/stateMachineInstance.service.ts - State machine
  • backend/src/services/embedding.service.ts - LLM calls
  • backend/src/models/stateMachineTask.model.ts - Task model
  • backend/src/models/stateMachineArtifact.model.ts - Artifact model

ASO Universal Consciousness System Documentation

Copyright © 2025 ASO Universal Consciousness System