Core Doctor

core-doctor

Diagnose Agentic Life OS repo state, private state, runtime visibility, source-decision config, and integration readiness. The script doctor validates boring files; the LLM doctor interprets what it means and what is safe to do next.

Trigger

Use when the user asks to check, diagnose, verify, repair, or explain a Life OS install.

Principle

Doctor is read-only by default. It may run validators and native status commands, but it must not repair, migrate, register skills, create crons, edit config, or touch runtime-owned systems unless the user explicitly asks.

Inputs to inspect

1. Current repo state and files.
2. Life OS private state directory:

• $HOME/.life-os by default
• LIFEOS_DATA_DIR if explicitly set

1. Runtime adapter for the active runtime:

• ../../runtimes/hermes.md
• ../../runtimes/openclaw.md

1. Runtime-native health and visibility commands.
2. Relevant subskills if the reported issue names one.

Base private-state check

From the repo root:

python3 scripts/lifeos.py doctor

The helper checks:

• skills/life-os/skill-index.yaml exists and references real subskills
• every indexed subskill has SKILL.md
• every indexed subskill has schemas/data.schema.json
• JSON schemas parse
• private data dir exists, if installed
• installed.json, runtime.json, and config.json exist, if installed
• per-subskill private data files exist, if installed
• semantic_health: whether required source, schedule, delivery, routine, review-cron, and record-keeping decisions have been asked and saved

If semantic_health.complete is false, the install is mechanically present but semantically incomplete. Missing semantic answers are discovery tasks, not blind user-preference questions. Before asking the user to decide, inspect the active runtime with native tools and report what already exists.

Correct flow for each missing decision:

1. Run python3 scripts/lifeos.py next-question to identify the missing key.
2. Inspect the matching runtime-owned state first, for example cron list/status/output history, delivery routes, task source, memory policy, or existing review routines.
3. Tell the user what already exists and the safe default recommendation: reuse, ignore, or propose a change.
4. Only then ask for approval if the answer would create, change, disable, migrate, or globally register anything.
5. Save the decided pointer/policy with python3 scripts/lifeos.py answer '' --kind and run doctor again.

Do not ask “should X exist?” when runtime evidence can answer “X already exists, here is what it does.” That is lazy setup theatre.

When the helper returns setup_completion.status: incomplete, surface it to the user as the next action. Do not bury the pending checklist in diagnostic JSON, and do not continue explaining Life OS features without offering to complete setup.

Use setup_completion.agent_next_message as the default wording seed for the visible reply when it is present. Adapt it to the active conversation, but preserve the contract: the agent operates the helper and runtime checks, then asks for one clear decision. Do not ask the user to run helper commands or paste JSON back into the chat. The user-facing output is the decision, not the plumbing.

Use next_setup_decision when present as the machine-readable setup cursor. It may include recommended_answer, human_options, requires_runtime_discovery, and inspect_before_asking so agents can inspect the right runtime-owned state and ask one clear question without parsing prose from question or the checklist. Use setup_progress for current_step, completed_steps, and blocked_on; do not infer progress from checklist order when that structure is present. These fields are agent-facing structure, not final UX; translate them into the current conversation style.

Hermes doctor checklist

Load ../../runtimes/hermes.md, then use native Hermes commands as available:

hermes skills list --source all
hermes skills list --enabled-only | grep -E '(^|[[:space:]])life-os([[:space:]]|$)'
hermes skills config
hermes cron list --all
hermes cron status
hermes memory status
hermes tools list
hermes profile list
hermes gateway status
hermes status --all
hermes config check
python3 scripts/lifeos.py doctor

Interpretation:

• Missing life-os in hermes skills list is a runtime registration/visibility issue, not a private-state failure.
• Doctor warnings about missing private files usually mean install has not run for this data dir.
• Hermes profile selection matters. A skill visible in one profile may be missing in another.
• Cron, memory, tools, provider config, gateway status, and delivery are Hermes-owned. Report them as runtime systems, not Life OS files.
• For missing routine decisions such as quiet_heartbeat, review_cadence, review_cron_install_policy, system_improvement_review, delivery_policy, or cron_record_source, inspect hermes cron list --all / scheduler output and existing delivery targets before asking for a decision.
• If review_cron_install_policy is pending, the install is not complete until the user approves creating/reusing review meeting crons or explicitly chooses manual-only/disabled reviews.
• If the user wants a fix, propose a specific action and ask before changing profile config, skill registration, cron jobs, delivery routes, or memory.

OpenClaw doctor checklist

Load ../../runtimes/openclaw.md, then use native OpenClaw commands as available:

openclaw skills list
openclaw skills info life-os
openclaw skills check
openclaw agents list --bindings
openclaw status --all
openclaw doctor
openclaw config file
openclaw config validate
openclaw cron list
openclaw tasks list
openclaw memory status
python3 scripts/lifeos.py doctor

For a named OpenClaw agent:

openclaw skills list --agent 
openclaw skills info life-os --agent 
openclaw skills check --agent 
openclaw memory status --agent 

Interpretation:

• Missing life-os in openclaw skills list is a workspace/agent/shared visibility issue, not a private-state failure.
• openclaw tasks is a background work ledger, not necessarily the user's task list.
• openclaw cron owns schedules and run history.
• openclaw agents list --bindings explains agent/workspace/channel routing boundaries.
• openclaw doctor --repair and config edits can mutate runtime state. Do not run repair modes unless the user asks.

Diagnosis categories

Classify every finding as one of these:

• repo: public repo files, skill index, schemas, docs, CI metadata
• private-state: $LIFEOS_DATA_DIR install/config/data files, including sources, internal_state, and caches
• source-decisions: where each domain lives and how future runs should access it
• runtime-visibility: runtime can or cannot see life-os or subskills
• runtime-owned: cron, tasks ledger, memory, delivery, tools, config, profiles, agents, workspaces, plugins
• approval-needed: any proposed change with side effects
• unknown: missing facts that require runtime docs, command output, or user choice

Output contract

Doctor:
- Repo: 
- Private state: 
- Runtime: 
- Skill visibility: 
- Skill-owned source state: 
- Semantic setup: 
- Runtime-owned systems: 
- Issues: 
- Safe next action: 
- Needs approval: 

Keep it compact. Do not paste raw command dumps unless the user asks.

Repair policy

Safe without asking:

• read repo files
• run read-only validators/status commands
• run python3 scripts/lifeos.py doctor
• run python3 scripts/lifeos.py install only when the user explicitly asked to install or state files are clearly the requested target

Ask before:

• symlink/copy skill registration
• runtime config edits
• cron/job creation, deletion, or schedule changes
• memory/vault/provider changes
• delivery route changes
• OpenClaw doctor --repair / Hermes repair-like commands
• migrations/imports/bridges
• deleting or rewriting private state

Data

Private state belongs in:

$LIFEOS_DATA_DIR/core-doctor/data.json

Do not commit personal data, credentials, private runtime config, raw logs, transcripts, screenshots, audio, or real delivery targets.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: djangonavarro220
• Source: djangonavarro220/agentic-life-os
• License: MIT

Install and usage instructions live in the source repository linked above.