# Roadmap: Konstruct

## Overview

Konstruct ships in three coarse phases ordered by dependency: first build the secure multi-tenant pipeline and prove that a Slack message triggers an LLM response (Phase 1 — Foundation), then add the agent capabilities that make it a real product: memory, tools, WhatsApp, and escalation (Phase 2 — Agent Features), then complete the operator-facing experience so tenants can self-onboard and pay (Phase 3 — Operator Experience). Phase 3 is gated on DB schema stability, which only exists after Phase 2 defines the memory and tool data models.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Foundation** - Secure multi-tenant pipeline with Slack end-to-end and basic agent response (completed 2026-03-23)
- [ ] **Phase 2: Agent Features** - Persistent memory, tool framework, WhatsApp integration, and human escalation
- [ ] **Phase 3: Operator Experience** - Admin portal, tenant onboarding, and Stripe billing

## Phase Details

### Phase 1: Foundation
**Goal**: Operators can deploy the platform, a Slack message triggers an LLM response back in-thread, and no tenant can ever see another tenant's data
**Depends on**: Nothing (first phase)
**Requirements**: CHAN-01, CHAN-02, CHAN-05, AGNT-01, LLM-01, LLM-02, TNNT-01, TNNT-02, TNNT-03, TNNT-04, PRTA-01, PRTA-02
**Success Criteria** (what must be TRUE):
  1. A user can send a Slack @mention or DM to the AI employee and receive a coherent reply in the same thread — end-to-end in under 30 seconds
  2. Tenant A's messages, agent configuration, and conversation data are completely invisible to Tenant B — verified by integration tests with two-tenant fixtures
  3. A request that exceeds the per-tenant or per-channel rate limit is rejected with an informative response rather than silently dropped
  4. The LLM backend pool routes requests through LiteLLM to both Ollama (local) and Anthropic/OpenAI, with automatic fallback when a provider is unavailable
  5. A new AI employee can be configured with a custom name, role, and persona — and that persona is reflected in responses
  6. An operator can create tenants and design agents (name, role, persona, system prompt, tools, escalation rules) via the admin portal
**Plans**: 4 plans

Plans:
- [ ] 01-01: Monorepo scaffolding, Docker Compose dev environment, shared Pydantic models, DB schema with RLS
- [ ] 01-02: LiteLLM backend pool service with Ollama + Anthropic/OpenAI providers and Celery async dispatch
- [ ] 01-03: Channel Gateway (Slack adapter), Message Router (tenant resolution), basic Agent Orchestrator (single agent, no memory/tools)
- [ ] 01-04: Next.js admin portal with Auth.js v5, tenant CRUD, and Agent Designer module

### Phase 2: Agent Features
**Goal**: The AI employee maintains conversation memory, can execute tools, handles WhatsApp messages, and escalates to humans when rules trigger — making it a capable product rather than a demo
**Depends on**: Phase 1
**Requirements**: CHAN-03, CHAN-04, AGNT-02, AGNT-03, AGNT-04, AGNT-05, AGNT-06
**Success Criteria** (what must be TRUE):
  1. The AI employee remembers context from earlier in the same conversation and can reference it accurately — tested at 30+ conversation turns without degradation
  2. A user can send a WhatsApp message to the AI employee and receive a reply — with per-tenant phone number isolation and business-function scoping enforced per Meta 2026 policy
  3. The agent can invoke a registered tool (e.g., knowledge base search) and incorporate the result into its response
  4. When a configured escalation rule triggers (e.g., failed resolution attempts), the conversation and full context are handed off to a human with no information lost
  5. Every LLM call, tool invocation, and handoff event is recorded in an immutable audit trail queryable by tenant
**Plans**: 5 plans

Plans:
- [ ] 02-01: Conversational memory layer (Redis sliding window + pgvector long-term storage with HNSW index)
- [ ] 02-02: Tool framework (registry, schema-validated execution, audit logging) — split into audit+tools+wiring
- [ ] 02-03: WhatsApp adapter (Business Cloud API, per-tenant phone numbers, media download, Meta policy compliance)
- [ ] 02-04: Human escalation/handoff with full context transfer and audit trail
- [ ] 02-05: Cross-channel media support and multimodal LLM interpretation (Slack file_share, image_url content blocks, channel-aware outbound routing)

### Phase 3: Operator Experience
**Goal**: An operator can sign up, onboard their tenant through a web UI, connect their messaging channels, configure their AI employee, and manage their subscription — without touching config files or the command line
**Depends on**: Phase 2
**Requirements**: AGNT-07, LLM-03, PRTA-03, PRTA-04, PRTA-05, PRTA-06
**Success Criteria** (what must be TRUE):
  1. An operator can connect Slack and WhatsApp to their tenant through a guided in-portal wizard without reading documentation
  3. A new tenant completes the full onboarding sequence (connect channel → configure agent → send test message) in under 15 minutes
  4. An operator can subscribe, upgrade, and cancel their plan through Stripe — and feature limits are enforced automatically based on subscription state
  5. The portal displays per-tenant agent cost and token usage, giving operators visibility into spending without requiring access to backend logs
**Plans**: 4 plans

Plans:
- [ ] 03-01: Channel connection wizard (Slack + WhatsApp), onboarding flow, portal polish
- [ ] 03-03: Stripe subscription integration, cost tracking dashboard, usage metrics display

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation | 4/4 | Complete    | 2026-03-23 |
| 2. Agent Features | 0/5 | Not started | - |
| 3. Operator Experience | 0/2 | Not started | - |

---

## Coverage Notes

**LLM-03 conflict flagged:** LLM-03 (BYO API keys, encrypted at rest) is listed as a v1 requirement in REQUIREMENTS.md but is explicitly listed as out-of-scope in PROJECT.md ("BYO API key support — v2"). LLM-03 has been assigned to Phase 3 (least disruptive placement) but this conflict must be resolved before Phase 3 planning begins. Options: (1) confirm v2 deferral and move LLM-03 to REQUIREMENTS.md v2 section, or (2) confirm it's in scope for v1 and keep in Phase 3.

---
*Roadmap created: 2026-03-23*
*Coverage: 25/25 v1 requirements mapped*