| name | session-begin |
| description | Pre-flight checklist for work sessions — loads context, checks hook state, surfaces warnings, and gates on acknowledgment before work begins. |
| compatibility | agentskills-v1 |
| metadata | {"version":2.1} |
Session Begin Pre-Flight
Pre-flight checklist that orients the session: loads context, validates
environment, surfaces warnings, and hands off to the user with a goal-selection
prompt.
Time budget: Session-begin SHOULD complete in under 3 minutes. If script
issues or staleness require extended remediation, present findings and defer
fixes to user decision.
JASON-OS v0.1 scope note: This skill was ported from SoNash and trimmed
for bootstrap. Sections referencing infrastructure JASON-OS doesn't have yet
(health scripts, override/health-score logs, technical-debt index,
consolidation pipeline, secrets-decryption gate) are marked DEFERRED inline
with a pointer to re-wire them when the corresponding systems land. See
BOOTSTRAP_DEFERRED.md for
the broader deferral ledger.
Critical Rules (MUST follow)
- Duplicate detection first — MUST check before any action (see below).
- Never double-increment — MUST verify the session counter wasn't already
incremented in this conversation or after compaction before incrementing.
- Announce session number — MUST output "Session #N started on [branch]"
after incrementing.
- Script failures escalate to user — MUST present failures with options
(fix now / defer / ignore). Do not decide unilaterally. (Vacuous in
bootstrap — no health scripts wired yet; restore when Phase 3 lands.)
- Stale docs are a user decision — MUST present discrepancies and ask
"Update now or defer?" Do not auto-fix.
- Scope explosion guard — if 3+ scripts failed or 3+ actionable findings
surfaced, MUST present a triage list before acting on any.
Duplicate Detection (MUST — before anything)
Check all three:
- Have I already completed this checklist in the current conversation?
- Was SESSION_CONTEXT.md "Last Updated" modified today? (date-only field —
sub-day relies on checks #1 and #3)
- Did I already increment the session counter in this conversation?
If ANY true: "Session #N already active. What would you like to work on?"
If ALL false: Proceed with full checklist.
When to Use
- Start of every AI work session
- User explicitly invokes
/session-begin
When NOT to Use
- Session closure →
/session-end
- State snapshot →
/checkpoint
- Already ran this session → duplicate detection catches it
Hook Boundary
The SessionStart hook in JASON-OS v0.1 runs only check-mcp-servers.js
(and compact-restore.js after compactions). Consolidation, cross-session
validation, dependency install, and build are NOT handled by the hook yet —
when those hooks land, update this section and remove the corresponding
manual steps below.
Warm-Up (MUST — first output after duplicate detection passes)
"Starting Session #N pre-flight on [branch]. Will load context, check hook
state, and surface any warnings."
Phase 1: Environment Setup (MUST)
1.1 Secrets Decryption Check (DEFERRED)
JASON-OS bootstrap has no scripts/secrets/ infrastructure. When an
.env.local.encrypted + decrypt pipeline lands, restore the SoNash-style gate
here (passphrase-via-stdin, never logged).
1.2 Cross-Session Validation (DEFERRED)
SessionStart hook does not yet do cross-session validation. When that hook
work lands, restore the prior-session-missed-/session-end check here.
Phase 2: Context Loading (MUST)
2.1 Load Session Context (MUST)
- Read SESSION_CONTEXT.md — status, blockers,
goals
- Increment session counter (MUST — verify not already incremented first)
- Output: "Session #N started on [branch]"
(ROADMAP.md read is DEFERRED — JASON-OS v0.1 does not have ROADMAP.md yet.
Next Session Goals live in SESSION_CONTEXT.md for now.)
2.2 Branch Validation (MUST)
Report the current branch from git branch --show-current in the session
announcement. If SESSION_CONTEXT.md documents a different branch (in Quick
Status or Next Session Goals), warn the user before proceeding.
2.3 Stale Documentation Check (MUST)
git log --oneline -15
Compare recent commits against SESSION_CONTEXT.md's "Next Session Goals" and
"Quick Status." If discrepancies found, present them: "Docs appear stale:
[specifics]. Update now or defer?"
Let the user decide. Do not auto-update.
2.4–2.6 (DEFERRED)
Session-gap detection, consolidation status, and prior-research surface all
depend on infrastructure not yet in JASON-OS (npm run session:gaps,
scripts/run-consolidation.js, .research/research-index.jsonl). Restore
when those land.
Phase 3: Health Scripts (DEFERRED — JASON-OS v0.1)
JASON-OS bootstrap does not yet wire any npm run health scripts. When any of
patterns:check, review:check, lessons:surface, session:gaps,
roadmap:hygiene, reviews:sync, reviews:check-archive, reviews:archive,
hooks:analytics, crossdoc:check, or the velocity/task-dependency reports
land, restore the SoNash-style block here and flip the script-failure-
escalation rule (Critical Rule 4) from vacuous to live.
Until then: note "Health scripts: not yet wired (JASON-OS v0.1)" in the
summary.
Phase 4: Warning Gates (MUST)
4.1 Hook Anomaly Gate (MUST)
Check .claude/state/hook-warnings-log.jsonl. If 10+ entries in last 7 days
→ warn. If fewer, skip silently.
(SoNash override-trend and health-score-drop sub-checks are DEFERRED —
.claude/override-log.jsonl and .claude/state/health-score-log.jsonl do
not exist in JASON-OS v0.1. Restore when those logs land.)
4.2 Warning Acknowledgment Gate (DEFERRED)
No .claude/hook-warnings.json or scripts/sync-warnings-ack.js in JASON-OS
v0.1. When the warning-acknowledgment pipeline lands, restore the gate here.
4.3 Infrastructure Failure Gate (DEFERRED)
No .claude/state/session-start-failures.json, pending-test-registry.json,
or decision-documentation hook-warnings entries yet. Restore when those
systems land.
4.4 Technical Debt Snapshot (DEFERRED)
No docs/technical-debt/INDEX.md in JASON-OS v0.1. Restore when a tech-debt
index lands (or adapt to a JASON-OS-native debt surface).
Phase 5: Summary & Goal Selection (MUST)
Summary Template
Present using this format:
Session #N — Pre-Flight Summary
Branch: [branch]
Working tree: [clean / N uncommitted]
Health scripts: not yet wired (JASON-OS v0.1)
Hook warnings: [none / N new entries in last 7d]
Deferred infrastructure: see BOOTSTRAP_DEFERRED.md
Next Goals (from SESSION_CONTEXT.md):
[list ALL goals from the "Next Session Goals" section —
do not truncate or cap the list]
Goal Selection (MUST)
After the summary: "Which goal would you like to focus on, or something else?"
Reference the surfaced goals — do not use a generic open-ended prompt.
Closure Signal (MUST)
"Session #N pre-flight complete. Ready to work."
Done when: Session counter incremented, context loaded, hook state
checked, goal selected.
Guard Rails
- Scope explosion: If 3+ scripts failed or 3+ findings surfaced, present a
triage list: "Multiple issues found. Which to address now vs defer?" Do not
auto-fix multiple issues.
- Disengagement: If user says "skip" or "let's work" mid-checklist, stop
immediately. Present what's completed vs remaining. Proceed to goal selection.
- Compaction recovery: If compaction occurs mid-session-begin, re-read
SESSION_CONTEXT.md. If counter was already incremented, do not re-increment.
Resume from the last unfinished phase.
Integration
- Neighbors:
session-end (receives session context), checkpoint
(mid-session state)
- Handoff to session-end: SESSION_CONTEXT.md updated with session number
and current work.
- Reference material: See REFERENCE.md for skill routing,
code review procedures, and anti-pattern guidance.
Version History
| Version | Date | Description |
|---|
| 2.1 | 2026-04-17 | JASON-OS bootstrap trim: DEFERRED markers for unwired infra |
| 2.0 | 2026-03-16 | Skill-audit rewrite: 31 decisions, 51→73 score |
| 1.0 | 2026-02-25 | Initial implementation |
