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

# Core Concepts

> Understanding the key concepts behind Overdeck's architecture

export const ThemedImage = ({light, dark, alt = ""}) => <>
    <img src={light} alt={alt} className="block dark:hidden" />
    <img src={dark ?? light} alt={alt} className="hidden dark:block" />
  </>;

# Core Concepts

Learn the fundamental concepts that power Overdeck.

## Command Deck

The live development surface where you and your agents work together. A full-height **project sidebar** on the left owns project selection; everything to its right is scoped to the project you pick and updates in real time:

* **App bar** — the project crumb, a project-scoped search, and status pills at a glance (Deacon health, running-agent count, stopped agents). No more persistent banners — attention items surface as compact pills.
* **Tab strip** — every issue, agent, and conversation you open becomes a tab. Scroll on overflow, middle-click to close, right-click to pop out to a window or close others, and **split the view** (drag a tab to a pane's edge) to watch two panes side by side.
* **Pane body** — the working area. A project's **Home cockpit** (issue swimlanes, recent spend, a stuck count), an **issue cockpit** (blocker spotlight → phase timeline → single-source metric strip → scan cards → dig tabs), or an agent's live conversation and terminal.
* **Awareness rail** — one right-hand rail with **Needs-you / Project / Global** scopes, so anything waiting on your input is always a glance away. Collapse it when you want the extra width.

<ThemedImage light="/images/dashboard/command-deck-hero-light.png" dark="/images/dashboard/command-deck-hero-dark.png" alt="Command Deck — project and conversation sidebar, issue tree, an agent's turn-by-turn tool calls and reasoning, and the Needs-you / Project / Global awareness rail" />

Command Deck is where you *manage the conversation*, not just watch a workflow run. The center pane streams the agent's turn-by-turn reasoning and tool calls as they happen, the sidebar keeps every project, issue, and conversation one click away, and the awareness rail on the right collects anything that needs your attention.

Everything is alive — no refresh buttons. Domain events trigger small, informative UI motion: cost increments animate, tool names fade in and out, status dots pulse.

<ThemedImage light="/images/command-deck/issue-cockpit-light.png" dark="/images/command-deck/issue-cockpit-dark.png" alt="The issue cockpit — blocker spotlight, phase timeline, and single-source metric strip" />

The **issue cockpit** above leads with a *blocker spotlight* (why the issue is stuck and the actions to unblock it, or "ready to merge"), then a phase timeline and a single-source metric strip (cost · diff · PR · sessions · last activity), with scan cards and dig tabs below.

### What You Can Do From Command Deck

* **Review diffs as they land** — every file change appears inline as the agent works. Open the diff panel for a turn-by-turn view, or hit "vs main" to see the full picture.
* **Talk to agents** — type in the composer to steer an agent mid-task. Point it at the right file, correct its approach, or tell it to rethink.
* **Hot-swap models** — open the model picker and switch from Sonnet to Opus (or Kimi, GPT, Gemini) without losing the conversation.
* **Branch to explore** — fork any conversation to try a different approach. Keep the original intact, compare both.
* **Roll back with checkpoints** — Command Deck snapshots agent state as work progresses. Go sideways? Roll back instead of starting over.
* **See the plan** — xBRIEF work plans render as interactive DAGs with dependencies, acceptance criteria, and live status tracking.

## Agents

Agents are AI coding assistants that work on the tasks you assign. You direct them from Command Deck — watch them code in real time, send messages to steer their approach, swap their model when the task shifts, fork the conversation to try something different, and review their diffs inline as they go.

Agent types:

* **Implementation agents** — Work on features, bugs, refactoring in isolated worktrees
* **Planning agents** — Explore codebases and create PRDs with Opus
* **Specialist agents** — Dedicated review, test, inspect, UAT, and merge agents triggered by Cloister

You can manage agents via Command Deck, the CLI, or the REST API.

## Cloister

The lifecycle manager. Cloister routes tasks to models based on capabilities, detects stuck agents, triggers specialist handoffs, and tracks costs. It runs a patrol loop that checks agent health and manages the specialist queue. Supports multi-provider routing across Anthropic, OpenAI, Google, Kimi, MiniMax, and OpenRouter.

## PRD-Driven Workflow

Opus writes a PRD before implementation starts. Agents are blocked from starting without a PRD — this ensures strategic decisions are made by the strongest model, not cheaper ones. PRDs are auto-committed to the workspace after planning.

## Workspaces

**Workspaces are git worktrees** — isolated working directories for each issue. Each workspace:

* Has its own feature branch (e.g., `feature/pan-123`)
* Shares git history with the main repo (no separate clone)
* Can include Docker containers for full development environments
* Is located at `{project}/workspaces/feature-{issue-id}/`
* Contains a `.planning/` directory with PRD, STATE.md, beads, and feedback

This allows multiple agents to work on different features simultaneously without conflicts.

Workspaces support both local execution and remote execution via Fly.io for cloud-hosted agent environments.

### Main Project Branch Convention

The main project directory should **always** stay on the `main` branch. All feature work happens in workspaces (git worktrees), never in the main project. This ensures specialists always find the correct code, and merge operations have a clean target.

### Docker Integration

Workspaces can include Docker containers for full development environments. Supports both local execution and remote execution via Fly.io.

## Specialists

When you want to go hands-off, the specialist pipeline takes over. Five dedicated agents handle the quality lifecycle automatically:

1. **Review Agent** — Comprehensive code review (correctness, security, performance)
2. **Test Agent** — Runs tests and validates functionality
3. **Inspect Agent** — Per-step verification after each bead, ensuring implementation matches the spec
4. **UAT Agent** — Browser-based requirement verification using Playwright after tests pass
5. **Merge Agent** — Handles PR/MR creation and merging

The only manual step is clicking **MERGE** when you're satisfied with the results.

<ThemedImage light="/images/dashboard/pipeline-light.png" dark="/images/dashboard/pipeline-dark.png" alt="Pipeline page — a metric strip (Active issues, Work running, Review queue, Ship, Spend) above phase-grouped issue rows for Ship, Review, and Verifying, with an activity feed on the right" />

The **Pipeline** page is the at-a-glance view of this lifecycle: a metric strip across the top (Active issues, Work running, Review queue, Ship, Spend) sits over issue rows grouped by phase — Ship, Review, Verifying — with a live activity feed alongside. It shows where every issue sits as specialists hand it forward.

## Multi-Model Routing

Overdeck routes tasks to the right model automatically based on task type, capability, and budget:

* **Planning** — Opus-class models for strategic decisions
* **Implementation** — Cost-effective models (Kimi, Sonnet, GPT) for writing code
* **Review** — Strong models for code review judgment
* **Helpers** — Fast models (Haiku) for quick commands

Override any routing decision from Command Deck's model picker or the Settings page.

## Skills

Universal SKILL.md format works across Claude Code, Codex, Cursor, Gemini CLI, and Google Antigravity. 70+ skills ship out of the box covering:

* Development workflows (feature work, bug fixing, refactoring)
* Code review (correctness, security, performance)
* Incident response and debugging
* Codebase onboarding
* Project-specific knowledge capture

Sync skills to all your AI tools with `pan sync`.

## Beads

Git-backed task tracking that survives context compaction and works offline. Beads give agents persistent memory across sessions — when a conversation gets compressed, the agent can recover its task state from beads.

## Convoys

Run parallel agents on related issues. Useful for security audits, performance reviews, or breaking an epic into concurrent work streams. Results are auto-synthesized by a dedicated synthesis agent.

## Issue Tracker Integration

Overdeck integrates with 4 issue trackers:

* **GitHub Issues** — Full integration with PRs and status updates
* **Linear** — Full integration with cycles, labels, and status updates
* **GitLab Issues** — Issue tracking and MR management
* **Rally (CA Agile Central)** — Enterprise issue tracking

The dashboard displays issues from all configured trackers in a unified kanban board with cost badges, agent status indicators, and workspace controls.

## Cost Tracking

Per-issue, per-stage token costs with dashboard analytics. Every agent session is tracked with:

* Model and provider attribution
* Token counts (input/output)
* Dollar costs per stage (planning, work, review, test, merge)
* Daily cost summaries on the Board view

## Shadow Engineering

Monitor existing workflows before transitioning to AI-driven development. Upload transcripts, sync discussions, and generate inference documents to build institutional knowledge before handing off to agents.

## Next Steps

* [CLI Commands](/cli/overview) - Learn about available commands
* [Mission Control](/features/mission-control) - Deep dive into the dashboard
* [Cloister](/features/cloister) - Understand the AI lifecycle manager
* [Specialists](/features/specialists) - Learn about the automated quality pipeline