/xguard-manager

name: xguard-manager
description: Read, replace, reset, export, and import XGuard policy options on the orchestrator. Use when you need to inspect current per-label policies for text or prompt scans, ship a refined policy, restore defaults, or back up the policy registry. Read-only by default; destructive operations require an explicit `--writable` flag.

XGuard Policy Manager

Use this skill to manage XGuard policy options against the orchestrator's `/v1/manager/xguard/*` admin endpoints.

Each label's policy is the natural-language prompt text + threshold + action that the orchestrator applies when evaluating an XGuard call. See [docs/features/scanner-prompt-tuning.md](../../../docs/features/scanner-prompt-tuning.md) for how this fits into the scanner refinement lifecycle. Phase 4 (refine policy) is the typical use of this skill: fetch the current options, edit a policy, PUT the new version, then track FP/FN rates against the new `policyHash` in the audit log.

Setup

The skill reads `ORCHESTRATOR_ENDPOINT` and `ORCHESTRATOR_ACCESS_TOKEN` from the project `.env` (or `.claude/skills/xguard-manager/.env` if you want skill-specific overrides). No additional setup beyond having those env vars set.

Commands

node .claude/skills/xguard-manager/manage.mjs <command> [args] [options]

| Command | Description | |---------|-------------| | `get <mode>` | GET current options for the mode (`text` or `prompt`) | | `defaults <mode>` | GET hardcoded defaults baked into the orchestrator | | `put <mode>` | PUT new options for the mode (requires `--writable` + `--file`) | | `reset <mode>` | POST reset back to defaults (requires `--writable`) | | `export` | GET bulk export across all modes | | `import` | PUT bulk import across all modes (requires `--writable` + `--file`) |

Options

| Flag | Description | |------|-------------| | `--writable` | Allow destructive operations (PUT / POST). Required for `put`, `reset`, `import`. | | `--file <path>`, `-f <path>` | Read the request body (JSON) from a file. Required for `put` and `import`. | | `--output <path>`, `-o <path>` | Save response to a file (instead of printing to stdout). | | `--quiet`, `-q` | Only print the response body, no connection headers. | | `--timeout <s>`, `-t <s>` | Request timeout in seconds (default: 30). |

Examples

# Inspect current prompt-mode options
node .claude/skills/xguard-manager/manage.mjs get prompt

# Save the current prompt-mode options to a file you can edit
node .claude/skills/xguard-manager/manage.mjs get prompt -o /tmp/prompt-policies.json

# See what the defaults look like (useful for scaffolding a new label)
node .claude/skills/xguard-manager/manage.mjs defaults prompt

# Ship an edited policy
node .claude/skills/xguard-manager/manage.mjs put prompt -f /tmp/prompt-policies.json --writable

# Wipe prompt-mode policies back to defaults (destructive)
node .claude/skills/xguard-manager/manage.mjs reset prompt --writable

# Back up the entire policy registry before a risky edit
node .claude/skills/xguard-manager/manage.mjs export -o /tmp/xguard-backup.json

# Restore from a backup
node .claude/skills/xguard-manager/manage.mjs import -f /tmp/xguard-backup.json --writable

Safety

1. **Read-only by default**: `get`, `defaults`, and `export` always work without `--writable`. 2. **Destructive operations require explicit `--writable`**: `put`, `reset`, and `import` change orchestrator state and refuse to run without the flag. 3. **Always ask the user before using `--writable`**: policy changes are global — every subsequent scan will use the new policy text. Confirm the intent before running. 4. **Back up before editing**: run `export -o backup.json` before any non-trivial change so you can `import` to restore if needed.

Typical workflow for refining a policy (Phase 4)

# 1. Snapshot current state for safe rollback
node .claude/skills/xguard-manager/manage.mjs export -o /tmp/xguard-backup-$(date +%Y%m%d).json

# 2. Pull the current options for the mode you're editing
node .claude/skills/xguard-manager/manage.mjs get prompt -o /tmp/prompt-current.json

# 3. Edit /tmp/prompt-current.json with the refined policy text

# 4. Ship it (after user confirms)
node .claude/skills/xguard-manager/manage.mjs put prompt -f /tmp/prompt-current.json --writable

# 5. Track FP/FN rate of new policyHash via the audit log + focused review

Why this is separate from the postgres-query / clickhouse-query skills

Those query the audit *data* (verdicts, scores, matched terms). This skill manages the *policy* itself — the prompt text the orchestrator hands to XGuard. A typical tuning loop uses both: query data to identify FP patterns, edit the policy here, then re-query after new scans land under the new `policyHash`.