Techcle Wiki

Architecture Questions Round2

12 min read

OpenCode Slack Integration - Architecture Questions Round 2

Date: 2026-01-30
Project: .ai/projects/ai-dev/opencode-slack-integration
Context: Critical clarifications needed based on your feedback

Your Feedback Summary

From your annotations and comments, we understand:

✅ Confirmed Decisions

  • Workspace structure: Use .builders/{category-project}/repos/ with git worktrees (like codev)
  • State management: Git-based state in project directories
  • Category prefixes: Show “ai-dev/proj-name” in UIs, “ai-dev-proj-name” in channels
  • Multi-project: One task per project, multiple projects in parallel
  • Session persistence: Days/weeks of context, can survive OpenCode restarts
  • Slack workspace: Single workspace (yours)
  • Timeline: 1-2 weeks for MVP
  • Primary user: Solo use initially
  • Language: Python where appropriate

✅ Architecture Corrections You Made

  1. Generic gateway, not “Slack gateway” - Correct! Should be modular with connectors
  2. Lab namespace deployment is CRITICAL - Builders need to run code to complete work
  1. Workspace init reuse - Leverage existing task workspace:init from codev

Critical Questions We Need Answered

Section 1: OpenCode Session Management

Your question: “On tmux, are opencode sessions a similar concept? Can multiple sessions run in parallel and then sessions open in tabs in the browser?”

Our question back: How does your current ttyd + OpenCode setup work?

Please describe:

Q1.1: Current multi-project setup When you work on multiple projects today (e.g., proj-api-service and proj-frontend):

  • I run multiple separate OpenCode instances (how many? how started?)
  • I use tmux windows/panes with one OpenCode per window
  • I use a single OpenCode session and manually switch project context
  • Other: _________________

Details: At the moment i use codev & multiple instances of claude. Each claude instance is a seperate tmux session with its own multi repo worktree setup.

Q1.2: Browser access When you access ttyd in your browser:

  • I see one terminal (single OpenCode session)
  • I see multiple tabs (one per tmux window)
  • I see multiple browser tabs (one per ttyd instance)
  • Other: _________________

Details:

Q1.3: tmux layout If you use tmux, what’s your current layout?

Example 1:
tmux session "dev"
├── window 0: "api-service" → running OpenCode
├── window 1: "frontend" → running OpenCode  
└── window 2: "database" → running OpenCode

Example 2:
tmux session "opencode"
└── window 0: single OpenCode session, manually switch projects

Your setup:

tmux list-sessions af-architect-4401: 1 windows (created Wed Jan 28 20:28:02 2026) (attached) builder-workspace-root-task-XZ2A: 1 windows (created Thu Jan 29 10:32:36 2026) builder-workspace-root-task-rMsV: 1 windows (created Fri Jan 30 13:39:36 2026) (attached)

Note - these are claude, not opencode

Q1.4: OpenCode context switching When you switch from working on proj-a to proj-b:

  • I start a new OpenCode instance
  • I switch tmux windows
  • I tell OpenCode to change directory/project
  • I close and restart OpenCode
  • Other: _________________

Details:

Codev orchestrates this

Section 2: Deployment Infrastructure (CRITICAL)

Your critical feedback: “We can’t do without this - a builder will need to run their code somehow in order to complete its work.”

Absolutely right! This is now CORE MVP. We need to understand your current deployment flow.

Q2.1: Where does code run during development?

In codev today, when a builder is working on a task and needs to test code:

  • Docker Compose on local machine
  • Docker Compose on K8s node (running in pod)
  • K8s namespace per builder/task (e.g., builder-task-abc)
  • K8s namespace per project (e.g., proj-api-service-dev)
  • Shared K8s dev namespace (e.g., dev)
  • Other: _________________

Details: Because this will run on k8s itself, using docker compose would be complex. Having a namespace for each builder would allow it to spin up things fairly easily & tear down. We use kustomize but there may be a tool that can help with this (thinking something like skaffold)

Q2.2: How does deployment happen?

When a builder writes code and needs to deploy it for testing:

  • Automatic - File watcher triggers deployment
  • Manual command - Builder runs task deploy or similar
  • Git-based - Push to branch triggers CI/CD
  • Direct kubectl - Builder runs kubectl apply
  • Other: _________________

Details:

Kubectl + kustomize or skaffold i’d say

Q2.3: Container build process

When code changes, how are containers built?

  • Pre-built base images, mount code as volume (fast)
  • Build new image on every change (slower but isolated)
  • Mix - rebuild only when dependencies change
  • No containers - run code directly in pods
  • Other: _________________

Details:

We try to avoid building images, but when it’s necessary a github action pushing to ghcr and reference from there, see .ai/steering/docker-image-workflow.md

Q2.4: What infrastructure does a typical project need?

For example, for proj-api-service:

  • Just the app container
  • App + database (PostgreSQL, MySQL, etc.)
  • App + database + cache (Redis, etc.)
  • Full microservices stack (multiple services)
  • Depends heavily on project type

Common dependencies (check all that apply):

  • Database (specify which: _________)
  • Message queue (specify: _________)
  • Cache (Redis, Memcached, etc.)
  • External APIs/services
  • Storage (S3, MinIO, etc.)
  • Other: _________________

Details: I try to avoid stateful dependencies at the prototyping stage. Favour git storage

Q2.5: Namespace lifecycle

When a builder finishes a task:

  • Namespace is deleted immediately
  • Namespace stays alive for manual cleanup
  • Namespace stays alive for N days
  • Namespace is persistent (dev environment)
  • Other: _________________

Details:

Can be left, store the status in git and have tasks in taskfile to manage them

Q2.6: Testing against deployed services

After deployment, how do tests run?

  • Builder runs pytest or similar from their session
  • Tests run in separate pod/container
  • Tests are manual (builder checks health endpoints)
  • CI/CD pipeline runs tests
  • Other: _________________

Details:

See .ai/steering/testing-standards.md

Q2.7: Deployment timing

How long does: “make code change → deployed and testable” take?

  • < 30 seconds (very fast, mount volumes)
  • 1-2 minutes (fast image rebuild)
  • 3-5 minutes (full rebuild + deploy)
  • > 5 minutes (complex stack)

Details:

Section 3: Architecture Clarifications

Q3.1: “It needs to run it”

You said: “I think it needs to run it, as otherwise you won’t know it’s working”

What does “it needs to run it” mean?

  • The gateway should have a health check UI showing system status
  • The gateway should actively monitor OpenCode sessions are alive
  • The gateway should run tests on startup to verify everything works
  • The gateway should demonstrate a working deployment on startup
  • Other: _________________

Details: I mean, a builder needs to run what its building

Q3.2: Workspace init reuse

You mentioned reusing task workspace:init. Should we:

  • Invoke it directly via subprocess (call existing Taskfile)
  • Reimplement the logic in Python (own the code)
  • Use it as reference but adapt for our needs
  • Other: _________________

Details:

builder:init BUILDER_NAME=project-name REPOS=domain-apis,k8s-lab might be the correct task

Q3.3: Git worktree management

For the .builders/{category-project}/repos/ structure:

  • Gateway creates worktrees automatically when project starts
  • Worktrees are created manually first, gateway just uses them
  • Gateway uses existing workspace but doesn’t manage worktrees
  • Other: _________________

Details:

Section 4: Slack Interaction Details

Q4.1: Starting work

You said slash command or workflow form would be sensible. Our recommendation:

User types: /opencode start

Slack shows workflow form:
┌─────────────────────────────────┐
│ Start OpenCode Work Session     │
├─────────────────────────────────┤
│ Category:    [ai-dev        ▼] │
│ Project:     [proj-api-service] │
│ Task Title:  [________________] │
│ Description: [________________] │
│              [________________] │
│ Priority:    [High          ▼] │
│                                 │
│        [Cancel]  [Start]        │
└─────────────────────────────────┘

Bot creates thread in #ai-dev-proj-api-service channel

Is this the right flow?

  • Yes, perfect
  • Close, but adjust: _________________
  • No, prefer: _________________

Details:

Q4.2: Threading strategy

You said: “One thread per significant unit of work within a project”

Define “significant unit of work”:

  • Equals one task/feature (e.g., “Implement JWT auth”)
  • Equals one codev spec/plan item
  • Equals one PR/branch
  • Flexible - user decides when to start new thread
  • Other: _________________

I think the system can decide. I think a codev plan item task / feature is approxiamately the same thing?

Can multiple threads be active simultaneously for same project?

  • Yes - parallel work units in same project
  • No - one active thread per project at a time
  • Depends: _________________

Details:

Q4.3: Question timeout behavior

You said: “Include a default option & timeout (within 2 business hours) whereby work continues with best option if no response received.”

How should “2 business hours” be defined?

  • 2 hours wall clock time (even at 11pm)
  • 2 hours during business hours only (9am-5pm your timezone)
  • Configurable per project
  • Configurable per question urgency

What’s “best option”?

  • Agent picks safest/most conservative choice
  • Agent picks recommended option (marked in question)
  • Agent analyzes context and decides
  • Configurable default per question type

Details: I think it should be possible to answer, after the timeout, so git should be used to keep the changes seperate until an answer is confirmed. It may be ok to ask, but continue immediately with the recommended option?

Q4.4: Progress update frequency

You selected “Major milestones” and “Summary every N minutes”

What’s a major milestone?

  • Phase complete (e.g., “Implementation done”, “Tests written”)
  • Deployment complete (e.g., “Deployed to lab namespace”)
  • Tests passing (e.g., “All 23 tests pass”)
  • All of the above
  • Other: _________________

I think also significant changes within a phase

Summary frequency:

  • Every 5 minutes
  • Every 10 minutes
  • Every 15 minutes
  • Every 30 minutes
  • Configurable per project

Details:

Every 1-2 hours if there’s been no significant point reached

Section 5: Infrastructure & Constraints

Q5.1: Container registry

Where should built images be stored?

  • In-cluster registry (e.g., Harbor, registry:2)
  • Docker Hub (public or private repos)
  • GitHub Container Registry (ghcr.io)
  • Cloud provider registry (ECR, GCR, ACR)
  • Don’t know / need recommendation
  • Other: _________________

Details:

Q5.2: Build strategy

How should containers be built within K8s?

  • Kaniko (K8s-native, no Docker daemon needed) ← Recommended
  • Docker-in-Docker (requires privileged pod)
  • Buildah/Podman (rootless option)
  • External CI system (GitHub Actions, GitLab CI)
  • Don’t know / need recommendation
  • Other: _________________

Details:

We can set something up via the k8s lab project for this but we’ve mostly avoided building images, using uv and camel jbang to run things with config maps.

Q5.3: Manifest management

How should K8s manifests be generated/managed?

  • Simple templates with variable substitution
  • Kustomize (overlays for base + environment)
  • Helm charts
  • Direct kubectl apply of static YAML
  • Reuse existing patterns from projects
  • Don’t know / need recommendation

Details:

Helm charts when it’s going to be used more than once per environment Kustomise otherwise Consider skaffold

Q5.4: K8s cluster access

Does the gateway need special permissions?

  • Cluster admin (can do anything)
  • Namespace admin (can create namespaces + deploy within them)
  • Limited access (can only deploy to specific namespaces)
  • Use service account with RBAC
  • Don’t know / need recommendation

Details:

Q5.5: Existing infrastructure

What already exists in your K8s cluster?

  • Container registry
  • Ingress controller (for exposing services)
  • Certificate manager (for HTTPS)
  • Logging/monitoring (Prometheus, Grafana, etc.)
  • ArgoCD or other GitOps tools
  • Service mesh (Istio, Linkerd, etc.)
  • Shared databases/services builders can use
  • Other: _________________

Details:

N8n

Section 6: Example Workflow Validation

Please review this end-to-end workflow and annotate what’s wrong/missing:

┌─────────────────────────────────────────────────────────────┐
│ 1. Craig types: /opencode start                             │
│    Form: Category=ai-dev, Project=proj-api-service          │
│    Task="Implement JWT authentication"                      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Gateway receives webhook from Slack                      │
│    - Creates/finds tmux window for "ai-dev-proj-api-service"│
│    - Initializes workspace if needed:                       │
│      .builders/ai-dev-proj-api-service/repos/...            │
│    - Starts/attaches OpenCode session                       │
│    - Creates thread in #ai-dev-proj-api-service channel     │
└─────────────────────────────────────────────────────────────┘
                            ↓
<!-- At this point we need to consider BMAD - does this get sent to an architect, or product manager? Party mode? Depending on how much feedback/questions there could be a thread opened per question, or if a lot,  generate a document for annotation -->
┌─────────────────────────────────────────────────────────────┐
│ 3. Gateway sends task to OpenCode via tmux                  │
│    OpenCode: "Implement JWT authentication for API"         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. OpenCode works, Gateway posts progress to thread:        │
│    "✅ Analyzed existing auth implementation"               │
│    "✅ Created JWT token service"                           │
│    "⚙️ In progress: Writing middleware"                     │
└─────────────────────────────────────────────────────────────┘
                            ↓
<!-- At this point the question should become a new thread unless its within context of what was happening in a thread already? -->
┌─────────────────────────────────────────────────────────────┐
│ 5. OpenCode asks question:                                  │
│    "Should I use RS256 or HS256 for JWT signing?"           │
│    Gateway posts to thread with buttons                     │
│    Sets 2-hour timeout with default=RS256                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. Craig clicks "RS256" button from phone (30 min later)    │
│    Gateway sends response back to OpenCode                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. OpenCode completes implementation                        │
│    Gateway initiates deployment:                            │
│    - Builds container image                                 │
│    - Creates/updates namespace: ai-dev-proj-api-service-lab │
│    - Deploys to K8s                                         │
│    - Waits for pods ready                                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
<!-- Do you think the gateway does all these things, or a seperate component?
The domain for the components is *.lab.ctoaas.co, i'd suggest for the builders we might use <projects>.builder.lab.ctoaas.co?
 -->
┌─────────────────────────────────────────────────────────────┐
│ 8. Gateway runs tests against deployed service              │
│    Posts results to thread:                                 │
│    "✅ Unit tests: 23/23 passing"                           │
│    "✅ Integration tests: 12/12 passing"                    │
│    "🔗 Lab API: https://api-service-lab.example.com"        │
│    "🔗 Code Server: https://code.example.com/workspace/..." │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 9. Craig clicks "Approve & Promote" button                  │
│    Gateway: Creates PR? Merges to main? What happens?       │
└─────────────────────────────────────────────────────────────┘

What’s wrong or missing in this flow?

Your annotations:

Looks good. annotated above.

Summary: What We Need From You

CRITICAL (Blocks Architecture)

  1. OpenCode session management - How do you run multiple projects today?
  2. Deployment infrastructure - Where/how does code run for testing?
  3. Container build process - What exists today in your cluster?

IMPORTANT (Shapes Implementation)

  1. Threading strategy - What’s a “significant unit of work”?
  2. Timeout behavior - How to define “2 business hours” and “best option”?
  3. End-to-end workflow - What’s wrong/missing in our example?

HELPFUL (Nice to Know)

  1. Workspace init - Reuse vs reimplement?
  2. Registry choice - Where to store images?
  3. Manifest strategy - Kustomize, Helm, or simple templates?

Next Steps

Once you’ve annotated this document:

  1. Winston will finalize the architecture diagram
  2. Barry will create detailed implementation plan with deployment pipeline
  3. Sally will design the complete Slack UX flow
  4. Amelia will identify code components and dependencies
  5. John will revise timeline based on deployment complexity

Please annotate and let us know when ready!

Notes Section

Any additional thoughts or context:

Graph View