---
phase: 05-employee-design
plan: 02
subsystem: ui
tags: [nextjs, react, tanstack-query, react-hook-form, shadcn, typescript]

# Dependency graph
requires:
  - phase: 05-01
    provides: "Template backend API (GET /api/portal/templates, POST /api/portal/templates/{id}/deploy), AgentTemplate model, build_system_prompt Python function"
provides:
  - "Three-option entry screen at /agents/new (Templates, Guided Setup, Advanced)"
  - "Template gallery at /agents/new/templates with card grid, preview dialog, one-click deploy"
  - "5-step wizard at /agents/new/wizard (Role, Persona, Tools, Channels, Escalation + Review)"
  - "Advanced mode at /agents/new/advanced (existing AgentDesigner in create mode)"
  - "EmployeeWizard component with stepper and React state management"
  - "TemplateGallery component with TanStack Query hooks"
  - "system-prompt-builder.ts mirroring Python build_system_prompt"
  - "Template and TemplateDeployResponse TypeScript types in api.ts"
  - "useTemplates and useDeployTemplate TanStack Query hooks"
affects: [agent-editing, employee-management]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Three-option creation entry pattern (Templates / Wizard / Advanced)"
    - "Wizard state in React useState (not URL) — persona text would pollute URL"
    - "URL step param for stepper position (shareable, router.replace for history hygiene)"
    - "base-ui Select onValueChange null coercion with ?? '' for TypeScript compatibility"

key-files:
  created:
    - packages/portal/app/(dashboard)/agents/new/page.tsx
    - packages/portal/app/(dashboard)/agents/new/advanced/page.tsx
    - packages/portal/app/(dashboard)/agents/new/templates/page.tsx
    - packages/portal/app/(dashboard)/agents/new/wizard/page.tsx
    - packages/portal/components/employee-wizard.tsx
    - packages/portal/components/template-gallery.tsx
    - packages/portal/components/wizard-steps/step-role.tsx
    - packages/portal/components/wizard-steps/step-persona.tsx
    - packages/portal/components/wizard-steps/step-tools.tsx
    - packages/portal/components/wizard-steps/step-channels.tsx
    - packages/portal/components/wizard-steps/step-escalation.tsx
    - packages/portal/components/wizard-steps/step-review.tsx
    - packages/portal/lib/system-prompt-builder.ts
  modified:
    - packages/portal/lib/api.ts
    - packages/portal/lib/queries.ts

key-decisions:
  - "Wizard state held in React useState — persona text in URL would be impractical and polluting"
  - "Channels step is informational in v1 — agent routing is tenant-scoped, not per-agent"
  - "Template gallery uses Dialog for preview — prevents page navigation, keeps context"

patterns-established:
  - "WizardData interface exported from employee-wizard.tsx for use by all step components"
  - "Step components receive data: Partial<WizardData> and onNext: (updates) => void"
  - "buildSystemPrompt always appends AI transparency clause — non-negotiable"

requirements-completed: [EMPL-01, EMPL-02, EMPL-03, EMPL-04, EMPL-05]

# Metrics
duration: 5min
completed: 2026-03-25
---

# Phase 5 Plan 02: Employee Design Frontend Summary

**Three-option employee creation UI: template gallery with one-click deploy, 5-step guided wizard with auto-generated system prompt, and Advanced AgentDesigner — all routes live and building clean**

## Performance

- **Duration:** 5 min
- **Started:** 2026-03-25T02:34:33Z
- **Completed:** 2026-03-25T02:39:33Z
- **Tasks:** 2
- **Files modified:** 15

## Accomplishments

- Three-option entry screen at /agents/new routes to Templates, Guided Setup, or Advanced with "Recommended" badge on Templates card
- Template gallery fetches from /api/portal/templates, shows card grid with preview dialog and one-click deploy; redirects to agent edit page on success
- 5-step wizard (Role, Persona, Tools, Channels, Escalation) plus Review & Deploy step; auto-generates system prompt with AI transparency clause via buildSystemPrompt
- Advanced page at /agents/new/advanced renders existing AgentDesigner unchanged in create mode
- TypeScript Template types, useTemplates and useDeployTemplate hooks, system-prompt-builder.ts added

## Task Commits

Each task was committed atomically:

1. **Task 1: Entry screen, advanced page, types, hooks, system prompt builder** - `55873bb` (feat)
2. **Task 2: Template gallery, wizard, all step components** - `de23e9e` (feat)

## Files Created/Modified

- `packages/portal/app/(dashboard)/agents/new/page.tsx` - Three-option entry screen
- `packages/portal/app/(dashboard)/agents/new/advanced/page.tsx` - AgentDesigner in create mode
- `packages/portal/app/(dashboard)/agents/new/templates/page.tsx` - Template library page
- `packages/portal/app/(dashboard)/agents/new/wizard/page.tsx` - 5-step wizard page
- `packages/portal/components/employee-wizard.tsx` - Wizard with stepper and step routing
- `packages/portal/components/template-gallery.tsx` - Card grid with preview dialog and deploy
- `packages/portal/components/wizard-steps/step-role.tsx` - Name + job title form
- `packages/portal/components/wizard-steps/step-persona.tsx` - Behavioral description textarea
- `packages/portal/components/wizard-steps/step-tools.tsx` - Badge chip tool multi-select
- `packages/portal/components/wizard-steps/step-channels.tsx` - Informational channel display
- `packages/portal/components/wizard-steps/step-escalation.tsx` - Dynamic escalation rule list
- `packages/portal/components/wizard-steps/step-review.tsx` - Summary + Deploy button
- `packages/portal/lib/system-prompt-builder.ts` - TypeScript mirror of Python build_system_prompt
- `packages/portal/lib/api.ts` - Template and TemplateDeployResponse types added
- `packages/portal/lib/queries.ts` - useTemplates, useDeployTemplate hooks added

## Decisions Made

- Wizard state held in React useState (not URL) — persona text in URL would be impractical and polluting; step position exposed via URL searchParam only
- Channels step is informational in v1 — agent routing is tenant-scoped, not per-agent; selected channel IDs are not persisted to a channel-agent join table
- Preview in template gallery uses Dialog (not inline collapsible) — cleaner UX for multi-field preview

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Fixed base-ui Select onValueChange null coercion**
- **Found during:** Task 1 (three-option entry screen)
- **Issue:** base-ui Select onValueChange signature is `(string | null) => void` per project decision, but setState setter expects `SetStateAction<string>` — TypeScript error
- **Fix:** Wrapped setter in arrow function: `(v) => setSelectedTenantId(v ?? "")`
- **Files modified:** `packages/portal/app/(dashboard)/agents/new/page.tsx`
- **Verification:** Build passes TypeScript check
- **Committed in:** 55873bb (Task 1 commit)

---

**Total deviations:** 1 auto-fixed (1 type error)
**Impact on plan:** Minimal — standard project pattern per STATE.md decisions. No scope creep.

## Issues Encountered

None beyond the auto-fixed TypeScript error above.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- All employee creation paths are live and building clean
- Template deploy and wizard both redirect to /agents/{id} for editing (EMPL-05 satisfied)
- Phase 5 is now complete — all 2 plans done

---
*Phase: 05-employee-design*
*Completed: 2026-03-25*

## Self-Check: PASSED

- All 8 key files verified present on disk
- Commits 55873bb and de23e9e verified in git log
