Create Webroles

> Plugin check: Run node "${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 ${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.
• Caller-suppress mode is opt-in: When invoked by another skill (e.g. /add-ai-webapi) with the [CALLED-BY-PARENT-SKILL] sentinel in $ARGUMENTS, suppress this skill's deploy prompts (Phase 1's missing-deploy ask, Phase 6's deploy ask (step 3), and the closing reminder) and return as soon as roles are created. The caller batches the deploy at end-of-orchestration. Human invocations never trigger this mode. See Phase 0 below for parsing.

> 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

Phase 0: Detect caller-suppress mode

Inspect $ARGUMENTS. If the text contains the sentinel [CALLED-BY-PARENT-SKILL], set an

internal flag caller-suppress = true that downstream phases consult. The optional token

caller=<skill-name> may follow the sentinel for diagnostic purposes (e.g.

caller=add-ai-webapi); record it for the final summary but do not branch on it.

When the flag is set, skip every deploy prompt this skill would otherwise issue:

• Phase 1 missing-deploy ask: if .powerpages-site is absent, do NOT ask the user to

deploy now. Stop with a clear contract-violation message back to the caller — the caller

was supposed to gate on this before invoking us.

• Phase 6 deploy ask (step 3) and the closing "Please run /deploy-site"

reminder: skip both. The caller batches the single deploy decision at end-of-orchestration.

When the sentinel is absent, proceed exactly as today (full interactive flow). This is the

regression guard — no human invocation changes behavior.

Workflow

• Phase 1: Verify Site Structure → Check for .powerpages-site/web-roles/ directory
• Phase 2: Discover Existing Roles → Read current web role YAML files
• Phase 3: Determine New Roles → Analyze the site and ask the user what roles are needed
• Phase 4: Create Web Role Files → Generate YAML files with UUIDs from the Node script
• Phase 5: Verify Web Roles → Validate all created files exist, have valid UUIDs, and flags are correct
• 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:

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

<!-- gate: create-webroles:1.deploy-first | category=plan | cancel-leaves=nothing -->

> 🚦 Gate (plan · create-webroles:1.deploy-first): .powerpages-site missing — skill cannot proceed without that folder. Prompt to deploy first or stop.

>

> Trigger: Phase 1 found no .powerpages-site directory.

> Why we ask: Web role YAML files written to a non-existent path will never get picked up by deploy; user thinks roles were created but they weren't.

> Cancel leaves: Nothing — no YAML files written.

• If .powerpages-site does NOT exist:
• In caller-suppress mode (Phase 0 flag): stop with a contract-violation message —

the calling skill should have gated on this folder existing before invoking us.

• Otherwise: 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.

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

• 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:

• 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

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

• 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.)*

• 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:

<!-- gate: create-webroles:3.role-selection | category=plan | cancel-leaves=nothing -->

> 🚦 Gate (plan · create-webroles:3.role-selection): Multi-select over suggested + custom web roles. Drives the Phase 4 YAML file writes.

>

> Trigger: Phase 2 inventoried existing roles; Phase 3 suggests new ones.

> Why we ask: Wrong roles get created locally — fixable but adds churn to the .powerpages-site/web-roles/ folder.

> Cancel leaves: Nothing — no YAML files written yet.

• 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

• Ask the user which roles they want to create:

| Question | Options |

|----------|---------|

| Which web roles would you like to create for your site? You can select from suggestions or describe custom roles. | *(Provide relevant suggestions based on site context, existing roles, and business domain)* |

CRITICAL: Do NOT suggest roles that already exist. Filter out any existing role names before presenting options.

• Allow the user to specify custom role names as well.

Output: Confirmed list of new web roles to create

Phase 4: Create Web Role Files

Goal: Generate properly formatted YAML files with valid UUIDs for each new web role

Actions:

For each new web role the user approved, create a YAML file in .powerpages-site/web-roles/.

4.1 Generate UUID

For each role, generate a UUID using the Node script. NEVER generate UUIDs yourself — always use the script.

node "${PLUGIN_ROOT}/scripts/generate-uuid.js"

4.2 Create the YAML File

The filename should be the role name in kebab-case with a .yml extension (e.g., Administrators → administrators.yml, Content Editors → content-editors.yml).

Write the file with this exact format (4 fields, no extra whitespace or comments):

anonymoususersrole: <true if this is the anonymous users role, false otherwise>
authenticatedusersrole: <true if this is the authenticated users role, false otherwise>
id: <UUID from generate-uuid.js>
name: <Role Name>

Rules:

• Only ONE role can have anonymoususersrole: true
• Only ONE role can have authenticatedusersrole: true
• If an existing role already has one of these flags set to true, do not set it again on a new role
• Each role MUST have a unique UUID generated by the script — run the script once per role

Output: All new web role YAML files created

Phase 5: Verify Web Roles

Goal: Validate that all created web role files exist, have valid format, and constraints are satisfied

Actions:

• List all files in .powerpages-site/web-roles/ and read each new file to confirm they were written correctly.

• For each new web role file, verify:
• The file exists at the expected path
• The id field contains a valid UUID v4 format
• The name field matches the expected role name
• anonymoususersrole and authenticatedusersrole are valid booleans

• Verify uniqueness constraints across ALL role files (existing + new):
• At most one role has anonymoususersrole: true
• At most one role has authenticatedusersrole: true
• No duplicate id values exist across roles

• If any file fails validation, fix the issue before proceeding.

Output: All web role files validated — correct format, valid UUIDs, no constraint violations

Phase 6: Review & Deploy

Goal: Present a summary of created roles and offer deployment

Actions:

• Record skill usage:

> Reference: ${PLUGIN_ROOT}/references/skill-tracking-reference.md

Follow the skill tracking instructions in the reference to record this skill's usage. Use --skillName "CreateWebroles".

• Present a summary of what was created:

> "I've created the following new web roles:"

>

> | Role Name | ID | Anonymous | Authenticated |

> |-----------|-----|-----------|---------------|

> | Content Editors | a1b2c3d4-... | false | false |

> | *(etc.)* |

<!-- gate: create-webroles:6.deploy | category=plan | cancel-leaves=nothing -->

> 🚦 Gate (plan · create-webroles:6.deploy): Final post-create prompt — deploy now to make the new roles take effect, or defer.

>

> Trigger: Phase 5 validation succeeded.

> Why we ask: Auto-invoking /deploy-site would push the site to whatever env PAC CLI happens to point at — wrong-env push is messy to undo.

> Cancel leaves: Nothing — the YAML files stay on disk; no deploy fired.

• In caller-suppress mode (Phase 0 flag): skip the deploy ask and the closing reminder

entirely. Return the created-roles summary to the caller and stop. The caller owns the

single end-of-orchestration deploy decision; nesting deploy reminders inside delegations

gives the user 2–3 redundant prompts per parent-skill run.

Otherwise, ask the user if they want to deploy the site to apply the new roles:

| Question | Options |

|----------|---------|

| The new web roles have been created locally. To apply them in Power Pages, the site needs to be deployed. Would you like to deploy now? | Yes, deploy now (Recommended), No, I'll deploy later |

• If "Yes, deploy now": Tell the user to invoke the deploy skill:

> "Please run /deploy-site to deploy your site and apply the new web roles."

• If "No, I'll deploy later": Acknowledge and remind them:

> "No problem! Remember to deploy your site using /deploy-site when you're ready to apply the new web roles to your Power Pages environment."

Output: Summary presented and deployment offered

Important Notes

Key Decision Points (Wait for User)

• After Phase 1: Confirm deployment if .powerpages-site is missing
• After Phase 3: Confirm which roles to create
• After Phase 6: Deploy or skip

Progress Tracking

Before starting Phase 1, create a task list with all phases using TaskCreate:

| Task subject | activeForm | Description |

|-------------|------------|-------------|

| Verify site structure | Verifying site structure | Check for .powerpages-site/web-roles/ directory, create if needed |

| Discover existing roles | Discovering existing roles | Read current web role YAML files and compile list of existing roles |

| Determine new roles | Determining new roles | Analyze site needs and ask user which roles to create |

| Create web role files | Creating web role files | Generate YAML files with UUIDs from the Node script for each new role |

| Verify web roles | Verifying web roles | Validate all files exist, have valid UUIDs, and uniqueness constraints are satisfied |

| Review and deploy | Reviewing and deploying | Present summary of created roles and offer deployment |

Mark each task in_progress when starting it and completed when done via TaskUpdate. This gives the user visibility into progress and keeps the workflow deterministic.

Begin with Phase 1: Verify Site Structure