AIRepo

The AI-Ready Repository Framework
by MILIUTIN

AIRepo is an open, provider-neutral framework for organizing software repositories so humans and AI agents can work with explicit authority, ownership, lifecycle, provenance, compatibility, and validation boundaries.

It is not a prescribed folder tree, an agent runtime, an orchestration platform, or a replacement for a project's own architecture and governance. It is a repository assessment and design framework for making repository-facing engineering work safer and more deterministic in AI-centred development.

AI agents can generate code quickly, but repository structure often leaves critical questions implicit:

• Which artifact is authoritative?
• Who owns a semantic decision?
• What is durable state versus generated or transient output?
• Which rules actually apply to this repository?
• When is a structural change justified?
• What evidence is sufficient before an agent may make an authority-bearing claim or change?

AIRepo makes those boundaries explicit without imposing a universal technology stack or directory layout.

The canonical framework is organized into ten semantic owners:

Start with framework/SO-01.md, then use the Quick Start for an assessment.

• Project authority wins. Applying AIRepo does not make the framework part of a consumer project's authority hierarchy.
• Semantic before physical. Repository organization follows responsibility, ownership, consumers, lifecycle, and compatibility—not a preferred folder pattern.
• Evidence before authority-bearing claims. Missing evidence should trigger read-only acquisition where possible; unresolved evidence fails closed before consequential claims or actions.
• Minimal structural change. Preserve acceptable organization and introduce structure only for real consumers or reproducible failure modes.
• Provider and technology neutrality. AIRepo does not depend on a specific LLM, repository host, language, runtime, or project-management system.
• Generated views are not authority. Machine-readable and localized projections are derived from canonical semantic owners and must detect staleness.

1.0.0 is the first public release. The release was assembled from a pre-public framework lineage that was independently qualified and validated against two independent consumer scenarios before promotion. Historical pre-public identifiers are retained only in release provenance evidence.

Canonical public semantics live only in framework/.

• release/manifest.md binds the exact canonical source hashes.
• generated/airepo.machine.json is a non-authoritative deterministic machine projection.
• localization/ contains revision-bound localized projections.
• release/provenance/ contains pre-public validation and qualification evidence.

Agents and tools may consume generated/airepo.machine.json for discovery, stable identities, applicability metadata, and validation support. Canonical Markdown remains authoritative; the machine projection must fail validation when its manifest or source hashes become stale.

AIRepo can be used in three broad ways:

1. Read-only assessment — evaluate an existing repository and produce evidence-backed findings without modifying it.
2. Repository design — propose the smallest structural changes required to resolve proven failure modes.
3. Adoption — bind an exact AIRepo revision to a project-owned profile while preserving the project's own authority and Systems of Record.

See docs/QUICKSTART.md.

Issues and pull requests are welcome. Contributions must preserve explicit authority boundaries, technology/provider neutrality, stable rule identity, evidence-backed reasoning, and proportional complexity. See CONTRIBUTING.md.

Do not submit secrets, credentials, customer data, production traces, personal data, or protected project decisions. See SECURITY.md.

AIRepo was created by Andrei Miliutin and published under the MILIUTIN brand.

• Website: https://miliutin.com
• LinkedIn: https://www.linkedin.com/in/discoverer
• Citation metadata: CITATION.cff

MILIUTIN is the creator/publisher brand, not a framework dependency or authority source.

Licensed under the Apache License 2.0. See LICENSE and NOTICE.