SuperClaude_Framework Documentation

~/.claude/superclaude/
├── framework/              # 全フレームワークドキュメント
│   ├── flags.md           # ~5KB
│   ├── principles.md      # ~8KB
│   ├── rules.md           # ~15KB
│   └── ...
├── business/              # ビジネスパネル全体
│   ├── examples.md        # ~20KB
│   ├── symbols.md         # ~10KB
│   └── ...
├── research/              # リサーチ設定全体
│   └── config.md          # ~10KB
├── commands/              # 全コマンド
│   ├── sc_brainstorm.md
│   ├── sc_test.md
│   ├── sc_cleanup.md
│   ├── ... (30+ files)
└── modes/                 # 全モード
    ├── MODE_Brainstorming.md
    ├── MODE_Business_Panel.md
    ├── ... (7 files)

Total: ~210KB (推定 50K-60K tokens)

site-packages/superclaude/
├── __init__.py            # Package metadata (~0.5KB)
├── pytest_plugin.py       # Plugin entry point (~6KB)
├── pm_agent/              # PM Agentコアのみ
│   ├── __init__.py
│   ├── confidence.py      # ~8KB
│   ├── self_check.py      # ~15KB
│   ├── reflexion.py       # ~12KB
│   └── token_budget.py    # ~10KB
├── execution/             # 実行エンジン
│   ├── parallel.py        # ~15KB
│   ├── reflection.py      # ~8KB
│   └── self_correction.py # ~10KB
└── cli/                   # CLI（使用時のみ）
    ├── main.py            # ~3KB
    ├── doctor.py          # ~4KB
    └── install_skill.py   # ~3KB

Total: ~88KB (推定 20K-25K tokens)

MCP tools (AIRIS Gateway後):     5K tokens  (PR #449で改善済み)
Memory files (~/.claude/):       50K tokens  (全ドキュメント読み込み)
SuperClaude components:          10K tokens  (Component/Installer)
─────────────────────────────────────────
Total consumed:                  65K tokens
Available for user:              135K tokens (65%)

MCP tools (AIRIS Gateway):        5K tokens  (同じ)
Memory files (~/.claude/):        0K tokens  (何もインストールしない)
SuperClaude pytest plugin:       20K tokens  (pytest起動時のみ)
─────────────────────────────────────────
Total consumed (session start):   5K tokens
Available for user:             195K tokens (97%)

※ pytest実行時: +20K tokens (テスト時のみ)

PM Agent Skill全体読み込み:
├── implementation.md          # ~25KB = 6K tokens
├── modules/
│   ├── git-status.md          # ~5KB = 1.2K tokens
│   ├── token-counter.md       # ~8KB = 2K tokens
│   └── pm-formatter.md        # ~10KB = 2.5K tokens
└── 関連ドキュメント           # ~20KB = 5K tokens
─────────────────────────────────────────
Total:                         ~17K tokens

PM Agentコアのみインポート:
├── confidence.py              # ~8KB = 2K tokens
├── self_check.py              # ~15KB = 3.5K tokens
├── reflexion.py               # ~12KB = 3K tokens
└── token_budget.py            # ~10KB = 2.5K tokens
─────────────────────────────────────────
Total:                         ~11K tokens

全Skills強制インストール:      50K tokens

デフォルト: 0K tokens
ユーザーが install-skill実行後: 使った分だけ

# Before/After同一テストスイート
uv run pytest tests/pm_agent/ -v

Result: 79 passed ✅

# Plugin auto-discovery確認
uv run pytest tests/test_pytest_plugin.py -v

Result: 18 passed ✅

# インストール正常性確認
make doctor

Result:
✅ pytest plugin loaded
✅ Skills installed (optional)
✅ Configuration
✅ SuperClaude is healthy

# pytest起動時に全モジュールimport
from superclaude.pm_agent import confidence, self_check, reflexion, token_budget

# 使用時のみimport
def confidence_checker():
    from superclaude.pm_agent.confidence import ConfidenceChecker
    return ConfidenceChecker()

# 事前にインストール必要
superclaude install-skill pm-agent

# 使用時に自動ダウンロード & キャッシュ
@pytest.mark.usefixtures("pm_agent_skill")  # 自動fetch
def test_example():
    ...

Problem:
  - Installs to ~/.claude/superclaude/ (pollutes Claude Code)
  - Complex Component/Installer infrastructure (468-line base class)
  - Skills vs Commands混在 (2つのメカニズム)
  - setup.py packaging (deprecated)

Impact:
  - Claude Code directory pollution
  - Difficult to maintain
  - Not pip-installable cleanly
  - Confusing for users

Solution:
  - Python package in site-packages/ only
  - pytest plugin via entry points (auto-discovery)
  - Optional Skills (user choice to install)
  - PEP 517 src/ layout (modern packaging)

Benefits:
  ✅ Zero ~/.claude/ pollution (unless user wants skills)
  ✅ pip install superclaude → pytest auto-loads
  ✅ Standard pytest plugin architecture
  ✅ Clear separation: core vs user config
  ✅ Tests stay in project root (not installed)

/* Detailed source-code truncated for AI context efficiency. */

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "superclaude"
version = "0.4.0"
description = "AI-enhanced development framework for Claude Code"
readme = "README.md"
license = {file = "LICENSE"}
authors = [
    {name = "Kazuki Nakai"}
]
requires-python = ">=3.10"
dependencies = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest-benchmark>=4.0.0",
    "scipy>=1.10.0",  # For A/B testing
]

# ⭐ pytest plugin auto-discovery
[project.entry-points.pytest11]
superclaude = "superclaude.pytest_plugin"

# ⭐ CLI commands
[project.entry-points.console_scripts]
superclaude = "superclaude.cli.main:main"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = [
    "-v",
    "--strict-markers",
    "--tb=short",
]
markers = [
    "unit: Unit tests",
    "integration: Integration tests",
    "hallucination: Hallucination detection tests",
    "performance: Performance benchmark tests",
]

[tool.hatch.build.targets.wheel]
packages = ["src/superclaude"]

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

pytest tests/test_confidence_check.py -v
pytest tests/test_self_check_protocol.py -v
pytest tests/test_token_budget.py -v
pytest tests/test_reflexion_pattern.py -v

# tests/test_pytest_plugin.py

def test_plugin_loads(pytester):
    """Test that superclaude plugin loads correctly"""
    pytester.makeconftest("""
        pytest_plugins = ['superclaude.pytest_plugin']
    """)

    result = pytester.runpytest("--trace-config")
    result.stdout.fnmatch_lines(["*superclaude*"])


def test_confidence_checker_fixture(pytester):
    """Test confidence_checker fixture availability"""
    pytester.makepyfile("""
        def test_example(confidence_checker):
            assert confidence_checker is not None
            confidence = confidence_checker.assess({})
            assert 0.0 <= confidence <= 1.0
    """)

    result = pytester.runpytest()
    result.assert_outcomes(passed=1)

# Clean install
pip uninstall superclaude -y
pip install -e .

# Verify plugin loaded
pytest --trace-config | grep superclaude

# Verify CLI
superclaude --version
superclaude doctor

# Verify ~/.claude/ clean
ls ~/.claude/  # Should not have superclaude/ unless skill installed

# Install from PyPI (future)
pip install superclaude

# Install from source (development)
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install -e .

# Verify installation
superclaude doctor

# Optional: Install PM Agent skill
superclaude install-skill pm-agent

# Clone repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Check pytest plugin
pytest --trace-config

src/superclaude/
├── __init__.py              # Package entry point (version, exports)
├── pytest_plugin.py         # ⭐ Pytest auto-discovery entry point
├── pm_agent/                # PM Agent core modules
│   ├── __init__.py
│   ├── confidence.py        # Pre-execution confidence checking
│   ├── self_check.py        # Post-implementation validation
│   ├── reflexion.py         # Error learning pattern
│   └── token_budget.py      # Complexity-based budget allocation
├── execution/               # Execution engines (renamed from core)
│   ├── __init__.py
│   ├── parallel.py          # Parallel execution engine
│   ├── reflection.py        # Reflection engine
│   └── self_correction.py   # Self-correction engine
└── cli/                     # CLI commands
    ├── __init__.py
    ├── main.py              # Click CLI entry point
    ├── doctor.py            # Health check command
    └── install_skill.py     # Skill installation command

$ uv run python -m pytest --trace-config | grep superclaude
PLUGIN registered: <module 'superclaude.pytest_plugin' from '.../src/superclaude/pytest_plugin.py'>
registered third-party plugins:
  superclaude-0.4.0 at .../src/superclaude/pytest_plugin.py

[project.entry-points.pytest11]
superclaude = "superclaude.pytest_plugin"

$ uv run superclaude --version
SuperClaude version 0.4.0

$ uv run superclaude doctor
🔍 SuperClaude Doctor

✅ pytest plugin loaded
✅ Skills installed
✅ Configuration

✅ SuperClaude is healthy

# 1. Package installed in correct location
$ uv run python -c "import superclaude; print(superclaude.__file__)"
/Users/kazuki/github/superclaude/src/superclaude/__init__.py

# 2. Pytest plugin registered
$ uv run python -m pytest --trace-config | grep superclaude
superclaude-0.4.0 at .../src/superclaude/pytest_plugin.py

# 3. CLI works
$ uv run superclaude --version
SuperClaude version 0.4.0

# 4. Doctor check passes
$ uv run superclaude doctor
✅ SuperClaude is healthy

collected 115 items / 12 errors

# SuperClaude pytest plugin auto-loads these fixtures:
# - confidence_checker
# - self_check_protocol
# - reflexion_pattern
# - token_budget
# - pm_context

$ uv run pytest tests/test_pytest_plugin.py -v
======================== 18 passed in 0.02s =========================

$ uv run pytest tests/pm_agent/ -v
======================== 79 passed, 1 warning in 0.03s =========================

PM Agent Tests:        79 passed
Plugin Tests:          18 passed
─────────────────────────────────
Total:                 97 passed ✅

ERROR tests/core/pm_init/test_init_hook.py        # superclaude.context
ERROR tests/test_cli_smoke.py                      # superclaude.cli.app
ERROR tests/test_mcp_component.py                  # setup.components.mcp
ERROR tests/validators/test_validators.py          # superclaude.validators

$ uv run pytest --trace-config | grep superclaude
PLUGIN registered: <module 'superclaude.pytest_plugin' from '.../src/superclaude/pytest_plugin.py'>
registered third-party plugins:
  superclaude-0.4.0 at .../src/superclaude/pytest_plugin.py

def test_example(confidence_checker, token_budget, pm_context):
    # All fixtures automatically available via pytest plugin
    confidence = confidence_checker.assess({})
    assert 0.0 <= confidence <= 1.0

@pytest.mark.confidence_check
def test_with_confidence():
    ...

@pytest.mark.self_check
def test_with_validation():
    ...

# Run all tests
make test

# Test pytest plugin loading
make test-plugin

# Run health check
make doctor

# Comprehensive Phase 1 verification
make verify

$ make verify
🔍 Phase 1 Installation Verification
======================================

1. Package location:
   /Users/kazuki/github/superclaude/src/superclaude/__init__.py

2. Package version:
   SuperClaude, version 0.4.0

3. Pytest plugin:
   superclaude-0.4.0 at .../src/superclaude/pytest_plugin.py
   ✅ Plugin loaded

4. Health check:
   ✅ All checks passed

======================================
✅ Phase 1 verification complete

# ❌ Wrong
remaining = token_budget.remaining()  # TypeError

# ✅ Correct
remaining = token_budget.remaining    # Property access

# ❌ Wrong
markers = {marker.name for marker in pytestconfig.getini("markers")}

# ✅ Correct
markers_str = "\n".join(pytestconfig.getini("markers"))
assert "confidence_check" in markers_str

uv pip install -e ".[dev]"

Resolved 24 packages in 4ms
Built superclaude @ file:///Users/kazuki/github/superclaude
Prepared 1 package in 154ms
Uninstalled 1 package in 0.54ms
Installed 1 package in 1ms
 ~ superclaude==0.4.0 (from file:///Users/kazuki/github/superclaude)

uv run python -m pytest --trace-config 2>&1 | grep "registered third-party plugins:"

registered third-party plugins:
  superclaude-0.4.0 at /Users/kazuki/github/superclaude/src/superclaude/pytest_plugin.py

[project.entry-points.pytest11]
superclaude = "superclaude.pytest_plugin"

~/.claude/
└── superclaude/                    # ❌ Framework files polluted user config
    ├── framework/
    ├── business/
    ├── modules/
    └── .superclaude-metadata.json

~/.claude/
├── skills/                         # ✅ User-installed skills only
│   ├── pm/                         # Optional PM Agent skill
│   ├── brainstorming-mode/
│   └── ...
└── (NO superclaude/ directory)     # ✅ Zero framework pollution

uv run superclaude doctor --verbose

🔍 SuperClaude Doctor

✅ pytest plugin loaded
    SuperClaude pytest plugin is active
✅ Skills installed
    9 skill(s) installed: pm, token-efficiency-mode, pm.backup, ...
✅ Configuration
    SuperClaude 0.4.0 installed correctly

✅ SuperClaude is healthy

$ uv run pytest tests/pm_agent/ -v
======================== 79 passed, 1 warning in 0.03s =========================

$ uv run pytest tests/test_pytest_plugin.py -v
============================== 18 passed in 0.02s ==============================

Location: /Users/kazuki/github/superclaude/src/superclaude/__init__.py
Version: 0.4.0

superclaude doctor              # Health check
superclaude install-skill <name>  # Install Skills (optional)
superclaude version             # Show version
superclaude --help              # Show help

make install        # Development installation
make test           # Run all tests
make test-plugin    # Test plugin loading
make doctor         # Health check
make verify         # Comprehensive verification
make clean          # Clean artifacts

src/superclaude/
├── pm_agent/          # Core PM Agent functionality
├── execution/         # Execution engine (parallel, reflection)
├── cli/               # CLI interface
└── pytest_plugin.py   # Test integration

~/.claude/skills/
├── pm/                # PM Agent Skill (optional auto-activation)
├── modes/             # Behavioral modes (optional)
└── ...                # Other skills (optional)

uv pip install -e .
# Result: pytest plugin + PM Agent core

superclaude install-skill pm-agent
# Result: Auto-activation + PDCA docs + Upstream compatibility

def test_example(confidence_checker, token_budget, pm_context):
    # Fixtures automatically available
    confidence = confidence_checker.assess({})
    assert 0.0 <= confidence <= 1.0

[project.entry-points.pytest11]
superclaude = "superclaude.pytest_plugin"

ERROR tests/core/pm_init/test_init_hook.py        # Old init hooks
ERROR tests/test_cli_smoke.py                      # Old CLI structure
ERROR tests/test_mcp_component.py                  # Old setup system
ERROR tests/validators/test_validators.py          # Old validators

# tests/test_example.py
def test_with_pm_agent(confidence_checker, token_budget):
    confidence = confidence_checker.assess(context)
    assert confidence > 0.7

# Claude Code session start
/sc:pm  # Auto-loads from ~/.claude/skills/pm/
# Output: 🟢 [integration] | 2M 103D | 68%

superclaude install  # Installs to ~/.claude/superclaude/

pip install superclaude  # Standard Python package

# Optional: Install Skills for auto-activation
superclaude install-skill pm-agent

~/.claude/
└── skills/
    └── pm/                              # PM Agent Skill
        ├── implementation.md            # ~25KB - 全ワークフロー
        ├── modules/
        │   ├── git-status.md            # ~5KB - Git状態フォーマット
        │   ├── token-counter.md         # ~8KB - トークンカウント
        │   └── pm-formatter.md          # ~10KB - ステータス出力
        └── workflows/
            └── task-management.md       # ~15KB - タスク管理

superclaude/
├── agents/
│   └── pm-agent.md                      # ~50KB - Agent定義
├── commands/
│   └── pm.md                            # ~5KB - /sc:pm command
└── core/
    └── pm_init/                         # Python init hooks
        ├── __init__.py
        ├── context_contract.py          # ~10KB - Context管理
        ├── init_hook.py                 # ~10KB - Session start
        └── reflexion_memory.py          # ~12KB - Reflexion

Total: ~150KB ≈ 35K-40K tokens

src/superclaude/
└── pm_agent/                            # Python package
    ├── __init__.py                      # Package exports
    ├── confidence.py                    # ~8KB - Pre-execution
    ├── self_check.py                    # ~15KB - Post-validation
    ├── reflexion.py                     # ~12KB - Error learning
    └── token_budget.py                  # ~10KB - Budget management

tests/pm_agent/
├── test_confidence_check.py             # 18 tests
├── test_self_check_protocol.py          # 16 tests
├── test_reflexion_pattern.py            # 16 tests
└── test_token_budget.py                 # 29 tests

Total: ~45KB ≈ 10K-12K tokens (import時のみ)

Trigger: EVERY session start (自動)
Method: pm_init/init_hook.py

Actions:
  1. PARALLEL Read:
     - docs/memory/pm_context.md
     - docs/memory/last_session.md
     - docs/memory/next_actions.md
     - docs/memory/current_plan.json
  2. Confidence Check (200 tokens)
  3. Output: 🟢 [branch] | [n]M [n]D | [token]%

Token Cost: ~8K (memory files) + 200 (confidence)

# 自動実行なし - 手動で呼び出し
from superclaude.pm_agent.confidence import ConfidenceChecker

checker = ConfidenceChecker()
confidence = checker.assess(context)

Token Cost: ~2K (confidence moduleのみ)

# superclaude/agents/pm-agent.md より

Confidence Check (200 tokens):
  ❓ "全ファイル読めた？"
  ❓ "コンテキストに矛盾ない？"
  ❓ "次のアクション実行に十分な情報？"

Output: Markdown形式
Location: Agent definition内

# src/superclaude/pm_agent/confidence.py

class ConfidenceChecker:
    def assess(self, context: Dict[str, Any]) -> float:
        """
        Assess confidence (0.0-1.0)

        Checks:
        1. Documentation verified? (40%)
        2. Patterns identified? (30%)
        3. Implementation clear? (30%)

        Budget: 100-200 tokens
        """
        # Python実装
        return confidence_score

# agents/pm-agent.md より

Self-Evaluation Checklist:
  - [ ] Did I follow architecture patterns?
  - [ ] Did I read documentation first?
  - [ ] Did I check existing implementations?
  - [ ] Are all tasks complete?
  - [ ] What mistakes did I make?
  - [ ] What did I learn?

Token Budget:
  Simple: 200 tokens
  Medium: 1,000 tokens
  Complex: 2,500 tokens

Output: docs/pdca/[feature]/check.md

# src/superclaude/pm_agent/self_check.py

class SelfCheckProtocol:
    def validate(self, implementation: Dict[str, Any])
        -> Tuple[bool, List[str]]:
        """
        Four Questions Protocol:
        1. All tests pass?
        2. Requirements met?
        3. Assumptions verified?
        4. Evidence exists?

        7 Hallucination Red Flags detection

        Returns: (passed, issues)
        """
        # Python実装

# superclaude/core/pm_init/reflexion_memory.py

class ReflexionMemory:
    """
    Error learning with dual storage:
    1. Local JSONL: docs/memory/solutions_learned.jsonl
    2. Mindbase: Semantic search (if available)

    Lookup: mindbase → grep fallback
    """

# src/superclaude/pm_agent/reflexion.py

class ReflexionPattern:
    """
    Same dual storage strategy:
    1. Local JSONL: docs/memory/solutions_learned.jsonl
    2. Mindbase: Semantic search (optional)

    Methods:
    - get_solution(error_info) → past solution lookup
    - record_error(error_info) → save to memory
    - get_statistics() → recurrence rate
    """

# agents/pm-agent.md より

Token Budget (Complexity-Based):
  Simple Task (typo): 200 tokens
  Medium Task (bug): 1,000 tokens
  Complex Task (feature): 2,500 tokens

Implementation: Markdown定義のみ
Enforcement: 手動

# src/superclaude/pm_agent/token_budget.py

class TokenBudgetManager:
    BUDGETS = {
        "simple": 200,
        "medium": 1000,
        "complex": 2500,
    }

    def use(self, tokens: int) -> bool:
        """Track usage"""

    @property
    def remaining(self) -> int:
        """Get remaining budget"""

    def get_recommendation(self) -> str:
        """Suggest optimization"""

EVERY session start:
  - Auto-read memory files
  - Auto-restore context
  - Auto-output status

# Manual activation required
from superclaude.pm_agent.confidence import ConfidenceChecker
checker = ConfidenceChecker()

Auto-generate:
  - docs/pdca/[feature]/plan.md
  - docs/pdca/[feature]/do.md
  - docs/pdca/[feature]/check.md
  - docs/pdca/[feature]/act.md

# なし - ユーザーが手動で記録

# workflows/task-management.md
- TodoWrite auto-tracking
- Progress checkpoints
- Session continuity

# TodoWriteはClaude Codeネイティブツールとして利用可能
# PM Agent特有のワークフローなし

# Core PM Agent (This PR) - always installed
pip install -e .

# Skills PM Agent (Upstream) - optional
superclaude install-skill pm-agent

# 本家Skills版のみ使用
superclaude install-skill pm-agent

# Pytest fixturesは使わない

# This PRのみ
pip install -e .

# Skillsなし

PM Agent Activation Layers:

  Layer 1 - Session Start (ALWAYS):
    Trigger: Every new conversation session
    Action: Auto-restore context from docs/memory/
    Detection: Session initialization event

  Layer 2 - Documentation Guardian (CONTINUOUS):
    Trigger: Any file operation in project
    Action: Ensure relevant docs are read before implementation
    Detection: Write/Edit tool usage

  Layer 3 - Commander (ON-DEMAND):
    Trigger: Complex tasks (>3 steps OR >3 files)
    Action: Orchestrate sub-agents and track progress
    Detection: TodoWrite usage OR complexity keywords

  Layer 4 - Post-Implementation (AUTO):
    Trigger: Task completion
    Action: Document learnings and update knowledge base
    Detection: Completion keywords OR test pass

  Layer 5 - Mistake Handler (IMMEDIATE):
    Trigger: Errors or test failures
    Action: Root cause analysis and prevention documentation
    Detection: Error messages OR test failures

session_start_indicators:
  - First message in new conversation
  - No prior context in current session
  - Token budget reset to baseline
  - No active TodoWrite items in memory

Wave 1 - PARALLEL Context Restoration:
  1. Bash: git status && git branch
  2. PARALLEL Read (silent):
     - Read docs/memory/pm_context.md (if exists)
     - Read docs/memory/last_session.md (if exists)
     - Read docs/memory/next_actions.md (if exists)
     - Read docs/memory/current_plan.json (if exists)
     - Read CLAUDE.md (ALWAYS)
     - Read docs/patterns/*.md (recent 5 files)

Checkpoint - Confidence Check (200 tokens):
  ❓ "全ファイル読めた？"
  ❓ "コンテキストに矛盾ない？"
  ❓ "次のアクション実行に十分な情報？"

  IF confidence >70%:
    → Output: 📍 [branch] | [status] | 🧠 [token]%
    → Ready for user request
  ELSE:
    → Report what's missing
    → Request user clarification

pre_write_checks:
  - BEFORE any Write tool usage
  - BEFORE any Edit tool usage
  - BEFORE complex TodoWrite (>3 tasks)

detection_logic:
  IF tool_name in [Write, Edit, MultiEdit]:
    AND file_path matches project patterns:
      → Auto-trigger Documentation Guardian

Documentation Guardian Protocol:

1. Identify Relevant Docs:
   file_path: src/auth.ts
   → Read docs/patterns/authentication-*.md
   → Read docs/mistakes/auth-*.md
   → Read CLAUDE.md sections matching "auth"

2. Confidence Check:
   ❓ "関連ドキュメント全部読んだ？"
   ❓ "過去の失敗パターン把握してる？"
   ❓ "既存の成功パターン確認した？"

   IF any_missing:
     → Read missing docs
     → Update understanding
     → Proceed with implementation
   ELSE:
     → Proceed confidently

3. Pattern Matching:
   IF similar_mistakes_found:
     ⚠️ "過去に同じミス発生: [mistake_pattern]"
     ⚠️ "防止策: [prevention_checklist]"
     → Apply prevention before implementation

commander_triggers:
  complexity_based:
    - TodoWrite with >3 tasks
    - Operations spanning >3 files
    - Multi-directory scope (>2 dirs)
    - Keywords: "refactor", "migrate", "redesign"

  explicit_keywords:
    - "orchestrate"
    - "coordinate"
    - "delegate"
    - "parallel execution"

Commander Protocol:

1. Task Analysis:
   - Identify independent vs dependent tasks
   - Determine parallelization opportunities
   - Select appropriate sub-agents

2. Orchestration Plan:
   tasks:
     - task_1: [agent-backend] → auth refactor
     - task_2: [agent-frontend] → UI updates (parallel)
     - task_3: [agent-test] → test updates (after 1+2)

   parallelization:
     wave_1: [task_1, task_2] # parallel
     wave_2: [task_3]         # sequential dependency

3. Execution with Tracking:
   - TodoWrite for overall plan
   - Sub-agent delegation via Task tool
   - Progress tracking in docs/memory/checkpoint.json
   - Validation gates between waves

4. Synthesis:
   - Collect sub-agent outputs
   - Integrate results
   - Final validation
   - Update documentation

completion_indicators:
  test_based:
    - "All tests passing" in output
    - pytest: X/X passed
    - ✅ keywords detected

  task_based:
    - All TodoWrite items marked completed
    - No pending tasks remaining

  explicit:
    - User says "done", "finished", "complete"
    - Commit message created

Post-Implementation Protocol:

1. Self-Evaluation (The Four Questions):
   ❓ "テストは全てpassしてる？"
   ❓ "要件を全て満たしてる？"
   ❓ "思い込みで実装してない？"
   ❓ "証拠はある？"

   IF any_fail:
     ❌ NOT complete
     → Report actual status
   ELSE:
     ✅ Proceed to documentation

2. Pattern Extraction:
   - What worked? → docs/patterns/[pattern].md
   - What failed? → docs/mistakes/[mistake].md
   - New learnings? → docs/memory/patterns_learned.jsonl

3. Knowledge Base Update:
   IF global_pattern_discovered:
     → Update CLAUDE.md with new rule
   IF project_specific_pattern:
     → Update docs/patterns/
   IF anti_pattern_identified:
     → Update docs/mistakes/

4. Session State Update:
   - Write docs/memory/session_summary.json
   - Update docs/memory/next_actions.md
   - Clean up temporary docs (>7 days old)

error_indicators:
  test_failures:
    - "FAILED" in pytest output
    - "Error" in test results
    - Non-zero exit code

  runtime_errors:
    - Exception stacktrace detected
    - Build failures
    - Linter errors (critical only)

  validation_failures:
    - Type check errors
    - Schema validation failures

Mistake Handler Protocol:

1. STOP Current Work:
   → Halt further implementation
   → Do not workaround the error

2. Reflexion Pattern:
   a) Check Past Errors:
      → Grep docs/memory/solutions_learned.jsonl
      → Grep docs/mistakes/ for similar errors

   b) IF similar_error_found:
      ✅ "過去に同じエラー発生済み"
      ✅ "解決策: [past_solution]"
      → Apply known solution

   c) ELSE (new error):
      → Root cause investigation
      → Document new solution

3. Documentation:
   Create docs/mistakes/[feature]-YYYY-MM-DD.md:
     - What Happened (現象)
     - Root Cause (根本原因)
     - Why Missed (なぜ見逃したか)
     - Fix Applied (修正内容)
     - Prevention Checklist (防止策)
     - Lesson Learned (教訓)

4. Update Knowledge Base:
   → echo '{"error":"...","solution":"..."}' >> docs/memory/solutions_learned.jsonl
   → Update prevention checklists

Step 1 - Update pm-agent.md:
  Remove: "Manual Invocation: /sc:pm command"
  Add: "Auto-Activation: Behavior-based triggers (see below)"

Step 2 - Delete /sc:pm command:
  File: ~/.claude/commands/sc/pm.md
  Action: Archive or delete (functionality now in persona)

Step 3 - Update rules.md:
  Agent Orchestration section:
  - Remove references to /sc:pm command
  - Add auto-activation trigger documentation

Step 4 - Test Auto-Activation:
  - Start new session → Should auto-restore context
  - Make file changes → Should auto-read relevant docs
  - Complete task → Should auto-document learnings
  - Encounter error → Should auto-trigger mistake handler

Current (Manual /sc:pm):
  If forgotten: 0 tokens (no PM functionality)
  If remembered: 200-500 tokens per invocation
  Average: Inconsistent, user-dependent

Proposed (Auto-Activation):
  Session Start: 200 tokens (ALWAYS)
  Documentation Guardian: 0-100 tokens (as needed)
  Commander: 0 tokens (only if complex task)
  Post-Implementation: 200-2,500 tokens (only after completion)
  Mistake Handler: 0 tokens (only if error)

  Total per session: 400-3,000 tokens (predictable)

  Trade-off: Slight increase in baseline usage
  Benefit: 100% consistent PM Agent functionality
  ROI: Prevents 5K-50K token waste from wrong implementations

Phase 1 - Core Auto-Activation:
  - [ ] Update pm-agent.md with auto-activation triggers
  - [ ] Remove session start from /sc:pm command
  - [ ] Test session start auto-restoration
  - [ ] Verify token budget calculations

Phase 2 - Documentation Guardian:
  - [ ] Add pre-write documentation checks
  - [ ] Implement pattern matching logic
  - [ ] Test with various file operations
  - [ ] Verify no performance degradation

Phase 3 - Commander Mode:
  - [ ] Add complexity detection logic
  - [ ] Implement sub-agent delegation
  - [ ] Test parallel execution patterns
  - [ ] Verify progress tracking

Phase 4 - Post-Implementation:
  - [ ] Add completion detection logic
  - [ ] Implement auto-documentation triggers
  - [ ] Test pattern extraction
  - [ ] Verify knowledge base updates

Phase 5 - Mistake Handler:
  - [ ] Add error detection logic
  - [ ] Implement Reflexion pattern lookup
  - [ ] Test mistake documentation
  - [ ] Verify prevention checklist updates

Phase 6 - Cleanup:
  - [ ] Archive /sc:pm command
  - [ ] Update all documentation
  - [ ] Remove manual invocation references
  - [ ] Final integration testing

User Session:

1. Start Conversation:
   Claude: [Auto-activates PM Agent]
   Claude: 📍 feature/auth | ✨ Clean | 🧠 15% (30K/200K)
   User: "Fix authentication bug in auth.ts"

2. Pre-Implementation:
   Claude: [Documentation Guardian activates]
   Claude: [Reads docs/patterns/authentication-*.md silently]
   Claude: [Reads docs/mistakes/auth-*.md silently]
   Claude: ⚠️ Past mistake found: "Missing token validation"
   Claude: Applying prevention checklist before implementation...

3. Implementation:
   Claude: [Makes changes with prevention applied]
   Claude: [Runs tests]
   Claude: ✅ All tests passing

4. Post-Implementation:
   Claude: [Auto-activates documentation]
   Claude: [Runs Four Questions self-check]
   Claude: [Extracts pattern: "Token validation pattern"]
   Claude: [Updates docs/patterns/authentication-token-validation.md]
   Claude: ✅ Task complete with documentation updated

User: [Never had to invoke /sc:pm manually]

MODE_Task_Management.md:
  - write_memory() / read_memory() 使用
  - Serena MCP依存
  - セッション開始時のlist_memories()
  - TodoWrite + memory並行管理

pm-agent.md:
  - docs/memory/ ファイル管理
  - ローカルファイルベース
  - セッション開始時のRead並行実行
  - TodoWrite + docs/memory/並行管理

結論: 完全に機能が重複、統合必須

docs/memory/:
  - いつクリアするか決まってない
  - ファイルベース vs MCP memoryの使い分け不明
  - ライフサイクル管理なし

write_memory() (Serena MCP):
  - いつ使うべきか不明確
  - docs/memory/との使い分けなし
  - 削除タイミング不明

Level 1 - Session Memory (Mindbase MCP):
  Purpose: 会話履歴の長期保存（Claude Code標準機能）
  Technology: Mindbase MCP (自動管理)
  Scope: 全プロジェクト横断
  Lifecycle: 永続（自動管理）
  Use Cases:
    - 過去の会話検索
    - 長期的なパターン学習
    - プロジェクト間の知識共有

Level 2 - Project Documentation (File-based):
  Purpose: プロジェクト固有の知識ベース
  Technology: Markdown files in docs/
  Scope: プロジェクトごと
  Lifecycle: Git管理（明示的削除まで永続）
  Locations:
    docs/patterns/: 成功パターン（永続）
    docs/mistakes/: 失敗記録（永続）
    CLAUDE.md: グローバルルール（永続）

Level 3 - Task State (Serena MCP - Code Understanding):
  Purpose: コードベース理解のためのシンボル管理
  Technology: Serena MCP
  Scope: セッション内
  Lifecycle: セッション終了で自動削除
  Use Cases:
    - コード構造の理解
    - シンボル間の関係追跡
    - リファクタリング支援

Level 4 - TodoWrite (Claude Code Built-in):
  Purpose: 現在のタスク進捗管理
  Technology: Claude Code標準機能
  Scope: セッション内
  Lifecycle: タスク完了で削除
  Use Cases:
    - 現在進行中のタスク追跡
    - サブタスクの管理
    - 進捗の可視化

Session Start:
  1. Mindbaseから過去の関連会話を自動ロード（Claude Code標準）
  2. docs/patterns/ と docs/mistakes/ を読む（必要に応じて）
  3. CLAUDE.md を常に読む
  4. Serena: 使わない（コード理解時のみ）
  5. TodoWrite: 新規作成（必要なら）

During Work:
  1. Mindbase: 自動保存（Claude Code標準）
  2. docs/: 新しいパターン/ミスを文書化
  3. Serena: コード理解時のみ使用
  4. TodoWrite: 進捗更新

Session End:
  1. Mindbase: 自動保存（Claude Code標準）
  2. docs/: 学習内容を永続化
  3. Serena: 自動削除（何もしない）
  4. TodoWrite: 完了タスクはクリア

Monthly Maintenance:
  1. docs/patterns/: 古い（>6ヶ月）で未参照なら削除
  2. docs/mistakes/: 重複をマージ
  3. CLAUDE.md: ベストプラクティス抽出

Mindbase MCP (会話履歴):
  Auto-Managed: Claude Codeが自動管理
  PM Agent Role: なし（自動で動く）
  User Action: なし（透明）

Serena MCP (コード理解):
  Trigger: コードベース理解が必要な時のみ
  PM Agent Role: コード理解時に自動活用
  Examples:
    - リファクタリング計画
    - シンボル追跡
    - コード構造分析
  NOT for: タスク管理、会話記憶

Sequential MCP (複雑な推論):
  Trigger: 複雑な分析・設計が必要な時
  PM Agent Role: Commander modeで活用
  Examples:
    - アーキテクチャ設計
    - 複雑なデバッグ
    - システム分析

Context7 MCP (ドキュメント参照):
  Trigger: 公式ドキュメント参照が必要な時
  PM Agent Role: Pre-Implementation Confidence Check
  Examples:
    - ライブラリの使い方確認
    - ベストプラクティス参照
    - API仕様確認

DELETE:
  1. docs/memory/ ディレクトリ全体
     理由: Mindbaseと重複、ライフサイクル不明確

  2. MODE_Task_Management.md の memory操作部分
     理由: pm-agent.mdと重複

  3. pm-agent.md の docs/memory/ 参照
     理由: Mindbaseに統合

  4. write_memory() / read_memory() 使用
     理由: Serenaはコード理解専用

PM Agent Core Responsibilities:

1. Session Lifecycle Management:
   Start:
     - Git status確認
     - CLAUDE.md読み込み
     - docs/patterns/ 最近5件読み込み
     - Mindbase自動ロード（Claude Code標準）

   End:
     - docs/patterns/ or docs/mistakes/ 更新
     - CLAUDE.md更新（必要なら）
     - Mindbase自動保存（Claude Code標準）

2. Documentation Guardian:
   - 実装前にdocs/patterns/とdocs/mistakes/を確認
   - 関連ドキュメントを自動読み込み
   - Pre-Implementation Confidence Check

3. Commander (Complex Tasks):
   - TodoWrite でタスク管理
   - Sequentialで複雑な分析
   - 並列実行の調整

4. Post-Implementation Documentation:
   - 成功パターン → docs/patterns/
   - 失敗記録 → docs/mistakes/
   - グローバルルール → CLAUDE.md

5. Mistake Handler (Reflexion):
   - docs/mistakes/ 検索（過去の失敗確認）
   - 新しいミス → docs/mistakes/ 文書化
   - 防止策の適用

削除:
  - docs/memory/ 全体（Mindbaseで代替）
  - write_memory() 使用（Serenaはコード理解専用）
  - 複雑なメモリ管理ロジック

残す:
  - docs/patterns/（成功パターン）
  - docs/mistakes/（失敗記録）
  - CLAUDE.md（グローバルルール）
  - TodoWrite（進捗管理）

Session Start:
  1. git status && git branch
  2. Read CLAUDE.md
  3. Read docs/patterns/*.md (最近5件)
  4. Mindbase自動ロード（透明）
  5. 準備完了 → ユーザーリクエスト待機

実装前:
  1. 関連docs/patterns/とdocs/mistakes/読む
  2. Confidence Check
  3. Context7で公式ドキュメント確認（必要なら）

実装中:
  1. TodoWrite更新
  2. コード理解が必要 → Serena使用
  3. 複雑な分析 → Sequential使用

実装後:
  1. パターン抽出 → docs/patterns/
  2. ミス記録 → docs/mistakes/
  3. グローバルルール → CLAUDE.md
  4. Mindbase自動保存

Phase 1 - Cleanup:
  - [ ] docs/memory/ ディレクトリ削除
  - [ ] MODE_Task_Management.md からmemory操作削除
  - [ ] pm-agent.md からdocs/memory/参照削除

Phase 2 - MCP Role Clarification:
  - [ ] pm-agent.md にMCP使用ガイドライン追加
  - [ ] Serena = コード理解専用 明記
  - [ ] Mindbase = 自動管理 明記
  - [ ] Sequential = 複雑な分析 明記
  - [ ] Context7 = 公式ドキュメント参照 明記

Phase 3 - Documentation:
  - [ ] docs/patterns/README.md 作成（成功パターン記録ガイド）
  - [ ] docs/mistakes/README.md 作成（失敗記録ガイド）
  - [ ] Memory管理ポリシー文書化

Phase 4 - Testing:
  - [ ] セッション開始の自動ロードテスト
  - [ ] 実装前のドキュメント確認テスト
  - [ ] 実装後の文書化テスト
  - [ ] MCPの適切な使用テスト

$ ls ~/.claude/skills/
brainstorming-mode
business-panel-mode
deep-research-mode
introspection-mode
orchestration-mode
pm                          # ← PM Agent Skill
pm.backup                   # ← バックアップ
task-management-mode
token-efficiency-mode

$ wc -c ~/.claude/skills/*/implementation.md ~/.claude/skills/*/SKILL.md
   64394 total  # 約64KB ≈ 15K tokens

superclaude install-skill pm-agent
# → ~/.claude/skills/pm/ にコピー

起動時:
  1. ~/.claude/ をスキャン
  2. skills/ 配下の全 *.md を読み込み
  3. implementation.md を Claude に渡す

Result: 64KB = 約15K tokens消費

# バックアップ作成
mv ~/.claude/skills ~/.claude/skills.backup.$(date +%Y%m%d)

# 確認
ls ~/.claude/skills
# → "No such file or directory" になればOK

# PM Agentだけ削除（新実装があるため）
rm -rf ~/.claude/skills/pm
rm -rf ~/.claude/skills/pm.backup

# 他のSkillsは残す
ls ~/.claude/skills/
# → brainstorming-mode, business-panel-mode, etc. 残る

# 使っているSkillsを確認
cd ~/.claude/skills
ls -la

# 使わないものを削除
rm -rf brainstorming-mode     # 使ってない
rm -rf business-panel-mode    # 使ってない
rm -rf pm pm.backup           # 新実装あり

# 必要なものだけ残す
# deep-research-mode → 使ってる
# orchestration-mode → 使ってる

cp -r ~/.claude/skills ~/.claude/skills.backup.$(date +%Y%m%d)

rm -rf ~/.claude/skills/pm
rm -rf ~/.claude/skills/pm.backup

# 新PM Agentが動作することを確認
make verify
uv run pytest tests/pm_agent/ -v

# Claude Code再起動して体感確認
# Context window利用可能量が増えているはず

# 全Skills削除
rm -rf ~/.claude/skills

# 効果: 15K tokens回復

# PM Agent系のみ削除
rm -rf ~/.claude/skills/pm*

# 他のSkillsは残す（deep-research, orchestration等）
# 効果: 3K tokens回復

Context consumed at startup:
- MCP tools: 5K tokens (AIRIS Gateway)
- Skills (全部): 15K tokens ← 削除対象
- SuperClaude: 0K tokens (未インストール状態想定)
─────────────────────────────
Total: 20K tokens
Available: 180K tokens

Context consumed at startup:
- MCP tools: 5K tokens (AIRIS Gateway)
- Skills: 0K tokens ← 削除完了
- SuperClaude pytest plugin: 0K tokens (pytestなし時)
─────────────────────────────
Total: 5K tokens
Available: 195K tokens

# 安全にバックアップ取りながら削除
cd ~/.claude
mv skills skills.backup.20251021
mkdir skills  # 空のディレクトリ作成（Claude Code用）

# 確認
ls -la skills/
# → 空になっていればOK