71 lines (45 loc) · 1.89 KB

Agentic Guidance for the AIXCL Repository

This document provides normative guidance for agents (and humans using agentic tools) working with the AIXCL codebase.

Its purpose is to prevent well-intentioned but harmful changes and to preserve architectural integrity as the platform evolves.

1. Architectural Intent

AIXCL is an opinionated AI development distribution with a fixed core runtime:

Ollama
OpenCode

Do not attempt to generalize or abstract the runtime core.

2. Non-Negotiable Rules (Strict)

Agents must not:

Remove, replace, or conditionally disable runtime core components
Introduce dependencies from runtime core -> operational services
Merge runtime logic with monitoring, logging, or admin tooling
Collapse service boundaries
Introduce architectural indirection without explicit instruction

3. Safe Areas for Refactoring and Contribution

Agents may safely operate in:

Operational services (monitoring, logging, automation)
Documentation improvements
CLI ergonomics (without changing semantics)
Compose organization (if invariants are preserved)
Adding new operational profiles or tooling

4. Preferred Change Style

Declarative configuration over imperative logic
Explicit over implicit behavior
Small, reversible steps
Clear grouping by responsibility
Minimal assumptions about upstream internals

5. How to Handle Uncertainty

If an agent encounters ambiguity:

Assume runtime invariants must be preserved
Avoid introducing new dependencies
Prefer documenting a concern over changing behavior
Request clarification rather than guessing intent

6. Relationship to Other Documents

00_invariants.md -- architectural non-negotiables
02_profiles.md -- allowed compositions
service_contracts/ -- dependency direction and scope

If guidance conflicts, invariants take precedence.