External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

📚 Major documentation improvements and corrections

Browse Source 
- 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
2025-08-22 20:09:27 +02:00
parent 850e5a69a6
commit 886323b240
9 changed files with 562 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -191,3 +191,7 @@ ehthumbs.db
Thumbs.db Thumbs.db
Desktop.ini Desktop.ini
$RECYCLE.BIN/ $RECYCLE.BIN/
# Personal files
CRUSH.md
TODO.txt

108
Docs/Developer-Guide/technical-architecture.md
View File

@@ -22,27 +22,64 @@ This guide documents how SuperClaude's Context-Oriented Configuration Framework
### Directory Structure ### Directory Structure
``` ```
~/.claude/ # Claude Code's configuration directory ~/.claude/ (SuperClaude Framework Files Only)
├── CLAUDE.md # Main context file with imports ├── CLAUDE.md # Main context file with imports
├── FLAGS.md # Flag definitions and triggers ├── FLAGS.md # Flag definitions and triggers
├── RULES.md # Core behavioral rules ├── RULES.md # Core behavioral rules
├── PRINCIPLES.md # Guiding principles ├── PRINCIPLES.md # Guiding principles
├── agents/ # Domain specialist contexts ├── ZIG.md # Zig language integration
│ ├── backend-architect.md # Backend expertise ├── MCP_Context7.md # Context7 MCP integration
│ ├── frontend-architect.md # Frontend expertise ├── MCP_Magic.md # Magic MCP integration
│ ├── security-engineer.md # Security expertise ├── MCP_Morphllm.md # Morphllm MCP integration
│ ├── python-expert.md # Python expertise ├── MCP_Playwright.md # Playwright MCP integration
│ └── ... (13 total agents) ├── MCP_Sequential.md # Sequential MCP integration
├── commands/ # Workflow pattern contexts ├── MCP_Serena.md # Serena MCP integration
│ ├── implement.md # Implementation patterns ├── MCP_Zig.md # Zig MCP integration
│ ├── analyze.md # Analysis patterns ├── MODE_Brainstorming.md # Collaborative discovery mode
│ ├── brainstorm.md # Discovery patterns ├── MODE_Introspection.md # Transparent reasoning mode
│ └── ... (21 total commands) ├── MODE_Orchestration.md # Tool coordination mode
└── modes/ # Behavioral modification contexts ├── MODE_Task_Management.md # Task orchestration mode
├── MODE_Brainstorming.md # Collaborative discovery ├── MODE_Token_Efficiency.md # Compressed communication mode
├── MODE_Introspection.md # Transparent reasoning ├── agents/ # Domain specialist contexts (13 total)
├── MODE_Task_Management.md # Task orchestration │ ├── backend-architect.md # Backend expertise
└── ... (6 total modes) │ ├── devops-architect.md # DevOps expertise
│ ├── frontend-architect.md # Frontend expertise
│ ├── learning-guide.md # Educational expertise
│ ├── performance-engineer.md # Performance expertise
│ ├── python-expert.md # Python expertise
│ ├── quality-engineer.md # Quality assurance expertise
│ ├── refactoring-expert.md # Code quality expertise
│ ├── requirements-analyst.md # Requirements expertise
│ ├── root-cause-analyst.md # Problem diagnosis expertise
│ ├── security-engineer.md # Security expertise
│ ├── system-architect.md # System design expertise
│ └── technical-writer.md # Documentation expertise
└── commands/ # Workflow pattern contexts
└── sc/ # SuperClaude command namespace (21 total)
├── analyze.md # Analysis patterns
├── brainstorm.md # Discovery patterns
├── build.md # Build patterns
├── cleanup.md # Cleanup patterns
├── design.md # Design patterns
├── document.md # Documentation patterns
├── estimate.md # Estimation patterns
├── explain.md # Explanation patterns
├── git.md # Git workflow patterns
├── implement.md # Implementation patterns
├── improve.md # Improvement patterns
├── index.md # Index patterns
├── load.md # Context loading patterns
├── reflect.md # Reflection patterns
├── save.md # Session persistence patterns
├── select-tool.md # Tool selection patterns
├── spawn.md # Multi-agent patterns
├── task.md # Task management patterns
├── test.md # Testing patterns
├── troubleshoot.md # Troubleshooting patterns
└── workflow.md # Workflow planning patterns
Note: Other directories (backups/, logs/, projects/, serena/, etc.) are Claude Code
operational directories, not part of SuperClaude framework content.
``` ```
### Context File Types ### Context File Types
@@ -61,13 +98,28 @@ This guide documents how SuperClaude's Context-Oriented Configuration Framework
The main `CLAUDE.md` file uses an import system to load multiple context files: The main `CLAUDE.md` file uses an import system to load multiple context files:
```markdown ```markdown
# CLAUDE.md structure # CLAUDE
@import commands/*.md # Loads all command patterns
@import agents/*.md # Loads all agent contexts *MANDATORY*
@import modes/*.md # Loads all behavioral modes @FLAGS.md # Flag definitions and triggers
@import FLAGS.md # Loads flag definitions @RULES.md # Core behavioral rules
@import RULES.md # Loads core rules @PRINCIPLES.md # Guiding principles
@import PRINCIPLES.md # Loads guiding principles *SECONDARY*
@MCP_Context7.md # Context7 MCP integration
@MCP_Magic.md # Magic MCP integration
@MCP_Morphllm.md # Morphllm MCP integration
@MCP_Playwright.md # Playwright MCP integration
@MCP_Sequential.md # Sequential MCP integration
@MCP_Serena.md # Serena MCP integration
@MCP_Zig.md # Zig MCP integration
*CRITICAL*
@MODE_Brainstorming.md # Collaborative discovery mode
@MODE_Introspection.md # Transparent reasoning mode
@MODE_Task_Management.md # Task orchestration mode
@MODE_Orchestration.md # Tool coordination mode
@MODE_Token_Efficiency.md # Compressed communication mode
*LANGUAGE SPECIFIC*
@ZIG.md # Zig language integration
``` ```
### Import Processing ### Import Processing
@@ -152,7 +204,7 @@ Practical usage examples
### Command Processing ### Command Processing
When user types `/sc:implement "feature"` in Claude Code conversation: When user types `/sc:implement "feature"` in Claude Code conversation:
1. Claude reads `commands/implement.md` 1. Claude reads `commands/sc/implement.md`
2. Adopts implementation workflow pattern 2. Adopts implementation workflow pattern
3. May auto-activate related agents 3. May auto-activate related agents
4. Follows defined workflow steps 4. Follows defined workflow steps
@@ -217,7 +269,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security"
↓ ↓
1. Parse Command: identify 'analyze' command 1. Parse Command: identify 'analyze' command
↓ ↓
2. Load Context: read commands/analyze.md 2. Load Context: read commands/sc/analyze.md
↓ ↓
3. Check Flags: --focus security 3. Check Flags: --focus security
↓ ↓
@@ -240,7 +292,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security"
### Adding New Commands ### Adding New Commands
1. Create `~/.claude/commands/new-command.md` 1. Create `~/.claude/commands/sc/new-command.md`
2. Define metadata, triggers, and workflow 2. Define metadata, triggers, and workflow
3. No code changes needed - just context 3. No code changes needed - just context
@@ -252,7 +304,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security"
### Adding New Modes ### Adding New Modes
1. Create `~/.claude/modes/MODE_NewMode.md` 1. Create `~/.claude/MODE_NewMode.md`
2. Define activation triggers and modifications 2. Define activation triggers and modifications
3. Mode activates based on triggers 3. Mode activates based on triggers

4
Docs/Developer-Guide/testing-debugging.md
View File

@@ -53,13 +53,13 @@ done
### Count Installed Components ### Count Installed Components
```bash ```bash
# Should have 13 agents # Should have 14 agents
ls ~/.claude/agents/*.md | wc -l ls ~/.claude/agents/*.md | wc -l
# Should have 21 commands # Should have 21 commands
ls ~/.claude/commands/*.md | wc -l ls ~/.claude/commands/*.md | wc -l
# Should have 6+ modes # Should have 5 modes
ls ~/.claude/modes/*.md | wc -l ls ~/.claude/modes/*.md | wc -l
``` ```

4
Docs/Getting-Started/quick-start.md
View File

@@ -52,8 +52,8 @@ pip install SuperClaude && SuperClaude install
SuperClaude enhances Claude Code with: SuperClaude enhances Claude Code with:
**21 Slash Commands** for workflow automation (/sc:brainstorm, /sc:implement, /sc:analyze) **21 Slash Commands** for workflow automation (/sc:brainstorm, /sc:implement, /sc:analyze)
**13 AI Specialists** with domain expertise (@agent-architect, @agent-security, @agent-frontend) **14 AI Specialists** with domain expertise (@agent-architect, @agent-security, @agent-frontend)
**6 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration) **5 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration)
**6 MCP Servers** for enhanced capabilities (Context7, Sequential, Magic, Playwright) **6 MCP Servers** for enhanced capabilities (Context7, Sequential, Magic, Playwright)
**Important**: The `.md` files in `SuperClaude/` directory are NOT documentation - they are the actual context framework instructions that Claude Code reads to enhance its capabilities. **Important**: The `.md` files in `SuperClaude/` directory are NOT documentation - they are the actual context framework instructions that Claude Code reads to enhance its capabilities.

12
Docs/README.md
View File

@@ -24,10 +24,10 @@ pip install SuperClaude && SuperClaude install
### 🌱 Start Here (New Users) ### 🌱 Start Here (New Users)
| Guide | Purpose | | Guide | Purpose |
|-------|---------|------| |-------|---------|
| **[Quick Start](Getting-Started/quick-start.md)** | Setup and first commands | | | **[Quick Start](Getting-Started/quick-start.md)** | Setup and first commands |
| **[Installation](Getting-Started/installation.md)** | Detailed setup instructions | | | **[Installation](Getting-Started/installation.md)** | Detailed setup instructions |
| **[Commands Guide](User-Guide/commands.md)** | All 21 `/sc:` commands | | | **[Commands Guide](User-Guide/commands.md)** | All 21 `/sc:` commands |
### 🌿 Daily Usage (Regular Users) ### 🌿 Daily Usage (Regular Users)
| Guide | Purpose | Use For | | Guide | Purpose | Use For |
@@ -59,8 +59,8 @@ pip install SuperClaude && SuperClaude install
### Framework Components ### Framework Components
- **21 Commands** (`/sc:*`) - Workflow automation patterns - **21 Commands** (`/sc:*`) - Workflow automation patterns
- **15 Agents** (`@agent-*`) - Domain specialists - **14 Agents** (`@agent-*`) - Domain specialists
- **6 Modes** - Behavioral modification patterns - **5 Modes** - Behavioral modification patterns
- **6 MCP Servers** - Optional external tools - **6 MCP Servers** - Optional external tools
## 🚀 Quick Command Reference ## 🚀 Quick Command Reference

5
Docs/User-Guide/agents.md
View File

@@ -2,11 +2,6 @@
SuperClaude provides 14 domain specialist agents that Claude Code can invoke for specialized expertise. 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 ## 🧪 Testing Agent Activation

5
Docs/User-Guide/commands.md
View File

@@ -58,11 +58,6 @@ SuperClaude provides behavioral context files that Claude Code reads to adopt sp
- `@agent-security` - Activates security specialist context - `@agent-security` - Activates security specialist context
- All commands work inside Claude Code chat interface only - 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. > **Quick Start**: Try `/sc:brainstorm "your project idea"` → `/sc:implement "feature name"` → `/sc:test` to experience the core workflow.

252
Docs/User-Guide/flags.md
View File

@@ -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. **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 | | Flag | When Activated | What It Does |
|------|---------------|--------------| |------|---------------|--------------|
| `--think` | 5+ files OR complex analysis | Standard structured analysis | | `--think` | 5+ files OR complex analysis | Standard structured analysis (~4K tokens) |
| `--magic` | UI components, frontend | Modern UI generation | | `--think-hard` | Architectural analysis, system dependencies | Deep analysis (~10K tokens) with enhanced tools |
| `--loop` | "improve", "polish", "refine" | Iterative enhancement cycles | | `--ultrathink` | Critical system redesign, legacy modernization | Maximum depth analysis (~32K tokens) with all tools |
| `--safe-mode` | Production, >15 files | Maximum validation |
| `--uc` | High context usage | Ultra-compressed output |
| `--validate` | Risk detected | Pre-execution validation |
### MCP Server Flags ### MCP Server Flags
| Flag | Server | Purpose | API Key Required | | Flag | Server | Purpose | Auto-Triggers |
|------|---------|---------|------------------| |------|---------|---------|---------------|
| `--c7` | Context7 | Official docs, framework patterns | No | | `--c7` / `--context7` | Context7 | Official docs, framework patterns | Library imports, framework questions |
| `--seq` | Sequential | Multi-step reasoning, debugging | No | | `--seq` / `--sequential` | Sequential | Multi-step reasoning, debugging | Complex debugging, system design |
| `--magic` | Magic | UI component generation | Yes | | `--magic` | Magic | UI component generation | `/ui` commands, frontend keywords |
| `--play` | Playwright | Browser testing, E2E validation | No | | `--play` / `--playwright` | Playwright | Browser testing, E2E validation | Testing requests, visual validation |
| `--morph` | Morphllm | Bulk transformations, pattern edits | Yes | | `--morph` / `--morphllm` | Morphllm | Bulk transformations, pattern edits | Bulk operations, style enforcement |
| `--serena` | Serena | Project memory, symbol operations | No | | `--serena` | Serena | Project memory, symbol operations | Symbol operations, large codebases |
### Control Flags ### Behavioral Mode Flags
| Flag | Purpose | Example | | Flag | When Activated | What It Does |
|------|---------|---------| |------|---------------|--------------|
| `--all-mcp` | Enable all MCP servers | Maximum capability tasks | | `--brainstorm` | Vague requests, exploration keywords | Collaborative discovery mindset |
| `--no-mcp` | Native tools only | Quick operations, testing | | `--introspect` | Self-analysis, error recovery | Expose reasoning process with transparency |
| `--scope [file\|module\|project]` | Define analysis boundary | Limit operation scope | | `--task-manage` | >3 steps, complex scope | Orchestrate through delegation |
| `--focus [security\|performance\|quality]` | Target specific domain | Specialized analysis | | `--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 ### Frontend Development
```bash ```bash
/sc:implement "responsive dashboard" --magic --c7 /sc:implement "responsive dashboard" --magic --c7
/sc:design component-library --type component --format code
/sc:test ui-components/ --magic --play /sc:test ui-components/ --magic --play
/sc:improve legacy-ui/ --magic --morph --validate /sc:improve legacy-ui/ --magic --morph --validate
``` ```
@@ -44,23 +192,25 @@
### Backend Development ### Backend Development
```bash ```bash
/sc:analyze api/ --focus performance --seq --think /sc:analyze api/ --focus performance --seq --think
/sc:analyze system/ --think-hard --c7 --scope system /sc:design payment-api --type api --format spec
/sc:analyze . --focus security --ultrathink --validate /sc:troubleshoot "API timeout" --type performance --trace
/sc:improve auth-service --type security --validate
``` ```
### Large Projects ### Large Projects
```bash ```bash
/sc:improve large-codebase/ --delegate --morph --uc
/sc:analyze . --ultrathink --all-mcp --safe-mode /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 ```bash
# Force specific behavior /sc:improve src/ --type quality --safe --interactive
/sc:analyze . --no-mcp # Native tools only /sc:cleanup imports --type imports --preview
/sc:implement feature --ultrathink # Maximum analysis depth /sc:reflect --type completion --validate
/sc:troubleshoot issue --uc # Ultra-compressed output /sc:git commit --smart-commit
``` ```
## Flag Interactions ## Flag Interactions
@@ -70,25 +220,51 @@
- `--magic` + `--play`: UI generation with testing - `--magic` + `--play`: UI generation with testing
- `--serena` + `--morph`: Project memory with transformations - `--serena` + `--morph`: Project memory with transformations
- `--safe-mode` + `--validate`: Maximum safety - `--safe-mode` + `--validate`: Maximum safety
- `--loop` + `--validate`: Iterative improvement with validation
### Conflicting Flags ### Conflicting Flags
- `--all-mcp` vs individual MCP flags (use one or the other) - `--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 ### 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 - **Operation too slow**: Add `--uc` to compress output
- **Validation blocking**: Use `--validate` instead of `--safe-mode` in development - **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 ### Quick Fixes
```bash ```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 . --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 ## Related Resources
- [Commands Guide](commands.md) - Commands that use these flags - [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

427
Docs/User-Guide/session-management.md
View File

@@ -1,235 +1,310 @@
# SuperClaude Session Management Guide # Session Management Guide
## ✅ Important Note SuperClaude provides persistent session management through the Serena MCP server, enabling true context preservation across Claude Code conversations and long-term project continuity.
Sessions are conversation-scoped, not persistent between Claude Code conversations.
## 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 Happens**:
- Serena MCP reads persistent memory files from previous sessions
### What /sc:load and /sc:save Actually Do - Project context is restored from stored memories
- Previous decisions, patterns, and progress are loaded
- **`/sc:load`**: Tells Claude to analyze and understand a project structure within the current conversation - Session state is initialized with historical context
- **`/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
**Use Cases**:
```bash ```bash
# Load existing project context from persistent memory
/sc:load src/ /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**: ### `/sc:save` - Session Persistence to Memory
- Starting work on an existing project **Purpose**: Save current session state and decisions to persistent memory
- Helping Claude understand codebase structure **MCP Integration**: Triggers Serena MCP to write memory files
- Establishing context for subsequent commands **Syntax**: `/sc:save "session_description"`
### /sc:save - Conversation Summary **What Happens**:
- Current context and decisions are written to Serena memory
**What it does**: Creates a summary of work done - Project state and progress are persisted across conversations
**What it doesn't do**: Actually save for next conversation - Key insights and patterns are stored for future sessions
- Session summary is created with timestamp for retrieval
**Use Cases**:
```bash ```bash
/sc:save "refactoring-complete" # Save completed feature work for future reference
# Claude summarizes what was accomplished /sc:save "user authentication implemented with JWT"
# Useful for you to copy/paste to notes
# Does NOT persist for next conversation # 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**: ### `/sc:reflect` - Progress Assessment with Memory Context
- Creating documentation of work done **Purpose**: Analyze current progress against stored memories and validate session completeness
- Generating summary for your records **MCP Integration**: Uses Serena MCP to compare current state against stored memories
- Checkpoint before major changes **Syntax**: `/sc:reflect [--scope project|session]`
### /sc:reflect - Conversation Review **What Happens**:
- Serena MCP reads previous memories and current context
**What it does**: Reviews current conversation progress - Progress is assessed against stored goals and milestones
**What it doesn't do**: Access previous conversations - Gaps and next steps are identified using historical context
- Session completeness is validated against project memory
**Use Cases**:
```bash ```bash
# Assess project progress against stored milestones
/sc:reflect --scope project
# Validate current session completeness
/sc:reflect /sc:reflect
# Claude reviews what's been discussed
# Summarizes decisions and progress # Check if ready to move to next phase based on memory
# Only covers current conversation /sc:reflect --scope session
``` ```
**Use cases**: ## Persistent Memory Architecture
- Mid-conversation status check
- Reviewing decisions made
- Planning next steps
## 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 ```bash
/sc:load project-directory/ /sc:load project-name
# Re-establishes project understanding # Automatically restores all previous context, decisions, and progress
``` ```
2. **Summarize Previous Work** 2. **Progress Continuation**
``` - Previous session decisions are immediately available
"We previously refactored the auth system. Now we need to..." - Architectural patterns and code insights are preserved
``` - Project history and rationale are maintained
3. **Reference Key Decisions** 3. **Intelligent Context Building**
``` - Serena MCP provides relevant memories based on current work
"We're using JWT tokens with refresh tokens, as decided earlier" - 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** **Memory Content Strategy**:
```markdown - Store decisions and rationale, not just outcomes
# project-notes.md - Include alternative approaches considered
- Document integration patterns and dependencies
- Preserve learning and insights for future reference
## Session 1 (Date) **Memory Lifecycle Management**:
- Implemented user authentication - Regular cleanup of outdated memories
- Decided on JWT with refresh tokens - Consolidation of related session memories
- Created user model with email validation - Archiving of completed project phases
- Pruning of obsolete architectural decisions
## Session 2 (Date) ## Best Practices for Persistent Sessions
- Added password reset functionality
- Integrated email service
```
2. **Copy Important Summaries** ### Session Start Protocol
```bash 1. Always begin with `/sc:load` for existing projects
/sc:save "session-end" 2. Use `/sc:reflect` to understand current state from memory
# Copy the output to your notes 3. Plan work based on persistent context and stored patterns
``` 4. Build on previous decisions and architectural choices
3. **Document Key Decisions** ### Session End Protocol
```bash 1. Use `/sc:reflect` to assess completeness against stored goals
/sc:reflect 2. Save key decisions with `/sc:save` for future sessions
# Copy important decisions to your documentation 3. Document next steps and open questions in memory
``` 4. Preserve context for seamless future continuation
## MCP Servers and "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
### Serena MCP Server ## Integration with Other SuperClaude Features
If Serena MCP is configured, it may provide some project analysis capabilities, but: ### MCP Server Coordination
- Still doesn't persist between Claude conversations - **Serena MCP**: Provides the persistent memory infrastructure
- Operates within MCP server constraints - **Sequential MCP**: Uses stored memories for enhanced complex analysis
- Not true persistent memory - **Context7 MCP**: References stored patterns and documentation approaches
- **Morphllm MCP**: Applies stored refactoring patterns consistently
### What MCP Servers Can Do ### 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
- Provide tools for file analysis ### Command Integration with Persistence
- Help with project navigation - All `/sc:` commands can reference and build on persistent context
- Enhance Claude's capabilities - Previous command outputs and decisions are available across sessions
- But NOT store conversation history - Workflow patterns are stored and reusable
- Implementation history guides future command decisions
## Best Practices ## Troubleshooting Persistent Sessions
### For Single Conversation ### Common Issues
1. **Load Context Early** **Memory Not Loading**:
```bash - Verify Serena MCP is configured and running properly
/sc:load . - Check memory file permissions and accessibility
# Start with full project context - Ensure consistent project naming conventions
``` - Validate memory file integrity and format
2. **Work Systematically** **Context Loss Between Sessions**:
```bash - Always use `/sc:save` before ending sessions
/sc:workflow "plan the session" - Use descriptive memory names for easy retrieval
# Organize your work - Regular `/sc:reflect` to validate memory completeness
``` - Backup important memory files periodically
3. **Save Summaries** **Memory Conflicts**:
```bash - Use timestamped memory names for version control
/sc:save "checkpoint-1" - Regular cleanup of obsolete memories
# Create summaries as you go - Clear separation between project and session memories
``` - Consistent memory naming conventions across sessions
### For Multiple Conversations ### Quick Fixes
1. **Maintain External Notes** **Reset Session State**:
- Keep a project journal ```bash
- Document decisions /sc:load --fresh # Start without previous context
- Track progress /sc:reflect # Assess current state
```
2. **Create Context Files** **Memory Cleanup**:
```markdown ```bash
# .claude-context.md /sc:reflect --cleanup # Remove obsolete memories
Project context for Claude Code sessions /sc:save --consolidate # Merge related memories
- Architecture: microservices ```
- Database: PostgreSQL
- Auth: JWT with refresh tokens
```
3. **Start Consistently** **Context Recovery**:
```bash ```bash
# At start of each conversation: /sc:load --recent # Load most recent memories
/sc:load . /sc:reflect --repair # Identify and fix context gaps
"Please read .claude-context.md for project decisions" ```
```
## Common Misconceptions ## Advanced Persistent Session Patterns
### ❌ Myth: Sessions Persist ### Multi-Phase Projects
**Reality**: Each Claude conversation is independent - 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: /sc:save Stores Data ### Team Collaboration
**Reality**: It creates a summary for you to copy - 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
### ❌ Myth: /sc:load Remembers Previous Work ### Long-Term Maintenance
**Reality**: It analyzes current files only - 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
### ❌ Myth: Serena Provides Memory ## Key Benefits of Persistent Session Management
**Reality**: MCP tools work within conversation scope
## Troubleshooting ### 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
### "Claude doesn't remember our previous conversation" ### Enhanced Productivity
**Expected behavior**: Claude Code conversations don't persist - Reduced need to re-explain project context
**Solution**: Provide context at start of new conversation - Faster startup time for continued work
- Building on previous insights and patterns
- Cumulative project knowledge growth
### "/sc:load isn't loading previous session" ### Quality Consistency
**Expected behavior**: It loads project files, not session history - Consistent architectural patterns across sessions
**Solution**: Maintain your own project notes - Preserved code quality decisions and standards
- Reusable solutions and best practices
- Maintained technical debt awareness
### "/sc:save doesn't actually save" ---
**Expected behavior**: Creates summary text only
**Solution**: Copy output to your own notes
## Summary **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.
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.