> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the building blocks of OrgX: agents, artifacts, decisions, and the org graph.

## The OrgX Mental Model

OrgX is built around a simple loop:

```mermaid theme={"dark"}
graph LR
    A[Work Item] --> B[Agent Assigned]
    B --> C[Agent Executes]
    C --> D{Decision Needed?}
    D -->|Yes| E[Human Approves]
    D -->|No| F[Artifact Created]
    E --> F
    F --> G[Org Graph Updated]
    G --> A
```

Let's break down each component.

***

## Questions This Page Answers

* How does OrgX break down complex work so agents can execute reliably?
* Which agent should run which type of work?
* Where does human approval fit without slowing execution?
* How do I know outputs are trustworthy and auditable?
* Why does this model outperform generic “single chat agent” workflows?

## Why This Model Works

* **Less context loss**: IWMT + org graph preserve execution context across handoffs.
* **Faster throughput**: Domain agents execute in parallel while orchestrator handles routing.
* **Lower risk**: Decisions and verifier gates catch issues before shipping.
* **Compounding quality**: The flywheel learns from approvals, rejections, and outcomes.

***

## The IWMT Hierarchy

OrgX organizes work using the **IWMT hierarchy** — Initiative, Workstream, Milestone, Task. This structure enables automatic cascade execution.

<Card title="Initiative" icon="flag">
  A high-level goal or project. Examples: "Launch v2 of the marketing site",
  "Close Series A", "Ship AI-powered search"
</Card>

```yaml theme={"dark"}
Initiative: Q1 Product Launch           # Top-level goal
├── Milestone: Beta Launch (Apr 1)      # Checkpoint / deadline
├── Milestone: GA Release (Jun 1)
├── Workstream: Landing Page Redesign   # Parallel execution track
│   ├── Task: Design new hero section
│   ├── Task: Implement responsive layouts
│   └── Task: A/B test CTAs
├── Workstream: Documentation
│   ├── Task: Update API docs
│   └── Task: Create migration guide
└── Workstream: Marketing
    ├── Task: Write launch blog post
    └── Task: Prepare email campaign
```

### Auto-Continue Cascade

IWMT isn't just organizational — it drives **automatic execution**:

* When a task completes, the next queued task in the workstream auto-starts
* When all tasks in a milestone complete, the milestone auto-closes
* When a workstream finishes, dependent workstreams transition from "pending" to "ready"
* Cross-workstream dependencies resolve automatically through DAG resolution

This means agents continuously pick up the next piece of work without human intervention.

***

## Agents

Agents are specialized AI workers that handle different domains:

<Tabs>
  <Tab title="Engineering Agent">
    **Domain**: Engineering & implementation

    **Capabilities**:

    * Analyze codebases and suggest fixes
    * Create pull requests with proper context
    * Write and run tests
    * Refactor existing code

    **Triggered by**: Labels like `bug`, `refactor`, or engineering-related task descriptions
  </Tab>

  <Tab title="Product Agent">
    **Domain**: Product strategy & planning

    **Capabilities**:

    * Draft PRDs and initiative plans
    * Clarify goals, constraints, and success metrics
    * Identify roadmap and scope risks
    * Synthesize user/problem framing

    **Triggered by**: Tasks around requirements, prioritization, planning, and decision framing
  </Tab>

  <Tab title="Marketing Agent">
    **Domain**: Content & Campaigns

    **Capabilities**:

    * Draft campaign briefs and copy
    * Create outreach sequences
    * SEO optimization suggestions
    * Brand tone compliance

    **Triggered by**: Labels like `marketing`, `content`, or SEO-related tasks
  </Tab>

  <Tab title="Sales Agent">
    **Domain**: Pipeline & Outreach

    **Capabilities**:

    * Lead qualification and scoring
    * Personalized outreach drafts
    * CRM updates (HubSpot integration)
    * Meeting prep summaries

    **Triggered by**: Labels like `sales`, `lead`, or CRM-related tasks
  </Tab>

  <Tab title="Design Agent">
    **Domain**: UX & Visual

    **Capabilities**:

    * Design rationale documentation
    * UX pattern recommendations
    * Figma feedback (coming soon)
    * Accessibility checks

    **Triggered by**: Labels like `design`, `ux`, or product briefs
  </Tab>

  <Tab title="Operations Agent">
    **Domain**: Reliability, incidents, and operating rhythm

    **Capabilities**:

    * Create runbooks and incident playbooks
    * Triage operational blockers and escalations
    * Track SLA/budget guardrails
    * Generate health and readiness summaries

    **Triggered by**: Tasks involving operations, incident response, or execution hygiene
  </Tab>

  <Tab title="Orchestrator Agent">
    **Domain**: Cross-domain coordination

    **Capabilities**:

    * Decompose initiatives into executable slices
    * Route work to specialist agents
    * Manage dependency ordering and handoffs
    * Keep queue progression aligned with priorities

    **Triggered by**: Multi-step work requiring sequencing, delegation, or conflict resolution
  </Tab>
</Tabs>

### Agent Selection

When a work item enters the system, the **orchestrator** selects the best agent(s):

```json theme={"dark"}
{
  "primaryAgent": "engineering-agent",
  "secondaryAgents": ["product-agent"],
  "reasoning": "Task involves auth bug remediation plus product-impact validation before release.",
  "toolsNeeded": ["github.create_pr", "linear.comment"]
}
```

***

## Decisions

A **decision** is a checkpoint where agents need human judgment:

```yaml theme={"dark"}
Decision:
  type: approval
  agent: marketing
  context: 'Campaign brief ready for review'
  recommendation: 'Approve and schedule for Monday'
  evidence:
    - link: 'linear://issue/MARK-123'
      summary: 'Original campaign request'
    - link: 'artifact://brief/abc123'
      summary: 'Generated campaign brief'
  actions:
    - approve
    - reject
    - request_changes
```

### Decision Types

| Type              | Description                          | Example                               |
| ----------------- | ------------------------------------ | ------------------------------------- |
| **Approval**      | Agent completed work, needs sign-off | "Approve this PR for merge"           |
| **Escalation**    | Agent hit its autonomy limit         | "Budget exceeds \$500, need approval" |
| **Clarification** | Agent needs more context             | "Which target audience?"              |
| **Conflict**      | Competing priorities detected        | "Task A blocks Task B"                |

### Autonomy Levels

Configure how much agents can do independently:

| Level          | Description                                |
| -------------- | ------------------------------------------ |
| **Shadow**     | Agent suggests, never acts                 |
| **Tutor**      | Agent explains before each action          |
| **Supervised** | Agent acts, human approves before shipping |
| **Autonomous** | Agent acts within budget limits            |
| **Full Auto**  | Agent ships without approval (risky)       |

<Warning>
  We recommend starting at **Supervised** and adjusting based on agent
  performance.
</Warning>

***

## Artifacts

Artifacts are the **verified outputs** of agent work:

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines">
    Product requirements, technical designs, briefs
  </Card>

  <Card title="Code" icon="code">
    Pull requests, patches, migrations
  </Card>

  <Card title="Content" icon="pen">
    Blog posts, email sequences, social copy
  </Card>

  <Card title="Reports" icon="chart-line">
    Research findings, analyses, summaries
  </Card>
</CardGroup>

### Artifact Lifecycle

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> Forming: Agent starts work
    Forming --> Testing: Draft complete
    Testing --> NeedsYou: Verification failed
    Testing --> Ready: Verification passed
    NeedsYou --> Testing: Human fixes issues
    Ready --> Shipped: Approved
    Shipped --> [*]
```

### Verification

Every artifact passes through the **Verifier** before shipping:

* **Citation check**: Are sources referenced?
* **Policy check**: Does it comply with brand/legal guidelines?
* **Contract check**: Does output match expected schema?
* **Budget check**: Within token/latency limits?

***

## Intelligence Flywheel

The Intelligence Flywheel is OrgX's continuous improvement engine. It connects agent execution to measurable business outcomes, building trust over time.

<CardGroup cols={2}>
  <Card title="Value Ledger" icon="receipt">
    Every agent action generates a **receipt** tracking cost and attributed
    value. Query ROI and recent value signals with `orgx_recommend`.
  </Card>

  <Card title="Trust Levels" icon="shield-check">
    Agents earn trust per capability: `read_only` → `draft` →
    `act_with_approval` → `autonomous`. Check with `get_my_trust_context`.
  </Card>

  <Card title="Autonomous Sessions" icon="moon">
    Budget-bounded overnight execution. Start with `start_autonomous_session`,
    review with `orgx_recommend`.
  </Card>

  <Card title="Org Learnings" icon="graduation-cap">
    Agents share discoveries (failure patterns, cost optimizations) across the
    org via `submit_learning` and `get_relevant_learnings`.
  </Card>
</CardGroup>

***

## Mission Control

**Mission Control** is the operational dashboard that gives you real-time visibility into everything agents are doing:

* **Next Up Queue** — Scored and prioritized list of what agents should work on next, using configurable scoring weights
* **Slices Plane** — IWMT hierarchy view with resizable columns showing initiative → workstream → milestone → task breakdown
* **Live Dashboard** — Real-time agent activity, decision status, and stream progress
* **Red-Dot Control Plane** — Internal health indicators surfacing blocked work, stale initiatives, and pending decisions via proactive sentinels

### Proactive Sentinels

Sentinels run automatically to detect issues before they become blockers:

* **Stale Initiative Sentinel** — Flags initiatives with no activity
* **Pending Decision Sentinel** — Escalates decisions that have been waiting too long
* **Blocked Workstream Sentinel** — Creates decisions when workstreams are stuck

***

## The Org Graph

All entities connect in the **Org Graph** — a knowledge layer that agents query and update:

```mermaid theme={"dark"}
graph TD
    subgraph Org Graph
        I[Initiatives]
        W[Workstreams]
        T[Tasks]
        A[Artifacts]
        D[Decisions]
        E[Evidence]
    end

    I --> W
    W --> T
    T --> A
    T --> D
    A --> E
    D --> E
```

### Why It Matters

* **Context**: Agents understand relationships between work items
* **Citations**: Every action links back to source evidence
* **Audit**: Full trail of who/what/when for compliance
* **Learning**: System improves by analyzing past patterns

***

## MCP & External Tools

OrgX exposes its capabilities via the **Model Context Protocol (MCP)**:

<AccordionGroup>
  <Accordion title="Tools" icon="wrench">
    Actions agents can take:

    * `scaffold_initiative` - Create a new initiative with full hierarchy
    * `orgx_write` - Create any entity type (task, milestone, etc.)
    * `orgx_act` - Lifecycle actions (launch, pause, complete)
    * `orgx_decide` - Sign off on agent work
    * `orgx_search` - Search the knowledge graph
    * `orgx_spawn` - Assign work to an agent
  </Accordion>

  {' '}

  <Accordion title="Resources" icon="folder">
    Data agents can access: - `orgx://initiative/{id}` - Initiative details -
    `ui://widget/decisions.html` - Decision card widget - `orgx://artifact/{id}` -
    Artifact contents
  </Accordion>

  <Accordion title="Prompts" icon="message">
    Pre-built conversation starters:

    * `create-roadmap` - Scaffold initiative with milestones
    * `weekly-recap` - Summarize agent activity
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="See Agents in Action" icon="play" href="/docs/platform/agents">
    Detailed guide to each agent type
  </Card>

  <Card title="MCP Tools Reference" icon="server" href="/docs/api/mcp-tools">
    Complete API for MCP integrations
  </Card>
</CardGroup>