docs(05-02): complete employee creation UI frontend plan
- Three-option entry screen, template gallery, 5-step wizard, advanced mode - SUMMARY.md created with task commits, deviations, decisions - STATE.md updated with decisions, metrics, session - ROADMAP.md updated with phase 5 plan progress - Requirements EMPL-01, EMPL-05 marked complete
This commit is contained in:
157
.planning/phases/05-employee-design/05-02-SUMMARY.md
Normal file
157
.planning/phases/05-employee-design/05-02-SUMMARY.md
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user