Organizing Your Implementers with Teams

In Catalio, a Team is a named group of users who share responsibility for implementing requirements. Teams provide the organizational structure that connects your people to your work, enabling clear accountability, efficient coordination, and meaningful performance tracking.

Unlike simple user assignments, teams provide:

Functional Organization: Group specialists by domain expertise (Backend, Frontend, QA, DevOps)
Clear Accountability: Know exactly which team owns each requirement
Coordination Framework: Track dependencies and handoffs between teams
Performance Metrics: Measure team throughput, quality, and velocity
Organizational Boundaries: Multi-tenant isolation ensures teams stay within their organization

Why Teams Matter

The Challenge Without Teams

Imagine managing a large implementation project with individual user assignments:

❌ Assignment Chaos

“Who’s working on the API requirements?” → “Let me check each requirement individually…”
User goes on vacation → Reassign 20 requirements one by one
New developer joins → No clear context on what their group is building

❌ Coordination Overhead

Backend work blocking frontend? → No systematic way to identify cross-assignment dependencies
Multiple people working on related requirements → No visibility into team capacity

❌ Reporting Nightmare

“How is the backend team performing?” → Manual aggregation across scattered assignments
“Which teams are bottlenecks?” → Impossible to answer systematically

The Power of Team-Based Organization

✅ Functional Clarity

Salesforce Implementation Team
├─ REQ-001: Custom Object Design (In Development)
├─ REQ-002: Validation Rules (Deployed)
├─ REQ-003: Workflow Automation (In Testing)
└─ REQ-004: Permission Sets (Pending)

ServiceNow ITSM Team
├─ REQ-010: Incident Management Flow (Deployed)
├─ REQ-011: Change Request Workflow (In Development)
└─ REQ-012: CMDB Integration (In Testing)

✅ Simplified Management

“Salesforce team is at 75% capacity” → Immediately visible across all requirements
Team member changes → Team assignment remains stable, internal allocation flexible
New requirement? → Assign to appropriate team based on domain expertise

✅ Automatic Metrics

Team throughput: 12 requirements deployed in Q1
Team velocity: Average 2 weeks from assigned → deployed
Team quality: 5% rollback rate (industry-leading)
Team blocking impact: Frontend waiting on Backend for 3 requirements

Team Structure: Simple but Powerful

Teams in Catalio have a minimal, focused structure:

Core Attributes

Name (required)

Human-readable identifier for the team
Must be unique within your organization
Examples: “Salesforce Implementation Team”, “Backend API Team”, “QA Automation Team”

Description (optional)

Explains the team’s purpose, domain, and responsibilities
Helps new users understand which team to assign work to
Documents specialized skills or focus areas

Organization (required)

Every team belongs to exactly one organization
Multi-tenant isolation: Teams cannot see or interact with other organizations’ teams
Ensures security and data privacy in multi-tenant deployments

Database Design

teams
├─ id (UUID v7, primary key)
├─ name (string, not null)
├─ description (string, nullable)
├─ organization_id (UUID, not null)
├─ created_by_id (UUID, audit trail)
├─ updated_by_id (UUID, audit trail)
├─ inserted_at (timestamp)
├─ updated_at (timestamp)
└─ archived_at (timestamp, soft delete)

Unique constraint: [organization_id, name]

Design Rationale: Catalio’s team model is intentionally lightweight. Teams are organizational labels that group work, not complex entities with membership rosters. This simplicity enables fast queries, flexible coordination, and easy reorganization as your needs evolve.

Creating and Managing Teams

Creating a Team

Minimum Requirements:

Name: Clear, descriptive identifier
Organization: Automatically set based on your authenticated user
Actor: User creating the team (captured for audit trail)

Best Practice Naming Conventions:

Function-Based:

“Backend Engineering Team”
“Frontend Development Team”
“QA Automation Team”
“DevOps Infrastructure Team”
“Security Compliance Team”

Domain-Based:

“Salesforce Implementation Team”
“ServiceNow ITSM Team”
“Workday Integrations Team”
“Power BI Reporting Team”

Product-Based:

“Customer Portal Team”
“Admin Dashboard Team”
“Mobile App Team”
“API Platform Team”

Hybrid:

“Salesforce Backend Team” (domain + function)
“Mobile QA Team” (product + function)
“Platform Architecture Team” (product + function)

Choose naming conventions that match your organizational structure and make team ownership obvious at a glance.

Team Descriptions: Adding Context

Great team descriptions answer these questions:

What is the team’s domain?

"Salesforce Implementation Team: Responsible for all Salesforce platform
customizations including custom objects, validation rules, workflows,
and integrations."

What specialized skills does the team have?

"Platform Architecture Team: Cross-functional team of senior engineers
specializing in system design, API architecture, data modeling, and
performance optimization across all products."

What boundaries define the team’s work?

"ServiceNow ITSM Team: Manages incident management, change request, and
problem management workflows in ServiceNow. Does NOT handle CMDB or
asset management (owned by Configuration Team)."

Pro Tip: Document what the team does AND what it doesn’t do. Clear boundaries prevent confusion and duplicate work.

Updating Teams

Teams can be updated to reflect organizational changes:

Allowed Updates:

✅ Name changes (if team rebrands or restructures)
✅ Description updates (refine responsibilities over time)

Immutable Attributes:

❌ Organization ID (teams cannot move between organizations)
❌ Created metadata (preserved for audit trail)

Audit Trail: All updates are tracked with:

updated_by_id: Who made the change
updated_at: When the change occurred
Version history via AshPaperTrail

Archiving Teams

Teams use soft delete via the archived_at timestamp:

When to Archive:

Team no longer exists (reorganization)
Work domain is discontinued
Team merged into another team

What Happens:

Team hidden from normal views
Historical data preserved (audit trail, reporting)
Existing ProcessRequirement assignments remain intact
Cannot create new assignments to archived teams

Why Soft Delete? Historical reporting requires team data. Archiving preserves “which team deployed this in Q2 2024?” while keeping your active workspace clean.

Assigning Teams to Requirements

Teams are assigned to requirements through the ProcessRequirement join resource, not directly on requirements. This design provides critical flexibility.

Why Process-Level Assignment?

The Insight: The same requirement might be implemented by different teams in different contexts.

Example Scenario:

Requirement: “REQ-050: User Authentication API”

Process A: “Customer Portal MVP” → Assigned to Backend Team
Process B: “Mobile App Launch” → Assigned to Mobile Backend Team
Process C: “Admin Dashboard v2” → Assigned to Platform Team

The requirement is reused, but different teams handle implementation depending on the process context.

Benefits:

✅ Requirements remain reusable across processes
✅ Team assignment reflects actual project structure
✅ Same requirement tracks different deployment states per process
✅ Accurate team performance metrics per process

The ProcessRequirement Model

When you assign a team to a requirement in a process, ProcessRequirement captures:

ProcessRequirement {
  process_id: UUID              // Which workflow
  requirement_id: UUID          // Which capability
  team_id: UUID                 // Which team implements it
  order: integer                // Sequence in workflow
  step_label: string            // "Phase 1", "MVP", etc.
  deployment_state: atom        // :pending, :in_development, :deployed, etc.
  is_optional: boolean          // Required vs optional
  dependencies: map             // Team coordination needs
  organization_id: UUID         // Multi-tenant boundary
}

Assignment Best Practices

Assign Based on Domain Expertise:

Database Migration → Infrastructure Team
API Development → Backend Team
UI Implementation → Frontend Team
Security Review → Security Team
Documentation → Technical Writing Team

Respect Team Capacity:

Monitor team workload across all processes
Distribute requirements to prevent bottlenecks
Use deployment metrics to identify overloaded teams

Document Dependencies:

{
  "infrastructure_team_id": {
    "type": "blocking",
    "description": "Database schema must be deployed before API development"
  },
  "security_team_id": {
    "type": "non_blocking",
    "description": "Security review in parallel, feedback addressed iteratively"
  }
}

Blocking vs Non-Blocking:

Blocking: Team A cannot proceed until Team B completes their work
Non-Blocking: Teams work in parallel, coordinate iteratively

Team Coordination via Processes

Processes are where teams collaborate to deliver complex features.

Sequential Team Handoffs

Pattern: Requirements flow from team to team in order.

Example: API Feature Implementation

Order 1: "REQ-001: Database Schema"
         → Infrastructure Team (BLOCKING next steps)

Order 2: "REQ-002: Backend API Endpoints"
         → Backend Team (depends on #1)

Order 3: "REQ-003: Frontend Components"
         → Frontend Team (depends on #2)

Order 4: "REQ-004: E2E Tests"
         → QA Team (depends on #3)

Order 5: "REQ-005: Production Deployment"
         → DevOps Team (depends on #4)

Coordination Mechanism:

Infrastructure deploys database schema
Backend team watches deployment state → starts when schema shows :deployed
Frontend team watches backend deployment → starts when APIs show :deployed
Clear handoff chain with deployment state visibility

Parallel Team Work

Pattern: Multiple teams work simultaneously on independent requirements.

Example: Multi-Workstream Project

Order 1 (Parallel):
├─ "REQ-010: CI/CD Pipeline" → DevOps Team
├─ "REQ-011: Test Framework Setup" → QA Team
└─ "REQ-012: Design System" → Frontend Team

Order 2 (After All Order 1 Complete):
└─ "REQ-020: Feature Implementation" → Full Stack Team (depends on all)

Coordination Benefits:

Maximize parallel work to compress timeline
Clear dependencies prevent premature starts
Deployment tracking shows when all prerequisites complete

Cross-Team Dependencies

Use the dependencies JSONB field to document coordination needs:

Backend Team’s Requirement:

{
  "dependencies": {
    "infrastructure_team_id": {
      "type": "blocking",
      "description": "Cannot deploy API without database migration"
    },
    "security_team_id": {
      "type": "non_blocking",
      "description": "Security review findings addressed in next sprint"
    }
  }
}

Queries Enabled:

“Show all requirements blocked by Infrastructure Team”
“Which teams have non-blocking dependencies on Security?”
“What’s blocking Backend Team from deploying?”

Team Metrics and Reporting

Catalio automatically aggregates team performance data from ProcessRequirement assignments.

Core Team Metrics

Throughput: Requirements Completed

Salesforce Team Q1 2025:
- Total Assigned: 24 requirements
- Deployed: 18 requirements
- In Progress: 4 requirements
- Pending: 2 requirements
- Throughput: 18 deployed / 13 weeks = 1.38 per week

Velocity: Cycle Time

Average time from assignment → deployed:
- Backend Team: 12 days (excellent)
- Frontend Team: 18 days (good)
- DevOps Team: 8 days (outstanding)
- QA Team: 25 days (investigate bottleneck)

Quality: Rollback Rate

Deployments rolled back / Total deployments:
- Backend Team: 2/18 = 11% (investigate issues)
- Frontend Team: 0/15 = 0% (excellent)
- DevOps Team: 1/22 = 4.5% (good)

Blocking Impact

How often this team's delays block other teams:
- Infrastructure Team: Blocking 6 requirements (high impact)
- Security Team: Blocking 0 requirements (non-blocking reviews)
- Backend Team: Blocking 3 requirements (medium impact)

Team Performance Dashboard

Team Overview:

Salesforce Implementation Team
├─ Active Processes: 3
├─ Assigned Requirements: 24
│   ├─ Pending: 2
│   ├─ In Development: 4
│   ├─ In Testing: 6
│   └─ Deployed: 12
├─ Deployment Rate: 50% (12/24)
├─ Average Cycle Time: 16 days
├─ Rollback Rate: 8.3% (1/12)
└─ Blocking: 2 other teams

Trend Analysis:

Month-over-Month:
- Throughput: ↑ 15% (10 → 11.5 per month)
- Cycle Time: ↓ 12% (18 days → 16 days)
- Quality: ↑ (rollbacks 12% → 8%)
- Team improving across all dimensions ✓

Team Comparison

Cross-Team Performance:

Team	Assigned	Deployed	Rate	Cycle Time	Rollbacks
Backend	32	24	75%	12 days	2 (8%)
Frontend	28	21	75%	18 days	0 (0%)
DevOps	18	16	89%	8 days	1 (6%)
QA	22	14	64%	25 days	1 (7%)

Insights:

DevOps most efficient (89% deployment rate, 8-day cycle)
QA bottleneck (64% rate, 25-day cycle) → investigate capacity
Frontend highest quality (0% rollbacks)
Backend solid performance across metrics

Action Items:

Add QA capacity or reduce assignment rate
Study DevOps processes for best practice transfer
Recognize Frontend team for quality excellence

Multi-Tenant Isolation: Organization Boundaries

Teams are strictly isolated by organization for security and privacy.

Multi-Tenancy Rules

1. Team Creation:

# Policy: organization_id must match actor's organization
policy action_type(:create) do
  authorize_if changing_attributes(organization_id: [to: actor(:organization_id)])
end

You can only create teams in your organization.

2. Team Access:

# Policy: Can only read/update/delete teams in your organization
policy action_type([:read, :update, :destroy]) do
  authorize_if expr(^actor(:organization_id) == organization_id)
end

You can only see and modify teams in your organization.

3. Cross-Organization Protection:

Organization A cannot:

❌ View Organization B’s teams
❌ Assign Organization B’s teams to their processes
❌ See performance metrics from Organization B’s teams
❌ Access any data about Organization B’s teams

Database Enforcement:

-- Multi-tenancy via attribute strategy
WHERE organization_id = :current_user_organization_id

-- Unique constraint scoped to organization
UNIQUE (organization_id, name)

Why This Matters:

In multi-tenant SaaS deployments:

Prevents data leakage between organizations
Enables team name reuse across organizations (“Backend Team” can exist in multiple orgs)
Simplifies authorization (organization membership = access)
Supports compliance requirements (data isolation)

Team Examples: Patterns That Work

Example 1: Salesforce Implementation Team

Name: “Salesforce Implementation Team”

Description:

Responsible for all Salesforce platform customizations including:
- Custom objects and fields
- Validation rules and formula fields
- Workflows and Process Builder flows
- Lightning components and Visualforce pages
- Apex triggers and classes
- API integrations with Salesforce

This team does NOT handle:
- Salesforce administration (user management, security)
- Data migration (owned by Data Team)
- Third-party AppExchange app configuration

Typical Requirements:

“REQ-101: Custom Account Validation Rules”
“REQ-102: Opportunity Pipeline Automation”
“REQ-103: Case Assignment Workflow”
“REQ-104: Lightning Web Component for Dashboard”

Process Assignment Example:

Process: “Q1 2025 Salesforce Enhancements”

REQ-101 → Salesforce Team (Order 1, Required)
REQ-102 → Salesforce Team (Order 2, Required)
REQ-103 → Salesforce Team (Order 3, Optional)
REQ-104 → Salesforce Team (Order 4, Required)

Deployment Tracking:

Week 1: REQ-101 → In Development
Week 2: REQ-101 → Deployed, REQ-102 → In Development
Week 3: REQ-102 → Deployed, REQ-103 → Skipped (optional), REQ-104 → In Development
Week 4: REQ-104 → Deployed, Process → Active

Metrics (Quarterly):

Throughput: 18 Salesforce requirements deployed
Cycle Time: 14 days average
Quality: 5% rollback rate (1 rolled back validation rule)

Example 2: ServiceNow ITSM Team

Name: “ServiceNow ITSM Team”

Description:

Manages IT Service Management workflows in ServiceNow including:
- Incident management processes
- Change request workflows
- Problem management procedures
- Service catalog items
- SLA definitions and notifications
- ITSM reporting and dashboards

Coordinates with:
- Configuration Team (CMDB and asset management)
- Integration Team (external system connections)

Typical Requirements:

“REQ-201: Automated Incident Routing Rules”
“REQ-202: Change Request Approval Workflow”
“REQ-203: P1 Incident SLA Configuration”
“REQ-204: Self-Service Portal Catalog”

Process Assignment Example:

Process: “ServiceNow ITSM Optimization”

REQ-201 → ServiceNow ITSM Team (Order 1, Required, depends on Configuration Team)
REQ-202 → ServiceNow ITSM Team (Order 2, Required)
REQ-203 → ServiceNow ITSM Team (Order 1, Required, parallel with REQ-201)
REQ-204 → ServiceNow ITSM Team (Order 3, Optional)

Dependencies:

{
  "configuration_team_id": {
    "type": "blocking",
    "description": "CMDB assignment groups must be configured before incident routing"
  }
}

Coordination:

Configuration Team deploys CMDB updates first
ServiceNow ITSM Team watches for :deployed state
Parallel work on SLA configuration (no dependencies)
Sequential work on self-service catalog after workflows stable

Example 3: Platform Architecture Team

Name: “Platform Architecture Team”

Description:

Cross-functional team of senior engineers responsible for:
- System architecture and design patterns
- API design and standards
- Data modeling and database architecture
- Performance optimization and scalability
- Security architecture and threat modeling
- Technology evaluation and selection

This is a consulting/review team, not an implementation team.
Works across all product teams to ensure architectural consistency.

Typical Requirements:

“REQ-301: Design Microservices Communication Pattern”
“REQ-302: Define API Versioning Strategy”
“REQ-303: Establish Database Sharding Approach”
“REQ-304: Security Review of Authentication Flow”

Process Assignment Example:

Process: “Platform Modernization Initiative”

REQ-301 → Platform Architecture Team (Order 1, Required, BLOCKING all downstream)
REQ-302 → Platform Architecture Team (Order 2, Required, depends on #1)
REQ-303 → Platform Architecture Team (Order 1, Required, parallel with REQ-301)
REQ-304 → Platform Architecture Team (Order 3, Non-blocking review)

Dependencies in Downstream Work:

{
  "platform_architecture_team_id": {
    "type": "blocking",
    "description": "Backend team cannot start API development until architecture patterns approved"
  }
}

Unique Pattern:

Platform team defines standards → Other teams implement
Blocking dependencies common (architecture decisions gate implementation)
Lower throughput (thinking work, not building work)
High impact per requirement (decisions affect entire organization)

Metrics (Quarterly):

Throughput: 8 architecture requirements completed (lower volume, higher impact)
Cycle Time: 21 days average (longer due to review cycles)
Blocking Impact: High (gates 24 downstream implementation requirements)
Quality: 0% rollback (architecture designs validated before implementation)

Best Practices for Team Organization

Team Design Principles

Do:

✅ Align with organizational structure: Teams should match how work is actually organized
✅ Keep teams focused: Each team has clear domain boundaries
✅ Use consistent naming: Adopt conventions and stick to them
✅ Document boundaries: What the team does AND doesn’t do
✅ Size appropriately: 5-10 people per team is typical (but Catalio doesn’t enforce this)
✅ Plan for dependencies: Document blocking vs non-blocking relationships

Don’t:

❌ Create teams for one-off projects: Teams should be durable organizational units
❌ Over-specialize: “Backend Team” is better than “Node.js Express API Team” (too narrow)
❌ Leave boundaries ambiguous: “Platform Team” vs “Infrastructure Team” should be clearly distinguished
❌ Ignore existing structure: Create teams that match reality, not idealized org charts
❌ Forget multi-tenant isolation: Team names can collide across organizations (by design)

Team Naming Best Practices

Clear > Clever

✅ “Salesforce Implementation Team”
❌ “The Force Be With You Team”

Function > People

✅ “Backend Engineering Team”
❌ “Sarah’s Team”

Durable > Temporary

✅ “Mobile Development Team”
❌ “Q1 2025 Mobile Sprint Team”

Specific > Generic

✅ “ServiceNow ITSM Team”
❌ “Integration Team” (which integrations?)

Assignment Strategy

Match Domain Expertise:

Database requirements → Data Engineering Team
UI requirements → Frontend Team
API requirements → Backend Team
Security requirements → Security Team

Balance Team Capacity:

Backend Team: 12 active requirements (80% capacity)
Frontend Team: 8 active requirements (60% capacity)
→ Assign next full-stack requirement to Frontend

Minimize Dependencies:

❌ Avoid: 5 teams with complex blocking dependencies
✅ Prefer: 2-3 teams with clear sequential handoffs

Document Coordination:

{
  "team_id": {
    "type": "blocking | non_blocking",
    "description": "Explain exactly what and why"
  }
}

Performance Monitoring

Track Leading Indicators:

Assignment backlog growing? (capacity issue)
Cycle time increasing? (process inefficiency)
Blocking dependencies accumulating? (coordination breakdown)

Celebrate Wins:

Team deployed 10 requirements with 0 rollbacks → Recognize quality
Team reduced cycle time 20% quarter-over-quarter → Share best practices
Team unblocked 5 other teams ahead of schedule → Highlight coordination

Address Problems:

Team consistently missing deadlines → Investigate capacity/process
Team high rollback rate → Review testing practices
Team blocking others frequently → Examine dependencies/handoffs

Reorganization

Teams are flexible organizational labels. When structure changes:

Option 1: Rename Existing Team

"Backend Team" → "API Platform Team"
- Preserves historical data
- Updates all future views
- Audit trail shows name change

Option 2: Create New Team, Archive Old

Archive: "Monolith Engineering Team"
Create: "Microservices Team A", "Microservices Team B"
- Clear historical boundary
- New assignments go to new teams
- Old assignments preserved under old team

Option 3: Merge Teams

Archive: "Frontend Web Team", "Frontend Mobile Team"
Create: "Frontend Engineering Team"
- Consolidate related domains
- Historical data preserved
- Simplified going forward

Choose based on continuity needs: Rename when it’s the same team with a new name, archive+create when it’s truly a different organizational structure.

Integration with Processes and Requirements

The Complete Flow

1. Define Teams (Organizational Setup)

Create team: "Salesforce Implementation Team"
Create team: "QA Automation Team"
Create team: "DevOps Team"

2. Define Requirements (Capability Library)

REQ-001: "Custom Validation Rules"
REQ-002: "Automated Test Suite"
REQ-003: "Production Deployment Pipeline"

3. Build Process (Implementation Workflow)

Process: "Salesforce Enhancement Q1"
├─ Order 1: REQ-001 → Salesforce Implementation Team
├─ Order 2: REQ-002 → QA Automation Team (depends on #1)
└─ Order 3: REQ-003 → DevOps Team (depends on #2)

4. Execute and Track (Real-Time Progress)

Week 1:
  REQ-001: Pending → In Development (Salesforce Team)

Week 2:
  REQ-001: In Development → Deployed
  REQ-002: Pending → In Development (QA Team, unblocked)

Week 3:
  REQ-002: In Development → Deployed
  REQ-003: Pending → In Development (DevOps, unblocked)

Week 4:
  REQ-003: In Development → Deployed
  Process: Active ✓

5. Measure and Improve

Metrics:
- Salesforce Team: 1 requirement, 7 days cycle time
- QA Team: 1 requirement, 7 days cycle time
- DevOps Team: 1 requirement, 7 days cycle time
- Process: 4 weeks total (3 weeks sequential + 1 week buffer)

Lessons:
- Sequential dependencies added 2 weeks vs parallel approach
- Next time: Can QA prepare test framework in parallel with development?
- Update process template with optimization

Traceability Chain

Teams complete the end-to-end traceability:

Business Need: "Improve data quality in Salesforce"
    ↓
Persona: "Data Steward" (who needs this)
    ↓
Requirement: "REQ-001: Custom Account Validation Rules" (what to build)
    ↓
Use Cases: "Validate email format", "Require phone on Enterprise accounts"
    ↓
Process: "Q1 Data Quality Initiative" (how to deliver)
    ↓
Team: "Salesforce Implementation Team" (who builds it)
    ↓
Deployment: "Deployed to Production 2025-01-15" (delivery confirmation)

Every capability can be traced from business value → specification → implementation team → production delivery.

Next Steps

Now that you understand teams, explore how to:

Build Processes - Orchestrate requirements with team assignments
Track Deployments - Monitor team progress from development to production
Define Requirements - Create capabilities that teams implement
Manage Performance - Measure and improve team effectiveness

Pro Tip: Start with 3-5 teams that match your existing structure. Don’t over-engineer the team model—simple, durable teams aligned with real organizational boundaries work best. You can always refine as you learn.

Support

Questions about teams? We’re here to help:

Documentation: Continue reading about Processes and Deployment Tracking
In-App Help: Look for the 🤖 AI assistant in the teams interface
Email: support@catalio.com
Community: Share team organizational patterns with other Catalio users