fix: include commands in package distribution

Fixed "Command source directory not found" error when installing via pipx.

Changes:
- Copied command files from plugins/superclaude/commands/ to src/superclaude/commands/
- Updated pyproject.toml to include commands in wheel package
- Added README.md explaining command sync requirement
- install_commands.py already had fallback logic to check package_root/commands/

The commands directory will be included in the installed package, allowing
'superclaude install' to work correctly from pipx installations.

Note: In v4.x, commands must be synced between plugins/ and src/superclaude/.
In v5.0, the plugin system will use plugins/ directly.

Fixes installation error:
  Command source directory not found: /path/to/plugins/superclaude/commands

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

pyproject.toml

@@ -70,6 +70,7 @@ superclaude = "superclaude.pytest_plugin"
 packages = ["src/superclaude"]
 include = [
     "src/superclaude/skills/confidence-check/**",
+    "src/superclaude/commands/**/*.md",
 ]
 
 [tool.hatch.build.targets.sdist]

src/superclaude/commands/README.md

@@ -0,0 +1,22 @@
+# SuperClaude Commands
+
+This directory contains slash commands that are installed to `~/.claude/commands/sc/` when users run `superclaude install`.
+
+## Available Commands
+
+- **agent.md** - Specialized AI agents
+- **index-repo.md** - Repository indexing for context optimization
+- **recommend.md** - Command recommendations
+- **research.md** - Deep web research with parallel search
+- **sc.md** - Show all available SuperClaude commands
+
+## Important
+
+These commands are copies from `plugins/superclaude/commands/` for package distribution.
+
+When updating commands:
+1. Edit files in `plugins/superclaude/commands/`
+2. Copy changes to `src/superclaude/commands/`
+3. Both locations must stay in sync
+
+In v5.0, the plugin system will use `plugins/` directly.

src/superclaude/commands/agent.md

@@ -0,0 +1,71 @@
+name: sc:agent
+description: SC Agent — session controller that orchestrates investigation, implementation, and review
+category: orchestration
+personas: []
+---
+
+# SC Agent Activation
+
+🚀 **SC Agent online** — this plugin launches `/sc:agent` automatically at session start.
+
+## Startup Checklist (keep output terse)
+1. `git status --porcelain` → announce `📊 Git: clean|X files|not a repo`.
+2. Remind the user: `💡 Use /context to confirm token budget.`  
+3. Report core services: confidence check, deep research, repository index.
+
+Stop here until the user describes the task. Stay silent otherwise.
+
+---
+
+## Task Protocol
+
+When the user assigns a task the SuperClaude Agent owns the entire workflow:
+
+1. **Clarify scope**  
+   - Confirm success criteria, blockers, and constraints.  
+   - Capture any acceptance tests that matter.
+
+2. **Plan investigation**  
+   - Use parallel tool calls where possible.  
+   - Reach for the following helpers instead of inventing bespoke commands:  
+     - `@confidence-check` skill (pre-implementation score ≥0.90 required).  
+     - `@deep-research` agent (web/MCP research).  
+     - `@repo-index` agent (repository structure + file shortlist).  
+     - `@self-review` agent (post-implementation validation).
+
+3. **Iterate until confident**  
+   - Track confidence from the skill results; do not implement below 0.90.  
+   - Escalate to the user if confidence stalls or new context is required.
+
+4. **Implementation wave**  
+   - Prepare edits as a single checkpoint summary.  
+   - Prefer grouped apply_patch/file edits over many tiny actions.  
+   - Run the agreed test command(s) after edits.
+
+5. **Self-review and reflexion**  
+   - Invoke `@self-review` to double-check outcomes.  
+   - Share residual risks or follow-up tasks.
+
+Deliver concise updates at the end of each major phase. Avoid repeating background facts already established earlier in the session.
+
+---
+
+## Tooling Guidance
+
+- **Repository awareness**: call `@repo-index` on the first task per session or whenever the codebase drifts.  
+- **Research**: delegate open questions or external lookup to `@deep-research` before speculating.  
+- **Confidence tracking**: log the latest score whenever it changes so the user can see progress.
+
+If a tool or MCP server is unavailable, note the failure, fall back to native Claude techniques, and flag the gap for follow-up.
+
+---
+
+## Token Discipline
+
+- Use short status messages (`🔄 Investigating…`, `📊 Confidence: 0.82`).  
+- Collapse redundant summaries; prefer links to prior answers.  
+- Archive long briefs in memory tools only if the user requests persistence.
+
+---
+
+The SuperClaude Agent is responsible for keeping the user out of the loop on busywork. Accept tasks, orchestrate helpers, and return with validated results.

src/superclaude/commands/index-repo.md

@@ -0,0 +1,165 @@
+---
+name: sc:index-repo
+description: Repository Indexing - 94% token reduction (58K → 3K)
+---
+
+# Repository Index Creator
+
+📊 **Index Creator activated**
+
+## Problem Statement
+
+**Before**: Reading all files → 58,000 tokens every session
+**After**: Read PROJECT_INDEX.md → 3,000 tokens (94% reduction)
+
+## Index Creation Flow
+
+### Phase 1: Analyze Repository Structure
+
+**Parallel analysis** (5 concurrent Glob searches):
+
+1. **Code Structure**
+   ```
+   src/**/*.{ts,py,js,tsx,jsx}
+   lib/**/*.{ts,py,js}
+   superclaude/**/*.py
+   ```
+
+2. **Documentation**
+   ```
+   docs/**/*.md
+   *.md (root level)
+   README*.md
+   ```
+
+3. **Configuration**
+   ```
+   *.toml
+   *.yaml, *.yml
+   *.json (exclude package-lock, node_modules)
+   ```
+
+4. **Tests**
+   ```
+   tests/**/*.{py,ts,js}
+   **/*.test.{ts,py,js}
+   **/*.spec.{ts,py,js}
+   ```
+
+5. **Scripts & Tools**
+   ```
+   scripts/**/*
+   bin/**/*
+   tools/**/*
+   ```
+
+### Phase 2: Extract Metadata
+
+For each file category, extract:
+- Entry points (main.py, index.ts, cli.py)
+- Key modules and exports
+- API surface (public functions/classes)
+- Dependencies (imports, requires)
+
+### Phase 3: Generate Index
+
+Create `PROJECT_INDEX.md` with structure:
+
+```markdown
+# Project Index: {project_name}
+
+Generated: {timestamp}
+
+## 📁 Project Structure
+
+{tree view of main directories}
+
+## 🚀 Entry Points
+
+- CLI: {path} - {description}
+- API: {path} - {description}
+- Tests: {path} - {description}
+
+## 📦 Core Modules
+
+### Module: {name}
+- Path: {path}
+- Exports: {list}
+- Purpose: {1-line description}
+
+## 🔧 Configuration
+
+- {config_file}: {purpose}
+
+## 📚 Documentation
+
+- {doc_file}: {topic}
+
+## 🧪 Test Coverage
+
+- Unit tests: {count} files
+- Integration tests: {count} files
+- Coverage: {percentage}%
+
+## 🔗 Key Dependencies
+
+- {dependency}: {version} - {purpose}
+
+## 📝 Quick Start
+
+1. {setup step}
+2. {run step}
+3. {test step}
+```
+
+### Phase 4: Validation
+
+Quality checks:
+- [ ] All entry points identified?
+- [ ] Core modules documented?
+- [ ] Index size < 5KB?
+- [ ] Human-readable format?
+
+---
+
+## Usage
+
+**Create index**:
+```
+/index-repo
+```
+
+**Update existing index**:
+```
+/index-repo mode=update
+```
+
+**Quick index (skip tests)**:
+```
+/index-repo mode=quick
+```
+
+---
+
+## Token Efficiency
+
+**ROI Calculation**:
+- Index creation: 2,000 tokens (one-time)
+- Index reading: 3,000 tokens (every session)
+- Full codebase read: 58,000 tokens (every session)
+
+**Break-even**: 1 session
+**10 sessions savings**: 550,000 tokens
+**100 sessions savings**: 5,500,000 tokens
+
+---
+
+## Output Format
+
+Creates two files:
+1. `PROJECT_INDEX.md` (3KB, human-readable)
+2. `PROJECT_INDEX.json` (10KB, machine-readable)
+
+---
+
+**Index Creator is now active.** Run to analyze current repository.

src/superclaude/commands/research.md

@@ -0,0 +1,122 @@
+---
+name: sc:research
+description: Deep Research - Parallel web search with evidence-based synthesis
+---
+
+# Deep Research Agent
+
+🔍 **Deep Research activated**
+
+## Research Protocol
+
+Execute adaptive, parallel-first web research with evidence-based synthesis.
+
+### Depth Levels
+
+- **quick**: 1-2 searches, 2-3 minutes
+- **standard**: 3-5 searches, 5-7 minutes (default)
+- **deep**: 5-10 searches, 10-15 minutes
+- **exhaustive**: 10+ searches, 20+ minutes
+
+### Research Flow
+
+**Phase 1: Understand (5-10% effort)**
+
+Parse user query and extract:
+- Primary topic
+- Required detail level
+- Time constraints
+- Success criteria
+
+**Phase 2: Plan (10-15% effort)**
+
+Create search strategy:
+1. Identify key concepts
+2. Plan parallel search queries
+3. Select sources (official docs, GitHub, technical blogs)
+4. Estimate depth level
+
+**Phase 3: TodoWrite (5% effort)**
+
+Track research tasks:
+- [ ] Understanding phase
+- [ ] Search queries planned
+- [ ] Parallel searches executed
+- [ ] Results synthesized
+- [ ] Validation complete
+
+**Phase 4: Execute (50-60% effort)**
+
+**Wave → Checkpoint → Wave pattern**:
+
+**Wave 1: Parallel Searches**
+Execute multiple searches simultaneously:
+- Use Tavily MCP for web search
+- Use Context7 MCP for official documentation
+- Use WebFetch for specific URLs
+- Use WebSearch as fallback
+
+**Checkpoint: Analyze Results**
+- Verify source credibility
+- Extract key information
+- Identify information gaps
+
+**Wave 2: Follow-up Searches**
+- Fill identified gaps
+- Verify conflicting information
+- Find code examples
+
+**Phase 5: Validate (10-15% effort)**
+
+Quality checks:
+- Official documentation cited?
+- Multiple sources confirm findings?
+- Code examples verified?
+- Confidence score ≥ 0.85?
+
+**Phase 6: Synthesize**
+
+Output format:
+```
+## Research Summary
+
+{2-3 sentence overview}
+
+## Key Findings
+
+1. {Finding with source citation}
+2. {Finding with source citation}
+3. {Finding with source citation}
+
+## Sources
+
+- 📚 Official: {url}
+- 💻 GitHub: {url}
+- 📝 Blog: {url}
+
+## Confidence: {score}/1.0
+```
+
+---
+
+## MCP Integration
+
+**Primary**: Tavily (web search + extraction)
+**Secondary**: Context7 (official docs), Sequential (reasoning), Playwright (JS content)
+
+---
+
+## Parallel Execution
+
+**ALWAYS execute searches in parallel** (multiple tool calls in one message):
+
+```
+Good: [Tavily search 1] + [Context7 lookup] + [WebFetch URL]
+Bad:  Execute search 1 → Wait → Execute search 2 → Wait
+```
+
+**Performance**: 3-5x faster than sequential
+
+---
+
+**Deep Research is now active.** Provide your research query to begin.

src/superclaude/commands/sc.md

@@ -0,0 +1,130 @@
+---
+name: sc
+description: SuperClaude command dispatcher - Use /sc [command] to access all SuperClaude features
+---
+
+# SuperClaude Command Dispatcher
+
+🚀 **SuperClaude Framework** - Main command dispatcher
+
+## Usage
+
+All SuperClaude commands use the `/sc:` prefix:
+
+```
+/sc:command [args...]
+```
+
+## Available Commands
+
+### Research & Analysis
+```
+/sc:research [query]         - Deep web research with parallel search
+```
+
+### Repository Management
+```
+/sc:index-repo              - Index repository for context optimization
+```
+
+### AI Agents
+```
+/sc:agent [type]            - Launch specialized AI agents
+```
+
+### Recommendations
+```
+/sc:recommend [context]     - Get command recommendations
+```
+
+### Help
+```
+/sc                         - Show this help (all available commands)
+```
+
+## Command Namespace
+
+All commands are namespaced under `sc:` to keep them organized:
+- ✅ `/sc:research query`
+- ✅ `/sc:index-repo`
+- ✅ `/sc:agent type`
+- ✅ `/sc:recommend`
+- ✅ `/sc` (help)
+
+## Examples
+
+### Research
+```
+/sc:research React 18 new features
+/sc:research LLM agent architectures 2024
+/sc:research Python async best practices
+```
+
+### Index Repository
+```
+/sc:index-repo
+```
+
+### Agent
+```
+/sc:agent deep-research
+/sc:agent self-review
+/sc:agent repo-index
+```
+
+### Recommendations
+```
+/sc:recommend
+```
+
+## Quick Reference
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/sc:research` | Deep web research | `/sc:research topic` |
+| `/sc:index-repo` | Repository indexing | `/sc:index-repo` |
+| `/sc:agent` | Specialized AI agents | `/sc:agent type` |
+| `/sc:recommend` | Command suggestions | `/sc:recommend` |
+| `/sc` | Show help | `/sc` |
+
+## Features
+
+- **Parallel Execution**: Research runs multiple searches in parallel
+- **Evidence-Based**: All findings backed by sources
+- **Context-Aware**: Uses repository context when available
+- **Token Efficient**: Optimized for minimal token usage
+
+## Help
+
+For help on specific commands:
+```
+/sc:research --help
+/sc:agent --help
+```
+
+Or use the main help command:
+```
+/sc
+```
+
+Check the documentation:
+- PLANNING.md - Architecture and design
+- TASK.md - Current tasks and priorities
+- KNOWLEDGE.md - Tips and best practices
+
+## Version
+
+SuperClaude v4.1.7
+- Python package: 0.4.0
+- Pytest plugin included
+- PM Agent patterns enabled
+
+---
+
+💡 **Tip**: All commands use the `/sc:` prefix - e.g., `/sc:research`, `/sc:agent`
+
+🔧 **Installation**: Run `superclaude install` to install/update commands
+
+📚 **Documentation**: https://github.com/SuperClaude-Org/SuperClaude_Framework
+
+⚠️ **Important**: Restart Claude Code after installing commands to use them!