Orchestrata Ultimate / Specs / 070-team-tools

070-team-tools: Team Tools Specification

The Team Tools specification defines a comprehensive system for team creation and management within the Orchestrata platform. This module provides foundational infrastructure for organizing users into teams with hierarchical role-based access control (RBAC), enabling secure multi-tenant collaboration while maintaining strict isolation between team resources.

At a glance

Reading this spec

This spec describes a team creation and management system: organizing users into teams with hierarchical role-based access control, secure multi-tenant collaboration and strict isolation between team resources. The spec is archived. Its note, dated 2026-07-12 (session 227, tool-wave ruling), says the content is generic user and team CRUD plus RBAC boilerplate, dated 2024-01-15, that is disjoint from the volk agent model: orchestrata has volks and governance policies, not human team hierarchies. The note adds that governance-side RBAC is tracked separately as a real SPEC-007 gap. The status line reads "Archived (2026-07-12 — disjoint from volk model; was: Complete)".

For historical reference, the scope was team entity management (create, delete, update), a role hierarchy with permission inheritance, membership and user assignment, resource isolation and access control, and team deletion cascades. The target users were platform administrators, team administrators, service accounts and end users. The three scenarios are enterprise team onboarding, team restructuring and cross-team collaboration. The 157 requirement IDs (REQ-070-NNN) cover the team.json entity schema (UUID, name, slug and audit fields), role permissions (for example the MEMBER role may create, read, update and list the team resources it owns), role assignment, a role hierarchy of up to 5 parent-child levels, compliance review when a privileged role changes, a 100 requests per minute rate limit per user, and a P99 team-creation latency under 500 ms.

No code module cites this spec, consistent with the archive decision. The requirements traceability matrix lists every ID. The spec tracks 2 files. No src/ symbol cites any of the 157 requirements, so measured trace coverage is 0.0%, and in tests/, 0 requirements are cited by a test-side @traces. All 157 requirements have no citing symbol.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

No src/ symbol cites a requirement of this spec.

Other tracked files

• specs/070-team-tools/compliance-audit.md

Full spec text

Verbatim from specs/070-team-tools/spec.md; headings are pushed down two levels.

SPEC-070: Team Tools Specification

ARCHIVED 2026-07-12 (session 227, tool-wave ruling — plans/tool-wave-plan.md): generic user/team-CRUD + RBAC boilerplate (dated 2024-01-15) disjoint from the volk agent model — orchestrata has volks and governance policies, not human team hierarchies. Governance-side RBAC is tracked separately as a real SPEC-007 gap (plans/spec-implementation-gaps.md §3). Revisit only if multi-tenant human collaboration becomes a product goal.

Metadata

• Spec ID: SPEC-070
• Title: Team Tools Specification
• Author: Mohamed
• Status: Archived (2026-07-12 — disjoint from volk model; was: Complete)
• Created: 2024-01-15
• Last Updated: 2024-01-15
• Priority: P1
• Version: 1.0.0
• Extends: SPEC-001 (Core Architecture)

Overview

Purpose

The Team Tools specification defines a comprehensive system for team creation and management within the Orchestrata platform. This module provides foundational infrastructure for organizing users into teams with hierarchical role-based access control (RBAC), enabling secure multi-tenant collaboration while maintaining strict isolation between team resources.

Scope

This specification encompasses:

• Team entity management (creation, deletion, updates)
• Role hierarchy and permission inheritance
• Team membership and user assignment
• Resource isolation and access control
• Team deletion cascade operations

Target Users

• Platform administrators managing tenant teams
• Team administrators creating and managing team structures
• Service accounts and automated systems requiring team-based access
• End users participating in team-based workflows

User Scenarios

Scenario 1: Enterprise Team Onboarding

Actor: Platform Administrator (SUPER_ADMIN role)

Description: A large enterprise customer requests a new team structure for their marketing department. The administrator must create a team with appropriate permissions, assign team administrators, and configure resource quotas.

Flow:

1. Administrator authenticates with SUPER_ADMIN credentials
2. Administrator invokes TeamCreateTool with department-specific configuration
3. System validates permissions and creates team with default roles
4. Administrator assigns team administrators via membership operations
5. System propagates permissions through role hierarchy
6. Team is ready for user onboarding

Expected Outcome: New team created with 3 default roles (ADMIN, MEMBER, VIEWER), 2 team administrators assigned, resource quota configured.

Scenario 2: Team Restructuring

Actor: Team Administrator (TEAM_ADMIN role)

Description: A team administrator needs to reorganize team structure due to department merge. This requires deleting the legacy team, migrating members to a new team, and ensuring resource continuity.

Flow:

1. Administrator authenticates with TEAM_ADMIN credentials for source team
2. Administrator exports team member list for migration
3. Administrator invokes TeamDeleteTool with soft-delete and migration options
4. System validates no critical dependencies exist
5. System creates backup of team configuration
6. System cascades deletion to dependent resources with configurable behavior
7. Administrator creates new team with inherited settings
8. Administrator imports members to new team

Expected Outcome: Legacy team deleted with 30-day recovery window, members migrated to new team, audit trail preserved.

Scenario 3: Cross-Team Collaboration

Actor: Team Member (TEAM_MEMBER role)

Description: A user needs to share resources with another team for a joint project while maintaining security boundaries. The user requests temporary access through their team administrator.

Flow:

1. User authenticates with TEAM_MEMBER credentials
2. User requests resource sharing via team admin
3. Team admin creates cross-team role with limited permissions
4. System validates permission inheritance chain
5. System grants temporary access with expiration
6. User accesses shared resources within scope
7. Access automatically expires after project duration
8. System logs all cross-team access for audit

Expected Outcome: User gains temporary access to 3 resources in external team for 7 days, all access logged.

Terminology

Core Terms

Team: A logical grouping of users with shared resources and permissions within the Orchestrata platform.

Role: A named collection of permissions that can be assigned to team members.

RBAC (Role-Based Access Control): Authorization model where permissions are associated with roles rather than individual users.

Tenant: A customer organization using the Orchestrata platform with isolated resources and configuration.

Cascade Deletion: Process of automatically deleting dependent resources when a parent resource is deleted.

Soft Delete: Deletion that marks resources as deleted without immediate physical removal, enabling recovery during a defined window.

Hard Delete: Permanent deletion with immediate physical removal, cannot be recovered.

Team Hierarchy: Parent-child relationships between teams enabling permission inheritance and organization.

Migration Target: The destination team for member relocation during team deletion operations.

Resource Quota: Platform-defined limits on team resource consumption (members, storage, API calls, etc.).

Data Models

Core Entity Schemas

Team Entity

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://orchestrata.io/schemas/team.json",
  "title": "Team",
  "type": "object",
  "required": [
    "id",
    "name",
    "slug",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique team identifier"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[\\w\\s\\-]+$",
      "description": "Human-readable team name"
    },
    "slug": {
      "type": "string",
      "minLength": 3,
      "maxLength": 50,
      "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
      "description": "URL-safe team identifier"
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Team description"
    },
    "created_by": {
      "type": "string",
      "format": "uuid",
      "description": "User ID of team creator"
    },
    "owner_id": {
      "type": "string",
      "format": "uuid",
      "description": "User or service account owning the team"
    },
    "parent_team_id": {
      "type": ["string", "null"],
      "format": "uuid",
      "description": "Parent team for hierarchical teams"
    },
    "settings": {
      "$ref": "#/definitions/TeamSettings"
    },
    "quotas": {
      "$ref": "#/definitions/TeamQuotas"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Custom key-value metadata"
    },
    "status": {
      "type": "string",
      "enum": ["active", "suspended", "deleted", "pending"],
      "default": "active"
    },
    "deleted_at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Soft delete timestamp"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "definitions": {
    "TeamSettings": {
      "type": "object",
      "properties": {
        "allow_external_invites": {
          "type": "boolean",
          "default": true
        },
        "require_mfa": {
          "type": "boolean",
          "default": false
        },
        "session_timeout_minutes": {
          "type": "integer",
          "minimum": 15,
          "maximum": 1440,
          "default": 60
        },
        "ip_whitelist_enabled": {
          "type": "boolean",
          "default": false
        },
        "ip_whitelist": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(?:/(?:[0-9]|[1-2][0-9]|3[0-2]))?$"
          }
        },
        "default_role": {
          "type": "string",
          "enum": ["admin", "member", "viewer"],
          "default": "member"
        },
        "visibility": {
          "type": "string",
          "enum": ["private", "internal", "public"],
          "default": "private"
        }
      }
    },
    "TeamQuotas": {
      "type": "object",
      "properties": {
        "max_members": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "default": 100
        },
        "max_storage_gb": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100000,
          "default": 100
        },
        "max_api_calls_per_day": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 100000000,
          "default": 100000
        },
        "max_teams": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 10
        },
        "max_resources_per_team": {
          "type": "integer",
          "minimum": 10,
          "maximum": 100000,
          "default": 1000
        }
      }
    }
  }
}

REQ-070-001: A Team entity SHALL conform to the team.json schema — id (UUID), name, slug, created_by, created_at and updated_at are required; description, owner_id, parent_team_id, settings, quotas and metadata are optional; status MUST be one of active, suspended, deleted or pending, defaulting to active; and deleted_at MUST carry the soft-delete timestamp.

REQ-070-002: Team settings SHALL comprise allow_external_invites (default true), require_mfa (default false), session_timeout_minutes (15–1440, default 60), ip_whitelist_enabled (default false), ip_whitelist (CIDR-formatted entries), default_role (admin, member or viewer, default member) and visibility (private, internal or public, default private).

REQ-070-003: Team quotas SHALL comprise max_members (1–10000, default 100), max_storage_gb (1–100000, default 100), max_api_calls_per_day (1000–100000000, default 100000), max_teams (1–1000, default 10) and max_resources_per_team (10–100000, default 1000).

Team Member Entity

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://orchestrata.io/schemas/team-member.json",
  "title": "TeamMember",
  "type": "object",
  "required": [
    "id",
    "team_id",
    "user_id",
    "role_id",
    "joined_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "team_id": {
      "type": "string",
      "format": "uuid"
    },
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "role_id": {
      "type": "string",
      "format": "uuid"
    },
    "invited_by": {
      "type": ["string", "null"],
      "format": "uuid"
    },
    "invitation_token": {
      "type": ["string", "null"],
      "description": "Token for pending invitations"
    },
    "invitation_expires_at": {
      "type": ["string", "null"],
      "format": "date-time"
    },
    "status": {
      "type": "string",
      "enum": ["active", "pending", "suspended", "removed"]
    },
    "joined_at": {
      "type": "string",
      "format": "date-time"
    },
    "last_active_at": {
      "type": ["string", "null"],
      "format": "date-time"
    }
  }
}

REQ-070-004: A TeamMember entity SHALL conform to the team-member.json schema — id, team_id, user_id, role_id and joined_at are required; invited_by, invitation_token, invitation_expires_at and last_active_at are nullable; and status MUST be one of active, pending, suspended or removed.

Role Entity

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://orchestrata.io/schemas/role.json",
  "title": "Role",
  "type": "object",
  "required": [
    "id",
    "team_id",
    "name",
    "permissions",
    "is_system",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "team_id": {
      "type": ["string", "null"],
      "format": "uuid",
      "description": "Null for global roles"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "pattern": "^[A-Z][A-Za-z0-9_]*$"
    },
    "display_name": {
      "type": "string",
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "maxLength": 500
    },
    "permissions": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Permission"
      },
      "description": "List of permissions granted by this role"
    },
    "inherited_from": {
      "type": ["string", "null"],
      "format": "uuid",
      "description": "Parent role ID for inheritance"
    },
    "is_system": {
      "type": "boolean",
      "description": "System roles cannot be modified"
    },
    "is_default": {
      "type": "boolean",
      "description": "Default role for new members"
    },
    "priority": {
      "type": "integer",
      "description": "Role priority for conflict resolution (higher = more privilege)"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "definitions": {
    "Permission": {
      "type": "object",
      "required": ["action", "resource"],
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "create",
            "read",
            "update",
            "delete",
            "list",
            "execute",
            "manage",
            "invite",
            "configure"
          ]
        },
        "resource": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*$"
        },
        "conditions": {
          "type": ["object", "null"],
          "description": "Conditional permission rules"
        },
        "scope": {
          "type": "string",
          "enum": ["self", "team", "department", "organization", "global"],
          "default": "team"
        }
      }
    }
  }
}

REQ-070-005: A Role entity SHALL conform to the role.json schema — id, team_id, name, permissions, is_system and created_at are required; team_id MUST be null for a global role; name MUST match ^[A-Z][A-Za-z0-9_]*$; inherited_from MUST reference the parent role for inheritance; is_system MUST mark roles that cannot be modified; is_default MUST mark the role given to new members; and priority MUST express precedence for conflict resolution, higher meaning more privilege.

REQ-070-006: A Permission SHALL comprise a required action drawn from create, read, update, delete, list, execute, manage, invite and configure; a required resource matching ^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*$; optional conditions carrying conditional permission rules; and a scope of self, team, department, organization or global, defaulting to team.

API Request/Response Schemas

Create Team Request

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://orchestrata.io/schemas/create-team-request.json",
  "title": "CreateTeamRequest",
  "type": "object",
  "required": ["name", "slug"],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "slug": {
      "type": "string",
      "minLength": 3,
      "maxLength": 50,
      "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$"
    },
    "description": {
      "type": "string",
      "maxLength": 500
    },
    "parent_team_id": {
      "type": ["string", "null"],
      "format": "uuid"
    },
    "owner_id": {
      "type": ["string", "null"],
      "format": "uuid"
    },
    "settings": {
      "$ref": "team.json#/definitions/TeamSettings"
    },
    "quotas": {
      "$ref": "team.json#/definitions/TeamQuotas"
    },
    "metadata": {
      "type": "object"
    }
  }
}

REQ-070-007: A CreateTeamRequest SHALL conform to the create-team-request.json schema — name and slug are required, additional properties are rejected, and description, parent_team_id, owner_id, settings, quotas and metadata are optional.

Delete Team Request

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://orchestrata.io/schemas/delete-team-request.json",
  "title": "DeleteTeamRequest",
  "type": "object",
  "required": ["team_id"],
  "additionalProperties": false,
  "properties": {
    "team_id": {
      "type": "string",
      "format": "uuid"
    },
    "delete_resources": {
      "type": "boolean",
      "default": false,
      "description": "Whether to cascade delete team resources"
    },
    "migration_target_team_id": {
      "type": ["string", "null"],
      "format": "uuid",
      "description": "Target team for member migration"
    },
    "soft_delete": {
      "type": "boolean",
      "default": true,
      "description": "Enable 30-day recovery window"
    },
    "force": {
      "type": "boolean",
      "default": false,
      "description": "Force deletion even with active dependencies"
    },
    "backup_enabled": {
      "type": "boolean",
      "default": true,
      "description": "Create backup before deletion"
    }
  }
}

REQ-070-008: A DeleteTeamRequest SHALL conform to the delete-team-request.json schema — team_id is required, additional properties are rejected, and delete_resources (default false), migration_target_team_id (default null), soft_delete (default true), force (default false) and backup_enabled (default true) carry the stated defaults.

Team Response

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://orchestrata.io/schemas/team-response.json",
  "title": "TeamResponse",
  "type": "object",
  "properties": {
    "team": {
      "$ref": "team.json"
    },
    "roles": {
      "type": "array",
      "items": {
        "$ref": "role.json"
      }
    },
    "member_count": {
      "type": "integer"
    },
    "created_resources_count": {
      "type": "integer"
    }
  }
}

REQ-070-009: A TeamResponse SHALL carry the subject team, the array of its roles, the member_count and the created_resources_count.

Technical Design

Architecture Overview

The Team Tools module follows a service-oriented architecture within the Orchestrata platform. It exposes both REST API endpoints and MCP tool interfaces for team management operations.

REQ-070-010: The Team Tools module SHALL expose both REST API endpoints and MCP tool interfaces for team management operations.

Component Design

┌─────────────────────────────────────────────────────────┐
│                     API Gateway                          │
│              (Authentication & Rate Limiting)            │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│                  Team Service                           │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐     │
│  │TeamManager   │ │RoleManager   │ │MemberManager │     │
│  └──────────────┘ └──────────────┘ └──────────────┘     │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│              Permission Engine                           │
│         (RBAC Evaluation & Inheritance)                  │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│            Database Layer (PostgreSQL)                  │
│        TeamRepository, RoleRepository, etc.             │
└─────────────────────────────────────────────────────────┘

Key Classes and Interfaces

REQ-070-011: The Team Tools module SHALL provide TeamService orchestrating team operations through create(), update(), delete() and get(); TeamRepository providing team data access through save(), findById(), findBySlug() and delete(); RoleService managing roles and permissions through createRole(), assignRole() and evaluatePermissions(); MembershipService handling team membership through invite(), addMember() and removeMember(); and PermissionEngine evaluating RBAC decisions through checkPermission() and getEffectiveRoles().

Database Schema

The team module uses the following primary tables:

• teams - Core team entity with settings and quotas
• team_members - Membership junction table
• roles - Role definitions with permissions
• role_permissions - Permission entries for roles
• team_invitations - Pending invitations with tokens

REQ-070-012: The team module SHALL persist its state in the teams, team_members, roles, role_permissions and team_invitations tables.

Event Flow for Team Creation

1. Client sends POST /api/v1/teams with team config
2. API Gateway validates JWT and extracts user context
3. PermissionEngine verifies user has team:create permission
4. TeamService validates input against schema
5. TeamRepository checks slug uniqueness
6. RoleService creates default roles (ADMIN, MEMBER, VIEWER)
7. TeamRepository saves team with generated UUID
8. AuditService logs creation event
9. NotificationService sends confirmation to team owner
10. Response returns created team with default roles

REQ-070-013: Team creation SHALL follow the ordered flow: the API gateway validates the JWT and extracts the user context; the PermissionEngine verifies the team:create permission; TeamService validates the input against the schema; TeamRepository checks slug uniqueness; RoleService creates the default ADMIN, MEMBER and VIEWER roles; TeamRepository saves the team with a generated UUID; AuditService logs the creation event; NotificationService sends confirmation to the team owner; and the response returns the created team with its default roles.

Examples

Create Team Example

Request:

curl -X POST https://api.orchestrata.io/api/v1/teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team",
    "slug": "engineering",
    "description": "Core engineering team",
    "settings": {
      "allow_external_invites": true,
      "require_mfa": false,
      "visibility": "internal",
      "session_timeout_minutes": 60
    },
    "quotas": {
      "max_members": 50,
      "max_storage_gb": 500
    }
  }'

Response (201 Created):

{
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Engineering Team",
    "slug": "engineering",
    "description": "Core engineering team",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "roles": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "ADMIN",
      "display_name": "Administrator",
      "is_system": true,
      "priority": 100
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "name": "MEMBER",
      "display_name": "Member",
      "is_system": true,
      "is_default": true,
      "priority": 50
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440012",
      "name": "VIEWER",
      "display_name": "Viewer",
      "is_system": true,
      "priority": 10
    }
  ],
  "member_count": 1
}

Delete Team with Migration Example

Request:

curl -X DELETE https://api.orchestrata.io/api/v1/teams/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "soft_delete": true,
    "migration_target_team_id": "660e8400-e29b-41d4-a716-446655440001",
    "backup_enabled": true
  }'

Response (200 OK):

{
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "deleted",
    "deleted_at": "2024-01-15T10:30:00Z",
    "recoverable_until": "2024-02-14T10:30:00Z"
  },
  "backup_id": "550e8400-e29b-41d4-a716-446655440099",
  "cascaded_resources": {
    "deleted": 0,
    "migrated": 25,
    "preserved": 15
  }
}

Invite Team Member Example

Request:

curl -X POST https://api.orchestrata.io/api/v1/teams/engineering/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "770e8400-e29b-41d4-a716-446655440002",
    "role_id": "550e8400-e29b-41d4-a716-446655440011"
  }'

Response (201 Created):

{
  "member": {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "team_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "770e8400-e29b-41d4-a716-446655440002",
    "role_id": "550e8400-e29b-41d4-a716-446655440011",
    "status": "active",
    "joined_at": "2024-01-15T10:35:00Z"
  }
}

Functional Requirements

Team Creation

FR-001 — REQ-070-014: The TeamCreateTool shall create a new team with unique identifier, name, and slug.

FR-002 — REQ-070-015: The TeamCreateTool shall generate three default roles upon team creation: ADMIN, MEMBER, and VIEWER.

FR-003 — REQ-070-016: The TeamCreateTool shall assign the creator as the initial team administrator.

FR-004 — REQ-070-017: The TeamCreateTool shall support optional parent team assignment for hierarchical team structures.

FR-005 — REQ-070-018: The TeamCreateTool shall validate team slug uniqueness across the platform.

FR-006 — REQ-070-019: The TeamCreateTool shall enforce quota limits based on platform configuration.

FR-007 — REQ-070-020: The ADMIN role shall include: manage, create, read, update, delete, list, invite, configure permissions for all team resources.

FR-008 — REQ-070-021: The MEMBER role shall include: create, read, update, list permissions for team resources they own.

FR-009 — REQ-070-022: The VIEWER role shall include: read, list permissions for all team resources.

FR-010 — REQ-070-023: Team name must be 1-100 characters, matching pattern ^[\w\s\-]+$.

FR-011 — REQ-070-024: Team slug must be 3-50 characters, lowercase alphanumeric with hyphens, starting and ending with alphanumeric.

FR-012 — REQ-070-025: Parent team ID must reference an existing active team.

FR-013 — REQ-070-026: Owner ID must reference an existing user or service account.

Team Deletion

FR-014 — REQ-070-027: The TeamDeleteTool shall support soft delete with configurable recovery window (default 30 days).

FR-015 — REQ-070-028: The TeamDeleteTool shall support hard delete for immediate permanent removal.

FR-016 — REQ-070-029: The TeamDeleteTool shall optionally cascade deletion to team resources when enabled.

FR-017 — REQ-070-030: The TeamDeleteTool shall support member migration to another team.

FR-018 — REQ-070-031: The TeamDeleteTool shall create backup before deletion when enabled.

FR-019 — REQ-070-032: The TeamDeleteTool shall maintain complete audit trail of deletion operations.

FR-020 — REQ-070-033: Team deletion shall be blocked if active child teams exist (unless force flag is set).

FR-021 — REQ-070-034: Team deletion shall be blocked if resources are actively in use (unless force flag is set).

FR-022 — REQ-070-035: Team deletion shall validate migration target team exists and has capacity.

FR-023 — REQ-070-036: Soft-deleted teams shall have their slug reserved during recovery window.

Team Updates

FR-024 — REQ-070-037: The system shall support updating team name, description, settings, and quotas.

FR-025 — REQ-070-038: The system shall support adding and removing parent team relationships.

FR-026 — REQ-070-039: The system shall support team suspension and reactivation.

Membership Management

FR-027 — REQ-070-040: The system shall support inviting users to teams with expiration tokens.

FR-028 — REQ-070-041: The system shall support role assignment and modification.

FR-029 — REQ-070-042: The system shall support bulk member operations.

FR-030 — REQ-070-043: The system shall enforce maximum team member quota.

Role Management

FR-031 — REQ-070-044: The system shall support custom role creation within teams.

FR-032 — REQ-070-045: The system shall support role inheritance from parent roles.

FR-033 — REQ-070-046: The system shall support permission conflict resolution via role priority.

FR-034 — REQ-070-047: System roles shall not be modifiable or deletable.

Error Conditions

Consolidated Error Table

REQ-070-048: The system SHALL reject a team-creation request whose name or slug violates its format requirements with HTTP 400 and validation details (ERR-001, ERR-002), and SHALL reject a request whose slug is already in use or whose name already exists in the parent scope with HTTP 409 and conflict details (ERR-003, ERR-004).

REQ-070-049: The system SHALL fail a team-creation request with HTTP 404 when the referenced parent team or owner does not exist (ERR-005, ERR-007), with HTTP 400 when the parent team is not active or the settings contain invalid values (ERR-006, ERR-010), and with HTTP 403 when the platform quota would be exceeded or the user lacks the create permission (ERR-008, ERR-009).

REQ-070-050: The system SHALL fail a team-deletion request with HTTP 404 when the team does not exist (ERR-011), with HTTP 410 and the recovery deadline when the team is already soft-deleted (ERR-012), and with HTTP 400 listing the blocking entities when active child teams or actively-used team resources exist (ERR-013, ERR-014).

REQ-070-051: The system SHALL fail a team-deletion request with HTTP 404 when the migration target team is not found (ERR-015), with HTTP 400 when the migration target has insufficient capacity or team ownership has not been reassigned (ERR-016, ERR-018), with HTTP 500 and a retry option when the backup could not be created (ERR-017), and with HTTP 403 when the user lacks the deletion permission (ERR-019).

REQ-070-052: The system SHALL fail a membership operation with HTTP 409 when the user is already a team member (ERR-020), with HTTP 404 when the member or the referenced role does not exist (ERR-021, ERR-022), with HTTP 400 when the invitation has expired, the invitation token was already redeemed, or the last team administrator would be removed (ERR-023, ERR-024, ERR-026), and with HTTP 403 and quota details when adding the member would exceed quota (ERR-025).

REQ-070-053: The system SHALL fail a role operation with HTTP 403 when a system role would be modified (ERR-027), and with HTTP 400 when the role is still assigned to team members, the requested inheritance would create a cycle, or the permission conflicts with an inherited role (ERR-028, ERR-029, ERR-030).

Non-Functional Requirements

Performance Requirements

REQ-070-101: Team creation SHALL complete in under 500 ms at p99 under normal load.

REQ-070-102: Team deletion SHALL complete in under 2 s at p99 under normal load.

REQ-070-103: Listing 1000 teams SHALL complete in under 1 s at p99 under normal load.

REQ-070-104: A permission check SHALL complete in under 50 ms at p99 for all requests.

REQ-070-105: Ten parallel team creations SHALL complete in under 5 s in total at peak load.

Scalability Requirements

REQ-070-106: The platform SHALL support up to 10,000 teams per tenant as a per-tenant quota.

REQ-070-107: The platform SHALL support up to 10,000 members per team, configurable per team.

REQ-070-108: The platform SHALL support a role hierarchy of up to 5 parent-child levels.

REQ-070-109: The platform SHALL support cross-team membership of up to 100 teams per user.

Availability Requirements

REQ-070-110: The Team Tools service SHALL meet a 99.9% uptime SLA.

REQ-070-111: Planned maintenance SHALL consume less than 4 hours per month.

REQ-070-112: The recovery time objective SHALL be under 1 hour.

REQ-070-113: The recovery point objective SHALL be under 5 minutes.

Observability Requirements

• All team operations must emit structured logs with correlation IDs
• Metrics: team_create_total, team_delete_total, team_membership_changes, role_assignments
• Traces must include full permission evaluation path

REQ-070-114: All team operations SHALL emit structured logs carrying correlation IDs.

REQ-070-115: The service SHALL emit the metrics team_create_total, team_delete_total, team_membership_changes and role_assignments.

REQ-070-116: Traces SHALL include the full permission evaluation path.

API Contracts

Team Management Endpoints

Create Team

POST /api/v1/teams
Authorization: Bearer <token>
Content-Type: application/json

Request:
{
  "name": "Engineering",
  "slug": "engineering",
  "description": "Engineering team",
  "settings": {
    "allow_external_invites": true,
    "require_mfa": false,
    "visibility": "internal"
  },
  "quotas": {
    "max_members": 50
  }
}

Response (201 Created):
{
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Engineering",
    "slug": "engineering",
    "description": "Engineering team",
    "created_by": "550e8400-e29b-41d4-a716-446655440001",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "roles": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "ADMIN",
      "display_name": "Administrator",
      "permissions": [...],
      "is_system": true,
      "is_default": false
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "name": "MEMBER",
      "display_name": "Member",
      "permissions": [...],
      "is_system": true,
      "is_default": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440012",
      "name": "VIEWER",
      "display_name": "Viewer",
      "permissions": [...],
      "is_system": true,
      "is_default": false
    }
  ],
  "member_count": 1,
  "created_resources_count": 0
}

REQ-070-054: POST /api/v1/teams SHALL accept a bearer-token-authorized JSON body carrying name, slug, description, settings and quotas, and SHALL return HTTP 201 with the created team, its three default roles with their permissions, the member_count and the created_resources_count.

Delete Team

DELETE /api/v1/teams/{team_id}
Authorization: Bearer <token>
Content-Type: application/json

Request:
{
  "delete_resources": false,
  "migration_target_team_id": null,
  "soft_delete": true,
  "force": false,
  "backup_enabled": true
}

Response (200 OK):
{
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "deleted",
    "deleted_at": "2024-01-15T10:30:00Z",
    "recoverable_until": "2024-02-14T10:30:00Z"
  },
  "backup_id": "550e8400-e29b-41d4-a716-446655440099",
  "cascaded_resources": {
    "deleted": 0,
    "migrated": 0,
    "preserved": 15
  }
}

REQ-070-055: DELETE /api/v1/teams/{team_id} SHALL accept a bearer-token-authorized JSON body carrying delete_resources, migration_target_team_id, soft_delete, force and backup_enabled, and SHALL return HTTP 200 with the team's status, deleted_at and recoverable_until, the backup_id, and the counts of cascaded resources deleted, migrated and preserved.

Tool Interface Contracts

TeamCreateTool Interface

from typing import Optional
from datetime import datetime
from uuid import UUID

class TeamCreateTool:
    """
    Tool for creating new teams with role-based access control.
    
    Implements: FR-TC-001 through FR-TC-013
    """
    
    async def execute(
        self,
        name: str,
        slug: str,
        description: Optional[str] = None,
        parent_team_id: Optional[UUID] = None,
        owner_id: Optional[UUID] = None,
        settings: Optional[dict] = None,
        quotas: Optional[dict] = None,
        metadata: Optional[dict] = None,
        created_by: UUID = None
    ) -> TeamResponse:
        """
        Create a new team with default roles and permissions.
        
        Args:
            name: Human-readable team name (1-100 chars)
            slug: URL-safe team identifier (3-50 chars)
            description: Optional team description
            parent_team_id: Optional parent team for hierarchy
            owner_id: Optional team owner user ID
            settings: Optional team settings
            quotas: Optional team resource quotas
            metadata: Optional custom metadata
            created_by: ID of user creating the team
            
        Returns:
            TeamResponse with created team, roles, and counts
            
        Raises:
            TeamValidationError: For invalid input (TEAM_NAME_INVALID, TEAM_SLUG_INVALID)
            TeamConflictError: For slug/name conflicts (TEAM_SLUG_CONFLICT, TEAM_NAME_CONFLICT)
            ResourceNotFoundError: For invalid parent/owner references
            QuotaExceededError: When quota limits exceeded
            PermissionDeniedError: When user lacks creation permission
        """
        ...

REQ-070-056: TeamCreateTool.execute() SHALL accept name, slug, description, parent_team_id, owner_id, settings, quotas, metadata and created_by; SHALL return a TeamResponse carrying the created team, its roles and its counts; and SHALL raise TeamValidationError for invalid input, TeamConflictError for slug or name conflicts, ResourceNotFoundError for invalid parent or owner references, QuotaExceededError when quota limits are exceeded, and PermissionDeniedError when the user lacks the creation permission.

TeamDeleteTool Interface

class TeamDeleteTool:
    """
    Tool for deleting teams with cascade and migration support.
    
    Implements: FR-TD-001 through FR-TD-010
    """
    
    async def execute(
        self,
        team_id: UUID,
        delete_resources: bool = False,
        migration_target_team_id: Optional[UUID] = None,
        soft_delete: bool = True,
        force: bool = False,
        backup_enabled: bool = True,
        deleted_by: UUID = None
    ) -> DeleteTeamResponse:
        """
        Delete a team with configurable cascade behavior.
        
        Args:
            team_id: ID of team to delete
            delete_resources: Whether to cascade delete resources
            migration_target_team_id: Target team for member migration
            soft_delete: Enable 30-day recovery window
            force: Force deletion despite dependencies
            backup_enabled: Create backup before deletion
            deleted_by: ID of user performing deletion
            
        Returns:
            DeleteTeamResponse with deletion status and metadata
            
        Raises:
            TeamNotFoundError: When team does not exist
            TeamAlreadyDeletedError: When team already soft-deleted
            ChildTeamsExistError: When child teams block deletion
            ResourcesInUseError: When active resources block deletion
            MigrationTargetError: When migration target invalid
            BackupFailedError: When backup creation fails
            PermissionDeniedError: When user lacks deletion permission
        """
        ...

REQ-070-057: TeamDeleteTool.execute() SHALL accept team_id, delete_resources, migration_target_team_id, soft_delete, force, backup_enabled and deleted_by; SHALL return a DeleteTeamResponse carrying the deletion status and metadata; and SHALL raise TeamNotFoundError, TeamAlreadyDeletedError, ChildTeamsExistError, ResourcesInUseError, MigrationTargetError, BackupFailedError or PermissionDeniedError for the corresponding failure.

Governance

Approval Process

Team creation and deletion require approval from tenant administrators or designated team owners. All team administrative operations must be logged with full audit trail for compliance purposes.

REQ-070-058: Team creation and deletion SHALL require approval from a tenant administrator or a designated team owner.

REQ-070-059: All team administrative operations SHALL be logged with a full audit trail for compliance purposes.

Lifecycle Policy

• Team Creation: Must include business justification and resource allocation plan
• Team Modification: Changes to quotas or permissions require approval if impact > 10% of current usage
• Team Deletion: Requires 30-day advance notice to all members, migration plan for resources
• Emergency Suspension: Platform administrators may suspend teams for security violations with immediate notification

REQ-070-060: A team creation SHALL include a business justification and a resource allocation plan.

REQ-070-061: A change to team quotas or permissions SHALL require approval when its impact exceeds 10% of current usage.

REQ-070-062: Team deletion SHALL require 30 days advance notice to all members and a migration plan for resources.

REQ-070-063: Platform administrators SHALL be able to suspend a team for a security violation, with immediate notification.

Compliance Requirements

• All team operations logged with user ID, timestamp, IP address, and correlation ID
• Audit logs retained for 7 years per SOC2 requirements
• Role changes trigger compliance review for privileged roles (ADMIN, TENANT_ADMIN, SUPER_ADMIN)
• Data residency requirements must be enforced for teams in regulated regions

REQ-070-064: All team operations SHALL be logged with the acting user ID, timestamp, IP address and correlation ID.

REQ-070-065: A role change SHALL trigger a compliance review for the privileged roles ADMIN, TENANT_ADMIN and SUPER_ADMIN.

REQ-070-066: Data residency requirements SHALL be enforced for teams in regulated regions.

REQ-070-117: Audit logs SHALL be retained for 7 years per SOC2 requirements.

Change Management

REQ-070-067: The system SHALL enforce the change-management approvals and review timelines above: a new team creation approved by the team owner or a tenant admin within 2 business days; a quota modification above 10% approved by a tenant admin within 5 business days; a permission model change approved by the security team and a tenant admin within 10 business days; and a team deletion approved by a tenant admin and the resource owners with 30 days notice.

Risk Management

High Risk Operations:

• Deletion of teams with >100 members (requires security review)
• Role elevation to ADMIN level (requires approval from 2 administrators)
• Cross-tenant resource sharing (requires compliance sign-off)

REQ-070-068: Deletion of a team with more than 100 members SHALL require a security review, elevation of a role to ADMIN level SHALL require approval from two administrators, and cross-tenant resource sharing SHALL require compliance sign-off.

Mitigation Controls:

• All deletions require confirmation and support ticket reference
• Automated backup before any destructive operation
• Rate limiting on sensitive operations (max 5 deletions/hour)
• Mandatory security scan for teams before deletion

REQ-070-069: The system SHALL require a confirmation and a support ticket reference for every deletion, SHALL take an automated backup before any destructive operation, SHALL rate-limit sensitive operations to a maximum of 5 deletions per hour, and SHALL run a mandatory security scan on a team before deletion.

Integration Points

User Management Integration

Primary Integration: orchestrata-auth service provides JWT validation and user context

Flow:

1. Team operations receive user_id from JWT token
2. PermissionEngine queries auth service for effective roles
3. AuditService captures user identity for all operations
4. NotificationService sends updates to user's registered email

REQ-070-070: Team operations SHALL take the acting user_id from the JWT issued by the orchestrata-auth service, the PermissionEngine SHALL query that service for effective roles, the AuditService SHALL capture the user identity for all operations, and the NotificationService SHALL send updates to the user's registered email.

Notification Service Integration

Events Emitted:

• team.created (owner, administrators)
• team.updated (administrators)
• team.deleted (all members)
• member.invited (invited user, team administrators)
• member.added (new member, team administrators)
• member.removed (removed member)

REQ-070-071: The service SHALL emit team.created to the owner and administrators, team.updated to administrators, team.deleted to all members, member.invited to the invited user and team administrators, member.added to the new member and team administrators, and member.removed to the removed member.

Notification Channels:

• Email (all events)
• In-app notifications (team-related events)
• Webhook (team administrators via configured endpoints)
• Slack (critical operations: deletion, suspension)

REQ-070-072: Notifications SHALL be delivered by email for all events, by in-app notification for team-related events, by webhook to team administrators at their configured endpoints, and by Slack for the critical operations of deletion and suspension.

Resource Management Integration

Team tools integrate with SPEC-060 (Resource Management) for:

• Resource ownership assignment to teams
• Resource quota tracking and enforcement
• Resource migration during team deletion
• Resource isolation across teams

REQ-070-073: Team tools SHALL integrate with SPEC-060 (Resource Management) for resource ownership assignment to teams, resource quota tracking and enforcement, resource migration during team deletion, and resource isolation across teams.

Audit Service Integration

All team operations emit structured audit events:

{
  "event_type": "team.create",
  "correlation_id": "req-123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2024-01-15T10:30:00Z",
  "actor": {
    "user_id": "user-123",
    "tenant_id": "tenant-456"
  },
  "resource": {
    "type": "team",
    "id": "team-789",
    "slug": "engineering"
  },
  "changes": {
    "team_id": "team-789",
    "status": "active"
  },
  "ip_address": "192.168.1.1",
  "user_agent": "orchestrata-cli/1.2.3"
}

REQ-070-074: Every team operation SHALL emit a structured audit event carrying event_type, correlation_id, timestamp, the actor (user_id, tenant_id), the resource (type, id, slug), the changes, the ip_address and the user_agent.

Authentication Service Integration

The Team Tools service validates all requests through the authentication gateway:

JWT Claims Used:

• sub (subject): User ID for permission evaluation
• tenant_id: Tenant context for multi-tenant isolation
• roles: User's global roles for permission aggregation
• scopes: OAuth2 scopes for fine-grained authorization

REQ-070-075: The service SHALL consume the JWT claims sub as the user ID for permission evaluation, tenant_id as the multi-tenant isolation context, roles for global permission aggregation, and scopes for fine-grained OAuth2 authorization.

Token Validation Flow:

1. Extract JWT from Authorization header
2. Validate signature with auth service public key
3. Check token expiration and revocation status
4. Extract user context and permissions
5. Attach user context to request for team operations

REQ-070-076: The service SHALL validate every request by extracting the JWT from the Authorization header, verifying its signature with the auth service public key, checking token expiration and revocation status, extracting the user context and permissions, and attaching that context to the request.

Monitoring and Observability

Metrics Exposed:

• team_operations_total{operation="create|update|delete"}
• team_creation_duration_seconds
• team_membership_operations_total{action="invite|add|remove"}
• permission_checks_total{result="allow|deny"}
• active_teams_count
• team_members_total

REQ-070-118: The service SHALL expose the metrics team_operations_total{operation="create|update|delete"}, team_creation_duration_seconds, team_membership_operations_total{action="invite|add|remove"}, permission_checks_total{result="allow|deny"}, active_teams_count and team_members_total.

Alerts:

• Team creation rate > 100/hour (potential abuse)
• Deletion rate > 10/hour (investigate)
• Permission denied rate > 5% (configuration issue)
• Team operations error rate > 1% (service degradation)

REQ-070-119: The service SHALL alert when the team creation rate exceeds 100 per hour, the deletion rate exceeds 10 per hour, the permission-denied rate exceeds 5%, or the team operations error rate exceeds 1%.

Success Criteria

Functional Success Criteria

REQ-070-120: Team creation SHALL succeed for 100% of valid requests, measured as an error rate below 0.1% in production.

REQ-070-121: 100% of teams SHALL have their ADMIN, MEMBER and VIEWER default roles created correctly.

REQ-070-122: Hierarchical role inheritance SHALL verify correctly in 100% of inheritance tests.

REQ-070-123: 100% of soft deletions SHALL be recoverable within the 30-day window.

REQ-070-124: Team deletion SHALL lose zero member records during migration.

Performance Success Criteria

REQ-070-125: P99 team creation latency SHALL stay under 500 ms for 99.9% of requests.

REQ-070-126: P99 team deletion latency SHALL stay under 2 s for 99.9% of requests.

REQ-070-127: P99 permission check latency SHALL stay under 50 ms for 99.9% of checks.

REQ-070-128: Ten parallel team creations SHALL all complete successfully in under 5 s.

REQ-070-129: Simple database queries SHALL complete in under 100 ms for 99% of queries.

Security Success Criteria

• Zero Security Incidents: No unauthorized team access or privilege escalation
• 100% Audit Coverage: All team operations logged with complete metadata
• Permission Matrix Compliance: All role-based access control tests passing
• Penetration Testing: Zero critical findings in annual security audit
• Compliance Readiness: 100% SOC2 and GDPR audit log coverage

REQ-070-130: There SHALL be zero unauthorized team access or privilege escalation incidents.

REQ-070-131: 100% of team operations SHALL be logged with complete metadata.

REQ-070-132: All role-based access control permission matrix tests SHALL pass.

REQ-070-133: The annual security audit SHALL report zero critical penetration-testing findings.

REQ-070-134: Audit log coverage SHALL be 100% for SOC2 and GDPR compliance readiness.

Reliability Success Criteria

• Uptime: 99.9% availability (SLA)
• Data Durability: 99.999999999% (11 nines) team configuration data durability
• Recovery Time Objective: < 1 hour for service restoration
• Recovery Point Objective: < 5 minutes data loss window
• Backup Integrity: 100% of backups restorable and verified monthly

REQ-070-135: The service SHALL achieve 99.9% availability against its SLA.

REQ-070-136: Team configuration data SHALL achieve 99.999999999% (11 nines) durability.

REQ-070-137: Service restoration SHALL complete within 1 hour.

REQ-070-138: The data loss window SHALL not exceed 5 minutes.

REQ-070-139: 100% of backups SHALL be restorable and SHALL be verified monthly.

Operational Success Criteria

• Monitoring Coverage: 100% of critical operations monitored with alerts
• Error Rate: < 0.1% of team operations result in errors
• Ticket Volume: < 10 team-related support tickets per 1000 teams/month
• Documentation: Complete API documentation with examples for all endpoints
• Testing Coverage: > 95% code coverage for team management module

REQ-070-140: 100% of critical operations SHALL be monitored with alerts.

REQ-070-141: Fewer than 0.1% of team operations SHALL result in errors.

REQ-070-142: Team-related support tickets SHALL stay below 10 per 1000 teams per month.

REQ-070-143: Every endpoint SHALL carry complete API documentation with examples.

REQ-070-144: The team management module SHALL hold above 95% code coverage.

User Experience Success Criteria

• Team Creation Time: < 5 minutes from request to active team
• Administrator Onboarding: < 30 minutes to configure basic team structure
• User Feedback: > 4.5/5 average satisfaction score for team management UI
• API Usability: Complete OpenAPI 3.0 specification with working examples
• Error Messages: 100% of errors include actionable resolution guidance

REQ-070-145: A team SHALL go from request to active in under 5 minutes.

REQ-070-146: An administrator SHALL be able to configure a basic team structure in under 30 minutes.

REQ-070-147: The team management UI SHALL hold an average satisfaction score above 4.5/5.

REQ-070-148: The API SHALL ship a complete OpenAPI 3.0 specification with working examples.

REQ-070-149: 100% of errors SHALL include actionable resolution guidance.

Integration Success Criteria

• Auth Service Integration: 100% of JWT validation working correctly
• Notification Delivery: 99.5% successful notification delivery rate
• Audit Service: 100% of operations logged to audit system
• Resource Management: Seamless resource ownership transfer during team operations
• Monitoring: Real-time metrics and alerting fully operational

REQ-070-150: 100% of JWT validation through the auth service SHALL work correctly.

REQ-070-151: Notification delivery SHALL succeed for 99.5% of notifications.

REQ-070-152: 100% of operations SHALL be logged to the audit system.

REQ-070-153: Resource ownership SHALL transfer without interruption during team operations.

REQ-070-154: Real-time metrics and alerting SHALL be fully operational.

Security Requirements

Role Hierarchy

Global Roles

REQ-070-077: The platform SHALL define the global roles SUPER_ADMIN with full platform access able to manage all teams, TENANT_ADMIN able to manage all teams within a tenant, and AUDITOR with global or tenant read-only access for compliance.

Team-Level Roles

REQ-070-078: Each team SHALL carry the team-level roles ADMIN at priority 100 for full team management, MEMBER at priority 50 for standard team access, and VIEWER at priority 10 for read-only team access.

Hierarchical Inheritance

• Child team roles inherit permissions from parent team roles
• Permission resolution: Explicit > Inherited > Default
• Role priority determines final permission in conflicts

REQ-070-079: Child team roles SHALL inherit permissions from parent team roles, permission resolution SHALL prefer explicit over inherited over default, and role priority SHALL determine the final permission in a conflict.

Permission Inheritance Model

Permission Check Algorithm:
1. Check user's direct role permissions
2. Check user's inherited team role permissions (parent teams)
3. If multiple roles, use highest priority role
4. Deny if no role grants permission

REQ-070-080: A permission check SHALL evaluate the user's direct role permissions, then the permissions inherited from parent team roles, SHALL use the highest-priority role when several apply, and SHALL deny when no role grants the permission.

Team Deletion Cascade

Cascade Levels

REQ-070-081: Team deletion SHALL cascade through the stated levels — team memberships soft-deleted with a migration option, team roles soft-deleted, and team settings, quotas and custom permissions deleted — and SHALL handle team resources by the configured action of delete, migrate or preserve.

Cascade Flow

Team Deletion Flow:
1. Validate deletion prerequisites
2. Create backup (if enabled)
3. Lock team for modifications
4. Process child teams (recurse or block)
5. Migrate or remove members
6. Handle dependent resources
7. Soft-delete or hard-delete team
8. Update audit trail
9. Send notifications
10. Release reserved slug after recovery window

REQ-070-082: Team deletion SHALL follow the ordered flow: validate the deletion prerequisites, create the backup when enabled, lock the team for modifications, process child teams by recursion or block, migrate or remove members, handle dependent resources, soft-delete or hard-delete the team, update the audit trail, send notifications, and release the reserved slug after the recovery window.

Access Control Matrix

REQ-070-083: The system SHALL enforce the access control matrix above — SUPER_ADMIN may perform every listed operation; TENANT_ADMIN may perform every listed operation within its tenant; TEAM_ADMIN may delete, update, manage the roles of and view the audit logs of its own team, and may list teams and invite or remove members; TEAM_MEMBER may list only the teams it belongs to; and VIEWER may only list teams.

Security Controls

• Authentication: All API requests require valid JWT token
• Authorization: Role-based access control with permission checks
• Audit Logging: All team operations logged with user, timestamp, IP
• Rate Limiting: 100 requests per minute per user
• Input Validation: All inputs validated against schemas
• SQL Injection Prevention: Parameterized queries only
• Slug Reservation: Prevented during soft-delete recovery window

REQ-070-084: Every API request SHALL carry a valid JWT token.

REQ-070-085: Authorization SHALL be enforced by role-based access control with explicit permission checks.

REQ-070-086: All team operations SHALL be audit-logged with the acting user, the timestamp and the IP address.

REQ-070-087: The service SHALL rate-limit each user to 100 requests per minute.

REQ-070-088: All inputs SHALL be validated against their schemas.

REQ-070-089: Database access SHALL use parameterized queries only.

REQ-070-090: A team slug SHALL remain reserved for the duration of the soft-delete recovery window.

Testing Requirements

Unit Tests

TeamCreateTool Tests

REQ-070-091: The TeamCreateTool SHALL be covered by unit tests TC-UT-001 through TC-UT-010 asserting valid creation with default roles, TEAM_SLUG_CONFLICT on a duplicate slug, TEAM_NAME_INVALID and TEAM_SLUG_INVALID on bad formats, PARENT_TEAM_NOT_FOUND, QUOTA_EXCEEDED, correct application of custom settings, an established hierarchy when a parent team is given, PERMISSION_DENIED, and OWNER_NOT_FOUND.

TeamDeleteTool Tests

REQ-070-092: The TeamDeleteTool SHALL be covered by unit tests TD-UT-001 through TD-UT-010 asserting recoverable soft delete, permanent hard delete, member migration to the target, resource cascade, TEAM_NOT_FOUND, TEAM_ALREADY_DELETED, CHILD_TEAMS_EXIST and RESOURCES_IN_USE except under force, MIGRATION_TARGET_INVALID, and successful force deletion despite dependencies.

Integration Tests

REQ-070-093: The module SHALL be covered by integration tests TC-IT-001 through TC-IT-006 exercising the full team lifecycle, cross-team permission inheritance, deletion of a team with more than 1000 members, concurrent team operations, a team hierarchy of 5 or more levels, and role permission conflict resolution.

Security Tests

REQ-070-094: The module SHALL be covered by security tests TC-ST-001 through TC-ST-006 exercising unauthorized team creation, cross-tenant team access, role privilege escalation, SQL injection in team parameters, XSS in the team description, and bulk deletion permission bypass.

Performance Tests

REQ-070-095: The module SHALL be covered by performance tests TC-PT-001 through TC-PT-005 asserting team creation under 500 ms p99, team deletion under 2 s p99, listing of 1000 teams under 1 s p99, permission checks under 50 ms p99, and ten parallel creates under 5 s in total.

Dependencies

Direct Dependencies

REQ-070-096: The module SHALL depend on orchestrata-core >=2.0.0 for core platform abstractions, orchestrata-auth >=1.5.0 for authentication and authorization, orchestrata-database >=3.0.0 for database migrations and queries, orchestrata-audit >=1.0.0 for audit logging, and orchestrata-notifications >=1.2.0 for notification delivery.

External Dependencies

REQ-070-097: The module SHALL run against PostgreSQL >=14.0 as the primary data store, Redis >=7.0 for caching and rate limiting, and Kafka >=3.0 for event streaming.

Dev Dependencies

REQ-070-098: The module SHALL be developed against pytest >=7.0.0, pytest-asyncio >=0.21.0, pytest-cov >=4.0.0, ruff >=0.1.0 and mypy >=1.0.0.

Observability

Logging Requirements

1. Component Logging
   • Log all major operations with appropriate log levels
   • Include correlation IDs for request tracing
   • Log performance metrics for critical operations
   • Log errors with full context for debugging

REQ-070-155: The module SHALL log all major operations at appropriate log levels, SHALL include correlation IDs for request tracing, SHALL log performance metrics for critical operations, and SHALL log errors with full context for debugging.

Metrics Requirements

1. Performance Metrics
   • Operation duration histograms
   • Request/error rate counters
   • Resource utilization gauges
   • Business metrics relevant to domain

REQ-070-156: The module SHALL expose operation duration histograms, request and error rate counters, resource utilization gauges, and the business metrics relevant to the team domain.

Tracing Requirements

1. Distributed Tracing
   • Trace propagation across component boundaries
   • Span attributes for domain-specific context
   • Trace sampling based on operational needs

REQ-070-157: The module SHALL propagate traces across component boundaries, SHALL attach domain-specific span attributes, and SHALL sample traces according to operational needs.

Alerting Requirements

1. Critical Alerts
   • Error rate spikes
   • Performance degradation
   • Resource exhaustion
   • Business metric anomalies

REQ-070-158: The module SHALL raise critical alerts on error rate spikes, performance degradation, resource exhaustion and business metric anomalies.

Dashboard Requirements

1. Operational Dashboard
   • Real-time system health
   • Performance trends
   • Error analysis
   • Resource monitoring

REQ-070-159: The module SHALL provide an operational dashboard showing real-time system health, performance trends, error analysis and resource monitoring.

Revision History

References

• SPEC-001: Core Architecture
• SPEC-010: Authentication
• SPEC-020: Authorization Model
• SPEC-060: Resource Management
• RFC 2119: Key Words for Use in RFCs
• JSON Schema Draft-07

Related

• RTM page for 070-team-tools
• All specs
• RTM overview
• Gates