docs(05-01): complete agent templates backend plan — system prompt builder, migration 007, template API

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.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.