Adolfo Delorenzo
b917f7c54c
- 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
158 lines
7.3 KiB
Markdown
158 lines
7.3 KiB
Markdown
---
|
|
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
|