From 6a9516ed8bd84358b5d3b410626260257e4dbbcb Mon Sep 17 00:00:00 2001 From: Adolfo Delorenzo Date: Tue, 24 Mar 2026 19:59:49 -0600 Subject: [PATCH] docs(05): capture phase context --- .../phases/05-employee-design/05-CONTEXT.md | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 .planning/phases/05-employee-design/05-CONTEXT.md diff --git a/.planning/phases/05-employee-design/05-CONTEXT.md b/.planning/phases/05-employee-design/05-CONTEXT.md new file mode 100644 index 0000000..367ff9e --- /dev/null +++ b/.planning/phases/05-employee-design/05-CONTEXT.md @@ -0,0 +1,111 @@ +# Phase 5: Employee Design - Context + +**Gathered:** 2026-03-24 +**Status:** Ready for planning + + +## 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. + + + + +## 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 + + + + +## 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 + + + + +## 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 + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 05-employee-design* +*Context gathered: 2026-03-24*