Top-level lifeos/ directory for cross-cutting agent documentation¶
- Date: 2026-03-23
- Status: Accepted
- Tags:
structuretooling
Context¶
Life-OS is the Obsidian-based personal knowledge management system at the
centre of our daily workflow. All AI agents — Claude Code, Cursor, Windsurf,
Gemini — need persistent understanding of the Life-OS system when working in
the vault or related repos (e.g. lifeos-agents).
Today, Life-OS knowledge is scattered:
- ADR 0004 documents the Claude Code ↔ vault integration (CLAUDE.md rules, skills, MCP layer)
- Obsidian ADR 0002 documents vault structure conventions and ai-grep
- The upstream Life-OS project publishes
llms.txtandllms-full.txtatlifeos.vipfollowing the llms.txt standard for AI consumption - No single location in this repo provides a canonical, tool-agnostic reference that any agent can be pointed at
The issue ([PHA-14]) asks: where should Life-OS agent documentation live so all AI tools can reference it?
Decision¶
Create a top-level lifeos/ directory at the repo root, parallel to
claude/, cursor/, obsidian/, etc.
Directory structure¶
lifeos/
├── README.md # What this directory is, how agents should use it
├── llms.txt # Cached copy of lifeos.vip/llms.txt
├── llms-full.txt # Cached copy of lifeos.vip/llms-full.txt
└── agent-context.md # Curated agent instructions — vault conventions,
# PARA structure, session workflow, frontmatter
# standards — written for AI consumption
Boundary with obsidian/¶
obsidian/— Obsidian app configuration: plugin settings, MCP setup, vault-level ADRs, patterns for Obsidian-specific operationslifeos/— Life-OS system documentation for agents: what the system is, how it's structured, how to work within it. Tool-agnostic.
How agents consume it¶
Each tool's config can reference lifeos/ files directly:
- Claude Code:
CLAUDE.mdcan include@lifeos/agent-context.mdor instruct Claude to readlifeos/llms-full.txtwhen working in the vault - Cursor:
.cursorrulescan referencelifeos/agent-context.md - Windsurf:
.windsurfrulessimilarly - Gemini: Context instructions can point to the same files
Keeping docs current¶
The llms.txt and llms-full.txt files are cached copies of the upstream
Life-OS documentation. When the upstream publishes updates, refresh them:
curl -sL https://lifeos.vip/llms.txt -o lifeos/llms.txt
curl -sL https://lifeos.vip/llms-full.txt -o lifeos/llms-full.txt
The agent-context.md file is maintained manually and captures our
project-specific conventions layered on top of the upstream docs.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
obsidian/lifeos/ — nest under obsidian directory |
Life-OS docs are cross-cutting, not Obsidian-specific config. Agents working outside the vault context wouldn't intuitively look in obsidian/ for system docs. |
context/lifeos/ — new shared context directory |
Over-engineered for a single system. Introduces a new structural concept not established in the repo. Could revisit if more cross-cutting systems emerge. |
Inline in each tool's directory (e.g. claude/lifeos/, cursor/lifeos/) |
Duplicates content across multiple directories; single source of truth is better. |
| Only reference upstream URLs, no local cache | Upstream site may be slow or unreachable (confirmed during this research — lifeos.vip timed out). Local copies ensure agents always have access. |
Consequences¶
Positive:
- Single, canonical location for Life-OS agent documentation
- Any AI tool can be pointed at
lifeos/agent-context.mdregardless of tool-specific config format - Local cached copies of
llms.txt/llms-full.txtsurvive upstream downtime - Follows the repo's existing pattern of one top-level directory per system
- Clear boundary between Obsidian app config (
obsidian/) and Life-OS system docs (lifeos/)
Negative / Trade-offs:
- Another top-level directory to maintain
- Cached
llms.txtfiles can drift from upstream — requires periodic refresh agent-context.mdis manually maintained and may lag behind vault changes
Ongoing obligations:
- Refresh
llms.txtandllms-full.txtwhen upstream publishes updates - Keep
agent-context.mdcurrent as vault conventions evolve - Update each tool's config to reference
lifeos/files as tools are onboarded
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.