refactor: migrate to clean architecture with src/ layout

## Migration Summary
- Moved from flat `superclaude/` to `src/superclaude/` (PEP 517/518)
- Deleted old structure (119 files removed)
- Added new structure with clean architecture layers

## Project Structure Changes
- OLD: `superclaude/{agents,commands,modes,framework}/`
- NEW: `src/superclaude/{cli,execution,pm_agent}/`

## Build System Updates
- Switched: setuptools → hatchling (modern, PEP 517)
- Updated: pyproject.toml with proper entry points
- Added: pytest plugin auto-discovery
- Version: 4.1.6 → 0.4.0 (clean slate)

## Makefile Enhancements
- Removed: `superclaude install` calls (deprecated)
- Added: `make verify` - Phase 1 installation verification
- Added: `make test-plugin` - pytest plugin loading test
- Added: `make doctor` - health check command

## Documentation Added
- docs/architecture/ - 7 architecture docs
- docs/research/python_src_layout_research_20251021.md
- docs/PR_STRATEGY.md

## Migration Phases
- Phase 1: Core installation ✅ (this commit)
- Phase 2: Lazy loading + Skills system (next)
- Phase 3: PM Agent meta-layer (future)

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

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

docs/architecture/SKILLS_CLEANUP.md

@@ -0,0 +1,240 @@
+# Skills Cleanup for Clean Architecture
+
+**Date**: 2025-10-21
+**Issue**: `~/.claude/skills/` に古いSkillsが残っている
+**Impact**: Claude Code起動時に約64KB (15K tokens) 読み込んでいる可能性
+
+---
+
+## 📊 現状
+
+### ~/.claude/skills/ の内容
+
+```bash
+$ 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
+```
+
+### サイズ確認
+
+```bash
+$ wc -c ~/.claude/skills/*/implementation.md ~/.claude/skills/*/SKILL.md
+   64394 total  # 約64KB ≈ 15K tokens
+```
+
+---
+
+## 🎯 クリーンアーキテクチャでの扱い
+
+### 新アーキテクチャ
+
+**PM Agent Core** → `src/superclaude/pm_agent/`
+- Python modulesとして実装
+- pytest fixturesで利用
+- `~/.claude/` 汚染なし
+
+**Skills (オプション)** → ユーザーが明示的にインストール
+```bash
+superclaude install-skill pm-agent
+# → ~/.claude/skills/pm/ にコピー
+```
+
+---
+
+## ⚠️ 問題：Skills自動読み込み
+
+### Claude Codeの動作（推測）
+
+```yaml
+起動時:
+  1. ~/.claude/ をスキャン
+  2. skills/ 配下の全 *.md を読み込み
+  3. implementation.md を Claude に渡す
+
+Result: 64KB = 約15K tokens消費
+```
+
+### 影響
+
+現在のローカル環境では：
+- ✅ `src/superclaude/pm_agent/` - 新実装（使用中）
+- ❌ `~/.claude/skills/pm/` - 古いSkill（残骸）
+- ❌ `~/.claude/skills/*-mode/` - 他のSkills（残骸）
+
+**重複読み込み**: 新旧両方が読み込まれている可能性
+
+---
+
+## 🧹 クリーンアップ手順
+
+### Option 1: 全削除（推奨 - クリーンアーキテクチャ完全移行）
+
+```bash
+# バックアップ作成
+mv ~/.claude/skills ~/.claude/skills.backup.$(date +%Y%m%d)
+
+# 確認
+ls ~/.claude/skills
+# → "No such file or directory" になればOK
+```
+
+**効果**:
+- ✅ 15K tokens回復
+- ✅ クリーンな状態
+- ✅ 新アーキテクチャのみ
+
+---
+
+### Option 2: PM Agentのみ削除
+
+```bash
+# PM Agentだけ削除（新実装があるため）
+rm -rf ~/.claude/skills/pm
+rm -rf ~/.claude/skills/pm.backup
+
+# 他のSkillsは残す
+ls ~/.claude/skills/
+# → brainstorming-mode, business-panel-mode, etc. 残る
+```
+
+**効果**:
+- ✅ PM Agent重複解消（約3K tokens回復）
+- ✅ 他のSkillsは使える
+- ❌ 他のSkillsのtoken消費は続く（約12K）
+
+---
+
+### Option 3: 必要なSkillsのみ残す
+
+```bash
+# 使っている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 → 使ってる
+```
+
+**効果**:
+- ✅ カスタマイズ可能
+- ⚠️ 手動管理必要
+
+---
+
+## 📋 推奨アクション
+
+### Phase 3実施前
+
+**1. バックアップ作成**
+```bash
+cp -r ~/.claude/skills ~/.claude/skills.backup.$(date +%Y%m%d)
+```
+
+**2. 古いPM Agent削除**
+```bash
+rm -rf ~/.claude/skills/pm
+rm -rf ~/.claude/skills/pm.backup
+```
+
+**3. 動作確認**
+```bash
+# 新PM Agentが動作することを確認
+make verify
+uv run pytest tests/pm_agent/ -v
+```
+
+**4. トークン削減確認**
+```bash
+# Claude Code再起動して体感確認
+# Context window利用可能量が増えているはず
+```
+
+---
+
+### Phase 3以降（完全移行後）
+
+**Option A: 全Skillsクリーン（最大効果）**
+```bash
+# 全Skills削除
+rm -rf ~/.claude/skills
+
+# 効果: 15K tokens回復
+```
+
+**Option B: 選択的削除**
+```bash
+# PM Agent系のみ削除
+rm -rf ~/.claude/skills/pm*
+
+# 他のSkillsは残す（deep-research, orchestration等）
+# 効果: 3K tokens回復
+```
+
+---
+
+## 🎯 PR準備への影響
+
+### Before/After比較データ
+
+**Before (現状)**:
+```
+Context consumed at startup:
+- MCP tools: 5K tokens (AIRIS Gateway)
+- Skills (全部): 15K tokens ← 削除対象
+- SuperClaude: 0K tokens (未インストール状態想定)
+─────────────────────────────
+Total: 20K tokens
+Available: 180K tokens
+```
+
+**After (クリーンアップ後)**:
+```
+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
+```
+
+**Improvement**: +15K tokens (7.5%改善)
+
+---
+
+## ⚡ 即時実行推奨コマンド
+
+```bash
+# 安全にバックアップ取りながら削除
+cd ~/.claude
+mv skills skills.backup.20251021
+mkdir skills  # 空のディレクトリ作成（Claude Code用）
+
+# 確認
+ls -la skills/
+# → 空になっていればOK
+```
+
+**効果**:
+- ✅ 即座に15K tokens回復
+- ✅ いつでも復元可能（backup残してる）
+- ✅ クリーンな環境でテスト可能
+
+---
+
+**ステータス**: 実行待ち
+**推奨**: Option 1 (全削除) - クリーンアーキテクチャ完全移行のため