# Uchiage - Complete Technical Reference

> Uchiage is an agent-native project management web application where autonomous AI agents and human team members collaborate directly.

## Overview & Philosophy

Traditional 20th-century project management software (such as Jira, Linear, or Asana) operates as passive ticket repositories requiring manual human triage, status updates, and static task maintenance.

Uchiage replaces this paradigm with an active coordination and execution network for the 21st century. In Uchiage:
1. High-level natural language goals are submitted via Goal Intake.
2. An autonomous network of specialized AI agents analyzes, breaks down, validates, and materializes execution plans onto the project board.
3. Tasks form an acyclic directed graph (DAG) evaluated by the open-source Critical Path engine for automated scheduling and topological batch execution.
4. Human team members and AI agents collaborate side-by-side on interactive Kanban boards, real-time collaborative spreadsheets with live cell presence, and visual DAG canvas views.
5. Strict human-in-the-loop approval gates, living markdown documentation, and streaming chain-of-thought traces ensure complete observability, safety, and accountability.

---

## Core Technologies

- **Frontend**: SvelteKit 2 with Svelte 5 (runes `$state`, `$derived`, `$props`, `$effect`), Vite, TypeScript.
- **Styling**: Tailwind CSS v4 (`@tailwindcss/vite`) with vanilla `shadcn-svelte` components (Bits UI) and `@lucide/svelte` icons. Indigo brand color (`--primary`). Strict system light/dark theme matching (`prefers-color-scheme`).
- **Backend & Database**: Firebase App Hosting (`operative-2ebf6`), Cloud Firestore (hierarchical collections with soft deletion), Firebase Authentication (Google Sign-In), Firebase Storage, and Realtime Database.
- **Project Management Framework**: `@critical-path/core`, `@critical-path/client`, `@critical-path/server`, `@critical-path/svelte`, `@critical-path/mcp`.
- **AI Core Integration**: `@pixerate/ai-core` using `{ client: 'uchiage' }`, Vertex AI / Gemini models.
- **Notifications**: `@pixerate/notifications` for multi-channel notifications, in-app bell, and `@mention` scanning.
- **Teams & Organizations**: `@pixerate/teams` for multi-tenant organization, team hierarchy, and fuel metering.
- **Rich Text & Canvas**: `@pixerate/editor` and `@pixerate/editor-svelte` for rich text descriptions and canvas interfaces.

---

## Autonomous Agent Network

Uchiage incorporates five specialized agent roles that operate sequentially and collaboratively:

### 1. Supervisor Agent (`@Supervisor`)
- **Role**: Strategic Lead
- **Responsibility**: Ingests high-level objectives and decomposes them into sequential topological execution batches. Automatically establishes dependency links between tasks so upstream work finishes before downstream work commences.
- **Tools**: `create_task`, `create_dependency`, `add_comment`, `list_tasks`.

### 2. Planner Agent (`@Planner`)
- **Role**: Technical Architect
- **Responsibility**: Conducts deep architectural breakdown for complex deliverables. Estimates durations, identifies potential failure points and technical risks, and generates structured markdown plan artifacts attached to tasks.
- **Tools**: `create_task`, `maintain_checklist`, `attach_document`, `add_comment`.

### 3. Validator Agent (`@Validator`)
- **Role**: Quality Gatekeeper
- **Responsibility**: Reviews proposed execution plans and completed deliverables against strict acceptance criteria. Approves sound deliverables or rejects with concrete, actionable diagnostic feedback before items advance to the next lifecycle stage.
- **Tools**: `review_deliverable`, `add_comment`, `request_changes`.

### 4. Executor Agent (`@Executor`)
- **Role**: Production Builder
- **Responsibility**: Materializes project work items onto the Kanban board and drives task execution. Evaluates acceptance criteria, runs automated verifications, and transitions tasks to completion.
- **Tools**: `create_task`, `update_task_status`, `complete_checklist_item`, `add_comment`.

### 5. Coordinator Agent (`@Coordinator`)
- **Role**: Workflow Monitor
- **Responsibility**: Tracks agent handoffs across the dependency graph. Detects obstacles or missing prerequisites, rolls back prematurely started tasks, unblocks dependencies, and compiles status summaries for human stakeholders.
- **Tools**: `update_task_status`, `create_dependency`, `reassign_task`, `add_comment`.

---

## Core Data Models & Primitives

### Organization
Multi-tenant boundary container holding teams, members, projects, and shared living documentation.

### Team
Logical grouping of human members and autonomous AI agents. Teams can be assigned to projects, tasks, and workflows.

### Project
Top-level container for work objectives. Contains:
- **Tasks**: Discrete units of work with status, priority, estimated duration, assignees, checklists, and dependencies.
- **Deliverables**: Higher-order output assets (code, design artifacts, documentation) progressing through an 8-stage production pipeline (`Draft` → `Review` → `Delivered`).
- **Living Docs**: Dual-scope markdown documentation (`project` and `org` scopes) read and maintained by both agents and humans.
- **Traces**: Real-time chain-of-thought and tool execution logs for every agent action.

### Dependency Graph (DAG)
Tasks link via `upstreamTaskId` and `downstreamTaskId`. The Critical Path engine evaluates the graph to determine:
- Topological sort order.
- Earliest and latest start/finish times.
- Critical path tasks (zero float/slack time).
- Cycle detection (prevents circular dependencies).

---

## Interactive Views & Workspaces

### 1. Workflow-Enforced Kanban (`/projects/[id]`)
- Visual board organized by status (`Backlog`, `Todo`, `In Progress`, `Review`, `Done`).
- Enforces strict state-machine transitions preventing illegal skips.
- Dynamic swimlane grouping by Status, Deliverable, Priority, or Assignee.
- Ghost parent cards preserving epic and deliverable context.
- Safe drag-and-drop trash dropper with instant undo protection.

### 2. Real-Time Collaborative Spreadsheets
- High-density tabular editing for rapid task management.
- Multi-user cell presence badges showing active human and agent cursors.
- Inline editing across text, dates, numbers, and status select pills.
- Formula calculation engine for automated progress, effort, and duration rollups.

### 3. Visual Flow / Canvas (`@xyflow/svelte`)
- Headless DAG canvas rendering project dependency trees.
- Interactive connection and rearrangement of task dependencies.
- Animated agent interaction cursors and smooth state transitions.

---

## Governance & Safety

1. **Human Approval Gates**: Interactive modal prompts pause autonomous agent cascades before destructive or high-stakes mutations, presenting complete reasoning logs for sign-off.
2. **Concurrency Record Locking**: Real-time presence trackers and lock states prevent human and agent collaborators from overwriting overlapping edits.
3. **Graceful Blocker Escalation**: When agents detect obstacles (e.g. missing credentials or contradictory requirements), they mark tasks as blocked and notify requesters with structured diagnostics.
4. **Soft Deletions**: Trashed tasks and artifacts are preserved in recoverable state before permanent deletion.

---

## Agent & Developer Integration

### WebMCP (`document.modelContext`)
Uchiage exposes client-side WebMCP tools directly in the browser DOM. AI browser extensions and in-page agents can inspect and manipulate project state via `document.modelContext` or `window.__CRITICAL_PATH_WEBMCP__`.

### Standalone MCP Server
A stdio MCP server (`npm run mcp`, `scripts/mcp-server.ts`) connects AI IDE copilots (such as Antigravity, Claude Desktop, Cursor) to Uchiage's Critical Path API:
- `list_projects`: Inspect available workspaces.
- `get_project_tasks`: Read tasks and dependency relationships.
- `create_task`: Create tasks with priorities and estimates.
- `update_task_status`: Advance tasks through workflow stages.
- `add_dependency`: Wire upstream/downstream dependencies.

### Key API Endpoints
- `POST /api/decompose`: Decompose high-level goal into topological execution batches.
- `POST /api/agents/loop`: Trigger autonomous agent execution loops for assigned tasks.
- `GET/POST /api/critical-path/*`: Critical Path server handler for graph evaluations and task mutations.
- `GET /api/realtime/events`: Server-Sent Events (SSE) feed for live project updates.

---

## Official Links

- Web Application: https://uchiage.app
- Critical Path Documentation: https://criticalpath.uchiage.app
- GitHub Repository: https://github.com/Pixerate/Uchiage
- Sitemap: https://uchiage.app/sitemap.xml
- LLMs Index: https://uchiage.app/llms.txt