ciz documentation

CNCF-grade planning docs

Compile policy-aware intent into execution DAGs you can review, diff, and run anywhere.

ciz separates desired state, composition logic, and runtime execution. Platform teams define intent once, validate it against schemas, bind it to reusable compositions, and materialize a deterministic plan that can run on a local shell, inside Docker, or through a GitHub Actions-compatible backend.

Start with the quick startRead the compiler pipeline

Intent stays declarative

Keep policy, environment defaults, and component subscriptions in intent files instead of leaking execution details into app repos.

Compositions stay reusable

Each composition pairs a schema with one or more job definitions, so platform teams can evolve execution contracts centrally.

Plans stay deterministic

The generated plan is an immutable DAG with explicit jobs, steps, dependencies, retries, and state-file metadata.

Runtimes stay swappable

Compile once, then preview or execute through the local shell, a Docker runner, or GitHub Actions compatibility mode.

What ciz is for

Use ciz when you need a planner that can scale from a single repository to a platform estate without collapsing intent, validation, and execution into one format.

• Define desired state in intent.yaml plus discovered component.yaml files.
• Validate platform contracts through JSON schema.
• Bind component types to reusable job registries under a compositions directory.
• Render a reviewable plan.json before anything executes.
• Run the plan in dry-run or execute mode with explicit backend selection.

Mental model

intent.yaml + component.yaml + compositions/
                  ↓
        load, normalize, validate
                  ↓
      expand environment × component matrix
                  ↓
      bind jobs and resolve dependencies
                  ↓
          render immutable plan.json
                  ↓
       dry-run or execute with a runner

Desired state

Intent and components

Intent declares environments, group-level policy, discovery roots, inline components, and change-scoping inputs. Component manifests declare type, inputs, labels, overrides, and dependencies.

Execution contract

Compositions and schemas

Each composition directory contains a schema for validation and a job registry for runtime behavior. That keeps platform logic versioned and reusable.

Compiled artifact

Plan DAG

The plan records explicit jobs, step order, phase boundaries, dependencies, and runtime hints. It is the artifact you diff, archive, and execute.

Typical workflow

./ciz validate \
  --intent examples/intent.yaml \
  --config-dir assets/config/compositions

./ciz plan \
  --intent examples/intent.yaml \
  --config-dir assets/config/compositions \
  --output /tmp/ciz-plan.json

./ciz run --plan /tmp/ciz-plan.json

The default run mode is a dry-run, so teams can inspect the resolved jobs and steps before enabling --execute.

How to read these docs

Start here

Getting started

Install the CLI, compile the example intent, and inspect the generated plan before executing anything.

Then learn

Concepts and architecture

Understand the separation between intent, compositions, plans, and runners before authoring your own platform contracts.

Then operate

CLI and reference

Use the command reference, schema reference, and environment variable matrix when integrating ciz into CI or platform automation.

Next steps

1. Follow the installation guide.
2. Run the repository-backed quick start.
3. Read intent model and plan DAG before writing new compositions.