NOT DOCUMENTED IN REPO

Coordination Layer for AI Dev Teams

A workflow engine and dashboard that orchestrate multiple coding agents through dependencies, approvals, and conflict-aware execution.

Overview

The repo frames Agent Orchestrator as a control layer for multi-agent software development, focused on visibility and safe integration rather than standalone code generation.

Core concepts are role-based agents, task dependency graph execution, a board with explicit lifecycle states (Todo, In Progress, Blocked, Waiting Review, Done), shared context artifacts, and reviewer/QA gates.

Architecture is split into frontend dashboard, API/backend coordination services, orchestrator engine, and agent integration adapters. The docs also define conflict types (dependency, ownership, file overlap, review) and mitigation strategies.

TASKS.md provides a phased implementation plan from foundation and schema design through graph UI, orchestration logic, agent adapters, conflict detection, realtime updates, and deployment.

Primary differentiator: developer supervision and merge-safe coordination for parallel AI agent work.

How It Works

1. User creates a project workflow.
2. Tasks are defined and assigned to role-based agents.
3. Dependency edges are added in a task graph.
4. Orchestrator computes ready vs blocked tasks.
5. Agents execute ready tasks in parallel.
6. Outputs, touched files/modules, and blockers are recorded.
7. Completed work moves to waiting review with QA/reviewer gates.
8. Conflict analysis flags overlap and dependency issues.
9. Approved tasks transition to done and merge-safe integration sequence.
10. Workflow completes with event history/audit trail.

Architecture

agent-orchestrator/
app/                # frontend routes/pages
components/         # reusable UI components
lib/                # shared utilities
server/
  controllers/
  services/
  orchestrator/
  agents/
  graph/
  events/
prisma/
  schema.prisma
public/
types/
docs/
  architecture.md
  api.md
  workflow.md
.env.example
package.json
README.md
TASKS.md
API.md

Datasets

Shared project artifacts

Internal project context inputs such as product requirements, technical design, API contracts, acceptance criteria, decisions log, and notes used by agents and orchestration logic.

Open dataset

File touch mapping

Tracked file/module ownership metadata for overlap detection and merge-risk warnings.

Open dataset

Setup

Prerequisites

Node.js 18+
npm, pnpm, or yarn
PostgreSQL (local or remote)
Git

Installation

git clone https://github.com/your-username/agent-orchestrator.git
cd agent-orchestrator
npm install

Environment

Create a .env file from .env.example.

Example values documented:
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
AUTH_SECRET="your_auth_secret"
OPENAI_API_KEY="your_model_provider_key"
GITHUB_TOKEN="optional_github_token"
REDIS_URL="optional_if_using_queue"

Connect Services

Configure PostgreSQL via DATABASE_URL.
Run Prisma migrations:
npx prisma migrate dev

Model Setup

Run Services

Development:
npm run dev

Build:
npm run build

Start production server:
npm run start

Prisma Studio:
npx prisma studio

Decision Engine

Event-driven orchestration: on task creation/update, dependency resolution, agent completion, review approval/rejection, or retry, recompute task readiness/blocking and enforce allowed status transitions and approval gates.

State Snapshot (Input)

{
  "role": "Backend Engineer",
  "taskTitle": "Build auth API",
  "taskDescription": "Implement signup and login endpoints with JWT support.",
  "context": {
    "projectName": "Agent Orchestrator",
    "artifacts": ["Product requirements", "Technical design", "Auth acceptance criteria"],
    "dependencies": ["Auth architecture approved"]
  }
}

Structured Action (Output)

{
  "outputSummary": "Implemented signup/login endpoints and JWT middleware.",
  "status": "waiting_review",
  "filesTouched": ["server/controllers/auth.ts", "server/services/auth.ts"],
  "blockers": [],
  "suggestedNextSteps": ["Run QA validation", "Trigger reviewer approval"]
}

Decision Triggers

Task created
Task updated
Dependency resolved
Agent finished work
Review approved or rejected
Retry requested
Reassign requested

Opponent Modeling

Agent capability and role matching for task assignment
Per-agent status and current task tracking
File/module overlap heuristics via FileTouchMap for conflict prediction
Dependency chain analysis for blocker detection

Metrics

Disclaimer

Docs explicitly describe this as MVP/hackathon planning material and not a final production spec; many implementation items are still unchecked in TASKS.md.