gh-awudevelop-claude-plugins-session/commands/start.md at master

zhongwei/gh-awudevelop-claude-plugins-session

Files

Zhongwei Li 681c2e46c0 Initial commit

2025-11-29 17:59:29 +08:00

9.7 KiB

Raw Permalink Blame History

You are managing a session memory system. The user wants to start a new named session.

CRITICAL - Command Format: All session plugin commands use the /session: prefix. DO NOT suggest commands without this prefix.

✅ Correct: /session:list, /session:start, /session:continue, /session:status
❌ Wrong: /session list, /session start, /session continue, /session status Use ONLY the exact command formats specified in this template.

Task: Start New Session

Parse the session name from the command arguments. The command format is: /session:start [name]

OPTIMIZATION: This command now updates the metadata index after creating the session.

Step 1: Validate Session Name

Extract the session name from the arguments
Validate the name matches regex: ^[a-zA-Z0-9_-]+$

If invalid, show error:

❌ Error: Invalid session name '{name}'
Session names can only contain:
- Letters (a-z, A-Z)
- Numbers (0-9)
- Hyphens (-)
- Underscores (_)

Example: my-session or my_session_123

Then STOP.

Step 2: Check for Duplicate Sessions

CRITICAL: Check both directory names AND session.md file contents to prevent duplicates.

Check directory collision:

Check if .claude/sessions/{name}/ directory already exists

If exists, show error:

❌ Error: Session directory '{name}' already exists
💡 Use /session:continue {name} to resume
💡 Or use /session:list to see all sessions

Then STOP.

Check session name collision (NEW - prevents duplicate names):
- Use the CLI to get all existing sessions:
```
node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js list
```
- Parse the JSON response and check if any existing session has name: "{name}"
- If a session with this name exists (even if directory name is different), show error:
```
❌ Error: A session named '{name}' already exists
💡 Use /session:list to see all sessions
💡 Choose a different name for this session
```
  Then STOP.

This dual-check prevents both directory collisions and duplicate session names.

Step 3: Check for Active Session and Transition (NEW - Session Cleanup)

Before creating the new session, check if there's already an active session:

Check if .claude/sessions/.active-session exists
If it exists:
- Read the current active session name
- Show: "📋 Closing previous session '{previous_session_name}'..."
- Close the previous session status:
```
node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js update-status "{previous_session_name}" "closed"
```
- This marks the previous session as closed in .auto-capture-state
Continue to next step (the new session activation will overwrite .active-session)

Note: The SessionEnd hook will handle final cleanup on Claude Code termination.

Step 4: Create Session Folder

Create directory: .claude/sessions/{name}/
Verify creation was successful

Step 5: Initialize session.md

CRITICAL: The session name in session.md MUST match the directory name to prevent duplicates.

Create .claude/sessions/{name}/session.md with this content:

# Session: {name}

**Started**: {current_timestamp_YYYY-MM-DD_HH:MM}
**Last Updated**: {current_timestamp_YYYY-MM-DD_HH:MM}

## Goal
[Ask user to describe the goal for this session]

## Overview
Working on: {name}

## Key Milestones
- [ ] [To be defined during session]

## Files Involved
- [Will be tracked as work progresses]

## Configuration
- Auto-capture: enabled

## Notes
Session started. Use /session:save to capture important milestones.

Step 6: Initialize context.md

Create .claude/sessions/{name}/context.md with this content:

# Session Context: {name}

## Key Decisions
[Decisions will be captured during session]

## Important Discoveries
[Discoveries will be documented as they occur]

## Blockers & Resolutions
[Issues and resolutions will be tracked here]

## Technical Context
[Architecture decisions and technical details]

## Summary
Session started on {current_timestamp}. Ready to capture context.

Step 7: Update Active Session Tracker

Write the session name to .claude/sessions/.active-session (single line, just the name)
This marks it as the currently active session

Step 7.5: Initialize .auto-capture-state with Session Status

Create .claude/sessions/{name}/.auto-capture-state with initial session status:

echo '{
  "interaction_count": 0,
  "modified_files": [],
  "last_snapshot_timestamp": null,
  "session_status": "active",
  "session_started": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
  "session_closed": null
}' > .claude/sessions/{name}/.auto-capture-state

This initializes the operational state tracking for the session, including the session status which is now tracked in JSON for fast, atomic updates.

Step 8: Update Index (NEW - CRITICAL)

Run the CLI command to add the new session to the metadata index:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js update-index --session {name}

This ensures the new session appears immediately in /session:list without requiring a full rebuild.

Step 9: Display Success Message

Show this confirmation to the user:

✓ Session '{name}' started
📁 Location: .claude/sessions/{name}/
💡 Use /session:save to capture important milestones
📊 Check /session:status to monitor tokens

Ready to work! What would you like to accomplish in this session?

Step 10: Ask for Session Goal

After showing the success message, ask the user: "What is the main goal or purpose of this session? (This will be saved to session.md)"

Wait for their response, then update the "Goal" section in session.md with their answer.

PERFORMANCE BENEFITS:

Before: No index integration, sessions invisible until manual list command scans
After: Instant index update, session immediately visible in list
Improvement: Better UX, no stale index issues

IMPORTANT:

Execute all steps in order
Use the Read, Write, and Bash tools to perform file operations
The CLI update-index command is fast (< 10ms) and ensures consistency
Do not skip any steps

CRITICAL: Check for Unconsolidated Logs (Inline Analysis)

IMPORTANT: New session start should NOT have unconsolidated logs, but check anyway for robustness.

MUST CHECK BEFORE DISPLAYING SUCCESS MESSAGE:

After starting the session, check if previous session left unconsolidated logs:

Check if .claude/sessions/{name}/conversation-log.jsonl exists
If the file exists:
- Show brief message: "📊 Analyzing previous session... (this may take 1-3 seconds)"
- Read the conversation log file
- Parse interactions from JSONL format
- Capture git history (if available):
  - Run: node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js capture-git "{name}"
  - This creates .claude/sessions/{name}/git-history.json (~2-3KB compressed)
  - Contains: last 50 commits, uncommitted changes, branch status, hotspots
  - Performance: ~60-90ms (acceptable at session boundary)
  - If no git repo, command returns success: false (silent skip, no error)
- Analyze the conversation with Claude inline:
  - Extract conversation summary (2-3 paragraphs covering what happened)
  - Identify key decisions made with rationale
  - List completed todos/tasks
  - Document files modified with context about what changed and why
  - Assess current state, what's next, and any blockers
- Create consolidated snapshot via CLI:
```
echo "# Consolidated Snapshot: {session_name}
```

Timestamp: {ISO timestamp} Method: Claude Inline Analysis (Free) Status: Consolidated from conversation log Format Version: 2.0

Topics Discussed

[Category]: [Brief description of what was discussed]
[Category]: [Brief description of what was discussed] [Continue for ALL topics in chronological order]

Suggestions & Recommendations

[Category]: [Specific suggestion] - [Rationale]
[Category]: [Specific suggestion] - [Rationale] [Continue for ALL suggestions]

Decisions Made

[Decision]: [Rationale and context]
[Decision]: [Rationale and context] [Continue for ALL decisions]

Tasks Completed

[Action completed in past tense]
[Action completed in past tense] [Continue for ALL tasks]

Files Modified

[file_path]: [What changed and why]
[file_path]: [What changed and why] [Continue for ALL files]

Current Status

Progress: [Where things stand - what's been accomplished]
Next Steps: [What should be done next]
Blockers: [Issues or write "None"]

Notes

Consolidated via Claude inline analysis at session boundary. Zero cost, highest quality." | node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js write-snapshot "{name}" --stdin --type auto ```

Delete conversation-log.jsonl after successful snapshot creation
Update .auto-capture-state to reset counters and set last_snapshot_timestamp

If no log exists:
- Still capture git history for repository context:
  - Run: node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js capture-git "{name}"
  - This provides git context even for new sessions
  - Silent skip if no git repo (no error)
- Initialize .auto-capture-state if needed

PERFORMANCE:

Log check: <5ms
Claude analysis: 1-3s (acceptable at session boundaries - users expect loading)
Snapshot write: <50ms
Log deletion: <5ms
Total: ~1-3 seconds (users expect loading at session start)

NOTE: This is the v3.5.1 architecture where conversation logging is incremental (<2ms per interaction) and consolidation happens inline at session boundaries using FREE Claude analysis for highest quality.

9.7 KiB Raw Permalink Blame History