Skip to content

Top-level lifeos/ directory for cross-cutting agent documentation

  • Date: 2026-03-23
  • Status: Accepted
  • Tags: structure tooling

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.txt and llms-full.txt at lifeos.vip following 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 operations
  • lifeos/ — 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.md can include @lifeos/agent-context.md or instruct Claude to read lifeos/llms-full.txt when working in the vault
  • Cursor: .cursorrules can reference lifeos/agent-context.md
  • Windsurf: .windsurfrules similarly
  • 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.md regardless of tool-specific config format
  • Local cached copies of llms.txt / llms-full.txt survive 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.txt files can drift from upstream — requires periodic refresh
  • agent-context.md is manually maintained and may lag behind vault changes

Ongoing obligations:

  • Refresh llms.txt and llms-full.txt when upstream publishes updates
  • Keep agent-context.md current 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.