Skip to main content
Version: MVP

Runner preview workflows

6 min readFor contributorsUpdated 2026-05-19

What you'll do

Walk through Craik's v0.1.0 runner-preview surface: context discovery and case files · policy-aware prompt compilation · fixture or prompt-handoff execution · receipt and handoff metadata capture. The preview validates the runner boundary before live side effects are trusted.

Preview adapters do not grant authority.

Fixture mode, prompt handoff, and governed provider execution are the expected paths. Side effects still require explicit capability grants.

Workflow​

  1. Register or select a project.
  2. Create a task with explicit scope, constraints, and expected outputs.
  3. Build the task case file.
  4. Compile a runner-targeted prompt.
  5. Build a runner adapter request from the compiled prompt.
  6. Run the preview adapter in fixture or prompt-handoff mode.
  7. Persist receipts and handoffs from the normalized result when appropriate.
  8. Review runner metadata, policy boundaries, omitted context, and diagnostics before treating output as evidence.

Context and overrides​

Case files decide what context reaches the prompt. Configure project docs, immutable paths, discovery includes, and discovery excludes before building the case file.

Omissions are stop-or-ask conditions.

Compiled prompts surface omitted or excluded context in context_omissions. Runners must treat omissions as stop-or-ask conditions — not as evidence that omitted material is irrelevant.

Compile a prompt​

Use the runner capability matrix to choose the runner:

craik runners matrix
craik runners matrix --runner codex

Compile the prompt:

craik prompt compile <task-id> --runner codex
craik prompt compile <task-id> --runner claude
craik prompt compile <task-id> --runner gemini

The compiler persists a craik.compiled_prompt and includes:

Task and policy boundaries

Capability grants

Runner trust profile

Unsupported / prompt-handoff capabilities

Context omissions

Governing distillations

Rendered as their own authoritative section with provenance annotations.

Expected output schemas

Stop conditions

Run a preview adapter​

Each preview adapter implements the same runtime shape:

from craik.runtime.codex_adapter import CodexRunnerAdapter, request_from_compiled_prompt

adapter = CodexRunnerAdapter()
request = request_from_compiled_prompt(compiled_prompt, adapter=adapter)
result = adapter.run(request)

craik.runtime.codex_adapter

craik.runtime.claude_adapter

craik.runtime.gemini_adapter

Fixture outcomes are controlled through request context:

request = request_from_compiled_prompt(
    compiled_prompt,
    context={
        "fixture_status": "blocked",
        "blocked_reason": "missing approval for shell.execute",
    },
)

Supported fixture statuses: completed · blocked · failed · partial.

Result shape​

Adapters return craik.runner_adapter_result.

Field
Purpose
Contents
outputs.prompt_handoff
handoff bundle
Compiled prompt + runner id.
outputs.receipt_inputs
receipt drafts
For granted capabilities.
outputs.handoff_input
handoff bundle
Fields suitable for handoff creation.
outputs.runner_metadata
audit
Stable runner · adapter · trust · capability metadata.
diagnostics
surface notes
Fixture and prompt-handoff limitations or runner diagnostics.

Receipts and handoffs preserve stable runner metadata so future agents can see which adapter, version, execution mode, trust profile, and capability profile were involved. Runner-specific fields remain nested and redacted.

Policy boundary​

Preview adapters do not grant authority.

Side effects require explicit capability grants. Unsupported capabilities are blocked. Prompt-handoff side effects must return through Craik review. Fixture results are deterministic test outputs, not proof of live execution. Receipt metadata describes runner context but does not replace concrete side-effect receipts.

Smoke-test checklist​

  1. Run craik runners matrix --runner <id> and confirm the trust profile.
  2. Run craik prompt compile <task-id> --runner <id>.
  3. Build a request with the matching adapter module.
  4. Run one completed, one blocked, and one failed fixture path.
  5. Confirm outputs.runner_metadata, outputs.receipt_inputs, and outputs.handoff_input are present.
  6. Confirm secrets in runner-specific metadata are redacted.
  7. Run the project validation command from Development checks.

What's next​

ReferenceRunner adapter contractThe shipped contract every preview adapter implements.ReferencePrompt compilerThe compiler output shape that drives preview adapters.GuideSingle-agent fixture loopCompose preview adapters into the full loop boundary.