cloudflare-os-operator

Files (3)

• SKILL.md
• troubleshooting.md · references/
• upgrade-and-rollback.md · references/

SKILL.md (first lines)

# Cloudflare OS Operator

Own the outcome, not just the next command. Guide the operator from an unprepared checkout to a verified deployment, or from a failure to a diagnosed and safe recovery. A provider outage, unavailable product, or incorrect external policy can never be ruled out in advance, so do not promise an issue-free deployment. Prevent avoidable failures and do not call the work complete without evidence.

This skill operates the deployment wrapper, not Cloudflare OS in isolation. The wrapper pins Cloudflare OS as a submodule, derives temporary Wrangler configs, and coordinates several Workers.

## Locate The Starter

Find the repository root containing all of these markers:

- `deployment.jsonc`
- `scripts/deploy.mjs`
- `cloudflare-os/`
- `packages/custom-gatekeeper/`

Do not assume the current working directory or this skill's directory is the starter root. If the markers are absent, stop and ask for the starter checkout. Do not apply this workflow directly to a standalone Cloudflare OS checkout. To port this wrapper's Asana, AWS, or QuickBooks Gatekeepers into an OS fork, load [install-gatekeepers-in-os-fork](../install-gatekeepers-in-os-fork/SKILL.md) instead.

## Read Current Sources First

Before any mutation, always read the current checkout's:

1. `README.md`
2. `deployment.jsonc`
3. `scripts/deploy.mjs`
4. `package.json`
5. `.gitmodules`
6. Available relevant upstream files under `cloudflare-os/`

Load `docs/customization.md`, `docs/observability.md`, package guides, and reference files from this skill only when their subject is relevant. If the submodule is unavailable, inspect all available wrapper sources and defer upstream-dependent advice until provenance is resolved.

Inspect the deploy script rather than assuming its validation, generated paths, build steps, or deployment order. Consult current Cloudflare documentation before relying on product behavior, permissions, CLI syntax, limits, or rollback support. Repository code is authoritative for what this checkout does; current Cloudflare documentation is authoritative for the platform it calls. Surface conflicts instead of silently choosing one.

Expected baseline commands are:

```sh
git submodule update --init
pnpm install
pnpm --dir cloudflare-os install
pnpm exec wrangler login
pnpm check
pnpm deploy
```

Confirm them against the checkout before running them. Always use `pnpm`, never `npm` or `yarn`.

## Operating Rules

- Start read-only. Inventory before mutation.
- Ask for all missing operator decisions in one concise batch.
- Explain why each requested value is needed and where to find it.
- Never guess an account ID, resource ID, hostname, Access issuer, audience, administrator, Worker name, provider, or existing-resource ownership.
- Never expose a token, cookie, JWT, secret, prompt, request body, response body, or private log content in chat, tracked files, command arguments, or reports. For local development only, use Wrangler's supported local-secret mechanism after proving the file is ignored and the credential is non-production.
- Use the project-pinned Wrangler through `pnpm exec wrangler`.
- Run only one `pnpm check` or `pnpm deploy` per checkout at a time. Use separate worktrees for concurrency.
- Change one root cause at a time. Re-run the narrow check, then the complete check.
- Do not broaden permissions, disable security controls, recreate resources, or retry deployments blindly to make an error disappear.
- Keep a sanitized operation record: root commit, submodule commit, target account, intended route, Worker names, resource identities, deployment/version IDs, decisions, verification, and rollback limits.

## Classify The Operation

Choose one mode before acting:

- **Research:** read-only explanation or design.
- **Evaluation:** a non-production deployment, usually on an explicitly protected `workers.dev` hostname.
- **Production:** a custom domain and production data or users.
- **Incident:** restore safety and service while preserving evidence.
- **Upgrade:** move the pinned `cloudflare-os` gitlink to a reviewed commit.

Also classify the deployment as a first deploy, continuation of an existing deployment, or replacement. If this is unclear, remain read-only.

## Hard Stops

### Secrets

Never ask the operator to paste a secret. Never read or print a secret to confirm it. Never put production secrets in `deployment.jsonc`, Wrangler vars, repository-local environment files, tracked files, shell history, or chat.

When AI is enabled, a human enters `CF_AI_GATEWAY_API_TOKEN` interactively for the exact Workshop Worker:

```sh
CLOUDFLARE_ACCOUNT_ID=<account-id> pnpm exec wrangler secret put CF_AI_GATEWAY_API_TOKEN --name <workshop-worker>
```

Confirm this account selector against current Wrangler documentation. Confirm the account, existing Worker ownership, and Worker name immediately before presenting or running the interactive command. `secret put` immediately deploys a new Worker version; require production approval, record its version ID, and verify it like any other deployment. Verify only that the secret name exists, never its value. If exposure is suspected, stop deployment and rotate or revoke the credential first.

### Trust Boundary

Require explicit operator approval before changing any of these:

- Cloudflare account, Worker identity, route, DNS, or Access application.
- Access issuer, audience, sign-in method, policy, administrator list, or allowed population.
- Existing KV/R2 bindings, `context.sharingDomain`, data ownership, or service bindings.
- AI provider, billing, token scope, model logging, retention, or external observability export.
- Gatekeeper authority, OAuth scopes, writes, observer policy, auto-provisioning, or ambience.
- Reporter visibility, browser reporting, retention, or destination.
- Durable Object migrations or storage schema.

Show the authority before and after, affected users/data, cost and privacy implications, verification plan, and rollback limitations.

### Production Mutation

Do not run `pnpm deploy`, install or delete secrets, modify Access/DNS, adopt resources, or roll back production until the operator approves a mutation summary containing:

- Exact account ID and hostname.
- Root and submodule commits.
- Every Worker to create or update.
- Every resource to provision or adopt.
- Access application and administrator policy.
- AI, observability, Reporter, and Gatekeeper modes.
- Last-known-good deployment IDs and rollback limitations.
- Evidence that `pnpm check` passed.

Never delete Workers, routes, Access applications, KV namespaces, R2 buckets, secrets, or user data as automatic cleanup or troubleshooting.

## End-To-End Workflow

### 1. Establish Provenance And State

Record, without leaking credentials:

From departure/ontix-iq, Apache-2.0.

More from departure/ontix-iq