kilroy: Instructions file for Codex

Repository Guidelines

What Kilroy Is

Kilroy is a local-first Go CLI for running software-factory pipelines in a Git repository. There is a skill to convert English requirements into DOT graphs. Then it validates graph semantics and executes stages with checkpoint commits and a run history backed by cxdb. Foundational specs that are in docs/strongdm/attractor.

Use Kilroy in this order: build the binary, generate or write a graph, validate it, then run it with a config file. Typical flow: go build -o ./kilroy ./cmd/kilroy, ./kilroy attractor ingest -o pipeline.dot "<requirements>", ./kilroy attractor validate --graph pipeline.dot, then ./kilroy attractor run --graph pipeline.dot --config run.yaml.

What you're doing here - the Prime Directive.

If you can see this message, then you are not here to use Kilroy - YOU ARE HERE TO IMPROVE KILROY. If Kilroy fails to build a project:

• Don't fix the project
• Don't fix the dotfile
• Don't fix the system so it works for this project Use the knowledge you've gained from the failure to make the system more robust for every project. Your changes should work for every project, every language, every system. Of course, specific user instructions may override this, or any other section.

Think like a user

Think about a blank slate agent that is trying to properly create a dotfile using the dotfile skill and then run it with the attractor. What mistakes would it make? What ergonomics would steer it away? How can you make that robust for every possible project the attractor could work on, not just this one? How can you do that without asking it to know the impossible, like how hard a problem is or how long something might take?

Canonical Specs

These three specs are the true north for system design. If you are making a change that relates to one of their areas, you must consult the relevant spec first to see what the idiomatic solution is.

• Unified LLM Spec (docs/strongdm/attractor/unified-llm-spec.md): Provider-agnostic LLM client — a single Client interface across LLM endpoints with unified types, retry/backoff, streaming, and tool calling. Key implementation: internal/llm/ (client, types, errors, retry, generate, streaming) and internal/llm/providers/ (per-provider adapters).