AGENTS.md — Rules of engagement for AI sessions

Read this first. It tells any AI agent — Claude, ChatGPT, Cursor, Copilot, Gemini, or anything else — how this LifeOS vault is organized and how to work inside it. This is a reusable pattern, not one person's story. Identity and settings live in dashboard/lifeos.config.json (falling back to dashboard/lifeos.config.example.json); the words below use {{owner}} wherever your name would go. Anywhere you see <!-- lifeos:fill -->, replace it with something true for you and delete the marker.

Onboarding — read this if a person just opened this repo

Everything shipped here is demo data. The name Alex Rivera, the town of Portland, the app "Fieldnotes," the pottery hobby, the "Operation Launch Week" mission, the sample tasks and habits — all placeholder. It exists so a fresh clone renders fully before anyone personalizes it. Every seed data file announces this: JSON files carry a top-level "_DEMO" key, and the marker files say <!-- lifeos:fill -->. See DEMO_DATA.md for the full convention.

Your job, the first time someone opens this repo with you, is to replace that persona with the real one. Concretely:

1. Recognize the placeholders. If you see Alex Rivera / Portland / Fieldnotes / pottery, or a "_DEMO" key, treat it as a fill-me-in template — never as the user's real life.
2. Get their material. Ask them about themselves, or take whatever they hand you: a paragraph, a brain-dump, an old journal, an exported Obsidian vault, a Notion export, a folder of loose files, a task list. Whatever form it's in is fine — the mapping is your job, not theirs. Don't make them reformat anything.
3. Map it onto the schemas. The files in schemas/ are the contract. Read the relevant schema, then write conforming data:
   • identity, area codes, currency, enabled modules → dashboard/lifeos.config.json (copy dashboard/lifeos.config.example.json, replace the demo values). Define the area codes from their life, not the demo's — their real domains (work, a relationship, a side project, caregiving, study, faith — whatever they actually spend life on), and switch off modules they won't use. It holds identity + toggles, never secrets — but it is still personal data: commit it only in the owner's private instance (a private clone or a private repo made from this template), where committing it inside dashboard/ is exactly what personalizes a static deploy. Never write real identity into a public fork of the template.
   • the one thing they're driving toward → dashboard/mission.json (mission.schema.json)
   • their tasks → dashboard/tasks-data.json (tasks.schema.json); recurring things → dashboard/habits-data.json (habits.schema.json). These two files are what the dashboard hydrates from on first run, so writing them is how the user sees tasks/habits without touching the UI. (A vault mirror at 06_Trackers/tasks.md / habits.md is an optional long-form layer.)
   • facts about them (strengths, values, watch-outs, preferences, one per life area) → dashboard/kb-data.json (kb.schema.json) — the surface the Knowledge Base page renders. Keep 02_Areas/knowledge_base/*.md as an optional long-form layer; the page reads the JSON, not the markdown.
   • money → dashboard/finance-data.json (finance.schema.json)
4. Snapshot before you overwrite. Move demo content into archive/ rather than deleting it, and confirm before replacing a file the user might have touched.
5. Stop when it renders as them. Open dashboard/index.html — their name, areas, and mission should appear. Don't gold-plate the first session; get them a working vault, then iterate.

The schemas are what make this reliable across any assistant: infer the fields the schema asks for (area codes from their config, priority as P1/P2/P3, status, due dates from natural language) and emit valid JSON. Messy input in, structured data out. If you're Claude Code, the /setup skill walks this exact path; any other assistant does it by reading this section and the schemas directly.

Who this is for

North Star: <!-- lifeos:fill --> one sentence naming the life {{owner}} is building — the thing every mission ultimately serves.

The agent should treat this section as the standing context for every session. When it goes stale, update it; don't work around it.

The operating principle

LifeOS offers Think once → Build → Measure → Improve as one possible working method. The owner decides whether it helps.

The default method encourages a small, reviewable artifact when that serves the owner's goal. Rest, exploration, maintenance and a well-considered decision can also be valid outcomes. The owner chooses the pace and can change this method.

Optional focus support. If the owner asks for help narrowing the work, suggest one manageable next step. Do not infer their emotional state from planning, label them as spiraling, or push productivity when they ask for rest or reflection.

One hero mission at a time

The dashboard has one hero mission slot. It is a focus aid, not a rule about how the owner must live; they decide what else needs attention.

• The hero renders entirely from dashboard/mission.json (see the lifecycle below). Nothing else hardcodes it.
• Offer a parking lot for unrelated work when the owner wants help narrowing focus. Never postpone a requested commitment or basic need solely because it falls outside the mission.
• When the owner asks for help keeping a narrow focus, offer to park unrelated work. They decide what to pursue.

File map

The vault is plain Markdown + JSON so it stays portable, greppable, and yours. Folders are numbered so they sort in order.

• 00_START_HERE.md — the daily home base / index. Where a session starts.
• 01_Focus/ — the current mission's working files: study/prep notes, plans, checklists, scripts specific to the hero mission.
• 02_Areas/ — the standing life areas (one file per area code from lifeos.config.json), plus 02_Areas/knowledge_base/ — the searchable "about you" notes that power the knowledge base.
• 03_Projects/ — ongoing ventures and projects, each with its own notes and (optionally) subagent roles.
• 04_AI_Workflow/ — how AI runs this vault: the orchestrator/subagent pattern, the master prompt, the model-orchestration map.
• 05_Checklists/ — reusable checklists (topic-wise and situational).
• 06_Trackers/ — the live state layer. The repo ships blank *.template.md files here (tasks.template.md, habits.template.md, reminders.template.md, inbox.template.md, evidence.template.md, finance.template.md); your live tasks.md, habits.md, etc. are created from them on first setup. This is the shared memory that skills and subagents read and write. (What the dashboard renders lives as JSON in dashboard/ — tasks-data.json, habits-data.json, kb-data.json, finance-data.json — per the schemas.)
• templates/ — blank templates (daily journal, weekly review, project story, decision log).
• dashboard/ — the interactive dashboard (index.html) whose hero renders from mission.json.
• api/ — serverless sync functions (e.g. optional two-way Notion sync).
• schemas/ — the JSON Schemas that define the data contracts (config, mission, tasks, habits, finance, knowledge base). When in doubt about a shape, read the schema.
• reviews/ — filed weekly reviews (YYYY-Www.md) — the memory for the "Measure" step.
• examples/alex/ — a fully worked demo instance (the "Alex Rivera" persona) so a fresh clone renders and reads end-to-end before you personalize it.
• archive/ — closed hero missions and retired mission.json snapshots.

Data contracts

Live state has schemas in schemas/. Skills and sync code should honor them:

• lifeos.config.schema.json — identity, area codes, enabled modules. Read dashboard/lifeos.config.json for the current instance (falling back to dashboard/lifeos.config.example.json).
• mission.schema.json — the hero mission (dashboard/mission.json).
• tasks.schema.json, habits.schema.json, finance.schema.json, kb.schema.json — trackers and knowledge base.

Area codes are defined once in dashboard/lifeos.config.json. Every task/note tags one of those codes — don't invent new area strings ad hoc.

Mission lifecycle — how to swap the hero

The dashboard hero (header, countdown, one-thing, week planner, evidence) renders entirely from dashboard/mission.json. Swapping the hero is a small, mechanical edit — not a rewrite. The mission-swap skill automates it; the steps are:

1. Snapshot the old mission. Copy the current dashboard/mission.json to archive/mission_<old-slug>.json. Move any mission-specific working folder under archive/<old-slug>/.
2. Write the new mission.json. New slug, new hero block (kicker, title, subtitle, gate date, gateLabel, oneThing, rule), new week rows, new evidence items. Validate against schemas/mission.schema.json.
3. Preserve checks with a fresh namespace. The slug namespaces week/evidence keys, so a fresh slug starts unticked without removing the previous mission's saved checks. Keep those keys and browser backups; do not clear storage to swap missions.
4. Update the pointers. Refresh the hero line in 00_START_HERE.md and the "current state" note in this file so the written context matches the dashboard.

That's the whole swap — a ~10-minute edit.

Rules of engagement

1. Follow the owner's priorities. The hero is a focus aid. Offer to sequence or park work when asked; the owner decides what needs attention.
2. Match the requested outcome. Build when implementation is requested. Planning, reflection and rest are also valid; repeated planning alone is not evidence that the owner needs intervention.
3. Keep tone direct and calm. Offer structure when useful and follow the owner's stated needs.
4. Preserve {{owner}}'s entries. When updating trackers, append — don't overwrite.
5. Log evidence, not ideas. Every session that ships something adds a line to 06_Trackers/evidence.md.
6. Privacy first. A personal LifeOS holds sensitive detail (finances, relationships, IDs). The public repo is the clean template; the owner's instance lives in a private repo, and personal config + data JSON are committed only there. Any hosted personal dashboard should sit behind access protection or be treated as public. For anything public, extract a sanitized showcase instead of publishing the vault. <!-- lifeos:fill --> add any owner-specific privacy rules.
7. Self-describing on purpose. Any session can get oriented from CLAUDE.md → AGENTS.md → 00_START_HERE.md → 06_Trackers/. Keep that chain accurate.

Verification — prove a change works before you call it done

Give yourself a check you can run; without one, the human becomes your test loop.

The command: npm test. It chains three checks and CI runs exactly this on every push and PR (.github/workflows/ci.yml):

bash scripts/pii-scan.sh . runs as its own CI job (.github/workflows/pii-scan.yml) — run it before pushing; this is a public template and secrets must never land in it.

The dashboard has no build step: for a UI change, open dashboard/index.html (or python3 -m http.server) and look at it. Nothing compiles; there is no dev server to wait on.

Dashboard edits live in browser storage and do not write back to the JSON seed files. Before an assistant changes an existing instance's task/habit files, reconcile a private browser export with them. Never clear browser storage to force a seed refresh. See docs/browser-data.md for backup, restore and sync boundaries.

Build-level work for this template is queued in TODOS.md; when a session dies mid-task, its trace and the friction log live in worksheets/ so the next one can finish it. This is a lightweight, harness-agnostic version of the agentic working pattern — adopt as much of it as your own workflow wants.

Sync

• This Git repo owns versioned source files and initial JSON seeds. Dashboard edits live in browser storage; optional task/habit sync exchanges records with Notion and does not update Git. Reconcile an export before changing seed files. Hosting and connector setup are optional (see 04_AI_Workflow/ and api/).
• The repo doubles as an Obsidian vault: relative Markdown links (not wikilinks), YAML frontmatter on content files (title/area/type/tags/updated). When you add a note, give it frontmatter so it joins the computed layer.