docs(state): record phase 5 context session

.planning/STATE.md

@@ -3,11 +3,11 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: completed
-stopped_at: Completed 04-rbac-03-PLAN.md — all tasks complete, human-verify checkpoint approved
+stopped_at: Phase 5 context gathered
-last_updated: "2026-03-24T23:24:33.831Z"
+last_updated: "2026-03-25T01:59:49.880Z"
 last_activity: 2026-03-23 — Completed 03-02 onboarding wizard, Slack OAuth, BYO API keys
 progress:
-  total_phases: 4
+  total_phases: 5
   completed_phases: 4
   total_plans: 18
   completed_plans: 18
@@ -162,6 +162,6 @@ None — all phases complete.
 
 ## Session Continuity
 
-Last session: 2026-03-24T23:20:03.256Z
+Last session: 2026-03-25T01:59:49.877Z
-Stopped at: Completed 04-rbac-03-PLAN.md — all tasks complete, human-verify checkpoint approved
+Stopped at: Phase 5 context gathered
-Resume file: None
+Resume file: .planning/phases/05-employee-design/05-CONTEXT.md

.planning/phases/05-employee-design/05-CONTEXT.md

@@ -0,0 +1,111 @@
+# Phase 5: Employee Design - Context
+
+**Gathered:** 2026-03-24
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Three-path AI employee creation system: pre-built templates for one-click deployment, a guided wizard for step-by-step setup, and the existing Agent Designer as "Advanced" mode. Templates stored as DB seed data with card-grid gallery. Wizard auto-generates system prompts from user inputs. All paths produce agents editable in Agent Designer after creation.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### New Employee Entry Point
+- "New Employee" button presents three options: Templates / Guided Setup / Advanced
+- **Templates**: Card grid gallery of pre-built agents — one-click deploy
+- **Guided Setup**: 5-step wizard (Role → Persona → Tools → Channels → Escalation)
+- **Advanced**: Existing Agent Designer form — full manual control over all fields including system prompt
+- Labels: "Templates", "Guided Setup", "Advanced" — clear hierarchy from easiest to most control
+
+### Wizard Flow
+- 5 steps: Role definition → Persona setup → Tool selection → Channel assignment → Escalation rules
+- System prompt auto-generated from wizard inputs — hidden from user (never shown during wizard)
+- Final step: Review summary card showing everything configured, user clicks "Deploy Employee"
+- After deploy: agent goes live on selected channels immediately
+- Wizard-created agents appear in Agent Designer for later customization
+
+### Template Library
+- Templates stored as database seed data — platform admin can add/edit templates via portal
+- Card grid gallery with preview — each card shows: name, role description, included tools
+- "Preview" expands to show full configuration before deploying
+
+**V1 Templates (7+):**
+- Customer Support Rep — handles tickets, FAQs, troubleshooting, escalates complex issues
+- Sales Assistant — qualifies leads, answers product questions, books meetings
+- Office Manager — internal ops: onboarding, HR FAQs, IT help, scheduling
+- Project Coordinator — status updates, task tracking, meeting notes, deadline reminders
+- Financial Manager — high-level financial oversight and reporting
+- Controller — expense report management, budget tracking, financial controls
+- Accountant — invoice tracking, accounts payable, general accounting, billing
+
+### Template Deployment
+- One-click deploy — no customization step before deployment
+- Auto-assigns to all connected channels for the tenant
+- User can find the deployed agent in the employee list and edit via Agent Designer later
+- Template is a snapshot — deploying creates an independent agent that doesn't track template changes
+
+### Wizard vs Agent Designer Relationship
+- Agent Designer becomes the "Advanced" option for new employee creation
+- Also serves as the edit mode for all existing agents (regardless of how they were created)
+- Wizard-created and template-deployed agents are fully editable in Agent Designer
+- No functionality removed from Agent Designer — it remains the power-user tool
+
+### Claude's Discretion
+- Wizard step UI design (stepper, cards, progress indicator)
+- Template card visual design
+- Review summary card layout
+- How wizard inputs map to system prompt construction
+- Template seed data format and migration approach
+- Whether templates get a dedicated DB table or reuse the agents table with a `is_template` flag
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- The three-option entry point should make it obvious that Templates is the fastest path — "Deploy in 30 seconds"
+- Wizard should feel like hiring an employee — "What role will they fill?" not "Configure agent parameters"
+- Finance templates are important for SMB target market — accountants, controllers, financial managers are high-value hires that SMBs can't afford
+- Template preview should show enough to build confidence — "here's what this employee can do" with listed tools and sample behaviors
+
+</specifics>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `packages/portal/components/agent-designer.tsx` — Full agent form (Identity, Personality, Configuration, Capabilities, Escalation sections). Becomes "Advanced" mode.
+- `packages/portal/app/(dashboard)/agents/new/page.tsx` — Current new agent page. Needs to become the three-option entry point.
+- `packages/portal/lib/queries.ts` — TanStack Query hooks for agent CRUD (createAgent, updateAgent, etc.)
+- `packages/shared/shared/api/portal.py` — Agent CRUD endpoints (POST /tenants/{tid}/agents)
+- `packages/shared/shared/models/tenant.py:Agent` — Agent ORM model with all fields
+
+### Established Patterns
+- Forms: react-hook-form + zod + standardSchemaResolver
+- Components: shadcn/ui (Card, Button, Input, Select, etc.)
+- State: TanStack Query for server state
+- RBAC: `require_tenant_admin` guard on agent creation endpoints
+- Portal submodule: separate git repo in packages/portal
+
+### Integration Points
+- `app/(dashboard)/agents/new/page.tsx` — entry point needs to become three-option selector
+- Agent CRUD API — wizard and templates both create agents through existing POST endpoint
+- Template data — new DB table or flag on agents table, new seed migration
+- Template CRUD — platform admin needs endpoints to manage templates
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 05-employee-design*
+*Context gathered: 2026-03-24*