Claude

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MonoTask is a Bun-powered monorepo implementing an AI-driven task automation system with GitHub integration, state machine orchestration, and real-time progress tracking. The system uses Claude AI agents to handle task elicitation, implementation, testing, and validation through a multi-phase workflow.

Core Development Commands

Cloudflare Workers Development

bash

# Local development
wrangler dev                      # Start local worker development server
wrangler dev --port 8787          # Specify custom port

# Deployment
wrangler deploy                   # Deploy to production
wrangler deploy --env development # Deploy to development environment
wrangler deploy --env staging     # Deploy to staging environment

# Monitoring and debugging
wrangler tail                     # Stream production logs in real-time
wrangler tail --status error      # Filter by error status
wrangler tail --format pretty     # Pretty-print log output

# Database operations (D1)
wrangler d1 execute DB --command="SELECT * FROM tasks"
wrangler d1 migrations list DB
wrangler d1 migrations apply DB --env production

# KV operations
wrangler kv:key list --namespace-id=xxx
wrangler kv:key get KEY --namespace-id=xxx
wrangler kv:key put KEY VALUE --namespace-id=xxx

# R2 operations
wrangler r2 bucket list
wrangler r2 object list BUCKET_NAME

# Queue operations
wrangler queues list
wrangler queues consumer add QUEUE_NAME WORKER_NAME

Local Development (Legacy Dashboard/Frontend)

bash

# Database initialization (run first on new setup)
bun run db:init        # Initialize database schema
bun run db:migrate     # Apply pending migrations
bun run db:reset       # Wipe and reinitialize database

# Frontend development
bun run dev:frontend   # Start only frontend (Vite dev server)

Testing Commands

bash

# Unit tests
bun test               # Run all unit tests
bun test [file]        # Run specific test file

# E2E tests (Playwright-based)
bun run test:e2e                    # Full E2E suite
bun run test:e2e:onboarding         # Onboarding flows
bun run test:e2e:onboarding:ui      # Interactive debugging
bun run test:e2e:onboarding:debug   # Debug mode

# Code quality
bun run typecheck      # TypeScript type checking
bun run lint          # ESLint checks
bun run format        # Prettier formatting

Build & Deployment

bash

bun run build          # Build all packages
bun run clean         # Remove dist and node_modules

# Cloudflare Workers Deployment
bun run deploy:staging # Deploy all workers to staging
bun run deploy:prod    # Deploy all workers to production

Cloudflare Workers Local Development

bash

# Start all workers concurrently (recommended for full stack development)
bun run dev:workers    # Starts all 6 workers on different ports

# Or start individual workers for focused development
bun run dev:agent      # Agent worker on port 8701
bun run dev:task       # Task worker on port 8702
bun run dev:github     # GitHub worker on port 8703
bun run dev:websocket  # WebSocket worker on port 8704
bun run dev:auth       # Auth worker on port 8705
bun run dev:api        # API gateway on port 8787

# Monitor worker logs in production
bun run logs:agent     # Stream agent worker logs
bun run logs:task      # Stream task worker logs
bun run logs:github    # Stream GitHub worker logs
bun run logs:websocket # Stream WebSocket worker logs
bun run logs:auth      # Stream auth worker logs
bun run logs:api       # Stream API gateway logs

Architecture & Code Organization

Monorepo Structure

packages/
├── shared/                # Central utilities, database abstractions, types, logging
├── core/                  # State machine, validation engine, evidence collection
├── dashboard/             # [LEGACY] REST API server (being replaced by Cloudflare Workers)
├── frontend/              # React SPA client, metrics visualization
├── cli/                   # Command-line interface for automation
├── ai/                    # Claude-based AI agents for task phases
├── parser/                # Task and requirement parsing utilities
├── e2e/                   # Playwright end-to-end test suites
└── cloudflare-workers/    # Cloudflare Workers architecture (production)
    ├── agent-worker/      # AI agent orchestration
    ├── task-worker/       # Task state machine and CRUD
    ├── github-worker/     # GitHub webhooks and API proxy
    ├── websocket-worker/  # Real-time WebSocket updates
    ├── auth-worker/       # Authentication and sessions
    ├── api-gateway/       # Request routing
    └── monitoring/        # Performance and error tracking

Key Architectural Patterns

State Machine Flow

Tasks progress through defined states enforced by @monotask/core/state-machine:

PENDING → ELICITATION → PLANNING → IN_PROGRESS →
WRITING_TESTS → IMPLEMENTING → VALIDATING →
NEEDS_REVIEW → COMPLETED

Each state has:

Entry/exit conditions
Allowed transitions
Terminal/active classification
Associated AI agent triggers

Database Architecture

Technology: SQLite with WAL mode for concurrent access
Location: .monotask/project.db (always use MONOTASK_DB_PATH env var)
Migrations: Sequential in /migrations, managed by MigrationRunner
Key Patterns:
- Repository pattern for data access (@monotask/shared/repositories)
- Transaction wrapper with automatic rollback
- Prepared statements for all queries
- Performance profiles (testing/default/performance)

Service Layer Design

Dashboard services (@monotask/dashboard/services) follow single-responsibility:

GitHubAppService: GitHub App token management with caching
OAuthService: Token encryption (AES-256-GCM)
IssueImportService: Background import with progress tracking
TaskStateService: State transition validation
Always use factory pattern: getGitHubAppService() for singletons

Cloudflare Workers Architecture

Cloudflare Workers provide serverless, globally distributed compute:

Core Workers:

agent-worker: AI agent orchestration with Claude API
- Agent types: Elicitation, TestWriter, Implementation, ContextGathering, Validation
- E2B sandbox integration for process execution
- R2 artifact storage
- Queue-based execution with retries
task-worker: Task state machine and CRUD operations
- State transition validation
- TaskCoordinator Durable Object for state history
- D1 database operations
- KV caching layer
- Real-time WebSocket notifications
github-worker: GitHub integration
- Webhook receiver with signature verification
- Issue/PR synchronization
- GitHub API proxy
- Installation management
websocket-worker: Real-time updates
- WebSocketRoom Durable Object with hibernation
- Room-based broadcasting
- Multi-room support
auth-worker: Authentication
- OAuth flow handling (GitHub OAuth)
- JWT token management
- Session management with KV storage
api-gateway: Request routing
- Service binding coordination
- Authentication middleware
- Rate limiting

Infrastructure:

Cloudflare Queues: TASK_QUEUE, GITHUB_QUEUE, AGENT_QUEUE
Durable Objects: TaskCoordinator, QueueManager, SandboxLifecycle, WebSocketRoom
D1 Database: Relational data (tasks, executions, installations)
KV Namespaces: CACHE, SESSIONS
R2 Buckets: AGENT_ARTIFACTS, FILE_VERSIONS

Package Dependencies & Module Resolution

TypeScript path aliases configured in tsconfig.json:

typescript

@monotask/core       → packages/core/src
@monotask/shared     → packages/shared/src
@monotask/ai         → packages/ai/src
@monotask/parser     → packages/parser/src
@monotask/cli        → packages/cli/src

Always use workspace imports (@monotask/*) instead of relative paths when crossing package boundaries.

API Endpoints (Cloudflare Workers)

Production Base URL: https://api-gateway.{your-subdomain}.workers.devLocal Development: http://localhost:8787 (via wrangler dev)

Core Task Operations (task-worker)

GET /api/tasks - List tasks with pagination and filtering
GET /api/tasks/:id - Get task details (with KV caching)
POST /api/tasks - Create new task
PUT /api/tasks/:id - Update task details
PUT /api/tasks/:id/state - Transition task state
DELETE /api/tasks/:id - Delete task (cascade)

GitHub Integration (github-worker)

POST /api/github/webhook - Webhook receiver
GET /api/github/installations - List installations
POST /api/github/installations/:id/sync - Sync installation
GET /api/github/repos/* - GitHub API proxy

Agent Execution (agent-worker)

POST /api/agents/execute - Queue agent execution
GET /api/agents/status?execution_id={id} - Get execution status
GET /api/agents/executions/:id - Get execution details

Authentication (auth-worker)

GET /api/auth/github/authorize - Initiate GitHub OAuth
GET /api/auth/github/callback - OAuth callback
POST /api/auth/refresh - Refresh token
POST /api/auth/logout - Logout and clear session
GET /api/auth/me - Get current user

Real-time Updates (websocket-worker)

WS /ws - WebSocket connection
WS /ws/rooms/:roomId - Join specific room
Supports room-based broadcasting for isolation

AI Agent System

Agents in @monotask/ai/agents handle different task phases:

Agent	Triggered By State	Purpose
ElicitationAgent	ELICITATION	Gather requirements through Q&A
TestWriterAgent	WRITING_TESTS	Generate test suites
ImplementationAgent	IMPLEMENTING	Write implementation code
ContextGatheringAgent	IN_PROGRESS	Background research

Agent execution flow:

Task state transition triggers queue message
Agent worker receives message from AGENT_QUEUE
Agent uses Claude API (model configurable via CLAUDE_MODEL)
Results persisted to D1 database and R2 storage
WebSocket broadcasts updates to frontend

Critical Implementation Notes

Database Connection Management

Always use process.env.MONOTASK_DB_PATH for database paths
Never use relative paths like ../../.monotask/project.db
Create separate connections for async operations to avoid "closed database" errors
Use withTransaction() wrapper for atomic operations

GitHub Integration

OAuth tokens encrypted with AES-256-GCM before storage
GitHub App private key in GITHUB_APP_PRIVATE_KEY env var
Installation tokens cached with expiration tracking
Use /api/auth/github/app/sync if installation exists but wasn't stored

Testing Best Practices

Unit tests adjacent to source (*.test.ts)
E2E tests in packages/e2e/tests
Use temporary databases for integration tests
Mock external services (GitHub API, Claude API)
Run bun test before commits

Performance Considerations

Database views for complex aggregations (validation_summary, latest_validation)
Prepared statements for all queries
WAL mode for concurrent read/write
Worker pool for CPU-intensive tasks
WebSocket for real-time updates instead of polling

Environment Variables

Cloudflare Workers (Set via Wrangler CLI)

Secrets (encrypted, use wrangler secret put):

bash

# Agent Worker
wrangler secret put ANTHROPIC_API_KEY        # Claude API key
wrangler secret put E2B_API_KEY              # E2B sandbox API key

# GitHub Worker
wrangler secret put GITHUB_WEBHOOK_SECRET    # Webhook signature verification
wrangler secret put GITHUB_TOKEN             # GitHub API token
wrangler secret put GITHUB_APP_PRIVATE_KEY   # GitHub App private key

# Auth Worker
wrangler secret put ENCRYPTION_KEY           # Token encryption key
wrangler secret put GITHUB_CLIENT_SECRET     # OAuth client secret

Variables (public, set in wrangler.toml):

toml

# wrangler.toml
[vars]
ENVIRONMENT = "production"
CLAUDE_MODEL = "claude-3-5-sonnet-20241022"
CLAUDE_MAX_TOKENS = "4096"
GITHUB_CLIENT_ID = "your-github-client-id"
E2B_TEMPLATE_ID = "your-e2b-template-id"

Local Development (Legacy Dashboard)

bash

# Database
MONOTASK_DB_PATH=.monotask/project.db
MONOTASK_PROJECT_ROOT=/path/to/project

# AI Configuration
ANTHROPIC_API_KEY=your-api-key
CLAUDE_MODEL=claude-3-opus-20240229

# GitHub Integration
GITHUB_APP_ID=your-app-id
GITHUB_APP_PRIVATE_KEY=your-private-key
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# Server
PORT=4000

Debugging Tips

Common Issues & Solutions

Worker deployment fails
- Verify wrangler.toml configuration
- Check that all bindings (D1, KV, R2, Queues) are created
- Run wrangler deploy --dry-run to preview changes
D1 database connection issues
- Verify database exists: wrangler d1 list
- Check database_id in wrangler.toml matches actual ID
- Apply migrations: wrangler d1 migrations apply DB
GitHub webhook not receiving events
- Verify webhook URL is correct in GitHub settings
- Check webhook secret matches GITHUB_WEBHOOK_SECRET
- Test signature verification with sample payload
- View webhook delivery history in GitHub
Agent execution timeouts
- Check Claude API key is valid
- Verify CPU time limit is configured (default 30s, can extend to 5 minutes)
- Review queue configuration for max_batch_timeout
- Check E2B sandbox provisioning
WebSocket connection issues
- Verify WebSocket URL uses wss:// (secure)
- Check Durable Object binding is configured
- Test connection with WebSocket client tool
- Review hibernation settings if scaling issues

Useful Debugging Commands

bash

# Worker logs (real-time streaming)
wrangler tail task-worker --env production
wrangler tail task-worker --env production --status error
wrangler tail task-worker --env production --format pretty

# Database inspection (D1)
wrangler d1 execute DB --command="SELECT * FROM tasks LIMIT 10"
wrangler d1 execute DB --command=".schema tasks"
wrangler d1 execute DB --file=query.sql

# KV inspection
wrangler kv:key list --namespace-id=YOUR_NAMESPACE_ID
wrangler kv:key get "task:123" --namespace-id=YOUR_NAMESPACE_ID

# R2 inspection
wrangler r2 object list AGENT_ARTIFACTS
wrangler r2 object get AGENT_ARTIFACTS executions/123/result.json

# Queue inspection
wrangler queues list
wrangler queues consumer list TASK_QUEUE

# Local development debugging
wrangler dev --local --persist  # Persist data between restarts
wrangler dev --log-level debug  # Verbose logging

Code Style Guidelines

TypeScript with strict mode enabled
ESM modules (no CommonJS)
Two-space indentation
Single quotes for strings
PascalCase for components: TaskDetail.tsx
camelCase for utilities: formatDate.ts
kebab-case for directories: task-detail/
Run bun run format before committing

Security Considerations

Prepared statements prevent SQL injection
OAuth tokens encrypted at rest (AES-256-GCM)
GitHub App private key in environment only
CSRF protection via state parameters
No sensitive data in API responses
Transaction isolation prevents race conditions

Claude ​

Project Overview ​

Core Development Commands ​

Cloudflare Workers Development ​

Local Development (Legacy Dashboard/Frontend) ​

Testing Commands ​

Build & Deployment ​

Cloudflare Workers Local Development ​

Architecture & Code Organization ​

Monorepo Structure ​

Key Architectural Patterns ​

State Machine Flow ​

Database Architecture ​

Service Layer Design ​

Cloudflare Workers Architecture ​

Package Dependencies & Module Resolution ​

API Endpoints (Cloudflare Workers) ​

Core Task Operations (task-worker) ​

GitHub Integration (github-worker) ​

Agent Execution (agent-worker) ​

Authentication (auth-worker) ​

Real-time Updates (websocket-worker) ​

AI Agent System ​

Critical Implementation Notes ​

Database Connection Management ​

GitHub Integration ​

Testing Best Practices ​

Performance Considerations ​

Environment Variables ​

Cloudflare Workers (Set via Wrangler CLI) ​

Local Development (Legacy Dashboard) ​

Debugging Tips ​

Common Issues & Solutions ​

Useful Debugging Commands ​

Code Style Guidelines ​

Security Considerations ​

Claude

Project Overview

Core Development Commands

Cloudflare Workers Development

Local Development (Legacy Dashboard/Frontend)

Testing Commands

Build & Deployment

Cloudflare Workers Local Development

Architecture & Code Organization

Monorepo Structure

Key Architectural Patterns

State Machine Flow

Database Architecture

Service Layer Design

Cloudflare Workers Architecture

Package Dependencies & Module Resolution

API Endpoints (Cloudflare Workers)

Core Task Operations (task-worker)

GitHub Integration (github-worker)

Agent Execution (agent-worker)

Authentication (auth-worker)

Real-time Updates (websocket-worker)

AI Agent System

Critical Implementation Notes

Database Connection Management

GitHub Integration

Testing Best Practices

Performance Considerations

Environment Variables

Cloudflare Workers (Set via Wrangler CLI)

Local Development (Legacy Dashboard)

Debugging Tips

Common Issues & Solutions

Useful Debugging Commands

Code Style Guidelines

Security Considerations