session-init

Session Init

Create protocol-compliant session logs with verification-based enforcement.

Quick Start

Automated (Recommended)

pwsh .claude/skills/session-init/scripts/New-SessionLog.ps1

The script will:

1. Prompt for session number and objective
2. Auto-detect git state (branch, commit, date)
3. Read canonical template from SESSION-PROTOCOL.md
4. Write session log with EXACT template format
5. Validate immediately with Validate-SessionJson.ps1
6. Exit nonzero on validation failure

Manual (If Needed)

/session-init

Follow the manual workflow below if the automated script doesn't meet your needs.

Triggers

Why This Skill Exists

Problem: Every PR starts with malformed session logs that fail CI validation.

Root Cause: Agents generate session logs from LLM memory instead of copying the canonical template from SESSION-PROTOCOL.md. This causes variations like:

• Missing (COMPLETE ALL before closing) text in Session End header
• Wrong heading levels (## vs ###)
• Missing sections

Solution: Verification-based enforcement following the proven Serena initialization pattern.

Session Naming Protocol

Format: YYYY-MM-DD-session-NN.json

The script automatically generates human-readable filenames by extracting up to 5 keywords from the session objective using NLP heuristics:

• Remove stop words: Common words like "the", "a", "to", "for" are filtered out
• Keep domain terms: Technical verbs like "implement", "debug", "fix", "refactor" are preserved
• Convert to kebab-case: Words are joined with hyphens for readability
• Limit to 5 keywords: Most relevant terms from the start of the objective

Examples

Benefits

• Human-readable discovery: Browse session history with ls .agents/sessions/ and instantly understand content
• Grep-friendly search: Find sessions by topic with grep -l "oauth" .agents/sessions/*.json
• Self-documenting: No need to open files to understand what each session covers
• Chronological order: YYYY-MM-DD prefix preserves time-based sorting
• Pattern identification: Keyword clustering reveals recurring themes across sessions

Process Overview

User Request: /session-init
    |
    v
+---------------------------------------------+
| Phase 1: GATHER INPUTS                      |
| - Prompt for session number                 |
| - Prompt for objective                      |
| - Auto-detect: date (YYYY-MM-DD)           |
| - Auto-detect: branch (git branch)         |
| - Auto-detect: commit (git log)            |
| - Auto-detect: git status                  |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 2: READ CANONICAL TEMPLATE            |
| - Read .agents/SESSION-PROTOCOL.md         |
| - Extract template (lines 494-612)         |
| - Preserve EXACT formatting                |
| - Critical: Keep "(COMPLETE ALL before     |
|   closing)" text in Session End header     |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 3: POPULATE TEMPLATE                  |
| - Replace NN with session number           |
| - Replace YYYY-MM-DD with date             |
| - Replace [branch name] with actual branch |
| - Replace [SHA] with commit hash           |
| - Replace [objective] with user input      |
| - Replace [clean/dirty] with git status    |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 4: WRITE SESSION LOG                  |
| - Generate descriptive filename with        |
|   keywords from objective                   |
| - Write to .agents/sessions/YYYY-MM-DD-    |
|   session-NN-keyword1-keyword2-...md       |
| - Preserve all template sections           |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 5: IMMEDIATE VALIDATION               |
| - Run Validate-SessionJson.ps1         |
| - Report validation result                 |
| - If FAIL: show errors, allow retry       |
| - If PASS: confirm success                 |
+---------------------------------------------+
    |
    v
Protocol-Compliant Session Log

Workflow

Step 1: Gather Session Information

Prompt user for required inputs:

What is the session number? (e.g., 375)
What is the session objective? (e.g., "Implement session-init skill")

Auto-detect from environment:

# Current date
date +%Y-%m-%d
# or PowerShell: Get-Date -Format "yyyy-MM-dd"

# Current branch
git branch --show-current

# Starting commit
git log --oneline -1

# Git status
git status --short

Step 2: Read Canonical Template

CRITICAL: Use the New-SessionLog.ps1 script to read the template from SESSION-PROTOCOL.md.

$template = & .claude/skills/session-init/scripts/New-SessionLog.ps1

DO NOT generate the template from memory or read specific line numbers. The script extracts the canonical template dynamically:

• Header levels (## vs ###)
• Table structure with pipe separators
• Checkbox format [ ]
• Comment blocks <!-- -->
• CRITICAL: ### Session End (COMPLETE ALL before closing) header text

Step 3: Populate Template Variables

Replace placeholders with actual values:

Leave these unchanged:

• All checklist items [ ] (unchecked)
• Evidence columns with placeholder text
• Comment blocks

Step 4: Write Session Log File

Write the populated session log to a file with descriptive naming:

Filename Format: YYYY-MM-DD-session-NN.json

The script automatically:

1. Extracts up to 5 keywords from the objective
2. Filters out common stop words (the, a, to, for, etc.)
3. Converts to kebab-case
4. Generates human-readable filename

Example:

For objective "Debug recurring session validation failures", the filename becomes: 2026-01-06-session-374-debug-recurring-session-validation-failures.md

Construct filename: .agents/sessions/YYYY-MM-DD-session-NN.json

Example: .agents/sessions/.agents/sessions/2026-01-05-session-375.json

Write the populated template to this file.

Step 5: Validate Immediately

Run validation script:

pwsh scripts/Validate-SessionJson.ps1 -SessionPath ".agents/sessions/YYYY-MM-DD-session-NN.json" 

Check exit code:

Verification Checklist

Before reporting success:

• Session number provided by user
• Objective provided by user
• Template read from SESSION-PROTOCOL.md (NOT generated from memory)
• All template sections present
• Session End header includes (COMPLETE ALL before closing)
• File written to correct path .agents/sessions/YYYY-MM-DD-session-NN.json
• Validation script executed
• Validation result is PASS (exit code 0)

Anti-Patterns

Example Output

Success:

Session log created and validated

  File: .agents/sessions/.agents/sessions/2026-01-05-session-375.json
  Validation: PASS
  Branch: feat/session-init
  Commit: abc1234

Next: Complete Session Start checklist in the session log

Failure:

Session log created but validation FAILED

  File: .agents/sessions/.agents/sessions/2026-01-05-session-375.json
  Validation: FAIL
  Errors:
    - Missing Session End checklist header

Run: pwsh scripts/Validate-SessionJson.ps1 -SessionPath ".agents/sessions/.agents/sessions/2026-01-05-session-375.json" 

Fix the issues and re-validate.

Related Skills

Scripts

Example Usage

Automated (Recommended):

# Create session log with interactive prompts
pwsh .claude/skills/session-init/scripts/New-SessionLog.ps1

# Create session log with parameters
pwsh .claude/skills/session-init/scripts/New-SessionLog.ps1 -SessionNumber 375 -Objective "Implement feature X"

Manual Template Extraction (for custom workflows):

# Extract template
$template = & .claude/skills/session-init/scripts/New-SessionLog.ps1

# Populate with session data
$sessionLog = $template -replace 'NN', '375' -replace 'YYYY-MM-DD', '2026-01-06'

# Write to file
$sessionLog | Out-File -FilePath '.agents/sessions/.agents/sessions/2026-01-06-session-375.json'

References

• SESSION-PROTOCOL.md - Canonical template source
• Validate-SessionJson.ps1 - Validation script
• Template Extraction - How to extract template
• Validation Patterns - Common validation issues

Pattern: Verification-Based Enforcement

This skill follows the same pattern as Serena initialization:

Why it works:

• Reads canonical template from file (single source of truth)
• Auto-populates git state (reduces manual errors)
• Validates immediately with same script as CI (instant feedback)
• Cannot skip validation (built into skill workflow)
• Provides actionable error messages if validation fails