diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index ba57610..1567eb7 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -59,9 +59,9 @@ Requirements for beta-ready release. Each maps to roadmap phases. ### Employee Design - [ ] **EMPL-01**: Multi-step wizard guides user through AI employee creation (role definition, persona, tools, channels, escalation rules) without requiring knowledge of system prompt format -- [ ] **EMPL-02**: Pre-built agent templates (e.g., Customer Support Rep, Sales Assistant, Office Manager) available for one-click deployment with sensible defaults -- [ ] **EMPL-03**: Template-deployed agents are immediately functional — respond in connected channels with the template's persona, tools, and escalation rules -- [ ] **EMPL-04**: Wizard and templates accessible to platform admins and customer admins (RBAC-enforced, not operators) +- [x] **EMPL-02**: Pre-built agent templates (e.g., Customer Support Rep, Sales Assistant, Office Manager) available for one-click deployment with sensible defaults +- [x] **EMPL-03**: Template-deployed agents are immediately functional — respond in connected channels with the template's persona, tools, and escalation rules +- [x] **EMPL-04**: Wizard and templates accessible to platform admins and customer admins (RBAC-enforced, not operators) - [ ] **EMPL-05**: Agents created via wizard or template appear in Agent Designer for further customization ## v2 Requirements @@ -144,9 +144,9 @@ Which phases cover which requirements. Updated during roadmap creation. | RBAC-05 | Phase 4 | Complete | | RBAC-06 | Phase 4 | Complete | | EMPL-01 | Phase 5 | Pending | -| EMPL-02 | Phase 5 | Pending | -| EMPL-03 | Phase 5 | Pending | -| EMPL-04 | Phase 5 | Pending | +| EMPL-02 | Phase 5 | Complete | +| EMPL-03 | Phase 5 | Complete | +| EMPL-04 | Phase 5 | Complete | | EMPL-05 | Phase 5 | Pending | **Coverage:** diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 98dbc3b..a0f9f6c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -121,7 +121,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 | 2. Agent Features | 6/6 | Complete | 2026-03-24 | | 3. Operator Experience | 5/5 | Complete | 2026-03-24 | | 4. RBAC | 3/3 | Complete | 2026-03-24 | -| 5. Employee Design | 0/3 | Not started | - | +| 5. Employee Design | 1/3 | In Progress| | --- diff --git a/.planning/STATE.md b/.planning/STATE.md index 8b11248..89a559e 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: completed -stopped_at: Phase 5 context gathered -last_updated: "2026-03-25T01:59:49.880Z" +stopped_at: Completed 05-01 agent templates backend +last_updated: "2026-03-25T02:33:33.764Z" last_activity: 2026-03-23 — Completed 03-02 onboarding wizard, Slack OAuth, BYO API keys progress: total_phases: 5 completed_phases: 4 - total_plans: 18 - completed_plans: 18 + total_plans: 21 + completed_plans: 19 percent: 100 --- @@ -70,6 +70,7 @@ Progress: [██████████] 100% | Phase 04-rbac P01 | 8min | 3 tasks | 14 files | | Phase 04-rbac P02 | 5min | 3 tasks | 10 files | | Phase 04-rbac P03 | 8min | 2 tasks | 7 files | +| Phase 05-employee-design P01 | 7min | 2 tasks | 9 files | ## Accumulated Context @@ -147,6 +148,9 @@ Recent decisions affecting current work: - [Phase 04-rbac]: base-ui Select onValueChange typed as (string | null) — filter state setters use ?? '' to coerce null - [Phase 04-rbac]: Operator test-message endpoint uses require_tenant_member not require_tenant_admin — locked decision: operators can QA agent behavior without CRUD access - [Phase 04-rbac]: Impersonation logs via raw SQL INSERT into audit_events — consistent with audit table immutability design (UPDATE/DELETE revoked at DB level) +- [Phase 05-employee-design]: AgentTemplate is global (not tenant-scoped) — templates readable by all authenticated users, no RLS; deploy creates independent Agent snapshot +- [Phase 05-employee-design]: build_system_prompt() always appends AI transparency clause — non-negotiable per Phase 1 architectural decision +- [Phase 05-employee-design]: Template GET endpoints use get_portal_caller (not require_tenant_member) — no tenant_id path param in global template routes ### Roadmap Evolution @@ -162,6 +166,6 @@ None — all phases complete. ## Session Continuity -Last session: 2026-03-25T01:59:49.877Z -Stopped at: Phase 5 context gathered -Resume file: .planning/phases/05-employee-design/05-CONTEXT.md +Last session: 2026-03-25T02:33:33.761Z +Stopped at: Completed 05-01 agent templates backend +Resume file: None diff --git a/.planning/phases/05-employee-design/05-01-SUMMARY.md b/.planning/phases/05-employee-design/05-01-SUMMARY.md new file mode 100644 index 0000000..039fe43 --- /dev/null +++ b/.planning/phases/05-employee-design/05-01-SUMMARY.md @@ -0,0 +1,94 @@ +--- +phase: 05-employee-design +plan: "01" +subsystem: backend-api +tags: [agent-templates, system-prompt, migration, rbac, tdd] +dependency_graph: + requires: [04-rbac] + provides: [template-gallery-api, system-prompt-builder] + affects: [packages/shared, packages/gateway, migrations] +tech_stack: + added: [] + patterns: + - AgentTemplate ORM model (global, non-tenant-scoped) + - build_system_prompt() functional builder with mandatory AI transparency clause + - Alembic migration with seed data via conn.execute() + CAST jsonb pattern +key_files: + created: + - packages/shared/shared/models/tenant.py (AgentTemplate class added) + - packages/shared/shared/prompts/__init__.py + - packages/shared/shared/prompts/system_prompt_builder.py + - migrations/versions/007_agent_templates.py + - packages/shared/shared/api/templates.py + - tests/unit/test_system_prompt_builder.py + - tests/integration/test_templates.py + modified: + - packages/shared/shared/api/__init__.py (export templates_router) + - packages/gateway/gateway/main.py (mount templates_router) +decisions: + - "AgentTemplate is NOT tenant-scoped — templates are global, readable by all authenticated users, no RLS needed" + - "Deploy creates an independent Agent snapshot — changes to template do not affect deployed agents" + - "GET /templates and GET /templates/{id} use get_portal_caller (not require_tenant_member) — no tenant_id path parameter available, any authenticated user can browse" + - "AI transparency clause always appended — non-negotiable per Phase 1 architectural decision" + - "Seed data uses conn.execute() with CAST(:col AS jsonb) pattern — consistent with Phase 2 asyncpg jsonb handling" +metrics: + duration: "7 minutes" + completed_date: "2026-03-25" + tasks_completed: 2 + files_created_or_modified: 9 +--- + +# Phase 5 Plan 01: Agent Templates — Backend Foundation Summary + +AgentTemplate ORM model, Alembic migration 007 with 7 seed templates, system prompt builder with mandatory AI transparency clause, template gallery API (list/detail/deploy), and comprehensive unit + integration test coverage. + +## Tasks Completed + +| # | Task | Commit | Files | +|---|------|--------|-------| +| 1 | AgentTemplate model, migration 007, system prompt builder, unit tests | d1acb29 | tenant.py, 007_agent_templates.py, prompts/system_prompt_builder.py, test_system_prompt_builder.py | +| 2 | Template API endpoints (list, detail, deploy) + RBAC + integration tests | f9ce3d6 | templates.py, __init__.py, main.py, test_templates.py | + +## What Was Built + +### AgentTemplate ORM Model (`packages/shared/shared/models/tenant.py`) + +Added `AgentTemplate` class with fields: id (UUID PK), name, role, description, category, persona, system_prompt, model_preference, tool_assignments (JSON), escalation_rules (JSON), is_active, sort_order, created_at. NOT tenant-scoped — no tenant_id, no RLS. + +### Migration 007 (`migrations/versions/007_agent_templates.py`) + +Creates `agent_templates` table and seeds 7 professional templates: +1. Customer Support Rep (support) — zendesk tools, sentiment/billing escalation +2. Sales Assistant (sales) — calendar_book, pricing negotiation escalation +3. Office Manager (operations) — calendar_book, HR complaint escalation +4. Project Coordinator (operations) — deadline missed escalation +5. Financial Manager (finance) — large transaction threshold escalation +6. Controller (finance) — budget exceeded escalation +7. Accountant (finance) — invoice discrepancy escalation + +### System Prompt Builder (`packages/shared/shared/prompts/system_prompt_builder.py`) + +`build_system_prompt(name, role, persona, tool_assignments, escalation_rules) -> str` assembles: identity header + optional tools section + optional escalation section + mandatory AI transparency clause. Empty/None tools and escalation rules omit their sections cleanly. + +### Template API (`packages/shared/shared/api/templates.py`) + +- `GET /api/portal/templates` — list active templates ordered by sort_order, any authenticated caller +- `GET /api/portal/templates/{id}` — template detail, 404 if inactive or missing +- `POST /api/portal/templates/{id}/deploy` — creates Agent snapshot for tenant, tenant_admin only (customer_operator gets 403) + +## Test Coverage + +- **17 unit tests** (`tests/unit/test_system_prompt_builder.py`): full prompt, minimal, empty sections, AI clause always present +- **11 integration tests** (`tests/integration/test_templates.py`): list 7+ templates, field verification, single template detail, deploy creates snapshot, platform_admin deploy, operator 403, not-found 404, two deploys create independent agents + +## Deviations from Plan + +None — plan executed exactly as written. + +Pre-existing test failures noted (not caused by this plan): +- `tests/integration/test_invite_flow.py` — Celery/Redis not available at localhost:6379 in dev env +- `tests/integration/test_portal_rbac.py` — RLS policy violation in `_create_agent` fixture (no SET LOCAL before INSERT) + +## Self-Check: PASSED + +All 8 expected files present. Both task commits verified (d1acb29, f9ce3d6). Unit tests (17) and integration tests (11) pass.