Cloister: AI Lifecycle Manager

Cloister is Overdeck’s intelligent agent lifecycle manager. It monitors all running agents and automatically handles:

Model Routing - Routes tasks to appropriate models based on complexity, across multiple providers
Stuck Detection - Identifies agents that have stopped making progress
Automatic Handoffs - Escalates to specialists when needed
Specialist Coordination - Manages review-agent, test-agent, inspect-agent, uat-agent, and merge-agent

How Cloister Works

┌─────────────────────────────────────────────────────────────┐
│                     CLOISTER SERVICE                         │
│                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  Heartbeat  │───▶│   Trigger   │───▶│   Handoff   │     │
│  │   Monitor   │    │   Detector  │    │   Manager   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│         │                  │                  │             │
│         ▼                  ▼                  ▼             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Agent     │    │  Complexity │    │ Specialists │     │
│  │   Health    │    │   Analysis  │    │  (5 types)  │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
└─────────────────────────────────────────────────────────────┘

Starting Cloister

# Via dashboard - click "Start" in the Cloister status bar
# Or via CLI:
pan cloister start

# Check status
pan cloister status

# Stop monitoring
pan cloister stop

Specialists

Cloister manages five specialized agents that handle specific phases of the development lifecycle:

Specialist	Purpose	Trigger
review-agent	Code review before merge	Human clicks “Review”
test-agent	Runs test suite after review	After review passes
inspect-agent	Per-step verification during implementation	After each bead completion
uat-agent	Browser-based requirement verification	After tests pass
merge-agent	Handles git merge and conflict resolution	”Approve & Merge” button

See the Specialists feature guide for detailed information on specialist agents.

Review Pipeline Flow

The review pipeline is a sequential handoff between specialists:

Human clicks "Review"
        │
        ▼
┌───────────────────┐
│   review-agent    │ Reviews code, checks for issues
└─────────┬─────────┘
          │ If PASSED: queues test-agent
          │ If BLOCKED: sends feedback to work-agent
          ▼
┌───────────────────┐
│    test-agent     │ Runs test suite, analyzes failures
└─────────┬─────────┘
          │ If PASSED: queues uat-agent
          │ If FAILED: sends feedback to work-agent
          ▼
┌───────────────────┐
│    uat-agent      │ Browser-based requirement verification
└─────────┬─────────┘
          │ If PASSED: marks ready for merge
          │ If FAILED: sends feedback to work-agent
          ▼
┌───────────────────┐
│  (Human clicks    │ Human approval required
│  "Approve & Merge"│ before merge
└─────────┬─────────┘
          ▼
┌───────────────────┐
│   merge-agent     │ Performs merge, resolves conflicts
└───────────────────┘

Additionally, inspect-agent runs during implementation (between beads), not as part of this post-implementation pipeline. Key Points:

Human-initiated start - A human must click “Review” to start the pipeline
Automatic handoffs - review-agent → test-agent → uat-agent happens automatically
Human approval for merge - Merge is NOT automatic; human clicks “Approve & Merge”
Feedback loops - Failed reviews/tests/UAT send feedback back to the work-agent

Queue Processing

Each specialist has a task queue (~/.overdeck/specialists/{name}/hook.json) managed via the FPP (Fixed Point Principle):

1. Task arrives (via API or handoff)
        │
        ▼
2. wakeSpecialistOrQueue() checks if specialist is busy
        │
        ├── If IDLE: Wake specialist immediately with task
        │
        └── If BUSY: Add task to queue (hook.json)
                │
                ▼
3. When specialist completes current task:
        │
        ├── Updates status via API (passed/failed/skipped)
        │
        └── Dashboard automatically wakes specialist for next queued task

Queue priority order: urgent > high > normal > low Completion triggers: When a specialist reports status (passed, failed, or skipped), the dashboard:

Sets the specialist state to idle
Checks the specialist’s queue for pending work
If work exists, immediately wakes the specialist with the next task

Agent Self-Requeue (Circuit Breaker)

After a human initiates the first review, work-agents can request re-review up to 3 times automatically:

# Work-agent requests re-review after fixing issues
pan work request-review MIN-123 -m "Fixed: added tests for edge cases"

Circuit breaker behavior:

First human click resets the counter to 0
Each pan work request-review increments the counter
After 3 automatic re-requests, returns HTTP 429
Human must click “Review” in dashboard to continue

This prevents infinite loops where an agent repeatedly fails review. API endpoint: POST /api/workspaces/:issueId/request-review

Specialist Auto-Initialization

When Cloister starts, it automatically initializes specialists that don’t exist yet. This ensures all five specialists are ready to receive wake signals without manual setup.

Automatic Handoffs

Cloister detects situations that require intervention:

Trigger	Condition	Action
stuck_escalation	No activity for 30+ minutes	Escalate to more capable model
complexity_upgrade	Task complexity exceeds model capability	Route to Opus
implementation_complete	Agent signals work is done	Wake review-agent
test_failure	Tests fail repeatedly	Escalate model or request help
planning_complete	Planning session finishes	Transition to implementation
merge_requested	User clicks “Approve & Merge”	Wake merge-agent

The same lifecycle signals that drive these handoffs also feed the Fix-All Flywheel orchestrator, which keeps the pipeline turning autonomously — prioritizing what to work on next, launching planning and work agents, and escalating where Cloister flags a problem. Cloister is the per-agent lifecycle layer; the Flywheel is the cross-issue orchestrator built on top of it.

Handoff Methods

Cloister supports two handoff methods, automatically selected based on agent type:

Method	When Used	How It Works
Kill & Spawn	General agents (agent-min-123, etc.)	1. Captures full context (STATE.md, beads, git state) 2. Kills tmux session 3. Spawns new agent with handoff prompt 4. New agent continues work with preserved context
Specialist Wake	Permanent specialists (merge-agent, test-agent, etc.)	1. Captures handoff context 2. Sends wake message to existing session 3. Specialist resumes with context injection

Kill & Spawn is used for temporary agents that work on specific issues. It creates a clean handoff by:

Capturing the agent’s current understanding (from STATE.md)
Preserving beads task progress and open items
Including relevant git diff and file context
Building a comprehensive handoff prompt for the new model

Specialist Wake is used for permanent specialists that persist across multiple issues. It avoids the overhead of killing/respawning by injecting context into the existing session.

Handoff Context Capture

When a handoff occurs, Cloister captures:

{
  "agentId": "agent-min-123",
  "issueId": "MIN-123",
  "currentModel": "kimi-k2.5",
  "targetModel": "opus",
  "reason": "stuck_escalation",
  "handoffCount": 1,
  "state": {
    "phase": "implementation",
    "complexity": "complex",
    "lastActivity": "2024-01-22T10:30:00-08:00"
  },
  "beadsTasks": [...],
  "gitContext": {
    "branch": "feature/min-123",
    "uncommittedChanges": ["src/auth.ts", "src/tests/auth.test.ts"],
    "recentCommits": [...]
  }
}

Handoff prompts are saved to ~/.overdeck/agents/{agent-id}/handoffs/ for debugging.

Heartbeat Monitoring

Agents send heartbeats via Claude Code hooks. Cloister tracks:

Last tool use and timestamp
Current task being worked on
Git branch and workspace
Process health

What Cloister tracks per agent surfaces directly on the dashboard’s Agents page, which rolls the live heartbeat data up into a fleet view: each card shows the agent’s model, runtime, and last activity, topped by a metric strip (Running, Stuck, Cost 24h, Tokens 24h, runtime, Queue). This is where the stuck-detection and process-health signals described below become operator-visible. Heartbeat files are stored in ~/.overdeck/heartbeats/:

{
  "timestamp": "2024-01-22T10:30:00-08:00",
  "agent_id": "agent-min-123",
  "tool_name": "Edit",
  "last_action": "{\"file_path\":\"/path/to/file.ts\"...}",
  "git_branch": "feature/min-123",
  "workspace": "/home/user/projects/myapp/workspaces/feature-min-123"
}

Heartbeat Hook Installation

The heartbeat hook is automatically synced to ~/.overdeck/bin/heartbeat-hook via pan sync. It’s also installed automatically when you install or upgrade Overdeck via npm. Manual installation:

pan sync  # Syncs all skills, agents, AND hooks

Hook configuration in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.overdeck/bin/heartbeat-hook"
          }
        ]
      }
    ]
  }
}

Hook resilience: The heartbeat hook is designed to fail silently if:

The heartbeats directory doesn’t exist
Write permissions are missing
The hook script has errors

This prevents hook failures from interrupting agent work. If heartbeats stop arriving — or any other part of the lifecycle plumbing drifts — the dashboard’s Health page surfaces it. Its system health checks and diagnostics cover the same hooks, sockets, and services Cloister depends on, so you can confirm the monitoring stack itself is sound before trusting the stuck-detection signals it produces.

Configuration

Cloister configuration lives in ~/.overdeck/cloister/config.json:

{
  "monitoring": {
    "heartbeat_interval_ms": 5000,
    "stuck_threshold_minutes": 30,
    "health_check_interval_ms": 30000
  },
  "specialists": {
    "review_agent": { "enabled": true, "auto_wake": false },
    "test_agent": { "enabled": true, "auto_wake": true },
    "inspect_agent": { "enabled": true },
    "uat_agent": { "enabled": true },
    "merge_agent": { "enabled": true, "auto_wake": false }
  },
  "triggers": {
    "stuck_escalation": { "enabled": true },
    "complexity_upgrade": { "enabled": true }
  }
}

Model Routing & Complexity Detection

Cloister automatically routes tasks to the appropriate model based on detected complexity, optimizing for cost while ensuring quality. Model routing supports multiple providers: Anthropic, OpenAI, Google, Kimi, and Zhipu.

Complexity Levels

Level	Default Model	Use Case
trivial	Haiku	Typos, comments, documentation updates
simple	Haiku	Small fixes, test additions, minor changes
medium	Kimi	Features, components, integrations
complex	Kimi	Refactors, migrations, redesigns
expert	Opus	Architecture, security, performance optimization

The default implementation model is configurable per-project. Kimi is the current default for medium/complex tasks, providing a cost-effective alternative to Sonnet with strong coding performance.

Complexity Detection Signals

Complexity is detected from multiple signals (in priority order):

Explicit field - Task has a complexity field set (e.g., in beads)
Labels/tags - Issue labels like architecture, security, refactor
Keywords - Title/description contains keywords like “migration”, “overhaul”
File count - Number of files changed (>20 files = complex)
Time estimate - If estimate exceeds thresholds

Keyword patterns:

{
  trivial: ['typo', 'rename', 'comment', 'documentation', 'readme'],
  simple: ['add comment', 'update docs', 'fix typo', 'small fix'],
  medium: ['feature', 'endpoint', 'component', 'service'],
  complex: ['refactor', 'migration', 'redesign', 'overhaul'],
  expert: ['architecture', 'security', 'performance optimization']
}

Configuring Model Routing

Model routing is configured via the dashboard Settings page or ~/.overdeck/cloister/config.json:

{
  "model_selection": {
    "default_model": "kimi-k2.5",
    "complexity_routing": {
      "trivial": "haiku",
      "simple": "haiku",
      "medium": "kimi-k2.5",
      "complex": "kimi-k2.5",
      "expert": "opus"
    }
  }
}

Supported Providers

Provider	Models	Use Case
Anthropic	Opus, Sonnet, Haiku	Planning (Opus), review, general
OpenAI	GPT-4o, o1	Alternative implementation
Google	Gemini	Alternative implementation
Kimi	Kimi K2.5	Cost-effective implementation (default)
Zhipu	GLM-4	Alternative implementation

Cost Optimization

Model routing helps optimize costs:

Model	Relative Cost	Best For
Haiku	1x (cheapest)	Simple tasks, bulk operations
Kimi	~2x	Most implementation work (default)
Sonnet	3x	Review, complex implementation
Opus	15x	Planning, architecture, critical fixes

A typical agent run might:

Plan with Opus (high-quality strategic decisions)
Implement with Kimi (cost-effective coding)
Escalate to Opus only if stuck or complexity detected

Specialists - Detailed specialist agent documentation
Convoys - Multi-agent orchestration
Core Commands - Cloister CLI commands

​Cloister: AI Lifecycle Manager

​How Cloister Works

​Starting Cloister

​Specialists

​Review Pipeline Flow

​Queue Processing

​Agent Self-Requeue (Circuit Breaker)

​Specialist Auto-Initialization

​Automatic Handoffs

​Handoff Methods

​Handoff Context Capture

​Heartbeat Monitoring

​Heartbeat Hook Installation

​Configuration

​Model Routing & Complexity Detection

​Complexity Levels

​Complexity Detection Signals

​Configuring Model Routing

​Supported Providers

​Cost Optimization

​Related Guides

Cloister: AI Lifecycle Manager

How Cloister Works

Starting Cloister

Specialists

Review Pipeline Flow

Queue Processing

Agent Self-Requeue (Circuit Breaker)

Specialist Auto-Initialization

Automatic Handoffs

Handoff Methods

Handoff Context Capture

Heartbeat Monitoring

Heartbeat Hook Installation

Configuration

Model Routing & Complexity Detection

Complexity Levels

Complexity Detection Signals

Configuring Model Routing

Supported Providers

Cost Optimization

Related Guides