Universal AI Context Layer (UACL)

Experimental context compiler for AI-assisted development.

UACL is a prototype that generates, validates, and maintains AGENTS.md and AI-readable project context from repository sources.

UACL does not replace AGENTS.md. It can generate and support AGENTS.md while compiling related Markdown and JSON context outputs. Its intended role is to explore repeatable compilation, validation, and lightweight drift detection as a repository changes.

Existing source code, README files, documentation, and architecture decision records remain the source of truth. UACL compiles from those sources and preserves explicitly maintained context fields; it does not supersede disciplined project documentation.

Experimental Status

UACL is an experimental project.

It explores whether generated and maintained AI-readable context files can improve AI-assisted development workflows across tools such as Claude, Codex, Cursor, Gemini, and others.

At this stage, there is no strong evidence that this approach consistently improves results across different models or coding agents. The project is kept open and documented as an exploration of the problem space: context drift, stale AI instructions, repository-aware context compilation, and cross-tool AI workflows.

The current value of UACL is primarily:

• documenting the experiment clearly
• providing a small working prototype
• making assumptions and limitations explicit
• creating a base for future validation or refinement

Validation Needed

The main open question is whether generated context actually helps AI coding agents in practice.

Future validation should compare:

• agent runs with and without UACL-generated context
• task completion quality
• number of irrelevant files read
• incorrect assumptions
• token usage
• test selection
• whether stale or generated context hurts more than it helps

Until such testing exists, UACL should be treated as an experiment rather than a recommended production workflow.

Suggested GitHub About: Experimental context compiler for AI-assisted development. Generates and validates AGENTS.md and AI-readable project context from repository sources.

Why UACL

Project context is often distributed across source code, README files, documentation, architecture decisions, task notes, and existing agent instructions. Even when a project has an AGENTS.md, it can become stale as files move and decisions change.

UACL provides a lightweight maintenance workflow:

• Generate: analyze repository structure and refresh the canonical context.
• Compile: produce AGENTS.md, UACL Markdown, and JSON outputs.
• Validate: detect missing referenced files, empty important sections, missing outputs, and stale exports.
• Preserve: keep human-authored goals, decisions, constraints, tasks, and AI instructions when generated repository analysis is refreshed.

UACL attempts to support repository instruction conventions by maintaining context artifacts that existing AI tools can consume.

Context Compiler Model

source code
README and docs
ADRs
existing AGENTS.md
.ai/context.yaml
future issue/task integrations
        |
        v
      UACL
 generate + validate + refresh
        |
        v
AGENTS.md + UACL_CONTEXT.md + JSON

The current prototype analyzes Python, JavaScript, and TypeScript repository structure; tracks README, docs, ADRs, existing AGENTS.md, and the canonical YAML as context sources; and preserves manually recorded project knowledge. Issue and task-system integrations are future work.

Outputs

aicontext export always compiles outputs under .ai/exports/:

• .ai/exports/AGENTS.md
• .ai/exports/UACL_CONTEXT.md
• .ai/exports/uacl-context.json
• compatibility aliases: AI_CONTEXT.md and project-context.json

To explicitly write a root-level AGENTS.md:

aicontext export --write-agents-md

UACL will not overwrite an existing root AGENTS.md unless --force is also passed:

aicontext export --write-agents-md --force

Workflow

1. Run aicontext generate to analyze the repository and refresh .ai/context.yaml.
2. Edit the canonical YAML to record goals, decisions, constraints, tasks, and instructions.
3. Run aicontext check to find simple drift and completeness problems.
4. Run aicontext export to compile fresh AI-consumable outputs.
5. Optionally write a root AGENTS.md explicitly for tools that discover it there.

Installation

Requires Python 3.11 or newer.

Recommended: uv

uv sync --extra dev
uv run aicontext --help

uv.lock keeps development environments reproducible. uv is recommended, but it is not required.

Alternative: venv and pip

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Both workflows install aicontext. The CLI name, ai_context_map Python package, .aicontext.toml, and .ai/context.yaml remain for compatibility.

CLI Workflow

aicontext generate
aicontext inspect
aicontext check
aicontext export
aicontext export --write-agents-md

With uv, prefix commands with uv run:

uv run aicontext generate
uv run aicontext inspect
uv run aicontext check
uv run aicontext export
uv run aicontext export --write-agents-md

Additional commands:

aicontext init
aicontext inspect-routes
aicontext export --output-dir ./compiled-context

Canonical Context

.ai/context.yaml combines generated repository analysis with human-maintained context:

project_goals:
  - Keep generated AI instructions aligned with the repository.
current_tasks:
  - Validate AGENTS.md generation.
decisions:
  - title: Treat AGENTS.md as a compiled output
    rationale: Existing standards should be supported rather than replaced.
constraints:
  - Never overwrite a root AGENTS.md without an explicit force flag.
ai_instructions:
  - Run tests and formatting checks before completing changes.

The schema also records:

• context_sources
• generated_outputs
• last_generated_at
• drift_warnings
• validation_warnings
• agent_roles
• ai_instructions

Drift Checks

aicontext check performs intentionally lightweight checks:

• important referenced files that no longer exist
• source or documentation newer than the canonical context
• missing .ai/exports/AGENTS.md
• missing or stale generated outputs
• empty goals, constraints, tasks, or decisions

Warnings are recorded in the canonical context. This provides a lightweight first pass, not semantic validation of every instruction.

Related Tools / Positioning

UACL exists in a growing ecosystem of tools and conventions around AI context files and AGENTS.md. It does not claim to define or own this category.

UACL currently focuses on:

• repository context compilation
• AGENTS.md export
• drift and staleness checks
• preserving human-authored context fields

Other tools may provide deeper semantic or AST-based drift detection. UACL's current drift checks are intentionally lightweight.

Optional Agent Workflows

Shared agent roles and orchestration are a possible use of compiled context, not UACL's core promise. See examples/agent-orchestration.yaml for a lightweight future-direction example.

Examples

• examples/AGENTS.md: compiled repository instructions
• examples/UACL_CONTEXT.md: compiled Markdown context
• examples/uacl-context.json: machine-readable compiled context
• examples/AI_CONTEXT.md and examples/project-context.json: compatibility aliases
• examples/agent-orchestration.yaml: optional future agent workflow

Development

uv sync --extra dev
uv run pytest -q
uv run ruff check .
uv run ruff format --check .

GitHub Actions runs the test suite, Ruff linting, and formatting checks on every push and pull request.

Possible Future Direction

A stronger future direction may be risk-aware context rather than broad context generation.

Instead of trying to tell an AI agent everything about a repository, UACL may evolve toward surfacing task-specific warnings that are difficult to infer from code alone, such as:

• files or areas involved in repeated regressions
• hidden coupling between files that often change together
• fragile modules with repeated hotfixes or reverts
• AI-generated code that needs extra review
• tests that may provide false confidence

This direction still needs validation before implementation.

Current Limitations

• There is no proven productivity improvement from using UACL yet.
• Generated context may become stale.
• Generated context may harm results when it is wrong, incomplete, or noisy.
• Current drift checks are lightweight, timestamp- and reference-based rather than semantic.
• UACL is not recommended as a production workflow without validation.
• Documentation and ADR ingestion is lightweight.
• UACL does not automatically solve context loss between AI tools.
• UACL does not replace disciplined documentation or make generated outputs authoritative over their repository sources.
• UACL is not yet a full semantic indexer or MCP server.
• UACL does not yet import issues from external trackers, resolve conflicting instructions, or automatically update a hand-authored root AGENTS.md.

License

Licensed under the Apache License 2.0.