🃏 DECK - Development Execution Control Kernel

DECK is a lightweight, file-based queue management system designed for managing concurrent CLIDE development sessions across multiple repositories. It ensures your autonomous development system scales gracefully without overwhelming resources.

Features

• Fire-and-forget webhook integration - Queue issues instantly, process asynchronously
• Multi-repository support - Manage work across your entire GitHub organization
• File-based simplicity - No databases, just reliable filesystem operations
• Self-healing design - Automatically recovers from crashes and restarts
• Priority queue management - Critical issues jump to the front
• Resource-aware scheduling - Never overwhelm your development environment
• Real-time monitoring - Watch your queue activity live

Quick Start

Installation

# Clone the repository
git clone https://github.com/clidecoder/deck.git
cd deck

# Run the installation script
./install.sh

# Or install manually
sudo mkdir -p /opt/deck /var/clide/deck
sudo cp -r src /opt/deck/
sudo ln -s /opt/deck/src/deck.sh /usr/local/bin/deck

Basic Usage

# Queue an issue for processing
deck queue myorg/myrepo 123

# Queue with priority
deck queue myorg/api 456 urgent

# Check queue status
deck status

# Release a completed issue
deck release myorg/myrepo 123

# Monitor queue in real-time
deck monitor --continuous

Daemon Management

# Start the background daemon
deck daemon start

# Or use systemd
sudo systemctl start deck
sudo systemctl enable deck

# Check daemon status
deck daemon status

Architecture

DECK uses a simple directory structure to manage queue state:

/var/clide/deck/
├── active/                      # Currently running sessions
│   └── myorg_api_123.lock      # Active work ticket
├── waiting/                     # Queued tickets
│   └── myorg_web_456.lock      # Waiting ticket
├── config/
│   └── deck.conf               # Configuration
└── logs/
    └── deck.log                # Operation logs

Each lock file contains JSON metadata about the work item, including repository, issue number, priority, and session information.

Configuration

Edit /var/clide/deck/config/deck.conf:

MAX_CONCURRENT=3                 # Maximum concurrent CLIDE sessions
TIMEOUT_HOURS=24                 # Timeout for stale sessions
AUTO_CLEANUP=true                # Automatic cleanup of old resources
PRIORITY_LABELS="urgent,security,hotfix"  # GitHub labels for priority
LOG_LEVEL="info"                 # Logging verbosity

Update configuration on the fly:

deck configure MAX_CONCURRENT 5
deck configure TIMEOUT_HOURS 48

Integration with Webhooks

DECK is designed for fire-and-forget webhook integration:

# Example webhook handler
@app.post("/webhook")
async def github_webhook(request: Request):
    payload = await request.json()
    
    if payload["action"] == "opened":
        repo = payload["repository"]["full_name"]
        issue_number = payload["issue"]["number"]
        
        # Queue the issue - returns immediately
        subprocess.run(["deck", "queue", repo, str(issue_number)])
        
    return {"status": "ok"}

Commands Reference

Core Commands

• deck queue <repo> <issue> [priority] - Queue a work ticket
• deck release <repo> <issue> - Release completed ticket
• deck status [--detailed] [--json] - Show queue status

Administrative Commands

• deck daemon <start|stop|restart|status> - Control daemon
• deck rebuild - Rebuild state from GitHub/tmux
• deck cleanup [--dry-run] - Clean stale resources
• deck configure <setting> <value> - Update configuration

Monitoring Commands

• deck monitor [--continuous] - Monitor queue activity
• deck logs [--tail] [--grep pattern] - View logs
• deck health - System health check

Development

Running Tests

# Run test suite (when implemented)
./tests/run_tests.sh

Project Structure

deck/
├── src/
│   ├── deck.sh         # Main CLI
│   ├── daemon.sh       # Background daemon
│   └── lib/            # Shared libraries
│       ├── common.sh   # Common utilities
│       ├── queue.sh    # Queue operations
│       ├── daemon.sh   # Daemon control
│       ├── admin.sh    # Admin commands
│       └── monitor.sh  # Monitoring functions
├── install.sh          # Installation script
├── deck.service        # Systemd service
└── README.md           # This file

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Support

• Issues: https://github.com/clidecoder/deck/issues
• Documentation: See OVERVIEW.md for detailed architecture