AI Library

Created at: September 7, 2026, last updated at: September 7, 2026

AI coding instructions tend to accumulate one repository at a time. A TypeScript rule gets copied into several projects, a linting workflow changes in one of them, and the copies gradually disagree. A single shared document avoids some duplication, but cannot express every combination of application architecture, language, and tooling without making each repository read rules it does not need.

ai-lib is a TypeScript CLI and catalog for composing that guidance. It selects modules appropriate to a repository, resolves their dependencies, activates rules for particular module combinations, and installs the resulting instructions and skills as local files. The package is named @sabinmarcu/ai; its executable is ai.

What it manages

The catalog contains guidance rather than an AI model or an inference service. Its modules describe concerns such as Node.js project architecture, TypeScript, React, Yarn, ESLint, Git hooks, and commit conventions. Source assets include agent instructions and skills that explain how to work with those concerns.

Applying a stack writes the selected AI assets and a managed entrypoint. It does not, by itself, install ESLint, rewrite application code, or perform every setup step described by a skill. Those instructions are consumed by a coding agent working in the target repository.

The distinction matters: ai-lib makes the instruction set reproducible and inspectable. It does not guarantee that an agent will follow it or that the resulting application configuration is correct.

From repository evidence to an instruction set

Detection inspects repository structure and package information. A module can provide its own detector, which returns an applicability decision, a reason, and supporting evidence. This keeps the knowledge of what makes TypeScript or a particular tool relevant beside the module that supplies its guidance.

The selected stack is not the complete instruction set. A preset supplies a bundle of module IDs, and ordinary modules can depend on other modules. Resolution expands those dependencies and rejects incompatible selections. Mixins are evaluated afterwards: they activate only when every ordinary module they require is present.

For example, TypeScript guidance and ESLint guidance can stand independently. When both are selected, a TypeScript-and-ESLint mixin supplies the integration rules. It is not another option that the user must remember to select.

Example resolution flow

A typical Node web application using TypeScript and ESLint illustrates how a stack is constructed. Selecting the node-web preset and adding tooling/eslint starts with two explicit inputs, which expand into eight effective modules and trigger two mixins automatically:

The workflow operates in distinct steps:

1. Input Selections: The user or detector requests the node-web preset and the tooling/eslint module.
2. Preset Expansion: node-web expands into its constituent modules (lang/typescript, arch/react, arch/web-application, guardrails/web-platform, guardrails/web-style, tooling/yarn, and global/core).
3. Transitive Dependency Resolution: arch/web-application and tooling/eslint both declare a dependency on arch/node-package, which is pulled into the effective module set automatically.
4. Automatic Mixin Triggers: The resolver evaluates registered mixin conditions against the effective module list. Because lang/typescript and tooling/eslint are both present, mixin/typescript-eslint activates. Similarly, arch/react and tooling/eslint activate mixin/react-eslint.
5. Materialization: All effective modules and active mixins write their source assets to target paths under .github/instructions/shared/ and assemble .ai/AGENTS.md.

Local files with recorded ownership

The normal asset mode materializes catalog assets into the consuming repository. The repository therefore retains its instructions without needing a live connection to ai-lib's source repository during everyday work.

Three files describe the installation:

A reference in the repository's root AGENTS.md directs agents to the managed entrypoint. Module and mixin assets retain provenance markers identifying their catalog owner and version.

Repository-specific tuning belongs in local override locations, not in shared copies. Recorded hashes allow the CLI to distinguish an upstream update from a local edit before replacing a file.

Reconciliation as the repository changes

An instruction stack can become inaccurate even when nobody edits its files. Adding TypeScript, removing a tool, or changing a project's role changes which guidance applies.

Reconciliation compares the existing stack with a newly detected selection. Its plan includes selected and effective module changes, mixin activation changes, override-path changes, and managed-file issues. Applying the plan updates the materialized assets and saved stack, then ensures the root entrypoint reference exists.

This is not a blind reset to detection results. Existing presets remain selected, and explicitly selected modules without detectors are retained. Modules with detectors are reconsidered against the current repository.

Boundaries

The default workflow vendors shared guidance; it does not require the consuming repository to import a runtime library. An alternative source mode links catalog assets in place, but requires those assets to live inside the target repository. It is useful when working on a catalog in the repository that consumes it, rather than as a pointer to an arbitrary external checkout.

The implementation also separates file synchronization from merging local changes. Drift is something to inspect and resolve deliberately, not text that can always be merged automatically. Controlled backporting of shared changes is a stated project goal; it is not a registered CLI command in the source described here.