| name | session-start |
| license | MIT |
| description | Session initialization procedure. Checks memory mount, reads all required memory files, validates skeleton version, checks dependency freshness, and surfaces alerts. Must be executed at the start of every session before any other work. |
Session Start Procedure
Execute every step below in order. Do not skip steps. Do not start any user task
until this procedure is complete.
Step 1 — Check memory mount
Step 1b — Link external skills (auto-recover after pull)
External skill packs (e.g. Google's android/skills) install into a shared per-machine store at ~/.agentskel/skills/ and are surfaced to each project via gitignored symlinks under .agents/skills/. After a teammate pulls a sync that introduced new external skill entries — or after a fresh clone — the manifest exists but the symlinks do not yet. Detect and auto-recover before reading anything else.
This step makes external skills available without the teammate having to remember a manual install step. The script is safe to re-run.
Step 2 — Read memory files
Read now (essential — do not skip):
Check only (deferred — loaded by workflows when needed):
Step 3 — Surface alerts
Step 4 — Check skeleton version
Step 5 — Check freshness timestamps (from .memory/CONFIG.md)
Step 6 — Check blueprint (if configured)
6a — Detect blueprint changes
6b — Check blueprint skeleton version
6c — Check Knowledge Bus
Step 7 — Check git state
Step 8 — Confirm ready
Session Reload
Re-execute this entire procedure (Steps 1–8) when any of the following triggers
occur mid-session:
| Trigger | When | Why |
|---|
| Post-sync | Immediately after sync-skeleton completes | Rules, skills, and workflows may have changed. The agent must internalize the updated .agents/ files. |
| Post-setup | Immediately after setup-skeleton completes | Everything was just installed — the agent needs to read it all. |
| Stale session | Before starting any workflow, if Timestamp (UTC) in RESUME.md is >24 hours ago | Long-running sessions lose context over time. A reload ensures the agent is working with fresh memory. |
Full reload: When triggered by post-sync or post-setup, also re-read all files
in .agents/rules/ (rules may have changed). For stale-session triggers, the
standard Steps 1–8 are sufficient.
After reload, update RESUME.md Timestamp (UTC) to the current time.
Common Rationalizations
| Rationalization | Why it's wrong | Do this instead |
|---|
| "I already know this codebase" | Your context was reset. LESSONS.md has mistakes you'll repeat without reading it. | Read ALL files in Step 2. |
| "The user's request is urgent, I'll read memory later" | Memory reading takes 30 seconds. Skipping costs 10 minutes of wrong assumptions. | Read first, act second. |
| "I'll just read the files I need for this task" | CONFIG.md has freshness checks, SACRED.md has constraints you don't know about yet. | Read every file in Step 2 — no exceptions. |
| "Memory pull failed, so I'll skip the memory step" | Stale memory is better than no memory. | Proceed with local files. |
| "The skeleton version check isn't important right now" | Version drift causes silent failures. The check takes 5 seconds. | Always run Step 4. |
| "I read these files last session" | Sessions don't share context. You are a new instance. | Read them again. |
| "The user said 'skip session start'" | Only skeleton sync (Step 4) can be skipped by user request. Steps 1-3 are never optional. | Execute Steps 1-3 always. |
Gate: Do not begin any user task until all steps above are checked off.
