Session Init & Lifecycle Skill

Single entry point for project initialization and soul purpose lifecycle management. Two modes, auto-detected. User runs /start — that is all.

Overview

This skill has two operational modes:

1. Init Mode — Triggered when session-context/ does NOT exist. First-run bootstrap: captures soul purpose, organizes files, generates CLAUDE.md, integrates Claude /init, onboards Ralph Loop.
2. Reconcile Mode — Triggered when session-context/ DOES exist. Lifecycle management: refreshes CLAUDE.md via Claude /init, assesses soul purpose status, optionally verifies with doubt agent, harvests active context on closure.

Mode is auto-detected from directory state. No flags, no arguments. User just runs /start.

Hard Invariants

These hold at all times, in both modes:

1. User authority is absolute — AI NEVER closes a soul purpose. Only suggests; user decides.
2. Zero unsolicited behavior — Skill ONLY runs when user types /start. No hooks, no proactive triggers.
3. Human-visible memory only — All state lives in files. Nothing hidden in chat memory.
4. Idempotent — Safe to run multiple times. Re-running does not corrupt state.
5. Templates are immutable — NEVER edit files in ~/claude-session-init-templates/. Copy only.
6. Reconcile mode is audit, not rewrite — Targeted changes only. Do not regenerate what already exists.

Rules

• Act as pure bootstrap + organizer in Init Mode, pure auditor in Reconcile Mode
• All persistent state lives in files, not chat memory
• If session-context/ files exist, do NOT overwrite unless explicitly instructed
• If project is already organized (few files at root), skip file organization steps
• NEVER edit template files in ~/claude-session-init-templates/ — they are immutable
• Confirm nothing except the organization map (Init Step 5) and harvest promotions (Reconcile Step 5). Execute deterministically otherwise.
• NEVER auto-invoke doubt agent. Only suggest it. User accepts or skips.
• NEVER auto-close a soul purpose. Present options; user chooses.
• All heavy file operations MUST be delegated to Task agents (see Agent-Driven Execution below)

Mode Detection

if session-context/ does NOT exist:
    → Init Mode
else:
    → Reconcile Mode

Run this check silently at the start:

[ -d session-context ] && echo "MODE=reconcile" || echo "MODE=init"

No flags, no arguments. The directory state is the only signal.

Session Context Validation

If Reconcile Mode was detected, validate session-context/ integrity before proceeding:

# Count expected files in session-context/
for f in CLAUDE-activeContext.md CLAUDE-decisions.md CLAUDE-patterns.md CLAUDE-soul-purpose.md CLAUDE-troubleshooting.md; do
  [ -f "session-context/$f" ] && [ -s "session-context/$f" ] && echo "OK: $f" || echo "MISSING: $f"
done

If any files are MISSING or zero-length:

1. Check if ~/claude-session-init-templates/ exists
2. Copy missing files from templates (do NOT overwrite existing files)
3. Report to user: "Repaired X missing session-context files from templates."

This ensures Reconcile Mode always has valid files to work with, even if a previous Init was interrupted.

Agent-Driven Execution (MANDATORY)

All skill operations MUST be delegated to Task agents. The main conversation thread acts as a thin orchestrator only.

Why

Reading and writing large files (session-context files, CLAUDE.md, source code) directly in the main conversation causes context death spirals — compact, re-read files to restore context, fills context, compact, repeat forever. Task agents have their own context windows and do not pollute the main thread.

Rules

1. NEVER read files >150 lines directly in the main skill flow
2. Delegate ALL file reading, analysis, and editing to Task agents
3. Main conversation holds the plan, dispatches agents, tracks progress
4. Each agent gets: specific instructions, file paths, clear edit requirements
5. Agents return: short summary of what changed (file, what was done)
6. Parallel agents where dependencies allow — e.g. populating active context and generating CLAUDE.md can run simultaneously

Agent Dispatch Pattern — Init Mode

• Wave 1: Bootstrap session-context (single agent — sequential file copies)
• Wave 2 (parallel): Populate active context + Generate CLAUDE.md
• Wave 3: Run Claude /init (must wait for CLAUDE.md to exist)
• Wave 4: Ralph Loop onboarding (interactive, main thread)

Agent Dispatch Pattern — Reconcile Mode

• Wave 1: Run Claude /init
• Wave 2: Read soul purpose + active context (single agent)
• Wave 3: Self-assessment (main thread — lightweight reasoning only)
• Wave 4 (if needed): Doubt agent verification
• Wave 5 (if closing): Harvest agent (reads active context, proposes promotions)

Marking Delegated Steps

Steps marked [DELEGATE TO AGENT] below MUST be executed via Task agents. Steps marked [MAIN THREAD] run directly in the orchestrator conversation.

Templates

Source: ~/claude-session-init-templates/

These are IMMUTABLE template files. Copy them, never edit them:

• CLAUDE-activeContext.md — Session state tracker
• CLAUDE-decisions.md — Architecture decision log
• CLAUDE-patterns.md — Code patterns and conventions
• CLAUDE-soul-purpose.md — Soul purpose placeholder
• CLAUDE-troubleshooting.md — Issue resolution guide
• CLAUDE-mdReference.md — CLAUDE.md template (rename to CLAUDE.md on copy)

INIT MODE — Execution

Triggered when session-context/ does NOT exist.

INIT STEP 1 — SOUL PURPOSE [MAIN THREAD]

Use the AskUserQuestion tool to ask:

question: "What is the soul purpose of this project?"
header: "Purpose"
options: []
multiSelect: false

Store the response verbatim as SOUL_PURPOSE.

INIT STEP 2 — DETECT ENVIRONMENT [MAIN THREAD]

Run these checks silently (do NOT report to user):

# Is this a git repo?
git rev-parse --git-dir 2>/dev/null && echo "GIT=true" || echo "GIT=false"

# Does session-context/ already exist?
[ -d session-context ] && echo "SESSION_CTX=exists" || echo "SESSION_CTX=missing"

# Does CLAUDE.md already exist?
[ -f CLAUDE.md ] && echo "CLAUDE_MD=exists" || echo "CLAUDE_MD=missing"

# Count root-level files (excluding directories, hidden files, CLAUDE.md)
ls -1p | grep -v / | grep -v "^CLAUDE" | wc -l

Set internal flags:

• IS_GIT: true/false (determines git mv vs mv)
• HAS_SESSION_CTX: true/false (skip bootstrap if exists)
• HAS_CLAUDE_MD: true/false (generate vs update)
• ROOT_FILE_COUNT: number (skip organization if <= 10)

INIT STEP 3 — BOOTSTRAP SESSION CONTEXT [DELEGATE TO AGENT]

Pre-flight: Validate template directory

# Verify templates exist before copying
ls ~/claude-session-init-templates/CLAUDE-activeContext.md \
   ~/claude-session-init-templates/CLAUDE-decisions.md \
   ~/claude-session-init-templates/CLAUDE-patterns.md \
   ~/claude-session-init-templates/CLAUDE-soul-purpose.md \
   ~/claude-session-init-templates/CLAUDE-troubleshooting.md \
   ~/claude-session-init-templates/CLAUDE-mdReference.md 2>/dev/null | wc -l

If count is not 6, STOP and tell the user:

"Template directory ~/claude-session-init-templates/ is missing or incomplete. Expected 6 template files. Please ensure templates are installed before running /start."

Do NOT proceed with bootstrap if templates are missing.

Dispatch a Task agent with these instructions:

Agent task: Create session-context/ directory and populate with templates.

If session-context/ does NOT exist:

mkdir -p session-context

Copy templates into session-context/:

cp ~/claude-session-init-templates/CLAUDE-activeContext.md session-context/
cp ~/claude-session-init-templates/CLAUDE-decisions.md session-context/
cp ~/claude-session-init-te