Plugin check: Run node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Create Web Roles

Create web roles for a Power Pages code site. Web roles define the permissions and access levels for different types of site users.

Core Principles

• Use TaskCreate/TaskUpdate: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.
• Always use the UUID script: Never generate UUIDs manually — always use ${CLAUDE_PLUGIN_ROOT}/scripts/generate-uuid.js to produce valid UUID v4 values for each web role.
• Preserve uniqueness constraints: Only one role can have anonymoususersrole: true and only one can have authenticatedusersrole: true. Always check existing roles before setting these flags.

Prerequisite: The site must be deployed at least once before web roles can be created, since deployment creates the .powerpages-site folder structure that stores web role definitions.

Initial request: $ARGUMENTS

Workflow

1. Phase 1: Verify Site Structure → Check for .powerpages-site/web-roles/ directory
2. Phase 2: Discover Existing Roles → Read current web role YAML files
3. Phase 3: Determine New Roles → Analyze the site and ask the user what roles are needed
4. Phase 4: Create Web Role Files → Generate YAML files with UUIDs from the Node script
5. Phase 5: Verify Web Roles → Validate all created files exist, have valid UUIDs, and flags are correct
6. Phase 6: Review & Deploy → Present summary and proceed to deployment

Phase 1: Verify Site Structure

Goal: Confirm the .powerpages-site/web-roles/ directory exists and is ready for web role files

Actions:

1. Locate the project root (**/powerpages.config.json) and check for .powerpages-site/web-roles/.

2. If .powerpages-site does NOT exist: Ask the user to deploy first via AskUserQuestion (options: "Yes, deploy now (Recommended)", "No, I'll do it later"). If yes, invoke /deploy-site then resume from Phase 2. If no, stop.

3. If .powerpages-site exists but web-roles/ does NOT: Create the <PROJECT_ROOT>/.powerpages-site/web-roles/ directory.

4. If both exist: Proceed to Phase 2.

Output: Confirmed .powerpages-site/web-roles/ directory exists and is ready

Phase 2: Discover Existing Roles

Goal: Identify all web roles already defined for the site

Actions:

1. Read all YAML files in the .powerpages-site/web-roles/ directory. Each file represents one web role with this format:

   anonymoususersrole: false
   authenticatedusersrole: false
   id: 778fa3d0-a2ef-4d2b-98b8-e6c7d8ce1444
   name: Administrators
   

2. Parse each file and compile a list of existing web roles (name, id, and flags).

3. Present the existing roles to the user:

   "I found the following existing web roles in your site:"

   • Administrators (id: 778fa3d0-..., authenticated: false, anonymous: false)
   • (etc.)

4. If no roles exist yet, inform the user:

   "No web roles are currently defined for your site."

Output: Complete list of existing web roles with their names, IDs, and flags

Phase 3: Determine New Roles

Goal: Decide which new web roles to create based on site needs and user input

Actions:

1. Based on the site's purpose and the existing roles, suggest appropriate web roles. Use AskUserQuestion to confirm with the user.

   Common web roles for Power Pages sites include:

   • Administrators — Full access to site management
   • Authenticated Users — Default role for logged-in users (set authenticatedusersrole: true)
   • Anonymous Users — Default role for non-logged-in visitors (set anonymoususersrole: true)
   • Content Editors — Users who can edit site content
   • Moderators — Users who can moderate community content
   • Custom roles based on business needs

…