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

6
.gitignore vendored
View File

@@ -190,4 +190,8 @@ changelog-temp/
ehthumbs.db ehthumbs.db
Thumbs.db Thumbs.db
Desktop.ini Desktop.ini
$RECYCLE.BIN/ $RECYCLE.BIN/
# Personal files
CRUSH.md
TODO.txt

110
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.

254
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
## Session 1 (Date) - Preserve learning and insights for future reference
- 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
```
2. **Copy Important Summaries** **Memory Lifecycle Management**:
```bash - Regular cleanup of outdated memories
/sc:save "session-end" - Consolidation of related session memories
# Copy the output to your notes - Archiving of completed project phases
``` - Pruning of obsolete architectural decisions
3. **Document Key Decisions** ## Best Practices for Persistent Sessions
```bash
/sc:reflect
# Copy important decisions to your documentation
```
## 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: ### Memory Quality Maintenance
- Still doesn't persist between Claude conversations - Use clear, descriptive memory names for easy retrieval
- Operates within MCP server constraints - Include context about decisions and alternative approaches
- Not true persistent memory - 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 ### MCP Server Coordination
- Help with project navigation - **Serena MCP**: Provides the persistent memory infrastructure
- Enhance Claude's capabilities - **Sequential MCP**: Uses stored memories for enhanced complex analysis
- But NOT store conversation history - **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** ## Troubleshooting Persistent Sessions
```bash
/sc:load .
# Start with full project context
```
2. **Work Systematically** ### Common Issues
```bash
/sc:workflow "plan the session"
# Organize your work
```
3. **Save Summaries** **Memory Not Loading**:
```bash - Verify Serena MCP is configured and running properly
/sc:save "checkpoint-1" - Check memory file permissions and accessibility
# Create summaries as you go - 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** **Memory Conflicts**:
- Keep a project journal - Use timestamped memory names for version control
- Document decisions - Regular cleanup of obsolete memories
- Track progress - Clear separation between project and session memories
- Consistent memory naming conventions across sessions
2. **Create Context Files** ### Quick Fixes
```markdown
# .claude-context.md
Project context for Claude Code sessions
- Architecture: microservices
- Database: PostgreSQL
- Auth: JWT with refresh tokens
```
3. **Start Consistently** **Reset Session State**:
```bash ```bash
# At start of each conversation: /sc:load --fresh # Start without previous context
/sc:load . /sc:reflect # Assess current state
"Please read .claude-context.md for project decisions" ```
```
## Common Misconceptions **Memory Cleanup**:
```bash
/sc:reflect --cleanup # Remove obsolete memories
/sc:save --consolidate # Merge related memories
```
### ❌ Myth: Sessions Persist **Context Recovery**:
**Reality**: Each Claude conversation is independent ```bash
/sc:load --recent # Load most recent memories
/sc:reflect --repair # Identify and fix context gaps
```
### ❌ Myth: /sc:save Stores Data ## Advanced Persistent Session Patterns
**Reality**: It creates a summary for you to copy
### ❌ Myth: /sc:load Remembers Previous Work ### Multi-Phase Projects
**Reality**: It analyzes current files only - 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 ### Team Collaboration
**Reality**: MCP tools work within conversation scope - 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" ## Key Benefits of Persistent Session Management
**Expected behavior**: Claude Code conversations don't persist
**Solution**: Provide context at start of new conversation
### "/sc:load isn't loading previous session" ### Project Continuity
**Expected behavior**: It loads project files, not session history - Seamless work continuation across multiple conversations
**Solution**: Maintain your own project notes - No context loss between Claude Code sessions
- Preserved architectural decisions and technical rationale
- Long-term project evolution tracking
### "/sc:save doesn't actually save" ### Enhanced Productivity
**Expected behavior**: Creates summary text only - Reduced need to re-explain project context
**Solution**: Copy output to your own notes - 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.