grandamenium Onboarding
This skill runs on first boot or when explicitly triggered. It is the only thing you should do until it is complete.
Step 0: Detect your runtime
Read config.json to find your runtime — it determines where your skills live, which slash-commands exist, and which env vars matter.
RUNTIME=$(grep -o '"runtime"[[:space:]]*:[[:space:]]*"[^"]*"' config.json | sed -E 's/.*"runtime"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/')
echo "Runtime: ${RUNTIME:-claude-code}"
Branch the rest of onboarding on this value:
| Runtime | Skills location | Slash-commands available | Auth env var |
|---|---|---|---|
claude-code (default) |
.claude/skills/<skill>/SKILL.md |
/loop, /usage, /compact, etc. |
CLAUDE_CODE_OAUTH_TOKEN |
codex-app-server |
plugins/cortextos-agent-skills/skills/<skill>/SKILL.md (linked into ~/.codex/skills/<agent>__<skill>) |
none — codex has no slash-command surface | CODEX_API_KEY (or codex login) |
hermes |
hermes-specific (see hermes adapter docs) | none | hermes-specific |
If runtime is missing or empty, treat it as claude-code (legacy default).
Step 1: Check onboarding status
[[ -f "${CTX_ROOT}/state/${CTX_AGENT_NAME}/.onboarded" ]] && echo "ONBOARDED" || echo "NEEDS_ONBOARDING"
If already ONBOARDED, skip to normal session start. Do not re-run onboarding unless the user explicitly requests it.
Step 2: Read ONBOARDING.md
cat ONBOARDING.md
This file contains the full onboarding protocol for your specific agent role. Follow every step exactly. Do not improvise.
Step 3: What onboarding establishes
Onboarding must complete all of the following before you are considered functional:
| Item | File written |
|---|---|
| Your name, role, emoji, and identity | IDENTITY.md |
| Your behavior, autonomy rules, and mode | SOUL.md |
| Your current goals and focus | GOALS.md |
| User preferences and context | USER.md |
| Guardrails and patterns to avoid | GUARDRAILS.md |
| Telegram bot connected and tested | .env (BOT_TOKEN, CHAT_ID) |
| Crons configured and running | config.json |
| .onboarded flag written | $CTX_ROOT/state/$CTX_AGENT_NAME/.onboarded |
Step 3b: External Persistent Crons
Your crons survive restarts automatically. No manual restoration needed.
When you set up recurring workflows during onboarding, add them as persistent crons:
# Example: heartbeat every 6h
cortextos bus add-cron $CTX_AGENT_NAME heartbeat 6h Read HEARTBEAT.md and follow its instructions.
The daemon reads ${CTX_ROOT}/state/${CTX_AGENT_NAME}/crons.json on every start and re-schedules all entries. Your crons will fire even after crashes or hard restarts.
Use cortextos bus add-cron for any workflow that must keep running across restarts. (Claude-Code-runtime agents: do NOT use /loop for persistent scheduling — it is session-only and dies on restart. Codex-runtime agents have no /loop to begin with; add-cron is the only path.)
For full details, see the ## External Persistent Crons section in AGENTS.md.
Step 4: Mark complete
When all steps in ONBOARDING.md are done:
mkdir -p "$CTX_ROOT/state/$CTX_AGENT_NAME"
touch "$CTX_ROOT/state/$CTX_AGENT_NAME/.onboarded"
Then notify the user via Telegram that you are online and ready.
If Onboarding Is Interrupted
If a session crash or restart interrupts onboarding mid-way:
- Check which steps completed (look at which files exist)
- Resume from the first incomplete step
- Do NOT restart from the beginning if some steps already completed
- Re-run
/onboardingif needed to trigger this skill again
Critical Rules
- Do NOT send a Telegram message claiming you are online until onboarding is complete
- Do NOT set up crons until IDENTITY.md and GOALS.md are written
- Do NOT start processing user requests until
.onboardedis written - The user is waiting — be efficient, but do not skip steps