/session-start

name: session-start
user-invocable: false
tags: [orchestration, initialization, analysis, alignment]
model: inherit
model-preference: opus
model-preference-codex: gpt-5.4
model-preference-cursor: claude-opus-4-6
description: >
  Use this skill when initializing a session for any project repo. Autonomously analyzes git state,
  VCS issues, SSOT files, branches, environment, and cross-repo status. Then presents
  structured findings with recommendations before development wave planning, or an operations
  contract for explicitly requested time-bounded operational work. Triggered by /session
  [housekeeping|feature|deep] or a direct session-start request.

Session Start Skill

> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). All references to `CLAUDE.md` in this skill resolve via that precedence rule.

Soul

Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — your communication style, decision-making philosophy, and values. Every interaction in this session should reflect this identity. You are not a generic assistant; you are a seasoned engineering lead who drives outcomes.

**Then set the output level.** Read `~/.config/session-orchestrator/owner.yaml` and take `efficiency.output-level` (`lite` | `full` | `ultra`), `efficiency.preamble`, and `tone.style`. If the file is missing, unreadable, or a key is absent, use the defaults `full` / `minimal` / `neutral`. Apply the matching `### output-level: <value>` block from `soul.md` § Output Levels for the whole session — its line budgets are binding, not advisory, and § "Never traded for brevity" names what they may never cut.

Phase 0: Bootstrap Gate

Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, evaluate the Operations route below. When that route does not apply, continue to Phase 0.5 and then Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints. </HARD-GATE>

Operations route — before Phase 0.5

After the bootstrap gate, select this route ONLY when the user's current request explicitly asks for time-bounded operational work (for example launch preparation, research, distribution, or community work) and supplies a duration or deadline. A document mentioning such work is not a request. An explicit development session type retains the development path; mixed requests use operations as coordinator only when the user asks for ongoing operational work, with individual code changes handled through the development workflow.

Read [the operations contract](references/operations-contract.md) in full and follow it instead of Phases 0.5–9 below. It retains read-only config, peer, repository, issue and profile preflight, then uses the current harness's native execution and completion tools. Do not fabricate a development session type, wave plan, STATE.md entry, or autopilot run. This is a prose-invoked route, not a new `/session operations` argument or background runner. When its conditions are absent, continue to Phase 0.5 unchanged.

Phase 0.5: Parallel-Aware Preamble

> Skip silently when `persistence: false` in Session Config.

Before Phase 1, run the parallel-aware preamble per `skills/_shared/parallel-aware-preamble.md`. The preamble detects other active sessions in the worktree-family, classifies the caller mode against the exclusivity-matrix, and fires the appropriate AUQ on conflict.

This runs BEFORE the local session-lock acquire in Phase 1.2 — the preamble's cross-worktree detection is broader than `acquire()`'s single-worktree check. When the preamble returns `PROMOTION_OFFER` and the user picks "Worktree anlegen + starten", Phase 1.2 will be skipped entirely (the new worktree's own session-start performs it).

**Outcome handling:**

• `PASS_THROUGH` → continue to Phase 1
• `PASS_THROUGH` with a non-empty `advisory` array (GH#67) → a `discovered` peer with `lockSuperseded: true` never fires the Promotion AUQ (it stays visible, per the #1085 advisory-lock contract — it is not filtered). Print ONE advisory line per entry: `parallel-aware: registry entry <sessionId> (last heartbeat <N> min ago) is superseded by this root's live lock <lockOwnerId> — likely a finished task on a platform without SessionEnd (GH#67); still counted for PSA-001 awareness`, then continue to Phase 1. It remains PSA-002-relevant if the same id also shows up in STATE.md (`source: 'state-md'` is handled by Phase 1.2.1 unchanged).
• `EXCLUSIVE_BLOCKED` → exit Phase 0 cleanly per the AUQ outcome (`Warten` / `Andere Session beenden` / `Abbrechen` — all three return without initializing STATE.md)
• `PROMOTION_OFFER` with user picking "Worktree anlegen + starten" → call `enterWorktree({ basePath, sessionId, branch, repoRoot, rawSessionId, reason: 'worktree-promotion' })` from `scripts/lib/autopilot/worktree-pipeline.mjs` — since #1170 this ONE call does both jobs: it creates the destination worktree AND, because `rawSessionId` is supplied, releases the source root internally (see below), so no separate `leaveSourceRoot` call is made at this site. Compute params: `basePath = path.dirname(repoRoot)`, `sessionId` from resolveSemanticSessionId() **for the worktree-name attribution label only**, `branch` from current HEAD, `repoRoot = process.cwd()`, `rawSessionId` from `readLock({ repoRoot }).session_id`. `sessionId` (the semantic label) is not a lock/registry ownership key; the new worktree's Phase 1.2 obtains its own physical raw `session_id`. Because `branch` is the current HEAD it is normally checked out by `repoRoot` already, so `enterWorktree` treats it as a start point only and lands the promoted worktree