docs(01): capture phase context

.planning/REQUIREMENTS.md

@@ -41,7 +41,7 @@ Requirements for beta-ready release. Each maps to roadmap phases.
 ### Admin Portal
 
 - [ ] **PRTA-01**: Operator can create, view, update, and delete tenants
-- [ ] **PRTA-02**: Operator can configure agent role, persona, tools, and escalation rules via web UI
+- [ ] **PRTA-02**: Operator can design agents via a dedicated Agent Designer module — defining job description, statement of work, persona, system prompt, tool assignments, and escalation rules
 - [ ] **PRTA-03**: Operator can connect messaging channels (Slack, WhatsApp) via guided wizard
 - [ ] **PRTA-04**: New tenants are guided through structured onboarding (connect channel, configure agent, test message)
 - [ ] **PRTA-05**: Operator can manage subscription plans and billing via Stripe integration
@@ -82,7 +82,7 @@ Deferred to future release. Tracked but not in current roadmap.
 | Voice/telephony channels (Twilio) | Completely different tech stack and regulatory environment; validate messaging first |
 | Open-ended general-purpose WhatsApp bot | Banned by Meta (Jan 2026 policy); agents must serve specific business functions |
 | Real-time token streaming in chat | Slack/WhatsApp don't support partial message streaming; zero user benefit |
-| Full no-code agent builder | Premature abstraction before agent quality is proven; config-based setup is sufficient |
+| Full no-code visual agent builder (drag-and-drop) | Agent Designer covers structured text-based configuration; visual flow builders are premature |
 | Cross-tenant agent communication | Security/isolation violation; no compliance framework supports it |
 | Dashboard-first UX for end users | Defeats core value proposition; agent interactions stay in messaging channels |
 | White-labeling for agencies | Secondary market; validate direct SMB first |
@@ -114,8 +114,8 @@ Which phases cover which requirements. Updated during roadmap creation.
 | TNNT-02 | Phase 1 | Pending |
 | TNNT-03 | Phase 1 | Pending |
 | TNNT-04 | Phase 1 | Pending |
-| PRTA-01 | Phase 3 | Pending |
+| PRTA-01 | Phase 1 | Pending |
-| PRTA-02 | Phase 3 | Pending |
+| PRTA-02 | Phase 1 | Pending |
 | PRTA-03 | Phase 3 | Pending |
 | PRTA-04 | Phase 3 | Pending |
 | PRTA-05 | Phase 3 | Pending |

.planning/ROADMAP.md

@@ -21,19 +21,21 @@ Decimal phases appear between their surrounding integers in numeric order.
 ### 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
+**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**: TBD
 
 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
@@ -56,18 +58,16 @@ Plans:
 ### 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-01, PRTA-02, PRTA-03, PRTA-04, PRTA-05, PRTA-06
+**Requirements**: AGNT-07, LLM-03, PRTA-03, PRTA-04, PRTA-05, PRTA-06
 **Success Criteria** (what must be TRUE):
-  1. An operator can create a tenant, configure an AI employee's name, role, persona, tools, and escalation rules entirely through the portal web UI
+  1. An operator can connect Slack and WhatsApp to their tenant through a guided in-portal wizard without reading documentation
-  2. 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**: TBD
 
 Plans:
-- [ ] 03-01: Next.js 16 admin portal foundation with Auth.js v5, API layer, tenant CRUD
+- [ ] 03-01: Channel connection wizard (Slack + WhatsApp), onboarding flow, portal polish
-- [ ] 03-02: Agent configuration UI, channel connection wizard (Slack + WhatsApp), onboarding flow
 - [ ] 03-03: Stripe subscription integration, cost tracking dashboard, usage metrics display
 
 ## Progress
@@ -77,9 +77,9 @@ Phases execute in numeric order: 1 → 2 → 3
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Foundation | 0/3 | Not started | - |
+| 1. Foundation | 0/4 | Not started | - |
 | 2. Agent Features | 0/4 | Not started | - |
-| 3. Operator Experience | 0/3 | Not started | - |
+| 3. Operator Experience | 0/2 | Not started | - |
 
 ---
 

.planning/phases/01-foundation/01-CONTEXT.md

@@ -0,0 +1,82 @@
+# Phase 1: Foundation - Context
+
+**Gathered:** 2026-03-23
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Secure multi-tenant pipeline: a Slack message triggers an LLM response in-thread, with full tenant isolation. Includes monorepo scaffolding, Docker Compose dev environment, PostgreSQL with RLS, Redis namespacing, LiteLLM backend pool, Channel Gateway (Slack adapter), Message Router, basic Agent Orchestrator (single agent per tenant, no memory/tools), and a Next.js admin portal with tenant CRUD and Agent Designer.
+
+**Scope change from roadmap:** Portal (PRTA-01, partial PRTA-02) pulled forward into Phase 1. Phase 3 retains billing, onboarding wizard, cost dashboard, and channel connection wizard.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Tenant Provisioning
+- Next.js portal starts in Phase 1 — not deferred to Phase 3
+- Portal includes tenant CRUD (create, list, view, edit, delete tenants)
+- Portal includes Agent Designer module (job description, SOW, persona, system prompt, tool assignments, escalation rules)
+- Auth.js v5 with email/password authentication from the start — no hardcoded credentials, no throwaway auth code
+- Phase 3 scope narrows to: Stripe billing integration, onboarding wizard, cost tracking dashboard, channel connection wizard, and portal polish
+
+### Agent Identity
+- AI employees have human-like names by default (e.g., "Mara", "Alex") — matches the "hire an AI employee" branding
+- Default persona tone: professional + warm — friendly but business-appropriate, like a good colleague
+- Always transparent about being AI when asked directly — never pretends to be human
+- Silent until spoken to — no auto-introduction message when added to a Slack channel
+- Operator configures name, role, persona, and system prompt via the Agent Designer in the portal
+
+### Slack Interaction Model
+- Agent responds to: @mentions in channels and direct messages
+- Does NOT monitor entire channels or respond to all messages (no "designated support channel" mode in v1)
+- Always replies in threads — keeps channels clean
+- Shows typing indicator while LLM is generating a response
+- Thread follow-up behavior: Claude's discretion (auto-follow engaged threads vs require @mention for each reply)
+
+### Claude's Discretion
+- Thread follow-up behavior (auto-follow after first engagement vs always require @mention)
+- Portal UI layout and component choices (within shadcn/ui)
+- Default AI employee name suggestions
+- Agent Designer form layout and field ordering
+- Error message copy and formatting
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- The Agent Designer is a dedicated, prominent module in the portal — not buried in a settings page. It's the primary way operators define what their AI employee does.
+- Agent Designer fields include: job description, statement of work, persona, system prompt, tool assignments, and escalation rules — all text inputs, not drag-and-drop.
+- The "employee" metaphor is central to the product — names, roles, and behavior should reinforce this (not "bot" or "assistant" language).
+
+</specifics>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- None — greenfield project, no existing code
+
+### Established Patterns
+- None yet — Phase 1 establishes all foundational patterns
+
+### Integration Points
+- CLAUDE.md defines the full repo structure and tech stack choices
+- Research docs (.planning/research/) provide library version recommendations and architectural patterns
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 01-foundation*
+*Context gathered: 2026-03-23*