Initial commit
This commit is contained in:
Zhongwei Li
486
skills/session-management/references/commands.md
Normal file
486
skills/session-management/references/commands.md
Normal file
@@ -0,0 +1,486 @@
|
||||
# Session Management Command Reference
|
||||
|
||||
Complete reference for all session management commands.
|
||||
|
||||
## Session Lifecycle Commands
|
||||
|
||||
### `start` - Start New Session
|
||||
|
||||
```bash
|
||||
python scripts/session.py start <branch-name> [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--objective "text"` - Set primary objective for this session
|
||||
- `--resume` - Resume if session already exists on this branch
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Start new feature
|
||||
python scripts/session.py start feature/user-auth --objective "Implement JWT authentication"
|
||||
|
||||
# Start with resume fallback
|
||||
python scripts/session.py start feature/payments --resume
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
1. Creates/checks out git branch
|
||||
2. Initializes session directory (`.git/sessions/<branch>/`)
|
||||
3. Loads project context from `.session/`
|
||||
4. Generates agent brief
|
||||
5. Displays user brief with status
|
||||
|
||||
---
|
||||
|
||||
### `resume` - Resume Existing Session
|
||||
|
||||
```bash
|
||||
python scripts/session.py resume [branch-name]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `branch-name` (optional) - Specific branch to resume; defaults to current
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Resume current branch
|
||||
python scripts/session.py resume
|
||||
|
||||
# Resume specific branch
|
||||
python scripts/session.py resume feature/oauth-integration
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
1. Checks out specified branch (if provided)
|
||||
2. Loads session context
|
||||
3. Analyzes git history since last session
|
||||
4. Generates comprehensive brief
|
||||
5. Displays current status
|
||||
|
||||
---
|
||||
|
||||
### `checkpoint` - Create Checkpoint
|
||||
|
||||
```bash
|
||||
python scripts/session.py checkpoint [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--label "text"` - Checkpoint label for easy reference
|
||||
- `--message "text"` - Git commit message
|
||||
- `--decision "text"` - Record architectural decision
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Simple checkpoint
|
||||
python scripts/session.py checkpoint --label "oauth-complete"
|
||||
|
||||
# With decision
|
||||
python scripts/session.py checkpoint \
|
||||
--label "auth-interface" \
|
||||
--decision "Using interface segregation for auth providers"
|
||||
|
||||
# With custom message
|
||||
python scripts/session.py checkpoint \
|
||||
--label "tests-passing" \
|
||||
--message "feat(auth): Add comprehensive test suite"
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
1. Captures current git state
|
||||
2. Analyzes code changes
|
||||
3. Updates progress toward objectives
|
||||
4. Creates enhanced git commit with metadata
|
||||
5. Saves checkpoint metadata
|
||||
|
||||
---
|
||||
|
||||
### `end` - End Session
|
||||
|
||||
```bash
|
||||
python scripts/session.py end [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--handoff` - Generate handoff document (default: true)
|
||||
- `--merge-to <branch>` - Merge to target branch after ending
|
||||
- `--summary` - Generate session summary (default: true)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# End with handoff
|
||||
python scripts/session.py end
|
||||
|
||||
# End and merge
|
||||
python scripts/session.py end --merge-to main
|
||||
|
||||
# End without handoff
|
||||
python scripts/session.py end --no-handoff
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
1. Final comprehensive state capture
|
||||
2. Calculates session metrics
|
||||
3. Generates handoff document
|
||||
4. Archives session data
|
||||
5. Optional: merges to target branch
|
||||
6. Displays accomplishments summary
|
||||
|
||||
---
|
||||
|
||||
### `switch` - Switch Sessions
|
||||
|
||||
```bash
|
||||
python scripts/session.py switch <branch-name>
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `branch-name` - Target session/branch to switch to
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Switch to hotfix
|
||||
python scripts/session.py switch hotfix/critical-bug
|
||||
|
||||
# Back to feature
|
||||
python scripts/session.py switch feature/main-work
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
1. Saves current session state
|
||||
2. Checks out target branch
|
||||
3. Loads target session context
|
||||
4. Displays quick brief
|
||||
5. Highlights differences
|
||||
|
||||
---
|
||||
|
||||
## Context Query Commands
|
||||
|
||||
### `status` - Session Status
|
||||
|
||||
```bash
|
||||
python scripts/session.py status [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--verbose` - Include detailed information
|
||||
- `--objectives` - Show only objectives
|
||||
- `--blockers` - Show only blockers
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Quick status
|
||||
python scripts/session.py status
|
||||
|
||||
# Detailed status
|
||||
python scripts/session.py status --verbose
|
||||
|
||||
# Just objectives
|
||||
python scripts/session.py status --objectives
|
||||
```
|
||||
|
||||
**Output includes:**
|
||||
- Current objectives and progress
|
||||
- Active blockers
|
||||
- Recent changes summary
|
||||
- Time in session
|
||||
- Quality metrics (if available)
|
||||
- Next recommended actions
|
||||
|
||||
---
|
||||
|
||||
### `history` - Session History
|
||||
|
||||
```bash
|
||||
python scripts/session.py history [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--count N` - Number of sessions to show (default: 10)
|
||||
- `--metrics` - Include velocity and quality metrics
|
||||
- `--since <date>` - Filter by date (YYYY-MM-DD format)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Last 10 sessions
|
||||
python scripts/session.py history
|
||||
|
||||
# Last 5 with metrics
|
||||
python scripts/session.py history --count 5 --metrics
|
||||
|
||||
# Since specific date
|
||||
python scripts/session.py history --since 2025-10-01
|
||||
```
|
||||
|
||||
**Output includes:**
|
||||
- Session timeline
|
||||
- Objectives completed per session
|
||||
- Velocity trends (if --metrics)
|
||||
- Quality progression (if --metrics)
|
||||
|
||||
---
|
||||
|
||||
## Management Commands
|
||||
|
||||
### `objectives` - Manage Objectives
|
||||
|
||||
```bash
|
||||
python scripts/session.py objectives <action> [options]
|
||||
```
|
||||
|
||||
**Actions:**
|
||||
- `add "text"` - Add new objective
|
||||
- `complete <id>` - Mark objective complete
|
||||
- `list` - Show all objectives
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Add objective
|
||||
python scripts/session.py objectives add "Implement webhook handlers"
|
||||
|
||||
# Complete objective
|
||||
python scripts/session.py objectives complete obj-1
|
||||
|
||||
# List objectives
|
||||
python scripts/session.py objectives list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `blockers` - Manage Blockers
|
||||
|
||||
```bash
|
||||
python scripts/session.py blockers <action> [options]
|
||||
```
|
||||
|
||||
**Actions:**
|
||||
- `add "text"` - Add new blocker
|
||||
- `resolve <id>` - Mark blocker resolved
|
||||
- `list` - Show all blockers
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Add blocker
|
||||
python scripts/session.py blockers add "Waiting on API keys"
|
||||
|
||||
# Resolve blocker
|
||||
python scripts/session.py blockers resolve blk-1
|
||||
|
||||
# List blockers
|
||||
python scripts/session.py blockers list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `decisions` - Log Decisions
|
||||
|
||||
```bash
|
||||
python scripts/session.py decisions <action> [options]
|
||||
```
|
||||
|
||||
**Actions:**
|
||||
- `add "text"` - Record architectural decision
|
||||
- `list` - Show decision log
|
||||
|
||||
**Options (for add):**
|
||||
- `--rationale "text"` - Decision rationale
|
||||
- `--alternatives "text"` - Alternatives considered
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Record decision
|
||||
python scripts/session.py decisions add "Using JWT over sessions" \
|
||||
--rationale "Stateless auth for microservices"
|
||||
|
||||
# With alternatives
|
||||
python scripts/session.py decisions add "Repository pattern for data access" \
|
||||
--rationale "Separates domain from persistence" \
|
||||
--alternatives "Active Record: Too coupled to database"
|
||||
|
||||
# List decisions
|
||||
python scripts/session.py decisions list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Analysis Commands
|
||||
|
||||
### `analyze` - Session Analysis
|
||||
|
||||
```bash
|
||||
python scripts/session.py analyze [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--velocity` - Calculate velocity metrics
|
||||
- `--patterns` - Detect coding patterns
|
||||
- `--recommendations` - Generate recommendations
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Basic analysis
|
||||
python scripts/session.py analyze
|
||||
|
||||
# With velocity
|
||||
python scripts/session.py analyze --velocity
|
||||
|
||||
# Full analysis
|
||||
python scripts/session.py analyze --velocity --patterns --recommendations
|
||||
```
|
||||
|
||||
**Output includes:**
|
||||
- Session health score
|
||||
- Pattern compliance
|
||||
- Code quality trends
|
||||
- Velocity calculations (if --velocity)
|
||||
- Recommended actions (if --recommendations)
|
||||
|
||||
---
|
||||
|
||||
### `compare` - Compare Sessions
|
||||
|
||||
```bash
|
||||
python scripts/session.py compare <session-id> [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--changes` - Show code changes
|
||||
- `--metrics` - Compare metrics
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Compare with previous session
|
||||
python scripts/session.py compare session-2025-10-30
|
||||
|
||||
# With detailed changes
|
||||
python scripts/session.py compare session-2025-10-30 --changes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `report` - Generate Reports
|
||||
|
||||
```bash
|
||||
python scripts/session.py report [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--weekly` - Weekly summary
|
||||
- `--project` - Complete project summary
|
||||
- `--format <type>` - Output format (markdown, json, html)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Weekly report
|
||||
python scripts/session.py report --weekly
|
||||
|
||||
# Project summary
|
||||
python scripts/session.py report --project --format markdown
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Starting Your Day
|
||||
|
||||
```bash
|
||||
# Resume where you left off
|
||||
python scripts/session.py resume
|
||||
|
||||
# Check what needs to be done
|
||||
python scripts/session.py status
|
||||
```
|
||||
|
||||
### During Development
|
||||
|
||||
```bash
|
||||
# Checkpoint at milestones
|
||||
python scripts/session.py checkpoint --label "api-implemented"
|
||||
|
||||
# Record important decisions
|
||||
python scripts/session.py decisions add "Using Redis for caching" \
|
||||
--rationale "Fast, simple, proven for this use case"
|
||||
|
||||
# Track blockers
|
||||
python scripts/session.py blockers add "Need database credentials"
|
||||
```
|
||||
|
||||
### Ending Your Day
|
||||
|
||||
```bash
|
||||
# End with comprehensive handoff
|
||||
python scripts/session.py end
|
||||
|
||||
# Or end and merge
|
||||
python scripts/session.py end --merge-to main
|
||||
```
|
||||
|
||||
### Context Switching
|
||||
|
||||
```bash
|
||||
# Urgent issue
|
||||
python scripts/session.py switch hotfix/prod-issue
|
||||
|
||||
# Back to feature work
|
||||
python scripts/session.py switch feature/current-work
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
All commands return standard exit codes:
|
||||
- `0` - Success
|
||||
- `1` - Error (check output for details)
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Session management respects these environment variables:
|
||||
|
||||
- `SESSION_CONFIG` - Path to custom config file
|
||||
- `SESSION_VERBOSE` - Enable verbose output (true/false)
|
||||
- `GIT_DIR` - Custom git directory location
|
||||
|
||||
---
|
||||
|
||||
## Integration with Git
|
||||
|
||||
Session management integrates with git through:
|
||||
|
||||
**Git Hooks:**
|
||||
- `post-checkout` - Auto-load session on branch switch
|
||||
- `prepare-commit-msg` - Inject session metadata
|
||||
- `post-commit` - Update progress tracking
|
||||
|
||||
**Git Configuration:**
|
||||
- Uses `user.name` and `user.email` for session attribution
|
||||
- Respects `.gitignore` for file tracking
|
||||
- Works with all git workflows (merge, rebase, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Tips & Tricks
|
||||
|
||||
**Aliases:**
|
||||
Add to your shell profile for quick access:
|
||||
```bash
|
||||
alias ss='python scripts/session.py status'
|
||||
alias sc='python scripts/session.py checkpoint'
|
||||
alias se='python scripts/session.py end'
|
||||
```
|
||||
|
||||
**Quick Checkpoints:**
|
||||
```bash
|
||||
# Label-only checkpoint (uses current time as message)
|
||||
python scripts/session.py checkpoint --label "milestone"
|
||||
```
|
||||
|
||||
**Verbose Troubleshooting:**
|
||||
```bash
|
||||
# Any command can use --verbose for detailed output
|
||||
python scripts/session.py status --verbose
|
||||
```
|
||||
Reference in New Issue
Block a user