Proposal: Separate Core, Configuration, and User Extensions in AIOS Projects #57
Description
# Proposal: Separate Core, Configuration, and User Extensions in AIOS Projects
Type
Architecture / Enhancement Proposal
Context
As AIOS-Core evolves — particularly with recent improvements around security, integrity validation, and signed manifests — it becomes increasingly important to formalize a clear separation between immutable core code, project-level configuration, and user-defined extensions.
Without an explicit architectural contract, projects may experience:
- loss of user configuration during Core updates
- users modifying Core internals unintentionally
- broken or inconsistent project structures
- increased maintenance, support, and security risks
This Issue proposes a clean, explicit, and enforceable project structure aligned with best practices for extensible systems and secure software distribution.
Goals
- Establish the AIOS Core as an immutable component
- Prevent user configuration and extensions from being overwritten during updates
- Improve security, predictability, and maintainability
- Provide a clear mental model for users and contributors
- Prepare the project for long-term extensibility and growth
This proposal is intentionally focused on architecture and structure, not implementation details.
1. Project Configuration File
Proposal
Introduce a single configuration file at the project root, preferably in JSON format:
.aios-core-config.json
(YAML may be optionally supported, but JSON should be the default.)
Rationale
- JSON is stricter and easier to validate
- Reduces user error compared to YAML
- Enables schema-based validation (e.g., JSON Schema)
- Provides a stable and predictable configuration surface
Location
The configuration file must live at the project root, not inside the Core directory:
/ (project root)
├── .aios-core-config.json
├── .aios-core/
├── .aios-extends/
Why this matters
- Prevents configuration loss when the Core is replaced or updated
- Reinforces the Core as an immutable, managed component
- Keeps project-specific concerns outside Core boundaries
The configuration file may include:
- paths to extension directories
- project-level AIOS settings
- feature flags and runtime options
- future configuration without modifying Core internals
2. Architectural Rule: Core Immutability
Principle
The
.aios-coredirectory must never be manually edited by users.
It should only be modified through:
- official AIOS updates
- controlled, automated processes
Rationale
- Preserves integrity and security guarantees
- Prevents accidental corruption
- Enables validation and trust mechanisms
- Simplifies upgrades and support
Recommendation
Every AIOS agent or project should include a basic rules document (.md) stating, as the first rule:
❗ Never manually edit the
.aios-coredirectory.
3. User Extension Structure
Proposal
All user-defined functionality — such as custom agents, workflows, tasks, tools, or project-specific logic — should live outside the Core, in a dedicated directory at the project root:
.aios-extends/
Suggested Structure
.aios-extends/
├── agents/
├── workflows/
├── tasks/
├── tools/
├── etc/
This structure may mirror the Core layout but must not override or modify Core files.
Rationale
- Prevents user extensions from being lost during updates
- Enables independent versioning of custom logic
- Keeps the Core clean, auditable, and secure
- Improves contributor understanding and onboarding
4. Installation and Developer Experience
Proposal
During initial AIOS setup:
-
Automatically create:
.aios-core-config.json.aios-extends/
-
Include a
.README.mdfile in each extension subdirectory explaining:- its purpose
- what belongs there
- basic usage examples
Optional Enhancement
Provide a helper command:
aios init-extendsWhich would:
- scaffold the extension directory structure
- generate README files
- prepare the project for safe and supported customization
5. Benefits
-
Clear and enforceable architecture
-
No loss of user data during Core updates
-
Stronger security and integrity guarantees
-
Improved developer experience (DX)
-
Easier maintenance and support
-
Clean separation between:
- Core (immutable)
- Configuration (project-level)
- Extensions (user-defined)
Open Questions for Discussion
- Should YAML be supported alongside JSON, or only JSON?
- Should the config file name be fixed or configurable?
- Should multiple extension roots be supported?
- How strictly should Core immutability be enforced (warnings vs hard errors)?
Conclusion
This Issue does not propose immediate code changes.
Instead, it aims to establish a clear architectural contract between AIOS-Core and the projects that use it.
By defining explicit boundaries between Core, configuration, and extensions, we can significantly improve security, extensibility, and long-term maintainability.
Feedback and discussion are encouraged before any implementation PR is opened.