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

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/.

<!-- 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.

2. 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.

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:

<!-- 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.

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

2. 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.

3. 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"