1. Problem: context grows faster than code

As the number of repositories increases, eight systemic failures become evident:

1. Duplication. A single workflow ("audit", "release" or "deploy") is copied into every repository and diverges into multiple versions.
2. Index drift. Manually maintained lists such as "22 commands, 14 rules" become obsolete immediately after publication.
3. Lack of history. A deleted skill cannot be restored, and the instructions in effect at a given date cannot be determined.
4. Invisible layers. Actual context = built-in IDE capabilities + user-global + plugins + MCP + project files. No comprehensive view exists.
5. Bidirectional chaos. Changes are made in both the project and the central library, causing layer conflicts and obscuring the canonical version.
6. Uncontrolled external context. Plugins and MCP servers are connected without demonstrated need, increasing prompt volume while remaining subject to an external release cycle.
7. Untestable behaviour. Skill changes enter operational use without tests, and regressions become apparent only during an operational task.
8. Fragility. Years of domain knowledge reside as instructions on a single storage device, without an off-site copy.

2. Inputs and definitions

A shared vocabulary for this document: without it, the same words denote different concepts across sections. Narrow terms for connecting a repository to the system (sync registration, MCP snapshots and related terms) are collected separately in the integration glossary.

3. The working repository is the single source of truth

Each project manages its AI context locally, in the directory that the IDE reads by default (for example, .cursor/ or its equivalent). This is not a copy derived from the central library; it is the authoritative version for that repository.

Contents of home

• Skills - step-by-step workflows (audit, commit, migration and domain procedures).
• Rules - mandatory restrictions (language of reports, pre-change protocol, prohibitions).
• Agents - specialised roles for delegation.
• Commands - operational entry points without a separate skill.
• Orientation - AGENTS.md, CLAUDE.md or equivalent: the project's purpose, available skills and navigation paths.

Push-only sync

Changes are made only in the working repository and are then published unidirectionally to the central library. The reverse flow - editing a project's files in the library - is prohibited because it would establish two sources of truth.

Minimum initial set

Channels and namespace (integration contract)

Each context file belongs to exactly one channel; assignment to multiple channels would create competing sources of truth:

• Project overlay (push): the project's skills / rules / agents / commands are edited only in home and published to the library.
• Core / shared (pull): common layers reside in the library and are materialised one way into projects; local edits in home are prohibited and detected by the ownership inspector.

Namespace-invariant: pull layers are materialised under a separate prefix or directory and are not mixed with the project overlay. Relative path matching between channels constitutes a model error; specificity on disk does not determine precedence.

Un-retire: reinstate an artefact from archive/ by recreating the file in home (the SSOT) and then running the normal push sync - never by editing the mirror.

4. Central Library

A separate Git repository does not replace home; it complements home in four ways:

1. Mirror - a snapshot of the context of each project in a predictable structure (projects/<slug>/skills/).
2. Evolution-Log - records who changed the stack, when and why, and constitutes the equivalent of a CHANGELOG for agent infrastructure.
3. Archive - deleted skills do not disappear; they move to archive/ with a date.
4. Cross-project index - identifies where problem X has already been solved without requiring a search of every repository.

Library structure (example)

ai-context-library/
├── projects/
│ ├── backend-api/
│ │ ├── skills/
│ │ ├── agents/
│ │ └── docs/AGENTS.md
│ ├── mobile-app/
│ │ └── ...
│ └── shared/
│ ├── register/ # pack: prose / workers (pull into homes)
│ └── svelte/ # pack: cross-Svelte stack (pull into homes)
├── Evolution-Log.md
├── history/ # timestamp snapshots after each sync
└── archive/ # retired skills with context

Backup

Apply the 3-2-1 rule: three copies of the data, on two types of media, with one copy off-site. At minimum, use a remote Git repository plus periodic export to object storage. Test recovery to a clean environment once per quarter.

Sync contract (for integration)

Each sync execution must be idempotent and produce a predictable result:

1. Copy the project overlay to projects/<slug>/ (Sync class: full_overlay or skills_only - record it in the wiring).
2. On updated: preserve the previous version in history/<timestamp>/ and write the diff to Evolution-Log.
3. On removed: move to archive/<slug>/<timestamp>/ with a metadata file (who, when, where) - do not delete permanently.
4. Write a machine-readable manifest.json for each run.
5. Where configured, commit and push the library (backup-push). Before pushing, run git pull --rebase and use either a single writer or standard Git reconciliation.

Restore script (backup DoD): clone the library → clone home → restore the overlay from the mirror on a clean machine. A backup remains unverified until a test restore succeeds.

5. Structure and layers of ownership

Context is not a flat list of files; it comprises a set of layers with distinct owners and inclusion policies.

Artefact types

Skills-first. Workflows belong in skills; commands are reserved for atomic operations without a skill wrapper. Shared stack packs live in the library under projects/shared/… and reach homes by pull - not by copy-paste into every overlay.

AIC blocks (the capability axis)

Orthogonal to ownership layers. Formula: (skills + agents + commands + rules) + (contexts + hooks) + (memory + navigation + inventory).

Ownership layers

Overlap analysis

When the project and projects/shared/ contain similar skills, select one of three options:

• Retire - the local copy is archived and the project adopts shared.
• Adopt - shared is unsuitable; the project remains the canon and shared remains unchanged.
• Hybrid - a specialised project skill calls the shared skill as a substep.

Default-deny for external context

Each MCP server, plugin and marketplace skill must pass a gate that establishes its necessity, owner, pinned version and contribution to the prompt. Connection to a production workflow without a registry entry is prohibited.

Must-have repository contract

This constitutes the minimum threshold for connecting a repository to the system. The full reusable checklist appears in → B. In summary:

1. Orientation document with explicit SSOT string and mirror path
2. Critical minimum always-on rules
3. Workflow-skills for repeatable processes
4. Operational commands (thin entry points)
5. Audit profile (machine readable)
6. Ownership config (paths and channels)
7. Slug in the library matrix and in the sync script
8. Evolution-Log (created by the first sync)
9. Git remote exists; off-site copy is current after push
10. Navigation guide (AI-GUIDE) - maintained and validated (validator = 0 errors)

Companion to item 10 (not a separate must-have). The / menu expands excessively (project, user, plugins, MCP, built-ins). Next to the guide, a human layer is required: a full inventory of those entries and an explicit priority-invocation order. AI-GUIDE stays situation → primitive and links to that layer; it does not duplicate priority lists. Diagrams and detail: → C.

Record the state of every repository in a repository × item matrix (Y/-); an approximate configuration state is not measurable.

6. Control: map, inspectors, tests

Context without measurement degrades as predictably as code without CI. Three instruments form an inspection loop.

6.1 Capability Map

A generated document or JSON inventory records all skills, rules, agents and commands by layer. A script updates it during every sync; it is never maintained manually. It provides:

• a complete inventory of the project and shared layers;
• intersections (overlap) between layers;
• connected MCPs and their tools;
• discrepancies between home and the library mirror.

6.2 Inspectors

6.3 Behaviour test pyramid

1. Static checks - valid SKILL.md structure, required sections and no broken links.
2. Smoke - the agent executes the skill's primary success path on a fixture repository.
3. Evals - a set of tasks with expected artefacts (files, commands, report format).

Initial coverage should comprise static checks and one smoke test for each critical skill (for example, "safe-commit"). Evals should be added as the skills mature.

6.4 What to include in library CI (integration)

• Index / capability-map drift (--fail-on-drift)
• Wiring: every slug in the index has a sync entry
• Ownership verification (push/pull channels, with no mirror-first edits)
• Scored audit against the audit profile in strict mode
• AI-GUIDE validation (0 errors)
• Optional local check: mirror parity home ↔ library

6.5 Runtime context hygiene (above file SSOT)

[planned] - recommendations only; not a must-have item and not a CI gate.

File SSOT (sections 3-5) governs artefacts on disk. Runtime governs the context window during a long session:

• Compaction - compact history: retain decisions and key facts; exclude repeating tool outputs.
• Structured note-taking - progress in external memory (NOTES.md / memory), retrieved on demand.
• Sub-agent condensed return - a subagent returns a short summary, not the full trace.

Correspondence: the test pyramid (§6.3) verifies behaviour; this hygiene reduces context rot during a session.

7. Change lifecycle

Every change to AI context must follow the same lifecycle as a code change:

Stages

1. Propose - edit the skill or rule in the working repository and update AGENTS.md if necessary.
2. Review - open a PR with checks for drift, overlap and rule/skill duplication.
3. Sync - the script publishes to the library, writes an Evolution-Log entry and stores the snapshot in history/.
4. Verify - run a smoke test on the affected skill; if it regresses, roll back from archive/history.

Removal and retirement

Skills must never be deleted without a record: move them to archive/<date>-<name>/ and add an Evolution-Log entry stating the reason and replacement.

8. Principles

9. Maturity and scale

The approach scales in stages. Implementation may proceed incrementally, but each level requires a sound foundation before progression to the next. The applicability threshold (when the investment is warranted) appears in the introduction; the table below is the staged maturity ladder after the decision to adopt.

Optional infrastructure evolution

• L0-L1: a Git remote and manual or scheduled sync.
• L2: a CI job for drift, plus a mirror diff after merge.
• L3: a full-text index (Elasticsearch, SQLite FTS or a monorepo tool's native search facility) covering skills and Evolution-Log.

The team selects the tools. The canon specifies what must be measurable and repeatable, rather than prescribing a vendor.

10. Getting started

Deployment follows readiness stages, not a calendar. Each stage begins only after the previous stage's Definition of Done has been satisfied. The initial implementation should establish the SSOT in home, a library mirror and minimum quality controls.

Stage 1 - foundation in home

1. Declare the working repository as the source of truth in an orientation document (AGENTS.md or equivalent) that defines the language policy, skills-first workflow and done criteria.
2. Ensure that the repository has a Git remote - this requirement is mandatory.
3. Capture 2-3 repeatable workflows as skills (for example, commit, audit and deployment).
4. Add one always-on rule with non-negotiable restrictions (pre-change protocol, prohibitions).

Stage 2 - central library

1. Create a separate library repository containing projects/<slug>/, history/ and archive/.
2. Write a sync script that copies home → library, records a timestamped snapshot in history/ and adds an entry to Evolution-Log.
3. Run the first sync and check that the mirror matches home.
4. Perform one test restore: clone the library → restore the overlay into a clean copy of home.

Stage 3 - layers and discipline

1. Mark ownership layers in AGENTS.md: project home, shared (if any), external (default-deny).
2. Separate the types of artefacts: workflow → skill, restriction → rule, narrow role → agent, atomic operation → command.
3. Complete the repository's must-have checklist (orientation, minimum rules, sync and archive instead of deletion) and note the gaps.
4. When a second similar skill appears, perform an overlap analysis (retire / adopt / hybrid).

Stage 4 - control

1. Create a capability-map script that inventories skills / rules / agents / commands from the file system rather than from a manual list.
2. Add a drift check: discrepancies between the map and references in AGENTS.md / README must block a merge or, at minimum, cause CI/pre-commit failure.
3. Add one smoke test in which the agent performs a critical skill on a fixture repository.
4. Commit external gate checklist (→ F) and a registry of connected MCPs/plugins.

Repository offboarding (exit path)

The must-have baseline describes onboarding; the reverse operation is mandatory, otherwise orphans remain in indexes and wiring.

1. Final sync - the mirror reflects the final home state.
2. Overlay archive - projects/<slug>/ → archive/<slug>/<timestamp>/ with a meta file; deletion = archiving.
3. Remove wiring - drop the slug from the sync script.
4. Index and map - remove the row from the cross-project index; regenerate the capability map.
5. Verify - drift = 0, ownership verify green, no orphans.

The archive and history/ are retained. Re-onboarding follows the same path as a new connection from home (read the archive if needed; do not edit-first in the mirror).

11. AIC roles and AI models

Operating policy for the system: which AIC roles every project must carry, and which parent model to select. This is not sync or wiring - reusable integration contracts remain in the appendices.

11.1 AIC roles

Codes in the table are portable job-shaped role identifiers. File names in a given home (skill / command / agent) may differ; what is required is the function and the must-have AIC form, not a slug match on disk. Mapping examples: dev-loop ↔ a restart/preview command; safe-commit ↔ a safe commit/push skill; ownership-check ↔ a home↔library ownership skill. Product-tied labels are not used as role codes.

Minimum AIC binding per role

11.2 AI models (LLM picker)

AI models are distinct from AIC roles: they are model families available in the picker (Grok, Opus and their peers). Agents / skills / commands do not pin model: in frontmatter; they inherit the parent session. Family names use (latest) exclusively - minor versions must not be pinned.

ON (4): Composer (latest), Grok (latest) High, Sonnet (latest) High, Opus (latest) High. Opt (not ON) - budget fallback (2): Gemini Flash (latest), GPT Luna (latest).

Task / AIC role → AI model

High is reserved for intensive exploration, audits or redesign. Routine work uses Composer without High. Model routing is defined by the table above; optionally mirrored as a local file in home. Orientation navigation links to that table (or local file) and does not duplicate prices or minor versions. AIC role codes in the table above remain portable - each repository defines the mapping onto on-disk skills / commands / agents.

Concise summaries of sections 1-11 are consolidated here for reference. Identical summaries remain at the end of their respective sections. Reusable integration contracts appear in the appendices.

Appendices - integration

Reusable contracts for connecting a repository to the system. Paths and filenames (.cursor/, AGENTS.md, CLAUDE.md) are illustrative; map the names onto the AI tooling stack in use. The conceptual model and operating policy appear in sections 1-11; these appendices cover operational procedures.

A. Runbook: connect the repository

The stages constitute a readiness sequence rather than a calendar schedule.

Step A - home + library framework

# Home: SSOT + remote
cd project
git remote -v # remote is required
$EDITOR AGENTS.md # "context-SSOT here" + path to mirror

# Library: separate repository
mkdir context-library && cd context-library
git init
mkdir -p projects external scripts docs history archive
git remote add origin 
git push -u origin HEAD

DoD A: home has a remote and an orientation document; the library repository is established and contains the required directories.

Step B - sync wiring

1. Register the slug in the sync script (class full_overlay or skills_only).
2. Implement sync: overlay → projects/<slug>/, history, archive, Evolution-Log, manifest.json.
3. Run sync and ensure the mirror matches home.
4. Perform one test restore in a clean directory.
5. Enable opt-in backup-push (after pull --rebase).

DoD B: a single sync execution mirrors the project, writes history/archive/manifest, and demonstrates successful restoration.

Step C - must-have + control

1. Complete checklist B and record any gaps in the repo × item matrix.
2. Run the capability-map generator at the end of sync.
3. CI: drift, wiring, ownership, scored-audit strict, AI-GUIDE validate.
4. Create snapshots of external layers and apply gate E to every new MCP server or plugin.
5. Run at least one smoke test per critical skill and add further evals in response to incidents.

DoD C: every context change must follow Propose → Review → Sync → Verify; degradation blocks a merge.

B. Reusable must-have checklist

Repo:  Date: ____ Responsible: ____

[ ] 1. Orientation document (AGENTS.md / CLAUDE.md)
       DoD: purpose, stack, explicit "context-SSOT here" statement, path to mirror.
[ ] 2. Critical minimum rules (always-on)
       DoD: language, prohibitions, edit policy; concise enough to remain always-on.
[ ] 3. Workflow skills
       DoD: repeatable processes as skills; no duplicate skill+command.
[ ] 4. Operational commands
       DoD: thin entry points (restart, pre-deploy); smoke test where applicable.
[ ] 5. Audit profile (JSON)
       DoD: expected architecture; scored-audit consumes the profile.
[ ] 6. Ownership config
       DoD: SSOT paths + push/pull channels; ownership-check detects violations.
[ ] 7. Wiring / index
       DoD: slug in the library matrix and in the sync script.
[ ] 8. Evolution-Log
       DoD: created by first sync; history is written from day one.
[ ] 9. Git remote + backup-push
       DoD: remote exists; off-site copy is current after push.
[ ] 10. AI-GUIDE (navigation)
       DoD: situation → primitive; maintained (current) and validator = 0 errors.
       Companion (not a separate item): human layer for «/» menu inventory + priority-invocation order;
       AI-GUIDE links to it and does not duplicate priority lists.

C. Slash UI catalog

Companion to must-have item 10 (AI-GUIDE), not a separate checklist item. The / menu mixes project, user, plugins, MCP and built-ins; a human layer is required: a full inventory of entries and an explicit priority-invocation order. AI-GUIDE stays situation → primitive and links to priorities without duplicating them.

The slash-menu catalog is stored in the working repository next to the orientation guide (typically under docs/: the catalog beside AI-GUIDE). File names, generators and CI gates are adapted to the team's tooling stack.

D. Library catalogue contract

context-library/
├── projects// # mirror overlay (skills, agents, rules, commands, docs)
├── projects/shared// # pull stack layer (namespace separated from overlay)
├── external/ # snapshots of MCP / plugins (version + hash)
├── scripts/ # sync, map, inspectors
├── docs/ # indexes, AI-GUIDE library-roles
├── history/ # timestamp snapshots before overwrite
├── archive/ # retired with metadata
├── Evolution-Log.md # or per-project log
└── manifest.json # each sync run

E. Artefact templates

E.1 Orientation document

#  - context for the AI agent

## Purpose


## Stack


## Context-SSOT
The authoritative version resides HERE, at <.cursor/ | .cloud/>.
Edits only here. Mirror (read-only): context-library/projects//.
DO NOT edit the mirror and DO NOT backport it into the project.

## Layer priority
project overlay > shared > core > user-level.
External / MCP / built-ins are not involved in resolving rule conflicts.

## Channels
- project overlay: push (home → library)
- core/shared: pull materialization (local edits are prohibited)

E.2 Always-on rules (minimum)

# Critical rules (always-on)
1. Language of communication: .
2. Prohibited actions: .
3. Edit policy: SSOT - this repo; core/shared are edited in the library.
4. Secrets MUST NOT be stored in context files.
5. Lists without "etc." / "..." - list in full.
6. Impact-before-change: explain the impact before changes.
7. One type of artefact - one location (no duplicates in other directories).

E.3 SKILL.md

---
name: 
description: 
---

# 

## When to use


## Steps
1. ...
2. ...

## Definition of Done
- [ ] 

## Must/Never
- MUST ...
- NEVER ...

## Links (lazy)
- references/
.md

Keep the body concise and place detailed material in references. Assign a low degree of freedom to destructive or operational commands and medium/high to heuristic workflows. Test the skill on the target models.

D.4 Audit profile (fragment)

{
  "repo": "",
  "repo_class": "product | library",
  "stack_mode": "",
  "required_categories": ["rules", "skills", "commands", "agents"],
  "rules": { "min_count": 1 },
  "skills": { "required_sections": ["When to apply", "Steps", "Definition of Done"] },
  "commands": { "smoke_testable": true }
}

D.5 Ownership config

{
  "repo": "<slug>",
  "ssot_paths": [".cursor/", "AGENTS.md"],
  "channels": {
    "project_overlay": "push",
    "core": "pull",
    "shared": "pull"
  },
  "mirror_path": "context-library/projects/<slug>/"
}

D.6 impact-check (example skill)

A reusable example of an always-on rule and its paired skill, presented in full as it appears in the application.

---
name: impact-check
description: Apply a strict pre-change critical checklist before editing code or docs. Use when user asks for "critical rule", "critical", "apply rules", or when starting implementation that needs impact, editing, and release-discipline safeguards.
disable-model-invocation: true
---

# Impact Check

Use this skill as a universal guardrail before making project changes.

## Goal

Enforce a consistent pre-change protocol:
- impact analysis before edits
- precise editing method
- documentation hygiene
- release/version discipline

## Mandatory Pre-Change Check

Before any edit, state:
1. current state
2. proposed change
3. impact:
   - affected files and functions
   - behaviour change
   - performance implications
   - risks

Then ask for confirmation when the repository policy requires it.

## Universal Constraints

- Do not abbreviate configuration or checklist items with `etc.`, `...`, `and so on`.
- Avoid truncating user-facing copy unless explicitly requested.

## Editing Discipline

- Prefer targeted edits over full rewrites.
- Keep diffs minimal and local to the requested change.
- Do not create extra documents unless required.
- Reuse existing documentation and repository files as source of truth.

## Release Discipline

When the workflow includes versioning:
- follow the repository's version bump process
- keep changelog/release artefacts in sync with policy
- do not invent ad-hoc version steps

## Quick Response Template

Use this short template before implementation:

```markdown
Critical check:
- Current state: ...
- Proposed change: ...
- Impact:
  - Files/functions: ...
  - Behaviour: ...
  - Performance: ...
  - Risks: ...
```

## When Not to Use

Skip this skill only when:
- the task is purely informational and no changes are requested
- the user explicitly asks to brainstorm without implementation

F. External context gate (MCP/plugin)

The default is deny. External context may be adopted only after every criterion has been satisfied:

Candidate: 

[ ] A documented task establishes the need; adoption is not precautionary.
[ ] Overlap analysis: no duplicate, or retire / adopt / hybrid is recorded.
[ ] Cost: always-on vs lazy; tokens / latency / attention.
[ ] Security: trusted source; tool poisoning / injection / exfiltration assessed.
[ ] Snapshot in external/ (version + hash + date).
[ ] Update checker; review the overlap decision during each update.
[ ] MCP: pin the tool-manifest hash (name + description + input schema); drift alert.
[ ] MCP: tool output = data, not instructions.
[ ] MCP: sandbox / least privilege; HITL on destructive / data-sharing.
[ ] MCP: multi-server = separate trust domains; no shadowing tools.

Decision: [ ] adopt [ ] hybrid [ ] retire-own [ ] deny
Who/When: ____

G. PR checklist for skill/rule

• Change only in home (project overlay) or the library (core/shared)
• Update AGENTS.md / AI-GUIDE when the inventory or policy changes
• Do not duplicate rules and skills; resolve overlap explicitly
• Drift and ownership checks pass
• Sync + Evolution-Log scheduled after merge
• Run a smoke test on the affected critical skill
• Confirm that the diff contains no secrets

H. Health metrics (monthly)

• Percentage of repositories with a current mirror (synced and with no open drift)
• Number of unresolved overlaps (retire / adopt / hybrid)
• Skills with smoke coverage (%)
• Percentage of external-registry entries with a current review
• Successful test restores from archive/library
• Percentage of library inspector runs that fail in CI

I. Checking against best practices

The approach in sections 1-11 was aligned with industry practice on the review date, 2026-08-10. Sources may have changed subsequently.

J. Glossary (integration)