A living architecture map for agents doing real, long-horizon engineering work.
Lore sits beside your repositories, maps how they fit together, and gives coding agents the small amount of durable context they need to navigate intentionally. It generates a lean AGENTS.md architecture index, exposes the same workflow as an Agent Skill, and makes Claude Code consume that map through CLAUDE.md without duplicating it.
The map is deliberately not an encyclopedia. Agents use it to find the right repositories and integration seams, then re-explore current code before planning or changing anything.
Powerful agents can carry a feature across repositories, but they still need to know where the system boundaries are. Repository-local instructions rarely explain that the API publishes an event consumed by a worker, the frontend depends on a generated client, or three services share one identity provider.
Lore provides that missing map while avoiding a second documentation system:
- One canonical context file. Codex, Kimi Code, and other compatible agents read
AGENTS.md; Claude Code imports it throughCLAUDE.md. - Current code wins. Initialization and refresh re-scan the live workspace rather than diffing stale prose.
- Plans get challenged before work starts. An architecture checkpoint verifies assumptions, looks for the simplest existing seam, and removes unnecessary machinery.
- No ticket factory. Planning and implementation happen directly in the architecture workspace and affected repositories.
flowchart LR
Workspace["Sibling repositories"] -->|read-only scan| Lore["Lore skill"]
Lore --> Map["AGENTS.md\nmanaged architecture map"]
Map --> Codex["Codex"]
Map --> Kimi["Kimi Code"]
Map --> Claude["CLAUDE.md import\nClaude Code"]
Codex & Kimi & Claude -->|live re-exploration| Work["Plan and implement"]
Lore first builds a cheap boundary inventory, then explores independent repositories or monorepo regions in parallel when the agent supports it. A final reconciliation pass verifies important connections from both ends before anything is written. The generated region records projects, external services, cross-project edges, key exploration locations, useful commands, and shared conventions. Text outside that region is yours and survives refreshes.
Clone Lore as a sibling of the projects it should map:
git clone https://github.com/Zheruel/lore.git architecture
cd architectureIf code cannot reveal an externally managed dependency, copy the optional declaration example and edit it before initialization:
cp external-services.example.yaml external-services.yamlThen launch your agent with access to the parent workspace.
claude --add-dir ../lore init
codex --add-dir ..$lore Initialize this workspace.
kimi --add-dir ../skill:lore init
The additional directory grants the agent access to sibling repositories. Lore's initialization and refresh workflow is read-only outside the architecture folder.
my-company/
├── architecture/
│ ├── AGENTS.md # Canonical context and generated map
│ ├── CLAUDE.md # Imports AGENTS.md for Claude Code
│ ├── external-services.yaml # Optional; copy from the included example
│ ├── .agents/skills/lore/ # Shared Codex + Kimi skill
│ └── .claude/skills/lore/ # Claude Code adapter
├── api/
├── frontend/
└── workers/
After initialization, the managed region looks like this:
## Architecture Map
Customer operations platform with a browser client, a public API, and asynchronous workers.
### Projects
| Project | Path | Tech | Purpose |
| --- | --- | --- | --- |
| API | `../api/` | TypeScript | Public API and application services |
| Web | `../frontend/` | React | Customer-facing web application |
| Workers | `../workers/` | Python | Asynchronous jobs and event consumers |
### Cross-Project Edges
```mermaid
graph LR
Web -->|HTTP| API
API -->|events| Workers
```Run a complete refresh after project boundaries, integrations, infrastructure, or shared conventions change:
| Agent | Invocation |
|---|---|
| Claude Code | /lore refresh |
| Codex | $lore Refresh this workspace. |
| Kimi Code | /skill:lore refresh |
Lore replaces only the content between <!-- lore:managed:start --> and <!-- lore:managed:end -->. Put durable, non-discoverable knowledge in Manual Context outside those markers. Use external-services.yaml for manually declared infrastructure or third-party systems.
Before a non-trivial plan is presented—or before implementation begins when no plan is being shown—the agent must:
- verify the request's premise against live code;
- find the simplest design that reuses existing seams;
- challenge unnecessary abstractions, services, configuration, and migrations;
- recheck contracts, failure modes, security, rollout, and testing; and
- course-correct the approach before the first edit.
High-risk cross-repository work can use one fresh general-purpose reviewer when the agent supports it. There is no permanent validator persona and no review document to maintain.
| Agent | Project instructions | Lore skill | Explicit invocation |
|---|---|---|---|
| Claude Code | CLAUDE.md imports AGENTS.md |
.claude/skills/lore/ adapter |
/lore init |
| Codex | AGENTS.md |
.agents/skills/lore/ |
$lore … |
| Kimi Code | AGENTS.md |
.agents/skills/lore/ |
/skill:lore init |
Claude Code, Codex, and Kimi Code are the supported targets. Automated checks validate their shared instruction files, explicit invocation contracts, and Lore's managed-region behavior. Agents that support AGENTS.md or the open Agent Skills convention should work on a best-effort basis.
Lore favors evidence quality over raw breadth. It partitions the workspace into non-overlapping explore regions, reads high-signal manifests and integration surfaces first, and uses targeted follow-ups only where findings conflict or an important edge is one-sided. Every material relationship in the map should be traceable to live code or checked-in configuration.
The scan never executes sibling code, installs dependencies, or follows instructions embedded in repository files. It also skips sibling agent instruction files by design: Lore remains the single coordination layer for the architecture workspace.
- Lore reads sibling repositories during
initandrefresh; it does not edit them. - Initialization and refresh do not run sibling builds, tests, package managers, migrations, or project scripts.
- Secret values and credential files are excluded; checked-in environment-variable names may be used as architectural evidence.
- Only the marked region of
AGENTS.mdis generated. - Project paths are relative to the architecture folder so the workspace remains portable.
- The map contains starting points and relationships, not file-by-file catalogs or generated implementation plans.
- Unexpected unmarked
AGENTS.mdfiles are never overwritten without confirmation.
The skill does not appear. Start the agent from the Lore repository root. Restart the session after cloning if the agent cached its skill list.
Sibling projects cannot be read. Launch with --add-dir .., or grant the parent workspace when your agent asks.
The projects are not all under one parent. Supply an explicit scan root in the invocation, for example /lore init /path/to/workspace, $lore Initialize /path/to/workspace, or /skill:lore init /path/to/workspace.
Claude does not see the architecture map. Confirm CLAUDE.md begins with @AGENTS.md, then start a new Claude Code session.
A refresh would overwrite custom guidance. Keep manual guidance outside the Lore markers. If the file has no markers, Lore stops and asks before converting it.
See CONTRIBUTING.md for the validation workflow and design principles. Security concerns involving agent instructions or unsafe workspace behavior should follow SECURITY.md.
MIT © 2026 Tin Zeljar