Create Runfile

Create Runfile

Scope

This skill owns run config authoring (run.yaml / run.json) for kilroy attractor run and resume.

In scope:

• Building config structure (version: 1 schema).
• Aligning provider backends with DOT model/provider usage.
• Setting runtime, preflight, modeldb, git, and CXDB defaults.

Out of scope:

• DOT graph authoring and routing design. Use create-dotfile for graph work.

Overview

Core principle:

• Keep execution policy in run config, not in DOT topology.
• Align run config with what the graph needs to execute now.
• Favor explicit, deterministic defaults over implicit behavior.

Default run-config source:

• skills/create-runfile/reference_run_template.yaml

Workflow

1. Collect inputs.

• Read the target DOT graph and detect provider usage (llm_provider attrs and model_stylesheet).
• Capture user constraints for production/test mode and backend policy.

2. Choose run mode explicitly.

• Production mode: llm.cli_profile: real and no test-shim flags.
• Test mode: llm.cli_profile: test_shim with shim-compatible provider config.

3. Start from the template and fill required fields.

• Required: version, repo.path, cxdb.binary_addr, cxdb.http_base_url, modeldb.openrouter_model_info_path.
• Keep absolute paths for repo/modeldb/script entries.
• Emit only fields supported by internal/attractor/engine/config.go.
• Unknown keys are rejected at load time; do not emit unsupported keys.

4. Align providers with DOT.

• For every provider used by DOT, set llm.providers.<provider>.backend (api or cli).
• Do not edit DOT to force backend execution strategy.

4.5 Resolve model names deterministically when catalogs are unavailable.

• Model resolution order: user-specified model -> run snapshot/modeldb path -> internal/attractor/modeldb/pinned/openrouter_models.json -> internal/attractor/modeldb/manual_models.yaml -> skills/shared/model_fallbacks.yaml.
• Use skills/shared/model_fallbacks.yaml only as backup; never let backup entries override explicit user model/provider choices.
• Normalize known aliases through fallback mappings before emitting YAML (for example provider zai: glm-5.0 -> glm-5).

5. Populate artifact_policy from skills/shared/profile_default_env.yaml.

• The engine applies only env overrides declared explicitly in the run config.
• Read skills/shared/profile_default_env.yaml for per-profile reference values.
• Emit all required env vars for each profile used by the DOT graph.
• Set artifact_policy.checkpoint.exclude_globs for checkpoint hygiene.
• Do not use deprecated git.checkpoint_exclude_globs.

5.5 Declare secrets the project needs at build/test time.

• If the project under construction needs API keys at test or build time (e.g. GEMINI_API_KEY for smoke tests that call a live LLM), declare them in artifact_policy.env.overrides so they pass through to the agent shell.
• The agent shell deny-lists env vars whose names contain API_KEY, SECRET, TOKEN, PASSWORD, or CREDENTIAL by default. Vars declared in artifact_policy.env.overrides bypass this deny list because they represent explicit operator intent.
• Store the actual secret values in a .env file at the repo root (gitignored). The engine loads .env at startup and declared override keys pick up the OS values automatically.
• Use an empty string as the override value — the engine substitutes the real value from the environment at resolve time:

  artifact_policy:
    env:
      overrides:
        generic:
          GEMINI_API_KEY: ""   # value comes from .env / shell environment

• Never put actual secret values in the run config file.