--- 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 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` — 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