NV oOS Pro Toolkit Team Management

The Pro Toolkit Team Management system provides organizational structure built on WordPress Custom Post Types. It defines the hierarchy: professions (specialties) → teams (organizational units) → users (team members). All entities are stored as CPT records accessible via the toolkit_cpt MCP tool.

WP-CLI Commands

Key mcp-ai WP-CLI commands for team management operations. Run via terminal:

Command	Use for
wp mcp-ai cron	Check team sync cron events (user-to-team assignments, role propagation)
wp mcp-ai queue	Inspect team import/export background jobs
wp mcp-ai health	Verify team structure integrity, orphaned members, missing professions
wp mcp-ai log	View team assignment and role change logs
wp user list --role=<role>	List WordPress users by role for team assignment planning

When to use this skill

Trigger when ANY of the following is true:

• Creating, updating, or deleting teams (organizational units).
• Defining or modifying professional roles and specialties.
• Assigning users to teams or professions.
• Reviewing organizational structure — which teams exist, who belongs to them.
• Searching for teams by name, profession, or membership.
• Building team hierarchies (parent/child teams, departments, divisions).
• Onboarding new staff — creating their profession record and team assignment.
• Auditing team composition for role coverage gaps.
• Managing profession metadata like thumbnails, descriptions, and required skills.

Mental model — Teams and professions

The team management system is organized around two entity types in a many-to-many relationship:

PROFESSION ──(defines role)──→ USER ←──(belongs to)── TEAM
     │                                                    │
     ├── title (specialty name)                          ├── title (team name)
     ├── editor (rich description)                       ├── editor (team description)
     └── thumbnail (icon/badge)                          └── members (via user meta or CPT links)

Relationships:

• A Profession (mcp_ai_profession) represents a role, specialty, or job function (e.g., "Cardiologist", "Frontend Developer", "Project Manager").
• A Team (mcp_ai_team) represents an organizational unit, department, or project group (e.g., "Cardiology Department", "Engineering Team Alpha").
• Users are WordPress user accounts. Team membership and profession are typically stored as user meta or linked via additional CPT relationships.
• One user can belong to multiple teams and hold one or more professions.
• Teams can have hierarchical relationships (parent/child) for departments and sub-teams, managed via the standard WordPress post_parent field.

Team Management Entity Types

All team management entities are managed through the toolkit_cpt MCP tool. Use the appropriate post_type slug for each entity:

CPT Slug	Label	Purpose	Supported Fields
mcp_ai_team	Teams	Organizational units, departments, project groups	title, editor (content), post_parent (hierarchy)
mcp_ai_profession	Professions	Professional roles, specialties, job functions	title, editor (content), thumbnail (featured image)

Team Fields (detailed)

Field	Type	Description	Example
title	string	Team name	"Cardiology Department", "Engineering Team Alpha"
content	string	Team description, mission, or charter	Rich text describing the team's purpose and scope
post_parent	integer	Parent team ID for hierarchy	15 (parent team post ID)
status	string	Post status	"publish", "draft"
author_id	integer	WordPress user ID of the team lead or creator	7

Profession Fields (detailed)

Field	Type	Description	Example
title	string	Profession name	"Cardiologist", "Senior Frontend Developer"
content	string	Role description, responsibilities, required qualifications	Rich text describing the role
thumbnail	integer	Featured image attachment ID (badge, icon, or photo)	205
status	string	Post status	"publish", "draft"
author_id	integer	WordPress user ID of the role creator	1

Available Tools

All team management operations use the toolkit_cpt MCP tool. This is the single interface for all team and profession CRUD operations.

Discovery

# List all available team management post types
toolkit_cpt(action: "list_types")

# Get field schema for teams or professions
toolkit_cpt(action: "get_schema", post_type: "mcp_ai_team")
toolkit_cpt(action: "get_schema", post_type: "mcp_ai_profession")

Reading records

// List all teams
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_ai_team",
    "orderby": "title",
    "order": "ASC",
    "per_page": 50,
    "page": 1
  }
}

// Search teams by name
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_ai_team",
    "search": "Cardiology"
  }
}

// List all professions
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_ai_profession",
    "orderby": "title",
    "order": "ASC",
    "per_page": 50
  }
}

// Search professions by name
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_ai_profession",
    "search": "Developer"
  }
}

// Get a single team or profession
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "get_item",
    "post_type": "mcp_ai_team",
    "item_id": 42
  }
}

Creating records

// Create a new team
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "create_item",
    "post_type": "mcp_ai_team",
    "fields": {
      "title": "Cardiology Department",
      "content": "The Cardiology Department provides comprehensive cardiac care including diagnostics, interventional procedures, and long-term heart health management.",
      "status": "publish"
    }
  }
}

// Create a child team (sub-team under a parent)
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "create_item",
    "post_type": "mcp_ai_team",
    "fields": {
      "title": "Interventional Cardiology Unit",
      "content": "Specialized unit within Cardiology handling catheter-based procedures.",
      "status": "publish",
      "post_parent": 42
    }
  }
}

// Create a new profession
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "create_item",
    "post_type": "mcp_ai_profession",
    "fields": {
      "title": "Interventional Cardiologist",
      "content": "Board-certified cardiologist specializing in catheter-based treatment of structural heart diseases. Requires fellowship training in interventional cardiology.",
      "status": "publish"
    }
  }
}

Updating records

// Rename a team
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "update_item",
    "post_type": "mcp_ai_team",
    "item_id": 42,
    "fields": {
      "title": "Cardiology & Vascular Department"
    }
  }
}

// Update a profession's description and thumbnail
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "update_item",
    "post_type": "mcp_ai_profession",
    "item_id": 88,
    "fields": {
      "title": "Senior Interventional Cardiologist",
      "content": "Updated: Requires 5+ years post-fellowship experience. Leads complex structural heart interventions including TAVR and MitraClip procedures."
    }
  }
}

// Re-parent a team (move under a different parent)
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "update_item",
    "post_type": "mcp_ai_team",
    "item_id": 55,
    "fields": {
      "post_parent": 99
    }
  }
}

Deleting records

// Delete a team
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "delete_item",
    "post_type": "mcp_ai_team",
    "item_id": 42
  }
}

⚠️ Warning: Deleting a team is permanent. Before deleting, reassign any member users and re-parent any child teams. Consider archiving via status: "draft" instead, to preserve organizational history.

Common Workflows

Setting up organizational structure

1. Define professions:    create_item(mcp_ai_profession) for each role in the organization.
2. Create top-level teams:  create_item(mcp_ai_team) for departments or divisions.
3. Create sub-teams:        create_item(mcp_ai_team, post_parent: <parent_id>) for units.
4. Verify hierarchy:        list_items(mcp_ai_team, orderby: "title")
                            → Review the parent-child structure for correctness.
5. Assign users:            Link WordPress users to teams via user meta or assignment CPT.
6. Set team lead:           update_item(mcp_ai_team, author_id: <user_id>) for the team lead.

Onboarding a new team member

1. Verify profession:    get_item(mcp_ai_profession, item_id: <profession_id>)
                         If the role doesn't exist yet: create_item(mcp_ai_profession).
2. Verify team:          get_item(mcp_ai_team, item_id: <team_id>)
3. Assign user:          Link the WordPress user to the team (via user meta or CPT).
4. Set profession:       Assign the user's profession (user meta or role assignment CPT).
5. Document:             Add user details to team's content or a team membership log.

Organizational audit

1. List all teams:         list_items(mcp_ai_team, per_page: 50)
2. List all professions:   list_items(mcp_ai_profession, per_page: 50)
3. Check for gaps:         Identify teams with no assigned members or vacant professions.
4. Check for orphans:      Find child teams whose post_parent references a deleted team.
5. Review stale records:   Find unpublished (draft/trash) teams and professions — archive or clean up.

Restructuring — merging teams

1. Identify source team:   get_item(mcp_ai_team, item_id: <source_id>)
2. Identify target team:   get_item(mcp_ai_team, item_id: <target_id>)
3. Reassign child teams:   For each child of source, update_item(post_parent: <target_id>)
4. Reassign members:       Move all users from source team to target team.
5. Archive source:         update_item(mcp_ai_team, item_id: <source_id>, status: "draft")
                           OR delete_item if the team is truly obsolete.

Critical Rules

• Always use get_schema first before creating or updating a record to verify available field keys and types.
• Team names must be unique within the same parent — two sibling teams cannot share the same title.
• post_parent creates hierarchy — use it for departments → units, not for loose organizational tags. The parent must exist before a child references it.
• Profession title should be singular and descriptive — use "Cardiologist" not "Cardiology" (that's a team name) and not "Cardiologists" (that's a plural).
• Do not delete a team that has children — re-parent child teams first, or delete children bottom-up.
• status field controls visibility — use "publish" for active teams/professions and "draft" for planned, inactive, or archived ones.
• thumbnail (featured image) on professions must be a valid attachment ID — verify the attachment exists before referencing it.

Common Mistakes

WRONG — deleting a team that has child teams
{ "action": "delete_item", "post_type": "mcp_ai_team", "item_id": 42 }
// Child teams with post_parent: 42 are now orphaned — they point to a deleted parent.

RIGHT — re-parent children before deleting
1. list_items(mcp_ai_team, filters: [{key: "post_parent", value: "42"}])
2. For each child: update_item(mcp_ai_team, item_id: <child_id>,
     fields: { "post_parent": <new_parent_id> })
3. Then: delete_item(mcp_ai_team, item_id: 42)

WRONG — creating a profession with a team name
{ "action": "create_item", "post_type": "mcp_ai_profession",
  "fields": { "title": "Cardiology Department" } }
// "Cardiology Department" is a team/organizational unit, not a profession.
// Profession should be: "Cardiologist"

RIGHT — use distinct, role-oriented names for professions
{ "action": "create_item", "post_type": "mcp_ai_profession",
  "fields": { "title": "Cardiologist",
  "content": "Medical doctor specializing in diagnosing and treating diseases of the cardiovascular system." } }

WRONG — using non-standard status values
// "active", "inactive", "archived" — these are not valid WordPress post statuses.

RIGHT — use standard WordPress statuses
// "publish" for active, "draft" for planned/inactive/archived.

WRONG — referencing a post_parent that doesn't exist
{ "post_parent": 99999 }  // This team ID doesn't exist — the hierarchy is broken.

RIGHT — verify parent exists before assigning
1. get_item(mcp_ai_team, item_id: <parent_id>) — confirm it returns a valid record.
2. Then: create_item or update_item with the confirmed post_parent.

Cross-References

• Run design-crm to link team members to CRM contacts, leads, and company relationships.
• Run design-pro-workflow-builder to automate team onboarding workflows and role-based task routing.
• Run design-pro-schedule-manager to schedule recurring team syncs, reviews, and roster updates.
• Run design-communications to set up team-specific communication channels and contact groups.
• Run wp-security-audit on any team assignment code — team membership controls access and must be properly authorized.

What This Skill Does NOT Cover

• WordPress user account creation and role management — use WordPress admin or WP-CLI (wp user create) for user accounts.
• User-to-team assignment mechanics — the specific meta keys or CPT relationships linking users to teams vary by implementation. This skill covers the Team and Profession CPTs themselves.
• Frontend team directory display — this skill covers data management; rendering is a theme concern.
• Permission and capability configuration — use WordPress role/capability APIs for access control based on team membership.
• External HR system integration — use ezuite_erp or custom REST endpoints for HR data sync.