Your project should remember why it was built this way.
AlatyrCore is a vendor-neutral project guardian for software teams and AI coding agents. It helps teams keep project knowledge, architectural decisions, and development guidance in their repository, rather than relying on a person's memory or an assistant's chat history.
It connects that knowledge to compatible AI agents, helping them find relevant context, respect project boundaries, and keep supporting documentation aligned with changes. You keep using your chosen assistant; the project keeps its knowledge.
- Project memory: preserve reviewed decisions and the reasons behind them.
- Architectural continuity: distinguish accepted intent from what the code currently does.
- Project discussion: ask questions and compare changes using recorded project sources.
- Connected change: coordinate code, tests, documentation, and validation around the same change.
Status: alpha. Read the current limitations before adopting it.
- Install in an existing project: follow the installation guide and give your assistant the installation request template.
- Explore before installing: read What is AlatyrCore? or follow the documentation walkthrough.
- Check your assistant: see supported surfaces and limitations.
- Work on AlatyrCore itself: start with Contributing.
To begin without authorizing changes, open your target project in a compatible assistant and ask:
Inspect this repository and propose the smallest useful AlatyrCore installation
from https://github.com/atvardovsky/AlatyrCore. Explain what would change, what
facts are missing, and which approvals are needed. Do not edit, commit, or push.
This starts an inspection and plan, not a completed installation. Continue with the installation guide before approving changes.
A project can outlast its developers, its AI tools, and the conversations that shaped it. Without recorded decisions, the next person or agent must reconstruct why a boundary exists, who owns a business rule, or which checks matter before changing it.
Repository-owned knowledge can be reviewed alongside code, versioned with the project, and shared across compatible assistants. That does not mean copying every conversation into a memory folder. Important facts stay in their existing project sources; the Alatyr adapter records where to find them and what remains missing, stale, or contradictory.
For example, a rule against direct database writes is more useful when an agent can also find its owner, reason, affected subsystem, and required tests.
AGENTS.md is a useful starting point. Alatyr connects that entry point to
project-owned sources, accepted decisions,
freshness checks, change boundaries, and validation. The instruction file
does not need to become one large, duplicated manual.
Read the project guardian concept for the longer explanation.
Optional code and knowledge checks can compare selected Python imports and symbols with recorded architecture bindings, or prepare questions for a fresh assistant. They report evidence and gaps, not automatic architecture approval or proof of understanding.
The individual ideas are familiar: document decisions, provide relevant context, review changes, and validate results. AlatyrCore's focus is connecting them into a continuous project-owned workflow:
Understand -> discuss -> authorize -> implement -> synchronize knowledge -> validate
A compatible assistant uses the project's installed adapter to find the sources relevant to the task. It checks which decisions are accepted, which facts come from observed implementation, and where evidence is missing. The assistant can then discuss options or perform work authorized for the current task.
For business changes, the assistant must distinguish approved requirements from its own inferences. A repair retains the original reported case, so passing tests or a healthy adapter cannot by themselves mean the user's problem is fixed. For material repairs, outcome checks can bind the requested role, system and workflow to the actual observation, keeping incomplete or wrong-system evidence from qualifying recorded proofs. These checks support review; they cannot prove that an assistant captured every requirement or that an observation is authentic. For costly or repeatedly rejected work, optional bounded delivery review checks a representative outcome before expansion and requires deeper review after failed validation. Historical test reports remain distinct from current proof.
For uncertain causes, evidence-guided analysis connects hypotheses to predictions, small discriminating checks and their result artifacts. Conclusions can be revised without losing unresolved duties. Optional knowledge queries bring selected project guidance into the task, not the entire archive. These mechanisms support disciplined investigation; they do not prove better reasoning or grant permission to act.
For a registered investigation, optional question-bound routing keeps the selected question, its evidence inputs and decision owners together. It does not replace that question with another recommendation or load all task history.
For longer work, execution focus helps the assistant revisit the current goal, unresolved checks and next useful action when evidence or scope changes, without loading the whole project again. Request review keeps unfinished outcomes visible across supporting work and reports stale evidence separately; finishing preparation does not finish the task.
Current checkpoints can be bound to that task view, while older reports stay reference material. Optional checks distinguish a worker assignment from a message, compare diagnostic fixtures with declared real producer coverage, and verify the project's ordinary validation route separately from adapter health. These controls require target-specific evidence; they do not guarantee that an assistant followed instructions or that the project's behavior is correct.
When code or tests change, the assistant must review the effect on project knowledge: update affected sources, explain why no update is needed, or report blocked or unverified work. A useful discovery can be proposed for review by a project decision owner and preserved in its accepted source for later tasks.
These parts reinforce one another. Stored knowledge helps the next task only if it is current and discoverable; validation helps only if its coverage is clear; a completed implementation is not the same as finalized evidence or published changes.
Responsibility stays explicit:
- The project owns its knowledge and rules. The adapter points to existing sources rather than creating a competing description of the project.
- The agent investigates and performs authorized work. Alatyr is not an autonomous coding agent or a hosted service.
- Project decision owners retain authority. An assistant's observation or proposal does not become accepted architecture by itself.
The canonical details are in the project adapter contract, source-of-truth registry, context router, project knowledge workflow, and support-information sync rules.
You can use Alatyr to understand a project before deciding whether to change it. Ask your compatible assistant questions such as:
- Why is this module designed this way?
- Where is the source of truth for this business rule?
- Is this behavior observed, proposed, or accepted?
- Would this change conflict with our architecture?
- Which tests and project documents would need review?
A discussion or recommendation does not authorize edits. The assistant should cite project sources, separate facts from assumptions, and name missing or contradictory evidence.
The following conversations are illustrative. Angle-bracketed sources are examples of target-project evidence, not paths or business facts in AlatyrCore.
Developer:
Why can the billing module not write directly to the order database?
Alatyr:
The accepted ownership rule assigns order lifecycle state to the Order Service.
Direct writes are restricted because they bypass validation and event
publication.
Sources:
- <canonical architecture source>
- <relevant ownership or decision record>
Developer:
Add retry handling to payment processing.
Alatyr:
This may affect payment state, idempotency, failure handling, observability,
and related tests.
Before implementation, I need to inspect:
- <relevant source>
- <relevant contract>
- <relevant validation>
The installed adapter must resolve real answers from the target repository. If the sources are absent, the assistant should report that gap instead of inventing an explanation. See architecture discussion and logical integrity review.
AlatyrCore is designed for:
- maintainers of long-lived projects with important architecture and compatibility decisions;
- teams using different AI coding assistants on the same codebase;
- architects and platform teams who need project guidance to survive handoffs;
- developers who need to understand an unfamiliar project before changing it.
It is most useful when the project can provide decision owners, current sources, and meaningful validation. A small prototype may need only a compact instruction file; installing every Alatyr capability is not the goal.
For practical examples, read the team use cases and team collaboration workflow.
Installation is repository-aware adaptation performed by an AI assistant. Give the assistant this repository and access to the target project, then use the installation request template.
The assistant inspects the target, proposes an installation plan, preserves existing instructions, and asks for approval before protected changes. It derives project facts from target evidence instead of treating generic templates as accepted architecture.
The result is a project-specific adapter: the files that connect Alatyr's portable rules to your project's sources, owners, checks, and supported assistants. Missing facts remain explicit gaps.
The main support files live under .ai/: portable framework guidance,
project-owned references, and assistant workflows. Short instruction entry
points connect supported assistants to those files without replacing existing
project instructions. See the repository layout
for the source and target structures.
Optional scaffolding can create placeholder structure. It cannot inspect project truth, resolve those gaps, grant approval, or complete installation.
Enable only the capabilities the project needs and can maintain. Optional modules cover areas such as architecture knowledge, vocabulary, code-reference documentation, test-first development, diagrams, team coordination, and adapted AI infrastructure.
Lifecycle checkpoints default to non-blocking observe delivery in new installations. Supported project-local native hooks are part of approved setup; other clients retain procedural checks. Existing choices and opt-outs survive updates. Blocking and automatic reminders are not defaults. They remain disabled by default and do not grant permission, prove completion, or replace project validation; unverified clients use procedural checks.
For recurring defects, an optional repair review helps distinguish a test that ran from one that exercised the intended scenario. A faithful failing test can guide a repair; component success or a faster benchmark does not establish that the original incident is fixed. See repair evidence. Optional harness identity and behavioral/setup accounting expose reused inputs and misleading totals; they do not prove test quality. Ordinary repairs need not enable that policy; follow the core-only workflow for evidence and finalization.
Task-specific routing is designed to avoid loading the complete support library for routine work. Optional phase-specific working sets preserve required owners and checks while selecting additional evidence within budget. Contract routing separates complete graph checks from the selected area evidence an agent needs; compact views do not replace the project's canonical sources or approval boundaries. When workers are useful and the selected assistant has verified support, independent read-only investigations can be delegated with bounded context. The coordinating assistant still owns decisions, edits, integration, and final validation. Delegation can increase total token use.
See the installation guide, module profile, and large-task explanation.
Keep using your supported assistant in natural language:
Alatyr
Alatyr status
Explain this project to a new developer.
Review the architectural impact of this change.
Create or repair the project blueprint.
Update Alatyr from the selected framework source.
These are chat requests, not universal shell commands. Clear requests can route to the relevant workflow; ambiguous or protected work needs clarification or a preview and the required approval.
Inspecting, editing, committing, pushing, and live external actions have separate authorization boundaries. A previous request to commit or push does not authorize publication of a different task.
An update request includes assessing the selected framework source, adapting the target, refreshing supporting indexes, and final validation. The assistant reports acceptance or the exact blocker and next action; an assessment alone is not a completed upgrade.
Project documentation can use focused topics behind small indexes, including
existing docs outside .ai/. Alatyr can propose a bounded refactor for older,
heavy support structures; it does not reorganize them merely because you
requested an update. See topic-sized support.
Working in several local sessions? Local session presence lets participating assistants see each other's reported tasks and maintain short entries while working. New accepted installations enable it by default; coordination becomes active when multiple independent sessions report work. Existing opt-outs are preserved. Linked worktrees share the registry, and each session removes its own entry when finished. It is not a scheduler or an exclusive work lock. See session presence.
To limit task drift, assistants retain the requested outcome, exclusions and action boundaries for all work, not only interfaces or testing. Optional request checks bind work to the reviewed request and declared prerequisites; they cannot guarantee understanding or obedience. See request-bound review. For costly or repeated work, optional delivery-efficiency review helps surface stalled progress and repeated validation. Time limits trigger reassessment, not fewer required checks or permission to publish unfinished work.
Session working state stays separate. Optional worker communication shares review-required updates only within a parent group, with source/snapshot checks and explicit sibling relays. It is not shared authority or automatic messaging. See worker communication.
Linked worktrees can share an explicitly configured local tooling locator and carry reviewed active-task evidence. Optional publisher handoffs and build-capacity observations help expose coordination gaps without claiming a lock or permission. See worktree collaboration.
When another session updates Alatyr, participating agents check their loaded context at the next request or work checkpoint and reconcile affected rules before continuing. Existing sessions need the checkpoint instructions first; an update cannot silently replace context already held by a client. See active-session freshness. The same checkpoints can track selected project knowledge and its declared sources, so another session's contract or code edit prompts review rather than silent reuse of an outdated conclusion.
The assistant-facing details, including validation coverage and the transactional support finalizer, remain in AI_ASSISTANTS.md and the source tooling reference. Installed request routing is defined by installed operations and operation help.
The source VERSION currently records 0.1.0-alpha.134. Implemented assets
include framework contracts, target templates, assistant-driven installation
guidance, source checks, conformance fixtures, optional scaffolding, and an
optional installed-adapter validator.
For changes spanning modules, agents can bind work to existing contracts and separate component tests from integrated outcomes. Optional completion checkpoints review that evidence without treating a progress report as proof of completion.
Important limits:
- Instructions are not enforcement. Alatyr cannot guarantee that every assistant loads or follows every rule, or that a proposed change is correct.
- Project facts need project authority. Automated checks do not establish correct architecture or business behavior by themselves. Missing and conflicting sources still require investigation and decisions.
- Assistant support needs evidence. Bridge files and static checks do not prove identical behavior across clients. Each target must record what it has actually verified.
- Performance benefits are not established broadly. Lower onboarding effort, rework, supervision, and AI cost remain intended outcomes requiring wider field validation. Context estimates are not measured token savings, and caching benefits depend on the exact provider and client.
- There is no complete runnable demonstration target here. The quick demo is a documentation-only walkthrough.
- Optional modules create maintenance obligations. Start small rather than treating more support files as evidence of better results.
The evidence status distinguishes current-contract real-run coverage from prepared, stale, and historical evidence. The full claim boundaries, including delegation and provider limits, remain in framework guarantees and limits.
Choose the detail you need:
- Understand the concept: What is AlatyrCore? and the project guardian explanation.
- Walk through a task: documentation walkthrough.
- Use it with a team: use cases and collaboration workflow.
- Resolve common questions: FAQ.
- Install or update: installation guide.
- Check assistant support: compatibility guide.
- Explore implementation: repository layout, source architecture, and tooling reference.
- Review contracts and evidence: framework index, task evidence validation, release process, and changelog.
Human guides explain the product. Canonical policy remains owned by the referenced framework documents and rule registry, not by this README.
Start with AI_ASSISTANTS.md. It routes source maintenance, installation, and installed-project work to the appropriate instructions and canonical owners. This README is the human-facing overview, not an additional operating contract.
Read CONTRIBUTING.md, AGENTS.md, and the framework maintenance guide before making changes. Use the documented source checks; those commands validate AlatyrCore, not every target project's runtime.
AlatyrCore also uses a source-only self-application workflow for its own material changes. Small tasks stay lightweight; task/session records remain local and ignored rather than becoming a second installed adapter.
Security reports follow SECURITY.md. Do not put credentials, private project facts, or exploit details in public issues. Use pseudonymized case summaries for external project reviews; keep real identities and raw captures outside this repository.
For usage questions, start with the FAQ. Report reproducible non-sensitive problems in GitHub issues, including the Alatyr version, assistant, expected behavior, and sanitized evidence.
AlatyrCore is licensed under the Apache License, Version 2.0.
See LICENSE for the complete terms.
Unless a file explicitly states otherwise, the license covers this repository's framework documents, source tools, templates, schemas, and public documentation. It does not change the ownership or licensing of target-project source code, architecture, business rules, project-specific documentation, or project-specific adapter content generated during installation. Those remain subject to the target repository's ownership and licensing rules.
The Apache License 2.0 covers the AlatyrCore source, framework documents, templates, and tools. It does not grant rights to use the AlatyrCore name or visual identity to imply that a derived product is an official AlatyrCore release.