Security Review

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

Review Security

Guide the user through a full security review of their Power Pages site. Runs the matching focused skills and assembles every finding into a single HTML report.

The skill never asks the user technical questions. The conversation stays in plain language.

Initial request: $ARGUMENTS

Workflow

The skill has six phases. Phases 2–5 each map to one conversation beat with the user; phases 1 and 6 are silent setup and cleanup. See references/flow.md for the rationale behind each beat.

Task Tracking

Create tasks in three groups. Mark each in_progress when starting, completed when done.

Group 1 — create at the start of prerequisites:

Only this one task. Do not create any other tasks until prerequisites complete.

Group 2 — create after prerequisites complete:

Group 3 — create after the goal is captured:

1. Prerequisites

1.1 Locate the project

Use Glob to find **/powerpages.config.json. If none is found, tell the user the site needs to be created first with /create-site, then stop.

For the monitor and release goals (any goal that delegates to scan-site or manage-firewall), also confirm that .powerpages-site/website.yml exists. If it does not, the site has not been deployed yet — tell the user (in plain language) the site needs to be deployed once before a live security review can run, recommend /deploy-site, then stop. Do not try to identify the site by name or URL — different sites can share the same name.

For the code-config goal, the deploy check is not required: source code, dependencies, authentication, web roles, and table permissions are read from local files alone.

1.2 Prepare a temporary working folder

Create a fresh working directory: <SYSTEM_TEMP>/security-review/. The folder holds JSON data files emitted by each skill in review mode. The folder is removed in the cleanup step.

If the folder already exists from a previous interrupted run, delete its contents (not the folder itself) before continuing.

1.3 Determine the docs output path

The final HTML always lives at <PROJECT_ROOT>/docs/security-review-<YYYY-MM-DD-HHMMSS>.html using the local timestamp at the start of the run (e.g. security-review-2026-05-14-053805.html). Always include the timestamp — do not use a bare security-review.html name. This keeps each run's report distinct.

2. Capture goal

2.1 Ask the goal

<!-- gate: security-review:2.1.goal | category=plan | cancel-leaves=nothing -->

🚦 Gate (plan · security-review:2.1.goal): Capture the review goal — choice branches into one of three sub-skill sets (code-config / release / monitor).

Trigger: Phase 2.1 entry, unless $ARGUMENTS already answers it. Why we ask: Auto-picking release runs ALL sub-skills (slow; possibly hits scan/firewall endpoints unnecessarily); auto-picking the wrong goal mis-scopes the review. Cancel leaves: Nothing — no sub-skills invoked yet.

Ask the user with a single AskUserQuestion call. If the user's initial request already answers it, skip and continue.

Question — What to review?

Goal mapping (internal):

2.2 Capture the chosen skill set

Build a selectedSkills list based on the answer. Always include the read-only check of setup-auth for the code-config and release goals (it consists of reading existing YAML, not running the skill itself — see § 3.2 below). This is the Access & Data Security Validation component.

3. Run the matching skills

Spawn each selected skill as a background subagent via the Agent tool. Each subagent invokes its skill with the argument --review <SYSTEM_TEMP>/security-review/. Each skill handles its own authentication, error reporting, and progress.

3.1 Skill invocation via subagents

Skills run as parallel subagents using the Agent tool.

Default — launch every Agent-eligible skill in one parallel batch. Spawn all selected subagents in a single message with multiple Agent tool calls so they start concurrently. Each subagent runs with run_in_background: true. The Agent-eligible set is scan-code, scan-site, manage-headers, manage-firewall — these all support --review mode. scan-site (server-side scan, several minutes) and scan-code (local static analysis + dependency scan, up to minutes on large projects) are the slowest; the others typically finish within seconds.

Fallback — staggered launch. If the harness rejects a parallel-batch call for any reason, launch scan-code and scan-site first (the long-running ones) and then the remaining skills in a follow-up message. This is a tool-affordance fallback, not the preferred path.

Inline checks (run while subagents work). audit-permissions and setup-auth do not support --review and MUST NOT be launched via Agent — handle them inline as described in § 3.2.

Wait for all subagents to complete before proceeding to the report-building step.

3.1.1 Subagent prompt pattern

Each subagent receives a self-contained prompt that includes:

1. The skill to invoke and the --review argument with the temp directory path
2. The project root path so the skill can locate site files
3. Any scope/depth parameters captured in the scope capture step

Example subagent call:

Agent({
  description: "Run scan-site",
  prompt: "Invoke the skill `scan-site` with argument `--review <SYSTEM_TEMP>/security-review/`. The Power Pages project root is <PROJECT_ROOT>. <any additional scope parameters>. Write the **transform script stdout verbatim** to <SYSTEM_TEMP>/security-review/scan-site.json. Do NOT synthesize, augment, or re-classify the findings. If the skill fails, write { \"status\": \"skipped\", \"reason\": \"<plain-language reason>\" } instead.",
  run_in_background: true
})

Verbatim rule: the subagent's output JSON must contain only the findings emitted by the skill's transform script. The orchestrator must not append findings, rewrite titles, add severity, or otherwise editorialize.

3.1.2 Expected output

After all subagents complete, expect JSON files at <SYSTEM_TEMP>/security-review/<skill-name>.json. Each file has the shape { status, findings, details? } produced by the skill's transform script:

<SYSTEM_TEMP>/security-review/
├── scan-code.json           (when invoked)
├── scan-site.json
├── manage-headers.json
├── manage-firewall.json
└── audit-permissions.json   (when invoked)

If a skill's subagent fails or is skipped, write a placeholder file with shape { "status": "skipped", "reason": "<plain-language reason>" }. The report-building step renders this as a single non-severity finding for that section (no severity field, to stay consistent with § 3.1.3).

3.1.3 Severity policy

Only findings that come from a tool that genuinely outputs severity may carry a severity field:

For inventory sections, do not add severity to findings — not even info. The subagent and orchestrator must write the transform output verbatim without inserting opinionated severity-bearing findings. The tag field is also off-limits as a severity workaround: it is reserved for short mechanical identifiers from tools (e.g. ZAP rule ids, CWE codes) and MUST NOT carry severity-equivalent strings (critical, warning, info), since the report template renders it as a visible chip next to the title.