create-runfile

name	create-runfile
description	Use when authoring or repairing Kilroy run config YAML/JSON files, including DOT-to-provider backend alignment and runtime policy defaults.

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.

6. Apply runtime defaults and safety guardrails.

• Set git.run_branch_prefix, git.commit_per_node, and git.require_clean intentionally.
• Keep runtime_policy explicit (stage_timeout_ms, stall_timeout_ms, retry cap).
• Enable preflight.prompt_probes and use a non-aggressive timeout baseline for real-provider runs.

7. Preserve local-run robustness.

• In this repo, keep cxdb.autostart launcher wiring when generating local CXDB configs.
• Keep artifact/checkpoint hygiene settings where relevant (for example managed tool-cache roots).

8. Validate alignment before handoff.

• Confirm every DOT provider has a run-config backend entry.
• Confirm mode consistency (real vs test_shim) with intended command flags.
• Confirm config has no unresolved placeholder paths.
• If graph prompts consume scratch artifacts, require run-scoped paths (.ai/runs/$KILROY_RUN_ID/...); root .ai is not implicitly ingested.

Non-Negotiable Guardrails

• Backend policy lives in run config; do not encode it in DOT structure.
• Do not omit providers that are referenced by the graph.
• Do not use fragile preflight probe timeouts for real-provider runs.
• Do not emit local CXDB configs without cxdb.autostart wiring in this repository context.
• Do not emit unsupported keys (for example: runtime_robustness, provider_capability_constraints).

References

• docs/strongdm/attractor/attractor-spec.md
• docs/strongdm/attractor/unified-llm-spec.md
• README.md
• skills/create-runfile/reference_run_template.yaml
• skills/shared/profile_default_env.yaml
• skills/shared/model_fallbacks.yaml