Techcle Wiki

Prd

9 min read

Product Requirements Document: OpenCode Slack Integration

Product: OpenCode Slack Integration
Category: ai-dev
Status: In Development
Owner: Craig
Created: 2026-01-30
Updated: 2026-01-31
Version: 1.0

Executive Summary

The OpenCode Slack Integration provides a mobile-first, asynchronous interface for AI-assisted development using OpenCode CLI. It enables developers to initiate, monitor, and interact with AI development sessions from Slack, with automatic deployment to Kubernetes lab namespaces for testing.

Problem Statement

Current OpenCode usage requires:

  • VPN + web access via ttyd for terminal interaction
  • Desktop/laptop for meaningful interaction (mobile is awkward)
  • Synchronous engagement (must be present while work progresses)
  • No notifications when agents make progress or encounter blockers

This creates friction for developers who need to work across multiple projects asynchronously and want mobile access to their development workflow.

Solution

A Slack-based gateway that:

  1. Routes development tasks to appropriate BMAD agents (Architect/PM/Builder)
  2. Manages isolated OpenCode sessions per project using workspace worktrees
  3. Deploys work-in-progress to Kubernetes lab namespaces for validation
  4. Provides async notifications and mobile-friendly interaction patterns

User Personas

Primary: Solo Developer (Craig)

Context:

  • Works on multiple projects simultaneously (one task per project)
  • Needs to context-switch frequently
  • Values async workflows with mobile accessibility
  • Prefers git-based state management and minimal infrastructure overhead

Goals:

  • Start development work via Slack from anywhere
  • Receive progress updates without constant monitoring
  • Approve/reject agent questions from mobile device
  • Test deployed code in isolated lab environments

Pain Points:

  • Desktop-only terminal access blocks mobile workflows
  • No async notifications when agents need input
  • Context switching requires manual session management
  • Testing requires manual deployment setup

Product Goals

MVP Goals (1-2 weeks)

  1. Slack Interaction

    • /opencode start command with workflow form
    • Thread-based conversation per work unit
    • Interactive buttons for approvals and questions
    • Progress updates for major milestones

  2. Session Management

    • Create isolated builder workspaces using par (workspace manager)
    • Route tasks to appropriate BMAD agents
    • Maintain session state across days/weeks
    • Support multiple parallel projects

  3. Lab Deployment

    • Deploy code to K8s namespace per builder
    • Use ConfigMap/PVC strategy for fast deployment (no image builds)
    • Create ingress at <project>.builder.lab.ctoaas.co
    • Run tests against deployed services

  4. Agent Integration

    • BMAD routing suggestions (architect/PM/builder/party-mode)
    • Question handling with timeouts and recommended defaults
    • Progress tracking and milestone reporting

Future Goals (Post-MVP)

  • Multi-user collaboration (team access)
  • Additional chat integrations (Discord, Teams)
  • Enhanced deployment strategies (image builds when needed)
  • Advanced monitoring and observability

Requirements

Functional Requirements

FR-1: Slack Command Interface

Priority: P0 (Must Have)

Description: Users can initiate development work via Slack slash command.

Acceptance Criteria:

  • /opencode start opens a workflow form
  • Form includes: category, project, repositories, task title/description, priority
  • Form submission creates a new work session
  • System creates dedicated thread for the work session
  • User receives confirmation with session details

FR-2: BMAD Routing

Priority: P0 (Must Have)

Description: System suggests appropriate BMAD agent based on task complexity.

Acceptance Criteria:

  • System analyzes task title and description
  • Provides routing suggestion (architect/PM/builder/party-mode) with confidence score
  • Suggests AI model to use from available options:
    • Claude Code (via Anthropic API) - for architecture and complex reasoning
    • Qwen 2.5 Coder 32B (locally hosted) - for code generation and implementation
  • Configurable in global application state
  • Shows reasoning for both agent type and model suggestion
  • User can confirm or override routing and model decision
  • Routing decision (agent + model) is recorded in session state

FR-3: Workspace Management

Priority: P0 (Must Have)

Description: System creates isolated builder workspaces using par workspace manager.

Acceptance Criteria:

  • System invokes task builder:init BUILDER_NAME={project} REPOS={repos}
  • Workspace includes workspace-root and specified repositories
  • Each workspace is isolated from other sessions
  • Workspace state persists across OpenCode session restarts
  • Workspace can be cleaned up when work is complete

FR-4: OpenCode Session Bridge

Priority: P0 (Must Have)

Description: System spawns and communicates with OpenCode sessions.

Acceptance Criteria:

  • System spawns OpenCode session in builder workspace
  • Session integrates with standard OpenCode session management (visible in opencode session list)
  • Session appears in OpenCode web UI alongside manually-created sessions
  • User messages from Slack are forwarded to OpenCode
  • OpenCode output is parsed and formatted for Slack
  • Questions from agents are detected and presented as interactive messages
  • Progress milestones are posted to thread
  • Session can be accessed from both Slack and OpenCode web UI (with appropriate conflict handling)

FR-5: Lab Deployment

Priority: P0 (Must Have)

Description: System deploys code to Kubernetes lab namespace for testing.

Acceptance Criteria:

  • System creates namespace: {project}-lab
  • Deployment uses ConfigMap/PVC strategy (no image builds for MVP)
  • Ingress created at {project}.builder.lab.ctoaas.co
  • System waits for pods ready before declaring success
  • Lab URL is posted to Slack thread

FR-6: Test Execution

Priority: P0 (Must Have)

Description: System runs tests against deployed code.

Acceptance Criteria:

  • Unit tests run in OpenCode session context
  • Integration tests run against lab URL
  • Acceptance tests verify critical flows
  • Test results formatted and posted to Slack
  • All-passing status clearly indicated

FR-7: Question Handling

Priority: P1 (Should Have)

Description: System handles agent questions with timeouts and defaults.

Acceptance Criteria:

  • Questions posted to Slack with interactive buttons
  • Timeout configured (default: 2 business hours)
  • Recommended option indicated
  • If no response within timeout, work continues with recommended option
  • Late responses are accepted and handled appropriately
  • Questions can spawn new threads for complex discussions

FR-8: Progress Updates

Priority: P1 (Should Have)

Description: System provides progress visibility without overwhelming user.

Acceptance Criteria:

  • Major milestones posted to thread (phase complete, tests passing, deployment ready)
  • Significant changes within a phase are reported
  • Summary posted every 1-2 hours if no milestones reached
  • Updates configurable per project
  • Updates include emojis and clear formatting

FR-9: Multi-Project Support

Priority: P0 (Must Have)

Description: User can work on multiple projects in parallel.

Acceptance Criteria:

  • Each project has isolated workspace and session
  • Sessions can run concurrently
  • User can switch between projects via Slack
  • Session state tracked per project
  • No cross-contamination of context between projects

FR-10: Session Persistence

Priority: P1 (Should Have)

Description: Sessions survive service restarts and long periods of inactivity.

Acceptance Criteria:

  • Session state stored in git (.session-state.yaml)
  • OpenCode sessions can be resumed after restart
  • Work context preserved across days/weeks
  • User can explicitly pause/resume sessions

Non-Functional Requirements

NFR-1: Response Time

Priority: P0 (Must Have)

  • Slack commands acknowledge within 3 seconds
  • Deployment to lab namespace completes in < 30 seconds
  • Question responses forwarded to OpenCode within 1 second

NFR-2: Reliability

Priority: P0 (Must Have)

  • System recovers gracefully from Slack webhook failures (retry logic)
  • Session state never lost (git-backed persistence)
  • Deployment failures clearly communicated with recovery options

NFR-3: Security

Priority: P0 (Must Have)

  • Slack webhook signatures verified
  • K8s service account with least-privilege RBAC
  • Lab namespaces isolated from production
  • No secrets exposed in Slack messages

NFR-4: Scalability

Priority: P2 (Nice to Have - Future)

  • MVP: Single user, < 10 concurrent sessions
  • Future: Multiple users, 50+ concurrent sessions

User Workflows

Workflow 1: Start New Development Task

  1. User types /opencode start in Slack
  2. Workflow form appears with pre-populated fields
  3. User fills: category, project, repositories, task details, priority
  4. System creates builder workspace
  5. System analyzes task and suggests BMAD routing
  6. User confirms or overrides routing
  7. System spawns OpenCode session and routes to appropriate agent
  8. Thread created in project-specific channel
  9. Agent begins work, posting progress updates

Workflow 2: Answer Agent Question

  1. Agent posts question to thread with interactive buttons
  2. User receives notification (mobile or desktop)
  3. User clicks button to select option
  4. Response sent to OpenCode session
  5. Agent acknowledges and continues work
  6. (Alternative) If no response within timeout, agent continues with recommended option

Workflow 3: Review and Deploy to Lab

  1. Agent completes implementation
  2. System requests deployment confirmation
  3. Deployment plan posted to thread (namespace, domain, strategy, tests)
  4. User clicks “Deploy” button
  5. System creates namespace, applies manifests, sets up ingress
  6. Real-time progress streamed to thread
  7. Tests run automatically
  8. Results posted with lab URL and Code Server link
  9. User can test deployed service

Workflow 4: Approve and Promote

  1. User reviews deployed code and test results
  2. User clicks “Approve & Promote” button
  3. System creates PR or merges to main (TBD in architecture)
  4. Namespace can be kept or cleaned up (user choice)
  5. Session marked complete

Success Metrics

MVP Success Criteria

  • Successfully start development session via Slack: 100% success rate
  • Deploy to lab namespace within 30 seconds: 90% of deployments
  • Questions answered within 2 business hours: 80% of questions
  • Zero lost session state incidents

User Satisfaction

  • Mobile interaction feels natural and responsive
  • Async workflow reduces “waiting time” perception
  • Lab deployment “just works” without manual intervention
  • Clear visibility into what agents are doing

Out of Scope (MVP)

  • Multi-user collaboration
  • Image building (using ConfigMap/PVC only)
  • Advanced deployment strategies (Helm, complex Kustomize)
  • Integration with external CI/CD systems
  • Custom slash commands beyond /opencode start
  • Detailed observability and monitoring dashboards

Dependencies

Technical Dependencies

  • OpenCode CLI: Installed and functional
  • Par (Workspace Manager): For multi-repo workspace management
  • Kubernetes Cluster: With ingress controller, cert-manager
  • Slack Workspace: With permissions to create custom apps
  • Git: For workspace and state management

Infrastructure Dependencies

  • K8s namespace creation permissions
  • Ingress domain: *.builder.lab.ctoaas.co
  • PVC storage for code files
  • Service account with appropriate RBAC

Open Questions

Architecture Questions (To be resolved in Architecture phase)

  1. Deployment Strategy: What happens on “Approve & Promote”? Create PR? Direct merge? GitOps?
  2. Workspace Pattern: Confirm par workspace manager is the correct approach (not sibling worktrees)
  3. Question Timeout Behavior: How to handle git branching when continuing with recommended option before user confirms?
  4. Component Responsibility: Does gateway handle all deployment logic, or separate deployment service?
  5. Threading Strategy: When to create new threads vs continue in existing thread?
  6. Model Selection Strategy: How to determine which model (Claude vs Qwen) for each agent type and task?
  7. Model Availability: Fallback strategy when suggested model is unavailable?
  8. Session Ownership: How to handle concurrent access from Slack bot and human via web UI?
  9. Session Visibility: Should web UI distinguish Slack-managed sessions from manual sessions?

Implementation Questions (To be resolved in Planning phase)

  1. OpenCode Bridge: How to reliably detect questions vs progress in output?
  2. SSE vs WebSocket for deployment progress streaming?
  3. Mock strategies for parallel development of Slack and Backend components

Appendices

  • discovery-questions.md - Annotated requirements from user
  • architecture-questions-round2.md - Technical clarifications
  • api-contract.md - Slack ↔ Backend interface
  • work-package-backend.md - Backend implementation scope
  • work-package-slack.md - Slack connector implementation scope

Appendix B: Terminology

  • Builder Workspace: Isolated directory created by par containing workspace-root and project repos
  • Lab Namespace: Kubernetes namespace for testing work-in-progress code
  • BMAD Routing: Decision of which agent type handles the work (architect/PM/builder/party-mode)
  • Par: Parallel Worktree & Session Manager - tool for managing multi-repo workspaces
  • ConfigMap/PVC Strategy: Fast deployment using ConfigMaps for small files, PVCs for large files (no image builds)

Next Step: Create Architecture Decision Document to resolve open questions and finalize technical design.

Graph View