From 886323b24029bebee709cd28a3b2c66c842448dc Mon Sep 17 00:00:00 2001 From: NomenAK Date: Fri, 22 Aug 2025 20:09:27 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Major=20documentation=20improvem?= =?UTF-8?q?ents=20and=20corrections?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .gitignore | 6 +- .../Developer-Guide/technical-architecture.md | 110 +++-- Docs/Developer-Guide/testing-debugging.md | 4 +- Docs/Getting-Started/quick-start.md | 4 +- Docs/README.md | 12 +- Docs/User-Guide/agents.md | 5 - Docs/User-Guide/commands.md | 5 - Docs/User-Guide/flags.md | 254 +++++++++-- Docs/User-Guide/session-management.md | 427 ++++++++++-------- 9 files changed, 562 insertions(+), 265 deletions(-) diff --git a/.gitignore b/.gitignore index dad5c8b..a70c525 100644 --- a/.gitignore +++ b/.gitignore @@ -190,4 +190,8 @@ changelog-temp/ ehthumbs.db Thumbs.db Desktop.ini -$RECYCLE.BIN/ \ No newline at end of file +$RECYCLE.BIN/ + +# Personal files +CRUSH.md +TODO.txt \ No newline at end of file diff --git a/Docs/Developer-Guide/technical-architecture.md b/Docs/Developer-Guide/technical-architecture.md index 460a553..37ff423 100644 --- a/Docs/Developer-Guide/technical-architecture.md +++ b/Docs/Developer-Guide/technical-architecture.md @@ -22,27 +22,64 @@ This guide documents how SuperClaude's Context-Oriented Configuration Framework ### Directory Structure ``` -~/.claude/ # Claude Code's configuration directory +~/.claude/ (SuperClaude Framework Files Only) โ”œโ”€โ”€ CLAUDE.md # Main context file with imports -โ”œโ”€โ”€ FLAGS.md # Flag definitions and triggers +โ”œโ”€โ”€ FLAGS.md # Flag definitions and triggers โ”œโ”€โ”€ RULES.md # Core behavioral rules โ”œโ”€โ”€ PRINCIPLES.md # Guiding principles -โ”œโ”€โ”€ agents/ # Domain specialist contexts -โ”‚ โ”œโ”€โ”€ backend-architect.md # Backend expertise -โ”‚ โ”œโ”€โ”€ frontend-architect.md # Frontend expertise -โ”‚ โ”œโ”€โ”€ security-engineer.md # Security expertise -โ”‚ โ”œโ”€โ”€ python-expert.md # Python expertise -โ”‚ โ””โ”€โ”€ ... (13 total agents) -โ”œโ”€โ”€ commands/ # Workflow pattern contexts -โ”‚ โ”œโ”€โ”€ implement.md # Implementation patterns -โ”‚ โ”œโ”€โ”€ analyze.md # Analysis patterns -โ”‚ โ”œโ”€โ”€ brainstorm.md # Discovery patterns -โ”‚ โ””โ”€โ”€ ... (21 total commands) -โ””โ”€โ”€ modes/ # Behavioral modification contexts - โ”œโ”€โ”€ MODE_Brainstorming.md # Collaborative discovery - โ”œโ”€โ”€ MODE_Introspection.md # Transparent reasoning - โ”œโ”€โ”€ MODE_Task_Management.md # Task orchestration - โ””โ”€โ”€ ... (6 total modes) +โ”œโ”€โ”€ ZIG.md # Zig language integration +โ”œโ”€โ”€ 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 +โ”œโ”€โ”€ MODE_Brainstorming.md # Collaborative discovery mode +โ”œโ”€โ”€ MODE_Introspection.md # Transparent reasoning mode +โ”œโ”€โ”€ MODE_Orchestration.md # Tool coordination mode +โ”œโ”€โ”€ MODE_Task_Management.md # Task orchestration mode +โ”œโ”€โ”€ MODE_Token_Efficiency.md # Compressed communication mode +โ”œโ”€โ”€ agents/ # Domain specialist contexts (13 total) +โ”‚ โ”œโ”€โ”€ backend-architect.md # Backend expertise +โ”‚ โ”œโ”€โ”€ 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 @@ -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: ```markdown -# CLAUDE.md structure -@import commands/*.md # Loads all command patterns -@import agents/*.md # Loads all agent contexts -@import modes/*.md # Loads all behavioral modes -@import FLAGS.md # Loads flag definitions -@import RULES.md # Loads core rules -@import PRINCIPLES.md # Loads guiding principles +# CLAUDE + +*MANDATORY* +@FLAGS.md # Flag definitions and triggers +@RULES.md # Core behavioral rules +@PRINCIPLES.md # 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 @@ -152,7 +204,7 @@ Practical usage examples ### Command Processing 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 3. May auto-activate related agents 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 โ†“ -2. Load Context: read commands/analyze.md +2. Load Context: read commands/sc/analyze.md โ†“ 3. Check Flags: --focus security โ†“ @@ -240,7 +292,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security" ### Adding New Commands -1. Create `~/.claude/commands/new-command.md` +1. Create `~/.claude/commands/sc/new-command.md` 2. Define metadata, triggers, and workflow 3. No code changes needed - just context @@ -252,7 +304,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security" ### Adding New Modes -1. Create `~/.claude/modes/MODE_NewMode.md` +1. Create `~/.claude/MODE_NewMode.md` 2. Define activation triggers and modifications 3. Mode activates based on triggers diff --git a/Docs/Developer-Guide/testing-debugging.md b/Docs/Developer-Guide/testing-debugging.md index 7b97060..0c2df03 100644 --- a/Docs/Developer-Guide/testing-debugging.md +++ b/Docs/Developer-Guide/testing-debugging.md @@ -53,13 +53,13 @@ done ### Count Installed Components ```bash -# Should have 13 agents +# Should have 14 agents ls ~/.claude/agents/*.md | wc -l # Should have 21 commands ls ~/.claude/commands/*.md | wc -l -# Should have 6+ modes +# Should have 5 modes ls ~/.claude/modes/*.md | wc -l ``` diff --git a/Docs/Getting-Started/quick-start.md b/Docs/Getting-Started/quick-start.md index 04a4885..c7de2c8 100644 --- a/Docs/Getting-Started/quick-start.md +++ b/Docs/Getting-Started/quick-start.md @@ -52,8 +52,8 @@ pip install SuperClaude && SuperClaude install SuperClaude enhances Claude Code with: **21 Slash Commands** for workflow automation (/sc:brainstorm, /sc:implement, /sc:analyze) -**13 AI Specialists** with domain expertise (@agent-architect, @agent-security, @agent-frontend) -**6 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration) +**14 AI Specialists** with domain expertise (@agent-architect, @agent-security, @agent-frontend) +**5 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration) **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. diff --git a/Docs/README.md b/Docs/README.md index e4ba932..1b6737d 100644 --- a/Docs/README.md +++ b/Docs/README.md @@ -24,10 +24,10 @@ pip install SuperClaude && SuperClaude install ### ๐ŸŒฑ Start Here (New Users) | Guide | Purpose | -|-------|---------|------| -| **[Quick Start](Getting-Started/quick-start.md)** | Setup and first commands | | -| **[Installation](Getting-Started/installation.md)** | Detailed setup instructions | | -| **[Commands Guide](User-Guide/commands.md)** | All 21 `/sc:` commands | | +|-------|---------| +| **[Quick Start](Getting-Started/quick-start.md)** | Setup and first commands | +| **[Installation](Getting-Started/installation.md)** | Detailed setup instructions | +| **[Commands Guide](User-Guide/commands.md)** | All 21 `/sc:` commands | ### ๐ŸŒฟ Daily Usage (Regular Users) | Guide | Purpose | Use For | @@ -59,8 +59,8 @@ pip install SuperClaude && SuperClaude install ### Framework Components - **21 Commands** (`/sc:*`) - Workflow automation patterns -- **15 Agents** (`@agent-*`) - Domain specialists -- **6 Modes** - Behavioral modification patterns +- **14 Agents** (`@agent-*`) - Domain specialists +- **5 Modes** - Behavioral modification patterns - **6 MCP Servers** - Optional external tools ## ๐Ÿš€ Quick Command Reference diff --git a/Docs/User-Guide/agents.md b/Docs/User-Guide/agents.md index 69ac5f4..5cea0cb 100644 --- a/Docs/User-Guide/agents.md +++ b/Docs/User-Guide/agents.md @@ -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 diff --git a/Docs/User-Guide/commands.md b/Docs/User-Guide/commands.md index e5ff742..a1252aa 100644 --- a/Docs/User-Guide/commands.md +++ b/Docs/User-Guide/commands.md @@ -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. diff --git a/Docs/User-Guide/flags.md b/Docs/User-Guide/flags.md index 696786f..abdcbfe 100644 --- a/Docs/User-Guide/flags.md +++ b/Docs/User-Guide/flags.md @@ -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 \ No newline at end of file +- [MCP Servers Guide](mcp-servers.md) - Understanding MCP flag activation +- [Session Management](session-management.md) - Using flags with persistent sessions \ No newline at end of file diff --git a/Docs/User-Guide/session-management.md b/Docs/User-Guide/session-management.md index 000e7fa..2364923 100644 --- a/Docs/User-Guide/session-management.md +++ b/Docs/User-Guide/session-management.md @@ -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. \ No newline at end of file +**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. \ No newline at end of file