mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
📚 Major documentation improvements and corrections
- Fix directory structure in technical-architecture.md to match actual ~/.claude/ structure - Correct session management documentation to show true persistent memory via Serena MCP - Add comprehensive flags documentation with 40+ missing command-specific flags - Remove verification status sections across all documentation - Fix component counts: 14 agents, 5 modes, 21 commands - Update gitignore to exclude CRUSH.md and TODO.txt personal files - Standardize documentation structure and remove fictional content 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
@@ -2,11 +2,6 @@
|
||||
|
||||
SuperClaude provides 14 domain specialist agents that Claude Code can invoke for specialized expertise.
|
||||
|
||||
## ✅ Verification Status
|
||||
- **Agent Count**: 14 specialists available
|
||||
- **Last Tested**: 2025-01-16
|
||||
- **Test Environment**: Linux/Windows/macOS
|
||||
- **Agent Activation**: ✅ All Verified
|
||||
|
||||
## 🧪 Testing Agent Activation
|
||||
|
||||
|
||||
@@ -58,11 +58,6 @@ SuperClaude provides behavioral context files that Claude Code reads to adopt sp
|
||||
- `@agent-security` - Activates security specialist context
|
||||
- All commands work inside Claude Code chat interface only
|
||||
|
||||
## ✅ Verification Status
|
||||
- **Last Updated**: 2025-01-21
|
||||
- **Last Tested**: 2025-01-16
|
||||
- **Test Environment**: Linux/Windows/macOS
|
||||
- **Command Syntax**: ✅ All Verified
|
||||
|
||||
> **Quick Start**: Try `/sc:brainstorm "your project idea"` → `/sc:implement "feature name"` → `/sc:test` to experience the core workflow.
|
||||
|
||||
|
||||
@@ -2,41 +2,189 @@
|
||||
|
||||
**Most flags activate automatically** - Claude Code reads behavioral instructions to engage appropriate contexts based on keywords and patterns in your requests.
|
||||
|
||||
## Essential Flags (90% of Use Cases)
|
||||
## Essential Auto-Activation Flags (90% of Use Cases)
|
||||
|
||||
### Auto-Activation Flags
|
||||
### Core Analysis Flags
|
||||
| Flag | When Activated | What It Does |
|
||||
|------|---------------|--------------|
|
||||
| `--think` | 5+ files OR complex analysis | Standard structured analysis |
|
||||
| `--magic` | UI components, frontend | Modern UI generation |
|
||||
| `--loop` | "improve", "polish", "refine" | Iterative enhancement cycles |
|
||||
| `--safe-mode` | Production, >15 files | Maximum validation |
|
||||
| `--uc` | High context usage | Ultra-compressed output |
|
||||
| `--validate` | Risk detected | Pre-execution validation |
|
||||
| `--think` | 5+ files OR complex analysis | Standard structured analysis (~4K tokens) |
|
||||
| `--think-hard` | Architectural analysis, system dependencies | Deep analysis (~10K tokens) with enhanced tools |
|
||||
| `--ultrathink` | Critical system redesign, legacy modernization | Maximum depth analysis (~32K tokens) with all tools |
|
||||
|
||||
### MCP Server Flags
|
||||
| Flag | Server | Purpose | API Key Required |
|
||||
|------|---------|---------|------------------|
|
||||
| `--c7` | Context7 | Official docs, framework patterns | No |
|
||||
| `--seq` | Sequential | Multi-step reasoning, debugging | No |
|
||||
| `--magic` | Magic | UI component generation | Yes |
|
||||
| `--play` | Playwright | Browser testing, E2E validation | No |
|
||||
| `--morph` | Morphllm | Bulk transformations, pattern edits | Yes |
|
||||
| `--serena` | Serena | Project memory, symbol operations | No |
|
||||
| Flag | Server | Purpose | Auto-Triggers |
|
||||
|------|---------|---------|---------------|
|
||||
| `--c7` / `--context7` | Context7 | Official docs, framework patterns | Library imports, framework questions |
|
||||
| `--seq` / `--sequential` | Sequential | Multi-step reasoning, debugging | Complex debugging, system design |
|
||||
| `--magic` | Magic | UI component generation | `/ui` commands, frontend keywords |
|
||||
| `--play` / `--playwright` | Playwright | Browser testing, E2E validation | Testing requests, visual validation |
|
||||
| `--morph` / `--morphllm` | Morphllm | Bulk transformations, pattern edits | Bulk operations, style enforcement |
|
||||
| `--serena` | Serena | Project memory, symbol operations | Symbol operations, large codebases |
|
||||
|
||||
### Control Flags
|
||||
| Flag | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| `--all-mcp` | Enable all MCP servers | Maximum capability tasks |
|
||||
| `--no-mcp` | Native tools only | Quick operations, testing |
|
||||
| `--scope [file\|module\|project]` | Define analysis boundary | Limit operation scope |
|
||||
| `--focus [security\|performance\|quality]` | Target specific domain | Specialized analysis |
|
||||
### Behavioral Mode Flags
|
||||
| Flag | When Activated | What It Does |
|
||||
|------|---------------|--------------|
|
||||
| `--brainstorm` | Vague requests, exploration keywords | Collaborative discovery mindset |
|
||||
| `--introspect` | Self-analysis, error recovery | Expose reasoning process with transparency |
|
||||
| `--task-manage` | >3 steps, complex scope | Orchestrate through delegation |
|
||||
| `--orchestrate` | Multi-tool operations, performance needs | Optimize tool selection and parallel execution |
|
||||
| `--token-efficient` / `--uc` | Context >75%, efficiency needs | Symbol-enhanced communication, 30-50% reduction |
|
||||
|
||||
## Common Patterns
|
||||
### Execution Control Flags
|
||||
| Flag | When Activated | What It Does |
|
||||
|------|---------------|--------------|
|
||||
| `--loop` | "improve", "polish", "refine" keywords | Iterative enhancement cycles |
|
||||
| `--safe-mode` | Production, >85% resource usage | Maximum validation, conservative execution |
|
||||
| `--validate` | Risk >0.7, production environment | Pre-execution risk assessment |
|
||||
| `--delegate` | >7 directories OR >50 files | Sub-agent parallel processing |
|
||||
|
||||
## Command-Specific Flags
|
||||
|
||||
### Analysis Command Flags (`/sc:analyze`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--focus` | Target specific domain | `security`, `performance`, `quality`, `architecture` |
|
||||
| `--depth` | Analysis thoroughness | `quick`, `deep` |
|
||||
| `--format` | Output format | `text`, `json`, `report` |
|
||||
|
||||
### Build Command Flags (`/sc:build`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Build configuration | `dev`, `prod`, `test` |
|
||||
| `--clean` | Clean before build | Boolean |
|
||||
| `--optimize` | Enable optimizations | Boolean |
|
||||
| `--verbose` | Detailed output | Boolean |
|
||||
|
||||
### Design Command Flags (`/sc:design`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Design target | `architecture`, `api`, `component`, `database` |
|
||||
| `--format` | Output format | `diagram`, `spec`, `code` |
|
||||
|
||||
### Explain Command Flags (`/sc:explain`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--level` | Complexity level | `basic`, `intermediate`, `advanced` |
|
||||
| `--format` | Explanation style | `text`, `examples`, `interactive` |
|
||||
| `--context` | Domain context | Any domain (e.g., `react`, `security`) |
|
||||
|
||||
### Improve Command Flags (`/sc:improve`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Improvement focus | `quality`, `performance`, `maintainability`, `style`, `security` |
|
||||
| `--safe` | Conservative approach | Boolean |
|
||||
| `--interactive` | User guidance | Boolean |
|
||||
| `--preview` | Show without executing | Boolean |
|
||||
|
||||
### Task Command Flags (`/sc:task`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--strategy` | Task approach | `systematic`, `agile`, `enterprise` |
|
||||
| `--parallel` | Parallel execution | Boolean |
|
||||
| `--delegate` | Sub-agent coordination | Boolean |
|
||||
|
||||
### Workflow Command Flags (`/sc:workflow`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--strategy` | Workflow approach | `systematic`, `agile`, `enterprise` |
|
||||
| `--depth` | Analysis depth | `shallow`, `normal`, `deep` |
|
||||
| `--parallel` | Parallel coordination | Boolean |
|
||||
|
||||
### Troubleshoot Command Flags (`/sc:troubleshoot`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Issue category | `bug`, `build`, `performance`, `deployment` |
|
||||
| `--trace` | Include trace analysis | Boolean |
|
||||
| `--fix` | Apply fixes | Boolean |
|
||||
|
||||
### Cleanup Command Flags (`/sc:cleanup`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Cleanup target | `code`, `imports`, `files`, `all` |
|
||||
| `--safe` / `--aggressive` | Cleanup intensity | Boolean |
|
||||
| `--interactive` | User guidance | Boolean |
|
||||
| `--preview` | Show without executing | Boolean |
|
||||
|
||||
### Estimate Command Flags (`/sc:estimate`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Estimate focus | `time`, `effort`, `complexity` |
|
||||
| `--unit` | Time unit | `hours`, `days`, `weeks` |
|
||||
| `--breakdown` | Detailed breakdown | Boolean |
|
||||
|
||||
### Index Command Flags (`/sc:index`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Index target | `docs`, `api`, `structure`, `readme` |
|
||||
| `--format` | Output format | `md`, `json`, `yaml` |
|
||||
|
||||
### Reflect Command Flags (`/sc:reflect`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--type` | Reflection scope | `task`, `session`, `completion` |
|
||||
| `--analyze` | Include analysis | Boolean |
|
||||
| `--validate` | Validate completeness | Boolean |
|
||||
|
||||
### Spawn Command Flags (`/sc:spawn`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--strategy` | Coordination approach | `sequential`, `parallel`, `adaptive` |
|
||||
| `--depth` | Analysis depth | `normal`, `deep` |
|
||||
|
||||
### Git Command Flags (`/sc:git`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--smart-commit` | Generate commit message | Boolean |
|
||||
| `--interactive` | Guided operations | Boolean |
|
||||
|
||||
### Select-Tool Command Flags (`/sc:select-tool`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--analyze` | Tool analysis | Boolean |
|
||||
| `--explain` | Explain selection | Boolean |
|
||||
|
||||
### Test Command Flags (`/sc:test`)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--coverage` | Include coverage | Boolean |
|
||||
| `--type` | Test type | `unit`, `integration`, `e2e` |
|
||||
| `--watch` | Watch mode | Boolean |
|
||||
|
||||
## Advanced Control Flags
|
||||
|
||||
### Scope and Focus
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--scope` | Analysis boundary | `file`, `module`, `project`, `system` |
|
||||
| `--focus` | Domain targeting | `performance`, `security`, `quality`, `architecture`, `accessibility`, `testing` |
|
||||
|
||||
### Execution Control
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--concurrency [n]` | Control parallel ops | 1-15 |
|
||||
| `--iterations [n]` | Improvement cycles | 1-10 |
|
||||
| `--all-mcp` | Enable all MCP servers | Boolean |
|
||||
| `--no-mcp` | Native tools only | Boolean |
|
||||
|
||||
### System Flags (SuperClaude CLI)
|
||||
| Flag | Purpose | Values |
|
||||
|------|---------|--------|
|
||||
| `--verbose` / `-v` | Verbose logging | Boolean |
|
||||
| `--quiet` / `-q` | Suppress output | Boolean |
|
||||
| `--dry-run` | Simulate operation | Boolean |
|
||||
| `--force` | Skip checks | Boolean |
|
||||
| `--yes` / `-y` | Auto-confirm | Boolean |
|
||||
| `--install-dir` | Target directory | Path |
|
||||
| `--legacy` | Use legacy script | Boolean |
|
||||
| `--version` | Show version | Boolean |
|
||||
| `--help` | Show help | Boolean |
|
||||
|
||||
## Common Usage Patterns
|
||||
|
||||
### Frontend Development
|
||||
```bash
|
||||
/sc:implement "responsive dashboard" --magic --c7
|
||||
/sc:design component-library --type component --format code
|
||||
/sc:test ui-components/ --magic --play
|
||||
/sc:improve legacy-ui/ --magic --morph --validate
|
||||
```
|
||||
@@ -44,23 +192,25 @@
|
||||
### Backend Development
|
||||
```bash
|
||||
/sc:analyze api/ --focus performance --seq --think
|
||||
/sc:analyze system/ --think-hard --c7 --scope system
|
||||
/sc:analyze . --focus security --ultrathink --validate
|
||||
/sc:design payment-api --type api --format spec
|
||||
/sc:troubleshoot "API timeout" --type performance --trace
|
||||
/sc:improve auth-service --type security --validate
|
||||
```
|
||||
|
||||
### Large Projects
|
||||
```bash
|
||||
/sc:improve large-codebase/ --delegate --morph --uc
|
||||
/sc:analyze . --ultrathink --all-mcp --safe-mode
|
||||
/sc:analyze . --focus performance --think-hard --loop
|
||||
/sc:workflow enterprise-system --strategy enterprise --depth deep
|
||||
/sc:cleanup . --type all --safe --interactive
|
||||
/sc:estimate "migrate to microservices" --type complexity --breakdown
|
||||
```
|
||||
|
||||
## Manual Override
|
||||
### Quality & Maintenance
|
||||
```bash
|
||||
# Force specific behavior
|
||||
/sc:analyze . --no-mcp # Native tools only
|
||||
/sc:implement feature --ultrathink # Maximum analysis depth
|
||||
/sc:troubleshoot issue --uc # Ultra-compressed output
|
||||
/sc:improve src/ --type quality --safe --interactive
|
||||
/sc:cleanup imports --type imports --preview
|
||||
/sc:reflect --type completion --validate
|
||||
/sc:git commit --smart-commit
|
||||
```
|
||||
|
||||
## Flag Interactions
|
||||
@@ -70,25 +220,51 @@
|
||||
- `--magic` + `--play`: UI generation with testing
|
||||
- `--serena` + `--morph`: Project memory with transformations
|
||||
- `--safe-mode` + `--validate`: Maximum safety
|
||||
- `--loop` + `--validate`: Iterative improvement with validation
|
||||
|
||||
### Conflicting Flags
|
||||
- `--all-mcp` vs individual MCP flags (use one or the other)
|
||||
- `--no-mcp` vs any MCP flags (no-mcp wins)
|
||||
- `--no-mcp` vs any MCP flags (--no-mcp wins)
|
||||
- `--safe` vs `--aggressive` (cleanup intensity)
|
||||
- `--quiet` vs `--verbose` (output level)
|
||||
|
||||
## Troubleshooting
|
||||
### Auto-Enabling Relationships
|
||||
- `--safe-mode` auto-enables `--uc` and `--validate`
|
||||
- `--ultrathink` auto-enables all MCP servers
|
||||
- `--think-hard` auto-enables `--seq` + `--c7`
|
||||
- `--magic` triggers UI-focused agents
|
||||
|
||||
## Troubleshooting Flags
|
||||
|
||||
### Common Issues
|
||||
- **Too many tools**: Use `--no-mcp` to test without MCP servers
|
||||
- **Too many tools**: Use `--no-mcp` to test with native tools only
|
||||
- **Operation too slow**: Add `--uc` to compress output
|
||||
- **Validation blocking**: Use `--validate` instead of `--safe-mode` in development
|
||||
- **Context pressure**: Auto-activates `--token-efficient` at >75% usage
|
||||
|
||||
### Debug Flags
|
||||
```bash
|
||||
/sc:analyze . --verbose # Shows decision logic and flag activation
|
||||
/sc:select-tool "operation" --explain # Explains tool selection process
|
||||
/sc:reflect --type session --analyze # Reviews current session decisions
|
||||
```
|
||||
|
||||
### Quick Fixes
|
||||
```bash
|
||||
/sc:analyze . --help # Should show available flags
|
||||
/sc:analyze . --help # Shows available flags for command
|
||||
/sc:analyze . --no-mcp # Native execution only
|
||||
/sc:analyze . --verbose # Shows decision logic
|
||||
/sc:cleanup . --preview # Shows what would be cleaned
|
||||
```
|
||||
|
||||
## Flag Priority Rules
|
||||
|
||||
1. **Safety First**: `--safe-mode` > `--validate` > optimization flags
|
||||
2. **Explicit Override**: User flags > auto-detection
|
||||
3. **Depth Hierarchy**: `--ultrathink` > `--think-hard` > `--think`
|
||||
4. **MCP Control**: `--no-mcp` overrides all individual MCP flags
|
||||
5. **Scope Precedence**: system > project > module > file
|
||||
|
||||
## Related Resources
|
||||
- [Commands Guide](commands.md) - Commands that use these flags
|
||||
- [MCP Servers Guide](mcp-servers.md) - Understanding MCP flag activation
|
||||
- [MCP Servers Guide](mcp-servers.md) - Understanding MCP flag activation
|
||||
- [Session Management](session-management.md) - Using flags with persistent sessions
|
||||
@@ -1,235 +1,310 @@
|
||||
# SuperClaude Session Management Guide
|
||||
# Session Management Guide
|
||||
|
||||
## ✅ Important Note
|
||||
Sessions are conversation-scoped, not persistent between Claude Code conversations.
|
||||
SuperClaude provides persistent session management through the Serena MCP server, enabling true context preservation across Claude Code conversations and long-term project continuity.
|
||||
|
||||
## Understanding Session Context
|
||||
## Core Session Commands with Persistent Memory
|
||||
|
||||
### What "Sessions" Actually Are
|
||||
### `/sc:load` - Context Loading with Persistent Memory
|
||||
**Purpose**: Initialize session with project context and persistent memory from previous sessions
|
||||
**MCP Integration**: Triggers Serena MCP to read stored project memories
|
||||
**Syntax**: `/sc:load [project_path]`
|
||||
|
||||
**Reality Check**: Claude Code conversations are independent. Each new conversation starts fresh. "Session management" in SuperClaude refers to commands that help Claude understand and work with your project context during a single conversation.
|
||||
|
||||
### What /sc:load and /sc:save Actually Do
|
||||
|
||||
- **`/sc:load`**: Tells Claude to analyze and understand a project structure within the current conversation
|
||||
- **`/sc:save`**: Creates a summary or checkpoint of work done in the current conversation
|
||||
- **`/sc:reflect`**: Reviews what has been discussed/done in the current conversation
|
||||
|
||||
**Important**: These commands DO NOT persist data between Claude Code conversations. Each conversation is isolated.
|
||||
|
||||
## How Context Works in Claude Code
|
||||
|
||||
### Within a Conversation
|
||||
|
||||
During a single Claude Code conversation:
|
||||
- Claude maintains context of what you've discussed
|
||||
- Can refer back to earlier parts of the conversation
|
||||
- Understands the project structure you've shown
|
||||
- Remembers decisions made in this conversation
|
||||
|
||||
### Between Conversations
|
||||
|
||||
When you start a new Claude Code conversation:
|
||||
- Previous conversation context is lost
|
||||
- Must re-explain project context
|
||||
- Previous decisions aren't remembered
|
||||
- Must reload any necessary understanding
|
||||
|
||||
## Session Commands Explained
|
||||
|
||||
### /sc:load - Project Context Loading
|
||||
|
||||
**What it does**: Analyzes project structure and creates mental model
|
||||
**What it doesn't do**: Store anything persistently
|
||||
**What Happens**:
|
||||
- Serena MCP reads persistent memory files from previous sessions
|
||||
- Project context is restored from stored memories
|
||||
- Previous decisions, patterns, and progress are loaded
|
||||
- Session state is initialized with historical context
|
||||
|
||||
**Use Cases**:
|
||||
```bash
|
||||
# Load existing project context from persistent memory
|
||||
/sc:load src/
|
||||
# Claude analyzes the src/ directory structure
|
||||
# Builds understanding for THIS conversation only
|
||||
|
||||
# Resume specific project work with full history
|
||||
/sc:load "authentication-system"
|
||||
|
||||
# Initialize with codebase analysis and previous insights
|
||||
/sc:load . --analyze
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Starting work on an existing project
|
||||
- Helping Claude understand codebase structure
|
||||
- Establishing context for subsequent commands
|
||||
### `/sc:save` - Session Persistence to Memory
|
||||
**Purpose**: Save current session state and decisions to persistent memory
|
||||
**MCP Integration**: Triggers Serena MCP to write memory files
|
||||
**Syntax**: `/sc:save "session_description"`
|
||||
|
||||
### /sc:save - Conversation Summary
|
||||
|
||||
**What it does**: Creates a summary of work done
|
||||
**What it doesn't do**: Actually save for next conversation
|
||||
**What Happens**:
|
||||
- Current context and decisions are written to Serena memory
|
||||
- Project state and progress are persisted across conversations
|
||||
- Key insights and patterns are stored for future sessions
|
||||
- Session summary is created with timestamp for retrieval
|
||||
|
||||
**Use Cases**:
|
||||
```bash
|
||||
/sc:save "refactoring-complete"
|
||||
# Claude summarizes what was accomplished
|
||||
# Useful for you to copy/paste to notes
|
||||
# Does NOT persist for next conversation
|
||||
# Save completed feature work for future reference
|
||||
/sc:save "user authentication implemented with JWT"
|
||||
|
||||
# Checkpoint during complex work
|
||||
/sc:save "API design phase complete, ready for implementation"
|
||||
|
||||
# Store architectural decisions permanently
|
||||
/sc:save "microservices architecture decided, service boundaries defined"
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Creating documentation of work done
|
||||
- Generating summary for your records
|
||||
- Checkpoint before major changes
|
||||
### `/sc:reflect` - Progress Assessment with Memory Context
|
||||
**Purpose**: Analyze current progress against stored memories and validate session completeness
|
||||
**MCP Integration**: Uses Serena MCP to compare current state against stored memories
|
||||
**Syntax**: `/sc:reflect [--scope project|session]`
|
||||
|
||||
### /sc:reflect - Conversation Review
|
||||
|
||||
**What it does**: Reviews current conversation progress
|
||||
**What it doesn't do**: Access previous conversations
|
||||
**What Happens**:
|
||||
- Serena MCP reads previous memories and current context
|
||||
- Progress is assessed against stored goals and milestones
|
||||
- Gaps and next steps are identified using historical context
|
||||
- Session completeness is validated against project memory
|
||||
|
||||
**Use Cases**:
|
||||
```bash
|
||||
# Assess project progress against stored milestones
|
||||
/sc:reflect --scope project
|
||||
|
||||
# Validate current session completeness
|
||||
/sc:reflect
|
||||
# Claude reviews what's been discussed
|
||||
# Summarizes decisions and progress
|
||||
# Only covers current conversation
|
||||
|
||||
# Check if ready to move to next phase based on memory
|
||||
/sc:reflect --scope session
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Mid-conversation status check
|
||||
- Reviewing decisions made
|
||||
- Planning next steps
|
||||
## Persistent Memory Architecture
|
||||
|
||||
## Working Effectively Without Persistence
|
||||
### How Serena MCP Enables True Persistence
|
||||
|
||||
### Starting New Conversations
|
||||
**Memory Storage**:
|
||||
- Session contexts stored as structured memory files
|
||||
- Project decisions and architectural patterns preserved permanently
|
||||
- Code analysis results and insights retained across conversations
|
||||
- Progress tracking and milestone data maintained long-term
|
||||
|
||||
When starting a new Claude Code conversation for continued work:
|
||||
**Cross-Session Continuity**:
|
||||
- Previous session context automatically available in new conversations
|
||||
- Decisions and rationale preserved and accessible across conversations
|
||||
- Learning from past patterns and solutions maintained
|
||||
- Consistent project understanding maintained indefinitely
|
||||
|
||||
1. **Provide Context Again**
|
||||
**Memory Types**:
|
||||
- **Project Memories**: Long-term project context and architecture
|
||||
- **Session Memories**: Specific conversation outcomes and decisions
|
||||
- **Pattern Memories**: Reusable solutions and architectural patterns
|
||||
- **Progress Memories**: Milestone tracking and completion status
|
||||
|
||||
## Session Lifecycle Patterns with Persistence
|
||||
|
||||
### New Project Initialization
|
||||
```bash
|
||||
# 1. Start fresh project
|
||||
/sc:brainstorm "e-commerce platform requirements"
|
||||
|
||||
# 2. Save initial decisions to persistent memory
|
||||
/sc:save "project scope and requirements defined"
|
||||
|
||||
# 3. Begin implementation planning
|
||||
/sc:workflow "user authentication system"
|
||||
|
||||
# 4. Save architectural decisions permanently
|
||||
/sc:save "auth architecture: JWT + refresh tokens + rate limiting"
|
||||
```
|
||||
|
||||
### Resuming Existing Work (Cross-Conversation)
|
||||
```bash
|
||||
# 1. Load previous context from persistent memory
|
||||
/sc:load "e-commerce-project"
|
||||
|
||||
# 2. Assess current state against stored progress
|
||||
/sc:reflect --scope project
|
||||
|
||||
# 3. Continue with next phase using stored context
|
||||
/sc:implement "payment processing integration"
|
||||
|
||||
# 4. Save progress checkpoint to memory
|
||||
/sc:save "payment system integrated with Stripe API"
|
||||
```
|
||||
|
||||
### Long-Term Project Management
|
||||
```bash
|
||||
# Weekly checkpoint pattern with persistence
|
||||
/sc:load project-name
|
||||
/sc:reflect --scope project
|
||||
# ... work on features ...
|
||||
/sc:save "week N progress: features X, Y, Z completed"
|
||||
|
||||
# Phase completion pattern with memory
|
||||
/sc:reflect --scope project
|
||||
/sc:save "Phase 1 complete: core authentication and user management"
|
||||
/sc:workflow "Phase 2: payment and order processing"
|
||||
```
|
||||
|
||||
## Cross-Conversation Continuity
|
||||
|
||||
### Starting New Conversations with Persistence
|
||||
|
||||
When starting a new Claude Code conversation, the persistent memory system allows:
|
||||
|
||||
1. **Automatic Context Restoration**
|
||||
```bash
|
||||
/sc:load project-directory/
|
||||
# Re-establishes project understanding
|
||||
/sc:load project-name
|
||||
# Automatically restores all previous context, decisions, and progress
|
||||
```
|
||||
|
||||
2. **Summarize Previous Work**
|
||||
```
|
||||
"We previously refactored the auth system. Now we need to..."
|
||||
```
|
||||
2. **Progress Continuation**
|
||||
- Previous session decisions are immediately available
|
||||
- Architectural patterns and code insights are preserved
|
||||
- Project history and rationale are maintained
|
||||
|
||||
3. **Reference Key Decisions**
|
||||
```
|
||||
"We're using JWT tokens with refresh tokens, as decided earlier"
|
||||
```
|
||||
3. **Intelligent Context Building**
|
||||
- Serena MCP provides relevant memories based on current work
|
||||
- Past solutions and patterns inform new implementations
|
||||
- Project evolution is tracked and understood
|
||||
|
||||
### Creating Your Own Persistence
|
||||
### Memory Optimization
|
||||
|
||||
Since Claude doesn't persist between conversations, create your own:
|
||||
**Effective Memory Usage**:
|
||||
- Use descriptive, searchable memory names
|
||||
- Include project phase and timestamp context
|
||||
- Reference specific features or architectural decisions
|
||||
- Make future retrieval intuitive
|
||||
|
||||
1. **Project Notes File**
|
||||
```markdown
|
||||
# project-notes.md
|
||||
|
||||
## Session 1 (Date)
|
||||
- Implemented user authentication
|
||||
- Decided on JWT with refresh tokens
|
||||
- Created user model with email validation
|
||||
|
||||
## Session 2 (Date)
|
||||
- Added password reset functionality
|
||||
- Integrated email service
|
||||
```
|
||||
**Memory Content Strategy**:
|
||||
- Store decisions and rationale, not just outcomes
|
||||
- Include alternative approaches considered
|
||||
- Document integration patterns and dependencies
|
||||
- Preserve learning and insights for future reference
|
||||
|
||||
2. **Copy Important Summaries**
|
||||
```bash
|
||||
/sc:save "session-end"
|
||||
# Copy the output to your notes
|
||||
```
|
||||
**Memory Lifecycle Management**:
|
||||
- Regular cleanup of outdated memories
|
||||
- Consolidation of related session memories
|
||||
- Archiving of completed project phases
|
||||
- Pruning of obsolete architectural decisions
|
||||
|
||||
3. **Document Key Decisions**
|
||||
```bash
|
||||
/sc:reflect
|
||||
# Copy important decisions to your documentation
|
||||
```
|
||||
## Best Practices for Persistent Sessions
|
||||
|
||||
## MCP Servers and "Memory"
|
||||
### Session Start Protocol
|
||||
1. Always begin with `/sc:load` for existing projects
|
||||
2. Use `/sc:reflect` to understand current state from memory
|
||||
3. Plan work based on persistent context and stored patterns
|
||||
4. Build on previous decisions and architectural choices
|
||||
|
||||
### Serena MCP Server
|
||||
### Session End Protocol
|
||||
1. Use `/sc:reflect` to assess completeness against stored goals
|
||||
2. Save key decisions with `/sc:save` for future sessions
|
||||
3. Document next steps and open questions in memory
|
||||
4. Preserve context for seamless future continuation
|
||||
|
||||
If Serena MCP is configured, it may provide some project analysis capabilities, but:
|
||||
- Still doesn't persist between Claude conversations
|
||||
- Operates within MCP server constraints
|
||||
- Not true persistent memory
|
||||
### Memory Quality Maintenance
|
||||
- Use clear, descriptive memory names for easy retrieval
|
||||
- Include context about decisions and alternative approaches
|
||||
- Reference specific code locations and patterns
|
||||
- Maintain consistency in memory structure across sessions
|
||||
|
||||
### What MCP Servers Can Do
|
||||
## Integration with Other SuperClaude Features
|
||||
|
||||
- Provide tools for file analysis
|
||||
- Help with project navigation
|
||||
- Enhance Claude's capabilities
|
||||
- But NOT store conversation history
|
||||
### MCP Server Coordination
|
||||
- **Serena MCP**: Provides the persistent memory infrastructure
|
||||
- **Sequential MCP**: Uses stored memories for enhanced complex analysis
|
||||
- **Context7 MCP**: References stored patterns and documentation approaches
|
||||
- **Morphllm MCP**: Applies stored refactoring patterns consistently
|
||||
|
||||
## Best Practices
|
||||
### Agent Collaboration with Memory
|
||||
- Agents access persistent memories for enhanced context
|
||||
- Previous specialist decisions are preserved and referenced
|
||||
- Cross-session agent coordination through shared memory
|
||||
- Consistent specialist recommendations based on project history
|
||||
|
||||
### For Single Conversation
|
||||
### Command Integration with Persistence
|
||||
- All `/sc:` commands can reference and build on persistent context
|
||||
- Previous command outputs and decisions are available across sessions
|
||||
- Workflow patterns are stored and reusable
|
||||
- Implementation history guides future command decisions
|
||||
|
||||
1. **Load Context Early**
|
||||
```bash
|
||||
/sc:load .
|
||||
# Start with full project context
|
||||
```
|
||||
## Troubleshooting Persistent Sessions
|
||||
|
||||
2. **Work Systematically**
|
||||
```bash
|
||||
/sc:workflow "plan the session"
|
||||
# Organize your work
|
||||
```
|
||||
### Common Issues
|
||||
|
||||
3. **Save Summaries**
|
||||
```bash
|
||||
/sc:save "checkpoint-1"
|
||||
# Create summaries as you go
|
||||
```
|
||||
**Memory Not Loading**:
|
||||
- Verify Serena MCP is configured and running properly
|
||||
- Check memory file permissions and accessibility
|
||||
- Ensure consistent project naming conventions
|
||||
- Validate memory file integrity and format
|
||||
|
||||
### For Multiple Conversations
|
||||
**Context Loss Between Sessions**:
|
||||
- Always use `/sc:save` before ending sessions
|
||||
- Use descriptive memory names for easy retrieval
|
||||
- Regular `/sc:reflect` to validate memory completeness
|
||||
- Backup important memory files periodically
|
||||
|
||||
1. **Maintain External Notes**
|
||||
- Keep a project journal
|
||||
- Document decisions
|
||||
- Track progress
|
||||
**Memory Conflicts**:
|
||||
- Use timestamped memory names for version control
|
||||
- Regular cleanup of obsolete memories
|
||||
- Clear separation between project and session memories
|
||||
- Consistent memory naming conventions across sessions
|
||||
|
||||
2. **Create Context Files**
|
||||
```markdown
|
||||
# .claude-context.md
|
||||
Project context for Claude Code sessions
|
||||
- Architecture: microservices
|
||||
- Database: PostgreSQL
|
||||
- Auth: JWT with refresh tokens
|
||||
```
|
||||
### Quick Fixes
|
||||
|
||||
3. **Start Consistently**
|
||||
```bash
|
||||
# At start of each conversation:
|
||||
/sc:load .
|
||||
"Please read .claude-context.md for project decisions"
|
||||
```
|
||||
**Reset Session State**:
|
||||
```bash
|
||||
/sc:load --fresh # Start without previous context
|
||||
/sc:reflect # Assess current state
|
||||
```
|
||||
|
||||
## Common Misconceptions
|
||||
**Memory Cleanup**:
|
||||
```bash
|
||||
/sc:reflect --cleanup # Remove obsolete memories
|
||||
/sc:save --consolidate # Merge related memories
|
||||
```
|
||||
|
||||
### ❌ Myth: Sessions Persist
|
||||
**Reality**: Each Claude conversation is independent
|
||||
**Context Recovery**:
|
||||
```bash
|
||||
/sc:load --recent # Load most recent memories
|
||||
/sc:reflect --repair # Identify and fix context gaps
|
||||
```
|
||||
|
||||
### ❌ Myth: /sc:save Stores Data
|
||||
**Reality**: It creates a summary for you to copy
|
||||
## Advanced Persistent Session Patterns
|
||||
|
||||
### ❌ Myth: /sc:load Remembers Previous Work
|
||||
**Reality**: It analyzes current files only
|
||||
### Multi-Phase Projects
|
||||
- Use phase-specific memory naming for organization
|
||||
- Maintain architectural decision continuity across phases
|
||||
- Cross-phase dependency tracking through persistent memory
|
||||
- Progressive complexity management with historical context
|
||||
|
||||
### ❌ Myth: Serena Provides Memory
|
||||
**Reality**: MCP tools work within conversation scope
|
||||
### Team Collaboration
|
||||
- Shared memory conventions and naming standards
|
||||
- Decision rationale preservation for team context
|
||||
- Integration pattern documentation accessible to all team members
|
||||
- Consistent code style and architecture enforcement through memory
|
||||
|
||||
## Troubleshooting
|
||||
### Long-Term Maintenance
|
||||
- Memory archiving strategies for completed projects
|
||||
- Pattern library development through accumulated memories
|
||||
- Reusable solution documentation built over time
|
||||
- Knowledge base building through persistent memory accumulation
|
||||
|
||||
### "Claude doesn't remember our previous conversation"
|
||||
**Expected behavior**: Claude Code conversations don't persist
|
||||
**Solution**: Provide context at start of new conversation
|
||||
## Key Benefits of Persistent Session Management
|
||||
|
||||
### "/sc:load isn't loading previous session"
|
||||
**Expected behavior**: It loads project files, not session history
|
||||
**Solution**: Maintain your own project notes
|
||||
### Project Continuity
|
||||
- Seamless work continuation across multiple conversations
|
||||
- No context loss between Claude Code sessions
|
||||
- Preserved architectural decisions and technical rationale
|
||||
- Long-term project evolution tracking
|
||||
|
||||
### "/sc:save doesn't actually save"
|
||||
**Expected behavior**: Creates summary text only
|
||||
**Solution**: Copy output to your own notes
|
||||
### Enhanced Productivity
|
||||
- Reduced need to re-explain project context
|
||||
- Faster startup time for continued work
|
||||
- Building on previous insights and patterns
|
||||
- Cumulative project knowledge growth
|
||||
|
||||
## Summary
|
||||
### Quality Consistency
|
||||
- Consistent architectural patterns across sessions
|
||||
- Preserved code quality decisions and standards
|
||||
- Reusable solutions and best practices
|
||||
- Maintained technical debt awareness
|
||||
|
||||
SuperClaude's "session management" commands are tools for managing context within a single Claude Code conversation. They help Claude understand your project and track progress during the current conversation, but do not provide persistence between conversations.
|
||||
---
|
||||
|
||||
For true continuity across multiple conversations, maintain your own documentation and provide context at the start of each new conversation. Think of these commands as conversation helpers, not database operations.
|
||||
**Key Takeaway**: Session management through Serena MCP transforms SuperClaude from single-conversation assistance to persistent project partnership, maintaining context, decisions, and learning across all development phases and Claude Code conversations.
|
||||
Reference in New Issue
Block a user