UpSquad -- Complete Product Requirements Document (PRD)

AI Workforce Platform | Version 1.9

Authors: Vaisakh, Ashik Date: 2026-04-16 Status: Restructured 2026-04-16 — see PRD Registry. Detailed component specs now live in sub-PRD issues; this document retains historical context + master-level narrative.

SUB-PRDs

This document is the markdown mirror of the Master PRD (GitHub issue #1). Detailed component-level requirements live in their own sub-PRDs. See PRD_REGISTRY.md for the canonical index.

Delivered sub-PRDs: Context Engine (#2), Client Portal MVP (#79), Agent Runtime Core (#93), BYOA & AI Governance (#231), SCM Credentials (#348), Agent Runtime Optimisation (#380), Onboarding APIs (#425).

Draft sub-PRDs (2026-04-16 restructure):

Org Model v2.3 (#549) — flexible hierarchy, RBAC, cascading guardrails, SCIM import
Agent Lifecycle & Upgrade (#550) — formerly P8
Workspace Persistence (#551) — formerly P10
Pricing & Packaging (#552) — formerly sections 33 + 34
Dashboard Intelligence (#553) — formerly P6.3
Competency Catalogue (#554) — formerly Appendix C

Note on embedded content: Sections below still contain the historical detailed requirements. These are preserved for context but are now superseded by the relevant sub-PRD — edits should go to the sub-PRD issue, not here. When a sub-PRD evolves, this document is updated with a brief summary + link, not re-written in full.

CHANGELOG

Version 1.9 -- 2026-04-16 -- MAJOR RESTRUCTURE

Triggered by: Consolidation of duplicate master-like PRDs (this document + PRD #1) into a single Master PRD + component sub-PRDs hierarchy. The goal: every requirement lives in exactly one owning PRD, with clear version and status.

Changes:

Renamed PRD #1 to "Master PRD: UpsQuad — AI Workforce Platform" (version 2.3). Master PRD now contains only master-level content (vision, goals, architecture overview, NFRs, sub-PRD registry, release milestones).
Extracted six component PRDs from prior PRD #1 scope-creep:
- Org Model v2.3 (#549) — NEW detailed requirements: flexible OrgUnits, RBAC, 4-level cascade, conflict resolution, SCIM 2.0, inline edit UX
- Agent Lifecycle & Upgrade (#550) — formerly P8
- Workspace Persistence (#551) — formerly P10
- Pricing & Packaging (#552) — formerly Pricing Model + Tier Feature Mapping sections
- Dashboard Intelligence & Copilot UX (#553) — formerly P6.3
- Competency Catalogue (#554) — formerly Appendix C
P11 BYOA content deduped — owned by PRD #231.
Added canonical PRD_REGISTRY.md as the single source of truth for which PRD owns which scope at which version.
Added SUB-PRDs section near the top of this document linking to all child PRDs.
This document (v1.9) retains the historical priority sections (P0–P9, cross-cutting concerns, appendices) as archive. Future edits should go to the owning sub-PRD, not here.

Version 1.8 -- 2026-04-15

Triggered by: Delivery of PRD #380 "Agent Runtime Optimisation & Security Hardening" (8 items across 5 waves). Captures the new P4.8 section + cumulative delivery status + security moat enumeration.

Changes:

Added new section P4.8 Agent Runtime Optimisation & Security Hardening covering 8 items shipped across Waves 1–5.
Added P4.8.1 Agent-to-agent delegation primitive (Wave 3, DELIVERED). Runtime delegate_to_agent tool; role-based target selection; child sessions inherit clamped clearance; per-session cycle detection; fan-out/depth quotas.
Added P4.8.2 Sub-agent session propagation (Wave 3, DELIVERED). Parent-child session state + subagent_invocations bridge with dual-hash anchors; RTD/retention quotas; cascade termination DFS-post-order; compliance sweeper.
Added P4.8.3 Approval Chain Engine (Wave 2, DELIVERED). Policy-driven approval routing with 10s scheduler tick; first-write-wins CAS; advisory-lock singleton; 4-channel dispatch (dashboard + email shipped, Slack + SCM deferred to 2.1).
Added P4.8.4 Pause/Resume API (Wave 2, DELIVERED). Message-boundary pause; system-role operator input injection; keepalive during operator pause; rendezvous-and-deliver on resume.
Added P4.8.5 Named Hook Points SDK (Wave 4A, DELIVERED). 4 named points (on_session_start / pre_llm_call / post_tool_call / on_error); strict-disjoint annotations; 3-panic auto-disable per session; Python→Go gRPC bridge with <3ms p95 RTT.
Added P4.8.6 Agent Isolation (Wave 1, DELIVERED). Tool parameter schema validation; per-tenant egress allow-list with private-IP block; JWT replay protection via jti cache; audit log hash-chaining with epoch semantics.
Added P4.8.7 Enterprise Compliance (Wave 4B, DELIVERED). Data-class registry (55 scopes) + CI coverage lint; RTD engine 4-phase state machine with strict dual-control + 72h window; retention policy with clamp model; SIEM export (OCSF v1.2, HMAC, at-least-once + idempotency, circuit breaker); SBOM generation (CycloneDX + SPDX) via Syft.
Added P4.8.8 ML-Layer Detection (Wave 5, DELIVERED). Jailbreak classifier (Python sidecar, Prompt-Guard-86M, shadow→warn→enforce rollout); OpenAI Moderation with 13 categories + 3 pipeline surfaces + circuit breaker; tool execution sandboxing (AppArmor + seccomp deny-list).
Updated P4.2 to mark P4.2.12–P4.2.19 as DELIVERED (SCM credentials work originally captured in v1.7; see item 17 below).
Added delivery ledger to the P4.8 section: 24 LLDs, 301 pen-test scenarios passing under -race, 71 milestone-9 issues closed.
Added process gates note: shelfware gate introduced after Wave 3 retro (0 shelfware incidents in Waves 4–5 vs 6 in Waves 1–3); proto-sync CI gate prevents missing-generated-file regressions.
Updated summary counts to reflect P4.2 + P4.8 additions across v1.7 + v1.8: Grand total MVP ~314 → ~329 (+15: 7 from P4.2 + 8 from P4.8), V1.1 ~145 → ~146 (+1 deferred — P4.2.19 GitLab), Total ~483 → ~499.

Version 1.7 -- 2026-04-13 (delivered; PRD doc update retroactive)

Triggered by: Gap analysis of SCM credential management in agent runtime. Tenant users need to provide their own SCM credentials (PAT or user-owned GitHub App) for agent tool use.

Changes:

Added P4.2.12 SCM credential vault — per-member storage with encrypted payload; pat and github_app credential types.
Added P4.2.13 PAT credential mode with expiry tracking + GitHub /user validation on save.
Added P4.2.14 GitHub App credential mode with on-demand ~1hr installation tokens.
Added P4.2.15 Credential resolution chain: member → team → org fallback.
Added P4.2.16 Credential health monitor with expiry alerts + 401 auto-revocation.
Added P4.2.17 Client portal credential management page (reference impl delivered; portal integration tracked in client repo).
Added P4.2.18 Credential access audit logging via Wave 1 audit chain.
Added P4.2.19 GitLab SCM credential support (V1.1 — PAT mode only).
Added functional requirements 101–103 (SCM credential modes, resolution chain, expiry detection).
All items DELIVERED via PRs #362–#368 (2026-04-13).

Version 1.6 -- 2026-04-06

Triggered by: Product refinement -- agent team adoption should be optional not mandatory, HRIS import user story, offboarding SOP user story, copilot-to-copilot collaboration moved to v1, and removal of ownership divisions from PRD.

Changes:

Updated Goals & Success Metrics (section 4): Changed "Agent team adoption" goal language from mandatory ("Engineering leaders deploy at least one agent team") to optional/available ("Eligible users have the option to deploy agent teams and are aware of the capability"). Target updated to reflect awareness rather than forced adoption.
Added US-12: Org Admin Imports Org Chart from HR Systems -- new user story for importing org hierarchy from HRIS providers (Workday, BambooHR, etc.) with preview, conflict resolution, ongoing automated sync, and audit logging.
Added US-13: Manager and Employee Offboarding (Resignation SOP) -- new user story covering the offboarding workflow for departing employees and managers, including access revocation, copilot deprovisioning, reporting line reassignment, agent team ownership transfer, and HRIS-triggered automated offboarding.
Moved Copilot-to-copilot collaboration from Out of Scope (v2) to In Scope (v1). Cross-user personal copilot communication is now a v1 capability with appropriate permission and privacy controls.
Added HRIS import/sync and offboarding SOP to In Scope (v1) list.
Removed all ownership division labels (V/A/Both) from every item table throughout the entire PRD. Ownership assignments are an operational concern, not a product requirement. Removed the "Founder Work Assignment Model" section entirely. Removed the "Owner" column from all ~67 tables (~520 row-level owner annotations removed).
Renumbered all sections from 13 onward (former section 13 "Founder Work Assignment Model" removed; former sections 14-38 are now 13-37).
Updated Table of Contents to reflect removed section and renumbering.
Version bumped from 1.5 to 1.6.

Version 1.5 -- 2026-04-05

Triggered by: Sync of 3 missing sections from GitHub issue #1 PRD that were not carried over in previous merges: Pricing Rationale, Pricing Tier Feature Mapping, and Competency Catalogue Appendix.

Changes:

Added Pricing Rationale subsection under Pricing Model (section 34) -- competitive positioning paragraph explaining $29/seat benchmarking, hourly pricing rationale, and Free tier PLG funnel strategy.
Added Pricing Tier Feature Mapping section (now section 35) -- detailed 27-row feature-by-tier matrix covering Free/Pro/Enterprise feature gating for org hierarchy limits, copilot seats, agent teams, competency profiles, delegated enablement, SSO, audit log, integration marketplace, approval workflows, SLA tiers, support tiers, and more.
Added Appendix C: Competency Catalogue (Default v1) -- full reference table defining all 12 default competency profiles (swe, em, sre, qa, pm, mktg, sales, hr, design, data, exec, general) with designation patterns, seniority modifier effects, and descriptions. Referenced by FR-20 through FR-27.
Updated Table of Contents with new sections (Pricing Tier Feature Mapping as section 35, renumbered subsequent sections, added Appendix C).
Version bumped from 1.4 to 1.5.

Version 1.4 -- 2026-04-03

Triggered by: MCP security hardening and defense-in-depth requirements for agent tool infrastructure. Adds transport-layer guardrail enforcement, context-aware MCP sandboxing, centralized MCP security gateway, and declarative output validation.

Changes:

Added P2.4.16: Context-mode MCP sandboxing -- agent runtime dynamically loads/unloads MCP server definitions based on current task step, reducing idle tool context consumption. Configurable per agent role. [BOOTSTRAP]
Added P2.4.17: MCP security gateway -- centralized gateway for all agent-to-MCP-server communication, enforcing authentication, authorization, rate limiting, payload inspection, and emergency tool revocation. [BOOTSTRAP]
Added P3.3.12: Runtime guardrail enforcement at MCP transport layer -- policy enforcement point for all tool calls and results, evaluating guardrail rules (P3.3.7) against actual tool invocation parameters. Defense-in-depth independent of LLM compliance. [BOOTSTRAP]
Added SEC.1.7: Declarative output validation specification -- structured schema language for agent output validation rules with field-level validators, corrective actions, severity levels, and tenant-customizable rules.
Updated Appendix B: Gap Coverage Matrix with 4 new entries
Updated summary counts: Grand total MVP ~311 to ~314, V1.1 ~144 to ~145, Total ~479 to ~483

Version 1.3 -- 2026-04-05

Triggered by: Merge of GitHub issue #1 PRD content (Org Hierarchy, User Enablement, Personal Copilots & Agent Teams) and technology bias removal across entire document.

Changes:

Added new section: Problem Statement (from issue #1 PRD)
Added new section: Two-Mode Product Model -- Personal Copilots and Agent Teams (from issue #1 PRD)
Added new section: Goals & Success Metrics with measurable targets (from issue #1 PRD)
Added new section: User Stories (US-1 through US-11) with full acceptance criteria (from issue #1 PRD)
Added new section: Functional Requirements -- 82 numbered requirements covering Human Employee Registry, Org Hierarchy, User Enablement, Personal Copilot Assignment, Copilot Personalisation, Agent Teams, Approval Workflows, Chat Interface, Integration Marketplace, Auth, Platform Owner Console, Billing, and Advanced Analytics (from issue #1 PRD)
Added new section: Non-Functional Requirements table (from issue #1 PRD)
Added new section: Scope (In Scope / Out of Scope with rationale) (from issue #1 PRD)
Added new section: Dependencies table (from issue #1 PRD)
Added new section: Edge Cases & Failure Modes table (from issue #1 PRD)
Added new section: Decisions (Resolved from Open Questions) -- 7 resolved decisions (from issue #1 PRD)
Updated Pricing Model section with dual billing model and Free/Pro/Enterprise tier table (from issue #1 PRD)
Removed technology-specific references throughout the entire document -- replaced all mentions of specific programming languages, frameworks, databases, cloud providers, infrastructure tools, and implementation details with technology-agnostic requirement descriptions. The PRD now describes WHAT the system must do, not HOW. Technology decisions belong in Architecture Decision Records (ADRs) and High-Level Design (HLD) documents.
Version bumped to 1.3

Version 1.2 -- 2026-04-04

Triggered by: Founder requirement -- Stateless Agent Runtime with External Context, Memory, Immutable Sessions, Hierarchical Context Editing, and Per-Agent Metering

Changes:

Added P0.3.11: ADR -- Stateless Agent Runtime (all agent state externalized, no local persistence)
Added P0.3.12: ADR -- Immutable Session Runtime (frozen config snapshot per session, explicit refresh only)
Added P2.1.15: Stateless agent contract enforcement (read-only FS, no writable volumes, liveness validation)
Added P2.1.16: Agent session initialization protocol (5-step fetch, validate, immutable snapshot)
Added P2.1.17: Per-action authorization check (RBAC verification before every agent action, blacklist model)
Added P2.1.18: Agent metrics interface (standard metrics endpoint)
Added P2.1.19: Billable metrics per agent (LLM tokens, tool invocations, API calls, compute time, storage)
Added P2.1.20: Performance metrics per agent (latency, completion time, error/success rate)
Added P2.1.21: Metrics attribution dimensions (tenant_id, agent_id, session_id, action_type)
Added P3.1.11: Context refresh mechanism (poll for latest, create new immutable snapshot)
Added P3.1.12: Context push operation (/push-context -- save session knowledge to external DB)
Added P3.1.13: Context pull operation (/pull-context -- fetch latest context, new immutable snapshot)
Added P3.1.14: Context push/pull authorization model
Added P3.3.6: Blacklist-based action model (default allow, guardrails define prohibitions)
Added P3.3.7: Guardrail definition format (structured rules: scope, condition, prohibition, violation response)
Added P3.3.8: Self-context immutability (agents cannot modify own role definition, guardrails, or system prompt)
Added P3.3.9: Hierarchical context editing (only parent agent or human can edit an agent's scope -- downward only)
Added P3.3.10: Agent hierarchy definition (tree: Human, PM, Architect, SMEs/QA/DevOps, configurable per tenant)
Added P3.3.11: Chain of trust enforcement (no self-edits, no lateral edits, no upward edits, full audit trail)
Added P6.1.10: Slash commands /push-context and /pull-context with version confirmation
Modified P2.2.5: "hot-reloadable" changed to "applied on next session start per immutable session runtime policy"
Modified P2.3.2: "tool whitelist" changed to "tool access list"; distinguished from action guardrails
Modified P4.6.5: Running sessions stay frozen; new sessions get updated config; critical-update signal triggers graceful restart
Updated Appendix B: Gap Coverage Matrix with 21 new entries
Updated summary counts: Grand total MVP ~290 to ~311, Total ~458 to ~479

Version 1.1 (2026-04-03)

Trigger: Customer inquiry -- overseas recruitment company with 5 non-technical staff. Revealed that the entire platform assumed engineering/software teams as the only customer. Platform must be industry-agnostic from day one.

Changes:

P2.3 Agent Type System -- Replaced hardcoded engineering types with a dynamic Role Builder. Agent types are now templates; any agent can assume any role defined by the tenant. Added Industry Template Library (IND section) with pre-built role packs for recruitment, sales, legal, marketing, finance, HR, customer support, and more.
P2.4 Tool Registry & MCP -- Added industry-agnostic tool packs: email, calendar, CRM, job boards, document generation, spreadsheet, communication, and generic HTTP/webhook tools.
P4.1 Workflow Engine -- Decoupled from SCM. Workflows can now use web dashboard, email, Slack, or SCM as their substrate. SCM is one option, not the default.
P4.2 SCM Integration -- Made optional. Renamed to "External Integration Adapters." Added non-SCM adapters: email, Slack, web portal.
P4.3 Approval Chain Engine -- Approvals no longer require SCM. Added multi-channel approval: web dashboard, email link, Slack button, mobile push.
P4.4 Change Guard -- Generalized from code-specific to domain-agnostic conflict detection.
P6.3 Onboarding Flow -- Replaced tech-specific questionnaire with industry-aware onboarding. System detects industry, suggests agent team templates, and provisions with zero technical knowledge required.
P3.5 RAG Knowledge Bases -- Generalized from engineering-specific to domain-agnostic knowledge bases. Added tenant-uploaded knowledge base support.
P7.1 Cost Engine -- Generalized per-agent pricing from engineering-specific to domain-agnostic metrics.
New Section: IND (Industry Template Library) -- Pre-built agent team templates for 8+ industries with role definitions, tool mappings, workflow templates, and onboarding guides.
Appendix A -- Updated MVP definition to be industry-agnostic.
Appendix B -- Added new gap coverage entries for industry-agnostic items.
Executive Summary -- Updated to reflect industry-agnostic positioning.
DOC.2 User Documentation -- Added industry-specific getting started guides.

Executive Summary
Problem Statement
Two-Mode Product Model
Goals & Success Metrics
User Stories
Functional Requirements
Non-Functional Requirements
Scope
Dependencies
Edge Cases & Failure Modes
Decisions (Resolved from Open Questions)
Platform Architecture Overview
Priority 0 -- Pre-Development (Legal, Compliance, Design)
Priority 1 -- Foundation
Priority 2 -- Agent Runtime
Priority 3 -- Context & Memory
Priority 4 -- Workflow & Governance
Priority 5 -- Agent Collaboration
Priority 6 -- User Experience
Priority 7 -- Cost & Measurement
Priority 8 -- Intelligence & Optimization
Priority 9 -- Business & Monetization
Cross-Cutting Concern: Platform Console
Cross-Cutting Concern: Security Hardening
Cross-Cutting Concern: Notification System
Cross-Cutting Concern: Testing Infrastructure
Cross-Cutting Concern: Documentation
Cross-Cutting Concern: Error Handling & Resilience
Cross-Cutting Concern: Disaster Recovery
Cross-Cutting Concern: Data Export & Portability
Cross-Cutting Concern: Customer-Facing Operations
Industry Template Library (IND)
Pricing Model
Pricing Tier Feature Mapping
Appendix A: Release Classification Definitions
Appendix B: Gap Coverage Matrix
Appendix C: Competency Catalogue (Default v1)

1. EXECUTIVE SUMMARY

UpSquad is a multi-tenant SaaS/PaaS platform that replaces traditional human teams with governed AI agent teams across any industry. Each organization deploys AI agents structured like a real company -- departments, sub-teams, and specialist roles -- all under human supervision with full audit trails. Whether it's an engineering firm, recruitment agency, law practice, marketing team, or finance department, UpSquad provides industry-specific agent templates while allowing fully custom role definitions.

UpsQuad provides two distinct modes of AI assistance: Personal Copilots (1:1 AI assistants matched to each employee's role) and Agent Teams (autonomous or supervised multi-agent teams that perform organisational work). Both modes coexist within the same platform, share the org hierarchy, and are governed by the same clearance and audit systems.

This PRD encompasses all 9 existing implementation priorities, fills 18 identified critical gaps, adds a Priority 0 for pre-development work, introduces the Platform Console as a cross-cutting concern, defines the Industry Template Library for out-of-the-box support across multiple verticals, establishes stateless agent runtime, immutable session, and hierarchical context editing as foundational architectural constraints, and defines the org hierarchy, user enablement, and dual-mode product model.

Release classifications:

MVP -- Must ship for first paying customer. No revenue without this.
V1.1 -- Ship within 4-8 weeks of MVP. Required for enterprise credibility.
V2 -- Ship within 3-6 months post-MVP. Competitive differentiation and scale.

Authors: Vaisakh, Ashik

2. PROBLEM STATEMENT

Organisations adopting UpsQuad need a structured way to onboard their company, define their organisational hierarchy, selectively enable the platform for employees, and have each enabled employee receive an AI copilot agent whose competency matches the employee's role/designation. Beyond personal copilots, organisations also need the ability to deploy Agent Teams -- one or more AI agents that operate as headless team members, performing work autonomously or under human oversight, mirroring the structure of real engineering and cross-functional teams.

Today there is no mechanism for an org admin to model their company structure, control who gets access, ensure the AI copilot assigned to an employee is contextually relevant to that person's job function, or deploy governed agent teams with appropriate approval gates.

Additionally, UpsQuad as a platform needs a Platform Owner Console -- a super-admin view that provides visibility into all onboarded organisations, their usage, and their expenses. Without this, the UpsQuad team cannot manage operations, billing, or support effectively.

Who it solves for:

Org Admins who need to onboard their company, control platform rollout, and approve agent team deployments.
Engineering Leaders (and equivalent senior roles) who need to deploy agent teams to augment or replace team capacity.
Team Leads / Managers who need to enable the platform for their direct reports.
Individual Contributors who need an AI copilot that understands their role and helps with role-specific tasks.
Single-person companies who need a full agent team (including an agent acting as engineering leader) to build out their product.
UpsQuad Platform Owners who need operational visibility across all tenants for billing, support, and business intelligence.

3. TWO-MODE PRODUCT MODEL

UpsQuad provides two distinct but complementary modes of AI assistance:

Mode 1: Personal Copilot

Every enabled user in an organisation receives a Personal Copilot -- a one-to-one AI assistant whose competency is matched to the user's designation and seniority level. Personal copilots help users with role-specific tasks (e.g., an SWE copilot helps with code, an EM copilot helps with sprint planning).

Eligibility: Every enabled user.
Provisioning: Automatic on enablement (see US-4).
Billing: Seat-based (per user per month).

Mode 2: Agent Team

Users on the engineering leadership ladder (Engineering Manager, Tech Lead, Director of Engineering, VP Engineering, CTO, or equivalent) OR org admins have the option to deploy an Agent Team. An agent team is a group of one or more AI agents that operate as headless team members within the organisation.

Eligibility: Users with engineering leadership designations OR org admin role.
Composition: A single agent or a multi-agent team. May or may not be autonomous (configurable autonomy level).
Approval required: Agent team deployments MUST be approved by (1) the deploying user's skip-level manager AND (2) the org admin before going live. For org admins deploying their own teams, only a confirmation step is required (no skip-level needed since they are the top authority).
Single-person company use case: A single-person company where the sole user is both org admin and engineering leader can deploy a full agent team -- including an agent designated as an engineering leader. In this case, the org admin self-approves the deployment.
Billing: Hourly pricing (agents accrue cost by the hour they are active/running).

Agent Team Agents as Headless Users

Agents in an agent team are registered as headless users in the org hierarchy:

Each agent has a name, designation/title, department, clearance level, and reports-to relationship -- just like a human employee.
Agents appear in the org chart but are visually distinguished as AI agents (e.g., a badge, icon, or label indicating "AI Agent" vs "Human").
Agents have specific clearance levels assigned that govern what data, systems, and actions they can access. Clearance levels are assigned by the deploying user and approved as part of the deployment approval flow.
Headless agent users do NOT consume a seat for personal copilot billing -- they are billed under the agent team hourly model.

4. GOALS & SUCCESS METRICS

Goal	Metric	Target
Seamless org onboarding	Time from admin signup to first copilot interaction	< 15 minutes
Flexible hierarchy modelling	Support org structures from 1 person to 10,000+ employees	100% of common structures supported
Controlled rollout	Admins and managers can selectively enable users	Granular: per-user and bulk enablement
Role-accurate copilot assignment	Copilot competency matches employee designation	100% automatic match on enablement
Delegated enablement	Managers can enable their reportees without admin intervention	Delegation adoption rate > 60% within 90 days
Platform stickiness	Enabled users return to the copilot daily	DAU/MAU ratio > 40% after 30 days
Agent team availability & adoption	Eligible users have the option to deploy agent teams and are aware of the capability	> 30% awareness among eligible users within 90 days; adoption is optional
Agent team governance	All agent team deployments go through approval flow	100% compliance
Platform operational visibility	Platform owners can view all orgs and expenses in real time	100% of tenants visible within 1 minute of onboarding
Dual billing accuracy	Personal copilot and agent team costs are tracked and billed separately	100% attribution accuracy

5. USER STORIES

US-1: Org Admin Defines Org Hierarchy

As an org admin, I want to define my company's organisational hierarchy (from CEO down to individual contributors), so that the platform understands my company's reporting structure and departments.

Acceptance Criteria:

Admin can create an org chart as a tree with reporting-line (reports-to) relationships and arbitrary depth (single person, single team, or full corporate hierarchy).
Each node in the hierarchy represents either a human employee or a headless agent user.
Human employee nodes store: name, email, job title, designation, department, seniority level (Junior, Mid, Senior, Staff, Principal, or equivalent), manager relationship (parent node), and optional external_id for HRIS sync.
Headless agent nodes store: agent name, designation/title, department, clearance level, manager relationship, and a flag indicating the node is an AI agent.
Admin can assign departments to teams/verticals (e.g., SRE, Marketing, Dev, Platform, QA). Departments are a taxonomy applied to each node.
The hierarchy supports reporting-line relationships: each node has exactly one parent (except the root).
Admin can add, edit, remove, and re-organise nodes after initial creation.
The hierarchy is visually rendered as an org chart, with human employees and AI agents visually distinguished.
Hierarchy data is scoped to the tenant -- no cross-tenant visibility.

US-2: Org Admin Enables Platform for Specific Users

As an org admin, I want to selectively enable the UpsQuad platform for specific employees or for everyone in the org, so that I can control the rollout pace and cost.

Acceptance Criteria:

Admin can enable the platform for individual users by selecting them from the org hierarchy.
Admin can enable the platform for all users in the org with a single action.
Admin can disable (revoke) platform access for any user at any time.
Enabling a user triggers provisioning of their personal copilot agent (see US-4).
The admin dashboard shows a clear count and list of enabled vs. not-enabled users.
Billing reflects only enabled users for seat-based charges (personal copilots).

US-3: Manager Enables Platform for Reportees (Delegated Enablement)

As a manager with platform access, I want to enable the platform for my direct reports, so that they can start using their copilot without waiting for the org admin.

Acceptance Criteria:

A manager can only enable users who are their direct reports in the org hierarchy.
A manager cannot enable users outside their reporting line.
The enablement follows the same flow as admin enablement (copilot provisioning, access grant).
The org admin retains an audit log and override capability for all delegated enablements.
The org admin can disable delegated enablement as a policy setting.
Delegation follows the hierarchy recursively: a manager's reportee who is also a manager can further delegate enablement to their own reports, provided the org-level delegation policy is enabled.

US-4: Enabled User Gets a Personal Copilot Agent

As an enabled user, I want to be automatically assigned a personal AI copilot agent whose competency matches my job designation, so that the copilot can help me with tasks relevant to my role.

Acceptance Criteria:

Upon enablement, the system automatically determines the user's competency from their designation and department.
A copilot agent is provisioned with the matching competency profile (e.g., Engineering Manager, Software Engineer, Marketing Specialist, SRE).
The competency profile governs the copilot's behaviour: what it knows, how it responds, what tools/integrations it can access.
If a user's designation changes, the copilot competency is updated accordingly.
The platform ships with a default competency catalogue covering common roles. Org admins can also create custom competency profiles for roles not covered by defaults.
Seniority (Junior, Mid, Senior, Staff, Principal) is treated as a modifier on the base competency profile, not a separate competency. The copilot adapts its depth of guidance and assumed context based on seniority level.
The copilot personalises its responses over time based on the user's interaction history, preferences, and working patterns.

US-5: Enabled User Interacts with Copilot via Chat Interface

As an enabled user, I want to log in and immediately see a chat prompt where I can give tasks to my copilot, so that I can start getting value from the platform instantly.

Acceptance Criteria:

The landing page after login shows a centred chat prompt ready for input.
A sidebar provides navigation: org chart view, settings, activity history, agent team management (if eligible).
The copilot responds with role-appropriate context (e.g., an EM copilot understands sprint planning, team management; an SWE copilot understands code, tickets).
Conversation history is persisted per user per session and across sessions.
The copilot identifies itself and its competency to the user on first interaction.
The copilot supports multiple languages for interaction (multi-language support).

US-6: Org Admin Views Platform Adoption Dashboard

As an org admin, I want to see a dashboard showing which users are enabled, active, and how they are using the platform, so that I can measure ROI and decide on further rollout.

Acceptance Criteria:

Dashboard shows: total employees in org, enabled users, active users (last 7/30 days).
Dashboard shows per-department breakdown.
Dashboard shows copilot interaction counts (aggregate, not content) per user.
Dashboard shows agent team status: deployed teams, active agents, agent-hours consumed.
Dashboard shows separate billing views for personal copilots (seat-based) and agent teams (hourly).
Dashboard includes copilot effectiveness scoring: task completion rates, user satisfaction signals.
Data is scoped to the admin's tenant only.

US-7: Platform Owner Views All Onboarded Organisations

As a UpsQuad platform owner, I want to see a console listing all onboarded organisations with key health metrics, so that I can manage platform operations and support effectively.

Acceptance Criteria:

The Platform Owner Console is a separate, dedicated interface accessible only to users with the platform_owner role.
The console displays a searchable, sortable table of all onboarded organisations.
For each organisation, the console shows: org name, onboarding date, plan/tier, total employees in hierarchy, enabled (seat) count, active users (last 7/30 days), agent teams deployed, agent-hours consumed, and current billing status.
The console supports filtering by: plan tier, onboarding date range, active/inactive status.
The console provides a drill-down view into any organisation's summary (not individual user data -- respects tenant privacy).
The console is completely isolated from tenant-facing interfaces -- org admins never see it.

US-8: Platform Owner Views Organisation Expenses (Dual Billing Streams)

As a UpsQuad platform owner, I want to see the expense breakdown for each onboarded organisation across both billing streams (personal copilots and agent teams), so that I can track revenue, monitor LLM costs, and identify accounts that may need attention.

Acceptance Criteria:

The expense view shows per-organisation: personal copilot revenue (seat-based), agent team revenue (hourly), total revenue, total LLM token cost, gross margin, and month-over-month trend.
The console shows an aggregate expense summary across all organisations: total platform revenue (broken down by copilot seats and agent-hours), total LLM cost, total gross margin.
Expenses are broken down by month with the ability to select custom date ranges.
The console highlights cost anomalies: organisations where LLM cost exceeds a configurable threshold percentage of revenue.
The console shows per-organisation seat utilisation: enabled seats vs. active seats (to identify underutilised accounts for customer success outreach).
The console shows per-organisation agent team utilisation: agent-hours consumed vs. allocated.
Export capability: platform owners can export expense data as CSV.

US-9: Engineering Leader Deploys an Agent Team

As an engineering leader (or org admin), I want to deploy an agent team to augment my team's capacity, so that I can scale output without hiring additional headcount.

Acceptance Criteria:

Users with engineering leadership designations or org admin role see an "Agent Teams" section in their dashboard.
The user can create a new agent team, specifying: team name, team purpose, number of agents, each agent's designation/role, clearance level, and autonomy level (fully autonomous, semi-autonomous with checkpoints, or fully supervised with approval gates).
Agent team deployment triggers an approval workflow: the deploying user's skip-level manager AND the org admin must both approve before the team goes live.
For org admins deploying their own teams (or single-person companies), only a confirmation step is required.
Once approved, agent team agents are registered as headless users in the org hierarchy.
Agent teams accrue cost by the hour they are active. The deploying user can set a monthly budget cap.
Agent teams can be paused, resumed, or decommissioned at any time by the deploying user or org admin.

US-10: Agent Team Operates with Configurable Autonomy

As an engineering leader, I want to configure the autonomy level of my agent team, so that I can balance speed with oversight based on the task criticality.

Acceptance Criteria:

Each agent team has a configurable autonomy level: fully autonomous, semi-autonomous (checkpoints at defined stages), or fully supervised (human approval required before each action).
Approval gates can be configured per action type (e.g., code commits require approval, documentation does not).
All agent actions are recorded on the organisation's existing source control platform as an audit trail.
The deploying user receives notifications at each checkpoint or approval gate.
Autonomy level can be changed after deployment without redeploying the team.

US-12: Org Admin Imports Org Chart from HR Systems

As an org admin, I want to import my company's organisational chart directly from our HR system (e.g., Workday, BambooHR, or other HRIS), so that I do not have to manually recreate the org hierarchy and can keep it automatically synchronised.

Acceptance Criteria:

Admin can connect to supported HR systems (Workday, BambooHR, and other major HRIS providers) via OAuth or API key authentication.
The import maps HRIS fields to UpsQuad hierarchy fields: employee name, email, job title, designation, department, seniority level, and reporting relationship.
Admin can preview the imported org chart before confirming the import.
The import handles conflicts gracefully: if an employee already exists in UpsQuad (matched by email or external_id), the system offers merge, skip, or overwrite options.
After initial import, the system supports ongoing automated sync from the HRIS at a configurable interval (e.g., daily, weekly) to keep the org hierarchy up to date.
Changes detected during sync (new hires, departures, title changes, reporting line changes) are applied automatically or queued for admin review, based on a configurable policy.
The system maintains an audit log of all HRIS sync operations (imports, updates, deletions).
Import and sync operations are scoped to the tenant -- no cross-tenant data leakage.
If the HRIS connection fails or credentials expire, the system notifies the admin and gracefully falls back to manual management until reconnected.

US-13: Manager and Employee Offboarding (Resignation SOP)

As an org admin or manager, I want the platform to handle offboarding when a manager or employee resigns, so that access is revoked, data is preserved for audit, copilots are deprovisioned, and reporting lines are gracefully reassigned.

Acceptance Criteria:

Admin or authorised manager can initiate an offboarding workflow for a departing employee by marking them as "offboarding" in the org hierarchy.
Offboarding an individual contributor: (a) their personal copilot is suspended, (b) platform access is revoked, (c) conversation history and work artifacts are retained for audit per the tenant's data retention policy, (d) their seat is released from billing at the end of the current billing period (or immediately, per admin preference).
Offboarding a manager: (a) all of the above, plus (b) the system prompts the admin to reassign the manager's direct reports to a new manager before finalising offboarding, (c) if the departing manager had delegated enablement rights, those are transferred to the new manager, (d) any agent teams deployed by the departing manager are flagged for review -- the admin or new manager must confirm continuation, transfer ownership, or decommission them.
If the departing user was the sole approver in any active approval workflow, the system escalates to the next person in the hierarchy or to the org admin.
If the HRIS sync is active and detects a departure (employee marked inactive in HRIS), the offboarding workflow is triggered automatically (or queued for admin review, per policy).
The system generates an offboarding summary: what was revoked, what was reassigned, what data was retained, and any pending actions requiring admin attention.
All offboarding actions are recorded in the audit trail.

US-11: Copilot Actions with Human-in-the-Loop Approval

As an org admin, I want to configure approval workflows for certain copilot actions, so that high-impact actions require human sign-off before execution.

Acceptance Criteria:

Org admins can define approval policies: which actions require human approval (e.g., sending emails, creating tickets, modifying code).
When a copilot or agent encounters an action requiring approval, it pauses and notifies the relevant approver.
Approvers can approve, reject, or modify the proposed action.
All approval decisions are logged in the audit trail.
Approval workflows apply to both personal copilots and agent team agents.

6. FUNCTIONAL REQUIREMENTS

Human Employee Registry

The system MUST maintain a human employee registry as part of the org hierarchy. Each human employee record MUST store: full name, email, job title, designation, department, seniority level (Junior, Mid, Senior, Staff, Principal, or equivalent), manager relationship (reports-to), and optional external_id for HRIS sync.
The system MUST support linking employee records to an external HRIS (e.g., Workday, BambooHR) via external_id and source fields. The system MUST support automated sync from external HR systems to keep the employee registry up to date.
Employee records MUST be unique per tenant (email uniqueness scoped to tenant).

Org Hierarchy Management

The system MUST model the org hierarchy as a tree structure with reporting-line (reports-to) relationships supporting arbitrary depth. Each node has exactly one parent (except the root node).
Departments MUST be modelled as a taxonomy applied to each node in the hierarchy (not as a separate structural layer). Departments are a configurable taxonomy (e.g., Engineering, Marketing, SRE, QA, Platform, Sales, HR). Admins MUST be able to add custom departments.
The hierarchy MUST include both human employees and headless agent users. Each node MUST have a type indicator (human or agent) that is stored in the data model and visually distinguished in the org chart UI.
Each human employee node MUST store: name, email, job title, designation, department, seniority level, reporting relationship (parent node), and optional external_id and source fields.
Each headless agent node MUST store: agent name, designation/title, department, clearance level, reporting relationship (parent node), deploying user reference, and agent team reference.
The system MUST provide CRUD operations on all hierarchy nodes.
The system MUST render the hierarchy visually as an org chart with human employees and AI agents visually distinguished (e.g., badges, icons, or colour coding).
The system MUST support bulk import of hierarchy data (CSV upload at minimum).
The system MUST enforce tenant isolation -- hierarchy data is never visible across tenants.

User Enablement

The system MUST allow org admins to enable/disable platform access for any user in the hierarchy.
The system MUST allow org admins to enable all users in one action ("enable all").
The system MUST allow managers to enable/disable their direct reports (delegated enablement), governed by an org-level policy toggle.
Delegated enablement MUST follow the hierarchy recursively: if manager A's reportee B is also a manager, B can delegate enablement to B's reports, provided the org-level delegation policy is enabled.
The system MUST maintain an audit log of all enablement/disablement actions (who, whom, when, by what authority).
Enabling a user MUST trigger automatic personal copilot agent provisioning.
Disabling a user MUST suspend (not delete) their copilot agent and conversation history.

Personal Copilot Assignment

The system MUST maintain a competency catalogue: a mapping of designation patterns to copilot competency profiles.
Seniority (Junior, Mid, Senior, Staff, Principal) MUST be treated as a modifier on the base competency, not a separate competency entry. The copilot MUST adapt its depth of guidance, assumed expertise, and communication style based on the seniority modifier.
The system MUST ship with a default competency catalogue covering at least: Software Engineer, Engineering Manager, SRE, QA Engineer, Product Manager, Marketing Specialist, Sales Representative, HR Specialist, Designer, Data Analyst, Executive/C-Suite.
Org admins MUST be able to create, edit, and manage custom competency profiles for roles not covered by the default catalogue. Custom profiles follow the same structure as default profiles (system prompt/persona, tools, knowledge domains, behavioural guidelines, seniority adjustments).
On user enablement, the system MUST automatically match the user's designation to the closest competency profile and provision a copilot with that profile.
If no exact match is found, the system MUST fall back to a "General Assistant" competency and flag it for admin review.
The competency profile MUST define: system prompt/persona, available tools/integrations, knowledge domains, behavioural guidelines, and seniority-based adjustments.
The system MUST allow org admins to override a user's auto-assigned competency.

Copilot Personalisation

The system MUST personalise copilot responses over time based on the user's interaction history, preferences, and working patterns.
Users MUST be able to view and reset their personalisation data.
Personalisation data MUST be scoped per-user, per-tenant and MUST NOT leak across users or tenants.

Agent Teams

The system MUST allow users with engineering leadership designations (Engineering Manager, Tech Lead, Director of Engineering, VP Engineering, CTO, or equivalent) OR org admin role to deploy agent teams.
An agent team MUST support one or more agents. Each agent has a designation, clearance level, and configurable autonomy level.
Agent team deployment MUST require approval from (a) the deploying user's skip-level manager AND (b) the org admin before going live.
For org admins deploying their own teams, only a confirmation step is required (no skip-level approval needed).
For single-person companies where the sole user is both org admin and engineering leader, self-approval of agent team deployment MUST be supported. This includes deploying agents with engineering leadership designations.
Once approved, each agent in the team MUST be registered as a headless user in the org hierarchy with the appropriate clearance level.
Agent teams MUST support configurable autonomy: fully autonomous, semi-autonomous (checkpoints at defined stages), or fully supervised (human approval gate before each action).
Approval gates MUST be configurable per action type.
All agent actions MUST be recorded on the organisation's existing source control platform as an audit trail.
Agent teams MUST be pausable, resumable, and decommissionable by the deploying user or org admin.
The system MUST track agent team active hours for billing purposes.

Human-in-the-Loop Approval Workflows

The system MUST support configurable approval workflows for copilot and agent actions.
Org admins MUST be able to define which action types require human approval.
When an action requires approval, the copilot or agent MUST pause execution and notify the designated approver.
Approvers MUST be able to approve, reject, or modify proposed actions.
All approval decisions MUST be recorded in the audit trail.

Chat Interface

The system MUST provide a web-based chat interface as the primary interaction point.
The chat interface MUST show a centred prompt on the landing page.
The sidebar MUST include: org chart navigation, user settings, conversation history, agent team management (for eligible users), and admin panel (for admins/managers).
The system MUST persist conversation history per user.
The copilot MUST respond in the context of its assigned competency profile.
The copilot MUST support multi-language interaction. The system MUST detect the user's preferred language and respond accordingly, with support for at least English, Spanish, French, German, Portuguese, Japanese, and Mandarin at launch.

Integration Marketplace

The system MUST provide an integration marketplace where org admins can connect external tools to copilots and agent teams.
v1 integrations MUST include at minimum: GitHub, GitLab, Jira, Slack, and Microsoft Teams.
Each integration MUST be configurable per-org and per-agent (which agents/copilots have access to which integrations).
Integration credentials MUST be stored securely (encrypted at rest) and scoped per-tenant.
The integration framework MUST be extensible to support additional integrations post-launch.

Authentication & Authorisation

The system MUST support SSO (SAML 2.0 / OIDC) for enterprise clients and email/password for smaller orgs.
The system MUST enforce role-based access control (RBAC) with at least five roles: Platform Owner, Org Admin, Manager, Individual Contributor, Headless Agent.
Permissions MUST be derived from the org hierarchy, enablement status, and clearance level (for agents).
The Platform Owner role MUST be entirely separate from tenant roles -- a platform owner does not belong to any tenant.

Platform Owner Console

The system MUST provide a dedicated Platform Owner Console accessible only to users with the platform_owner role.
The console MUST display all onboarded organisations with: org name, onboarding date, plan/tier, total employees, enabled seats, active users (7/30 day), agent teams deployed, agent-hours consumed, and billing status.
The console MUST provide search, sort, and filter capabilities across the organisation list.
The console MUST show a per-organisation expense view with dual billing streams: personal copilot revenue (seat-based), agent team revenue (hourly), total revenue, total LLM token cost, gross margin, and month-over-month trends.
The console MUST show an aggregate expense summary: total platform revenue (broken down by copilot seats and agent-hours), total LLM cost, total gross margin.
The console MUST highlight cost anomalies where LLM cost exceeds a configurable threshold percentage of revenue.
The console MUST show seat utilisation per organisation (enabled vs. active seats) and agent team utilisation (agent-hours consumed vs. allocated).
The console MUST support CSV export of organisation and expense data.
The console MUST provide a drill-down view per organisation (summary-level only, not individual user data) to respect tenant data privacy.
The console MUST be completely isolated from tenant-facing UI -- org admins and users MUST NOT have any visibility into it.

Billing & Cost Tracking

The system MUST implement a dual billing model: Personal copilots (human users) use seat-based pricing (billed per enabled user per month). Agent teams use hourly pricing (agents accrue cost by the hour they are active/running).
Both billing streams MUST be visible separately in the Platform Owner Console and in the per-org billing view (Org Admin dashboard).
The system MUST track per-tenant, per-user LLM token consumption in real time.
The system MUST associate each copilot/agent interaction with its token cost (input tokens, output tokens, model used, cost).
The system MUST aggregate costs at the user, agent team, department, and organisation level.
The system MUST expose cost data to the Platform Owner Console and (aggregated, per-tenant scoped) to Org Admin dashboards.
The system MUST support per-org and per-department token budgets that org admins can configure. When a budget threshold is approached, the system MUST alert the admin. When exceeded, the system MUST enforce the configured policy (alert-only, throttle, or hard-stop).
The system MUST support usage-based billing tiers as an option: for heavy users, a per-token overage charge beyond included message caps.

Advanced Analytics

The system MUST provide copilot effectiveness scoring: task completion rates, user satisfaction signals (thumbs up/down, explicit feedback), and response quality metrics.
The system MUST surface analytics at the per-user, per-department, and per-org level.
Analytics MUST be available to org admins in the admin dashboard and to platform owners in the Platform Owner Console.

HRIS Import & Sync

The system MUST support connecting to external HR systems (Workday, BambooHR, and other major HRIS providers) via OAuth or API key authentication for org hierarchy import.
The system MUST map HRIS fields to UpsQuad hierarchy fields (employee name, email, job title, designation, department, seniority level, reporting relationship) during import.
The system MUST provide an import preview allowing the admin to review the mapped org chart before confirming the import.
The system MUST handle import conflicts gracefully: when an employee already exists (matched by email or external_id), the system MUST offer merge, skip, or overwrite options.
The system MUST support ongoing automated sync from HRIS at a configurable interval (e.g., daily, weekly) to keep the org hierarchy current.
The system MUST detect changes during sync (new hires, departures, title changes, reporting line changes) and apply them automatically or queue for admin review, based on a configurable policy.
The system MUST maintain an audit log of all HRIS sync operations (imports, updates, deletions).

Employee & Manager Offboarding

The system MUST support an offboarding workflow triggered by admin or authorised manager for departing employees.
Offboarding an individual contributor MUST: (a) suspend their personal copilot, (b) revoke platform access, (c) retain conversation history and work artifacts per the tenant's data retention policy, (d) release their seat from billing at the end of the current billing period or immediately per admin preference.
Offboarding a manager MUST additionally: (a) require reassignment of direct reports to a new manager before finalisation, (b) transfer delegated enablement rights to the new manager, (c) flag agent teams deployed by the departing manager for review -- the admin or new manager must confirm continuation, transfer ownership, or decommission them.
If the departing user was the sole approver in any active approval workflow, the system MUST escalate to the next person in the hierarchy or to the org admin.
If HRIS sync is active and detects a departure (employee marked inactive in HRIS), the offboarding workflow MUST be triggered automatically or queued for admin review per policy.
The system MUST generate an offboarding summary: what was revoked, what was reassigned, what data was retained, and any pending actions requiring admin attention.

Copilot-to-Copilot Collaboration

The system MUST support personal copilots communicating with each other across users within the same tenant, enabling cross-user AI coordination.
Copilot-to-copilot collaboration MUST respect permission boundaries: copilots may only communicate with other copilots whose users are in the same team or have explicitly granted cross-team collaboration access.
All copilot-to-copilot interactions MUST be logged in the audit trail with both participating user IDs and the interaction summary.
Users MUST be able to view the cross-copilot interactions their copilot has participated in.
Org admins MUST be able to enable or disable copilot-to-copilot collaboration as an org-level policy.

7. NON-FUNCTIONAL REQUIREMENTS

Category	Requirement	Target
Performance	Org chart rendering for up to 10,000 nodes (including agent nodes)	< 2 seconds initial load
Performance	Copilot first-token response latency	< 1.5 seconds (p95)
Performance	Platform Owner Console load time (up to 10,000 orgs)	< 3 seconds
Scalability	Support 1,000 tenants with up to 10,000 users each (human + agent)	Horizontal scaling
Security	Tenant data isolation	Row-level security + namespace isolation
Security	Platform Owner Console access	Separate auth domain, MFA required
Security	All PII encrypted at rest and in transit	AES-256 at rest, TLS 1.3 in transit
Security	Agent clearance levels enforced at API layer	Zero-trust per-request verification
Compliance	Audit trail for all admin/enablement/agent actions	Immutable append-only log
Compliance	GDPR: right to erasure for user data	Supported within 30 days
Compliance	All agent actions recorded on org's source control platform	100% action traceability
Availability	Platform uptime	99.9% SLA
Cost Visibility	Per-tenant, per-user copilot token usage tracking	Real-time dashboard
Cost Visibility	Per-tenant agent team hourly cost tracking	Real-time dashboard
Cost Visibility	Platform-wide expense aggregation (dual streams)	Updated within 5 minutes of interaction
Internationalisation	Copilot multi-language support	7+ languages at launch

8. SCOPE

In Scope (v1)

Human employee registry with job title, designation, department, manager relationship, seniority level, and external_id for HRIS sync
Org hierarchy as a tree with reporting-line relationships, arbitrary depth, department taxonomy on each node, supporting both human employees and headless agent users (visually distinguished)
Org hierarchy CRUD (tree structure, departments, designations, seniority levels)
Visual org chart rendering with human/agent distinction
CSV bulk import for hierarchy
Automated HR system sync (via external_id and source fields)
User enablement/disablement by admin
Delegated enablement by managers (recursive, policy-governed)
Default competency catalogue (11+ roles) with seniority as modifier
Custom competency profile creation by org admins
Automatic personal copilot assignment based on designation
Copilot personalisation based on interaction history and working patterns
Agent team deployment with approval workflows (skip-level manager + org admin)
Agent team agents as headless users in org hierarchy with clearance levels
Configurable agent team autonomy (full, semi, supervised) with approval gates
Human-in-the-loop approval workflows for copilot and agent actions
Chat interface with role-based copilot
Multi-language copilot support (7+ languages)
Conversation persistence
Admin dashboard (adoption metrics, copilot effectiveness scoring, agent team status)
SSO + email/password authentication
RBAC (Platform Owner, Admin, Manager, IC, Headless Agent)
Tenant isolation
Enablement audit log
Dual billing model: seat-based for personal copilots + hourly for agent teams
Usage-based billing tiers (per-token overage option)
Per-org and per-department token budgets
Per-tenant, per-user LLM token cost tracking
Integration marketplace (GitHub, GitLab, Jira, Slack, Microsoft Teams)
Advanced analytics (copilot effectiveness scoring, task completion rates)
Platform Owner Console: all-org view, dual-stream expense tracking, seat and agent-hour utilisation, anomaly detection, CSV export
Copilot-to-copilot collaboration (personal copilots communicating with each other across users, enabling cross-user AI coordination with appropriate permission and privacy controls)
HRIS import and automated sync (connect to Workday, BambooHR, and other HR systems to import and continuously sync org hierarchy)
Employee and manager offboarding SOP (structured offboarding workflow handling access revocation, copilot deprovisioning, reporting line reassignment, and agent team ownership transfer)

Out of Scope (v1) -- with explicit rationale

Mobile app: v1 focuses on the web platform. Mobile requires a separate design and development track, and the core web experience must be validated first. Tracked for v2.
Premium competency packs (specialised paid add-ons for Legal, Compliance, Finance): The competency framework must be validated with default + custom profiles before introducing a marketplace/pricing layer on top. Tracked for v2.

9. DEPENDENCIES

Dependency	Type	Impact
LLM Provider (e.g., OpenAI, Anthropic)	External	Copilot and agent responses depend on LLM API availability and pricing
SSO/Identity Provider integration	External	Enterprise onboarding blocked without SAML/OIDC support
Billing/Payment system	Internal	Dual billing model (seat-based + hourly) must be wired before GA
Competency catalogue design	Internal	Copilot quality depends on well-crafted competency profiles
Frontend framework setup	Internal	Chat interface and org chart rendering depend on frontend scaffold
LLM cost tracking pipeline	Internal	Platform Owner Console expense view depends on real-time token cost tracking
Source control integration (GitHub/GitLab)	External	Agent team audit trail depends on SCM API availability
Integration marketplace APIs	External	Jira, Slack, Teams integrations depend on third-party API access and rate limits
HRIS provider APIs	External	HR system sync depends on HRIS API access

10. EDGE CASES & FAILURE MODES

Scenario	Expected Behaviour
Admin creates an org with only 1 person	System allows it; that person is both admin and IC; personal copilot assigned normally. That person can also deploy an agent team with self-approval.
Single-person company deploys an agent team with an engineering leader agent	Allowed. The sole user (org admin + engineering leader) self-approves. The agent team can include agents with any designation, including engineering leadership roles.
User's designation does not match any competency	System assigns "General Assistant" copilot and flags for admin review. Admin notified via dashboard alert.
Manager tries to enable a user outside their reporting line	System rejects with clear error: "You can only enable your direct reports."
Admin disables a user who has active conversations	Copilot is suspended; conversations are preserved but inaccessible until re-enabled.
User's designation changes (e.g., promoted from SWE to EM)	Admin updates designation in hierarchy; copilot competency is re-evaluated and updated. Conversation history is preserved. User may now be eligible to deploy agent teams.
Two tenants have users with the same email	Allowed -- email uniqueness is scoped per tenant, not globally.
Bulk CSV import has malformed rows	System imports valid rows, rejects invalid ones, and returns a detailed error report.
LLM provider is down or rate-limited	Copilot shows a graceful degradation message: "I'm temporarily unavailable. Your message has been queued." Retry with exponential backoff. Agent teams pause and notify deploying user.
Admin enables 5,000 users at once	System queues copilot provisioning asynchronously; admin sees progress bar; no timeout.
Delegated enablement is disabled by admin policy after managers have already enabled users	Previously enabled users remain enabled; managers lose the ability to enable/disable going forward.
Manager's reportee (also a manager) delegates enablement further down	Allowed if org-level delegation policy is enabled. The system enforces hierarchy scope at every level.
Platform owner drills into an org	Only summary-level data shown (seat counts, expense totals, plan tier, agent team counts). No individual user names, emails, or conversation content exposed.
Organisation is suspended for non-payment	All copilots and agent teams for that org are suspended. Users see a "Your organisation's subscription is inactive" message. Org admin can still log in to resolve billing. Platform owner sees "Suspended" status in console.
LLM cost for an org spikes unexpectedly	Platform Owner Console highlights the anomaly. If per-org token budget is configured, the system enforces the configured policy (alert, throttle, or hard-stop).
Agent team deployment approval is rejected	The deploying user is notified with the rejection reason. Agents are NOT registered in the hierarchy. The user can revise and resubmit.
Agent team agent exceeds its clearance level	The system blocks the action and logs the attempted access violation. The deploying user and org admin are notified.
Agent team is decommissioned	All headless agent users from that team are removed from the org hierarchy. Agent team data (actions, logs) is retained for audit purposes. Hourly billing stops.
Skip-level manager is not available for agent team approval	Approval request escalates to the next level up in the hierarchy. If no manager exists (e.g., reports directly to CEO who is unavailable), the org admin can approve alone.
Integration (e.g., Jira, Slack) credentials expire or become invalid	The system detects the failure, disables the integration gracefully, notifies the org admin, and queues pending actions for retry once credentials are refreshed.
HRIS import has employees with missing required fields	System imports complete records, flags incomplete records with specific missing fields, and presents an admin review queue. Admin can manually fill gaps or skip those records.
HRIS sync detects a manager departure but no replacement is designated in HRIS	System triggers offboarding workflow and prompts admin to manually assign a new manager for orphaned reports before finalising. Reports are not left without a manager.
Manager resigns while having active agent teams	Agent teams are flagged for review. They continue running until the admin or new manager explicitly confirms continuation (with ownership transfer), or decommissions them. No automatic decommissioning to avoid disruption.
Employee is offboarded but has pending approval actions	System escalates pending approvals to the next person in the hierarchy or to the org admin. Departing user's pending approvals are never silently dropped.
HRIS sync runs while admin is manually editing the org chart	HRIS sync detects conflicts and queues them for admin review rather than overwriting manual changes. Admin sees a merge interface.
Copilot-to-copilot collaboration attempted across teams without permission	System blocks the interaction with clear error: "Cross-team copilot collaboration requires explicit access grant from both team leads."
Copilot-to-copilot collaboration disabled at org level after being active	Existing cross-copilot conversation threads are preserved as read-only. No new cross-copilot interactions are allowed. Users see a notice that the feature has been disabled by their admin.

11. DECISIONS (RESOLVED FROM OPEN QUESTIONS)

The following decisions were originally open questions and have been resolved based on product recommendation:

Competency granularity: Seniority (Junior, Mid, Senior, Staff, Principal) is treated as a modifier on the base competency profile, not a separate competency. This keeps the catalogue simple and shippable. The copilot adapts tone, depth, and assumed context based on seniority. Requirement captured in FR-21.
Hierarchy source of truth: The data model MUST include external_id and source fields on every hierarchy node from day one. These fields support HRIS sync which is now in v1 scope. Requirement captured in FR-1, FR-2.
Copilot personalisation: Now in v1 scope. The copilot personalises based on interaction history and working patterns. Users can view and reset their personalisation data. Requirement captured in FR-28 through FR-30.
Enablement cost model: v1 uses a dual billing model -- seat-based for personal copilots and hourly for agent teams. Usage-based tiers are also available as an option. See Pricing Model section.
Admin delegation depth: Delegated enablement follows the hierarchy recursively. If manager A's reportee B is also a manager, B can delegate enablement to B's reports -- provided the org-level delegation policy is enabled. This mirrors real-world management structures. Requirement captured in FR-16.
Two-mode product model: UpsQuad provides Personal Copilots (for all enabled users) and Agent Teams (for engineering leaders / org admins). Agent teams require skip-level manager + org admin approval. This dual-mode approach allows the platform to serve both individual productivity and team-scale automation. Requirement captured in FR-31 through FR-41.
Agent identity model: Agent team agents are headless users in the org hierarchy with clearance levels, visually distinguished from humans. This ensures agents are governed by the same hierarchy rules as human employees while maintaining clear visibility into which nodes are AI. Requirement captured in FR-6, FR-8.

12. PLATFORM ARCHITECTURE OVERVIEW

Platform Console (Super-Admin: Founders only, above L5)
    |
    v
Tenant Layer (L5 Admin per tenant)
    |
    v
+------------------------------------------------------------------+
| Client Layer: Web Dashboard | CLI | SCM Plugin | API SDK          |
+------------------------------------------------------------------+
| API Gateway: Services + Auth + Custom Clearance                   |
+------------------------------------------------------------------+
| Core Platform: Workflow Engine | Agent Manager | Cost Engine       |
|   Clearance Engine | Context Engine | Change Guard | Config DB    |
+------------------------------------------------------------------+
| Agent Runtime: Executor | LLM Router | Tool Registry (MCP)       |
+------------------------------------------------------------------+
| Data Layer: Relational DB + Vector Store | Cache | Object Storage |
|   Event Streaming                                                 |
+------------------------------------------------------------------+
| Infrastructure: Container Orchestration | IaC | GitOps | CI/CD   |
+------------------------------------------------------------------+

13. PRIORITY 0 -- PRE-DEVELOPMENT

Everything that must be decided, drafted, or established before writing production code.

P0.1 Legal Foundation

Item	Description	Release
P0.1.1	Company incorporation (India Pvt Ltd, DPIIT Startup India registration)	MVP
P0.1.2	Terms of Service draft (covering AI agent actions, liability limitations, indemnification for agent outputs, SLA commitments)	MVP
P0.1.3	Privacy Policy (GDPR Article 13/14 compliant, CCPA notice, data processing details, AI-specific disclosures)	MVP
P0.1.4	Data Processing Agreement (DPA) template for enterprise customers (Standard Contractual Clauses, sub-processor list, breach notification procedure)	MVP
P0.1.5	Acceptable Use Policy (prohibited use cases, agent abuse prevention, content policies)	MVP
P0.1.6	SLA document (uptime commitments per tier: 99.5%/99.9%/99.99%, credit calculation, exclusions)	V1.1
P0.1.7	Patent filing -- Indian provisional application (IPO) for Context Engine + Change Guard + Immutable Agent Rules	MVP
P0.1.8	US/PCT patent application (follow provisional)	V1.1
P0.1.9	Cookie Policy and consent mechanism	MVP
P0.1.10	Open source license audit for all dependencies	MVP
P0.1.11	AI-specific liability clauses (agent output accuracy disclaimers, human oversight requirements)	MVP

P0.2 Compliance Preparation

Item	Description	Release
P0.2.1	EU AI Act classification assessment (determine risk category for AI workforce agents -- likely "limited risk" requiring transparency obligations)	MVP
P0.2.2	NIST AI Risk Management Framework (AI RMF) alignment checklist	V1.1
P0.2.3	SOC 2 Type I preparation (identify controls, document policies, define scope)	V1.1
P0.2.4	GDPR data flow mapping (every personal data touchpoint documented: ingestion, storage, processing, deletion)	MVP
P0.2.5	Data residency strategy document (which data in which region, cross-border transfer mechanisms)	MVP
P0.2.6	Incident response plan (security breach notification within 72 hours per GDPR, communication templates, escalation chain)	MVP
P0.2.7	OWASP Top 10 compliance checklist for all API endpoints	MVP
P0.2.8	AI model governance policy (approved models, evaluation criteria, model retirement process)	MVP
P0.2.9	Vendor risk assessment for all third-party providers (auth, billing, cloud, LLM providers)	V1.1

P0.3 Design & Architecture Decisions

Item	Description	Release
P0.3.1	Architecture Decision Records (ADR) template and first 10 ADRs: database isolation strategy, auth architecture, agent execution model, event bus choice, context storage format, API versioning, error code taxonomy, config hierarchy, approval chain data model, cost tracking granularity	MVP
P0.3.2	Database schema design v1 (all tables for P1-P4: tenants, users, teams, sub_teams, agents, agent_configs, org_hierarchy, employee_registry)	MVP
P0.3.3	API design (OpenAPI 3.1 spec) for core resources: tenants, teams, agents, workflows, approvals, configs, users, permissions, org hierarchy, enablement	MVP
P0.3.4	Inter-service communication contract definitions (service interfaces and message schemas)	MVP
P0.3.5	Event schema design (event format, envelope structure, versioning)	MVP
P0.3.6	UI/UX wireframes for MVP screens: login, dashboard (5 levels), agent detail, workflow detail, chat, config, org chart (with human/agent distinction), adoption dashboard	MVP
P0.3.7	Design system formalization (design tokens into component library: colors, typography, spacing, component specs)	MVP
P0.3.8	Error code taxonomy (structured error codes: USQ-AUTH-001, USQ-AGENT-001, etc. with human-readable messages and remediation hints)	MVP
P0.3.9	Platform Console wireframes (super-admin views for all-tenant monitoring, dual-stream billing, health)	MVP
P0.3.10	Monorepo structure decision and initial repository scaffolding	MVP
P0.3.11	ADR: Stateless Agent Runtime -- All agent instances must be stateless. No local file-based context, memory, or configuration. Agent instances contain only the executable and runtime. All context, memory, guardrails, and operational state must be fetched from external systems (database, cache, object storage) at session initialization. This is a foundational architectural constraint; all P2, P3, and P4 items must comply.	MVP
P0.3.12	ADR: Immutable Session Runtime -- Once an agent session starts, the agent operates on a frozen snapshot of its context, guardrails, and configuration for that session's duration. No mid-session config reloads, no mid-session guardrail mutations. Configuration changes take effect only on new sessions. Running sessions may receive a 'critical config update' signal that triggers graceful termination and restart with new config, but never silent mid-session mutation. Agents may explicitly refresh via /pull-context which ends the current snapshot scope and creates a new immutable snapshot.	MVP

P0.4 Infrastructure Accounts & Setup

Item	Description	Release
P0.4.1	Cloud provider organization setup (billing account, project hierarchy: prod, staging, dev)	MVP
P0.4.2	Domain DNS configuration (upsquad.ai, subdomains: api., app., console., docs., status.)	MVP
P0.4.3	Auth provider account setup and configuration (OAuth providers, custom claims for clearance level, tenant ID)	MVP
P0.4.4	Payment provider account setup (products, prices, webhook endpoints, tax settings)	MVP
P0.4.5	Source control organization setup (branch protection, required reviews, CI/CD secrets)	MVP
P0.4.6	Team email and collaboration workspace completion	MVP
P0.4.7	Monitoring and alerting accounts (dashboards, on-call alerting)	MVP
P0.4.8	LLM provider accounts (API keys, billing alerts)	MVP

14. PRIORITY 1 -- FOUNDATION

P1.1 Infrastructure & Deployment Core

Item	Description	Release
P1.1.1	Container orchestration cluster provisioning via IaC (single region for MVP)	MVP
P1.1.2	Namespace-per-tenant isolation pattern (IaC module that creates namespace + network policies + resource quotas per tenant)	MVP
P1.1.3	Container registry with image scanning enabled	MVP
P1.1.4	GitOps deployment pipeline (source control commit triggers sync to orchestration platform)	MVP
P1.1.5	Secrets management integration (IaC-managed, accessed via workload identity)	MVP
P1.1.6	IaC for all infrastructure (orchestration, database, cache, object storage, networking, IAM)	MVP
P1.1.7	CI/CD pipeline (lint, test, build, push image, trigger deployment sync)	MVP
P1.1.8	Multi-region readiness (IaC module parameterized by region, not deployed until V1.1)	V1.1
P1.1.9	Staging environment (separate cluster, separate database, same IaC modules)	MVP
P1.1.10	Development environment (local container orchestration, container-compose for dependencies)	MVP

P1.2 Database & Storage Layer

Item	Description	Release
P1.2.1	Managed relational database instance (HA, automated backups, point-in-time recovery enabled)	MVP
P1.2.2	Per-tenant schema isolation (schema creation on tenant provisioning, connection routing middleware)	MVP
P1.2.3	Schema design and migration framework (versioned SQL migrations, CI validation)	MVP
P1.2.4	Core schema: tenants, users, teams, sub_teams, agents, agent_configs, org_hierarchy, employee_registry	MVP
P1.2.5	Workflow schema: workflows, workflow_steps, approvals, approval_chains	MVP
P1.2.6	Governance schema: permissions, role_templates, access_grants, audit_logs, configs	MVP
P1.2.7	Distributed cache cluster (used for: caching, rate limiting, pub/sub, session state)	MVP
P1.2.8	Object storage buckets (per-tenant prefix isolation for agent memory, artifacts, exports)	MVP
P1.2.9	Vector search extension enabled on relational database (for RAG knowledge base storage)	MVP
P1.2.10	Event streaming setup (topics: workflow.events, agent.events, approval.events, config.events, audit.events)	MVP
P1.2.11	Database connection pooling with per-tenant routing	MVP
P1.2.12	Automated backup verification (weekly restore test to staging)	V1.1
P1.2.13	Database encryption at rest (default provider encryption) + application-level encryption for sensitive fields (API keys, BYOK keys) using per-tenant Data Encryption Keys (DEKs) wrapped by a Key Encryption Key (KEK) in a managed key service	MVP

P1.3 API Gateway & Auth

Item	Description	Release
P1.3.1	API gateway service (single entry point, supports both REST and internal RPC)	MVP
P1.3.2	Auth token verification middleware (validate tokens, extract user_id, email)	MVP
P1.3.3	Custom clearance layer middleware (user_id lookup for clearance level + tenant_id + team memberships from DB, inject into request context)	MVP
P1.3.4	Tenant resolution middleware (from token claims to tenant context, reject if tenant mismatch)	MVP
P1.3.5	Rate limiting engine (cache-backed token bucket algorithm, per-tenant limits based on pricing tier, standard rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After)	MVP
P1.3.6	WebSocket server for real-time agent status, workflow updates, chat	MVP
P1.3.7	API versioning (URL path prefix /v1/, version negotiation middleware)	MVP
P1.3.8	CORS configuration (allow app and console subdomains, localhost for dev)	MVP
P1.3.9	Request ID generation and propagation (X-Request-ID header, passed through all downstream services)	MVP
P1.3.10	Graceful degradation on rate limit (429 response with Retry-After, priority queue for paid tiers)	V1.1
P1.3.11	API key authentication (for programmatic/SDK access, separate from browser auth)	V1.1

P1.4 Multi-Tenancy Core

Item	Description	Release
P1.4.1	Tenant provisioning service (create tenant triggers: create namespace + DB schema + object storage prefix + cache keyspace + default configs)	MVP
P1.4.2	Tenant isolation enforcement (network policies preventing cross-namespace traffic, DB schema isolation preventing cross-schema queries, object storage prefix isolation)	MVP
P1.4.3	Tenant configuration store (plan tier, limits, region, feature flags, stored in platform schema)	MVP
P1.4.4	Cross-tenant request prevention (middleware: every DB query scoped to tenant schema, every object storage path scoped to tenant prefix, every cache key scoped to tenant ID)	MVP
P1.4.5	Tenant lifecycle: create, suspend (disable API access, pause agents), resume, delete	MVP
P1.4.6	Tenant deletion with data retention policy (soft delete, 30-day retention window, then hard purge of all tenant data including DB schema, object storage objects, cache keys, namespace)	MVP
P1.4.7	Cross-tenant prevention integration tests (automated tests that attempt cross-tenant data access and verify rejection)	MVP
P1.4.8	GDPR right-to-be-forgotten implementation (on tenant or user deletion: purge all PII, anonymize audit logs, delete from all storage backends, generate deletion certificate)	V1.1
P1.4.9	Tenant migration tooling (move tenant between regions, resize quotas)	V2

P1.5 Observability Foundation

Item	Description	Release
P1.5.1	Distributed tracing and metrics instrumentation in all services (traces, metrics, logs via standard telemetry protocol)	MVP
P1.5.2	Dashboards: platform health (service latency P50/P95/P99, error rates, instance count), per-tenant metrics (agent count, workflow throughput, cost)	MVP
P1.5.3	Structured JSON logging (with trace_id, span_id, tenant_id, user_id, agent_id fields)	MVP
P1.5.4	Error tracking and alerting (on-call integration for P0/P1 errors, chat notification for P2+)	MVP
P1.5.5	Cost metering hooks (instrument every LLM call with: model, input_tokens, output_tokens, latency, tenant_id, agent_id, workflow_id)	MVP
P1.5.6	Audit log pipeline (every state-changing operation logged to audit_logs table with: who, what, when, tenant_id, resource_type, resource_id, old_value, new_value)	MVP
P1.5.7	Health check endpoints (/healthz, /readyz) for all services	MVP
P1.5.8	SLI/SLO definitions (availability, latency, error rate targets per service)	V1.1

P1.6 Auth Hardening (GAP FILL: Security, Auth Details)

Item	Description	Release
P1.6.1	MFA/2FA enforcement (TOTP/WebAuthn, required for L3+ clearance, optional for L1-L2)	MVP
P1.6.2	Password reset flow (managed by auth provider, custom branded email template)	MVP
P1.6.3	Session management (configurable timeout per tier: 8h/24h/30d, force logout capability for L4+ admins)	MVP
P1.6.4	Token refresh strategy (short-lived access tokens + refresh tokens, sliding window refresh)	MVP
P1.6.5	Device tracking (device fingerprinting, display active sessions to user, allow remote session revocation)	V1.1
P1.6.6	Suspicious activity detection (failed login rate limiting: 5 attempts then 15-min lockout, IP-based anomaly detection, geo-impossible-travel detection)	V1.1
P1.6.7	Auth provider webhook handler (user.created, user.updated, user.deleted, session.created, session.ended events synced to local DB)	MVP

15. PRIORITY 2 -- AGENT RUNTIME

P2.1 Agent Executor

Item	Description	Release
P2.1.1	Agent = isolated instance model (agent supervisor process in each instance, manages LLM interactions, tool calls, memory)	MVP
P2.1.2	Agent container base image (agent binary + MCP client libraries, minimal attack surface, distroless base)	MVP
P2.1.3	Agent lifecycle manager (service: create, start, pause, terminate, restart agent instances via orchestration API)	MVP
P2.1.4	Agent health checks (liveness + readiness probes, heartbeat to control plane every 30s)	MVP
P2.1.5	Resource limits per agent (CPU/memory requests and limits per agent type, enforced via orchestration resource quotas per tenant namespace)	MVP
P2.1.6	Sandboxed execution (agent instances run with: read-only root filesystem, no privileged escalation, dropped capabilities, network policies restricting egress to only LLM providers + approved MCP servers)	MVP
P2.1.7	Agent status broadcasting (pub/sub: agent status changes published to tenant-scoped channel, consumed by WebSocket server for real-time UI)	MVP
P2.1.8	Agent state persistence and recovery (GAP FILL: on instance death, in-flight workflow state checkpointed to cache every 30s, new instance resumes from last checkpoint)	MVP
P2.1.9	Graceful shutdown handler (SIGTERM handler: complete current LLM call or checkpoint state, drain connections, max 30s grace period)	MVP
P2.1.10	Agent instance scheduling (node affinity: GPU nodes for large model inference, preemptible nodes for burst agents)	V1.1
P2.1.15	Stateless agent contract enforcement -- Agent instances must not persist any state locally. All runtime state in cache, all memory in object storage/database, all config fetched from config DB. Container image is identical across all instances. Enforced by: read-only filesystem (P2.1.6), no writable volumes, liveness probe validates zero local state files.	MVP
P2.1.16	Agent session initialization protocol -- On session start, agent must: (1) fetch role definition and system prompt from config DB, (2) fetch guardrails from all 4 immutable context layers, (3) fetch tool access list and permissions, (4) fetch agent-human mapping and authorization grants, (5) create immutable session snapshot of all fetched data with SHA-256 integrity hash. Agent does not accept work until initialization succeeds. Failed initialization triggers instance restart.	MVP
P2.1.17	Per-action authorization check -- Before every agent action (tool call, LLM interaction, A2A message, memory write, workflow state transition), the agent verifies authorization against the external RBAC/clearance engine. Denied actions are logged to audit trail with full context. Authorization grants are cached in the immutable session snapshot (grants do not change mid-session). Default policy: action is ALLOWED unless a guardrail explicitly prohibits it (blacklist model, see P3.3.6).	MVP
P2.1.18	Agent metrics interface -- Every agent exposes a standard metrics endpoint. Metrics are collected by the platform's observability stack. Agents must self-meter all operations, not rely solely on platform-level instrumentation.	MVP
P2.1.19	Billable metrics per agent -- Each agent must meter and report: LLM token usage (input/output/total per model), tool invocations (count, duration per tool), external API calls (count, duration, cost where applicable), compute time (wall-clock session duration, CPU time), storage used (memory writes, context size). All metrics attributable per-action.	MVP
P2.1.20	Performance metrics per agent -- Each agent must meter and report: response latency (p50/p95/p99), task completion time, error rate (by error type), success rate, throughput (actions per minute). Exposed via metrics endpoint and available for dashboard visualization.	MVP
P2.1.21	Metrics attribution dimensions -- All agent metrics must include dimensions: tenant_id, agent_id, session_id, action_type, timestamp. These dimensions enable per-tenant billing, per-agent performance analysis, per-session debugging, and cross-cutting cost attribution.	MVP

P2.2 LLM Router (Multi-Model Support)

Item	Description	Release
P2.2.1	Unified LLM interface (standard interface: Complete(ctx, model, messages, tools) returning Response, streaming variant)	MVP
P2.2.2	Provider adapters: Anthropic Claude, OpenAI GPT	MVP
P2.2.3	Provider adapter: Google Gemini	V1.1
P2.2.4	Provider adapter: self-hosted models (for on-premise deployments)	V2
P2.2.5	Per-agent model configuration (stored in config DB; changes applied on next session start per immutable session runtime policy P0.3.12; in-flight sessions continue with their initialized model configuration)	MVP
P2.2.6	Automatic fallback chain (primary model to secondary to tertiary, configurable per agent, failover on: rate limit, timeout, 5xx error)	MVP
P2.2.7	BYOK key injection (tenant API keys encrypted with per-tenant DEK, decrypted at call time, never logged, never stored in agent instance filesystem)	MVP
P2.2.8	Per-call cost tracking (input_tokens * input_price + output_tokens * output_price, written to metering table, aggregated by agent/team/tenant)	MVP
P2.2.9	Request retry with exponential backoff (jitter, max 3 retries, circuit breaker after 5 consecutive failures per provider)	MVP
P2.2.10	Streaming response support (SSE from LLM provider to agent to WebSocket to browser)	MVP
P2.2.11	Rate limit management per provider per tenant (track remaining quota, preemptive throttling before hitting provider limits)	V1.1
P2.2.12	Model governance registry (GAP FILL: approved models list, model evaluation scores, model retirement lifecycle, per-tenant model allowlists)	V1.1

P2.3 Agent Type System (Dynamic Role Builder)

Agent types are not hardcoded. The platform ships with pre-built role templates (via the Industry Template Library, section 33) but any tenant can define fully custom agent roles for their industry. An agent is defined by: role name, system prompt, tool access list, recommended model, and behavioral parameters.

Item	Description	Release
P2.3.1	Dynamic Role Builder (tenants define custom agent roles: role name, description, system prompt template, tool access list, recommended model, temperature, max tokens, output format expectations)	MVP
P2.3.2	Per-role configuration: default system prompt, tool access list per agent role (defines which tools are AVAILABLE to the agent; distinct from action guardrails P3.3.6 which define prohibited BEHAVIORS), recommended model, temperature, max tokens, industry context, behavioral guidelines. Stored in config DB, fetched during session initialization (P2.1.16).	MVP
P2.3.3	Agent-agnostic design (role defines behavior template, any model can fill any role, roles are industry-neutral at the engine level)	MVP
P2.3.4	Pre-built role templates from Industry Template Library (engineering, recruitment, sales, legal, marketing, finance, HR, customer support -- see IND section) selectable during onboarding	MVP
P2.3.5	Agent competency levels (L1-L5 per agent instance, affects: task complexity allowed, autonomy level, required human approval frequency)	V1.1
P2.3.6	Role cloning and customization (tenant selects a template role, clones it, modifies system prompt and tools to fit their specific needs)	MVP
P2.3.7	Role marketplace (tenants can publish their custom roles to a shared marketplace for other tenants to discover and clone)	V2
P2.3.8	Role validation (platform validates that a role definition is coherent: system prompt is well-formed, listed tools exist, model is available)	MVP
P2.3.9	Role versioning (role definitions are versioned, changes create new version, agents can pin to specific role version or track latest)	V1.1

P2.4 Tool Registry & MCP

Item	Description	Release
P2.4.1	MCP server framework (agents expose and consume tools via the Model Context Protocol)	MVP
P2.4.2	Built-in tools: code execution (sandboxed container), web search, file I/O (within agent storage prefix)	MVP
P2.4.3	SCM tools via MCP: GitHub (create issues, post comments, read code, create PRs, manage branches)	MVP
P2.4.4	SCM tools via MCP: GitLab (create issues, post comments, read code, create MRs, manage branches)	V1.1
P2.4.5	Tool permission model (L3+ enables/disables tools per agent, stored in config DB, enforced at MCP server level)	MVP
P2.4.6	Custom tool registration (tenant registers their own MCP servers, validated by platform before activation)	V1.1
P2.4.7	Tool execution auditing (every tool call logged: tool_name, input_params hash, output_summary, duration, agent_id, workflow_id)	MVP
P2.4.8	Tool sandboxing (GAP FILL: MCP tool execution in isolated containers, resource limits, timeout enforcement, no network access to internal services except explicitly allowed)	MVP
P2.4.9	Email tool via MCP (send/receive/search emails via tenant-connected email provider -- for agents that communicate with external parties)	MVP
P2.4.10	Calendar tool via MCP (create/read/update calendar events, check availability, schedule meetings)	MVP
P2.4.11	CRM tool via MCP (read/write contacts, deals, activities -- generic adapter interface with provider-specific implementations)	V1.1
P2.4.12	Document generation tool via MCP (generate PDFs, DOCX, spreadsheets from templates -- for contracts, reports, invoices, proposals)	MVP
P2.4.13	Web scraping tool via MCP (structured data extraction from web pages -- for job boards, competitor analysis, market research; respects robots.txt)	V1.1
P2.4.14	Communication tool via MCP (send/receive messages via team messaging platforms -- for agents that need to communicate in team channels)	V1.1
P2.4.15	Generic HTTP/webhook tool via MCP (make authenticated HTTP requests to any REST API -- allows agents to integrate with any SaaS tool the tenant uses, with configurable auth: API key, OAuth2, Bearer token)	MVP
P2.4.16	Context-mode MCP sandboxing [BOOTSTRAP] -- Agent runtime dynamically loads/unloads MCP server definitions based on the current task step. Only tools relevant to the active operation are injected into the agent's context window. Reduces context consumption by eliminating idle tool definitions. Configurable per agent role.	MVP
P2.4.17	MCP security gateway [BOOTSTRAP] -- All agent-to-MCP-server communication routes through a centralized security gateway. Enforces: authentication (agent identity per call), authorization (P2.4.5 checked centrally), rate limiting (per agent/tool/tenant), request/response payload inspection, emergency tool access revocation. Custom MCP servers (P2.4.6) must route through this gateway.	MVP

P2.5 Agent Scaling

Item	Description	Release
P2.5.1	Event-driven autoscaler (scale on event stream queue depth per tenant)	MVP
P2.5.2	Scale-to-zero for burst agents (QA, security scan -- scales to 0 when idle, scales up on workflow assignment)	MVP
P2.5.3	Always-on for core agents (code-gen, architect -- minimum 1 replica, warm start)	MVP
P2.5.4	Per-tenant scaling limits (max agent instances based on pricing tier: Starter 8, Business 30, Enterprise unlimited)	MVP
P2.5.5	Resource-based autoscaling triggers (CPU/memory for compute-intensive agents)	V1.1

16. PRIORITY 3 -- CONTEXT & MEMORY

P3.1 Context Engine

Item	Description	Release
P3.1.1	Context ingestion layer (ingest messages, tool outputs, workflow events into per-agent context store in database)	MVP
P3.1.2	Sliding Window compaction (default strategy: recent N messages full, older messages summarized via LLM)	MVP
P3.1.3	Key-Fact Extraction compaction (extract decisions, constraints, requirements as structured facts)	V1.1
P3.1.4	Hierarchical Summary compaction (minute to hour to day to week summaries)	V1.1
P3.1.5	Task-Scoped compaction (completed tasks compacted, active tasks full)	V1.1
P3.1.6	Compaction trigger (configurable threshold, default 80% of model max tokens)	MVP
P3.1.7	Per-agent/per-team configuration of strategy and thresholds (via config DB)	MVP
P3.1.8	Context overload detection and alerting (alert when context approaches limit inefficiently)	V1.1
P3.1.9	Smart retrieval (semantic search via vector store + recency weighting for context assembly before each LLM call)	MVP
P3.1.10	Context processing: entity extraction, reference resolution, importance scoring	V1.1
P3.1.11	Context refresh mechanism -- Agents may poll for the latest version of their context from the external DB via an explicit refresh operation. Refresh creates a new immutable session snapshot, effectively ending the previous snapshot's scope. Refresh may be triggered by: (a) user slash command /pull-context, (b) agent request with authorization, (c) platform critical-update signal. Refresh is an atomic operation -- agent operates on either old or new snapshot, never partial state.	MVP
P3.1.12	Context push operation -- /push-context saves the agent's accumulated session knowledge (decisions made, facts learned, state changes) to the external memory store. Push does NOT modify the agent's own role definition or guardrails -- it only persists session-derived knowledge. Push requires authorization (agent must have write permission to its own memory namespace).	MVP
P3.1.13	Context pull operation -- /pull-context fetches the latest context (role definition, guardrails, config, memory) from the external DB and creates a new immutable session snapshot. The previous snapshot is discarded. This is the primary mechanism for controlled context updates without violating session immutability. Pull is always authorized for the agent's own context.	MVP
P3.1.14	Context push/pull authorization model -- Push: agent must have write permission to its own memory namespace (default: granted). Pull: always authorized for own context. Neither push nor pull can modify the agent's role definition, guardrails, or system prompt -- those are only editable by the parent agent or human (see P3.3.9). Authorization checked against session's cached RBAC grants.	MVP

P3.2 Context Version Control

Item	Description	Release
P3.2.1	Auto-versioning on every context mutation (content-addressed SHA-256 hash, stored in context_versions table)	MVP
P3.2.2	Named snapshots (before critical operations, per workflow step, manually triggered by L3+)	MVP
P3.2.3	Context diffing (compare any two versions, show added/removed/modified context entries)	V1.1
P3.2.4	Context rollback (restore any previous version, L3+ required, recorded in audit log)	MVP
P3.2.5	Context branching (parallel exploration with different context, for experimental workflows)	V2
P3.2.6	Context merging (combine branches with conflict resolution, human review required for conflicts)	V2
P3.2.7	Full audit trail (who changed what, when, why -- linked to workflow step)	MVP

P3.3 Immutable Agent Context

Item	Description	Release
P3.3.1	4-layer enforcement: Layer 1 Platform Rules (hardcoded), Layer 2 Tenant Policies (L5 set), Layer 3 Team Guidelines (L3+ set), Layer 4 Agent Persona (set at creation)	MVP
P3.3.2	Injected as system prompt prefix before every agent LLM interaction (concatenated in order: L1+L2+L3+L4)	MVP
P3.3.3	Validation layer (blocks any attempt to override at runtime via prompt injection detection)	MVP
P3.3.4	Violation logging and agent operation termination (agent killed if immutable context violation detected)	MVP
P3.3.5	Layer management UI (L5 edits tenant policies, L3+ edits team guidelines, agent persona set at creation and locked)	MVP
P3.3.6	Blacklist-based action model -- Agents operate under a "default allow" policy. An agent may perform any action available through its tool access list (P2.3.2) UNLESS a guardrail explicitly prohibits it. Guardrails define what agents CANNOT do, not what they can do. This is the inverse of a whitelist model. Tool access (which tools are available) is separate from action guardrails (which behaviors are prohibited).	MVP
P3.3.7	Guardrail definition format -- Each guardrail is a structured rule with: (a) scope (platform/tenant/team/agent), (b) condition (when does this rule apply -- always, or contextual trigger), (c) prohibited action or behavior (what the agent must not do), (d) violation response (warn, block, terminate, escalate to human). Guardrails are stored in config DB and fetched during session initialization. Format is schema-validated.	MVP
P3.3.8	Self-context immutability for agents -- An agent CANNOT modify its own role definition, system prompt, guardrails, or clearance level. Any attempt to self-modify is blocked, logged as a security event, and optionally triggers session termination. This applies to all modification vectors: direct DB write, API call, tool invocation, or LLM-generated instruction.	MVP
P3.3.9	Hierarchical context editing -- An agent's context (role definition, guardrails, scope, tool access) can only be edited by: (a) the human user at or above the agent's level, or (b) the agent's direct parent in the agent hierarchy. Edits flow DOWNWARD only -- an agent cannot edit a peer's or parent's context. Example: Product Manager can edit Architect's scope; Architect can edit Backend-SME's scope; Backend-SME cannot edit its own or Architect's scope.	MVP
P3.3.10	Agent hierarchy definition -- Agents are organized in a tree structure that defines the chain of trust for context editing. Default hierarchy: Human (root), Product Manager, Principal Architect, then Backend-SME, Frontend-SME, QA-Engineer, DevOps-Engineer. The hierarchy is configurable per tenant. Hierarchy changes require human (L4+) approval. The hierarchy is stored in config DB and included in session initialization.	MVP
P3.3.11	Chain of trust enforcement -- All context edits are validated against the agent hierarchy before being applied. The system enforces: (a) no self-edits to own context, (b) no lateral edits to peer agents, (c) no upward edits to parent agents, (d) only downward edits to direct children. Every context edit is logged with: editor_id, target_agent_id, field_changed, old_value_hash, new_value_hash, timestamp. Violations are logged as security events and blocked.	MVP
P3.3.12	Runtime guardrail enforcement at MCP transport layer [BOOTSTRAP] -- All tool calls and tool results pass through a policy enforcement point before reaching the LLM or external system. Guardrail rules (P3.3.7) are evaluated against actual tool invocation parameters, not just system prompt instructions. Defense-in-depth independent of LLM compliance.	MVP

P3.4 Persistent Agent Memory

Item	Description	Release
P3.4.1	Object storage backend (per-tenant prefix, per-agent subfolder, object versioning enabled)	MVP
P3.4.2	Memory types: conversation context (per-workflow), learned knowledge (persistent), team preferences (persistent), work artifacts (90-day retention)	MVP
P3.4.3	Per-tenant isolation (separate storage paths per tenant per agent)	MVP
P3.4.4	Versioning with named snapshots (before major learning cycles, configurable)	MVP
P3.4.5	Rollback to any version (L4+ required, logged to audit trail)	V1.1
P3.4.6	Configurable retention policies (30/90/365 days/indefinite, per memory type, per tenant)	V1.1
P3.4.7	S3-compatible backend for on-premise deployments	V2

P3.5 RAG Knowledge Bases

Item	Description	Release
P3.5.1	Vector store per knowledge domain (per tenant schema)	MVP
P3.5.2	Domain knowledge RAG (industry-agnostic: tenant uploads documents, policies, procedures, playbooks -- automatically chunked, embedded, and indexed. Examples: codebase for engineering, candidate database for recruitment, case files for legal, product catalog for sales)	MVP
P3.5.3	Specialized RAG domains (per-tenant configurable: code, infrastructure, product, security, design, HR policies, compliance regulations, market data, client history -- tenant creates domains relevant to their industry)	V1.1
P3.5.4	Clearance-gated access (which agents can access which knowledge bases, per RBAC)	MVP
P3.5.5	MCP-exposed endpoints (agents access knowledge via MCP tools: search, get_context, find_similar)	MVP
P3.5.6	Update triggers (webhooks, doc updates, configurable schedule)	MVP
P3.5.7	Deduplication within knowledge base (content hash check before insert)	V1.1
P3.5.8	Cross-tenant contamination prevention (GAP FILL: RAG queries always scoped to tenant, embedding model never trained on cross-tenant data, automated isolation tests)	MVP
P3.5.9	Tenant self-service knowledge upload (web UI for L3+ to upload documents: PDF, DOCX, CSV, TXT, Markdown -- auto-processed into RAG domain, progress indicator, preview of extracted content)	MVP
P3.5.10	Industry knowledge base templates (pre-built RAG domains per industry template: recruitment laws per country, sales playbooks, compliance checklists -- downloadable and customizable)	V1.1

17. PRIORITY 4 -- WORKFLOW & GOVERNANCE

P4.1 Workflow Engine

Item	Description	Release
P4.1.1	Workflow tracking (every workflow tracked in platform DB; optionally mirrored to external systems: SCM issue for engineering, email thread for non-technical, messaging channel for collaborative teams -- configurable per tenant)	MVP
P4.1.2	Workflow state machine (pending, in_progress, waiting_approval, approved, next_step / rejected, redo -- stored in database with cache layer)	MVP
P4.1.3	Multi-step workflow execution (step to agent assignment to execution to output to approval gate to next step)	MVP
P4.1.4	Sub-task creation by agents (tracked in platform DB; optionally mirrored to external system: SCM child issues, messaging threads, email updates -- per tenant config)	MVP
P4.1.5	Progress updates posted to configured channel (web dashboard always, plus: SCM issue comments, messaging, email digests -- per tenant preference)	MVP
P4.1.6	Parallel step execution (independent steps run concurrently, join when all complete)	V1.1
P4.1.7	Workflow templates (reusable patterns for common tasks, stored in config DB)	V1.1
P4.1.8	Workflow cancellation (L3+ can cancel, agents gracefully stopped, tracking issue closed)	MVP
P4.1.9	Workflow rollback (revert to previous step, re-execute from that point)	V1.1
P4.1.10	In-flight workflow recovery (GAP FILL: on agent instance death, workflow engine detects via heartbeat timeout, reassigns step to new agent instance, resumes from last checkpoint)	MVP
P4.1.11	Stuck workflow detection and remediation (GAP FILL: if a workflow step has not progressed in 2x its SLA, alert L3+ and offer: reassign agent, restart step, escalate to human)	V1.1
P4.1.12	Industry workflow templates (pre-built workflow patterns per industry: recruitment pipeline, sales funnel, legal case management, content production, customer onboarding -- selectable from Industry Template Library)	MVP
P4.1.13	Visual workflow builder (drag-and-drop workflow creation for non-technical users: define steps, assign agent roles, set approval gates, configure notifications -- no code required)	MVP
P4.1.14	Workflow cloning (clone an existing workflow template, customize steps and agents, save as new template for reuse)	MVP

P4.2 External Integration Adapters

SCM integration is optional, not required. Non-technical tenants use the web dashboard, email, and messaging as their primary workflow substrate. SCM adapters are available for engineering teams.

Item	Description	Release
P4.2.1	GitHub adapter (issues, PRs, comments, CI integration, webhook receivers -- for engineering tenants)	MVP
P4.2.2	GitLab adapter (issues, MRs, comments, CI/CD triggers, webhook receivers -- for engineering tenants)	V1.1
P4.2.3	Approval via external channels (multi-channel: SCM comment, email reply, messaging button click, web dashboard button -- tenant configures preferred channel)	MVP
P4.2.4	Agent output posted to configured channel (SCM comments for engineering, email summaries for non-technical, messaging for collaborative, web dashboard always)	MVP
P4.2.5	Webhook receivers (issue events, PR events, comment events, with signature verification)	MVP
P4.2.6	Branch management (agents create feature branches, submit PRs, configurable naming convention -- engineering tenants only)	MVP
P4.2.7	Adapter interface (abstract integration interface for all external systems: SCM, email, messaging, CRM, project management)	MVP
P4.2.8	Email adapter (send workflow updates, receive approval replies, parse structured responses -- for tenants who work primarily via email)	MVP
P4.2.9	Messaging adapter (post workflow updates to channels, receive approval via interactive buttons, thread-based workflow tracking)	V1.1
P4.2.10	Web portal adapter (default for all tenants: built-in workflow tracking, approval buttons, progress feeds, notifications -- requires no external tool setup)	MVP
P4.2.11	Project management adapter interface (abstract interface for Jira, Asana, Monday.com, Trello -- implementations in V1.1/V2)	V1.1
P4.2.12	SCM credential vault — `scm_credentials` table with per-member credential storage (PAT or GitHub App); encrypted payload; member/team/org scope; status lifecycle	MVP ✅
P4.2.13	PAT credential mode — GitHub personal access token storage + validation via GitHub `/user`; expiry tracking with 7d/1d warnings	MVP ✅
P4.2.14	GitHub App credential mode — app_id + installation_id + encrypted PEM; on-demand ~1hr installation token generation (no long-lived tokens stored)	MVP ✅
P4.2.15	Credential resolution chain — member → team → org fallback lookup; replaces legacy `VaultGetter.GetKey` in SCM MCP servers	MVP ✅
P4.2.16	Credential health monitor — 7d/1d expiry alerts; HTTP 401 auto-revoke; `/internal/credential-health` endpoint	MVP ✅
P4.2.17	Client portal credential management page — CRUD with masked tokens + status badges; visibility scoping (org admin vs member)	MVP ✅
P4.2.18	Credential access audit logging — full lifecycle (store, retrieve, rotate, revoke) via Wave 1 hash chain	MVP ✅
P4.2.19	GitLab SCM credential support (PAT mode only; OAuth deferred to V2)	V1.1

P4.3 Approval Chain Engine

Item	Description	Release
P4.3.1	5-level override hierarchy (Platform Policy, Tenant Policy, Parent Team, Sub-Team, Per-Request -- highest priority wins)	MVP
P4.3.2	Approval templates: dev-only, dev+review, full-pipeline, critical-path (as defined in data model)	MVP
P4.3.3	Request initiator selects stakeholders who mandate downstream approvals	MVP
P4.3.4	Effective chain computation (merge all levels, highest priority wins, no weakening below locked level)	MVP
P4.3.5	Multi-channel approval recording (web dashboard button, email reply link, messaging interactive button, SCM issue comment -- all channels validated, recorded in audit log, advance workflow)	MVP
P4.3.6	Approval status tracking per workflow step (pending/approved/rejected with timestamps)	MVP
P4.3.7	Approval timeouts (GAP FILL: configurable per template -- default 24h for dev, 72h for critical-path, escalation on timeout: notify approver's manager, then auto-delegate to backup approver)	V1.1
P4.3.8	Approval delegation (GAP FILL: approver can delegate to another qualified user, delegation recorded in audit log, delegatee must have >= required clearance)	V1.1
P4.3.9	Approval revocation (GAP FILL: L4+ can revoke a previously granted approval, workflow step re-enters waiting_approval, all stakeholders notified)	V1.1
P4.3.10	Consensus breaking (GAP FILL: when multiple approvers are required and they disagree, configurable strategy: majority wins, unanimous required, escalate to L4+)	V2
P4.3.11	One-click approval for non-technical users (email contains a secure, time-limited approval link -- click to approve/reject with optional comment, no login required for single-action approval, link signed with HMAC)	MVP
P4.3.12	Approval via mobile push notification (push notification with approve/reject action buttons, for users who have the mobile app or PWA installed)	V1.1

P4.4 Change Guard (Dedup & Conflict Detection)

Item	Description	Release
P4.4.1	Step 1: Semantic search across RAG stores (similar existing work detection)	MVP
P4.4.2	Step 2: Historical work scan (for engineering: version control history, commits, MRs; for non-technical: past workflow outputs, completed tasks, document versions -- adapter-based per tenant type)	MVP
P4.4.3	Step 3: Active workflow check (cross-team conflicting work detection)	MVP
P4.4.4	Step 4: Dependency analysis (for engineering: downstream service impact; for non-technical: affected clients, pending deals, related workflows -- domain-agnostic impact graph)	V1.1
P4.4.5	Step 5: Risk assessment (blast radius, reversibility score)	V1.1
P4.4.6	Step 6: Notify and gate (block if score > threshold, notify via configured channels)	MVP
P4.4.7	Conflict levels: Info (log), Warning (pause, notify), Block (require human override)	MVP
P4.4.8	Human override recorded on configured channel (SCM issue, web dashboard, email thread -- per tenant config)	MVP

P4.5 Clearance & RBAC System

Item	Description	Release
P4.5.1	5-level clearance hierarchy (L1 Observer, L2 Contributor, L3 Team Lead, L4 Director, L5 Admin)	MVP
P4.5.2	18+ granular permissions (as defined in data model: agent:, workflow:, team:, rbac:, clearance:*)	MVP
P4.5.3	Per-resource scoping (permissions scoped to team, sub-team, or specific agent)	MVP
P4.5.4	Role templates (clearance level maps to default permission set, as defined in ROLE_TEMPLATES)	MVP
P4.5.5	Permission grant/revoke with audit trail (who granted what to whom, when)	MVP
P4.5.6	Clearance change restricted to L4+ with team access	MVP
P4.5.7	Middleware enforcement on every API call (permission check before handler execution)	MVP
P4.5.8	Permission caching (invalidate on grant/revoke, TTL 5 minutes)	MVP

P4.6 Central Configuration Database

Item	Description	Release
P4.6.1	Hierarchical namespaces (platform/ to tenant/{id}/ to team/{id}/ to agent/{id}/ to workflow/ to security/)	MVP
P4.6.2	Cascading inheritance (platform to tenant to team to agent, lower overrides higher unless locked)	MVP
P4.6.3	Full version history with diffs per config change	MVP
P4.6.4	Agent-proposed config changes require human approval via configured channel	V1.1
P4.6.5	Config change notification via pub/sub (config change published to tenant-scoped channel; running agent sessions continue on their frozen snapshot per P0.3.12; new sessions initialize with updated config; agents may receive 'critical update' signal triggering graceful session termination and restart with new config; agents may also explicitly refresh via /pull-context per P3.1.13)	MVP
P4.6.6	Config validation schemas per namespace (validated on write)	MVP

P4.7 Priority & SLA Management

Item	Description	Release
P4.7.1	Priority levels: P0 (4h), P1 (24h), P2 (72h), P3 (168h), P4 (backlog)	MVP
P4.7.2	ETA tracking per workflow and per step	MVP
P4.7.3	Cascading notification engine (2h "Set ETA", 80% "Approaching", Exceeded notify manager, 2x escalate to lead, SLA breach escalate to director)	V1.1
P4.7.4	SLA breach blocks dependent workflows	V1.1

P4.8 Agent Runtime Optimisation & Security Hardening

Status: All 8 items DELIVERED across 5 waves (2026-04-13 to 2026-04-15). Parent tracker: GitHub issue #380. 24 LLDs shipped. 301 pen-test scenarios passing under -race. 71 issues closed on milestone 9.

Delivered under PRD #380 to close gaps identified in the 2026-04-14 PM capability & security review. This section supersedes the items captured in issue #380; table below is the canonical record.

Item	Description	Wave	Release	Key PRs
P4.8.1	Agent-to-agent delegation primitive — runtime `delegate_to_agent` tool with role-based target selection; child sessions inherit clamped clearance via `min(parent, role.inherent, tenant.ceiling)`; per-session cycle detection; fan-out=8 / depth=5 / tree=64 quotas; approval-gated spawning	3	MVP ✅	#439, #449, #452
P4.8.2	Sub-agent session propagation — `parent_session_id` + `root_session_id` + `delegation_depth` on sessions; `subagent_invocations` bridge with dual-hash anchors; cascade termination DFS-post-order; orphan sweeper; single-replica coordinator	3	MVP ✅	#438, #440, #446
P4.8.3	Approval Chain Engine — policy-driven approval routing; 10s scheduler tick; first-write-wins CAS; advisory-lock singleton; dispatch channels (dashboard + email for v1, Slack + SCM deferred to 2.1 per founder decision)	2	MVP ✅	#422, #423
P4.8.4	Pause/Resume API — message-boundary pause (never mid-operation); system-role operator input injection (not forgeable by prior user messages); streaming keepalive during operator pause; rendezvous-and-deliver on resume	2	MVP ✅	#421, #446
P4.8.5	Named Hook Points SDK — 4 named hooks (`on_session_start`, `pre_llm_call`, `post_tool_call`, `on_error`); strict-disjoint annotation namespaces; 3-panic-per-session auto-disable; Python→Go gRPC bridge with p95 <3ms; `v0alpha1` proto tag for internal-only mutability	4A	MVP ✅	#468, #471, #480
P4.8.6	Agent Isolation — MCP tool parameter schema validation (soft→hard rollout gated on 99% coverage over 14d); per-tenant egress allow-list with RFC1918 + cloud-metadata IP block + DNS-rebinding defense; JWT replay protection via Redis jti cache (2-phase rollout); audit log hash-chaining with epoch clean-break semantics	1	MVP ✅	#387, #393, #397, #402, #407, #408, #410, #411
P4.8.7	Enterprise Compliance — data-class registry (55 scopes: 47 PG + 3 Vault + 3 Redis + 2 S3) with CI coverage lint; RTD engine 4-phase state machine (purge → verify → redact → certify) with strict dual-control + 72h attestation window; retention policy with clamp model (tenant can tighten but not loosen platform floor); SIEM export (OCSF v1.2, HMAC, at-least-once + idempotency key, circuit breaker); SBOM generation (CycloneDX + SPDX) via Syft in CI	4B	MVP ✅	#469, #477, #482, #483
P4.8.8	ML-Layer Detection — jailbreak classifier (Python sidecar with Prompt-Guard-86M; shadow → warn → enforce rollout with per-tenant pin; fail-open with loud metric); content moderation via OpenAI Moderation API (13 categories, 3 pipeline surfaces, circuit breaker, HTTPS-only); tool execution sandboxing (AppArmor + seccomp deny-list + readOnlyRootFS + runAsNonRoot + GKE Autopilot fallback)	5	MVP ✅	#492, #494, #490

Release sequencing (as delivered)

Wave	Scope	LLDs	QA pen-test scenarios	Sign-off
1	Agent Isolation	4 + 4 operational	30/30	2026-04-14
2	Approval Chain + Pause/Resume	5	69/69	2026-04-14
3	Agent Delegation + Session Propagation	5 + 3 supporting	78/78	2026-04-15
4	Hook SDK + Enterprise Compliance	7	77/77 + 1 skip	2026-04-15
5	ML Detection	3	47/47 + 2 skip	2026-04-15
Total	5 waves	24 LLDs	301 scenarios	—

Process gates adopted during delivery

Shelfware gate (docs/retrospectives/2026-04-15-shelfware-pattern.md) — added after Wave 3 retrospective. Every backend PR must include a ## Production callers grep section; architect runs independent grep before APPROVE. Result: 0 shelfware REQUEST_CHANGES in Waves 4–5 vs 6 in Waves 1–3.
Proto-sync CI gate (GitHub issue #473) — clean-checkout buf generate + git diff --exit-code runs on every go test ./.... Prevents the missing-generated-file class of main-breakage bug permanently.
Founder-delegation audit trail — all open-question decisions made during founder absence captured as comments on the parent PRD issue (#380) for post-hoc review.

Security moat (delivered positioning)

UpsQuad's agent runtime now ships the following capabilities that distinguish it from LangGraph / OpenAI Assistants / Anthropic tool use / Vercel AI SDK / CrewAI / AutoGen:

5-level clearance × 3-layer governance intersection with policy override ceilings (platform policy cannot be downgraded by tenant policy)
Governed MCP wrappers — every third-party MCP server runs behind a policy enforcement point
Immutable provenance chain with hash verification; GetProvenanceChain(cross_session=true) walks parent-child trees
Per-tenant BYOK vault with pgcrypto encryption + memory-zeroed passphrases
L1-L4 prompt integrity hash verification for system-role instructions
Agent-to-agent delegation with clearance propagation + quotas — not shelfware; actually runtime-capable
Approval chain with runtime pause/resume + dual-control — HITL governance for sensitive actions
Hook SDK with panic isolation + strict namespace disjoint — customer integrations can't collide or crash sessions
Data-class registry with CI coverage — every tenant-data store has an explicit deleter/redactor; new migrations fail CI if unregistered
Right-to-deletion engine with strict dual-control + 72h attestation + hash-chained certificates + aggregate-retention for tax-required data
SIEM export (OCSF v1.2) with HMAC + idempotency + circuit breaker — customer SOC integration
ML jailbreak + content moderation layered over regex filters — defense in depth
Container-level sandboxing with AppArmor + seccomp deny-list — agent-worker cannot ptrace/mount/bpf

18. PRIORITY 5 -- AGENT COLLABORATION

P5.1 A2A (Agent-to-Agent) Protocol

Item	Description	Release
P5.1.1	Agent discovery (Agent Cards describing skills and endpoints, registered on agent start)	MVP
P5.1.2	Task delegation with structured payloads (inter-agent communication within tenant namespace)	MVP
P5.1.3	Status streaming between agents	MVP
P5.1.4	Artifact exchange (code, docs, data shared via object storage with signed URLs)	V1.1
P5.1.5	Multi-turn collaboration (agents negotiate and iterate on complex tasks)	V1.1
P5.1.6	Clearance-gated communication (agents can only communicate with authorized peers per RBAC)	MVP

P5.2 Consensus System

Item	Description	Release
P5.2.1	Multi-agent validation for critical decisions (configurable: which decisions require consensus)	V1.1
P5.2.2	Configurable quorum (e.g., 2/3 agents must agree)	V1.1
P5.2.3	Resolution strategies: majority vote, weighted by competency, human escalation	V1.1
P5.2.4	Human escalation when consensus fails	V1.1
P5.2.5	Consensus results logged to audit trail	V1.1

P5.3 Agent-Human Mapping

Item	Description	Release
P5.3.1	Each human user mapped to specific teams and agents (as defined in tenant.users[].teams)	MVP
P5.3.2	Human as reviewer/approver for assigned agents	MVP
P5.3.3	Clearance-based access enforcement	MVP
P5.3.4	Manager (L3+) controls mapping	MVP
P5.3.5	Notifications routed to mapped human	MVP

19. PRIORITY 6 -- USER EXPERIENCE

P6.1 Human-Agent Chat Interface

Item	Description	Release
P6.1.1	1:1 chat with any authorized agent (WebSocket-based, real-time streaming responses)	MVP
P6.1.2	Thread-per-workflow (tied to tracking issue, context maintained)	MVP
P6.1.3	Rich output: code blocks with syntax highlighting, diffs, file attachments	MVP
P6.1.4	Slash commands: /approve, /reject, /escalate, /set-priority, /status	MVP
P6.1.5	Approval actions embedded in chat (inline approve/reject buttons)	MVP
P6.1.6	Real-time streaming responses (token-by-token display)	MVP
P6.1.7	Chat history persisted in agent memory (versioned)	MVP
P6.1.8	Group chat with multiple agents (cross-team coordination)	V1.1
P6.1.9	Slash commands: /set-eta, /handoff, /config	V1.1
P6.1.10	Context management slash commands -- /push-context: saves agent's accumulated session knowledge to external memory store. /pull-context: fetches latest context and creates new immutable session snapshot. Both commands display confirmation with version info (e.g., "Context pushed: v47, memory store" or "Context pulled: snapshot v12, v13"). Commands available to all agents and authorized users.	MVP

P6.2 Role-Based Dashboards

Item	Description	Release
P6.2.1	L1 Observer dashboard: read-only workflow and activity feeds	MVP
P6.2.2	L2 Contributor dashboard: my agents, my workflows, cost tracker	MVP
P6.2.3	L3 Team Lead dashboard: team overview, pending approvals, agent health, configs	MVP
P6.2.4	L4 Director dashboard: cross-team analytics, budget vs actual, SLA tracker, audit log	MVP
P6.2.5	L5 Admin dashboard: tenant health, all teams, security alerts, configuration management	MVP
P6.2.6	Widget framework (composable dashboard components)	V1.1
P6.2.7	Per-user customizable layout (widget drag-and-drop, layout persistence)	V2

P6.3 Onboarding Flow (Industry-Aware)

Onboarding must work for any industry and any technical skill level. A recruitment company owner with zero technical background should be able to go from signup to a running agent team in under 10 minutes.

Item	Description	Release
P6.3.1	Tenant signup flow (company name, admin email, plan selection, auth registration)	MVP
P6.3.2	Industry-aware questionnaire (Step 1: "What industry is your company in?" with predefined list + "Other". Step 2: "What does your team do day-to-day?" free text. Step 3: "How many people on your team?" Step 4: "What tools do you currently use?" with common options per industry)	MVP
P6.3.3	AI-powered team suggestion (based on questionnaire answers, the platform uses an LLM to suggest an agent team structure: role names, descriptions, recommended tools, and workflow templates -- e.g., recruitment company suggests Sourcer, Screener, Outreach Specialist, Compliance Checker, Interview Coordinator)	MVP
P6.3.4	Estimated cost breakdown before deployment (show monthly cost estimate based on suggested team, usage projection, and selected plan tier)	MVP
P6.3.5	One-click deployment of suggested team (accept the suggestion and platform provisions all agents with pre-configured roles, tools, and a starter workflow -- tenant is immediately operational)	MVP
P6.3.6	Guided tour (tooltips walking new users through key features, adapted to industry: engineering tour shows SCM integration, recruitment tour shows candidate pipeline)	V1.1
P6.3.7	Natural language team builder (alternative to questionnaire: user describes their business in plain English, LLM parses and suggests agent team -- "I run a 5-person recruitment agency that places IT professionals in Europe" maps to full team suggestion)	MVP
P6.3.8	Industry template gallery (browsable gallery of pre-built team templates with descriptions, role breakdowns, and example workflows -- user can select, preview, and deploy)	MVP
P6.3.9	Tool connection wizard (after team deployment, guided setup to connect tenant's existing tools: "Connect your email", "Connect your CRM", "Connect your calendar" -- OAuth flows where possible, API key input where not)	MVP
P6.3.10	First-workflow walkthrough (after team is deployed and tools connected, automatically create a sample workflow and walk the user through: trigger it, see agents work, approve a step, see the output -- industry-specific example)	MVP

P6.4 Client Interfaces

Item	Description	Release
P6.4.1	Web Dashboard (primary interface -- app.upsquad.ai)	MVP
P6.4.2	REST API with OpenAPI 3.1 spec (auto-generated docs at docs.upsquad.ai)	MVP
P6.4.3	CLI Tool (developer workflow integration: usq agent list, usq workflow create, usq chat)	V1.1
P6.4.4	TypeScript SDK (npm package)	V1.1
P6.4.5	Python SDK	V2
P6.4.6	GitHub App (native extension for approval flows)	V1.1
P6.4.7	Webhook support for external integrations (configurable per tenant, signed payloads)	V1.1

20. PRIORITY 7 -- COST & MEASUREMENT

P7.1 Cost Engine

Item	Description	Release
P7.1.1	Real-time cost tracking per LLM call (tokens * price, stored per call)	MVP
P7.1.2	Hierarchical aggregation: agent to team to department to tenant	MVP
P7.1.3	Per-agent pricing models (industry-agnostic: per-token, per-task, per-session, per-document, per-query, per-deliverable -- configurable per agent role. Examples: per-candidate-screened for recruitment, per-contract-drafted for legal, per-lead-qualified for sales, per-code-review for engineering)	MVP
P7.1.4	Budget limits with auto-pause at thresholds (80% alert, 100% pause, L4+ can override)	MVP
P7.1.5	Cost forecasting based on usage trends (linear projection, weekly/monthly)	V1.1
P7.1.6	Volume discounts (cheaper per-unit as usage scales up, configured per tier)	V1.1
P7.1.7	Cost comparison reports (agent cost vs estimated human baseline)	V2

P7.2 Agent Performance Measurement

Item	Description	Release
P7.2.1	Task completion rate and quality scores (per agent, per team)	V1.1
P7.2.2	Human approval rate (% approved first time vs rejected, per agent)	MVP
P7.2.3	Response time and throughput metrics (time to first output, total execution time)	MVP
P7.2.4	Context efficiency score (tokens used vs context window capacity)	V1.1
P7.2.5	Agent competency tracking (L1-L5 progression over time)	V2
P7.2.6	Regression detection (alert when agent approval rate drops > 10% over 7 days)	V1.1

P7.3 Compliance & Audit Agent

Item	Description	Release
P7.3.1	Automated compliance monitoring agent (verifies immutable context rules are followed)	V1.1
P7.3.2	Violation flagging and human escalation	V1.1
P7.3.3	Compliance report generation (GDPR data processing report, access audit report)	V1.1
P7.3.4	External audit log export (structured JSON, filterable by date/tenant/resource type)	V1.1
P7.3.5	SOC 2 evidence collection automation	V2

21. PRIORITY 8 -- INTELLIGENCE & OPTIMIZATION

P8.1 Optimization Engine

Item	Description	Release
P8.1.1	Detect under-optimized agent configurations (model too powerful for simple tasks)	V1.1
P8.1.2	Suggest better model/compaction/learning settings	V1.1
P8.1.3	Flag context overload (agent approaching token limits inefficiently)	V1.1
P8.1.4	Cost optimization suggestions (cheaper models for simple tasks)	V1.1
P8.1.5	Identify idle agents that can be scaled down	V1.1
P8.1.6	Recommend team structure changes based on usage patterns	V2

P8.2 Feedback & Learning Loop

Item	Description	Release
P8.2.1	Human feedback on agent outputs (approve/reject/rate 1-5/comment, stored per output)	MVP
P8.2.2	Automated quality scoring per output (based on approval rate, revision count)	V1.1
P8.2.3	Feed scores into continuous learning pipeline	V1.1
P8.2.4	Track agent improvement over time (quality score trend per agent)	V1.1
P8.2.5	A/B testing for agent configurations (split traffic between two configs, measure quality)	V2

P8.3 Continuous Learning Pipeline

Item	Description	Release
P8.3.1	Configurable frequency per agent (real-time/hourly/daily/weekly, based on tier limits)	MVP
P8.3.2	Sources: RAG stores, approved outputs, human feedback, version history	MVP
P8.3.3	Learning scoped to team/tenant (zero cross-tenant leakage, verified by isolation tests)	MVP
P8.3.4	Rollback learning if quality degrades (GAP FILL: automated quality regression detection triggers automatic rollback to previous learning state, alert L3+)	V1.1
P8.3.5	Learning job scheduling (scheduled jobs or triggered by webhook/events)	MVP
P8.3.6	Cross-tenant contamination prevention (GAP FILL: learning pipeline never accesses data outside tenant scope, automated penetration tests verify this, learning data stored with tenant_id tag, queries always filter by tenant_id)	MVP
P8.3.7	Learning audit trail (what was learned, from which sources, when, quality impact)	V1.1

22. PRIORITY 9 -- BUSINESS & MONETIZATION

P9.1 Pricing & Billing

Item	Description	Release
P9.1.1	Payment provider integration: products, prices, subscriptions (dual billing model: seat-based for copilots + hourly for agent teams)	MVP
P9.1.2	Feature gates per tier (max agents, max users, max workflows, learning frequency min)	MVP
P9.1.3	Usage-based metering (agent hours, LLM tokens, storage GB -- reported to payment provider as metered usage)	MVP
P9.1.4	Payment webhook handler (GAP FILL: invoice.paid, invoice.payment_failed, subscription.updated, subscription.deleted, payment_method.attached, charge.dispute.created)	MVP
P9.1.5	Invoice generation (payment provider-hosted invoices, accessible from dashboard)	MVP
P9.1.6	Payment retry / dunning process (GAP FILL: failed payment triggers retry after 3 days, retry after 7 days, final notice, suspend tenant after 14 days, delete after 30 days of suspension, each step sends email notification)	V1.1
P9.1.7	Tax calculation (GAP FILL: automatic tax calculation for GST/VAT compliance)	V1.1
P9.1.8	Volume discount tiers (pricing breakpoints at usage thresholds)	V1.1
P9.1.9	Free trial (14 days, Starter tier limits, no credit card required, convert to paid at trial end)	MVP
P9.1.10	Billing portal (self-service: update payment method, view invoices, change plan)	MVP
P9.1.11	India-specific payment gateway integration (for Indian customers)	V2

P9.2 Tenant Management (Platform Admin)

Item	Description	Release
P9.2.1	Tenant provisioning / deprovisioning (automated via signup flow + admin manual override)	MVP
P9.2.2	Plan upgrades / downgrades (immediate upgrade, end-of-period downgrade, proration via payment provider)	MVP
P9.2.3	Usage analytics per tenant (agents, workflows, LLM tokens, storage, cost)	MVP
P9.2.4	MRR/ARR tracking (real-time calculation from subscriptions + metered usage)	MVP
P9.2.5	Churn monitoring (trial expiry tracking, usage decline detection, payment failure tracking)	V1.1
P9.2.6	Tenant health scoring (composite score: usage trend, payment status, support tickets, feature adoption)	V1.1

P9.3 SSO & Enterprise Features

Item	Description	Release
P9.3.1	SAML SSO integration (enterprise identity providers)	V1.1
P9.3.2	OIDC SSO integration	V1.1
P9.3.3	Custom deployment (dedicated cluster for enterprise tenants)	V2
P9.3.4	Data residency guarantees (tenant data stays in selected region: US, EU, AP)	V1.1
P9.3.5	Custom SLA contracts (enterprise-specific SLA terms, stored in config DB)	V2
P9.3.6	Dedicated support channels (messaging, email alias per enterprise tenant)	V2

23. CROSS-CUTTING CONCERN: PLATFORM CONSOLE

The Platform Console is a separate admin interface at console.upsquad.ai, accessible ONLY to founders (Vaisakh + Ashik). It sits above L5 tenant admin and provides god-mode visibility across all tenants.

PC.1 Console Authentication & Authorization

Item	Description	Release
PC.1.1	Separate auth context: "Platform Operator" role, hardcoded to founder user IDs, cannot be granted via RBAC	MVP
PC.1.2	MFA mandatory for console access (hardware key preferred)	MVP
PC.1.3	Console access audit log (every console action logged with IP, timestamp, action)	MVP
PC.1.4	Session timeout: 1 hour idle, 8 hour maximum	MVP

PC.2 All-Tenant Monitoring

Item	Description	Release
PC.2.1	Tenant list view (all tenants with: name, plan, MRR, agent count, user count, region, health score, status)	MVP
PC.2.2	Tenant detail drill-down (full visibility into any tenant: teams, agents, workflows, users, configs, audit logs -- read-only by default)	MVP
PC.2.3	Cross-tenant search (find any user, agent, workflow across all tenants)	V1.1
PC.2.4	Tenant impersonation (act as any L5 admin for support purposes, logged to audit trail with reason required)	V1.1

PC.3 Usage Metering Dashboard

Item	Description	Release
PC.3.1	Real-time platform-wide metrics: total agents running, total workflows active, total LLM calls/min, total cost/hour	MVP
PC.3.2	Per-tenant usage breakdown: agent hours, LLM tokens (input/output), storage GB, API calls, workflows completed	MVP
PC.3.3	Usage trend charts (daily/weekly/monthly, per tenant and aggregate)	MVP
PC.3.4	Tier limit monitoring (which tenants are approaching their plan limits, auto-upgrade suggestions)	V1.1
PC.3.5	LLM provider cost tracking (what UpSquad pays to LLM providers vs what tenants pay UpSquad -- margin visibility)	MVP

PC.4 Financial Dashboard

Item	Description	Release
PC.4.1	MRR/ARR display (current, trailing 3/6/12 months, growth rate)	MVP
PC.4.2	Revenue by tenant (sortable table: tenant, plan, MRR, LTV, months active)	MVP
PC.4.3	Churn prediction (tenants with declining usage, failed payments, support issues -- risk score)	V1.1
PC.4.4	Gross margin calculation (revenue - LLM costs - infrastructure costs, per tenant and aggregate)	V1.1
PC.4.5	Cohort analysis (retention by signup month)	V2
PC.4.6	Revenue forecasting (linear projection based on current growth + pipeline)	V2

PC.5 Platform Health

Item	Description	Release
PC.5.1	Service health dashboard (all services: status, latency, error rate, instance count)	MVP
PC.5.2	Cluster health (node count, instance count, resource utilization, pending instances)	MVP
PC.5.3	Database health (connection count, query latency, replication lag, storage usage)	MVP
PC.5.4	LLM provider health (latency per provider, error rate, rate limit status)	MVP
PC.5.5	Incident management (create/track incidents, link to affected tenants, communication templates)	V1.1

PC.6 Platform Operations

Item	Description	Release
PC.6.1	Tenant provisioning (manual tenant creation for enterprise deals)	MVP
PC.6.2	Tenant suspension/unsuspension (for payment failure, abuse, maintenance)	MVP
PC.6.3	Feature flag management (enable/disable features per tenant, global feature flags)	MVP
PC.6.4	Platform configuration management (platform-level config DB entries, pricing tier definitions)	MVP
PC.6.5	Broadcast notifications (send announcement to all tenants or selected tenants)	V1.1
PC.6.6	Data export for tenant (generate GDPR-compliant data export package on request)	V1.1

24. CROSS-CUTTING CONCERN: SECURITY HARDENING

These items apply across all priorities and must be implemented as part of the relevant services.

SEC.1 Prompt Injection Prevention (GAP FILL: AI-Specific Security)

Item	Description	Release
SEC.1.1	Input sanitization layer (strip known injection patterns from user messages before passing to agents: "ignore previous instructions", "system: ", delimiter attacks)	MVP
SEC.1.2	Immutable context enforcement (system prompt cannot be overridden by user input, validated before every LLM call)	MVP
SEC.1.3	Agent output validation (GAP FILL: validate agent outputs against expected schema per agent type, flag anomalous outputs: SQL injection in code, shell commands in documentation, credential-like strings in any output)	MVP
SEC.1.4	Output filtering (remove any leaked system prompts, API keys, or PII from agent responses before delivery to user)	MVP
SEC.1.5	Canary tokens in system prompts (detect if agent leaks system prompt contents)	V1.1
SEC.1.6	Adversarial testing harness (automated red team tests: attempt to extract system prompts, bypass immutable context, inject cross-tenant data)	V1.1
SEC.1.7	Declarative output validation specification -- Structured schema language for agent output validation rules. Schemas specify: expected output structure, field-level validators, corrective actions on failure, severity levels. Versioned and stored in config DB per agent role. Tenants (L5) can add custom rules on top of platform defaults.	V1.1

SEC.2 Encryption & Key Management (GAP FILL)

Item	Description	Release
SEC.2.1	Per-tenant Data Encryption Key (DEK) generated on tenant provisioning, stored encrypted by KEK in managed key service	MVP
SEC.2.2	DEK rotation (automatic every 90 days, re-encrypt active data, old DEK retained for historical data decryption)	V1.1
SEC.2.3	BYOK key storage: tenant LLM API keys encrypted with tenant DEK, decrypted only in-memory at LLM call time, never written to logs or agent instance filesystem	MVP
SEC.2.4	TLS everywhere (all inter-service communication over mTLS, external API over TLS 1.3)	MVP
SEC.2.5	Database field-level encryption for: API keys, webhook secrets, BYOK keys, PII fields (email stored hashed for lookup, encrypted for display)	MVP

SEC.3 OWASP Compliance (GAP FILL)

Item	Description	Release
SEC.3.1	Injection prevention (parameterized queries everywhere, no string concatenation for SQL/commands)	MVP
SEC.3.2	Broken authentication prevention (auth provider handles auth, custom clearance layer validates on every request)	MVP
SEC.3.3	Sensitive data exposure prevention (no PII in logs, no secrets in error messages, response headers: X-Content-Type-Options, Strict-Transport-Security, X-Frame-Options)	MVP
SEC.3.4	Input injection prevention (strict schema validation on all API inputs)	MVP
SEC.3.5	CSRF protection (SameSite cookies, CSRF token for state-changing requests)	MVP
SEC.3.6	Security headers on all responses (CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy)	MVP
SEC.3.7	Dependency vulnerability scanning (automated in CI for all language ecosystems)	MVP
SEC.3.8	Container image scanning (vulnerability scanning, block deployment of images with critical CVEs)	MVP

SEC.4 AI Regulatory Compliance (GAP FILL)

Item	Description	Release
SEC.4.1	EU AI Act transparency: clearly disclose to end users when they are interacting with AI agents, not humans	MVP
SEC.4.2	AI decision audit trail: every AI decision logged with: input, model, output, reasoning summary, human oversight status	MVP
SEC.4.3	Human oversight enforcement: no AI agent can take irreversible actions without human approval (enforced by approval chain engine)	MVP
SEC.4.4	Model card documentation: for each supported LLM, document capabilities, limitations, known biases, intended use	V1.1
SEC.4.5	NIST AI RMF mapping: map UpSquad controls to NIST AI RMF categories (Govern, Map, Measure, Manage)	V1.1

25. CROSS-CUTTING CONCERN: NOTIFICATION SYSTEM (GAP FILL)

NOTIF.1 Notification Infrastructure

Item	Description	Release
NOTIF.1.1	Notification service (consumes from event stream notification topic, dispatches to channels)	MVP
NOTIF.1.2	Notification queue (event streaming: notification.events, ordered, persistent, consumer group per channel)	MVP
NOTIF.1.3	Notification deduplication (content hash + recipient + time window, prevent duplicate notifications within 5 minutes)	MVP
NOTIF.1.4	Notification templates (for each notification type: approval_request, workflow_update, sla_warning, etc.)	MVP
NOTIF.1.5	Notification batching (group multiple updates for same recipient within 2-minute window into single notification)	V1.1
NOTIF.1.6	Notification preferences per user (which channels for which notification types, stored in user config)	V1.1

NOTIF.2 Notification Channels

Item	Description	Release
NOTIF.2.1	In-app notifications (WebSocket push to browser, notification bell with count, notification center)	MVP
NOTIF.2.2	Email notifications (HTML templates, unsubscribe link)	MVP
NOTIF.2.3	SCM comments (GitHub/GitLab issue comments for workflow and approval notifications)	MVP
NOTIF.2.4	Messaging integration (post to channel or DM, interactive buttons for approve/reject)	V1.1
NOTIF.2.5	On-call integration (for SLA breaches, platform incidents, critical agent failures)	V1.1
NOTIF.2.6	Webhook delivery (tenant-configurable webhook endpoints, signed payloads, retry with exponential backoff: 1min/5min/15min/1hr, dead letter after 5 failures)	V1.1

26. CROSS-CUTTING CONCERN: TESTING INFRASTRUCTURE (GAP FILL)

TEST.1 Test Framework

Item	Description	Release
TEST.1.1	Unit test framework (standard testing packages for backend and frontend)	MVP
TEST.1.2	Integration test framework (test containers for database/cache, real service-to-service tests)	MVP
TEST.1.3	E2E test framework (browser automation tests against staging environment)	V1.1
TEST.1.4	API contract tests (OpenAPI spec validation, backward compatibility checks in CI)	MVP
TEST.1.5	CI test pipeline (unit tests on every PR, integration tests on merge to main)	MVP

TEST.2 Security & Resilience Testing

Item	Description	Release
TEST.2.1	Cross-tenant isolation tests (automated tests: create 2 tenants, attempt cross-tenant data access, verify rejection -- run in CI)	MVP
TEST.2.2	RBAC permission tests (automated: for each clearance level, verify access to allowed resources and rejection from disallowed)	MVP
TEST.2.3	Prompt injection test suite (automated: run known injection attacks against agent input pipeline, verify all blocked)	V1.1
TEST.2.4	Chaos engineering (fault injection: instance kill, network partition, database failover -- verify system recovers within RTO)	V1.1
TEST.2.5	Load testing (simulate 100 concurrent tenants, 1000 agents, 10000 workflows -- measure latency degradation)	V1.1
TEST.2.6	1M agent scale test (V2 milestone: spin-up of test environment, simulate 1M agents across 10000 tenants, measure infrastructure limits)	V2

TEST.3 Performance Benchmarks

Item	Description	Release
TEST.3.1	API latency benchmarks (P50 < 50ms, P95 < 200ms, P99 < 500ms for non-LLM endpoints)	MVP
TEST.3.2	Agent startup time benchmark (cold start < 10s, warm start < 2s)	MVP
TEST.3.3	Workflow throughput benchmark (100 concurrent workflows per tenant without degradation)	V1.1
TEST.3.4	Context retrieval benchmark (semantic search + assembly < 500ms for 1M context entries)	V1.1

27. CROSS-CUTTING CONCERN: DOCUMENTATION (GAP FILL)

DOC.1 API Documentation

Item	Description	Release
DOC.1.1	OpenAPI 3.1 spec (auto-generated from handlers, served at docs.upsquad.ai)	MVP
DOC.1.2	Interactive API explorer (with "Try it" functionality using test API keys)	MVP
DOC.1.3	Authentication guide (how to get API keys, how to use auth tokens, how to authenticate SDK)	MVP
DOC.1.4	Rate limit documentation (per-tier limits, headers, best practices for handling 429s)	MVP
DOC.1.5	Webhook event reference (all event types, payload schemas, verification instructions)	V1.1

DOC.2 User Documentation

Item	Description	Release
DOC.2.1	Getting started guide -- generic (from signup to first agent running, with screenshots, written for non-technical users)	MVP
DOC.2.1a	Getting started guide -- per industry (industry-specific variants: engineering, recruitment, sales, legal, marketing -- each with relevant examples and screenshots)	MVP
DOC.2.2	Agent configuration guide (how to configure agents, customize roles, connect tools, set up learning -- with industry-specific examples)	MVP
DOC.2.3	Workflow creation guide (how to create workflows, configure approval chains)	MVP
DOC.2.4	RBAC and clearance guide (understanding clearance levels, permissions, how to grant/revoke)	MVP
DOC.2.5	Troubleshooting runbooks (common issues: agent not responding, workflow stuck, approval not advancing, cost spike)	V1.1

DOC.3 Internal Documentation

Item	Description	Release
DOC.3.1	Architecture Decision Records (ADRs, numbered, in source control, template-based)	MVP
DOC.3.2	Service architecture diagram (all services, communication patterns, data flows)	MVP
DOC.3.3	Deployment runbook (how to deploy, rollback, scale, update configurations)	MVP
DOC.3.4	Incident response playbook (severity classification, communication templates, escalation chain, post-mortem template)	MVP
DOC.3.5	On-call procedures (rotation, response time expectations, escalation paths)	V1.1

28. CROSS-CUTTING CONCERN: ERROR HANDLING & RESILIENCE (GAP FILL)

ERR.1 Error Classification & Handling

Item	Description	Release
ERR.1.1	Error taxonomy (transient: network timeout, provider rate limit, instance restart; permanent: invalid config, permission denied, tenant suspended; unknown: unhandled exceptions)	MVP
ERR.1.2	Transient error retry strategy (exponential backoff with jitter: 100ms, 200ms, 400ms, 800ms, 1.6s; max 5 retries; circuit breaker after 10 consecutive failures)	MVP
ERR.1.3	Permanent error handling (immediate failure response with structured error code + human-readable message + remediation hint)	MVP
ERR.1.4	Dead letter queue (event stream for messages that failed all retries, monitored by Platform Console, manual retry capability)	MVP
ERR.1.5	Stuck workflow remediation (GAP FILL: workflow steps stuck > 2x SLA: auto-notification to L3+, dashboard widget showing stuck workflows, one-click actions: restart step, reassign agent, escalate to human, cancel workflow)	V1.1
ERR.1.6	Graceful degradation strategy (if LLM provider down: use fallback; if cache down: serve from DB with higher latency; if one service down: feature-flag dependent features to maintenance mode)	MVP

29. CROSS-CUTTING CONCERN: DISASTER RECOVERY (GAP FILL)

DR.1 Backup & Recovery

Item	Description	Release
DR.1.1	RTO/RPO targets: Tier definition -- Starter: RPO 24h / RTO 8h; Business: RPO 1h / RTO 2h; Enterprise: RPO 15min / RTO 30min	MVP
DR.1.2	Database backup strategy (managed automated daily backups + point-in-time recovery enabled, cross-region backup for Enterprise tier)	MVP
DR.1.3	Object storage versioning (enabled on all agent memory and artifact buckets, lifecycle policy for old versions)	MVP
DR.1.4	Cache backup (snapshots every hour, append-only file for point-in-time recovery)	MVP
DR.1.5	Recovery runbook (step-by-step procedures for: database restore, object storage restore, cache restore, full platform rebuild from IaC)	MVP
DR.1.6	Automated failover for database (HA configuration with automatic failover to standby)	MVP
DR.1.7	Disaster recovery drill (quarterly test: simulate region failure, recover in secondary region, measure actual RTO/RPO)	V1.1
DR.1.8	Multi-region deployment (active-active for Enterprise tenants, active-passive for others)	V2

30. CROSS-CUTTING CONCERN: DATA EXPORT & PORTABILITY (GAP FILL)

EXPORT.1 Data Export

Item	Description	Release
EXPORT.1.1	GDPR data export (per-user: all personal data in machine-readable JSON, downloadable within 30 days of request per GDPR Article 20)	V1.1
EXPORT.1.2	Tenant data export (all tenant data: teams, agents, configs, workflows, audit logs in structured JSON/CSV, downloadable by L5)	V1.1
EXPORT.1.3	Workflow history export (per-tenant: all workflows with steps, approvals, outputs, costs -- CSV and JSON formats)	V1.1
EXPORT.1.4	Audit log export (filterable by date range, resource type, user -- JSON format for SIEM integration)	V1.1
EXPORT.1.5	Tenant backup/restore (full tenant data backup to object storage, restorable to new tenant instance for migration or DR)	V2

31. CROSS-CUTTING CONCERN: CUSTOMER-FACING OPERATIONS (GAP FILL)

CUSTOPS.1 Status & Communication

Item	Description	Release
CUSTOPS.1.1	Status page (status.upsquad.ai, showing: API status, agent runtime status, integration status, per-region status)	MVP
CUSTOPS.1.2	Incident communication (status page update on incidents, email notification to affected tenants)	MVP
CUSTOPS.1.3	Changelog (public changelog at changelog.upsquad.ai or in-app, documenting every release with what changed)	V1.1
CUSTOPS.1.4	Support system (in-app chat support, email support@upsquad.ai, ticketing)	V1.1
CUSTOPS.1.5	Knowledge base (self-service help articles, searchable, categorized by topic)	V1.1
CUSTOPS.1.6	Uptime monitoring (external monitoring probing API endpoints every 60s from multiple regions)	MVP

32. INDUSTRY TEMPLATE LIBRARY (IND)

Pre-built agent team templates that allow any organization to deploy a functioning AI workforce in minutes. Each template includes: agent role definitions, system prompt templates, tool mappings, workflow templates, and onboarding guidance. Tenants can use templates as-is, customize them, or build fully custom teams.

IND.1 Template Engine

Item	Description	Release
IND.1.1	Template data model (template = {industry, name, description, roles[], workflows[], tools[], knowledge_base_seeds[], onboarding_steps[]}) stored in platform DB	MVP
IND.1.2	Template provisioning engine (on template selection: create agent roles from template, configure tools, deploy starter workflow, seed knowledge base)	MVP
IND.1.3	Template customization UI (after deployment: modify role names, adjust system prompts, add/remove tools, change workflow steps -- all via web UI, no code)	MVP
IND.1.4	Template versioning (templates are versioned, tenants pin to a version, notified when updates available)	V1.1
IND.1.5	Community template submissions (tenants can submit their custom team configurations as templates for review and publication)	V2

IND.2 Pre-Built Industry Templates

Each template below defines a complete agent team. MVP templates ship with the platform; V1.1 and V2 templates are added post-launch.

Item	Description	Release
IND.2.1	Engineering Team template -- Roles: Code Generator, Code Reviewer, Architect, QA Tester, DevOps Engineer, Project Manager, Security Analyst, Documentation Writer. Tools: GitHub/GitLab, CI/CD, code execution, terminal. Workflows: feature development, bug fix, code review, release.	MVP
IND.2.2	Recruitment Agency template -- Roles: Sourcer (scans job boards, databases for matching candidates), Screener (pre-screens resumes against JD criteria, scores fit), Outreach Specialist (drafts personalized candidate emails, follow-ups), Compliance Checker (verifies visa/work permit requirements per target country), Interview Coordinator (schedules interviews, sends reminders, collects feedback). Tools: email, calendar, web scraping, document generation. Workflows: new job order, candidate sourcing pipeline, interview scheduling, offer management.	MVP
IND.2.3	Sales Team template -- Roles: Lead Researcher (identifies prospects, enriches contact data), Outreach Writer (drafts cold emails, follow-up sequences), Proposal Builder (generates proposals and quotes from templates), CRM Manager (updates deal stages, logs activities), Win/Loss Analyst (analyzes closed deals for patterns). Tools: email, CRM, document generation, web scraping. Workflows: lead qualification, outreach sequence, proposal generation, deal closing.	MVP
IND.2.4	Legal Practice template -- Roles: Research Associate (legal research, case law lookup, statute analysis), Document Drafter (contracts, agreements, legal letters from templates), Compliance Monitor (regulatory change tracking, policy impact analysis), Case Manager (tracks deadlines, filings, client communications), Billing Coordinator (time tracking, invoice generation). Tools: email, document generation, calendar, web search. Workflows: new client intake, contract drafting, compliance review, case management.	V1.1
IND.2.5	Marketing Team template -- Roles: Content Writer (blog posts, social media, ad copy), SEO Analyst (keyword research, ranking analysis, optimization suggestions), Campaign Manager (plans and tracks campaigns across channels), Social Media Manager (schedules posts, monitors engagement, responds to comments), Analytics Reporter (pulls data, generates performance reports). Tools: email, web scraping, document generation, social media APIs. Workflows: content calendar, campaign launch, performance reporting.	V1.1
IND.2.6	Customer Support template -- Roles: Ticket Triager (categorizes incoming tickets, routes to right agent), Knowledge Writer (creates/updates help articles from resolved tickets), Response Drafter (drafts replies to customer inquiries), Escalation Handler (handles complex cases, coordinates with other teams), CSAT Analyst (analyzes satisfaction scores, identifies trends). Tools: email, CRM, knowledge base, communication. Workflows: ticket lifecycle, knowledge base update, escalation.	V1.1
IND.2.7	Finance & Accounting template -- Roles: Invoice Processor (reads invoices, extracts data, categorizes expenses), Report Generator (financial reports, cash flow analysis, budget vs actual), Compliance Monitor (tax deadline tracking, regulatory filing reminders), Audit Preparer (gathers documentation, prepares audit packages). Tools: email, document generation, spreadsheet, calendar. Workflows: month-end close, invoice processing, audit preparation.	V1.1
IND.2.8	HR & People Ops template -- Roles: Onboarding Coordinator (new hire checklists, document collection, IT setup requests), Policy Writer (drafts and updates employee policies), Leave Manager (tracks PTO, processes requests, handles edge cases), Performance Reviewer (collects feedback, drafts review summaries), Offboarding Coordinator (exit checklists, access revocation, knowledge transfer). Tools: email, calendar, document generation, communication. Workflows: employee onboarding, performance review cycle, offboarding.	V1.1
IND.2.9	Custom/Blank template -- Empty template with no pre-configured roles. Tenant builds their agent team from scratch using the Role Builder. Includes guided setup wizard.	MVP

IND.3 Template Metrics

Item	Description	Release
IND.3.1	Template adoption tracking (which templates are most used, customization rate, deployment success rate)	MVP
IND.3.2	Template effectiveness scoring (per-template: average workflow completion rate, user satisfaction, cost efficiency -- used to improve templates)	V1.1
IND.3.3	Template recommendation engine (based on tenant's industry, size, and tool stack, recommend the best-fit template with confidence score)	V1.1

33. PRICING MODEL

Dual Billing Model: Seat-Based (Copilots) + Hourly (Agent Teams)

UpsQuad v1 adopts a dual billing model:

Personal Copilots: Seat-based pricing where organisations pay per enabled human user per month. This provides predictability for enterprise procurement.

Agent Teams: Hourly pricing where agent teams accrue cost by the hour they are active/running. This aligns cost with value -- teams that do more work cost more, and inactive teams cost nothing.

Both billing streams are visible separately in the Platform Owner Console and in each org's billing view.

Tier Structure

	Free	Pro	Enterprise
Personal Copilot Price	$0/month	$29/seat/month	Custom (contact sales)
Agent Team Price	$0 (limited hours)	Market rate/agent-hour	Custom (volume discounts)
Copilot Seats included	Up to 3	Up to 100	Unlimited
Agent Team Allowance	10 agent-hours/month	Unlimited (pay-as-you-go)	Unlimited (volume discounts)
Org hierarchy limit	10 users (human + agent)	500 users (human + agent)	Unlimited
Copilot interactions	100 messages/seat/month	2,000 messages/seat/month	Unlimited
Competency catalogue	Default only	Default + custom	Default + custom
Copilot personalisation	Basic	Full	Full
Agent team autonomy levels	Supervised only	All levels	All levels
Delegated enablement	No	Yes	Yes
SSO (SAML/OIDC)	No	No	Yes
CSV bulk import	No	Yes	Yes
HR system sync	No	No	Yes

Rationale

$29/seat/month for personal copilots positions UpsQuad competitively against GitHub Copilot ($19/seat for individuals, $39/seat for business) and other AI-assisted productivity tools.
Hourly agent team pricing aligns cost with value and allows organisations to scale up/down flexibly. It also avoids the complexity of seat-based pricing for non-human entities.
The Free tier serves as a product-led growth funnel: small teams can experience both personal copilots and agent teams (with 10 agent-hours/month) before committing.
Enterprise pricing is custom to accommodate volume discounts, multi-year commitments, and compliance add-ons.

34. PRICING TIER FEATURE MAPPING

Feature	Free	Pro	Enterprise
Org hierarchy (up to 10 users, human + agent)	Yes	Yes	Yes
Org hierarchy (up to 500 users)	--	Yes	Yes
Org hierarchy (unlimited)	--	--	Yes
Personal copilot (up to 3 seats)	Yes	Yes	Yes
Personal copilot (up to 100 seats)	--	Yes	Yes
Personal copilot (unlimited seats)	--	--	Yes
Agent team deployment	Yes (10 hrs/month, supervised only)	Yes (pay-as-you-go, all autonomy levels)	Yes (volume discounts)
Default competency catalogue	Yes	Yes	Yes
Custom competency profiles	--	Yes	Yes
Seniority-based copilot adaptation	Yes	Yes	Yes
Copilot personalisation	Basic	Full	Full
Multi-language support	English only	All languages	All languages
Delegated enablement	--	Yes	Yes
Recursive delegation	--	Yes	Yes
Admin dashboard (basic)	Yes	Yes	Yes
Admin dashboard (per-dept breakdown + effectiveness)	--	Yes	Yes
Advanced analytics	--	Basic	Full
SSO (SAML/OIDC)	--	--	Yes
CSV bulk import	--	Yes	Yes
HR system sync	--	--	Yes
Audit log	--	--	Yes
Custom departments	--	Yes	Yes
Integration marketplace	--	Up to 3	Unlimited
Approval workflows (human-in-the-loop)	--	Yes	Yes
Per-org/dept token budgets	--	Yes	Yes
Usage-based overage billing	--	Yes	Yes
Copilot message cap	100/seat/month	2,000/seat/month	Unlimited
SLA	Best effort	99.5%	99.9%
Platform Owner Console	Internal only (not customer-facing)

35. APPENDIX A: RELEASE CLASSIFICATION DEFINITIONS

MVP (Minimum Viable Product)

Definition: The absolute minimum required to onboard the first paying customer (Starter tier) from any industry and have them successfully run AI agent workflows with human approval.
Timeline: Target 12-16 weeks from development start.
Criteria: User can sign up, select their industry, deploy an agent team from templates or custom roles, run a workflow, approve agent work via web dashboard (or optionally via email/SCM/messaging), pay via payment provider, and view costs. Must work for both technical users (with SCM integration) and non-technical users (web dashboard + email only).
Items counted: ~329 items across all priorities.

V1.1 (Fast Follow)

Definition: Features required for enterprise credibility and competitive differentiation. Ship within 4-8 weeks of MVP.
Criteria: SSO, GitLab support, advanced dashboards, approval delegation, optimization suggestions, messaging integration, compliance reports.
Items counted: ~145 items.

V2 (Scale & Differentiation)

Definition: Features for scale (1M agents), advanced intelligence, marketplace, and full enterprise deployment options.
Criteria: Multi-region active-active, on-premise, mobile app, marketplace, A/B testing, advanced forecasting.
Items counted: ~24 items.

36. APPENDIX B: GAP COVERAGE MATRIX

Gap Identified	Covered By	Section
MFA/2FA	P1.6.1	Foundation - Auth Hardening
Prompt injection prevention	SEC.1.1-1.6	Security Hardening
Agent output validation	SEC.1.3-1.4	Security Hardening
Tool sandboxing	P2.4.8	Agent Runtime - MCP
Encryption key management (per-tenant DEK)	SEC.2.1-2.5	Security Hardening
OWASP compliance	SEC.3.1-3.8	Security Hardening
Password reset	P1.6.2	Foundation - Auth Hardening
Session management	P1.6.3	Foundation - Auth Hardening
Token refresh	P1.6.4	Foundation - Auth Hardening
Device tracking	P1.6.5	Foundation - Auth Hardening
Suspicious activity detection	P1.6.6	Foundation - Auth Hardening
Cross-tenant prevention testing	P1.4.7, TEST.2.1	Multi-tenancy, Testing
Data retention post-deletion	P1.4.6	Multi-tenancy Core
GDPR right-to-be-forgotten	P1.4.8	Multi-tenancy Core
Agent state persistence (pod death)	P2.1.8-2.1.9	Agent Executor
In-flight workflow recovery	P4.1.10	Workflow Engine
Checkpoint strategy	P2.1.8	Agent Executor
Graceful shutdown	P2.1.9	Agent Executor
RTO/RPO targets	DR.1.1	Disaster Recovery
Backup strategy	DR.1.2-1.4	Disaster Recovery
Failover procedures	DR.1.6	Disaster Recovery
Recovery runbooks	DR.1.5	Disaster Recovery
Transient vs permanent errors	ERR.1.1-1.3	Error Handling
Retry strategies	ERR.1.2	Error Handling
Dead letter queues	ERR.1.4	Error Handling
Stuck workflow remediation	ERR.1.5, P4.1.11	Error Handling, Workflow
Notification queuing	NOTIF.1.2	Notification System
Notification retry	NOTIF.2.6	Notification System
Notification deduplication	NOTIF.1.3	Notification System
Notification templates	NOTIF.1.4	Notification System
Messaging/email/alerting integration	NOTIF.2.2-2.5	Notification System
Notification batching	NOTIF.1.5	Notification System
Webhook delivery guarantees	NOTIF.2.6	Notification System
Integration tests	TEST.1.2	Testing Infrastructure
Load testing (1M agents)	TEST.2.5-2.6	Testing Infrastructure
Chaos engineering	TEST.2.4	Testing Infrastructure
Performance benchmarks	TEST.3.1-3.4	Testing Infrastructure
API docs (OpenAPI)	DOC.1.1-1.4	Documentation
Agent development guide	DOC.2.2	Documentation
Troubleshooting runbooks	DOC.2.5	Documentation
ADRs	DOC.3.1	Documentation
GDPR data exports	EXPORT.1.1	Data Export
Workflow history export	EXPORT.1.3	Data Export
Tenant backup/restore	EXPORT.1.5	Data Export
Terms of Service	P0.1.2	Pre-Development Legal
Privacy Policy	P0.1.3	Pre-Development Legal
DPA	P0.1.4	Pre-Development Legal
SLA documents	P0.1.6	Pre-Development Legal
Status page	CUSTOPS.1.1	Customer-Facing Ops
Changelog	CUSTOPS.1.3	Customer-Facing Ops
Support system	CUSTOPS.1.4	Customer-Facing Ops
Prompt injection prevention	SEC.1.1-1.6	Security Hardening
Output validation	SEC.1.3	Security Hardening
Model governance	P2.2.12	LLM Router
AI regulatory compliance (EU AI Act)	SEC.4.1-4.2, P0.2.1	Security, Pre-Dev
NIST AI RMF	SEC.4.5, P0.2.2	Security, Pre-Dev
Token bucket algorithm	P1.3.5	API Gateway
Rate limit headers	P1.3.5	API Gateway
Graceful degradation (rate limit)	P1.3.10	API Gateway
Learning pipeline details	P8.3.1-8.3.7	Continuous Learning
Cross-tenant contamination	P8.3.6, P3.5.8	Learning, RAG
Learning rollback	P8.3.4	Continuous Learning
Payment webhooks	P9.1.4	Billing
Tax calculation	P9.1.7	Billing
Payment retry	P9.1.6	Billing
Dunning process	P9.1.6	Billing
Industry-agnostic agent types	P2.3.1-2.3.9	Agent Type System (Dynamic Role Builder)
Non-SCM workflow tracking	P4.1.1, P4.1.12-14	Workflow Engine
Multi-channel approvals (non-SCM)	P4.3.5, P4.3.11-12	Approval Chain Engine
Non-technical onboarding	P6.3.2-P6.3.10	Onboarding Flow
Industry-agnostic tools (email, calendar, CRM)	P2.4.9-P2.4.15	Tool Registry
Industry template library	IND.1.1-IND.3.3	Industry Template Library
Domain-agnostic knowledge bases	P3.5.2, P3.5.9-10	RAG Knowledge Bases
Visual workflow builder (no-code)	P4.1.13	Workflow Engine
Non-SCM external adapters	P4.2.8-P4.2.11	External Integration Adapters
Domain-agnostic change guard	P4.4.2, P4.4.4	Change Guard
Industry-agnostic cost metrics	P7.1.3	Cost Engine
Approval timeouts	P4.3.7	Approval Chain
Approval delegation	P4.3.8	Approval Chain
Approval revocation	P4.3.9	Approval Chain
Consensus breaking	P4.3.10	Approval Chain
Platform Console (all-tenant monitoring)	PC.2.1-2.4	Platform Console
Usage metering	PC.3.1-3.5	Platform Console
MRR/ARR	PC.4.1-4.2	Platform Console
Churn prediction	PC.4.3	Platform Console
Health scoring	P9.2.6, PC.5.1-5.4	Tenant Mgmt, Console
Stateless agent runtime (no local state)	P0.3.11, P2.1.15	Pre-Dev ADR, Agent Executor
Immutable session runtime (frozen config per session)	P0.3.12, P2.1.16	Pre-Dev ADR, Agent Executor
Agent session initialization protocol	P2.1.16	Agent Executor
Per-action authorization check	P2.1.17	Agent Executor
Agent self-metering (metrics endpoint)	P2.1.18	Agent Executor
Billable metrics per agent	P2.1.19	Agent Executor
Performance metrics per agent	P2.1.20	Agent Executor
Metrics attribution dimensions	P2.1.21	Agent Executor
Context refresh mechanism	P3.1.11	Context Engine
Context push operation (/push-context)	P3.1.12	Context Engine
Context pull operation (/pull-context)	P3.1.13	Context Engine
Context push/pull authorization model	P3.1.14	Context Engine
Blacklist-based action model	P3.3.6	Immutable Agent Context
Guardrail definition format	P3.3.7	Immutable Agent Context
Self-context immutability for agents	P3.3.8	Immutable Agent Context
Hierarchical context editing (downward only)	P3.3.9	Immutable Agent Context
Agent hierarchy definition (chain of trust tree)	P3.3.10	Immutable Agent Context
Chain of trust enforcement	P3.3.11	Immutable Agent Context
Context management slash commands (/push-context, /pull-context)	P6.1.10	Chat Interface
Config change with immutable session policy	P4.6.5 (modified)	Config DB
Org hierarchy as first-class entity	FR 4-12, US-1	Functional Requirements, User Stories
Human employee registry	FR 1-3, US-1	Functional Requirements, User Stories
Selective user enablement/disablement	FR 13-19, US-2, US-3	Functional Requirements, User Stories
1:1 copilot-per-employee model	FR 20-27, US-4	Functional Requirements, User Stories
Automatic copilot assignment based on designation	FR 24-27, US-4	Functional Requirements, User Stories
Delegated enablement by managers	FR 15-16, US-3	Functional Requirements, User Stories
Seat-based billing model	FR 72-79, Pricing Model	Functional Requirements, Pricing
Free tier	Pricing Model	Pricing
CSV bulk import of org hierarchy	FR 11, US-1	Functional Requirements, User Stories
Adoption dashboard	FR 80-82, US-6	Functional Requirements, User Stories
Agent team deployment with approval	FR 31-41, US-9	Functional Requirements, User Stories
Configurable agent autonomy	FR 37-38, US-10	Functional Requirements, User Stories
Human-in-the-loop approval workflows	FR 42-46, US-11	Functional Requirements, User Stories
Copilot personalisation	FR 28-30, US-4	Functional Requirements, User Stories
Integration marketplace	FR 53-57	Functional Requirements
Multi-language copilot support	FR 52	Functional Requirements
Context-aware MCP tool loading (reduce idle context)	P2.4.16	Tool Registry & MCP
Centralized MCP security gateway (auth, authz, rate limit, revocation)	P2.4.17	Tool Registry & MCP
Runtime guardrail enforcement at transport layer (defense-in-depth)	P3.3.12	Immutable Agent Context
Declarative output validation schema language	SEC.1.7	Security Hardening
HRIS import and automated sync	FR 83-89, US-12	Functional Requirements, User Stories
Employee and manager offboarding SOP	FR 90-95, US-13	Functional Requirements, User Stories
Copilot-to-copilot collaboration	FR 96-100	Functional Requirements

37. APPENDIX C: COMPETENCY CATALOGUE (DEFAULT v1)

Competency ID	Designation Pattern	Seniority Modifier Effect	Description
`swe`	Software Engineer, Developer, Programmer	Junior: more explanations, code examples. Senior: concise, assumes expertise.	Helps with coding tasks, PR reviews, debugging, technical documentation
`em`	Engineering Manager, Tech Lead, Team Lead	Mid: tactical sprint help. Senior/Director: strategic, cross-team.	Helps with sprint planning, 1:1 prep, team metrics, project tracking
`sre`	SRE, DevOps Engineer, Infrastructure Engineer	Junior: guided runbooks. Senior: root-cause analysis, architecture.	Helps with incident response, runbooks, monitoring, capacity planning
`qa`	QA Engineer, Test Engineer, SDET	Junior: test case templates. Senior: strategy, coverage optimisation.	Helps with test plans, test automation, bug triage, coverage analysis
`pm`	Product Manager, Product Owner	Junior: frameworks, templates. Senior: stakeholder strategy, roadmap.	Helps with PRDs, user stories, roadmap planning, stakeholder updates
`mktg`	Marketing Manager, Marketing Specialist, Growth	Junior: campaign briefs. Senior: channel strategy, attribution.	Helps with campaigns, content strategy, analytics, messaging
`sales`	Sales Rep, Account Executive, BDR	Junior: outreach scripts. Senior: deal strategy, executive selling.	Helps with outreach templates, pipeline management, deal strategy
`hr`	HR Specialist, People Ops, Recruiter	Junior: JD drafts. Senior: policy design, workforce planning.	Helps with job descriptions, interview plans, policy drafting
`design`	Designer, UX Designer, UI Designer	Junior: design patterns. Senior: design systems, user research strategy.	Helps with design briefs, user flows, accessibility reviews
`data`	Data Analyst, Data Scientist, BI Analyst	Junior: query help. Senior: modelling strategy, data architecture.	Helps with queries, dashboards, analysis frameworks, data storytelling
`exec`	CEO, CTO, VP, Director, C-Suite	N/A (inherently senior context).	Helps with strategic planning, board prep, OKR tracking, exec summaries
`general`	(fallback)	Adapts based on seniority if provided.	General assistant for unmatched designations

SUMMARY COUNTS

Priority	MVP Items	V1.1 Items	V2 Items	Total
P0: Pre-Development	28	5	0	33
P1: Foundation	41	9	1	51
P2: Agent Runtime	47	12	2	61
P3: Context & Memory	33	14	3	50
P4: Workflow & Governance	57	15	1	73
P5: Agent Collaboration	7	5	0	12
P6: User Experience	21	12	2	35
P7: Cost & Measurement	6	9	2	17
P8: Intelligence & Optimization	5	10	2	17
P9: Business & Monetization	13	10	4	27
Platform Console	14	7	2	23
Security Hardening	16	6	0	22
Notification System	5	5	0	10
Testing Infrastructure	6	5	1	12
Documentation	10	4	0	14
Error Handling	4	2	0	6
Disaster Recovery	5	1	1	7
Data Export	0	4	1	5
Customer-Facing Ops	3	3	0	6
Industry Template Library	7	8	2	17
TOTAL	~329	~146	~24	~499

Note: Item counts do not include the new User Stories (US-1 through US-13), Functional Requirements (FR 1-100), Non-Functional Requirements, Scope, Dependencies, Edge Cases, or Decisions sections, which add approximately 120+ additional requirements to the document.

AI Workforce Platform | Version 1.9
SUB-PRDs
CHANGELOG
- Version 1.9 -- 2026-04-16 -- MAJOR RESTRUCTURE
- Version 1.8 -- 2026-04-15
- Version 1.7 -- 2026-04-13 (delivered; PRD doc update retroactive)
- Version 1.6 -- 2026-04-06
- Version 1.5 -- 2026-04-05
- Version 1.4 -- 2026-04-03
- Version 1.3 -- 2026-04-05
- Version 1.2 -- 2026-04-04
- Version 1.1 (2026-04-03)
TABLE OF CONTENTS
1. EXECUTIVE SUMMARY
2. PROBLEM STATEMENT
3. TWO-MODE PRODUCT MODEL
- Mode 1: Personal Copilot
- Mode 2: Agent Team
- Agent Team Agents as Headless Users
4. GOALS & SUCCESS METRICS
5. USER STORIES
- US-1: Org Admin Defines Org Hierarchy
- US-2: Org Admin Enables Platform for Specific Users
- US-3: Manager Enables Platform for Reportees (Delegated Enablement)
- US-4: Enabled User Gets a Personal Copilot Agent
- US-5: Enabled User Interacts with Copilot via Chat Interface
- US-6: Org Admin Views Platform Adoption Dashboard
- US-7: Platform Owner Views All Onboarded Organisations
- US-8: Platform Owner Views Organisation Expenses (Dual Billing Streams)
- US-9: Engineering Leader Deploys an Agent Team
- US-10: Agent Team Operates with Configurable Autonomy
- US-12: Org Admin Imports Org Chart from HR Systems
- US-13: Manager and Employee Offboarding (Resignation SOP)
- US-11: Copilot Actions with Human-in-the-Loop Approval
6. FUNCTIONAL REQUIREMENTS
- Human Employee Registry
- Org Hierarchy Management
- User Enablement
- Personal Copilot Assignment
- Copilot Personalisation
- Agent Teams
- Human-in-the-Loop Approval Workflows
- Chat Interface
- Integration Marketplace
- Authentication & Authorisation
- Platform Owner Console
- Billing & Cost Tracking
- Advanced Analytics
- HRIS Import & Sync
- Employee & Manager Offboarding
- Copilot-to-Copilot Collaboration
7. NON-FUNCTIONAL REQUIREMENTS
8. SCOPE
- In Scope (v1)
- Out of Scope (v1) -- with explicit rationale
9. DEPENDENCIES
10. EDGE CASES & FAILURE MODES
11. DECISIONS (RESOLVED FROM OPEN QUESTIONS)
12. PLATFORM ARCHITECTURE OVERVIEW
13. PRIORITY 0 -- PRE-DEVELOPMENT
- P0.1 Legal Foundation
- P0.2 Compliance Preparation
- P0.3 Design & Architecture Decisions
- P0.4 Infrastructure Accounts & Setup
14. PRIORITY 1 -- FOUNDATION
- P1.1 Infrastructure & Deployment Core
- P1.2 Database & Storage Layer
- P1.3 API Gateway & Auth
- P1.4 Multi-Tenancy Core
- P1.5 Observability Foundation
- P1.6 Auth Hardening (GAP FILL: Security, Auth Details)
15. PRIORITY 2 -- AGENT RUNTIME
- P2.1 Agent Executor
- P2.2 LLM Router (Multi-Model Support)
- P2.3 Agent Type System (Dynamic Role Builder)
- P2.4 Tool Registry & MCP
- P2.5 Agent Scaling
16. PRIORITY 3 -- CONTEXT & MEMORY
- P3.1 Context Engine
- P3.2 Context Version Control
- P3.3 Immutable Agent Context
- P3.4 Persistent Agent Memory
- P3.5 RAG Knowledge Bases
17. PRIORITY 4 -- WORKFLOW & GOVERNANCE
- P4.1 Workflow Engine
- P4.2 External Integration Adapters
- P4.3 Approval Chain Engine
- P4.4 Change Guard (Dedup & Conflict Detection)
- P4.5 Clearance & RBAC System
- P4.6 Central Configuration Database
- P4.7 Priority & SLA Management
- P4.8 Agent Runtime Optimisation & Security Hardening
18. PRIORITY 5 -- AGENT COLLABORATION
- P5.1 A2A (Agent-to-Agent) Protocol
- P5.2 Consensus System
- P5.3 Agent-Human Mapping
19. PRIORITY 6 -- USER EXPERIENCE
- P6.1 Human-Agent Chat Interface
- P6.2 Role-Based Dashboards
- P6.3 Onboarding Flow (Industry-Aware)
- P6.4 Client Interfaces
20. PRIORITY 7 -- COST & MEASUREMENT
- P7.1 Cost Engine
- P7.2 Agent Performance Measurement
- P7.3 Compliance & Audit Agent
21. PRIORITY 8 -- INTELLIGENCE & OPTIMIZATION
- P8.1 Optimization Engine
- P8.2 Feedback & Learning Loop
- P8.3 Continuous Learning Pipeline
22. PRIORITY 9 -- BUSINESS & MONETIZATION
- P9.1 Pricing & Billing
- P9.2 Tenant Management (Platform Admin)
- P9.3 SSO & Enterprise Features
23. CROSS-CUTTING CONCERN: PLATFORM CONSOLE
- PC.1 Console Authentication & Authorization
- PC.2 All-Tenant Monitoring
- PC.3 Usage Metering Dashboard
- PC.4 Financial Dashboard
- PC.5 Platform Health
- PC.6 Platform Operations
24. CROSS-CUTTING CONCERN: SECURITY HARDENING
- SEC.1 Prompt Injection Prevention (GAP FILL: AI-Specific Security)
- SEC.2 Encryption & Key Management (GAP FILL)
- SEC.3 OWASP Compliance (GAP FILL)
- SEC.4 AI Regulatory Compliance (GAP FILL)
25. CROSS-CUTTING CONCERN: NOTIFICATION SYSTEM (GAP FILL)
- NOTIF.1 Notification Infrastructure
- NOTIF.2 Notification Channels
26. CROSS-CUTTING CONCERN: TESTING INFRASTRUCTURE (GAP FILL)
- TEST.1 Test Framework
- TEST.2 Security & Resilience Testing
- TEST.3 Performance Benchmarks
27. CROSS-CUTTING CONCERN: DOCUMENTATION (GAP FILL)
- DOC.1 API Documentation
- DOC.2 User Documentation
- DOC.3 Internal Documentation
28. CROSS-CUTTING CONCERN: ERROR HANDLING & RESILIENCE (GAP FILL)
- ERR.1 Error Classification & Handling
29. CROSS-CUTTING CONCERN: DISASTER RECOVERY (GAP FILL)
- DR.1 Backup & Recovery
30. CROSS-CUTTING CONCERN: DATA EXPORT & PORTABILITY (GAP FILL)
- EXPORT.1 Data Export
31. CROSS-CUTTING CONCERN: CUSTOMER-FACING OPERATIONS (GAP FILL)
- CUSTOPS.1 Status & Communication
32. INDUSTRY TEMPLATE LIBRARY (IND)
- IND.1 Template Engine
- IND.2 Pre-Built Industry Templates
- IND.3 Template Metrics
33. PRICING MODEL
- Dual Billing Model: Seat-Based (Copilots) + Hourly (Agent Teams)
- Tier Structure
- Rationale
34. PRICING TIER FEATURE MAPPING
35. APPENDIX A: RELEASE CLASSIFICATION DEFINITIONS
36. APPENDIX B: GAP COVERAGE MATRIX
37. APPENDIX C: COMPETENCY CATALOGUE (DEFAULT v1)
SUMMARY COUNTS

AI Workforce Platform | Version 1.9​

SUB-PRDs​

CHANGELOG​

Version 1.9 -- 2026-04-16 -- MAJOR RESTRUCTURE​

Version 1.8 -- 2026-04-15​

Version 1.7 -- 2026-04-13 (delivered; PRD doc update retroactive)​

Version 1.6 -- 2026-04-06​

Version 1.5 -- 2026-04-05​

Version 1.4 -- 2026-04-03​

Version 1.3 -- 2026-04-05​

Version 1.2 -- 2026-04-04​

Version 1.1 (2026-04-03)​

TABLE OF CONTENTS​

1. EXECUTIVE SUMMARY​

2. PROBLEM STATEMENT​

3. TWO-MODE PRODUCT MODEL​

Mode 1: Personal Copilot​

Mode 2: Agent Team​

Agent Team Agents as Headless Users​

4. GOALS & SUCCESS METRICS​

5. USER STORIES​

US-1: Org Admin Defines Org Hierarchy​

US-2: Org Admin Enables Platform for Specific Users​

US-3: Manager Enables Platform for Reportees (Delegated Enablement)​

US-4: Enabled User Gets a Personal Copilot Agent​

US-5: Enabled User Interacts with Copilot via Chat Interface​

US-6: Org Admin Views Platform Adoption Dashboard​

US-7: Platform Owner Views All Onboarded Organisations​

US-8: Platform Owner Views Organisation Expenses (Dual Billing Streams)​

US-9: Engineering Leader Deploys an Agent Team​

US-10: Agent Team Operates with Configurable Autonomy​

US-12: Org Admin Imports Org Chart from HR Systems​

US-13: Manager and Employee Offboarding (Resignation SOP)​

US-11: Copilot Actions with Human-in-the-Loop Approval​

6. FUNCTIONAL REQUIREMENTS​

Human Employee Registry​

Org Hierarchy Management​

User Enablement​

Personal Copilot Assignment​

Copilot Personalisation​

Agent Teams​

Human-in-the-Loop Approval Workflows​

Chat Interface​

Integration Marketplace​

Authentication & Authorisation​

Platform Owner Console​

Billing & Cost Tracking​

Advanced Analytics​

HRIS Import & Sync​

Employee & Manager Offboarding​

Copilot-to-Copilot Collaboration​

7. NON-FUNCTIONAL REQUIREMENTS​

8. SCOPE​

In Scope (v1)​

Out of Scope (v1) -- with explicit rationale​

9. DEPENDENCIES​

10. EDGE CASES & FAILURE MODES​

11. DECISIONS (RESOLVED FROM OPEN QUESTIONS)​

12. PLATFORM ARCHITECTURE OVERVIEW​

13. PRIORITY 0 -- PRE-DEVELOPMENT​

P0.1 Legal Foundation​

P0.2 Compliance Preparation​

P0.3 Design & Architecture Decisions​

P0.4 Infrastructure Accounts & Setup​

14. PRIORITY 1 -- FOUNDATION​

P1.1 Infrastructure & Deployment Core​

P1.2 Database & Storage Layer​

P1.3 API Gateway & Auth​

P1.4 Multi-Tenancy Core​

P1.5 Observability Foundation​

P1.6 Auth Hardening (GAP FILL: Security, Auth Details)​

15. PRIORITY 2 -- AGENT RUNTIME​

P2.1 Agent Executor​

P2.2 LLM Router (Multi-Model Support)​

P2.3 Agent Type System (Dynamic Role Builder)​

P2.4 Tool Registry & MCP​

P2.5 Agent Scaling​

16. PRIORITY 3 -- CONTEXT & MEMORY​

P3.1 Context Engine​

P3.2 Context Version Control​

AI Workforce Platform | Version 1.9

SUB-PRDs

CHANGELOG

Version 1.9 -- 2026-04-16 -- MAJOR RESTRUCTURE

Version 1.8 -- 2026-04-15

Version 1.7 -- 2026-04-13 (delivered; PRD doc update retroactive)

Version 1.6 -- 2026-04-06

Version 1.5 -- 2026-04-05

Version 1.4 -- 2026-04-03

Version 1.3 -- 2026-04-05

Version 1.2 -- 2026-04-04

Version 1.1 (2026-04-03)

TABLE OF CONTENTS

1. EXECUTIVE SUMMARY

2. PROBLEM STATEMENT

3. TWO-MODE PRODUCT MODEL

Mode 1: Personal Copilot

Mode 2: Agent Team

Agent Team Agents as Headless Users

4. GOALS & SUCCESS METRICS

5. USER STORIES

US-1: Org Admin Defines Org Hierarchy

US-2: Org Admin Enables Platform for Specific Users

US-3: Manager Enables Platform for Reportees (Delegated Enablement)

US-4: Enabled User Gets a Personal Copilot Agent

US-5: Enabled User Interacts with Copilot via Chat Interface

US-6: Org Admin Views Platform Adoption Dashboard

US-7: Platform Owner Views All Onboarded Organisations

US-8: Platform Owner Views Organisation Expenses (Dual Billing Streams)

US-9: Engineering Leader Deploys an Agent Team

US-10: Agent Team Operates with Configurable Autonomy

US-12: Org Admin Imports Org Chart from HR Systems

US-13: Manager and Employee Offboarding (Resignation SOP)

US-11: Copilot Actions with Human-in-the-Loop Approval

6. FUNCTIONAL REQUIREMENTS

Human Employee Registry

Org Hierarchy Management

User Enablement

Personal Copilot Assignment

Copilot Personalisation

Agent Teams

Human-in-the-Loop Approval Workflows

Chat Interface

Integration Marketplace

Authentication & Authorisation

Platform Owner Console

Billing & Cost Tracking

Advanced Analytics

HRIS Import & Sync

Employee & Manager Offboarding

Copilot-to-Copilot Collaboration

7. NON-FUNCTIONAL REQUIREMENTS

8. SCOPE

In Scope (v1)

Out of Scope (v1) -- with explicit rationale

9. DEPENDENCIES

10. EDGE CASES & FAILURE MODES

11. DECISIONS (RESOLVED FROM OPEN QUESTIONS)

12. PLATFORM ARCHITECTURE OVERVIEW

13. PRIORITY 0 -- PRE-DEVELOPMENT

P0.1 Legal Foundation

P0.2 Compliance Preparation

P0.3 Design & Architecture Decisions

P0.4 Infrastructure Accounts & Setup

14. PRIORITY 1 -- FOUNDATION

P1.1 Infrastructure & Deployment Core

P1.2 Database & Storage Layer

P1.3 API Gateway & Auth

P1.4 Multi-Tenancy Core

P1.5 Observability Foundation

P1.6 Auth Hardening (GAP FILL: Security, Auth Details)

15. PRIORITY 2 -- AGENT RUNTIME

P2.1 Agent Executor

P2.2 LLM Router (Multi-Model Support)

P2.3 Agent Type System (Dynamic Role Builder)

P2.4 Tool Registry & MCP

P2.5 Agent Scaling

16. PRIORITY 3 -- CONTEXT & MEMORY

P3.1 Context Engine

P3.2 Context Version Control