Session Management

Manages work sessions. Session paths must be explicitly provided or known from context.

Session Path Resolution

IMPORTANT: Sessions do NOT have a default location. The session path must be:

•Provided explicitly in arguments (e.g., start ~/projects/my-project/_sessions/session-name)
•Already known from conversation context (active session in working memory)
•Defined in project's .samocode file under SESSIONS path

If session path cannot be determined: STOP and ask the user for the session location.

Actions

Use $ARGUMENTS to specify action and parameters:

•start [session-path/name] - Create new session
•continue [session-name-pattern] - Load existing session
•sync - Sync current conversation to active session
•archive [session-name-pattern] - Archive a session

Action: start

Create a new work session.

Steps

•
Resolve session location:
- •If full path provided in arguments: use it
- •If only name provided: check project .samocode file for SESSIONS path
- •If neither: STOP and ask user for session directory path
•
Parse session name:
- •Take session name from arguments after "start"
- •If empty, ERROR: "Session name required. Usage: start [session-name]"
- •Sanitize name (lowercase, replace spaces with hyphens)
•
Create session folder:
- •Path: [SESSIONS_DIR]/[YY-MM-DD]-[session-name]/ (use current date for folder name)
- •If folder exists, ERROR: "Session already exists"
•
Detect Working Dir:
- •Check project .samocode file for MAIN_REPO path
- •Or use git root: git rev-parse --show-toplevel
- •Or use current working directory
- •If unclear: leave as "TBD" and note to set it

•

Create _overview.md:

markdown

# Session: [session-name]
Started: [TIMESTAMP_LOG]
Working Dir: [detected or TBD]

## Status
Phase: investigation
Iteration: 1
Blocked: no
Last Action: Session created
Next: Ready to work

## Flow Log
- [TIMESTAMP_ITERATION] Session created

## Files
(none yet)

## Plans
(none yet)

## Linear Tasks
(none yet)

•
Commit (if sessions dir is a git repo):
- •cd [SESSIONS_DIR] && git add . && git commit -m "Start session: [session-name]"

•

Confirm to user:

code

Session created: [YY-MM-DD]-[session-name]
Path: [full-path]

IMPORTANT: This is now your active session. Remember this path for subsequent commands.

Ready to work. Use /dive, /task, or /create-plan to continue.

IMPORTANT: After creating the session, keep the session path in your working memory for all subsequent session-aware commands.

Action: continue

Load and continue working in an existing session.

Steps

•
Resolve session location:
- •If full path provided: use it
- •Check project .samocode file for SESSIONS path
- •If not found: STOP and ask user for sessions directory
•
Find matching sessions:
- •Search sessions directory for folders matching *$ARGUMENTS* (exclude archive/)
- •Sort by modification time (most recent first)
•
Handle results:
- •No matches: ERROR: "No sessions found matching '$ARGUMENTS'. Use start action to create one."
- •One match: Proceed to load
- •Multiple matches: List them with dates and ask user to specify
•
Load session:
- •Read _overview.md from the session folder
- •Add Flow Log entry: - [TIMESTAMP_ITERATION] Session resumed
- •Commit if git repo: git add . && git commit -m "Resume session: [session-name]"

•

Present summary:

code

Session: [session-name]
Path: [full-path]
Working Dir: [from _overview.md]
Started: [date]

Recent Activity:
[Last 5-10 Flow Log entries]

Files: [count]
[List with brief descriptions]

Plans: [list if any]
Linear Tasks: [list if any]

---
Session loaded. Ready to continue.

IMPORTANT: After loading, keep the session path in your working memory for all subsequent session-aware commands.

Action: sync

Ensure all work from this conversation is recorded in the active session.

Steps

•
Check for active session:
- •If no session in working memory: ERROR: "No active session. Use continue action to load one first."
•
Read current session state:
- •Read [SESSION_PATH]/_overview.md
•
Review conversation for unrecorded work:
- •Code changes (files created, modified, deleted)
- •Decisions made
- •Problems solved
- •Discoveries about the codebase
- •Commits made
- •Blockers/TODOs remaining
•
Update _overview.md:
- •Add missing Flow Log entries
- •Add missing Files entries
- •Update other sections as needed
•
Create detail files if warranted:
- •Only for complex topics that need more than a log entry
•
Commit (if git repo):
- •cd [SESSION_DIR] && git add . && git commit -m "Sync session: [session-name]"
•
Report:
- •"Session synced: [what was added]"
- •Or: "Session already up to date."

Action: archive

Archive a session (full) or archive work within a session (partial).

Usage Patterns

•archive - Archive entire active session (moves folder to archive/)
•archive [session-name] - Archive entire named session
•archive keep file1.md file2.md - Archive work files within session, keep specified files
•archive [session-path] keep file1.md - Archive work in specific session, keep files

Full Archive (no "keep" keyword)

Session Resolution

•
If arguments after "archive" are empty:
- •Check for active session in working memory
- •If no active session: ERROR: "No active session and no session name provided."
- •Use active session path
•
If arguments provided (no "keep"):
- •Search sessions directory for folders matching *$ARGUMENTS* (exclude archive/)
- •No matches: ERROR: "No sessions found matching '$ARGUMENTS'"
- •One match: Confirm with user: "Archive session [name]? (y/n)"
- •Multiple matches: List and ask user to specify

Full Archive Process

•
Get session info:
- •Read [SESSION_PATH]/_overview.md
- •Extract Working Dir line
•
Create archive folder if needed:
bash
```
mkdir -p [SESSIONS_DIR]/archive
```
•
Remove worktree (if applicable):
- •
  If Working Dir contains /worktrees/:
  bash
  git worktree remove [working_dir_path]
- •If removal fails (uncommitted changes), warn user and ask to proceed or abort
- •Note: Branch is preserved, only worktree removed

•

Move session folder:

bash

mv [SESSION_PATH] [SESSIONS_DIR]/archive/

•
Commit changes (if git repo):
- •cd [SESSIONS_DIR] && git add . && git commit -m "Archive session: [session-name]"
•
Clear active session (if archiving active session):
- •Remove from working memory

•

Confirm to user:

code

Session archived: [session-name]
Moved to: [archive-path]
Worktree removed: [path] (branch preserved)

Session closed.

Partial Archive (with "keep" keyword)

Archives completed work within a session while keeping important deliverables accessible.

Argument Parsing

•Split arguments on "keep" keyword
•Before "keep": session path (optional, defaults to active session)
•After "keep": list of files to keep in place (space-separated)

Example: archive keep competitor-analysis.md → archive active session, keep competitor-analysis.md

Partial Archive Process

•
Resolve session:
- •If path before "keep": use it
- •Otherwise: use active session from working memory
- •ERROR if no session found
•
Get timestamp and slug:
bash
```
TIMESTAMP_FOLDER=$(date '+%y-%m-%d')
```
- •Extract slug from session folder name or task name from _overview.md
- •Archive folder: [SESSION_PATH]/archive/[YY-MM-DD]-[slug]/

•

Create archive subfolder:

bash

mkdir -p [SESSION_PATH]/archive/[YY-MM-DD]-[slug]

•
Identify files to archive:
- •
  All .md files in session root EXCEPT:
  - •_overview.md (always kept - session state)
  - •_qa.md (always kept if exists)
  - •_signal.json (always kept)
  - •Files listed after "keep" keyword
- •All timestamped files (pattern: [MM-DD-HH:mm]-*.md)

•

Move files to archive:

bash

for file in [files_to_archive]; do
  mv "$file" [SESSION_PATH]/archive/[YY-MM-DD]-[slug]/
done

•
Update _overview.md:
- •Add Flow Log entry: - [TIMESTAMP_LOG] Archived work to archive/[YY-MM-DD]-[slug]/, kept: [kept_files]
- •Reset Status section for next task

•

Report to user:

code

Work archived within session.
Archived to: [SESSION_PATH]/archive/[YY-MM-DD]-[slug]/
Files moved: [count] files
Kept in place: [kept_files]