konstruct/.planning/phases/05-employee-design/05-01-SUMMARY.md

phase, plan, subsystem, tags, dependency_graph, tech_stack, key_files, decisions, metrics

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics
05-employee-design	01	backend-api	agent-templates system-prompt migration rbac tdd	requires provides affects 04-rbac template-gallery-api system-prompt-builder packages/shared packages/gateway migrations	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	created modified 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 packages/shared/shared/api/__init__.py (export templates_router) packages/gateway/gateway/main.py (mount templates_router)	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	duration completed_date tasks_completed files_created_or_modified 7 minutes 2026-03-25 2 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.