On your first response in any fresh session (new session, after /clear,
or after /compact — not on plain resume), you MUST do the three checks
below using real tool calls, before responding to the human. Do not
guess outcomes from context. Run the tools.
Call Read on .claude/.onboarded at the workspace root.
- If the file exists → onboarding is complete. Skip to step 2.
- If
Readreturns "file not found" → the ritual hasn't finished yet. Silently invoke the/onboardskill. It is idempotent: it inspects workspace state (IDENTITY.md, USER.md,.claude/.capability-offered) and runs only the stages that are missing. Let the skill drive the conversation from here — don't improvise your own onboarding.
Do not skip this check because "the workspace looks configured" or "it probably ran before." The flag file is the only reliable signal.
Call Read on memory/YYYY-MM-DD.md where YYYY-MM-DD is today's date.
- If it exists → read it; it may contain context from earlier conversations today that affects how you respond.
- If it doesn't exist → skip; you'll create one later when something's worth journaling.
If .claude/loops/ exists in this workspace, you MUST invoke /loops sync.
Not "read the instructions and move on." Not "make a mental note." Call
the skill. This is a tool call you must actually make.
That skill reconciles the loop registry (files in .claude/loops/*.md)
with the currently-registered crons. It is how the keepalive loop first
gets registered on a brand-new install, and how every other loop gets
re-registered after a session restart. If you skip it, scheduled
automations go silent until the next fresh session — which might be
days away.
sync is idempotent and silent by default — no user-facing output
unless something failed. It's cheap; calling it every session costs
one tool call. The cost of skipping it is broken automation the human
won't notice until something they expected didn't fire.
If .claude/loops/ doesn't exist at all, this workspace isn't using
the loops system; move on.
Once all three checks have run, proceed with the human's message. You
don't need to announce that you did the checks — just behave consistently
with what you found. If /onboard fired, the skill is driving the first
turn; follow its instructions. If the onboarded flag was present, respond
as your already-established persona.
Common failure mode to avoid: scanning the loaded persona files
(IDENTITY.md blank, USER.md blank, etc.), concluding "this is a fresh
workspace" on that evidence alone, and inventing your own onboarding. The
blank templates are a hint, but .claude/.onboarded is the authoritative
signal. Always confirm with Read.
The imports below load at every session start (and after /compact). They
describe your persona, your human, how you operate, and the governance
layer you consult when routing tasks. All of them are editable by either
the human or you. When you edit one, tell the human what and why.
@./IDENTITY.md @./SOUL.md @./USER.md @./TOOLS.md
@./AGENTS.md
@./.claude/RESOLVER.md @./.claude/_output-rules.md
@./MEMORY.md
@./HEARTBEAT.md
Not auto-loaded. Go read them when the task calls for it.
BOOTSTRAP.md— human-readable documentation of the first-run ritual. The ritual itself is implemented as the/onboardskill; this file explains what the skill does for someone reading the repo. Not used by the agent directly.memory/YYYY-MM-DD.md— today's daily journal. Read at session start; write to it when there's something worth remembering..claude/loops/*.md— scheduled-loops registry. Each file is one loop. Managed via/loops; don't edit directly unless you're the/loopsskill..claude/skills/<name>/SKILL.md— skill implementations. Read when invoking a skill or debugging one..claude/launchd/— plist + wrapper scripts, only present if/install-launchagenthas been run..gitignore— keeps.DS_Store,.claude/settings.local.json, and runtime logs out of version control.