A quick orientation for contributors. Start with one rule, one engine, or one workflow improvement while keeping the responsibility boundary clear.
CONTRIBUTING.md.
CHANGE STATE ─────────► Optimizer DETECT PROBLEM ─────────► Validator DETECT SECURITY RISK ───────► Security Workflow order is separate from module ownership.
A rule looking at CPU, memory, probes, labels, or another field does not determine which engine owns it. What the rule is responsible for does.
Ask: am I changing state, detecting a general problem, or detecting a security risk?
The rule should remain self-contained and avoid depending on another rule's internal result.
Do not move responsibility between engines just because a workflow runs one before another.
The connection is provided by workflow composition. An engine does not need to become aware of every other engine.
Where an engine runs is a workflow concern too. The experimental remote example invokes the same engines through HTTP clients (koss remote) without changing what each one is responsible for. A new resource type needs serialization support in kostral/adapters/remote/client.py before it can pass through the remote adapter.
| If you want to... | Read |
|---|---|
| Understand the conceptual model | system-model.md |
| Understand engine/IR boundaries | architecture.md |
| Understand protected behavior | guarantees.md |
| Understand remote engine invocation | remote-engines.md |
| Start coding | GitHub repository |