refactor: migrate plugin structure from .claude-plugin to project root

Restructure plugin to follow Claude Code official documentation: - Move TypeScript files from .claude-plugin/* to project root - Create Markdown command files in commands/ - Update plugin.json to reference ./commands/*.md - Add comprehensive plugin installation guide Changes: - Commands: pm.md, research.md, index-repo.md (new Markdown format) - TypeScript: pm/, research/, index/ moved to root - Hooks: hooks/hooks.json moved to root - Documentation: PLUGIN_INSTALL.md, updated CLAUDE.md, Makefile Note: This commit represents transition state. Original TypeScript-based execution system was replaced with Markdown commands. Further redesign needed to properly integrate Skills and Hooks per official docs. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-29 16:16:08 +00:00 · 2025-10-21 16:37:35 +09:00
parent fbc74e4670
commit c91a3a4805
16 changed files with 1795 additions and 331 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,12 +1,15 @@
 {
  "name": "superclaude-local",
  "description": "Local development marketplace for SuperClaude plugins",
+  "owner": {
+    "name": "SuperClaude Team"
+  },
  "plugins": [
    {
      "name": "pm-agent",
-      "path": ".",
-      "version": "1.0.0",
-      "description": "Project Manager Agent with 90% confidence checks and zero-footprint memory"
+      "source": "./pm-agent",
+      "version": "2.1.0",
+      "description": "PM Agent - Confidence-driven orchestrator with deep research and repository indexing"
    }
  ]
 }
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,38 +1,18 @@
 {
  "name": "pm-agent",
-  "version": "2.0.0",
-  "description": "PM Agent - Auto-activating orchestrator with hot reload support",
-  "author": "SuperClaude Team",
-  "main": "pm/index.ts",
-  "commands": [
-    {
-      "name": "pm",
-      "path": "pm/index.ts",
-      "description": "Activate PM Agent with confidence-driven workflow (auto-starts via hooks)"
-    },
-    {
-      "name": "research",
-      "path": "research/index.ts",
-      "description": "Deep web research with adaptive planning and intelligent search"
-    },
-    {
-      "name": "index-repo",
-      "path": "index/index.ts",
-      "description": "Create repository structure index for fast context loading (94% token reduction)"
-    }
-  ],
-  "skills": [
-    {
-      "name": "confidence_check",
-      "path": "pm/confidence.ts",
-      "description": "Pre-implementation confidence assessment (≥90% required, Precision/Recall 1.0)"
-    }
-  ],
-  "hooks": {
-    "path": "hooks/hooks.json",
-    "description": "SessionStart auto-activation: /pm runs automatically on session start"
+  "version": "2.1.0",
+  "description": "PM Agent - Confidence-driven orchestrator with deep research and repository indexing",
+  "author": {
+    "name": "SuperClaude Team"
  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
+  "homepage": "https://github.com/kazukixjp/superclaude",
+  "repository": "https://github.com/kazukixjp/superclaude",
+  "license": "MIT",
+  "keywords": ["pm-agent", "confidence-check", "research", "indexing"],
+  "commands": [
+    "./commands/pm.md",
+    "./commands/research.md",
+    "./commands/index-repo.md"
+  ],
+  "hooks": "./hooks/hooks.json"
 }
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,381 +4,229 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## 🐍 Python Environment Rules

-**CRITICAL**: This project uses **UV** for all Python operations.
+**CRITICAL**: This project uses **UV** for all Python operations. Never use `python -m`, `pip install`, or `python script.py` directly.

 ### Required Commands

 ```bash
-# ❌ WRONG - Never use these
-python -m pytest
-pip install package
-python script.py
-
-# ✅ CORRECT - Always use UV
-uv run pytest
-uv pip install package
-uv run python script.py
-```
-
-### Why UV?
-
- **Fast**: 10-100x faster than pip
- **Reliable**: Lock file ensures reproducibility
- **Clean**: No system Python pollution
- **Standard**: Project convention for consistency
-
-### Common Operations
-
-```bash
-# Run tests
-uv run pytest tests/ -v
-
-# Install dependencies
-uv pip install -r requirements.txt
-
-# Run specific script
-uv run python scripts/analyze_workflow_metrics.py
-
-# Create virtual environment (if needed)
-uv venv
-```
-
-### Integration with Docker
-
-When using Docker for development:
-```bash
-# Inside Docker container
-docker compose exec workspace uv run pytest
+# All Python operations must use UV
+uv run pytest                    # Run tests
+uv run pytest tests/pm_agent/   # Run specific tests
+uv pip install package           # Install dependencies
+uv run python script.py          # Execute scripts
 ```

 ## 📂 Project Structure

-```
-SuperClaude_Framework/
-├── .claude-plugin/             # TypeScript plugins (v2.0 architecture)
-│   ├── pm/                     # PM Agent plugin
-│   │   ├── index.ts            # Main orchestrator (SessionStart auto-activation)
-│   │   ├── confidence.ts       # Confidence assessment (≥90% threshold, Precision/Recall 1.0)
-│   │   └── package.json        # Dependencies
-│   ├── research/               # Deep Research plugin
-│   │   ├── index.ts            # Web research with adaptive planning
-│   │   └── package.json        # Dependencies
-│   ├── index/                  # Repository indexing plugin
-│   │   ├── index.ts            # 94% token reduction (58K → 3K)
-│   │   └── package.json        # Dependencies
-│   ├── hooks/
-│   │   └── hooks.json          # SessionStart hook configuration
-│   ├── tests/                  # Plugin tests (confidence_check, test cases)
-│   └── plugin.json             # Plugin manifest (v2.0.0)
-├── src/superclaude/            # Python package (pytest plugin, CLI)
-│   ├── __init__.py             # Exports: ConfidenceChecker, SelfCheckProtocol, ReflexionPattern
-│   ├── pytest_plugin.py        # Auto-loaded pytest integration
-│   ├── pm_agent/               # PM Agent core (confidence, self-check, reflexion)
-│   ├── cli/                    # CLI commands (main, doctor, install_skill)
-│   └── execution/              # Execution patterns (parallel, reflection, self_correction)
-├── docs/                       # Documentation
-├── scripts/                    # Analysis tools (A/B testing, workflow metrics)
-└── tests/                      # Python test suite
-```
+**Dual-language architecture**: TypeScript plugins for Claude Code integration + Python package for testing/CLI tools.

-**Architecture Overview:**
- **TypeScript Plugins** (.claude-plugin/): Hot reload, auto-activation, production workflows
- **Python Package** (src/superclaude/): pytest plugin, CLI tools, PM Agent core logic
- **Dual Language**: TypeScript for Claude Code integration, Python for testing/tooling
+```
+# TypeScript Plugins (project root)
+pm/                      # PM Agent: confidence checks, orchestration
+research/                # Deep Research: web search, adaptive planning
+index/                   # Repository indexing: 94% token reduction
+hooks/hooks.json         # SessionStart auto-activation config
+
+# Claude Code Configuration
+.claude/settings.json    # Marketplace and plugin settings
+.claude-plugin/          # Plugin manifest
+├── plugin.json          # Plugin metadata (3 commands: /pm, /research, /index-repo)
+└── tests/               # Plugin tests
+
+# Python Package
+src/superclaude/         # Pytest plugin + CLI tools
+├── pytest_plugin.py     # Auto-loaded pytest integration
+├── pm_agent/            # confidence.py, self_check.py, reflexion.py
+├── execution/           # parallel.py, reflection.py, self_correction.py
+└── cli/                 # main.py, doctor.py, install_skill.py
+
+# Project Files
+tests/                   # Python test suite
+docs/                    # Documentation
+scripts/                 # Analysis tools (workflow metrics, A/B testing)
+PLANNING.md              # Architecture, absolute rules
+TASK.md                  # Current tasks
+KNOWLEDGE.md             # Accumulated insights
+```

 ## 🔧 Development Workflow

-### Makefile Commands (Recommended)
+### Essential Commands

 ```bash
-# Development setup
-make dev              # Install in editable mode with [dev] dependencies (RECOMMENDED)
-make verify           # Verify installation health (package, version, plugin, doctor)
+# Setup
+make dev              # Install in editable mode with dev dependencies
+make verify           # Verify installation (package, plugin, health)

 # Testing
-make test             # Run full test suite with pytest
-make test-plugin      # Verify pytest plugin auto-discovery
+make test             # Run full test suite
+uv run pytest tests/pm_agent/ -v              # Run specific directory
+uv run pytest tests/test_file.py -v           # Run specific file
+uv run pytest -m confidence_check             # Run by marker
+uv run pytest --cov=superclaude               # With coverage

-# Code quality
+# Code Quality
 make lint             # Run ruff linter
 make format           # Format code with ruff
+make doctor           # Health check diagnostics

 # Maintenance
-make doctor           # Run health check diagnostics
-make clean            # Remove build artifacts and caches
-make translate        # Translate README to zh/ja (requires neural-cli)
-```
-
-### Running Tests Directly
-
-```bash
-# All tests
-uv run pytest
-
-# Specific test file
-uv run pytest tests/pm_agent/test_confidence_check.py -v
-
-# By directory
-uv run pytest tests/pm_agent/ -v
-
-# By marker
-uv run pytest -m confidence_check
-uv run pytest -m "unit and not integration"
-
-# With coverage
-uv run pytest --cov=superclaude --cov-report=html
-```
-
-### Code Quality
-
-```bash
-# Linting
-uv run ruff check .
-
-# Formatting
-uv run ruff format .
-
-# Type checking (if configured)
-uv run mypy superclaude/
+make clean            # Remove build artifacts
 ```

 ## 📦 Core Architecture

-### Pytest Plugin System (Auto-loaded)
+### Pytest Plugin (Auto-loaded)

-SuperClaude includes an **auto-loaded pytest plugin** registered via entry points in pyproject.toml:66-67:
+Registered via `pyproject.toml` entry point, automatically available after installation.

-```toml
-[project.entry-points.pytest11]
-superclaude = "superclaude.pytest_plugin"
-```
+**Fixtures**: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`

-**Provides:**
- Custom fixtures: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`
- Auto-markers: Tests in `/unit/` → `@pytest.mark.unit`, `/integration/` → `@pytest.mark.integration`
- Custom markers: `@pytest.mark.confidence_check`, `@pytest.mark.self_check`, `@pytest.mark.reflexion`
- PM Agent integration for test lifecycle hooks
+**Auto-markers**:
+- Tests in `/unit/` → `@pytest.mark.unit`
+- Tests in `/integration/` → `@pytest.mark.integration`
+
+**Custom markers**: `@pytest.mark.confidence_check`, `@pytest.mark.self_check`, `@pytest.mark.reflexion`

 ### PM Agent - Three Core Patterns

-Located in `src/superclaude/pm_agent/`:
+**1. ConfidenceChecker** (src/superclaude/pm_agent/confidence.py)
+- Pre-execution confidence assessment: ≥90% required, 70-89% present alternatives, <70% ask questions
+- Prevents wrong-direction work, ROI: 25-250x token savings

-**1. ConfidenceChecker (Pre-execution)**
- Prevents wrong-direction execution by assessing confidence BEFORE starting
- Token budget: 100-200 tokens
- ROI: 25-250x token savings when stopping wrong implementations
- Confidence levels:
-  - High (≥90%): Proceed immediately
-  - Medium (70-89%): Present alternatives
-  - Low (<70%): STOP → Ask specific questions
+**2. SelfCheckProtocol** (src/superclaude/pm_agent/self_check.py)
+- Post-implementation evidence-based validation
+- No speculation - verify with tests/docs

-**2. SelfCheckProtocol (Post-implementation)**
- Evidence-based validation after implementation
- No speculation allowed - verify with actual tests/docs
- Ensures implementation matches requirements
+**3. ReflexionPattern** (src/superclaude/pm_agent/reflexion.py)
+- Error learning and prevention
+- Cross-session pattern matching

-**3. ReflexionPattern (Error learning)**
- Records failures for future prevention
- Pattern matching for similar errors
- Cross-session learning and improvement
+### Parallel Execution

-### Module Structure
+**Wave → Checkpoint → Wave pattern** (src/superclaude/execution/parallel.py):
+- 3.5x faster than sequential execution
+- Automatic dependency analysis
+- Example: [Read files in parallel] → Analyze → [Edit files in parallel]

-```
-src/superclaude/
-├── __init__.py              # Exports: ConfidenceChecker, SelfCheckProtocol, ReflexionPattern
-├── pytest_plugin.py         # Auto-loaded pytest integration (fixtures, hooks, markers)
-├── pm_agent/                # PM Agent core (confidence, self-check, reflexion)
-├── cli/                     # CLI commands (main, doctor, install_skill)
-└── execution/               # Execution patterns (parallel, reflection, self_correction)
-```
+### TypeScript Plugins (v2.0)

-### Parallel Execution Engine
+**Location**: Plugin source files are at **project root** (pm/, research/, index/), not in .claude-plugin/.
+**Hot reload enabled** - edit .ts file, save, instant reflection (no restart).

-Located in `src/superclaude/execution/parallel.py`:
+**Three plugins**:
+- **/pm**: Auto-starts on session (hooks/hooks.json), confidence-driven orchestration
+- **/research**: Deep web research, adaptive planning, Tavily MCP integration
+- **/index-repo**: Repository indexing, 94% token reduction (58K → 3K)

- **Automatic parallelization**: Analyzes task dependencies and executes independent operations concurrently
- **Wave → Checkpoint → Wave pattern**: 3.5x faster than sequential execution
- **Dependency graph**: Topological sort for optimal grouping
- **ThreadPoolExecutor**: Concurrent execution with result aggregation
+**Important**: When editing plugins, modify files in pm/, research/, or index/ at project root, not in .claude-plugin/.

-Example pattern:
-```python
-# Wave 1: Read files in parallel
-tasks = [read_file1, read_file2, read_file3]
+## 🧪 Testing with PM Agent

-# Checkpoint: Analyze results
-
-# Wave 2: Edit files in parallel based on analysis
-tasks = [edit_file1, edit_file2, edit_file3]
-```
-
-### Plugin Architecture (v2.0)
-
-**TypeScript Plugins** (.claude-plugin/):
- **pm/index.ts**: PM Agent orchestrator with SessionStart auto-activation
-  - Confidence-driven workflow (≥90% threshold required)
-  - Git status detection & display
-  - Auto-starts on every session (no user command needed)
- **research/index.ts**: Deep web research with adaptive planning
-  - 3 strategies: Planning-Only, Intent-Planning, Unified
-  - Multi-hop reasoning (up to 5 iterations)
-  - Tavily MCP integration
- **index/index.ts**: Repository indexing for token efficiency
-  - 94% token reduction (58K → 3K tokens)
-  - Parallel analysis (5 concurrent tasks)
-  - PROJECT_INDEX.md generation
-
-**Hot Reload**:
- Edit TypeScript file → Save → Instant reflection (no restart)
- Faster iteration than Markdown commands
-
-**SessionStart Hook**:
- Configured in hooks/hooks.json
- Auto-executes /pm command on session start
- User sees PM Agent activation message automatically
-
-## 🧪 Testing with PM Agent Markers
-
-### Custom Pytest Markers
+### Example Test with Markers

 ```python
-# Pre-execution confidence check (skips if confidence < 70%)
@pytest.mark.confidence_check
 def test_feature(confidence_checker):
+    """Pre-execution confidence check - skips if < 70%"""
    context = {"test_name": "test_feature", "has_official_docs": True}
    assert confidence_checker.assess(context) >= 0.7

-# Post-implementation validation with evidence requirement
@pytest.mark.self_check
 def test_implementation(self_check_protocol):
+    """Post-implementation validation with evidence"""
    implementation = {"code": "...", "tests": [...]}
    passed, issues = self_check_protocol.validate(implementation)
    assert passed, f"Validation failed: {issues}"

-# Error learning and prevention
@pytest.mark.reflexion
-def test_error_prone_feature(reflexion_pattern):
-    # If this test fails, reflexion records the error for future prevention
+def test_error_learning(reflexion_pattern):
+    """If test fails, reflexion records for future prevention"""
    pass

-# Token budget allocation (simple: 200, medium: 1000, complex: 2500)
-@pytest.mark.complexity("medium")
+@pytest.mark.complexity("medium")  # simple: 200, medium: 1000, complex: 2500
 def test_with_budget(token_budget):
+    """Token budget allocation"""
    assert token_budget.limit == 1000
 ```

-### Available Fixtures
-
-From `src/superclaude/pytest_plugin.py`:
-
- `confidence_checker` - Pre-execution confidence assessment
- `self_check_protocol` - Post-implementation validation
- `reflexion_pattern` - Error learning pattern
- `token_budget` - Token allocation management
- `pm_context` - PM Agent context (memory directory structure)
-
 ## 🌿 Git Workflow

-### Branch Strategy
+**Branch structure**: `master` (production) ← `integration` (testing) ← `feature/*`, `fix/*`, `docs/*`

-```
-master          # Production-ready releases
-├── integration # Integration testing branch (current)
-    ├── feature/*       # Feature development
-    ├── fix/*           # Bug fixes
-    └── docs/*          # Documentation updates
-```
-
-**Workflow:**
-1. Create feature branch from `integration`: `git checkout -b feature/your-feature`
+**Standard workflow**:
+1. Create branch from `integration`: `git checkout -b feature/your-feature`
 2. Develop with tests: `uv run pytest`
-3. Commit with conventional commits: `git commit -m "feat: description"`
-4. Merge to `integration` for integration testing
-5. After validation: `integration` → `master`
+3. Commit: `git commit -m "feat: description"` (conventional commits)
+4. Merge to `integration` → validate → merge to `master`

-**Current branch:** `integration` (see gitStatus above)
+**Current branch**: See git status in session start output

-## 🚀 Contributing
+### Parallel Development with Git Worktrees

-When making changes:
+**CRITICAL**: When running multiple Claude Code sessions in parallel, use `git worktree` to avoid conflicts.

-1. Create feature branch from `integration`
-2. Make changes with tests (maintain coverage)
-3. Commit with conventional commits (feat:, fix:, docs:, refactor:, test:)
-4. Merge to `integration` for integration testing
-5. Small, reviewable PRs preferred
+```bash
+# Create worktree for integration branch
+cd ~/github/superclaude
+git worktree add ../superclaude-integration integration

-## 📝 Essential Documentation
+# Create worktree for feature branch
+git worktree add ../superclaude-feature feature/pm-agent
+```

-**Read these files IN ORDER at session start:**
+**Benefits**:
+- Run Claude Code sessions on different branches simultaneously
+- No branch switching conflicts
+- Independent working directories
+- Parallel development without state corruption

-1. **PLANNING.md** - Architecture, design principles, absolute rules
-2. **TASK.md** - Current tasks and priorities
-3. **KNOWLEDGE.md** - Accumulated insights and troubleshooting
+**Usage**:
+- Session A: Open `~/github/superclaude/` (main)
+- Session B: Open `~/github/superclaude-integration/` (integration)
+- Session C: Open `~/github/superclaude-feature/` (feature branch)

-These documents are the **source of truth** for development standards.
+**Cleanup**:
+```bash
+git worktree remove ../superclaude-integration
+```

-**Additional Resources:**
- User guides: `docs/user-guide/`
- Development docs: `docs/Development/`
- Research reports: `docs/research/`
+## 📝 Key Documentation Files
+
+**PLANNING.md** - Architecture, design principles, absolute rules
+**TASK.md** - Current tasks and priorities
+**KNOWLEDGE.md** - Accumulated insights and troubleshooting
+
+Additional docs in `docs/user-guide/`, `docs/developer-guide/`, `docs/reference/`

 ## 💡 Core Development Principles

-From KNOWLEDGE.md and PLANNING.md:
-
 ### 1. Evidence-Based Development
- **Never guess** - verify with official docs (Context7 MCP, WebFetch, WebSearch)
- Example: Don't assume port configuration - check official documentation first
- Prevents wrong-direction implementations
+**Never guess** - verify with official docs (Context7 MCP, WebFetch, WebSearch) before implementation.

-### 2. Token Efficiency
- Every operation has a token budget:
-  - Simple (typo fix): 200 tokens
-  - Medium (bug fix): 1,000 tokens
-  - Complex (feature): 2,500 tokens
- Confidence check ROI: Spend 100-200 to save 5,000-50,000
+### 2. Confidence-First Implementation
+Check confidence BEFORE starting: ≥90% proceed, 70-89% present alternatives, <70% ask questions.

 ### 3. Parallel-First Execution
- **Wave → Checkpoint → Wave** pattern (3.5x faster)
- Good: `[Read file1, Read file2, Read file3]` → Analyze → `[Edit file1, Edit file2, Edit file3]`
- Bad: Sequential reads then sequential edits
+Use **Wave → Checkpoint → Wave** pattern (3.5x faster). Example: `[Read files in parallel]` → Analyze → `[Edit files in parallel]`

-### 4. Confidence-First Implementation
- Check confidence BEFORE implementation, not after
- ≥90%: Proceed immediately
- 70-89%: Present alternatives
- <70%: STOP → Ask specific questions
+### 4. Token Efficiency
+- Simple (typo): 200 tokens
+- Medium (bug fix): 1,000 tokens
+- Complex (feature): 2,500 tokens
+- Confidence check ROI: spend 100-200 to save 5,000-50,000

 ## 🔧 MCP Server Integration

-This framework integrates with multiple MCP servers via **airis-mcp-gateway**:
+Integrates with multiple MCP servers via **airis-mcp-gateway**.

-**Priority Servers:**
- **Tavily**: Primary web search (Deep Research plugin)
- **Serena**: Session persistence and memory
- **Mindbase**: Cross-session learning (zero-footprint)
- **Sequential**: Token-efficient reasoning (30-50% reduction)
+**High Priority**:
+- **Tavily**: Web search (Deep Research)
 - **Context7**: Official documentation (prevent hallucination)
+- **Sequential**: Token-efficient reasoning (30-50% reduction)
+- **Serena**: Session persistence
+- **Mindbase**: Cross-session learning

-**Optional Servers:**
- **Playwright**: JavaScript-heavy content extraction
- **Magic**: UI component generation
- **Chrome DevTools**: Performance analysis
+**Optional**: Playwright (browser automation), Magic (UI components), Chrome DevTools (performance)

-**Integration Pattern:**
- TypeScript plugins call MCP servers directly
- Python pytest plugin uses MCP for test validation
- Always prefer MCP tools over speculation when documentation or research is needed
-
-**Unified Gateway:**
- All MCP servers accessible via airis-mcp-gateway
- Simplified configuration and tool selection
- See: https://github.com/airis-mcp-gateway
-
-## 🔗 Related
-
- Global rules: `~/.claude/CLAUDE.md` (workspace-level)
- MCP servers: Unified gateway via `airis-mcp-gateway`
- Framework docs: Auto-installed to `~/.claude/superclaude/`
+**Usage**: TypeScript plugins and Python pytest plugin can call MCP servers. Always prefer MCP tools over speculation for documentation/research.
--- a/87
+++ b/87
@@ -1,4 +1,4 @@
-.PHONY: dev install test test-plugin doctor verify clean lint format help
+.PHONY: dev install test test-plugin doctor verify clean lint format install-plugin install-plugin-minimal install-plugin-dev uninstall-plugin reinstall-plugin reinstall-plugin-minimal reinstall-plugin-dev help

 # Development installation (local source, editable) - RECOMMENDED
 dev:
@@ -64,6 +64,82 @@ clean:
 	find . -type d -name .pytest_cache -exec rm -rf {} +
 	find . -type d -name .ruff_cache -exec rm -rf {} +

+# Install Claude Code plugin - MINIMAL (manifest only, for baseline performance)
+install-plugin-minimal:
+	@echo "🔌 Installing SuperClaude plugin (MINIMAL) to Claude Code..."
+	@if [ -d ~/.claude/plugins/pm-agent ]; then \
+		echo "⚠️  Plugin already exists at ~/.claude/plugins/pm-agent"; \
+		echo "   Run 'make reinstall-plugin-minimal' to update"; \
+		exit 1; \
+	fi
+	@mkdir -p ~/.claude/plugins/pm-agent
+	@cp .claude-plugin/plugin.json ~/.claude/plugins/pm-agent/
+	@cp .claude-plugin/marketplace.json ~/.claude/plugins/pm-agent/
+	@echo ""
+	@echo "✅ Plugin installed (MINIMAL configuration)"
+	@echo "   Only manifest files copied - for baseline performance testing"
+	@echo ""
+	@echo "🔄 Restart Claude Code to activate plugins"
+
+# Install Claude Code plugin - DEV (full, for development)
+install-plugin-dev:
+	@echo "🔌 Installing SuperClaude plugin (DEV) to Claude Code..."
+	@if [ -d ~/.claude/plugins/pm-agent ]; then \
+		echo "⚠️  Plugin already exists at ~/.claude/plugins/pm-agent"; \
+		echo "   Run 'make reinstall-plugin-dev' to update"; \
+		exit 1; \
+	fi
+	@mkdir -p ~/.claude/plugins/pm-agent
+	@cp -r .claude-plugin/* ~/.claude/plugins/pm-agent/
+	@cp -r commands ~/.claude/plugins/pm-agent/
+	@cp -r hooks ~/.claude/plugins/pm-agent/
+	@echo ""
+	@echo "✅ Plugin installed (DEV configuration)"
+	@echo ""
+	@echo "📋 Installed components:"
+	@echo "   - /pm: PM Agent orchestrator (SessionStart hook)"
+	@echo "   - /research: Deep web search with adaptive planning"
+	@echo "   - /index-repo: Repository indexing (94%% token reduction)"
+	@echo ""
+	@echo "🔄 Restart Claude Code to activate plugins"
+
+# Default install (dev configuration for backward compatibility)
+install-plugin: install-plugin-dev
+
+# Uninstall Claude Code plugin
+uninstall-plugin:
+	@echo "🗑️  Uninstalling SuperClaude plugin..."
+	@if [ ! -d ~/.claude/plugins/pm-agent ]; then \
+		echo "❌ Plugin not found at ~/.claude/plugins/pm-agent"; \
+		exit 1; \
+	fi
+	@rm -rf ~/.claude/plugins/pm-agent
+	@echo "✅ Plugin uninstalled successfully"
+
+# Reinstall plugin - MINIMAL
+reinstall-plugin-minimal:
+	@echo "🔄 Reinstalling SuperClaude plugin (MINIMAL)..."
+	@rm -rf ~/.claude/plugins/pm-agent 2>/dev/null || true
+	@mkdir -p ~/.claude/plugins/pm-agent
+	@cp .claude-plugin/plugin.json ~/.claude/plugins/pm-agent/
+	@cp .claude-plugin/marketplace.json ~/.claude/plugins/pm-agent/
+	@echo "✅ Plugin reinstalled (MINIMAL configuration)"
+	@echo "🔄 Restart Claude Code to apply changes"
+
+# Reinstall plugin - DEV
+reinstall-plugin-dev:
+	@echo "🔄 Reinstalling SuperClaude plugin (DEV)..."
+	@rm -rf ~/.claude/plugins/pm-agent 2>/dev/null || true
+	@mkdir -p ~/.claude/plugins/pm-agent
+	@cp -r .claude-plugin/* ~/.claude/plugins/pm-agent/
+	@cp -r commands ~/.claude/plugins/pm-agent/
+	@cp -r hooks ~/.claude/plugins/pm-agent/
+	@echo "✅ Plugin reinstalled (DEV configuration)"
+	@echo "🔄 Restart Claude Code to apply changes"
+
+# Default reinstall (dev configuration for backward compatibility)
+reinstall-plugin: reinstall-plugin-dev
+
 # Translate README to multiple languages using Neural CLI
 translate:
 	@echo "🌐 Translating README using Neural CLI (Ollama + qwen2.5:3b)..."
@@ -99,13 +175,14 @@ help:
 	@echo "  make format          - Format code (ruff format)"
 	@echo "  make clean           - Clean build artifacts"
 	@echo ""
+	@echo "🔌 Plugin Management:"
+	@echo "  make install-plugin  - Install plugin to Claude Code (~/.claude/plugins/)"
+	@echo "  make uninstall-plugin - Remove plugin from Claude Code"
+	@echo "  make reinstall-plugin - Update existing plugin installation"
+	@echo ""
 	@echo "📚 Documentation:"
 	@echo "  make translate       - Translate README to Chinese and Japanese"
 	@echo "  make help            - Show this help message"
 	@echo ""
-	@echo "💡 Plugin Usage:"
-	@echo "  cd /path/to/SuperClaude_Framework && claude"
-	@echo "  → .claude-plugin/ auto-detected (project-local plugin)"
-	@echo ""
 	@echo "💡 Legacy (backward compatibility):"
 	@echo "  make install         - Alias for 'make dev'"
--- a/PLUGIN_INSTALL.md
+++ b/PLUGIN_INSTALL.md
@@ -0,0 +1,161 @@
+# SuperClaude Plugin Installation Guide
+
+## 公式インストール方法（推奨）
+
+### 前提条件
+
+1. **ripgrep のインストール**
+   ```bash
+   brew install ripgrep
+   ```
+
+2. **環境変数の設定**（~/.zshrc または ~/.bashrc に追加）
+   ```bash
+   export USE_BUILTIN_RIPGREP=0
+   ```
+
+3. **シェルの再起動**
+   ```bash
+   exec $SHELL
+   ```
+
+### インストール手順
+
+#### 方法A: ローカルマーケットプレイス経由（推奨）
+
+1. Claude Code でマーケットプレイスを追加:
+   ```
+   /plugin marketplace add /Users/kazuki/github/superclaude
+   ```
+
+2. プラグインをインストール:
+   ```
+   /plugin install pm-agent@superclaude-local
+   ```
+
+3. Claude Code を再起動
+
+4. 動作確認:
+   ```
+   /pm
+   /research
+   /index-repo
+   ```
+
+#### 方法B: 開発者モード（直接コピー）
+
+**注意**: この方法は開発中のテスト用です。公式方法（方法A）の使用を推奨します。
+
+```bash
+# プロジェクトルートで実行
+make reinstall-plugin-dev
+```
+
+Claude Code を再起動後、コマンドが利用可能になります。
+
+## インストールされるコマンド
+
+### /pm
+PM Agent モードを起動。以下の機能を提供：
+- 90%信頼度チェック（実装前）
+- 並列実行最適化
+- トークン予算管理
+- エビデンスベース開発
+
+### /research
+Deep Research モード。以下の機能を提供：
+- 並列Web検索（Tavily MCP）
+- 公式ドキュメント優先
+- ソース検証
+- 信頼度付き結果
+
+### /index-repo
+リポジトリインデックス作成。以下の機能を提供：
+- プロジェクト構造解析
+- 94%トークン削減（58K → 3K）
+- エントリポイント特定
+- モジュールマップ生成
+
+## フックの自動実行
+
+SessionStart フックにより、新しいセッション開始時に `/pm` コマンドが自動実行されます。
+
+無効化したい場合は、`~/.claude/plugins/pm-agent/hooks/hooks.json` を編集してください。
+
+## トラブルシューティング
+
+### コマンドが認識されない場合
+
+1. **ripgrep の確認**:
+   ```bash
+   which rg
+   rg --version
+   ```
+
+   インストールされていない場合：
+   ```bash
+   brew install ripgrep
+   ```
+
+2. **環境変数の確認**:
+   ```bash
+   echo $USE_BUILTIN_RIPGREP
+   ```
+
+   設定されていない場合：
+   ```bash
+   echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.zshrc
+   exec $SHELL
+   ```
+
+3. **プラグインの確認**:
+   ```bash
+   ls -la ~/.claude/plugins/pm-agent/
+   ```
+
+   存在しない場合は再インストール：
+   ```bash
+   make reinstall-plugin-dev
+   ```
+
+4. **Claude Code を再起動**
+
+### それでも動かない場合
+
+Claude Code のバージョンを確認してください。2.0.x には既知のバグがあります：
+- GitHub Issue #8831: Custom slash commands not discovered
+
+回避策：
+- NPM版に切り替える（Homebrew版にバグの可能性）
+- ripgrep をシステムにインストール（上記手順）
+
+## プラグイン構造（参考）
+
+```
+~/.claude/plugins/pm-agent/
+├── plugin.json          # プラグインメタデータ
+├── marketplace.json     # マーケットプレイス情報
+├── commands/            # Markdown コマンド
+│   ├── pm.md
+│   ├── research.md
+│   └── index-repo.md
+└── hooks/
+    └── hooks.json       # SessionStart フック設定
+```
+
+## 開発者向け情報
+
+プラグインのソースコードは `/Users/kazuki/github/superclaude/` にあります。
+
+変更を反映するには：
+```bash
+make reinstall-plugin-dev
+# Claude Code を再起動
+```
+
+## サポート
+
+問題が発生した場合は、以下を確認してください：
+- 公式ドキュメント: https://docs.claude.com/ja/docs/claude-code/plugins
+- GitHub Issues: https://github.com/anthropics/claude-code/issues
+- プロジェクトドキュメント: CLAUDE.md, PLANNING.md
--- a/commands/index-repo.md
+++ b/commands/index-repo.md
@@ -0,0 +1,165 @@
+---
+name: 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.
--- a/commands/pm.md
+++ b/commands/pm.md
@@ -0,0 +1,240 @@
+---
+name: pm
+description: PM Agent - Confidence-driven workflow orchestrator
+---
+
+# PM Agent Activation
+
+🚀 **PM Agent activated**
+
+## Session Start Protocol
+
+**IMMEDIATELY execute the following checks:**
+
+1. **Git Status Check**
+   - Run `git status --porcelain`
+   - Display: `📊 Git: {clean | X file(s) modified | not a git repo}`
+
+2. **Token Budget Awareness**
+   - Display: `💡 Check token budget with /context`
+
+3. **Ready Message**
+   - Display startup message with core capabilities
+
+```
+✅ PM Agent ready to accept tasks
+
+**Core Capabilities**:
+- 🔍 Pre-implementation confidence check (≥90% required)
+- ⚡ Parallel investigation and execution
+- 📊 Token-budget-aware operations
+
+**Usage**: Assign tasks directly - PM Agent will orchestrate
+```
+
+---
+
+## Confidence-Driven Workflow
+
+**CRITICAL**: When user assigns a task, follow this EXACT protocol:
+
+### Phase 1: Investigation Loop
+
+**Parameters:**
+- `MAX_ITERATIONS = 10`
+- `confidence_threshold = 0.90` (90%)
+- `iteration = 0`
+- `confidence = 0.0`
+
+**Loop Protocol:**
+```
+WHILE confidence < 0.90 AND iteration < MAX_ITERATIONS:
+  iteration++
+
+  Display: "🔄 Investigation iteration {iteration}..."
+
+  Execute Investigation Phase (see below)
+
+  Execute Confidence Check (see below)
+
+  Display: "📊 Confidence: {confidence}%"
+
+  IF confidence < 0.90:
+    Display: "⚠️ Confidence < 90% - Continue investigation"
+    CONTINUE loop
+  ELSE:
+    BREAK loop
+END WHILE
+
+IF confidence >= 0.90:
+  Display: "✅ High confidence (≥90%) - Proceeding to implementation"
+  Execute Implementation Phase
+ELSE:
+  Display: "❌ Max iterations reached - Request user clarification"
+  ASK user for more context
+END IF
+```
+
+### Phase 2: Investigation Phase
+
+**For EACH iteration, perform these checks in parallel:**
+
+Use **Wave → Checkpoint → Wave** pattern:
+
+**Wave 1: Parallel Investigation**
+Execute these searches simultaneously (multiple tool calls in one message):
+
+1. **Duplicate Check** (25% weight)
+   - `Grep` for similar function names
+   - `Glob` for related modules
+   - Check if functionality already exists
+
+2. **Architecture Check** (25% weight)
+   - Read `CLAUDE.md`, `PLANNING.md`
+   - Verify tech stack compliance
+   - Check existing patterns
+
+3. **Official Docs Verification** (20% weight)
+   - Search for library/framework docs
+   - Use Context7 MCP or WebFetch
+   - Verify API compatibility
+
+4. **OSS Reference Search** (15% weight)
+   - Use Tavily MCP or WebSearch
+   - Find working implementations
+   - Check GitHub examples
+
+5. **Root Cause Analysis** (15% weight)
+   - Analyze error messages
+   - Check logs, stack traces
+   - Identify actual problem source
+
+**Checkpoint: Analyze Results**
+
+After all parallel searches complete, synthesize findings.
+
+### Phase 3: Confidence Check
+
+**Calculate confidence score (0.0 - 1.0):**
+
+```
+confidence = 0.0
+
+Check 1: No Duplicate Implementations? (25%)
+  IF duplicate_check_complete:
+    confidence += 0.25
+    Display: "✅ No duplicate implementations found"
+  ELSE:
+    Display: "❌ Check for existing implementations first"
+
+Check 2: Architecture Compliance? (25%)
+  IF architecture_check_complete:
+    confidence += 0.25
+    Display: "✅ Uses existing tech stack"
+  ELSE:
+    Display: "❌ Verify architecture compliance (avoid reinventing)"
+
+Check 3: Official Documentation Verified? (20%)
+  IF official_docs_verified:
+    confidence += 0.20
+    Display: "✅ Official documentation verified"
+  ELSE:
+    Display: "❌ Read official docs first"
+
+Check 4: Working OSS Implementation Referenced? (15%)
+  IF oss_reference_complete:
+    confidence += 0.15
+    Display: "✅ Working OSS implementation found"
+  ELSE:
+    Display: "❌ Search for OSS implementations"
+
+Check 5: Root Cause Identified? (15%)
+  IF root_cause_identified:
+    confidence += 0.15
+    Display: "✅ Root cause identified"
+  ELSE:
+    Display: "❌ Continue investigation to identify root cause"
+```
+
+**Display Confidence Checks:**
+```
+📋 Confidence Checks:
+   {check 1 result}
+   {check 2 result}
+   {check 3 result}
+   {check 4 result}
+   {check 5 result}
+```
+
+### Phase 4: Implementation Phase
+
+**ONLY execute when confidence ≥ 90%**
+
+1. **Plan implementation** based on investigation findings
+2. **Use parallel execution** (Wave pattern) for file edits
+3. **Verify with tests** (no speculation)
+4. **Self-check** post-implementation
+
+---
+
+## Token Budget Allocation
+
+- **Simple** (typo fix): 200 tokens
+- **Medium** (bug fix): 1,000 tokens
+- **Complex** (feature): 2,500 tokens
+
+**Confidence Check ROI**: Spend 100-200 tokens to save 5,000-50,000 tokens
+
+---
+
+## MCP Server Integration
+
+**Prefer MCP tools over speculation:**
+
+- **Context7**: Official documentation lookup (prevent hallucination)
+- **Tavily**: Deep web research
+- **Sequential**: Token-efficient reasoning (30-50% reduction)
+- **Serena**: Session persistence
+
+---
+
+## Evidence-Based Development
+
+**NEVER guess** - always verify with:
+1. Official documentation (Context7 MCP, WebFetch)
+2. Actual codebase (Read, Grep, Glob)
+3. Tests (pytest, uv run pytest)
+
+---
+
+## Parallel Execution Pattern
+
+**Wave → Checkpoint → Wave**:
+- **Wave 1**: [Read files in parallel] using multiple tool calls in one message
+- **Checkpoint**: Analyze results, plan next wave
+- **Wave 2**: [Edit files in parallel] based on analysis
+
+**Performance**: 3.5x faster than sequential execution
+
+---
+
+## Self-Check Protocol (Post-Implementation)
+
+After implementation:
+1. Verify with tests/docs (NO speculation)
+2. Check for edge cases and error handling
+3. Validate against requirements
+4. If errors: Record pattern, store prevention strategy
+
+---
+
+## Memory Management
+
+**Zero-footprint**: No auto-load, explicit load/save only
+
+- Load: Use Serena MCP `read_memory`
+- Save: Use Serena MCP `write_memory`
+
+---
+
+**PM Agent is now active.** When you receive a task, IMMEDIATELY begin the Confidence-Driven Workflow loop.
--- a/commands/research.md
+++ b/commands/research.md
@@ -0,0 +1,122 @@
+---
+name: 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.
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/pm",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
--- a/index/index.ts
+++ b/index/index.ts
@@ -0,0 +1,270 @@
+/**
+ * Repository Indexing for Token Efficiency
+ *
+ * Problem: Loading全ファイルで毎回50,000トークン消費
+ * Solution: 最初だけインデックス作成、以降3,000トークンで済む (94%削減)
+ *
+ * Token Efficiency:
+ * Before: 58,000 tokens (read all files)
+ * After: 3,000 tokens (read PROJECT_INDEX.md)
+ * Savings: 94% (55,000 tokens)
+ */
+
+import { execSync } from 'child_process';
+import { readdirSync, statSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export interface IndexOptions {
+  root?: string;
+  mode?: 'full' | 'quick' | 'update';
+}
+
+export interface IndexResult {
+  path: string;
+  files: number;
+  quality: number;
+  duration: number;
+}
+
+/**
+ * Create repository index
+ *
+ * Parallel analysis (5 concurrent tasks):
+ * 1. Code structure (src/, lib/, superclaude/)
+ * 2. Documentation (docs/, *.md)
+ * 3. Configuration (.toml, .yaml, .json)
+ * 4. Tests (tests/, **tests**)
+ * 5. Scripts (scripts/, bin/, tools/)
+ *
+ * Output:
+ * - PROJECT_INDEX.md (3KB, human-readable)
+ * - PROJECT_INDEX.json (10KB, machine-readable)
+ *
+ * @param options - Indexing configuration
+ * @returns Index result
+ */
+export async function createIndex(options: IndexOptions = {}): Promise<IndexResult> {
+  const { root = process.cwd(), mode = 'full' } = options;
+
+  console.log("================================================================================");
+  console.log("🚀 Parallel Repository Indexing");
+  console.log("================================================================================");
+  console.log(`Repository: ${root}`);
+  console.log(`Mode: ${mode}`);
+  console.log("================================================================================");
+  console.log("");
+
+  const startTime = Date.now();
+
+  // Check if index exists and is fresh
+  if (mode === 'update' && isIndexFresh(root)) {
+    console.log("✅ Index is fresh (< 7 days old) - skipping");
+    return {
+      path: join(root, 'PROJECT_INDEX.md'),
+      files: 0,
+      quality: 100,
+      duration: 0
+    };
+  }
+
+  console.log("📊 Executing parallel tasks...");
+  console.log("");
+
+  // Execute parallel tasks
+  const [codeStructure, documentation, configuration, tests, scripts] = await Promise.all([
+    analyzeCodeStructure(root),
+    analyzeDocumentation(root),
+    analyzeConfiguration(root),
+    analyzeTests(root),
+    analyzeScripts(root)
+  ]);
+
+  console.log(`  ✅ code_structure: ${codeStructure.duration}ms`);
+  console.log(`  ✅ documentation: ${documentation.duration}ms`);
+  console.log(`  ✅ configuration: ${configuration.duration}ms`);
+  console.log(`  ✅ tests: ${tests.duration}ms`);
+  console.log(`  ✅ scripts: ${scripts.duration}ms`);
+  console.log("");
+
+  // Generate index content
+  const index = generateIndex({
+    root,
+    codeStructure,
+    documentation,
+    configuration,
+    tests,
+    scripts
+  });
+
+  // Write outputs
+  const indexPath = join(root, 'PROJECT_INDEX.md');
+  const jsonPath = join(root, 'PROJECT_INDEX.json');
+
+  writeFileSync(indexPath, index.markdown);
+  writeFileSync(jsonPath, JSON.stringify(index.json, null, 2));
+
+  const duration = Date.now() - startTime;
+
+  console.log("================================================================================");
+  console.log(`✅ Indexing complete in ${(duration / 1000).toFixed(2)}s`);
+  console.log("================================================================================");
+  console.log("");
+  console.log(`💾 Index saved to: PROJECT_INDEX.md`);
+  console.log(`💾 JSON saved to: PROJECT_INDEX.json`);
+  console.log("");
+  console.log(`Files: ${index.totalFiles} | Quality: ${index.quality}/100`);
+
+  return {
+    path: indexPath,
+    files: index.totalFiles,
+    quality: index.quality,
+    duration
+  };
+}
+
+/**
+ * Check if index is fresh (< 7 days old)
+ */
+function isIndexFresh(root: string): boolean {
+  try {
+    const stat = statSync(join(root, 'PROJECT_INDEX.md'));
+    const age = Date.now() - stat.mtimeMs;
+    const sevenDays = 7 * 24 * 60 * 60 * 1000;
+    return age < sevenDays;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Analyze code structure
+ */
+async function analyzeCodeStructure(root: string): Promise<any> {
+  const start = Date.now();
+  // Find src/, lib/, superclaude/ directories
+  const files = findFiles(root, ['src', 'lib', 'superclaude'], ['.ts', '.js', '.py']);
+  return {
+    files,
+    duration: Date.now() - start
+  };
+}
+
+/**
+ * Analyze documentation
+ */
+async function analyzeDocumentation(root: string): Promise<any> {
+  const start = Date.now();
+  // Find docs/ and *.md files
+  const files = findFiles(root, ['docs'], ['.md']);
+  return {
+    files,
+    duration: Date.now() - start
+  };
+}
+
+/**
+ * Analyze configuration
+ */
+async function analyzeConfiguration(root: string): Promise<any> {
+  const start = Date.now();
+  // Find .toml, .yaml, .json files
+  const files = findFiles(root, [root], ['.toml', '.yaml', '.json']);
+  return {
+    files,
+    duration: Date.now() - start
+  };
+}
+
+/**
+ * Analyze tests
+ */
+async function analyzeTests(root: string): Promise<any> {
+  const start = Date.now();
+  // Find tests/ directories
+  const files = findFiles(root, ['tests', 'test'], ['.ts', '.js', '.py']);
+  return {
+    files,
+    duration: Date.now() - start
+  };
+}
+
+/**
+ * Analyze scripts
+ */
+async function analyzeScripts(root: string): Promise<any> {
+  const start = Date.now();
+  // Find scripts/, bin/, tools/ directories
+  const files = findFiles(root, ['scripts', 'bin', 'tools'], ['.sh', '.js', '.py']);
+  return {
+    files,
+    duration: Date.now() - start
+  };
+}
+
+/**
+ * Find files in directories with extensions
+ */
+function findFiles(root: string, dirs: string[], extensions: string[]): string[] {
+  // Simplified file finder (real implementation would be more robust)
+  return [];
+}
+
+/**
+ * Generate index content
+ */
+function generateIndex(data: any): any {
+  const totalFiles =
+    data.codeStructure.files.length +
+    data.documentation.files.length +
+    data.configuration.files.length +
+    data.tests.files.length +
+    data.scripts.files.length;
+
+  const markdown = `# Project Index
+
+**Generated**: ${new Date().toISOString().split('T')[0]}
+**Repository**: ${data.root}
+**Total Files**: ${totalFiles}
+**Quality Score**: 90/100
+
+## 📂 Directory Structure
+
+### Code Structure
+- src/: ${data.codeStructure.files.length} files
+- lib/: (if exists)
+
+### Documentation
+- docs/: ${data.documentation.files.length} files
+
+### Configuration
+- Config files: ${data.configuration.files.length} files
+
+### Tests
+- tests/: ${data.tests.files.length} files
+
+### Scripts
+- scripts/: ${data.scripts.files.length} files
+`;
+
+  return {
+    markdown,
+    json: data,
+    totalFiles,
+    quality: 90
+  };
+}
+
+/**
+ * Auto-execution check
+ * Runs on PM Mode session start if index is stale
+ */
+export async function autoIndex(): Promise<void> {
+  const indexPath = join(process.cwd(), 'PROJECT_INDEX.md');
+
+  if (!isIndexFresh(process.cwd())) {
+    console.log("🔄 Creating repository index (stale or missing)...");
+    await createIndex();
+  } else {
+    console.log("✅ Repository index is fresh");
+  }
+}
--- a/index/package.json
+++ b/index/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@pm-agent/index",
+  "version": "1.0.0",
+  "description": "Repository structure index for fast context loading (94% token reduction)",
+  "main": "index.ts",
+  "scripts": {
+    "test": "jest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}
--- a/pm/confidence.ts
+++ b/pm/confidence.ts
@@ -0,0 +1,171 @@
+/**
+ * Confidence Check - Pre-implementation confidence assessment
+ *
+ * Prevents wrong-direction execution by assessing confidence BEFORE starting.
+ * Requires ≥90% confidence to proceed with implementation.
+ *
+ * Test Results (2025-10-21):
+ * - Precision: 1.000 (no false positives)
+ * - Recall: 1.000 (no false negatives)
+ * - 8/8 test cases passed
+ */
+
+export interface Context {
+  task?: string;
+  duplicate_check_complete?: boolean;
+  architecture_check_complete?: boolean;
+  official_docs_verified?: boolean;
+  oss_reference_complete?: boolean;
+  root_cause_identified?: boolean;
+  confidence_checks?: string[];
+  [key: string]: any;
+}
+
+/**
+ * Assess confidence level (0.0 - 1.0)
+ *
+ * Investigation Phase Checks:
+ * 1. No duplicate implementations? (25%)
+ * 2. Architecture compliance? (25%)
+ * 3. Official documentation verified? (20%)
+ * 4. Working OSS implementations referenced? (15%)
+ * 5. Root cause identified? (15%)
+ *
+ * @param context - Task context with investigation flags
+ * @returns Confidence score (0.0 = no confidence, 1.0 = absolute certainty)
+ */
+export async function confidenceCheck(context: Context): Promise<number> {
+  let score = 0.0;
+  const checks: string[] = [];
+
+  // Check 1: No duplicate implementations (25%)
+  if (noDuplicates(context)) {
+    score += 0.25;
+    checks.push("✅ No duplicate implementations found");
+  } else {
+    checks.push("❌ Check for existing implementations first");
+  }
+
+  // Check 2: Architecture compliance (25%)
+  if (architectureCompliant(context)) {
+    score += 0.25;
+    checks.push("✅ Uses existing tech stack (e.g., Supabase)");
+  } else {
+    checks.push("❌ Verify architecture compliance (avoid reinventing)");
+  }
+
+  // Check 3: Official documentation verified (20%)
+  if (hasOfficialDocs(context)) {
+    score += 0.2;
+    checks.push("✅ Official documentation verified");
+  } else {
+    checks.push("❌ Read official docs first");
+  }
+
+  // Check 4: Working OSS implementations referenced (15%)
+  if (hasOssReference(context)) {
+    score += 0.15;
+    checks.push("✅ Working OSS implementation found");
+  } else {
+    checks.push("❌ Search for OSS implementations");
+  }
+
+  // Check 5: Root cause identified (15%)
+  if (rootCauseIdentified(context)) {
+    score += 0.15;
+    checks.push("✅ Root cause identified");
+  } else {
+    checks.push("❌ Continue investigation to identify root cause");
+  }
+
+  // Store check results
+  context.confidence_checks = checks;
+
+  // Display checks
+  console.log("📋 Confidence Checks:");
+  checks.forEach(check => console.log(`   ${check}`));
+  console.log("");
+
+  return score;
+}
+
+/**
+ * Check for duplicate implementations
+ *
+ * Before implementing, verify:
+ * - No existing similar functions/modules (Glob/Grep)
+ * - No helper functions that solve the same problem
+ * - No libraries that provide this functionality
+ */
+function noDuplicates(context: Context): boolean {
+  return context.duplicate_check_complete ?? false;
+}
+
+/**
+ * Check architecture compliance
+ *
+ * Verify solution uses existing tech stack:
+ * - Supabase project → Use Supabase APIs (not custom API)
+ * - Next.js project → Use Next.js patterns (not custom routing)
+ * - Turborepo → Use workspace patterns (not manual scripts)
+ */
+function architectureCompliant(context: Context): boolean {
+  return context.architecture_check_complete ?? false;
+}
+
+/**
+ * Check if official documentation verified
+ *
+ * For testing: uses context flag 'official_docs_verified'
+ * For production: checks for README.md, CLAUDE.md, docs/ directory
+ */
+function hasOfficialDocs(context: Context): boolean {
+  // Check context flag (for testing and runtime)
+  if ('official_docs_verified' in context) {
+    return context.official_docs_verified ?? false;
+  }
+
+  // Fallback: check for documentation files (production)
+  // This would require filesystem access in Node.js
+  return false;
+}
+
+/**
+ * Check if working OSS implementations referenced
+ *
+ * Search for:
+ * - Similar open-source solutions
+ * - Reference implementations in popular projects
+ * - Community best practices
+ */
+function hasOssReference(context: Context): boolean {
+  return context.oss_reference_complete ?? false;
+}
+
+/**
+ * Check if root cause is identified with high certainty
+ *
+ * Verify:
+ * - Problem source pinpointed (not guessing)
+ * - Solution addresses root cause (not symptoms)
+ * - Fix verified against official docs/OSS patterns
+ */
+function rootCauseIdentified(context: Context): boolean {
+  return context.root_cause_identified ?? false;
+}
+
+/**
+ * Get recommended action based on confidence level
+ *
+ * @param confidence - Confidence score (0.0 - 1.0)
+ * @returns Recommended action
+ */
+export function getRecommendation(confidence: number): string {
+  if (confidence >= 0.9) {
+    return "✅ High confidence (≥90%) - Proceed with implementation";
+  } else if (confidence >= 0.7) {
+    return "⚠️ Medium confidence (70-89%) - Continue investigation, DO NOT implement yet";
+  } else {
+    return "❌ Low confidence (<70%) - STOP and continue investigation loop";
+  }
+}
--- a/pm/index.ts
+++ b/pm/index.ts
@@ -0,0 +1,159 @@
+/**
+ * PM Agent - Project Manager with Confidence-Driven Workflow
+ *
+ * Auto-executes on session start via hooks/hooks.json
+ * Orchestrates sub-agents with 90% confidence threshold
+ */
+
+import { execSync } from 'child_process';
+import { confidenceCheck } from './confidence';
+
+interface SessionContext {
+  gitStatus: string;
+  tokenBudget: number;
+  projectRoot: string;
+}
+
+/**
+ * Session Start Protocol
+ * Auto-executes when Claude Code starts
+ */
+export async function sessionStart(): Promise<void> {
+  console.log("🚀 PM Agent activated");
+
+  // 1. Check git status
+  const gitStatus = checkGitStatus();
+  console.log(`📊 Git: ${gitStatus}`);
+
+  // 2. Token budget check (from Claude Code UI)
+  console.log("💡 Check token budget with /context");
+
+  // 3. Ready
+  console.log("✅ PM Agent ready to accept tasks");
+  console.log("");
+  console.log("**Core Capabilities**:");
+  console.log("- 🔍 Pre-implementation confidence check (≥90% required)");
+  console.log("- ⚡ Parallel investigation and execution");
+  console.log("- 📊 Token-budget-aware operations");
+  console.log("");
+  console.log("**Usage**: Assign tasks directly - PM Agent will orchestrate");
+}
+
+/**
+ * Check git repository status
+ */
+function checkGitStatus(): string {
+  try {
+    const status = execSync('git status --porcelain', { encoding: 'utf-8' });
+    if (!status.trim()) {
+      return 'clean';
+    }
+    const lines = status.trim().split('\n').length;
+    return `${lines} file(s) modified`;
+  } catch {
+    return 'not a git repo';
+  }
+}
+
+/**
+ * Main task handler
+ * Called when user assigns a task
+ */
+export async function handleTask(task: string): Promise<void> {
+  console.log(`📝 Task received: ${task}`);
+  console.log("");
+
+  // Start confidence-driven workflow
+  await confidenceDrivenWorkflow(task);
+}
+
+/**
+ * Confidence-Driven Workflow
+ *
+ * 1. Investigation phase (loop until 90% confident)
+ * 2. Confidence check
+ * 3. Implementation (only when ≥90%)
+ */
+async function confidenceDrivenWorkflow(task: string): Promise<void> {
+  let confidence = 0;
+  let iteration = 0;
+  const MAX_ITERATIONS = 10;
+
+  console.log("🔍 Starting investigation phase...");
+  console.log("");
+
+  while (confidence < 0.9 && iteration < MAX_ITERATIONS) {
+    iteration++;
+    console.log(`🔄 Investigation iteration ${iteration}...`);
+
+    // Investigation actions (delegated to sub-agents)
+    const context = await investigate(task);
+
+    // Self-evaluate confidence
+    confidence = await confidenceCheck(context);
+
+    console.log(`📊 Confidence: ${(confidence * 100).toFixed(0)}%`);
+
+    if (confidence < 0.9) {
+      console.log("⚠️ Confidence < 90% - Continue investigation");
+      console.log("");
+    }
+  }
+
+  if (confidence >= 0.9) {
+    console.log("✅ High confidence (≥90%) - Proceeding to implementation");
+    console.log("");
+    // Implementation phase
+    await implement(task);
+  } else {
+    console.log("❌ Max iterations reached - Request user clarification");
+  }
+}
+
+/**
+ * Investigation phase
+ * Delegates to sub-agents: research, index, grep, etc.
+ */
+async function investigate(task: string): Promise<any> {
+  // This will be orchestrated by Claude using:
+  // - /research for web research
+  // - /index-repo for codebase structure
+  // - Glob/Grep for code search
+  // - WebFetch for official docs
+
+  return {
+    task,
+    duplicate_check_complete: false,
+    architecture_check_complete: false,
+    official_docs_verified: false,
+    oss_reference_complete: false,
+    root_cause_identified: false
+  };
+}
+
+/**
+ * Implementation phase
+ * Only executed when confidence ≥ 90%
+ */
+async function implement(task: string): Promise<void> {
+  console.log(`🚀 Implementing: ${task}`);
+  // Actual implementation delegated to Claude
+}
+
+/**
+ * Memory Management (Mindbase MCP integration)
+ * Zero-footprint: No auto-load, explicit load/save only
+ */
+export const memory = {
+  load: async () => {
+    console.log("💾 Use /sc:load to load context from Mindbase MCP");
+  },
+  save: async () => {
+    console.log("💾 Use /sc:save to persist session to Mindbase MCP");
+  }
+};
+
+// Auto-execute on session start
+if (require.main === module) {
+  sessionStart();
+}
--- a/pm/package.json
+++ b/pm/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "@pm-agent/core",
+  "version": "1.0.0",
+  "description": "PM Agent - Project Manager with 90% confidence checks",
+  "main": "index.ts",
+  "scripts": {
+    "test": "jest",
+    "build": "tsc"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
--- a/research/index.ts
+++ b/research/index.ts
@@ -0,0 +1,207 @@
+/**
+ * Research Agent - Deep web research with adaptive planning
+ *
+ * Features:
+ * - Adaptive depth control (quick, standard, deep, exhaustive)
+ * - Parallel-first search execution
+ * - Multi-hop exploration
+ * - Evidence-based synthesis
+ *
+ * MCP Integration:
+ * - Tavily: Primary search and extraction
+ * - Sequential: Complex reasoning
+ * - Playwright: JavaScript-heavy content
+ * - Serena: Session persistence
+ */
+
+export interface ResearchOptions {
+  query: string;
+  depth?: 'quick' | 'standard' | 'deep' | 'exhaustive';
+  strategy?: 'planning' | 'intent' | 'unified';
+}
+
+export interface ResearchResult {
+  summary: string;
+  sources: Source[];
+  confidence: number;
+  timestamp: string;
+}
+
+interface Source {
+  url: string;
+  title: string;
+  excerpt: string;
+  credibility: number;
+}
+
+/**
+ * Execute deep research
+ *
+ * Flow:
+ * 1. Understand (5-10% effort)
+ * 2. Plan (10-15% effort)
+ * 3. TodoWrite (5% effort)
+ * 4. Execute (50-60% effort)
+ * 5. Track (Continuous)
+ * 6. Validate (10-15% effort)
+ *
+ * @param options - Research configuration
+ * @returns Research results with sources
+ */
+export async function research(options: ResearchOptions): Promise<ResearchResult> {
+  const { query, depth = 'standard', strategy = 'unified' } = options;
+
+  console.log(`🔍 Starting ${depth} research: ${query}`);
+  console.log(`📊 Strategy: ${strategy}`);
+  console.log("");
+
+  // 1. Understand (5-10% effort)
+  const context = await understand(query);
+  console.log(`✅ Understanding complete (complexity: ${context.complexity})`);
+
+  // 2. Plan (10-15% effort)
+  const plan = await createPlan(context, depth, strategy);
+  console.log(`✅ Research plan created (${plan.tasks.length} tasks)`);
+
+  // 3. TodoWrite (5% effort)
+  console.log(`📝 Creating task list...`);
+  // TodoWrite integration would go here
+
+  // 4. Execute (50-60% effort)
+  console.log(`🚀 Executing research...`);
+  const results = await execute(plan);
+
+  // 5. Validate (10-15% effort)
+  console.log(`🔍 Validating results...`);
+  const validated = await validate(results);
+
+  // 6. Generate report
+  const report = await generateReport(validated, query, depth);
+
+  return report;
+}
+
+/**
+ * Phase 1: Understand query
+ */
+async function understand(query: string): Promise<any> {
+  return {
+    query,
+    complexity: assessComplexity(query),
+    requiredInformation: identifyRequirements(query),
+    resourceNeeds: 'web_search',
+    successCriteria: ['evidence', 'credibility', 'completeness']
+  };
+}
+
+function assessComplexity(query: string): 'simple' | 'moderate' | 'complex' {
+  // Heuristic: word count, question type, etc.
+  if (query.length < 50) return 'simple';
+  if (query.length < 150) return 'moderate';
+  return 'complex';
+}
+
+function identifyRequirements(query: string): string[] {
+  // Identify what type of information is needed
+  return ['facts', 'sources', 'analysis'];
+}
+
+/**
+ * Phase 2: Create research plan
+ */
+async function createPlan(context: any, depth: string, strategy: string): Promise<any> {
+  const hops = getHopCount(depth);
+
+  return {
+    strategy,
+    tasks: generateTasks(context, hops),
+    parallelizationPlan: identifyParallelTasks(context),
+    milestones: createMilestones(hops)
+  };
+}
+
+function getHopCount(depth: string): number {
+  const hopMap = {
+    'quick': 1,
+    'standard': 2-3,
+    'deep': 3-4,
+    'exhaustive': 5
+  };
+  return hopMap[depth] || 2;
+}
+
+function generateTasks(context: any, hops: number): any[] {
+  // Generate research tasks based on context and depth
+  return [];
+}
+
+function identifyParallelTasks(context: any): any[] {
+  // Identify which searches can run in parallel
+  return [];
+}
+
+function createMilestones(hops: number): string[] {
+  return [`Complete hop ${hop}` for (let hop = 1; hop <= hops; hop++)];
+}
+
+/**
+ * Phase 4: Execute research
+ */
+async function execute(plan: any): Promise<any> {
+  // Execute searches (parallel-first approach)
+  // This would integrate with Tavily MCP, WebSearch, etc.
+
+  return {
+    findings: [],
+    sources: [],
+    confidence: 0.8
+  };
+}
+
+/**
+ * Phase 5: Validate results
+ */
+async function validate(results: any): Promise<any> {
+  // Verify evidence chains
+  // Check source credibility
+  // Resolve contradictions
+  // Ensure completeness
+
+  return {
+    ...results,
+    validated: true,
+    contradictions: [],
+    gaps: []
+  };
+}
+
+/**
+ * Phase 6: Generate report
+ */
+async function generateReport(data: any, query: string, depth: string): Promise<ResearchResult> {
+  const timestamp = new Date().toISOString();
+  const filename = `docs/research/${slugify(query)}_${timestamp.split('T')[0]}.md`;
+
+  console.log(`💾 Saving report to: ${filename}`);
+
+  return {
+    summary: `Research on: ${query}`,
+    sources: data.sources || [],
+    confidence: data.confidence || 0.8,
+    timestamp
+  };
+}
+
+function slugify(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '_');
+}
+
+/**
+ * Adaptive depth examples
+ */
+export const examples = {
+  quick: "/research 'latest quantum computing news' --depth quick",
+  standard: "/research 'competitive analysis of AI coding assistants'",
+  deep: "/research 'distributed systems best practices' --depth deep",
+  exhaustive: "/research 'self-improving AI agents' --depth exhaustive"
+};
--- a/research/package.json
+++ b/research/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@pm-agent/research",
+  "version": "1.0.0",
+  "description": "Deep web research with adaptive planning and intelligent search",
+  "main": "index.ts",
+  "scripts": {
+    "test": "jest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}