Waymaker roles

Overview

Manage organizational roles and assignments. Roles define positions within your organization with reporting relationships, responsibilities, and accountabilities.

Usage

waymaker roles <subcommand> [options]

Subcommands

Subcommand	Description
list	List all roles
create	Create a new role
get	Get role details
update	Update role properties
delete	Delete a role
hierarchy	Show organization chart
reports-to	Set reporting relationship
describe	Get role description
assignments	List users assigned to role
assign	Assign user to role
unassign	Remove user from role

Examples

List All Roles

waymaker roles list

Output:

name               type        status  reports_to  assigned
-----------------------------------------------------------
CEO                leadership  active  -           0
CTO                leadership  active  CEO         0
Software Engineer  executing   vacant  CTO         0

Create a Role

waymaker roles create \
  --name "Product Manager" \
  --purpose "Drive product strategy and roadmap" \
  --reports-to <cto-role-id> \
  --type supporting

Options:

• --name (required): Role name
• --purpose: Role purpose/description
• --reports-to: Parent role ID in hierarchy
• --type: executing, supporting, or leadership

View Organization Hierarchy

waymaker roles hierarchy

Output:

Organization Hierarchy

CEO (leadership)
├── CTO (leadership)
│   ├── Software Engineer (executing)
│   └── Product Manager (supporting)
└── CFO (leadership)
    └── Accountant (executing)

Set Reporting Relationship

waymaker roles reports-to <role-id> <parent-role-id>

Assign User to Role

waymaker roles assign <role-id> --user <user-id>

Unassign User from Role

waymaker roles unassign <role-id> --user <user-id>

Delete a Role

waymaker roles delete <role-id> --confirm

Note: You cannot delete a role that has users assigned or child roles reporting to it.

Options Reference

Option	Type	Description
--name	string	Role name
--purpose	string	Role purpose/description
--reports-to	uuid	Parent role ID
--type	enum	executing, supporting, leadership
--status	enum	active, vacant, planned
--team	uuid	Team ID
--user	string	User ID for assign/unassign
--json	flag	Output as JSON
--confirm	flag	Required for delete

JSON Output

waymaker roles list --json

[
  {
    "id": "abc123",
    "name": "CEO",
    "type": "leadership",
    "status": "active",
    "reports_to_id": null,
    "reports_to_name": null,
    "assigned_count": 1
  }
]

Use Cases

Set Up Organization Structure

# Create leadership roles
waymaker roles create --name "CEO" --type leadership
CEO_ID=$(waymaker roles list --json | jq -r '.[] | select(.name=="CEO") | .id')

waymaker roles create --name "CTO" --type leadership --reports-to $CEO_ID
waymaker roles create --name "CFO" --type leadership --reports-to $CEO_ID

# Create team roles
CTO_ID=$(waymaker roles list --json | jq -r '.[] | select(.name=="CTO") | .id')
waymaker roles create --name "Senior Engineer" --type executing --reports-to $CTO_ID
waymaker roles create --name "Junior Engineer" --type executing --reports-to $CTO_ID

AI Agent: Analyze Org Structure

# Get hierarchy data
ROLES=$(waymaker roles list --json)

# Find vacant roles
echo $ROLES | jq '.[] | select(.status=="vacant")'

# Count roles by type
echo $ROLES | jq 'group_by(.type) | map({type: .[0].type, count: length})'

Role Types

Type	Description	Examples
leadership	Strategic decision-makers	CEO, CTO, VP
supporting	Enable others to execute	PM, HR, Finance
executing	Deliver core work	Engineers, Designers

MCP Tools (Claude Desktop)

When using the Waymaker MCP server with Claude Desktop or other AI assistants, these tools are available for managing organizational roles:

commander_role_list

List all roles in an organization.

Parameters:

Parameter	Type	Required	Description
organization_id	string	Yes	Organization UUID or Clerk ID
department	string	No	Filter by department
include_vacant	boolean	No	Only show vacant roles

Example prompts:

"List all roles in the organization"

"Show me vacant roles that need to be filled"

"What roles are in the Engineering department?"

commander_role_get

Get a role by ID with its accountabilities and assignments.

Parameters:

Parameter	Type	Required	Description
role_id	string	Yes	Role UUID
include_assignments	boolean	No	Include user assignments (default: true)

Example prompts:

"Get the Engineering Manager role details"

"Show me who is assigned to the CTO role"

commander_role_create

Create a new role definition.

Parameters:

Parameter	Type	Required	Description
organization_id	string	Yes	Organization UUID or Clerk ID
title	string	Yes	Role title
purpose	string	No	Role purpose statement
department	string	No	Department name
reports_to_id	string	No	UUID of role this reports to
accountabilities	array	No	Key accountabilities [{title, description}]

Example prompts:

"Create a Senior Engineer role in the Engineering department"

"Create a Product Manager role that reports to the VP of Product"

"Create a Marketing Lead role with accountabilities for brand and campaigns"

commander_role_update

Update a role's details.

Parameters:

Parameter	Type	Required	Description
role_id	string	Yes	Role UUID
title	string	No	New title
purpose	string	No	New purpose statement
department	string	No	New department
reports_to_id	string	No	New reporting role

Example prompts:

"Update the Product Manager role to report to the CEO"

"Change the Engineering Lead title to Principal Engineer"

"Update the role purpose to include team mentoring"

commander_role_assign

Assign or unassign a user to/from a role.

Parameters:

Parameter	Type	Required	Description
role_id	string	Yes	Role UUID
user_id	string	Yes	User ID to assign/unassign
action	string	No	"assign" or "unassign" (default: assign)
start_date	string	No	Assignment start date
allocation_percentage	number	No	Time allocation (0-100)

Example prompts:

"Assign Sarah to the Engineering Manager role"

"Remove John from the Project Lead role"

"Assign the new hire to the Junior Developer role starting next Monday"

Using Frameworks with Roles

Combine the Role Description Builder framework with role tools:

"Apply the Role Description Builder framework to create a comprehensive Engineering Manager role, then create it in Commander"

This lets Claude generate role purposes, accountabilities, and metrics, then create the role directly.

Related Commands

• users - Manage users
• teams - Manage teams
• frameworks - Use Role Description Builder framework