Create protocol-compliant JSON session logs with verification-based enforcement. Autonomous operation with auto-incremented session numbers and objective derivation from git state. Use when starting any new session. Use when you say "start a session", "create the session log". Do NOT use for mid-session protocol checks (use session), or to complete and validate a log at the end of a session (use session-end).
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Create protocol-compliant JSON session logs with verification-based enforcement. Autonomous operation with auto-incremented session numbers and objective derivation from git state. Use when starting any new session. Use when you say "start a session", "create the session log". Do NOT use for mid-session protocol checks (use session), or to complete and validate a log at the end of a session (use session-end).
An existing session log has validation errors that need repair
CI failed with "Session protocol validation failed"
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
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_session_json.py |
| - Report validation result |
| - If FAIL: show errors, allow retry |
| - If PASS: confirm success |
+---------------------------------------------+
|
v
Protocol-Compliant Session Log
Workflow
Step 0: Issue Coordination Pre-flight (when an issue number is known)
Before creating the session log or a development branch for a specific issue,
confirm no one else is already working it (issue #2477, competing PRs):
# Refuse to open a duplicate if an open PR already addresses the issue
python3 .claude/skills/github/scripts/issue/check_existing_pr_for_issue.py --issue <N>
# Refuse to start if another login already holds the issue
python3 .claude/skills/github/scripts/issue/claim_issue.py --issue <N>
Either script exiting non-zero means STOP: coordinate on the existing claim or PR
instead of opening a competing one. Skip this step for issue-less sessions.
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 datedate +%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_session_log.py script to read the template from SESSION-PROTOCOL.md.
uv run python "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/session-init/scripts/new_session_log.py"
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:
Placeholder
Replace With
NN
Session number (e.g., 375)
YYYY-MM-DD
Current date
[branch name]
Git branch name
[SHA]
Starting commit hash
[What this session aims to accomplish]
User-provided objective
[clean/dirty]
Git status result
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:
Extracts up to 5 keywords from the objective
Filters out common stop words (the, a, to, for, etc.)
Converts to kebab-case
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.json
uv run python scripts/validate_session_json.py ".agents/sessions/YYYY-MM-DD-session-NN.json"
Check exit code:
Exit Code
Meaning
Action
0
PASS
Confirm success, agent proceeds
1
FAIL
Show errors, offer to retry
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
Avoid
Why
Instead
Generating template from memory
Will miss exact formatting
Read from SESSION-PROTOCOL.md
Skipping validation
Won't catch errors until CI
Validate immediately
Hardcoding template in skill
Template may change
Always read from canonical source
Pre-checking boxes
Defeats verification purpose
Leave all unchecked
Using ## Session End
Missing required text
Use ### Session End (COMPLETE ALL before closing)
Example Output
Success:
Session log created and validated
File: .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/2026-01-05-session-375.json
Validation: FAIL
Errors:
- Missing Session End checklist header
Run: uv run python scripts/validate_session_json.py ".agents/sessions/2026-01-05-session-375.json"
Fix the issues and re-validate.
# Create session log with parameters
uv run python "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/session-init/scripts/new_session_log.py" --session-number 375 --objective "Implement feature X"# Skip validation
uv run python "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/session-init/scripts/new_session_log.py" --session-number 375 --objective "Implement feature X" --skip-validation
# Simplified JSON-only version
uv run python "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/session-init/scripts/new_session_log_json.py" --session-number 375 --objective "Implement feature X"
Vendored install
This skill depends on upstream-only paths. In a vendored install (a consumer
repo that is not rjmurillo/ai-agents) these paths do not exist:
Path
Direction
Behavior when absent
.agents/sessions/
write via artifact root
The creation script creates the directory when needed and writes the session log there.
.agents/SESSION-PROTOCOL.md
reference only
The script does not read this file at runtime; it builds JSON from session_init/session_structure.py.
scripts/validate_session_json.py
read/execute for new_session_log.py validation
Vendored installs need this script in the consumer repo for new_session_log.py, or callers must use --skip-validation. new_session_log_json.py does not run validation.
The HTML comment above is the machine-readable declaration the
check_skill_md_portability.py validator (Issue #2050) reads to confirm this
skill has disclosed its path dependencies instead of hiding them in prose.
