# 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*