kandev/apps/backend/NEXT_STEPS.md

Kandev Backend - Next Steps

Current State (2026-01-10)

The backend is a unified Go binary (cmd/kandev/main.go) that runs:

• Task Service: Kanban board/column/task management (SQLite persistence)
• Agent Manager: Docker container lifecycle for AI agents
• Orchestrator: Coordinates task execution with agents

Working Features

1. SQLite Persistence

   • Database file: ./kandev.db (configurable via KANDEV_DB_PATH)
   • Stores boards, columns, and tasks with metadata
   • WAL mode enabled for concurrent reads
   • Data survives server restarts

2. Augment Agent Integration

   • Docker image: kandev/augment-agent:latest
   • Uses Auggie CLI with --print --output-format json
   • ACP (Agent Communication Protocol) message streaming
   • Session ID extraction and storage in task metadata

3. Session Resumption

   • Sessions persist in ~/.augment/sessions/ (mounted into containers)
   • Follow-up agents can resume with AUGGIE_SESSION_ID env var

4. Real-time Streaming

   • Container logs parsed for ACP JSON messages
   • Events published to in-memory event bus
   • WebSocket endpoints available for frontend

Immediate Next Steps

1. Agent Run History

Track all agent executions:

• Add agent_runs table to SQLite schema
• Store task_id, session_id, started_at, completed_at, exit_code
• Link runs to tasks for history viewing
• Store ACP messages for replay

2. Frontend Integration

• Create React/Vue frontend for Kanban board
• WebSocket client for real-time agent progress
• Task detail view with agent history and session resumption

3. Automatic Task Orchestration

• Configure tasks with agent_type field
• Auto-launch agents when tasks move to specific columns
• Handle agent failures with retry logic

API Reference

All communication happens over WebSocket at ws://localhost:8080/ws. See docs/WEBSOCKET_API.md for complete API documentation.

Key Actions

Action	Description
board.create	Create a new board
task.create	Create a task
task.subscribe	Subscribe to ACP streaming for a task
orchestrator.start	Start executing a task with an agent
agent.prompt	Send follow-up prompt to running agent

Development Commands

# Build
cd apps/backend && go build -o kandev ./cmd/kandev

# Run server
./kandev

# Build Docker image
cd apps/backend/dockerfiles/augment-agent && docker build -t kandev/augment-agent:latest .

Key Files

File	Purpose
cmd/kandev/main.go	Unified entry point, ACP handlers
internal/task/repository/interface.go	Repository interface definition
internal/task/repository/sqlite.go	SQLite implementation with schema
internal/task/repository/memory.go	In-memory implementation (for testing)
internal/agent/lifecycle/manager.go	Container lifecycle, mount templates
internal/agent/registry/defaults.go	Agent type definitions
internal/agent/streaming/reader.go	ACP message parsing from logs
dockerfiles/augment-agent/agent.sh	Container entrypoint script
dockerfiles/augment-agent/Dockerfile	Agent Docker image

Architecture Decisions

1. SQLite with WAL mode for simple, file-based persistence
2. In-memory event bus instead of NATS for simpler development
3. One agent per task constraint (prevents conflicts)
4. Session files mounted from host for persistence across container runs
5. ACP protocol for structured agent-to-server communication
6. Repository interface allows swapping storage backends (SQLite, Memory, PostgreSQL)

Configuration

Environment variables:

• KANDEV_DB_PATH - SQLite database file path (default: ./kandev.db)
• KANDEV_LOGGING_LEVEL - Log level: debug, info, warn, error (default: info)
• KANDEV_CREDENTIALS_FILE - Path to credentials file for agents