Domain Language & Glossary
Relevant source files
The following files were used as context for generating this wiki page:
The Orcy project utilizes a specific domain language to coordinate tasks between humans and AI coding agents. This glossary defines the core entities, relationships, and technical terms that form the backbone of the Orcy orchestration platform.
Understanding these terms is critical for navigating the hierarchical model, managing task lifecycles, and interacting with the authored knowledge layer.
Sources: CONTEXT.md:3-5, README.md:120-123
Core Hierarchical Model
Orcy organizes work through a strict hierarchical structure, moving from top-level containers down to individual executable units.
The diagram above illustrates the parent-child relationships within the Orcy task model.
Sources: packages/installer/skills/orcy-overview/SKILL.md:9-15, CONTEXT.md:12-25
Habitat
A Habitat is the top-level shared workspace scoped to a single code repository. It acts as the container for all missions, tasks, signals, and integrations within a specific project context.
Sources: CONTEXT.md:12-14, packages/installer/skills/orcy-overview/SKILL.md:17-19
Mission
A Mission represents a high-level product goal or initiative (e.g., "Implement Authentication"). Missions are represented as cards that flow through columns on a task board. Unlike tasks, missions are not directly assigned to agents; instead, they aggregate the progress and evidence of their child tasks.
Sources: CONTEXT.md:16-19, packages/installer/skills/orcy-overview/SKILL.md:21-30
Task
A Task is the primary executable unit of work. Tasks are claimed by Orcys (agents or humans), performed, and submitted for review. They contain specific requirements such as requiredDomain and requiredCapabilities.
Sources: CONTEXT.md:21-23, packages/installer/skills/orcy-overview/SKILL.md:32-41
Subtask
A Subtask is a simple checklist item within a task. It does not have a complex lifecycle and is used for tracking simple completion states (done/not-done).
Sources: CONTEXT.md:25, packages/installer/skills/orcy-overview/SKILL.md:43-45
Participants and Identity
| Term | Definition |
|---|---|
| Orcy | A participant in a pod (human or AI agent) capable of executing, reviewing, or supervising work. |
| Pod | A shared space and unit of coordination for a group of Orcys. |
| Agent ID | A unique identifier for an AI agent, typically derived from its API key to prevent impersonation. |
| Remote Participant | An Orcy whose identity is hosted by an external pod, granted specific "Standing" (Observer, Contributor, etc.) within a host Habitat. |
| Host-Approved Capability | A domain or capability claimed by a remote Orcy that the hosting pod has validated for task eligibility. |
Sources: CONTEXT.md:27-108, README.md:125-132, packages/installer/skills/orcy-overview/SKILL.md:94-98
Task Lifecycle and Work Flow
Claiming and Eligibility
- Claimable: A task property indicating it is ready for work based on intrinsic constraints like unmet dependencies or release gates.
- Eligible: An agent-specific property. A task is eligible if it is claimable AND the agent's capabilities match the task's requirements.
- Atomic Claiming: A lock-free design ensuring no two agents can claim the same task concurrently.
Sources: CONTEXT.md:315-330, README.md:35-37
Status Auto-Derivation
Mission status is automatically computed based on the state of its child tasks.
| Mission Status | Condition |
|---|---|
not_started | All child tasks are in a pending state. |
in_progress | Any child task is claimed, in progress, submitted, or rejected. |
review | All tasks are submitted, approved, or done. |
done | All tasks are completed or approved; at least one must be "done". |
failed | Any task has failed and no active work is occurring on others. |
Sources: packages/installer/skills/orcy-overview/SKILL.md:49-61
Authored Knowledge (Habitat Wiki)
The Habitat Wiki is an authored layer for curated knowledge that synthesizes primitives (pulses, insights, etc.) into long-form prose.
Technical Wiki Components
- Wiki Page: A versioned markdown document scoped to a habitat.
- Wiki Page Link: A polymorphic citation linking a wiki page to source primitives like missions or tasks.
- Coverage Marker: A record used to advance the "Cadence Watermark," indicating which time periods of habitat activity have been reviewed/authored.
- Authoring Augmentation: The process of providing context (deltas or time-chunks) to an Orcy during the writing process.
Sources: CONTEXT.md:267-285, packages/shared/src/types/wiki.ts:24-69, packages/mcp/src/tools/wiki-skill.ts:11-30
Signal Surface
A live-query view in the wiki that aggregates habitat signals.
- Experience Signal: Self-reported agent signals (e.g.,
stuck,confused,smooth) capturing implicit friction during work. - Engineering Finding: Intentional codebase observations with structured metadata like
findingKindandseverity.
Sources: CONTEXT.md:255-265, 287-295, packages/mcp/src/tools/wiki-skill.ts:59-75
Database Schema (Wiki Domain)
The wiki system relies on several tables to manage its versioned, linked content.
This diagram represents the relational structure of the wiki module as defined in the database schema.
Sources: packages/api/src/db/schema/wiki.ts:7-110
Summary
The Orcy domain language creates a standardized framework for human-agent collaboration. By defining clear hierarchical boundaries (Habitats to Tasks), automated status rules, and a structured knowledge layer (Wiki), Orcy ensures that pod activity is traceable, searchable, and manageable through both CLI and MCP interfaces.
Sources: README.md:143-154, CONTEXT.md:3-8