session-start

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

• Check whether .memory/ exists in the repo root.
• Exists → pull the latest memory from remote before reading anything:

  git -C .memory pull --ff-only origin ai-memory 2>/dev/null || true
  

  If the pull fails (e.g. network unavailable, diverged history), warn the user but proceed — stale memory is better than no memory. Then continue to Step 2.
• Does NOT exist → STOP. Do not start any task. Instead:
  1. Run git branch -r | grep origin/ai-memory
  2. Found → tell the user:

     "This project has AI memory but it's not mounted. Run ./scripts/install-agent.sh (or git worktree add .memory ai-memory) to load it, then restart this session."

  3. Not found → tell the user:

     "This project has no AI memory. A tech lead needs to run the setup-skeleton workflow first. See the agentskel README for setup instructions."

  4. End session. Do not attempt any work without memory files.

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.

• Check whether .agents/skills/.gitignore exists.
• Does not exist → no external skills configured for this project. Skip to Step 2.
• Exists → read the manifest (non-comment, non-blank lines are external skill directory names). For each entry, check whether .agents/skills/[name] exists as a symlink.
  • If every entry resolves to an existing symlink → skip to Step 2.
  • If any entry is missing → run bash scripts/install-agent.sh once. The script is idempotent: it re-pulls .memory/, then for each manifest entry tries to create a symlink pointing into ~/.agentskel/skills/. Surface any "shared store missing pack" warnings the script prints to the user, and offer to run the update-external-skills workflow now if a pack needs installing.

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):

• .memory/CONFIG.md — repo identity, operational config, check dates
• .memory/RULES.md — project-specific context and rules
• .memory/MAP.md — module and architecture map (read fully, including Critical Business Logic Flows)
• .memory/SYMBOLS.md — symbol index (module list in split mode, full symbols in single-file mode)
• .memory/RESUME.md — read up to the --- marker (Status, Last Completed Task, Next Task, Context Notes, Timestamp). Skip Cartography State and Previously Completed sections below the marker.
• .memory/LESSONS.md — past mistakes to avoid
• .memory/SACRED.md — behaviors that must never be changed
• .memory/DEPENDENCY_ALERTS.md — open major/security alerts

Check only (deferred — loaded by workflows when needed):

• .memory/NEEDS_REVIEW.md — check line count (wc -l). If > 15 lines (has entries), state the count: "N items pending triage in NEEDS_REVIEW.md." Do not read the full content.
• .memory/BACKLOG.md — check line count (wc -l). If > 15 lines (has entries), state: "N lines in BACKLOG.md — items pending. Review before starting work." Do not read the full content.
• .memory/VERSIONS.md — do not read at session start. Loaded by check-dependencies, develop-feature, and fix-tech-debt when needed. Session-start only checks the Last Dependency Check timestamp in CONFIG.md (Step 5).

Step 3 — Surface alerts

• If DEPENDENCY_ALERTS.md has any OPEN entries, surface them to the user before starting any work.
• If NEEDS_REVIEW.md has entries (detected by line count in Step 2), tell the user: "N items pending triage in NEEDS_REVIEW.md — classify as SACRED or TECH_DEBT."
• Autonomy mode banners. Read .memory/CONFIG.md. For each mode that is on, surface a one-line banner so the user is reminded the mode is active (they can toggle it off before starting work if they've changed their mind): - Direct-Commit Mode | on → Direct-Commit Mode is ON. Commits go directly to [Default Branch] (no PR) for trivial work. - Autopilot Mode | on → Autopilot Mode is ON. Agent will proceed within the approved plan without per-step approvals. Significant changes, destructive ops, and out-of-scope work still pause. Both banners must appear if both modes are on. Skip silently if both are off. See docs/AUTONOMY-MODES.md for full mode definitions.

Step 4 — Check skeleton version

• Read VERSION from the skeleton repo (resolve location via Skeleton Path in CONFIG.md → $CLAUDE_PLUGIN_ROOT → ../agentskel → GitHub fetch fallback).
• Compare with Skeleton Version in .memory/CONFIG.md.
• If they differ → run sync-skeleton before any other task (unless the user explicitly says to skip the sync this session).

Step 5 — Check freshness timestamps (from .memory/CONFIG.md)

• Last Skeleton Check — if >30 days ago or absent, run check-skeleton.
• Last Dependency Check — if >14 days ago or absent, run check-dependencies.
• Last Conventions Check — if >90 days ago or absent, remind the user and suggest running update-conventions. Do not auto-run it.
• Last Blueprint Sync — if Blueprint Path is set and Last Blueprint Sync is >7 days ago or absent, warn the user: > "Blueprint hasn't been synced in over 7 days. Other project agents may have > posted Knowledge Bus entries or updated domain specs since then." This is a warning only — do not block. Step 6 will pull the latest.

Step 6 — Check blueprint (if configured)

• Read Blueprint Path from .memory/CONFIG.md.
• Not set → skip this step.
• Set → confirm the path exists on disk. If not, warn the user and continue.

6a — Detect blueprint changes

• Pull latest blueprint changes: bash git -C [BLUEPRINT_PATH] pull --ff-only 2>/dev/null || true
• Read Last Blueprint Sync from .memory/CONFIG.md.
• If set, check for new commits since that date: bash git -C [BLUEPRINT_PATH] log --after="[LAST_BLUEPRINT_SYNC]" --oneline
• If new commits exist, surface a summary to the user: > "Blueprint has been updated since your last session. N new commits — review the changes below before starting work." Show the commit list and any changed spec files (specs/, parity/).
• Update Last Blueprint Sync in .memory/CONFIG.md to the current UTC timestamp.

6b — Check blueprint skeleton version

• Read [BLUEPRINT_PATH]/CONFIG.md — note Skeleton Version.
• Compare with the current skeleton version (already resolved in Step 4).
• If the blueprint's skeleton version is behind: > "Blueprint's skeleton is behind (v[BLUEPRINT_SKEL_VERSION] vs v[CURRENT_SKEL_VERSION]). > Someone needs to run sync-skeleton from the blueprint repo to update it." This is informational — do not block the session. The project agent cannot sync the blueprint's skeleton; that must be done from the blueprint repo directly.

6c — Check Knowledge Bus

• List files in [BLUEPRINT_PATH]/bus/ (excluding BUS_ENTRY_TEMPLATE.md, archive/, and .gitkeep).
• For each bus entry, read the file and check:
  1. Target Platforms — does it list this project's platform?
  2. Action Required — are there unchecked action items for this platform?
• If any bus entries have unchecked actions for this platform, surface them individually with their Change Summary and Action Required sections: > "N unprocessed Knowledge Bus entries targeting [PLATFORM]. These require > action before or during this session." List each entry's filename, origin agent, impact level, and the specific unchecked action item for this platform.
• If there are also bus entries targeting this platform where all actions are already checked, note them as informational only (no action needed).
• If any bus entries (for any platform) are older than 30 days, remind the user to run the janitor workflow to archive them.

Step 7 — Check git state

• Run git branch --show-current and git status.
• If on a non-default branch → read RESUME.md and ask the user whether to continue in-progress work or return to [DEFAULT_BRANCH] for a new task.
• If uncommitted changes exist → surface them to the user before starting any new task. Never stash, discard, or overwrite without explicit instruction.

Step 8 — Confirm ready

• Tell the user: session is ready. Summarise any alerts, version mismatches, stale checks, or pending bus entries found. Ask what they'd like to work on.

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.