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