If you do a lot of agentic work that crosses repository boundaries, a nexus is a handy pattern. It gives agents a stable place from which to discover the repositories, instructions, tools, and shared knowledge needed to complete work that does not fit neatly inside a single project.
The concept
A nexus is a stable, version-controlled home for agentic work.
It gives agents one place to begin, where they can discover the relevant projects, instructions, tools, and accumulated knowledge. Instead of repeatedly reconstructing context in prompts, you make that context persistent and navigable.
A nexus is not a monorepo, wiki, or orchestrator. It does not need to own everything or control every workflow. Its purpose is to make independently managed resources meaningfully adjacent.
Centralize context, not ownership.
Agents are often capable enough to perform a task, but lack the surrounding context needed to act correctly. A nexus closes that gap. It turns isolated sessions into cumulative work: agents can inherit what was learned before, operate under explicit rules, and leave useful knowledge behind.
A monorepo centralizes code. A wiki centralizes knowledge. An orchestrator centralizes execution. A nexus centralizes context.
Implementation guidelines
Start with an ordinary Git repository
Create one repository to act as the stable entry point for agent sessions. Its
root should contain a short inventory, the root AGENTS.md, and only files that
apply to the nexus as a whole.
The nexus should be useful immediately after a recursive clone. Document any remaining bootstrap steps, but avoid making successful orientation depend on unrecorded machine state or a previous chat session.
Add existing repositories as submodules
Do not merge independent repositories merely to make them visible to agents. Keep their histories, remotes, permissions, and release cycles intact by adding them as Git submodules:
git submodule add git@example.com:team/project.git projects/project git commit -m "Add project to nexus"
Clone the resulting nexus with:
git clone --recurse-submodules git@example.com:me/nexus.git
For an existing checkout, initialize the revisions pinned by the nexus:
git submodule update --init --recursive
The superproject records a known combination of repository revisions. This makes the nexus a reproducible snapshot of context without turning it into a single release unit.
When changing a submodule, commit and push that repository first. Only then commit the updated gitlink in the nexus. Otherwise a fresh recursive clone may refer to a commit that nobody else can fetch.
Use git submodule update --remote only when intentionally advancing to newer
upstream revisions. It should not be confused with restoring the revisions
already pinned by the nexus.
Organize by relationship, not by technology
Choose paths that help an agent infer why something is present. A small nexus
might keep repositories directly below the root. A larger one can group them
under directories such as projects/, operations/, knowledge/, and
tools/.
The names are less important than a topology that remains stable and obvious. Avoid deep taxonomies that require prior knowledge to navigate.
Layer instructions by scope
Put nexus-wide policy in the root AGENTS.md. Put domain-specific instructions
in the relevant subdirectory or repository. Agents should receive broad safety
and coordination rules at the root, then increasingly concrete guidance as
they approach the files they will change.
Instructions should state:
- where canonical knowledge lives;
- how to verify changes;
- how cross-repository commits are handled;
- which operations require confirmation;
- where secrets come from without revealing them;
- and what evidence is required before work is considered complete.
Prompt instructions improve coordination, but they are not an authorization boundary. Enforce important restrictions with operating-system permissions, scoped credentials, network controls, and sandboxing.
Give knowledge a canonical home
Agents should not have to rediscover the same facts in every session. Designate a versioned location for durable knowledge and require useful findings, decisions, procedures, and unresolved questions to be recorded there.
Prefer one canonical page over duplicated notes in several repositories. Project-local documentation can link to the canonical page when broader context is useful.
Keep durable knowledge distinct from transient output. Build artifacts, caches, logs, credentials, and temporary agent state generally do not belong in Git.
Make capabilities discoverable
Keep reusable scripts, skills, commands, and tool documentation close enough to the nexus that an agent can discover them. Describe when a capability should be used, its preconditions, its safety limits, and how to verify its result.
The goal is not to load all available context into every prompt. The goal is to make the right context easy to locate and cheap to load when needed.
Treat the nexus as a maintained map
A stale nexus can be worse than no nexus because it gives agents confident but incorrect context. Periodically check that:
- the inventory matches the checked-out repositories;
- submodule URLs and branches still exist;
- instructions do not contradict one another;
- operational notes identify their scope and age;
- obsolete skills and procedures are removed;
- and secrets have not entered tracked files.
Root AGENTS.md template
Adapt this template to the systems represented by the nexus. Remove rules that cannot be enforced or maintained.
# Nexus Purpose This repository is the main entry point for work that may span multiple repositories and systems. It provides the shared context needed to coordinate that work. # Repository Topology Read `INDEX.md` to make yourself familiar with the repo's topology. Repositories included as submodules retain their own history, workflow, and instructions. Read the nearest `AGENTS.md` before changing files. # Working Principles - Begin by inspecting the relevant files and current repository state. - Prefer the smallest correct change. - Do not revert or modify unrelated work. - Use canonical documentation instead of duplicating knowledge. - Start with read-only investigation and escalate to mutation deliberately. - Treat agent instructions as guidance, not as a security boundary. # Submodule Workflow - Initialize pinned revisions with `git submodule update --init --recursive`. - Update a submodule to newer upstream revisions only when the task requires it. - Commit and push submodule changes before committing the nexus gitlink. - Never publish a gitlink whose commit is unavailable from the submodule remote. - Keep unrelated submodule updates out of the same nexus commit. # Persistent Knowledge Record durable findings, decisions, procedures, verification results, and unresolved questions under `<knowledge-path>`. Update an existing canonical page when one exists. Include dates and environment details when facts may become stale. Do not rely on chat history as permanent documentation. # Safety And Secrets - Never commit passwords, tokens, private keys, cookies, or other credentials. - Document where credentials are supplied, not their values. - Require explicit confirmation for destructive, irreversible, or production-sensitive operations. - Respect repository-specific and system-specific safety rules. # Verification Follow the target repository's own test, review, deployment, and verification procedures. Do not claim completion without evidence appropriate to the change. For cross-repository work, verify each changed repository independently and then verify the integrated outcome. # Completion Before finishing: 1. Confirm that intended changes are committed in the correct repositories. 2. Confirm that required submodule commits are available remotely. 3. Record durable knowledge gained during the task. 4. Report verification performed and any unresolved risks.
Root INDEX.md template
The INDEX.md file is quite simple. It lists all relevant paths (of
submodules) with a concise one-line description of their purpose. Of
course this is highly dependent of your use cases.
# Repo Topology - `<path>`: `<purpose and ownership>` - `<path>`: `<purpose and ownership>` - `<knowledge-path>`: canonical durable documentation - `<tools-path>`: reusable agent tools, skills, and commands
The template's most important property is not its exact wording. It establishes the nexus as an entry point, delegates local behavior to nearer instructions, preserves knowledge across sessions, and makes cross-repository work reproducible.
If you liked this post, please consider supporting our Free and Open Source software work – you can sponsor us on Github and Patreon or star our FLOSS repositories.
