xray-xhttp-vpn-orchestrator

name	xray-xhttp-vpn-orchestrator
description	Coordinate the local Xray/VLESS/XHTTP VPN workflow, route tasks to internal worker modules, enforce scoped alarms, and accept outputs only after evidence and review.

Xray XHTTP VPN Orchestrator

Use this skill when a user asks to create, audit, diagnose, generate, or monitor an authorized Xray/VLESS/XHTTP VPN workflow using this skill group.

Inputs

• User goal and approved task context.
• TASK-PLAN.MD and FEATURE-PREPARATION.MD.
• Worker outputs and evidence manifests.

Outputs

• Routing decision.
• Worker handoff packet.
• Acceptance or rejection decision.
• Final synthesis with evidence paths and caveats.
• Deterministic helper outputs from scripts/ when the task asks for endpoint inventory validation, DNS probing, DNS API planning/apply, Xray build packages, SSH deployment planning/apply, client artifacts, split-routing checks, postflight, redaction, or package-shape validation.

Worker Registry

Workers are internal modules, not separately installed Codex skills. Before routing to a worker, read the matching WORKER.md and use group/references/ as the shared reference root.

• xray-xhttp-context-auditor -> group/workers/xray-xhttp-context-auditor/WORKER.md
• dns-endpoint-selector -> group/workers/dns-endpoint-selector/WORKER.md
• dns-delegation-advisor -> group/workers/dns-delegation-advisor/WORKER.md
• dns-api-provisioner -> group/workers/dns-api-provisioner/WORKER.md
• xray-endpoint-provisioner -> group/workers/xray-endpoint-provisioner/WORKER.md
• xray-xhttp-server-builder -> group/workers/xray-xhttp-server-builder/WORKER.md
• xray-client-json-factory -> group/workers/xray-client-json-factory/WORKER.md
• split-routing-auditor -> group/workers/split-routing-auditor/WORKER.md
• runtime-diagnostics -> group/workers/runtime-diagnostics/WORKER.md
• observability-netmon-planner -> group/workers/observability-netmon-planner/WORKER.md

Non-Goals

• Do not perform low-level DNS, server, router, Xray, nginx, Traefik, or runtime mutations without explicit user approval and the matching script gate.
• Do not store secrets.
• Do not accept worker output from file existence alone.

Workflow

1. Read references/production-skill-architecture.md, references/failure-modes.md, and references/group-contract.md.
2. Classify the request as endpoint-domain selection, read-only, draft-source, mutation, diagnostics, client JSON, split routing, or observability.
3. Propagate only scoped active alarms that apply to the requested task surface.
4. Route missing, ambiguous, or "no domain yet" endpoint FQDN/domain strategy requests to dns-endpoint-selector before DNS authority, server build, or client artifact work.
5. Route to the smallest worker in the Worker Registry that owns the write zone.
6. Require an accepted endpoint-domain-decision.json before DNS API provisioning, endpoint inventory finalization, server build, or client artifact export when the endpoint FQDN is not already proven.
7. Prefer deterministic helper scripts over freeform reconstruction when a matching script exists.
8. Require evidence before acceptance.

Operational Script Registry

Run these from the skill root unless a worker entrypoint is more convenient:

• python3 scripts/validate_endpoint_inventory.py --input <inventory.json> --output <report.json>
• python3 scripts/dns_authority_probe.py --input <dns-probe.json> --output <report.json>
• python3 scripts/cloudflare_dns_records.py --input <record.json> --output <plan.json>; add --apply --authority-packet <authority.json> only after explicit approval and a scoped token in CLOUDFLARE_API_TOKEN.
• python3 scripts/generate_xray_build_package.py --input <server-facts.json> --out <private-out-dir>; add --generate-uuid only when creating new private identities. Existing devices must provide users[].uuid/id.
• python3 scripts/deploy_xray_xhttp_server.py --package-dir <private-build-dir> --host <vps-fqdn-or-ip> --user root --nginx-location-path <remote-snippet> --output <deploy-report.json>; dry-run by default. Add --apply --acknowledge-live-mutation only for an approved live VPS change, and --reload-services only when reload is approved.
• python3 scripts/export_xray_artifacts.py --input <server-facts-or-xray-json> --out <private-out-dir>; add --public-facts <public-facts.json> when input is server-side Xray inbounds config behind nginx/443.
• python3 scripts/validate_client_artifacts.py <private-out-dir>/client-artifacts.manifest.json --output <report.json>
• python3 scripts/validate_xray_server_config.py <config.json> --output <report.json>
• python3 scripts/validate_split_routing.py --input <client-config.json> --output <report.json>
• python3 scripts/generate_postflight.py --input <postflight-input.json> --out <out-dir>
• python3 scripts/redact_xhttp_artifacts.py --input <secret-bearing-path> --out <redacted-out-dir>
• python3 scripts/check_single_container_package.py <skill-root-or-.skill> --output <report.json>

The source package may include sanitized FI/DE examples under assets/examples/; raw UUIDs, private keys, bearer tokens, and subscription/client links must remain outside the source package.

Dependency / Parallelism Table

Sequential by default when workers share evidence, write zones, or acceptance gates. Read-only context and DNS advice may run independently after the orchestrator contract exists.

Stop Rules

Return blocked instead of expanding scope when approval, secret boundary, DNS authority, Xray/client compatibility, rollback, or evidence required for the requested task surface is missing.

For endpoint-domain selection, return blocked when the user has not chosen among owned root domain, owned subdomain, or FreeDNS fallback; when root/www/mail impact is unclear; when FreeDNS is treated as production-equivalent to an owned domain; or when a raw FreeDNS update URL/token would be written into a file-bound artifact.

Completion Vs Acceptance

Worker completion is not acceptance. Acceptance requires artifact existence, required evidence, context review, and orchestrator decision.

Failure Modes

Use the closed taxonomy in references/failure-modes.md.

Retry Policy

Retry only according to references/failure-modes.md; never retry permission or security blockers without new user input.

Evidence Rule

Every accepted worker output must cite generated artifacts, command output, config diff, test result, or explicit scoped blocker.

Tool Verification

Before depending on helper scripts or external tools, verify tool reality and record missing/fallback/manual-approval states.

dig, whois, sing-box, mihomo, SSH, and Cloudflare API access are optional per task. Missing optional tools downgrade or block only the claim they would prove; they must not be replaced with fake evidence. The release gate is different: scripts/run_xray_runtime_regression.py must acquire the exact official Xray artifact pinned in references/xray-compatibility-matrix.json, verify its SHA-256 before execution, and parse the generated server plus every primary full-client JSON. A missing or red parser gate blocks release acceptance and cannot degrade to passed_static. Parser validity still does not prove live connectivity, route selection, or physical-client import.

Final Review

Do not claim the group is production-ready until evals, lint, tool verification, sanitation, dry-run install, and final review evidence exist.