Habitats, Missions, and Tasks
Relevant source files
The following files were used as context for generating this wiki page:
Orcy utilizes a strict hierarchical data model to coordinate work between humans and AI coding agents. This hierarchy consists of Habitats, which contain Missions, which in turn contain Tasks, and finally Subtasks. This structure ensures that product initiatives are broken down into executable units of work that can be claimed and tracked atomically.
The system is designed to provide a shared workspace where every participant (orcy)—whether human or agent—has visibility into the pod's progress, handoffs are logged, and quality is enforced through gates and reviews.
Sources: packages/installer/skills/orcy-overview/SKILL.md:12-18, README.md:104-106, CONTEXT.md:8-14
The Orcy Hierarchy
The relationship between entities is strictly top-down, representing the progression from high-level project containers to granular checklist items.
Habitat
A Habitat is the top-level container representing a specific project or sprint. It defines the shared workspace scoped to a single code repository. Within a Habitat, pod members coordinate missions, tasks, and various signals.
Key Characteristics:
- Contains configurable columns for workflow (e.g., Backlog, In Progress, Review, Done).
- Acts as the administrative boundary for settings, integrations, and automation.
- Aggregates health history, metrics, and habitat-wide skills.
Sources: packages/installer/skills/orcy-overview/SKILL.md:21-23, CONTEXT.md:12-15, packages/mcp/src/api.ts:246-248
Mission
A Mission represents a product initiative or goal (e.g., "Implement Authentication"). In the UI, a Mission manifests as a Kanban card that flows through the Habitat's columns. Crucially, Missions are not assigned to agents; instead, they contain the specific Tasks that agents claim.
Mission Data Model:
| Field | Description |
|---|---|
| Title & Description | Defines the goal and scope of the initiative. |
| Acceptance Criteria | Success metrics for the mission. |
| Priority | Low, Medium, High, or Critical. |
| Dependencies | Relationships defined via dependsOn or blocks. |
| Status | Auto-derived from the states of its child tasks. |
Sources: packages/installer/skills/orcy-overview/SKILL.md:25-34, CONTEXT.md:17-19, packages/mcp/src/api.ts:211-230
Task
A Task is the atomic unit of work inside a Mission. Agents claim tasks to lock them, preventing concurrent execution by other agents. Tasks are governed by domain routing and capability requirements, ensuring only qualified agents can perform the work.
Task Lifecycle and Assignment:
- Atomic Claiming: Prevents two agents from grabbing the same task.
- Domain Routing: Filters tasks based on
requiredDomain(e.g., frontend, backend) andrequiredCapabilities(e.g., typescript, postgresql). - Quality Gates: Completion requires validation of checklists, dependencies, and artifacts.
Sources: packages/installer/skills/orcy-overview/SKILL.md:36-45, README.md:41-49, CONTEXT.md:21-23
Subtask
Subtasks are simple checklist items within a Task. They consist of a title, a completion flag, and an optional assignee. Unlike Tasks, Subtasks do not have a complex lifecycle; they are either done or not done.
Sources: packages/installer/skills/orcy-overview/SKILL.md:47-49
Mission Status Auto-Derivation
Mission status is never set manually by users or agents. Instead, the system computes the status based on the current state of all child tasks associated with that mission. This ensures the Kanban board accurately reflects the ground-truth progress of technical work.
Status Mapping Logic
| Mission Status | Condition |
|---|---|
not_started | All child tasks are currently in the pending state. |
in_progress | Any child task is claimed, in_progress, submitted, approved, or rejected. |
review | All tasks are submitted, approved, or done; none are pending, in_progress, or claimed. |
done | All tasks are done or approved; at least one task must be done. |
failed | Any task has failed and no other tasks are being actively worked on. |
Sources: packages/installer/skills/orcy-overview/SKILL.md:53-62
Column Advancement
Missions automatically advance to specific columns in the Habitat based on their derived status:
- Backlog (First Column): Triggered by
not_started. - In Progress (Second Column): Triggered by
in_progress. - Review (Second-to-last Column): Triggered by
review. - Done (Terminal Column): Triggered by
done.
Sources: packages/installer/skills/orcy-overview/SKILL.md:66-74
Task Lifecycle States
Tasks follow a managed lifecycle driven by agent actions. Transitions are performed via the orcy_habitat_task MCP tool or the REST API.
Key Lifecycle Operations
- Claim: Atomically locks a
pendingtask to a specificagentId. - Submit: Marks work as ready for review, requiring
resulttext andartifacts. - Complete: A gated transition to
donethat validates quality gates (checklists, dependencies, and time tracking). - Approve: A human-override transition that skips quality gates.
- Release: Moves a
claimedtask back topending, typically due to blockers or agent disconnects.
Sources: packages/mcp/src/api.ts:474-539, packages/mcp/src/tools/instructions.ts:40-48
Technical Data Models
Habitat Schema
The Habitat defines the environment settings and repository integrations.
Sources: packages/mcp/src/api.ts:608-620, packages/mcp/src/api/interfaces.ts:316-324
Mission Summary Data
When querying a habitat summary, the following mission-level progress is typically returned:
| Field | Type | Description |
|---|---|---|
missionId | string | Unique identifier for the mission. |
title | string | The display name of the mission. |
status | string | Derived status (e.g., in_progress). |
completed | number | Count of completed tasks. |
total | number | Total count of tasks in the mission. |
Sources: packages/mcp/src/api.ts:805-812, packages/installer/skills/orcy-mcp-usage/SKILL.md:83-88
Task Context DTO
Retrieving task context provides a comprehensive view of the environment required to perform work.
interface TaskContext {
task: Task;
feature: Mission;
siblingTasks: Task[];
dependencies: TaskDependency[];
blockedBy: Task[];
blocking: Task[];
boardContext: { name: string; columns: Column[] };
}
Sources: packages/mcp/src/api/interfaces.ts:275-283, packages/installer/skills/orcy-mcp-usage/SKILL.md:180-188
Summary and Significance
The Habitat, Mission, and Task structure forms the backbone of Orcy's coordination engine. By enforcing a hierarchical breakdown, the system enables AI agents to work autonomously on granular tasks while providing humans with high-level oversight via missions and automated status derivation. This model reduces coordination overhead and ensures that all code changes are linked to specific product initiatives with verifiable evidence and quality gates.