danshapiro/kilroy/create-dotfile

Create Dotfile

Scope

This skill owns DOT graph authoring and repair for Attractor pipelines.

In scope:

• Turning requirements/spec/DoD into a runnable .dot graph.
• Defining topology, node prompts, routing, model assignments, and validation behavior.
• Enforcing DOT-specific guardrails and validator compatibility.

Out of scope:

• Run config (run.yaml / run.json) authoring and backend policy details. Use create-runfile for that.

Overview

Core principle:

• Prefer validated template topology over ad-hoc graph design.
• Compose prompt text from project evidence; do not copy stale boilerplate.
• Optimize for reliable execution and recoverability, not novelty.

Default topology source:

• skills/create-dotfile/reference_template.dot

Model defaults source:

• skills/create-dotfile/preferences.yaml

Workflow

1. Fetch the current model list (required before writing any model_stylesheet).

Run: kilroy attractor modeldb suggest

Capture the output. Use ONLY the model IDs listed in the output. Do not use model IDs from memory — they go stale. If the command is unavailable, default to: claude-sonnet-4.6 (anthropic), gemini-3-flash-preview (google), gpt-4.1 (openai).

1. Determine mode and hard constraints.

• If non-interactive/programmatic, do not ask follow-up questions.
• Extract explicit constraints (no fanout, model/provider requirements, deliverable paths).

1. Gather repo evidence.

• Read the authoritative spec/DoD sources if provided.
• Use repo docs and files to resolve ambiguity before making assumptions.

1. Choose topology from template first.

• Start from reference_template.dot for node shapes, routing, and loop structure.
• If user says no fanout or single path, remove fan-out/fan-in branch families.
• Fan-in semantics are shape-dependent:
• shape=tripleoctagon (parallel.fan_in) uses FanInHandler winner selection/fast-forward semantics.
• Converging branches into a shape=box node is a manual merge handoff: branch worktrees are passed to the LLM in that box node, and the prompt must instruct the node to manually inspect and merge branch outputs (including git-based workflows such as git diff, commit inspection, and merge/cherry-pick by branch head_sha when appropriate).
• graph-level retry_target: Set graph-level retry_target to the earliest node that

preserves already-completed work on re-entry. For pipelines with an analysis or planning phase, point to plan_work or debate_consolidate so re-entry can reuse completed design docs and implementation files. Pointing retry_target at a specific implement_* node skips all sibling workers' output.

Implementation Decomposition

• If the task involves implementing or porting a codebase estimated to exceed ~1,000 lines of new code, decompose the implement node into per-module fan-out nodes (e.g. implement_core, implement_api, implement_data_layer) with a merge_implementation synthesis node. Each module node targets a bounded deliverable (~200–500 lines). A single implement node for large codebases produces stub implementations that pass structural checks but deliver no functional behavior.
• Use parallel fan-out (multiple implement_X → merge_implementation) or sequential chain as appropriate. Each implement_X node writes to .ai/runs/$KILROY_RUN_ID/module_X_impl.md and commits the code. merge_implementation synthesizes integration points and resolves conflicts.
• Threshold: >1,000 estimated lines of new code → decompose. The cost of extra nodes is much lower than a stub implementation.

Analyze-before-implement (required when porting or reading existing source): When the task involves translating, porting, or extending an existing codebase, insert a dedicated analysis cluster BEFORE any implement_* nodes:

analyze_fanout (shape=component) → analyze_<module>×N (shape=box, auto_status=true)
  → merge_analysis (shape=box, auto_status=true) → [implement cluster]

Each analyze_<module> node reads specific source files and writes a compact design doc to .ai/runs/$KILROY_RUN_ID/design_<module>.md (under 300 lines — spec only, no implementation code). merge_analysis verifies all design docs exist and are cross-module consistent. Only after merge_analysis succeeds does the pipeline proceed to implement_* nodes. See skills/create-dotfile/reference_template.dot OPTIONAL comments for stub examples.

auto_status=true assignment rules:

• MUST: synthesis nodes — consolidate_, merge_, debate_*, review_consensus, postmortem
• SHOULD: all implement_, analyze_ nodes in fan-outs — their primary

completion signal is the deliverable file; auto_status removes redundant success writes

• NEVER on shape=diamond routing nodes or shape=parallelogram tool nodes

1. Set model/provider resolution in model_stylesheet.

• Ensure every shape=box node resolves provider + model via attrs or stylesheet.
• Keep backend choice (cli vs api) out of DOT; backend belongs in run config.
• model_stylesheet declarations MUST use semicolons to separate property-value pairs within each selector block. Omitting semicolons causes silent parsing failures where nodes resolve to no provider.
• Correct: * { llm_model: gemini-2.0-flash; llm_provider: google; }
• Wrong: * { llm_model: gemini-2.0-flash llm_provider: google } — space-separated declarations silently fail.
• After writing model_stylesheet: verify each {} block uses only semicolon-terminated declarations; no two property names appear adjacent without a semicolon separator.
• Anthropic model IDs use dot-separated version numbers: claude-opus-4.6, claude-sonnet-4.6, claude-haiku-4.5. Never use dashes in the version suffix — claude-opus-4-6 is wrong and will cause a validation ERROR. The three current canonical Anthropic IDs are: claude-opus-4.6, claude-sonnet-4.6, claude-haiku-4.5.

Model Constraint Contract (Required)

• Treat explicit user model/provider directives as hard constraints.
• For explicit fan-out mappings, keep branch-to-model assignments one-to-one; do not reorder branches or merge assignments.
• Canonicalize provider aliases for DOT keys: gemini/google_ai_studio -> google, z-ai/z.ai -> zai, moonshot/moonshotai -> kimi, minimax-ai -> minimax.
• Resolve explicit model IDs against local evidence in this order:

1. exact user-provided ID (if already canonical),
2. internal/attractor/modeldb/pinned/openrouter_models.json,
3. internal/attractor/modeldb/manual_models.yaml (if present),
4. skills/shared/model_fallbacks.yaml (backup only when other sources fail).

• Never silently downgrade or substitute an explicit model request with a different major/minor family (example: requested glm-5 must not become glm-4.5).
• If exact canonical resolution is unavailable, preserve the user-requested model literal in llm_model (normalize whitespace only) instead of guessing a nearby model.
• Apply known alias normalization from the fallback file before deciding unresolved status (for example: glm-5.0 -> glm-5 for provider zai).
• Explicit user model/provider directives override skills/create-dotfile/preferences.yaml defaults.