byoc-preflight

byoc-preflight gating a regulated promotion

A Ryvn CLI agent skill that gates regulated deployments before they ship.

byoc-preflight is a Claude Code skill, built in the Agent Skills format (agentskills.io) used by ryvn-technologies/skills. It adds a regulated-readiness gate to the Ryvn workflow: before a service installation is promoted or deployed into a regulated environment, the skill gathers evidence from the live ryvn CLI, runs a fourteen-check readiness gate, and refuses to let the task approval and the promotion through until the deployment is provably safe to land.

It is structured so it could be contributed directly to ryvn-technologies/skills: same repo layout, same plugin and hook convention, a route-first SKILL.md in the same style as their use-ryvn skill, and action-oriented references. To be clear, this is independent work. It is not affiliated with Ryvn and does not represent their product. I built it to show how I would extend the Ryvn agent workflow with a regulated-readiness gate, using their real resource model and CLI.

Example gate run: 14 checks, 1 blocker, 2 warnings, verdict NOT READY

The insight

Most deployment tooling answers the wrong question. It tells you the container came up healthy and the rollout finished. In normal SaaS that is most of what you need. In BYOC it is the easy part and the least important part.

When your software runs inside a hospital's or a bank's own cloud, the dangerous failure is silent success. A green deploy that quietly ships PHI out through a trace attribute has not failed to run. It ran perfectly and breached the contract. So the questions that actually gate a regulated deploy are different in kind. Not "did it run," but:

• Can customer data leave the environment, through any path, including the

observability pipeline.

• Can you operate and debug the workload without standing access to the

customer's box.

• If this release is bad, can you roll back to a known good version you have

actually tested.

• Did this release earn its way to the customer through a promotion pipeline, or

did someone push it straight in.

• Can you attribute and reproduce every change from Git when an auditor asks.

byoc-preflight turns those into explicit checks with severities and runs them as a gate. A blocker means NOT READY, full stop. Warnings are surfaced but do not gate.

How it fits the Ryvn model

Ryvn already task-gates deploys with ryvn task approve <uuid> and already runs a light preflight that verifies auth and context. This skill extends both into a real regulated-readiness gate at the last hop, the moment a release crosses into a regulated environment.

Ryvn ships changes progressively, to progressively more critical customers, and holds a release in production before it reaches a customer environment. byoc-preflight is the gate on the most critical hop of that rollout, the point where a mistake has the largest blast radius. It makes the readiness check architectural and automated, a step in the pipeline, rather than a manual review someone has to remember to run.

It uses the real Ryvn resource model and CLI. It operates on a service installation inside an environment, gathers evidence with read-only commands (ryvn describe installation -o json, ryvn get manifest, ryvn describe environment -o json), and composes with the real mutation verbs (ryvn task approve --reason, ryvn promote release --pipeline). The gate runs between the candidate and the regulated environment: gather evidence, run the gate, block on blockers, approve and promote only on a clean or acknowledged verdict, then verify with a read-back. PR-01 even checks that the release reached the regulated environment through the promotion pipeline rather than a direct push, so the gate enforces the very discipline it is part of.

The rig check

Six years as an NYC EMT, you do not roll the truck without the rig check. Same logic here. You do not push into a hospital's cloud without the pre-flight.

What it checks

Fourteen checks across seven groups. Each check has an id, a severity (blocker or warn), and a rule that genuinely evaluates fields in a deployment manifest derived from live Ryvn evidence. Full detail, with the ryvn command that gathers evidence for each, is in the checks reference.

1. Data residency and egress. No customer-data egress paths leave the

environment. Outbound endpoints are explicitly allowlisted. Telemetry and logs are scrubbed of customer PII before they leave.

1. Secrets and access. No standing vendor access (break-glass only). Secrets

sourced from the customer's vault, never baked into images. Deploy role least-privilege and scoped to named resources.

1. Observability without access. Health, metrics, and logs are reachable

without standing access to the customer box. A defined error-reporting path exists.

1. Rollback safety. Previous stable version pinned and the rollback path

tested and reversible. No destructive or irreversible schema migrations without an explicit gate.

1. Promotion discipline. This release reached the regulated environment through

a promotion pipeline, not a direct push.

1. Audit. Every change records who, what, when, and why, and is reproducible

from Git.

1. Compliance preconditions. Encryption at rest and in transit. Network

isolation appropriate to the customer's stated controls, for example HIPAA for healthcare.

A missing field fails the check, it does not pass. In a regulated environment, "we did not say" is a finding, not a default-OK.

Install the skill

The skill ships as a Claude Code plugin under plugins/byoc-preflight/.

1. Add this repo as a plugin marketplace and install it from inside Claude Code:

   /plugin marketplace add CodedVibesX/byoc-preflight
   /plugin install byoc-preflight

Or point the marketplace at a local clone of this repo.

1. Once installed, the skill activates on its own when you ask Claude Code to

deploy, promote, or release into a regulated, HIPAA, BYOC, or customer environment, or when you ask for a readiness gate or a go/no-go on a service installation.

The plugin includes a hook that auto-approves the read-only evidence-gathering commands (ryvn get, ryvn describe, and the local engine) while deliberately leaving mutations (ryvn task approve, ryvn promote, ryvn command) gated, so a human still authorizes anything that changes a regulated environment.

Run the engine directly

The gate engine is real and runnable on its own. The skill orchestrates it; you can also run it standalone:

pip install pyyaml
python3 engine/preflight.py \
  --manifest engine/example_deployment.yaml \
  --checks engine/checks.yaml \
  --out report.html

That writes report.html and report.json, prints the summary, and exits 1 because the example is NOT READY. Point it at your own manifest to gate a real deploy, or run it as a CI step and let the non-zero exit fail the promotion job.

The HIPAA example

The included scenario promotes acme-health-clinical-summary 2.7.0 into Mercy General Hospital's own AWS environment. The hospital is a HIPAA-covered entity, so no patient data may leave their cloud and the vendor gets no standing access.

The manifest is deliberately not all-green, because real deploys are not. Running the gate produces:

• One blocker, DR-03: application logs are scrubbed, but distributed traces are

not yet routed through the PII filter, so span attributes can still carry patient identifiers before telemetry leaves the boundary. This is the failure that looks fine in staging and leaks PHI in production. It forces NOT READY.

• Two warnings, SA-03 (the deploy role is still a broad wildcard rather than

scoped to named resources) and OB-02 (no dedicated error-reporting path is wired up yet).

• Eleven passes: egress is closed, secrets come from the customer vault, there is

no standing access, observability flows out without reaching in, rollback is pinned and tested, the release walked the promotion pipeline, the change is attributable and reproducible from Git, and encryption and network isolation match HIPAA.

Verdict: NOT READY. The report shows exactly which line failed and why, with the manifest value quoted as evidence on every row. A committed copy of report.html and report.json is in the repo, and report_preview.png shows the rendered HTML. The full end-to-end walkthrough is in the healthcare reference.

Repo layout

byoc-preflight/
  README.md
  plugins/byoc-preflight/
    .claude-plugin/plugin.json         Claude Code plugin manifest
    hooks/                              auto-approve read-only evidence steps
    skills/preflight/
      SKILL.md                         route-first skill, in the use-ryvn style
      references/
        checks.md                      the 14 checks, grouped, with evidence commands
        healthcare.md                  HIPAA walkthrough on a service installation
        audit.md                       audit report + GitOps + task-approve + promotion
  engine/
    preflight.py                       the readiness engine the skill runs
    checks.yaml                        the check definitions
    example_deployment.yaml            the HIPAA example manifest
  report.html                          generated report (committed)
  report.json                          generated report (committed)
  report_preview.png                   rendered screenshot of report.html
  ARCHITECTURE.md                      the failure model and design notes
  LICENSE                              MIT

A note on what this is

This is an independent work sample. It is not affiliated with Ryvn and does not represent their product. I built it in their open-source skill format to show how I would extend the Ryvn agent workflow with a regulated-readiness gate, and to think through what a real pre-flight gate for high-consequence deployments would actually need to check. The engine is real and runnable. The skill is structured to be contributed to ryvn-technologies/skills.

Contact

Lawrence Wolters GitHub: github.com/CodedVibesX Email: [email protected]