From efd964d46ab9f8c8f7e998495c7bac6569d55773 Mon Sep 17 00:00:00 2001 From: kazuki Date: Fri, 17 Oct 2025 16:17:12 +0900 Subject: [PATCH] chore: remove redundant docs after PLANNING.md migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cleanup after Self-Improvement Loop implementation: **Deleted (21 files, ~210KB)**: - docs/Development/ - All content migrated to PLANNING.md & TASK.md * ARCHITECTURE.md (15KB) → PLANNING.md * TASKS.md (3.7KB) → TASK.md * ROADMAP.md (11KB) → TASK.md * PROJECT_STATUS.md (4.2KB) → outdated * 13 PM Agent research files → archived in KNOWLEDGE.md - docs/PM_AGENT.md - Old implementation status - docs/pm-agent-implementation-status.md - Duplicate - docs/templates/ - Empty directory **Retained (valuable documentation)**: - docs/memory/ - Active session metrics & context - docs/patterns/ - Reusable patterns - docs/research/ - Research reports - docs/user-guide*/ - User documentation (4 languages) - docs/reference/ - Reference materials - docs/getting-started/ - Quick start guides - docs/agents/ - Agent-specific guides - docs/testing/ - Test procedures **Result**: - Eliminated redundancy after Root Documents consolidation - Preserved all valuable content in PLANNING.md, TASK.md, KNOWLEDGE.md - Maintained user-facing documentation structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/Development/ARCHITECTURE.md | 529 ------------- docs/Development/PROJECT_STATUS.md | 172 ----- docs/Development/ROADMAP.md | 349 --------- docs/Development/TASKS.md | 151 ---- docs/Development/architecture-overview.md | 103 --- docs/Development/cli-install-improvements.md | 658 ---------------- docs/Development/code-style.md | 50 -- ...is-pm-autonomous-enhancement-2025-10-14.md | 390 ---------- docs/Development/install-process-analysis.md | 489 ------------ .../installation-flow-understanding.md | 378 --------- docs/Development/pm-agent-ideal-workflow.md | 341 --------- docs/Development/pm-agent-improvements.md | 149 ---- docs/Development/pm-agent-integration.md | 477 ------------ .../pm-agent-parallel-architecture.md | 716 ------------------ .../pm-agent-parallel-execution-complete.md | 235 ------ docs/Development/project-overview.md | 24 - .../project-structure-understanding.md | 368 --------- docs/Development/tasks/current-tasks.md | 163 ---- docs/PM_AGENT.md | 332 -------- docs/pm-agent-implementation-status.md | 332 -------- docs/templates/__init__.py | 0 21 files changed, 6406 deletions(-) delete mode 100644 docs/Development/ARCHITECTURE.md delete mode 100644 docs/Development/PROJECT_STATUS.md delete mode 100644 docs/Development/ROADMAP.md delete mode 100644 docs/Development/TASKS.md delete mode 100644 docs/Development/architecture-overview.md delete mode 100644 docs/Development/cli-install-improvements.md delete mode 100644 docs/Development/code-style.md delete mode 100644 docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md delete mode 100644 docs/Development/install-process-analysis.md delete mode 100644 docs/Development/installation-flow-understanding.md delete mode 100644 docs/Development/pm-agent-ideal-workflow.md delete mode 100644 docs/Development/pm-agent-improvements.md delete mode 100644 docs/Development/pm-agent-integration.md delete mode 100644 docs/Development/pm-agent-parallel-architecture.md delete mode 100644 docs/Development/pm-agent-parallel-execution-complete.md delete mode 100644 docs/Development/project-overview.md delete mode 100644 docs/Development/project-structure-understanding.md delete mode 100644 docs/Development/tasks/current-tasks.md delete mode 100644 docs/PM_AGENT.md delete mode 100644 docs/pm-agent-implementation-status.md delete mode 100644 docs/templates/__init__.py diff --git a/docs/Development/ARCHITECTURE.md b/docs/Development/ARCHITECTURE.md deleted file mode 100644 index 8057b57..0000000 --- a/docs/Development/ARCHITECTURE.md +++ /dev/null @@ -1,529 +0,0 @@ -# SuperClaude Architecture - -**Last Updated**: 2025-10-14 -**Version**: 4.1.5 - -## 📋 Table of Contents - -1. [System Overview](#system-overview) -2. [Core Architecture](#core-architecture) -3. [PM Agent Mode: The Meta-Layer](#pm-agent-mode-the-meta-layer) -4. [Component Relationships](#component-relationships) -5. [Serena MCP Integration](#serena-mcp-integration) -6. [PDCA Engine](#pdca-engine) -7. [Data Flow](#data-flow) -8. [Extension Points](#extension-points) - ---- - -## System Overview - -### What is SuperClaude? - -SuperClaude is a **Context-Oriented Configuration Framework** that transforms Claude Code into a structured development platform. It is NOT standalone software with running processes - it is a collection of `.md` instruction files that Claude Code reads to adopt specialized behaviors. - -### Key Components - -``` -SuperClaude Framework -├── Commands (26) → Workflow patterns -├── Agents (16) → Domain expertise -├── Modes (7) → Behavioral modifiers -├── MCP Servers (8) → External tool integrations -└── PM Agent Mode → Meta-layer orchestration (Always-Active) -``` - -### Version Information - -- **Current Version**: 4.1.5 -- **Commands**: 26 slash commands (`/sc:*`) -- **Agents**: 16 specialized domain experts -- **Modes**: 7 behavioral modes -- **MCP Servers**: 8 integrations (Context7, Sequential, Magic, Playwright, Morphllm, Serena, Tavily, Chrome DevTools) - ---- - -## Core Architecture - -### Context-Oriented Configuration - -SuperClaude's architecture is built on a simple principle: **behavioral modification through structured context files**. - -``` -User Input - ↓ -Context Loading (CLAUDE.md imports) - ↓ -Command Detection (/sc:* pattern) - ↓ -Agent Activation (manual or auto) - ↓ -Mode Application (flags or triggers) - ↓ -MCP Tool Coordination - ↓ -Output Generation -``` - -### Directory Structure - -``` -~/.claude/ -├── CLAUDE.md # Main context with @imports -├── FLAGS.md # Flag definitions -├── RULES.md # Core behavioral rules -├── PRINCIPLES.md # Guiding principles -├── MODE_*.md # 7 behavioral modes -├── MCP_*.md # 8 MCP server integrations -├── agents/ # 16 specialized agents -│ ├── pm-agent.md # 🆕 Meta-layer orchestrator -│ ├── backend-architect.md -│ ├── frontend-architect.md -│ ├── security-engineer.md -│ └── ... (13 more) -└── commands/sc/ # 26 workflow commands - ├── pm.md # 🆕 PM Agent command - ├── implement.md - ├── analyze.md - └── ... (23 more) -``` - ---- - -## PM Agent Mode: The Meta-Layer - -### Position in Architecture - -PM Agent operates as a **meta-layer** above all other components: - -``` -┌─────────────────────────────────────────────┐ -│ PM Agent Mode (Meta-Layer) │ -│ • Always Active (Session Start) │ -│ • Context Preservation │ -│ • PDCA Self-Evaluation │ -│ • Knowledge Management │ -└─────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────┐ -│ Specialist Agents (16) │ -│ backend-architect, security-engineer, etc. │ -└─────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────┐ -│ Commands & Modes │ -│ /sc:implement, /sc:analyze, etc. │ -└─────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────┐ -│ MCP Tool Layer │ -│ Context7, Sequential, Magic, etc. │ -└─────────────────────────────────────────────┘ -``` - -### PM Agent Responsibilities - -1. **Session Lifecycle Management** - - Auto-activation at session start - - Context restoration from Serena MCP memory - - User report generation (前回/進捗/今回/課題) - -2. **PDCA Cycle Execution** - - Plan: Hypothesis generation - - Do: Experimentation with checkpoints - - Check: Self-evaluation - - Act: Knowledge extraction - -3. **Documentation Strategy** - - Temporary documentation (`docs/temp/`) - - Formal patterns (`docs/patterns/`) - - Mistake records (`docs/mistakes/`) - - Knowledge evolution to CLAUDE.md - -4. **Sub-Agent Orchestration** - - Auto-delegation to specialists - - Context coordination - - Quality gate validation - - Progress monitoring - ---- - -## Component Relationships - -### Commands → Agents → Modes → MCP - -``` -User: "/sc:implement authentication" --security - ↓ - [Command Layer] - commands/sc/implement.md - ↓ - [Agent Auto-Activation] - agents/security-engineer.md - agents/backend-architect.md - ↓ - [Mode Application] - MODE_Task_Management.md (TodoWrite) - ↓ - [MCP Tool Coordination] - Context7 (auth patterns) - Sequential (complex analysis) - ↓ - [PM Agent Meta-Layer] - Document learnings → docs/patterns/ -``` - -### Activation Flow - -1. **Explicit Command**: User types `/sc:implement` - - Loads `commands/sc/implement.md` - - Activates related agents (backend-architect, etc.) - -2. **Agent Activation**: `@agent-security` or auto-detected - - Loads agent expertise context - - May activate related MCP servers - -3. **Mode Application**: `--brainstorm` flag or keywords - - Modifies interaction style - - Enables specific behaviors - -4. **PM Agent Meta-Layer**: Always active - - Monitors all interactions - - Documents learnings - - Preserves context across sessions - ---- - -## Serena MCP Integration - -### Memory Operations - -Serena MCP provides semantic code analysis and session persistence through memory operations: - -``` -Session Start: - PM Agent → list_memories() - PM Agent → read_memory("pm_context") - PM Agent → read_memory("last_session") - PM Agent → read_memory("next_actions") - PM Agent → Report to User - -During Work (every 30min): - PM Agent → write_memory("checkpoint", progress) - PM Agent → write_memory("decision", rationale) - -Session End: - PM Agent → write_memory("last_session", summary) - PM Agent → write_memory("next_actions", todos) - PM Agent → write_memory("pm_context", complete_state) -``` - -### Memory Structure - -```json -{ - "pm_context": { - "project": "SuperClaude_Framework", - "current_phase": "Phase 1: Documentation", - "active_tasks": ["ARCHITECTURE.md", "ROADMAP.md"], - "architecture": "Context-Oriented Configuration", - "patterns": ["PDCA Cycle", "Session Lifecycle"] - }, - "last_session": { - "date": "2025-10-14", - "accomplished": ["PM Agent mode design", "Salvaged implementations"], - "issues": ["Serena MCP not configured"], - "learned": ["Session Lifecycle pattern", "PDCA automation"] - }, - "next_actions": [ - "Create docs/development/ structure", - "Write ARCHITECTURE.md", - "Configure Serena MCP server" - ] -} -``` - ---- - -## PDCA Engine - -### Continuous Improvement Cycle - -``` -┌─────────────┐ -│ Plan │ → write_memory("plan", goal) -│ (仮説) │ → docs/temp/hypothesis-YYYY-MM-DD.md -└──────┬──────┘ - ↓ -┌─────────────┐ -│ Do │ → TodoWrite tracking -│ (実験) │ → write_memory("checkpoint", progress) -└──────┬──────┘ → docs/temp/experiment-YYYY-MM-DD.md - ↓ -┌─────────────┐ -│ Check │ → think_about_task_adherence() -│ (評価) │ → think_about_whether_you_are_done() -└──────┬──────┘ → docs/temp/lessons-YYYY-MM-DD.md - ↓ -┌─────────────┐ -│ Act │ → Success: docs/patterns/[name].md -│ (改善) │ → Failure: docs/mistakes/mistake-*.md -└──────┬──────┘ → Update CLAUDE.md - ↓ - [Repeat] -``` - -### Documentation Evolution - -``` -Trial-and-Error (docs/temp/) - ↓ -Success → Formal Pattern (docs/patterns/) - ↓ -Accumulate Knowledge - ↓ -Extract Best Practices → CLAUDE.md (Global Rules) -``` - -``` -Mistake Detection (docs/temp/) - ↓ -Root Cause Analysis → docs/mistakes/ - ↓ -Prevention Checklist - ↓ -Update Anti-Patterns → CLAUDE.md -``` - ---- - -## Data Flow - -### Session Lifecycle Data Flow - -``` -Session Start: -┌──────────────┐ -│ Claude Code │ -│ Startup │ -└──────┬───────┘ - ↓ -┌──────────────┐ -│ PM Agent │ list_memories() -│ Activation │ read_memory("pm_context") -└──────┬───────┘ - ↓ -┌──────────────┐ -│ Serena │ Return: pm_context, -│ MCP │ last_session, -└──────┬───────┘ next_actions - ↓ -┌──────────────┐ -│ Context │ Restore project state -│ Restoration │ Generate user report -└──────┬───────┘ - ↓ -┌──────────────┐ -│ User │ 前回: [summary] -│ Report │ 進捗: [status] -└──────────────┘ 今回: [actions] - 課題: [blockers] -``` - -### Implementation Data Flow - -``` -User Request → PM Agent Analyzes - ↓ -PM Agent → Delegate to Specialist Agents - ↓ -Specialist Agents → Execute Implementation - ↓ -Implementation Complete → PM Agent Documents - ↓ -PM Agent → write_memory("checkpoint", progress) -PM Agent → docs/temp/experiment-*.md - ↓ -Success → docs/patterns/ | Failure → docs/mistakes/ - ↓ -Update CLAUDE.md (if global pattern) -``` - ---- - -## Extension Points - -### Adding New Components - -#### 1. New Command -```markdown -File: ~/.claude/commands/sc/new-command.md -Structure: - - Metadata (name, category, complexity) - - Triggers (when to use) - - Workflow Pattern (step-by-step) - - Examples - -Integration: - - Auto-loads when user types /sc:new-command - - Can activate related agents - - PM Agent automatically documents usage patterns -``` - -#### 2. New Agent -```markdown -File: ~/.claude/agents/new-specialist.md -Structure: - - Metadata (name, category) - - Triggers (keywords, file types) - - Behavioral Mindset - - Focus Areas - -Integration: - - Auto-activates on trigger keywords - - Manual activation: @agent-new-specialist - - PM Agent orchestrates with other agents -``` - -#### 3. New Mode -```markdown -File: ~/.claude/MODE_NewMode.md -Structure: - - Activation Triggers (flags, keywords) - - Behavioral Modifications - - Interaction Patterns - -Integration: - - Flag: --new-mode - - Auto-activation on complexity threshold - - Modifies all agent behaviors -``` - -#### 4. New MCP Server -```json -File: ~/.claude/.claude.json -{ - "mcpServers": { - "new-server": { - "command": "npx", - "args": ["-y", "new-server-mcp@latest"] - } - } -} -``` - -```markdown -File: ~/.claude/MCP_NewServer.md -Structure: - - Purpose (what this server provides) - - Triggers (when to use) - - Integration (how to coordinate with other tools) -``` - -### PM Agent Integration for Extensions - -All new components automatically integrate with PM Agent meta-layer: - -1. **Session Lifecycle**: New components' usage tracked across sessions -2. **PDCA Cycle**: Patterns extracted from new component usage -3. **Documentation**: Learnings automatically documented -4. **Orchestration**: PM Agent coordinates new components with existing ones - ---- - -## Architecture Principles - -### 1. Simplicity First -- No executing code, only context files -- No performance systems, only instructional patterns -- No detection engines, Claude Code does pattern matching - -### 2. Context-Oriented -- Behavior modification through structured context -- Import system for modular context loading -- Clear trigger patterns for activation - -### 3. Meta-Layer Design -- PM Agent orchestrates without interfering -- Specialist agents work transparently -- Users interact with cohesive system - -### 4. Knowledge Accumulation -- Every experience generates learnings -- Mistakes documented with prevention -- Patterns extracted to reusable knowledge - -### 5. Session Continuity -- Context preserved across sessions -- No re-explanation needed -- Seamless resumption from last checkpoint - ---- - -## Technical Considerations - -### Performance -- Framework is pure context (no runtime overhead) -- Token efficiency through dynamic MCP loading -- Strategic context caching for related phases - -### Scalability -- Unlimited commands/agents/modes through context files -- Modular architecture supports independent development -- PM Agent meta-layer handles coordination complexity - -### Maintainability -- Clear separation of concerns (Commands/Agents/Modes) -- Self-documenting through PDCA cycle -- Living documentation evolves with usage - -### Extensibility -- Drop-in new contexts without code changes -- MCP servers add capabilities externally -- PM Agent auto-integrates new components - ---- - -## Future Architecture - -### Planned Enhancements - -1. **Auto-Activation System** - - PM Agent activates automatically at session start - - No manual invocation needed - -2. **Enhanced Memory Operations** - - Full Serena MCP integration - - Cross-project knowledge sharing - - Pattern recognition across sessions - -3. **PDCA Automation** - - Automatic documentation lifecycle - - AI-driven pattern extraction - - Self-improving knowledge base - -4. **Multi-Project Orchestration** - - PM Agent coordinates across projects - - Shared learnings and patterns - - Unified knowledge management - ---- - -## Summary - -SuperClaude's architecture is elegantly simple: **structured context files** that Claude Code reads to adopt sophisticated behaviors. The addition of PM Agent mode as a meta-layer transforms this from a collection of tools into a **continuously learning, self-improving development platform**. - -**Key Architectural Innovation**: PM Agent meta-layer provides: -- Always-active foundation layer -- Context preservation across sessions -- PDCA self-evaluation and learning -- Systematic knowledge management -- Seamless orchestration of specialist agents - -This architecture enables SuperClaude to function as a **最高司令官 (Supreme Commander)** that orchestrates all development activities while continuously learning and improving from every interaction. - ---- - -**Last Verified**: 2025-10-14 -**Next Review**: 2025-10-21 (1 week) -**Version**: 4.1.5 diff --git a/docs/Development/PROJECT_STATUS.md b/docs/Development/PROJECT_STATUS.md deleted file mode 100644 index ffeb5d3..0000000 --- a/docs/Development/PROJECT_STATUS.md +++ /dev/null @@ -1,172 +0,0 @@ -# SuperClaude Project Status - -**Last Updated**: 2025-10-14 -**Version**: 4.1.5 -**Phase**: Phase 1 - Documentation Structure - ---- - -## 📊 Quick Overview - -| Metric | Status | Progress | -|--------|--------|----------| -| **Overall Completion** | 🔄 In Progress | 35% | -| **Phase 1 (Documentation)** | 🔄 In Progress | 66% | -| **Phase 2 (PM Agent)** | 🔄 In Progress | 30% | -| **Phase 3 (Serena MCP)** | ⏳ Not Started | 0% | -| **Phase 4 (Doc Strategy)** | ⏳ Not Started | 0% | -| **Phase 5 (Auto-Activation)** | 🔬 Research | 0% | - ---- - -## 🎯 Current Sprint - -**Sprint**: Phase 1 - Documentation Structure -**Timeline**: 2025-10-14 ~ 2025-10-20 -**Status**: 🔄 66% Complete - -### This Week's Focus -- [ ] Complete Phase 1 documentation (TASKS.md, PROJECT_STATUS.md, pm-agent-integration.md) -- [ ] Commit Phase 1 changes -- [ ] Commit PM Agent Mode improvements - ---- - -## ✅ Completed Features - -### Core Framework (v4.1.5) -- ✅ **26 Commands**: `/sc:*` namespace -- ✅ **16 Agents**: Specialized domain experts -- ✅ **7 Modes**: Behavioral modifiers -- ✅ **8 MCP Servers**: External tool integrations - -### PM Agent Mode (Design Phase) -- ✅ Session Lifecycle design -- ✅ PDCA Cycle design -- ✅ Documentation Strategy design -- ✅ Commands/pm.md updated -- ✅ Agents/pm-agent.md updated - -### Documentation -- ✅ docs/development/ARCHITECTURE.md -- ✅ docs/development/ROADMAP.md -- ✅ docs/development/TASKS.md -- ✅ docs/development/PROJECT_STATUS.md -- ✅ docs/PM_AGENT.md - ---- - -## 🔄 In Progress - -### Phase 1: Documentation Structure (66%) -- [x] ARCHITECTURE.md -- [x] ROADMAP.md -- [x] TASKS.md -- [x] PROJECT_STATUS.md -- [ ] pm-agent-integration.md - -### Phase 2: PM Agent Mode (30%) -- [ ] superclaude/Core/session_lifecycle.py -- [ ] superclaude/Core/pdca_engine.py -- [ ] superclaude/Core/memory_ops.py -- [ ] Unit tests -- [ ] Integration tests - ---- - -## ⏳ Pending - -### Phase 3: Serena MCP Integration (0%) -- Serena MCP server configuration -- Memory operations implementation -- Think operations implementation -- Cross-session persistence testing - -### Phase 4: Documentation Strategy (0%) -- Directory templates creation -- Lifecycle automation -- Migration scripts -- Knowledge management - -### Phase 5: Auto-Activation (0%) -- Claude Code initialization hooks research -- Auto-activation implementation -- Context restoration -- Performance optimization - ---- - -## 🚫 Blockers - -### Critical -- **Serena MCP Not Configured**: Blocks Phase 3 (Memory Operations) -- **Auto-Activation Hooks Unknown**: Blocks Phase 5 (Research needed) - -### Non-Critical -- Documentation directory structure (in progress - Phase 1) - ---- - -## 📈 Metrics Dashboard - -### Development Velocity -- **Phase 1**: 6 days estimated, on track for 7 days completion -- **Phase 2**: 14 days estimated, not yet started full implementation -- **Overall**: 35% complete, on schedule for 8-week timeline - -### Code Quality -- **Test Coverage**: 0% (implementation not started) -- **Documentation Coverage**: 40% (4/10 major docs complete) - -### Component Status -- **Commands**: ✅ 26/26 functional -- **Agents**: ✅ 16/16 functional, 1 (PM Agent) enhanced -- **Modes**: ✅ 7/7 functional -- **MCP Servers**: ⚠️ 7/8 functional (Serena pending) - ---- - -## 🎯 Upcoming Milestones - -### Week 1 (Current) -- ✅ Complete Phase 1 documentation -- ✅ Commit changes to repository - -### Week 2-3 -- [ ] Implement PM Agent Core (session_lifecycle, pdca_engine, memory_ops) -- [ ] Write unit tests -- [ ] Update user-guide documentation - -### Week 4-5 -- [ ] Configure Serena MCP server -- [ ] Implement memory operations -- [ ] Test cross-session persistence - ---- - -## 📝 Recent Changes - -### 2025-10-14 -- Created docs/development/ structure -- Wrote ARCHITECTURE.md (system overview) -- Wrote ROADMAP.md (5-phase development plan) -- Wrote TASKS.md (task tracking) -- Wrote PROJECT_STATUS.md (this file) -- Salvaged PM Agent mode changes from ~/.claude -- Updated Commands/pm.md and Agents/pm-agent.md - ---- - -## 🔮 Next Steps - -1. **Complete pm-agent-integration.md** (Phase 1 final doc) -2. **Commit Phase 1 documentation** (establish foundation) -3. **Commit PM Agent Mode improvements** (design complete) -4. **Begin Phase 2 implementation** (Core components) -5. **Configure Serena MCP** (unblock Phase 3) - ---- - -**Last Verified**: 2025-10-14 -**Next Review**: 2025-10-17 (Mid-week check) -**Version**: 4.1.5 diff --git a/docs/Development/ROADMAP.md b/docs/Development/ROADMAP.md deleted file mode 100644 index 90ecce6..0000000 --- a/docs/Development/ROADMAP.md +++ /dev/null @@ -1,349 +0,0 @@ -# SuperClaude Development Roadmap - -**Last Updated**: 2025-10-14 -**Version**: 4.1.5 - -## 🎯 Vision - -Transform SuperClaude into a self-improving development platform with PM Agent mode as the always-active meta-layer, enabling continuous context preservation, systematic knowledge management, and intelligent orchestration of all development activities. - ---- - -## 📊 Phase Overview - -| Phase | Status | Timeline | Focus | -|-------|--------|----------|-------| -| **Phase 1** | ✅ Completed | Week 1 | Documentation Structure | -| **Phase 2** | 🔄 In Progress | Week 2-3 | PM Agent Mode Integration | -| **Phase 3** | ⏳ Planned | Week 4-5 | Serena MCP Integration | -| **Phase 4** | ⏳ Planned | Week 6-7 | Documentation Strategy | -| **Phase 5** | 🔬 Research | Week 8+ | Auto-Activation System | - ---- - -## Phase 1: Documentation Structure ✅ - -**Goal**: Create comprehensive documentation foundation for development - -**Timeline**: Week 1 (2025-10-14 ~ 2025-10-20) - -**Status**: ✅ Completed - -### Tasks - -- [x] Create `docs/development/` directory structure -- [x] Write `ARCHITECTURE.md` - System overview with PM Agent position -- [x] Write `ROADMAP.md` - Phase-based development plan with checkboxes -- [ ] Write `TASKS.md` - Current task tracking system -- [ ] Write `PROJECT_STATUS.md` - Implementation status dashboard -- [ ] Write `pm-agent-integration.md` - Integration guide and procedures - -### Deliverables - -- [x] **docs/development/ARCHITECTURE.md** - Complete system architecture -- [x] **docs/development/ROADMAP.md** - This file (development roadmap) -- [ ] **docs/development/TASKS.md** - Task management with checkboxes -- [ ] **docs/development/PROJECT_STATUS.md** - Current status and metrics -- [ ] **docs/development/pm-agent-integration.md** - Integration procedures - -### Success Criteria - -- [x] Documentation structure established -- [x] Architecture clearly documented -- [ ] Roadmap with phase breakdown complete -- [ ] Task tracking system functional -- [ ] Status dashboard provides visibility - ---- - -## Phase 2: PM Agent Mode Integration 🔄 - -**Goal**: Integrate PM Agent mode as always-active meta-layer - -**Timeline**: Week 2-3 (2025-10-21 ~ 2025-11-03) - -**Status**: 🔄 In Progress (30% complete) - -### Tasks - -#### Documentation Updates -- [x] Update `superclaude/Commands/pm.md` with Session Lifecycle -- [x] Update `superclaude/Agents/pm-agent.md` with PDCA Cycle -- [x] Create `docs/PM_AGENT.md` -- [ ] Update `docs/user-guide/agents.md` - Add PM Agent section -- [ ] Update `docs/user-guide/commands.md` - Add /sc:pm command - -#### Core Implementation -- [ ] Implement `superclaude/Core/session_lifecycle.py` - - [ ] Session start hooks - - [ ] Context restoration logic - - [ ] User report generation - - [ ] Error handling and fallback -- [ ] Implement `superclaude/Core/pdca_engine.py` - - [ ] Plan phase automation - - [ ] Do phase tracking - - [ ] Check phase self-evaluation - - [ ] Act phase documentation -- [ ] Implement `superclaude/Core/memory_ops.py` - - [ ] Serena MCP wrapper - - [ ] Memory operation abstractions - - [ ] Checkpoint management - - [ ] Session state handling - -#### Testing -- [ ] Unit tests for session_lifecycle.py -- [ ] Unit tests for pdca_engine.py -- [ ] Unit tests for memory_ops.py -- [ ] Integration tests for PM Agent flow -- [ ] Test auto-activation at session start - -### Deliverables - -- [x] **Updated pm.md and pm-agent.md** - Design documentation -- [x] **PM_AGENT.md** - Status tracking -- [ ] **superclaude/Core/session_lifecycle.py** - Session management -- [ ] **superclaude/Core/pdca_engine.py** - PDCA automation -- [ ] **superclaude/Core/memory_ops.py** - Memory operations -- [ ] **tests/test_pm_agent.py** - Comprehensive test suite - -### Success Criteria - -- [ ] PM Agent mode loads at session start -- [ ] Session Lifecycle functional -- [ ] PDCA Cycle automated -- [ ] Memory operations working -- [ ] All tests passing (>90% coverage) - ---- - -## Phase 3: Serena MCP Integration ⏳ - -**Goal**: Full Serena MCP integration for session persistence - -**Timeline**: Week 4-5 (2025-11-04 ~ 2025-11-17) - -**Status**: ⏳ Planned - -### Tasks - -#### MCP Configuration -- [ ] Install and configure Serena MCP server -- [ ] Update `~/.claude/.claude.json` with Serena config -- [ ] Test basic Serena operations -- [ ] Troubleshoot connection issues - -#### Memory Operations Implementation -- [ ] Implement `list_memories()` integration -- [ ] Implement `read_memory(key)` integration -- [ ] Implement `write_memory(key, value)` integration -- [ ] Implement `delete_memory(key)` integration -- [ ] Test memory persistence across sessions - -#### Think Operations Implementation -- [ ] Implement `think_about_task_adherence()` hook -- [ ] Implement `think_about_collected_information()` hook -- [ ] Implement `think_about_whether_you_are_done()` hook -- [ ] Integrate with TodoWrite completion tracking -- [ ] Test self-evaluation triggers - -#### Cross-Session Testing -- [ ] Test context restoration after restart -- [ ] Test checkpoint save/restore -- [ ] Test memory persistence durability -- [ ] Test multi-project memory isolation -- [ ] Performance testing (memory operations latency) - -### Deliverables - -- [ ] **Serena MCP Server** - Configured and operational -- [ ] **superclaude/Core/serena_client.py** - Serena MCP client wrapper -- [ ] **superclaude/Core/think_operations.py** - Think hooks implementation -- [ ] **docs/troubleshooting/serena-setup.md** - Setup guide -- [ ] **tests/test_serena_integration.py** - Integration test suite - -### Success Criteria - -- [ ] Serena MCP server operational -- [ ] All memory operations functional -- [ ] Think operations trigger correctly -- [ ] Cross-session persistence verified -- [ ] Performance acceptable (<100ms per operation) - ---- - -## Phase 4: Documentation Strategy ⏳ - -**Goal**: Implement systematic documentation lifecycle - -**Timeline**: Week 6-7 (2025-11-18 ~ 2025-12-01) - -**Status**: ⏳ Planned - -### Tasks - -#### Directory Structure -- [ ] Create `docs/temp/` template structure -- [ ] Create `docs/patterns/` template structure -- [ ] Create `docs/mistakes/` template structure -- [ ] Add README.md to each directory explaining purpose -- [ ] Create .gitignore for temporary files - -#### File Templates -- [ ] Create `hypothesis-template.md` for Plan phase -- [ ] Create `experiment-template.md` for Do phase -- [ ] Create `lessons-template.md` for Check phase -- [ ] Create `pattern-template.md` for successful patterns -- [ ] Create `mistake-template.md` for error records - -#### Lifecycle Automation -- [ ] Implement 7-day temporary file cleanup -- [ ] Create docs/temp → docs/patterns migration script -- [ ] Create docs/temp → docs/mistakes migration script -- [ ] Automate "Last Verified" date updates -- [ ] Implement duplicate pattern detection - -#### Knowledge Management -- [ ] Implement pattern extraction logic -- [ ] Implement CLAUDE.md auto-update mechanism -- [ ] Create knowledge graph visualization -- [ ] Implement pattern search functionality -- [ ] Create mistake prevention checklist generator - -### Deliverables - -- [ ] **docs/temp/**, **docs/patterns/**, **docs/mistakes/** - Directory templates -- [ ] **superclaude/Core/doc_lifecycle.py** - Lifecycle automation -- [ ] **superclaude/Core/knowledge_manager.py** - Knowledge extraction -- [ ] **scripts/migrate_docs.py** - Migration utilities -- [ ] **tests/test_doc_lifecycle.py** - Lifecycle test suite - -### Success Criteria - -- [ ] Directory templates functional -- [ ] Lifecycle automation working -- [ ] Migration scripts reliable -- [ ] Knowledge extraction accurate -- [ ] CLAUDE.md auto-updates verified - ---- - -## Phase 5: Auto-Activation System 🔬 - -**Goal**: PM Agent activates automatically at every session start - -**Timeline**: Week 8+ (2025-12-02 onwards) - -**Status**: 🔬 Research Needed - -### Research Phase - -- [ ] Research Claude Code initialization hooks -- [ ] Investigate session start event handling -- [ ] Study existing auto-activation patterns -- [ ] Analyze Claude Code plugin system (if available) -- [ ] Review Anthropic documentation on extensibility - -### Tasks - -#### Hook Implementation -- [ ] Identify session start hook mechanism -- [ ] Implement PM Agent auto-activation hook -- [ ] Test activation timing and reliability -- [ ] Handle edge cases (crash recovery, etc.) -- [ ] Performance optimization (minimize startup delay) - -#### Context Restoration -- [ ] Implement automatic context loading -- [ ] Test memory restoration at startup -- [ ] Verify user report generation -- [ ] Handle missing or corrupted memory -- [ ] Graceful fallback for new sessions - -#### Integration Testing -- [ ] Test across multiple sessions -- [ ] Test with different project contexts -- [ ] Test memory persistence durability -- [ ] Test error recovery mechanisms -- [ ] Performance testing (startup time impact) - -### Deliverables - -- [ ] **superclaude/Core/auto_activation.py** - Auto-activation system -- [ ] **docs/developer-guide/auto-activation.md** - Implementation guide -- [ ] **tests/test_auto_activation.py** - Auto-activation tests -- [ ] **Performance Report** - Startup time impact analysis - -### Success Criteria - -- [ ] PM Agent activates at every session start -- [ ] Context restoration reliable (>99%) -- [ ] User report generated consistently -- [ ] Startup delay minimal (<500ms) -- [ ] Error recovery robust - ---- - -## 🚀 Future Enhancements (Post-Phase 5) - -### Multi-Project Orchestration -- [ ] Cross-project knowledge sharing -- [ ] Unified pattern library -- [ ] Multi-project context switching -- [ ] Project-specific memory namespaces - -### AI-Driven Pattern Recognition -- [ ] Machine learning for pattern extraction -- [ ] Automatic best practice identification -- [ ] Predictive mistake prevention -- [ ] Smart knowledge graph generation - -### Enhanced Self-Evaluation -- [ ] Advanced think operations -- [ ] Quality scoring automation -- [ ] Performance regression detection -- [ ] Code quality trend analysis - -### Community Features -- [ ] Pattern sharing marketplace -- [ ] Community knowledge contributions -- [ ] Collaborative PDCA cycles -- [ ] Public pattern library - ---- - -## 📊 Metrics & KPIs - -### Phase Completion Metrics - -| Metric | Target | Current | Status | -|--------|--------|---------|--------| -| Documentation Coverage | 100% | 40% | 🔄 In Progress | -| PM Agent Integration | 100% | 30% | 🔄 In Progress | -| Serena MCP Integration | 100% | 0% | ⏳ Pending | -| Documentation Strategy | 100% | 0% | ⏳ Pending | -| Auto-Activation | 100% | 0% | 🔬 Research | - -### Quality Metrics - -| Metric | Target | Current | Status | -|--------|--------|---------|--------| -| Test Coverage | >90% | 0% | ⏳ Pending | -| Context Restoration Rate | 100% | N/A | ⏳ Pending | -| Session Continuity | >95% | N/A | ⏳ Pending | -| Documentation Freshness | <7 days | N/A | ⏳ Pending | -| Mistake Prevention | <10% recurring | N/A | ⏳ Pending | - ---- - -## 🔄 Update Schedule - -- **Weekly**: Task progress updates -- **Bi-weekly**: Phase milestone reviews -- **Monthly**: Roadmap revision and priority adjustment -- **Quarterly**: Long-term vision alignment - ---- - -**Last Verified**: 2025-10-14 -**Next Review**: 2025-10-21 (1 week) -**Version**: 4.1.5 diff --git a/docs/Development/TASKS.md b/docs/Development/TASKS.md deleted file mode 100644 index 09e34da..0000000 --- a/docs/Development/TASKS.md +++ /dev/null @@ -1,151 +0,0 @@ -# SuperClaude Development Tasks - -**Last Updated**: 2025-10-14 -**Current Sprint**: Phase 1 - Documentation Structure - ---- - -## 🔥 High Priority (This Week: 2025-10-14 ~ 2025-10-20) - -### Phase 1: Documentation Structure -- [x] Create docs/development/ directory -- [x] Write ARCHITECTURE.md -- [x] Write ROADMAP.md -- [ ] Write TASKS.md (this file) -- [ ] Write PROJECT_STATUS.md -- [ ] Write pm-agent-integration.md -- [ ] Commit Phase 1 changes - -### PM Agent Mode -- [x] Design Session Lifecycle -- [x] Design PDCA Cycle -- [x] Update Commands/pm.md -- [x] Update Agents/pm-agent.md -- [x] Create PM_AGENT.md -- [ ] Commit PM Agent Mode changes - ---- - -## 📋 Medium Priority (This Month: October 2025) - -### Phase 2: Core Implementation -- [ ] Implement superclaude/Core/session_lifecycle.py -- [ ] Implement superclaude/Core/pdca_engine.py -- [ ] Implement superclaude/Core/memory_ops.py -- [ ] Write unit tests for PM Agent core -- [ ] Update user-guide documentation - -### Testing & Validation -- [ ] Create test suite for session_lifecycle -- [ ] Create test suite for pdca_engine -- [ ] Create test suite for memory_ops -- [ ] Integration testing for PM Agent flow -- [ ] Performance benchmarking - ---- - -## 💡 Low Priority (Future) - -### Phase 3: Serena MCP Integration -- [ ] Configure Serena MCP server -- [ ] Test Serena connection -- [ ] Implement memory operations -- [ ] Test cross-session persistence - -### Phase 4: Documentation Strategy -- [ ] Create docs/temp/ template -- [ ] Create docs/patterns/ template -- [ ] Create docs/mistakes/ template -- [ ] Implement 7-day cleanup automation - -### Phase 5: Auto-Activation -- [ ] Research Claude Code init hooks -- [ ] Implement auto-activation -- [ ] Test session start behavior -- [ ] Performance optimization - ---- - -## 🐛 Bugs & Issues - -### Known Issues -- [ ] Serena MCP not configured (blocker for Phase 3) -- [ ] Auto-activation hooks unknown (research needed for Phase 5) -- [ ] Documentation directory structure missing (in progress) - -### Recent Fixes -- [x] PM Agent changes salvaged from ~/.claude directory (2025-10-14) -- [x] Git repository cleanup in ~/.claude (2025-10-14) - ---- - -## ✅ Completed Tasks - -### 2025-10-14 -- [x] Salvaged PM Agent mode changes from ~/.claude -- [x] Cleaned up ~/.claude git repository -- [x] Created PM_AGENT.md -- [x] Created docs/development/ directory -- [x] Wrote ARCHITECTURE.md -- [x] Wrote ROADMAP.md -- [x] Wrote TASKS.md - ---- - -## 📊 Sprint Metrics - -### Current Sprint (Week 1) -- **Planned Tasks**: 8 -- **Completed**: 7 -- **In Progress**: 1 -- **Blocked**: 0 -- **Completion Rate**: 87.5% - -### Overall Progress (Phase 1) -- **Total Tasks**: 6 -- **Completed**: 3 -- **Remaining**: 3 -- **On Schedule**: ✅ Yes - ---- - -## 🔄 Task Management Process - -### Weekly Cycle -1. **Monday**: Review last week, plan this week -2. **Mid-week**: Progress check, adjust priorities -3. **Friday**: Update task status, prepare next week - -### Task Categories -- 🔥 **High Priority**: Must complete this week -- 📋 **Medium Priority**: Complete this month -- 💡 **Low Priority**: Future enhancements -- 🐛 **Bugs**: Critical issues requiring immediate attention - -### Status Markers -- ✅ **Completed**: Task finished and verified -- 🔄 **In Progress**: Currently working on -- ⏳ **Pending**: Waiting for dependencies -- 🚫 **Blocked**: Cannot proceed (document blocker) - ---- - -## 📝 Task Template - -When adding new tasks, use this format: - -```markdown -- [ ] Task description - - **Priority**: High/Medium/Low - - **Estimate**: 1-2 hours / 1-2 days / 1 week - - **Dependencies**: List dependent tasks - - **Blocker**: Any blocking issues - - **Assigned**: Person/Team - - **Due Date**: YYYY-MM-DD -``` - ---- - -**Last Verified**: 2025-10-14 -**Next Update**: 2025-10-17 (Mid-week check) -**Version**: 4.1.5 diff --git a/docs/Development/architecture-overview.md b/docs/Development/architecture-overview.md deleted file mode 100644 index 95981b6..0000000 --- a/docs/Development/architecture-overview.md +++ /dev/null @@ -1,103 +0,0 @@ -# アーキテクチャ概要 - -## プロジェクト構造 - -### メインパッケージ（superclaude/） -``` -superclaude/ -├── __init__.py # パッケージ初期化 -├── __main__.py # CLIエントリーポイント -├── core/ # コア機能 -├── modes/ # 行動モード（7種類） -│ ├── Brainstorming # 要件探索 -│ ├── Business_Panel # ビジネス分析 -│ ├── DeepResearch # 深層研究 -│ ├── Introspection # 内省分析 -│ ├── Orchestration # ツール調整 -│ ├── Task_Management # タスク管理 -│ └── Token_Efficiency # トークン効率化 -├── agents/ # 専門エージェント（16種類） -├── mcp/ # MCPサーバー統合（8種類） -├── commands/ # スラッシュコマンド（26種類） -└── examples/ # 使用例 -``` - -### セットアップパッケージ（setup/） -``` -setup/ -├── __init__.py -├── core/ # インストーラーコア -├── utils/ # ユーティリティ関数 -├── cli/ # CLIインターフェース -├── components/ # インストール可能コンポーネント -│ ├── agents.py # エージェント設定 -│ ├── mcp.py # MCPサーバー設定 -│ └── ... -├── data/ # 設定データ（JSON/YAML） -└── services/ # サービスロジック -``` - -## 主要コンポーネント - -### CLIエントリーポイント（__main__.py） -- `main()`: メインエントリーポイント -- `create_parser()`: 引数パーサー作成 -- `register_operation_parsers()`: サブコマンド登録 -- `setup_global_environment()`: グローバル環境設定 -- `display_*()`: ユーザーインターフェース関数 - -### インストールシステム -- **コンポーネントベース**: モジュラー設計 -- **フォールバック機能**: レガシーサポート -- **設定管理**: `~/.claude/` ディレクトリ -- **MCPサーバー**: Node.js統合 - -## デザインパターン - -### 責任の分離 -- **setup/**: インストールとコンポーネント管理 -- **superclaude/**: ランタイム機能と動作 -- **tests/**: テストとバリデーション -- **docs/**: ドキュメントとガイド - -### プラグインアーキテクチャ -- モジュラーコンポーネントシステム -- 動的ロードと登録 -- 拡張可能な設計 - -### 設定ファイル階層 -1. `~/.claude/CLAUDE.md` - グローバルユーザー設定 -2. プロジェクト固有 `CLAUDE.md` - プロジェクト設定 -3. `~/.claude/.claude.json` - Claude Code設定 -4. MCPサーバー設定ファイル - -## 統合ポイント - -### Claude Code統合 -- スラッシュコマンド注入 -- 行動指示インジェクション -- セッション永続化 - -### MCPサーバー -1. **Context7**: ライブラリドキュメント -2. **Sequential**: 複雑な分析 -3. **Magic**: UIコンポーネント生成 -4. **Playwright**: ブラウザテスト -5. **Morphllm**: 一括変換 -6. **Serena**: セッション永続化 -7. **Tavily**: Web検索 -8. **Chrome DevTools**: パフォーマンス分析 - -## 拡張ポイント - -### 新規コンポーネント追加 -1. `setup/components/` に実装 -2. `setup/data/` に設定追加 -3. テストを `tests/` に追加 -4. ドキュメントを `docs/` に追加 - -### 新規エージェント追加 -1. トリガーキーワード定義 -2. 機能説明作成 -3. 統合テスト追加 -4. ユーザーガイド更新 diff --git a/docs/Development/cli-install-improvements.md b/docs/Development/cli-install-improvements.md deleted file mode 100644 index c101dcd..0000000 --- a/docs/Development/cli-install-improvements.md +++ /dev/null @@ -1,658 +0,0 @@ -# SuperClaude Installation CLI Improvements - -**Date**: 2025-10-17 -**Status**: Proposed Enhancement -**Goal**: Replace interactive prompts with efficient CLI flags for better developer experience - -## 🎯 Objectives - -1. **Speed**: One-command installation without interactive prompts -2. **Scriptability**: CI/CD and automation-friendly -3. **Clarity**: Clear, self-documenting flags -4. **Flexibility**: Support both simple and advanced use cases -5. **Backward Compatibility**: Keep interactive mode as fallback - -## 🚨 Current Problems - -### Problem 1: Slow Interactive Flow -```bash -# Current: Interactive (slow, manual) -$ uv run superclaude install - -Stage 1: MCP Server Selection (Optional) - Select MCP servers to configure: - 1. [ ] sequential-thinking - 2. [ ] context7 - ... - > [user must manually select] - -Stage 2: Framework Component Selection - Select components (Core is recommended): - 1. [ ] core - 2. [ ] modes - ... - > [user must manually select again] - -# Total time: ~60 seconds of clicking -# Automation: Impossible (requires human interaction) -``` - -### Problem 2: Ambiguous Recommendations -```bash -Stage 2: "Select components (Core is recommended):" - -User Confusion: - - Does "Core" include everything needed? - - What about mcp_docs? Is it needed? - - Should I select "all" instead? - - What's the difference between "recommended" and "Core"? -``` - -### Problem 3: No Quick Profiles -```bash -# User wants: "Just install everything I need to get started" -# Current solution: Select ~8 checkboxes manually across 2 stages -# Better solution: `--recommended` flag -``` - -## ✅ Proposed Solution - -### New CLI Flags - -```bash -# Installation Profiles (Quick Start) ---minimal # Minimal installation (core only) ---recommended # Recommended for most users (complete working setup) ---all # Install everything (all components + all MCP servers) - -# Explicit Component Selection ---components NAMES # Specific components (space-separated) ---mcp-servers NAMES # Specific MCP servers (space-separated) - -# Interactive Override ---interactive # Force interactive mode (default if no flags) ---yes, -y # Auto-confirm (skip confirmation prompts) - -# Examples -uv run superclaude install --recommended -uv run superclaude install --minimal -uv run superclaude install --all -uv run superclaude install --components core modes --mcp-servers airis-mcp-gateway -``` - -## 📋 Profile Definitions - -### Profile 1: Minimal -```yaml -Profile: minimal -Purpose: Testing, development, minimal footprint -Components: - - core -MCP Servers: - - None -Use Cases: - - Quick testing - - CI/CD pipelines - - Minimal installations - - Development environments -Estimated Size: ~5 MB -Estimated Tokens: ~50K -``` - -### Profile 2: Recommended (DEFAULT for --recommended) -```yaml -Profile: recommended -Purpose: Complete working installation for most users -Components: - - core - - modes (7 behavioral modes) - - commands (slash commands) - - agents (15 specialized agents) - - mcp_docs (documentation for MCP servers) -MCP Servers: - - airis-mcp-gateway (dynamic tool loading, zero-token baseline) -Use Cases: - - First-time installation - - Production use - - Recommended for 90% of users -Estimated Size: ~30 MB -Estimated Tokens: ~150K -Rationale: - - Complete PM Agent functionality (sub-agent delegation) - - Zero-token baseline with airis-mcp-gateway - - All essential features included - - No missing dependencies -``` - -### Profile 3: Full -```yaml -Profile: full -Purpose: Install everything available -Components: - - core - - modes - - commands - - agents - - mcp - - mcp_docs -MCP Servers: - - airis-mcp-gateway - - sequential-thinking - - context7 - - magic - - playwright - - serena - - morphllm-fast-apply - - tavily - - chrome-devtools -Use Cases: - - Power users - - Comprehensive installations - - Testing all features -Estimated Size: ~50 MB -Estimated Tokens: ~250K -``` - -## 🔧 Implementation Changes - -### File: `setup/cli/commands/install.py` - -#### Change 1: Add Profile Arguments -```python -# Line ~64 (after --components argument) - -parser.add_argument( - "--minimal", - action="store_true", - help="Minimal installation (core only, no MCP servers)" -) - -parser.add_argument( - "--recommended", - action="store_true", - help="Recommended installation (core + modes + commands + agents + mcp_docs + airis-mcp-gateway)" -) - -parser.add_argument( - "--all", - action="store_true", - help="Install all components and all MCP servers" -) - -parser.add_argument( - "--mcp-servers", - type=str, - nargs="+", - help="Specific MCP servers to install (space-separated list)" -) - -parser.add_argument( - "--interactive", - action="store_true", - help="Force interactive mode (default if no profile flags)" -) -``` - -#### Change 2: Profile Resolution Logic -```python -# Add new function after line ~172 - -def resolve_profile(args: argparse.Namespace) -> tuple[List[str], List[str]]: - """ - Resolve installation profile from CLI arguments - - Returns: - (components, mcp_servers) - """ - - # Check for conflicting profiles - profile_flags = [args.minimal, args.recommended, args.all] - if sum(profile_flags) > 1: - raise ValueError("Only one profile flag can be specified: --minimal, --recommended, or --all") - - # Minimal profile - if args.minimal: - return ["core"], [] - - # Recommended profile (default for --recommended) - if args.recommended: - return ( - ["core", "modes", "commands", "agents", "mcp_docs"], - ["airis-mcp-gateway"] - ) - - # Full profile - if args.all: - components = ["core", "modes", "commands", "agents", "mcp", "mcp_docs"] - mcp_servers = [ - "airis-mcp-gateway", - "sequential-thinking", - "context7", - "magic", - "playwright", - "serena", - "morphllm-fast-apply", - "tavily", - "chrome-devtools" - ] - return components, mcp_servers - - # Explicit component selection - if args.components: - components = args.components if isinstance(args.components, list) else [args.components] - mcp_servers = args.mcp_servers if args.mcp_servers else [] - - # Auto-include mcp_docs if any MCP servers selected - if mcp_servers and "mcp_docs" not in components: - components.append("mcp_docs") - logger.info("Auto-included mcp_docs for MCP server documentation") - - # Auto-include mcp component if MCP servers selected - if mcp_servers and "mcp" not in components: - components.append("mcp") - logger.info("Auto-included mcp component for MCP server support") - - return components, mcp_servers - - # No profile specified: return None to trigger interactive mode - return None, None -``` - -#### Change 3: Update `get_components_to_install` -```python -# Modify function at line ~126 - -def get_components_to_install( - args: argparse.Namespace, registry: ComponentRegistry, config_manager: ConfigService -) -> Optional[List[str]]: - """Determine which components to install""" - logger = get_logger() - - # Try to resolve from profile flags first - components, mcp_servers = resolve_profile(args) - - if components is not None: - # Profile resolved, store MCP servers in config - if not hasattr(config_manager, "_installation_context"): - config_manager._installation_context = {} - config_manager._installation_context["selected_mcp_servers"] = mcp_servers - - logger.info(f"Profile selected: {len(components)} components, {len(mcp_servers)} MCP servers") - return components - - # No profile flags: fall back to interactive mode - if args.interactive or not (args.minimal or args.recommended or args.all or args.components): - return interactive_component_selection(registry, config_manager) - - # Should not reach here - return None -``` - -## 📖 Updated Documentation - -### README.md Installation Section -```markdown -## Installation - -### Quick Start (Recommended) -```bash -# One-command installation with everything you need -uv run superclaude install --recommended -``` - -This installs: -- Core framework -- 7 behavioral modes -- SuperClaude slash commands -- 15 specialized AI agents -- airis-mcp-gateway (zero-token baseline) -- Complete documentation - -### Installation Profiles - -**Minimal** (testing/development): -```bash -uv run superclaude install --minimal -``` - -**Recommended** (most users): -```bash -uv run superclaude install --recommended -``` - -**Full** (power users): -```bash -uv run superclaude install --all -``` - -### Custom Installation - -Select specific components: -```bash -uv run superclaude install --components core modes commands -``` - -Select specific MCP servers: -```bash -uv run superclaude install --components core mcp_docs --mcp-servers airis-mcp-gateway context7 -``` - -### Interactive Mode - -If you prefer the guided installation: -```bash -uv run superclaude install --interactive -``` - -### Automation (CI/CD) - -For automated installations: -```bash -uv run superclaude install --recommended --yes -``` - -The `--yes` flag skips confirmation prompts. -``` - -### CONTRIBUTING.md Developer Quickstart -```markdown -## Developer Setup - -### Quick Setup -```bash -# Clone repository -git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git -cd SuperClaude_Framework - -# Install development dependencies -uv sync - -# Run tests -pytest tests/ -v - -# Install SuperClaude (recommended profile) -uv run superclaude install --recommended -``` - -### Testing Different Profiles - -```bash -# Test minimal installation -uv run superclaude install --minimal --install-dir /tmp/test-minimal - -# Test recommended installation -uv run superclaude install --recommended --install-dir /tmp/test-recommended - -# Test full installation -uv run superclaude install --all --install-dir /tmp/test-full -``` - -### Performance Benchmarking - -```bash -# Run installation performance benchmarks -pytest tests/performance/test_installation_performance.py -v --benchmark - -# Compare profiles -pytest tests/performance/test_installation_performance.py::test_compare_profiles -v -``` -``` - -## 🎯 User Experience Improvements - -### Before (Current) -```bash -$ uv run superclaude install -[Interactive Stage 1: MCP selection] -[User clicks through options] -[Interactive Stage 2: Component selection] -[User clicks through options again] -[Confirmation prompt] -[Installation starts] - -Time: ~60 seconds of user interaction -Scriptable: No -Clear expectations: Ambiguous ("Core is recommended" unclear) -``` - -### After (Proposed) -```bash -$ uv run superclaude install --recommended -[Installation starts immediately] -[Progress bar shown] -[Installation complete] - -Time: 0 seconds of user interaction -Scriptable: Yes -Clear expectations: Yes (documented profile) -``` - -### Comparison Table -| Aspect | Current (Interactive) | Proposed (CLI Flags) | -|--------|----------------------|---------------------| -| **User Interaction Time** | ~60 seconds | 0 seconds | -| **Scriptable** | No | Yes | -| **CI/CD Friendly** | No | Yes | -| **Clear Expectations** | Ambiguous | Well-documented | -| **One-Command Install** | No | Yes | -| **Automation** | Impossible | Easy | -| **Profile Comparison** | Manual | Benchmarked | - -## 🧪 Testing Plan - -### Unit Tests -```python -# tests/test_install_cli_flags.py - -def test_profile_minimal(): - """Test --minimal flag""" - args = parse_args(["install", "--minimal"]) - components, mcp_servers = resolve_profile(args) - - assert components == ["core"] - assert mcp_servers == [] - -def test_profile_recommended(): - """Test --recommended flag""" - args = parse_args(["install", "--recommended"]) - components, mcp_servers = resolve_profile(args) - - assert "core" in components - assert "modes" in components - assert "commands" in components - assert "agents" in components - assert "mcp_docs" in components - assert "airis-mcp-gateway" in mcp_servers - -def test_profile_full(): - """Test --all flag""" - args = parse_args(["install", "--all"]) - components, mcp_servers = resolve_profile(args) - - assert len(components) == 6 # All components - assert len(mcp_servers) >= 5 # All MCP servers - -def test_profile_conflict(): - """Test conflicting profile flags""" - with pytest.raises(ValueError): - args = parse_args(["install", "--minimal", "--recommended"]) - resolve_profile(args) - -def test_explicit_components_auto_mcp_docs(): - """Test auto-inclusion of mcp_docs when MCP servers selected""" - args = parse_args([ - "install", - "--components", "core", "modes", - "--mcp-servers", "airis-mcp-gateway" - ]) - components, mcp_servers = resolve_profile(args) - - assert "core" in components - assert "modes" in components - assert "mcp_docs" in components # Auto-included - assert "mcp" in components # Auto-included - assert "airis-mcp-gateway" in mcp_servers -``` - -### Integration Tests -```python -# tests/integration/test_install_profiles.py - -def test_install_minimal_profile(tmp_path): - """Test full installation with --minimal""" - install_dir = tmp_path / "minimal" - - result = subprocess.run( - ["uv", "run", "superclaude", "install", "--minimal", "--install-dir", str(install_dir), "--yes"], - capture_output=True, - text=True - ) - - assert result.returncode == 0 - assert (install_dir / "CLAUDE.md").exists() - assert (install_dir / "core").exists() or len(list(install_dir.glob("*.md"))) > 0 - -def test_install_recommended_profile(tmp_path): - """Test full installation with --recommended""" - install_dir = tmp_path / "recommended" - - result = subprocess.run( - ["uv", "run", "superclaude", "install", "--recommended", "--install-dir", str(install_dir), "--yes"], - capture_output=True, - text=True - ) - - assert result.returncode == 0 - assert (install_dir / "CLAUDE.md").exists() - - # Verify key components installed - assert any(p.match("*MODE_*.md") for p in install_dir.glob("**/*.md")) # Modes - assert any(p.match("MCP_*.md") for p in install_dir.glob("**/*.md")) # MCP docs -``` - -### Performance Tests -```bash -# Use existing benchmark suite -pytest tests/performance/test_installation_performance.py -v - -# Expected results: -# - minimal: ~5 MB, ~50K tokens -# - recommended: ~30 MB, ~150K tokens (3x minimal) -# - full: ~50 MB, ~250K tokens (5x minimal) -``` - -## 📋 Migration Path - -### Phase 1: Add CLI Flags (Backward Compatible) -```yaml -Changes: - - Add --minimal, --recommended, --all flags - - Add --mcp-servers flag - - Keep interactive mode as default - - No breaking changes - -Testing: - - Run all existing tests (should pass) - - Add new tests for CLI flags - - Performance benchmarks - -Release: v4.2.0 (minor version bump) -``` - -### Phase 2: Update Documentation -```yaml -Changes: - - Update README.md with new flags - - Update CONTRIBUTING.md with quickstart - - Add installation guide (docs/installation-guide.md) - - Update examples - -Release: v4.2.1 (patch) -``` - -### Phase 3: Promote CLI Flags (Optional) -```yaml -Changes: - - Make --recommended default if no args - - Keep interactive available via --interactive flag - - Update CLI help text - -Testing: - - User feedback collection - - A/B testing (if possible) - -Release: v4.3.0 (minor version bump) -``` - -## 🎯 Success Metrics - -### Quantitative Metrics -```yaml -Installation Time: - Current (Interactive): ~60 seconds of user interaction - Target (CLI Flags): ~0 seconds of user interaction - Goal: 100% reduction in manual interaction time - -Scriptability: - Current: 0% (requires human interaction) - Target: 100% (fully scriptable) - -CI/CD Adoption: - Current: Not possible - Target: >50% of automated deployments use CLI flags -``` - -### Qualitative Metrics -```yaml -User Satisfaction: - Survey question: "How satisfied are you with the installation process?" - Target: >90% satisfied or very satisfied - -Clarity: - Survey question: "Did you understand what would be installed?" - Target: >95% clear understanding - -Recommendation: - Survey question: "Would you recommend this installation method?" - Target: >90% would recommend -``` - -## 🚀 Next Steps - -1. ✅ Document CLI improvements proposal (this file) -2. ⏳ Implement profile resolution logic -3. ⏳ Add CLI argument parsing -4. ⏳ Write unit tests for profile resolution -5. ⏳ Write integration tests for installations -6. ⏳ Run performance benchmarks (minimal, recommended, full) -7. ⏳ Update documentation (README, CONTRIBUTING, installation guide) -8. ⏳ Gather user feedback -9. ⏳ Prepare Pull Request with evidence - -## 📊 Pull Request Checklist - -Before submitting PR: - -- [ ] All new CLI flags implemented -- [ ] Profile resolution logic added -- [ ] Unit tests written and passing (>90% coverage) -- [ ] Integration tests written and passing -- [ ] Performance benchmarks run (results documented) -- [ ] Documentation updated (README, CONTRIBUTING, installation guide) -- [ ] Backward compatibility maintained (interactive mode still works) -- [ ] No breaking changes -- [ ] User feedback collected (if possible) -- [ ] Examples tested manually -- [ ] CI/CD pipeline tested - -## 📚 Related Documents - -- [Installation Process Analysis](./install-process-analysis.md) -- [Performance Benchmark Suite](../../tests/performance/test_installation_performance.py) -- [PM Agent Parallel Architecture](./pm-agent-parallel-architecture.md) - ---- - -**Conclusion**: CLI flags will dramatically improve the installation experience, making it faster, scriptable, and more suitable for CI/CD workflows. The recommended profile provides a clear, well-documented default that works for 90% of users while maintaining flexibility for advanced use cases. - -**User Benefit**: One-command installation (`--recommended`) with zero interaction time, clear expectations, and full scriptability for automation. diff --git a/docs/Development/code-style.md b/docs/Development/code-style.md deleted file mode 100644 index d7447fa..0000000 --- a/docs/Development/code-style.md +++ /dev/null @@ -1,50 +0,0 @@ -# コードスタイルと規約 - -## Python コーディング規約 - -### フォーマット（Black設定） -- **行長**: 88文字 -- **ターゲットバージョン**: Python 3.8-3.12 -- **除外ディレクトリ**: .eggs, .git, .venv, build, dist - -### 型ヒント（mypy設定） -- **必須**: すべての関数定義に型ヒントを付ける -- `disallow_untyped_defs = true`: 型なし関数定義を禁止 -- `disallow_incomplete_defs = true`: 不完全な型定義を禁止 -- `check_untyped_defs = true`: 型なし関数定義をチェック -- `no_implicit_optional = true`: 暗黙的なOptionalを禁止 - -### ドキュメント規約 -- **パブリックAPI**: すべてドキュメント化必須 -- **例示**: 使用例を含める -- **段階的複雑さ**: 初心者→上級者の順で説明 - -### 命名規則 -- **変数/関数**: snake_case（例: `display_header`, `setup_logging`） -- **クラス**: PascalCase（例: `Colors`, `LogLevel`） -- **定数**: UPPER_SNAKE_CASE -- **プライベート**: 先頭にアンダースコア（例: `_internal_method`） - -### ファイル構造 -``` -superclaude/ # メインパッケージ -├── core/ # コア機能 -├── modes/ # 行動モード -├── agents/ # 専門エージェント -├── mcp/ # MCPサーバー統合 -├── commands/ # スラッシュコマンド -└── examples/ # 使用例 - -setup/ # セットアップコンポーネント -├── core/ # インストーラーコア -├── utils/ # ユーティリティ -├── cli/ # CLIインターフェース -├── components/ # インストール可能コンポーネント -├── data/ # 設定データ -└── services/ # サービスロジック -``` - -### エラーハンドリング -- 包括的なエラーハンドリングとログ記録 -- ユーザーフレンドリーなエラーメッセージ -- アクション可能なエラーガイダンス diff --git a/docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md b/docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md deleted file mode 100644 index 2d27eb1..0000000 --- a/docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md +++ /dev/null @@ -1,390 +0,0 @@ -# PM Agent Autonomous Enhancement - 改善提案 - -> **Date**: 2025-10-14 -> **Status**: 提案中（ユーザーレビュー待ち） -> **Goal**: ユーザーインプット最小化 + 確信を持った先回り提案 - ---- - -## 🎯 現状の問題点 - -### 既存の `superclaude/commands/pm.md` -```yaml -良い点: - ✅ PDCAサイクルが定義されている - ✅ サブエージェント連携が明確 - ✅ ドキュメント記録の仕組みがある - -改善が必要な点: - ❌ ユーザーインプット依存度が高い - ❌ 調査フェーズが受動的 - ❌ 提案が「どうしますか？」スタイル - ❌ 確信を持った提案がない -``` - ---- - -## 💡 改善提案 - -### Phase 0: **自律的調査フェーズ**（新規追加） - -#### ユーザーリクエスト受信時の自動実行 -```yaml -Auto-Investigation (許可不要・自動実行): - 1. Context Restoration: - - Read docs/Development/tasks/current-tasks.md - - list_memories() → 前回のセッション確認 - - read_memory("project_context") → プロジェクト理解 - - read_memory("past_mistakes") → 過去の失敗確認 - - 2. Project Analysis: - - Read CLAUDE.md → プロジェクト固有ルール - - Glob **/*.md → ドキュメント構造把握 - - mcp__serena__get_symbols_overview → コード構造理解 - - Grep "TODO\|FIXME\|XXX" → 既知の課題確認 - - 3. Current State Assessment: - - Bash "git status" → 現在の状態 - - Bash "git log -5 --oneline" → 最近の変更 - - Read tests/ → テストカバレッジ確認 - - Security scan → セキュリティリスク確認 - - 4. Competitive Research (必要時): - - tavily search → ベストプラクティス調査 - - context7 → 公式ドキュメント参照 - - Deep Research → 競合サービス分析 - - 5. Architecture Evaluation: - - 既存アーキテクチャの強み分析 - - 技術スタックの特徴把握 - - 拡張可能性の評価 -``` - -#### 出力形式 -```markdown -📊 自律調査完了 - -現状分析: - - プロジェクト: [名前]（[技術スタック]） - - 進捗: [前回セッションの続き or 新規タスク] - - コードベース: [ファイル数]、テストカバレッジ [%] - - 既知の課題: [TODO/FIXME数] - - 最近の変更: [git log要約] - -アーキテクチャの強み: - - [強み1]: [具体的な理由] - - [強み2]: [具体的な理由] - -不足している要素: - - [不足1]: [影響] - - [不足2]: [影響] -``` - ---- - -### Phase 1: **確信を持った提案**（強化） - -#### ❌ 改善前（受動的） -``` -User: "認証機能作って" - -PM Agent: "認証機能を実装しますね。 - どんな認証方式がいいですか？" - -→ ユーザーに丸投げ -``` - -#### ✅ 改善後（能動的・確信あり） -``` -User: "認証機能作って" - -PM Agent: - 📊 自律調査完了（3秒）: - - 既存: Supabase統合済み（強み） - - 不足: 認証機能なし - - テスト: カバレッジ45%（目標80%） - - 競合調査: Auth0、Clerk、Supabase Auth比較済み - - セキュリティ: OWASP推奨3項目未対応 - - 💡 確信を持った提案: - - このアーキテクチャはSupabase連携に強みがあるため、 - **Supabase Auth統合**を推奨します。 - - 具体的な実装方針: - 1. Supabase Auth統合（JWT + リフレッシュトークン） - 2. MFA対応（TOTP実装） - 3. セキュリティテスト追加（カバレッジ85%目標） - 4. 既存APIとのシームレス統合 - - 選択理由: - ✅ 既存のSupabase接続再利用（実装コスト最小） - ✅ エンタープライズグレードのセキュリティ - ✅ 無料枠で十分な機能（コスト効率◎） - ✅ 将来のスケーラビリティ確保 - - 代替案との比較: - - Auth0: 月$25〜、実装複雑度高 - - Clerk: 月$25〜、React特化（このプロジェクトはNext.js） - - Supabase Auth: 無料、既存統合済み ← 推奨 - - この方針で進めてよろしいですか？ -``` - ---- - -### Phase 2: **自律実行**（既存を強化） - -#### 承認後の自動フロー -```yaml -User: "OK" - -PM Agent（完全自律実行）: - 1. Architecture Design: - - system-architect: Supabase Auth設計 - - security-engineer: セキュリティレビュー - - 2. Implementation: - - backend-architect: API統合実装 - - frontend-architect: UI実装 - - Load magic: Login/Register components - - 3. Testing: - - Write tests/auth/*.test.ts - - pytest実行 → 失敗検出 - - 4. Self-Correction: - - context7 → Supabase公式ドキュメント確認 - - エラー原因特定: "JWTシークレット未設定" - - 修正実装 - - 再テスト → 合格 - - 5. Documentation: - - Update docs/patterns/supabase-auth-integration.md - - Update CLAUDE.md（認証パターン追加） - - write_memory("success_pattern", 詳細) - - 6. Report: - ✅ 認証機能実装完了 - - 実装内容: - - Supabase Auth統合（JWT + リフレッシュ） - - MFA対応（TOTP） - - テストカバレッジ: 45% → 87%（目標達成） - - セキュリティ: OWASP準拠確認済み - - 学習記録: - - 成功パターン: docs/patterns/supabase-auth-integration.md - - 遭遇したエラー: JWT設定不足（修正済み） - - 次回の改善: 環境変数チェックリスト更新 -``` - ---- - -## 🔧 実装方針 - -### `superclaude/commands/pm.md` への追加セクション - -#### 1. Autonomous Investigation Phase（新規） -```markdown -## Phase 0: Autonomous Investigation (Auto-Execute) - -**Trigger**: Any user request received - -**Execution**: Automatic, no permission required - -### Investigation Steps: -1. **Context Restoration** - - Read `docs/Development/tasks/current-tasks.md` - - Serena memory restoration - - Project context loading - -2. **Project Analysis** - - CLAUDE.md → Project rules - - Code structure analysis - - Test coverage check - - Security scan - - Known issues detection (TODO/FIXME) - -3. **Competitive Research** (when relevant) - - Best practices research (Tavily) - - Official documentation (Context7) - - Alternative solutions analysis - -4. **Architecture Evaluation** - - Identify architectural strengths - - Detect technology stack characteristics - - Assess extensibility - -### Output Format: -``` -📊 Autonomous Investigation Complete - -Current State: - - Project: [name] ([stack]) - - Progress: [status] - - Codebase: [files count], Test Coverage: [%] - - Known Issues: [count] - - Recent Changes: [git log summary] - -Architectural Strengths: - - [strength 1]: [rationale] - - [strength 2]: [rationale] - -Missing Elements: - - [gap 1]: [impact] - - [gap 2]: [impact] -``` -``` - -#### 2. Confident Proposal Phase（強化） -```markdown -## Phase 1: Confident Proposal (Enhanced) - -**Principle**: Never ask "What do you want?" - Always propose with conviction - -### Proposal Format: -``` -💡 Confident Proposal: - -[Implementation approach] is recommended. - -Specific Implementation Plan: -1. [Step 1 with rationale] -2. [Step 2 with rationale] -3. [Step 3 with rationale] - -Selection Rationale: -✅ [Reason 1]: [Evidence] -✅ [Reason 2]: [Evidence] -✅ [Reason 3]: [Evidence] - -Alternatives Considered: -- [Alt 1]: [Why not chosen] -- [Alt 2]: [Why not chosen] -- [Recommended]: [Why chosen] ← Recommended - -Proceed with this approach? -``` - -### Anti-Patterns (Never Do): -❌ "What authentication do you want?" (Passive) -❌ "How should we implement this?" (Uncertain) -❌ "There are several options..." (Indecisive) - -✅ "Supabase Auth is recommended because..." (Confident) -✅ "Based on your architecture's Supabase integration..." (Evidence-based) -``` - -#### 3. Autonomous Execution Phase（既存を明示化） -```markdown -## Phase 2: Autonomous Execution - -**Trigger**: User approval ("OK", "Go ahead", "Yes") - -**Execution**: Fully autonomous, systematic PDCA - -### Self-Correction Loop: -```yaml -Implementation: - - Execute with sub-agents - - Write comprehensive tests - - Run validation - -Error Detected: - → Context7: Check official documentation - → Identify root cause - → Implement fix - → Re-test - → Repeat until passing - -Success: - → Document pattern (docs/patterns/) - → Update learnings (write_memory) - → Report completion with evidence -``` - -### Quality Gates: -- Tests must pass (no exceptions) -- Coverage targets must be met -- Security checks must pass -- Documentation must be updated -``` - ---- - -## 📊 期待される効果 - -### Before (現状) -```yaml -User Input Required: 高 - - 認証方式の選択 - - 実装方針の決定 - - エラー対応の指示 - - テスト方針の決定 - -Proposal Quality: 受動的 - - "どうしますか？"スタイル - - 選択肢の羅列のみ - - ユーザーが決定 - -Execution: 半自動 - - エラー時にユーザーに報告 - - 修正方針をユーザーが指示 -``` - -### After (改善後) -```yaml -User Input Required: 最小 - - "認証機能作って"のみ - - 提案への承認/拒否のみ - -Proposal Quality: 能動的・確信あり - - 調査済みの根拠提示 - - 明確な推奨案 - - 代替案との比較 - -Execution: 完全自律 - - エラー自己修正 - - 公式ドキュメント自動参照 - - テスト合格まで自動実行 - - 学習自動記録 -``` - -### 定量的目標 -- ユーザーインプット削減: **80%削減** -- 提案品質向上: **確信度90%以上** -- 自律実行成功率: **95%以上** - ---- - -## 🚀 実装ステップ - -### Step 1: pm.md 修正 -- [ ] Phase 0: Autonomous Investigation 追加 -- [ ] Phase 1: Confident Proposal 強化 -- [ ] Phase 2: Autonomous Execution 明示化 -- [ ] Examples セクションに具体例追加 - -### Step 2: テスト作成 -- [ ] `tests/test_pm_autonomous.py` -- [ ] 自律調査フローのテスト -- [ ] 確信提案フォーマットのテスト -- [ ] 自己修正ループのテスト - -### Step 3: 動作確認 -- [ ] 開発版インストール -- [ ] 実際のワークフローで検証 -- [ ] フィードバック収集 - -### Step 4: 学習記録 -- [ ] `docs/patterns/pm-autonomous-workflow.md` -- [ ] 成功パターンの文書化 - ---- - -## ✅ ユーザー承認待ち - -**この方針で実装を進めてよろしいですか？** - -承認いただければ、すぐに `superclaude/commands/pm.md` の修正を開始します。 diff --git a/docs/Development/install-process-analysis.md b/docs/Development/install-process-analysis.md deleted file mode 100644 index e1133b5..0000000 --- a/docs/Development/install-process-analysis.md +++ /dev/null @@ -1,489 +0,0 @@ -# SuperClaude Installation Process Analysis - -**Date**: 2025-10-17 -**Analyzer**: PM Agent + User Feedback -**Status**: Critical Issues Identified - -## 🚨 Critical Issues - -### Issue 1: Misleading "Core is recommended" Message - -**Location**: `setup/cli/commands/install.py:343` - -**Problem**: -```yaml -Stage 2 Message: "Select components (Core is recommended):" - -User Behavior: - - Sees "Core is recommended" - - Selects only "core" - - Expects complete working installation - -Actual Result: - - mcp_docs NOT installed (unless user selects 'all') - - airis-mcp-gateway documentation missing - - Potentially broken MCP server functionality - -Root Cause: - - auto_selected_mcp_docs logic exists (L362-368) - - BUT only triggers if MCP servers selected in Stage 1 - - If user skips Stage 1 → no mcp_docs auto-selection -``` - -**Evidence**: -```python -# setup/cli/commands/install.py:362-368 -if auto_selected_mcp_docs and "mcp_docs" not in selected_components: - mcp_docs_index = len(framework_components) - if mcp_docs_index not in selections: - # User didn't select it, but we auto-select it - selected_components.append("mcp_docs") - logger.info("Auto-selected MCP documentation for configured servers") -``` - -**Impact**: -- 🔴 **High**: Users following "Core is recommended" get incomplete installation -- 🔴 **High**: No warning about missing MCP documentation -- 🟡 **Medium**: User confusion about "why doesn't airis-mcp-gateway work?" - -### Issue 2: Redundant Interactive Installation - -**Problem**: -```yaml -Current Flow: - Stage 1: MCP Server Selection (interactive menu) - Stage 2: Framework Component Selection (interactive menu) - -Inefficiency: - - Two separate interactive prompts - - User must manually select each time - - No quick install option - -Better Approach: - CLI flags: --recommended, --minimal, --all, --components core,mcp -``` - -**Evidence**: -```python -# setup/cli/commands/install.py:64-66 -parser.add_argument( - "--components", type=str, nargs="+", help="Specific components to install" -) -``` - -CLI support EXISTS but is not promoted or well-documented. - -**Impact**: -- 🟡 **Medium**: Poor developer experience (slow, repetitive) -- 🟡 **Medium**: Discourages experimentation (too many clicks) -- 🟢 **Low**: Advanced users can use --components, but most don't know - -### Issue 3: No Performance Validation - -**Problem**: -```yaml -Assumption: "Install all components = best experience" - -Unverified Questions: - 1. Does full install increase Claude Code context pressure? - 2. Does full install slow down session initialization? - 3. Are all components actually needed for most users? - 4. What's the token usage difference: minimal vs full? - -No Benchmark Data: - - No before/after performance tests - - No token usage comparisons - - No load time measurements - - No context pressure analysis -``` - -**Impact**: -- 🟡 **Medium**: Potential performance regression unknown -- 🟡 **Medium**: Users may install unnecessary components -- 🟢 **Low**: May increase context usage unnecessarily - -## 📊 Proposed Solutions - -### Solution 1: Installation Profiles (Quick Win) - -**Add CLI shortcuts**: -```bash -# Current (verbose) -uv run superclaude install -→ Interactive Stage 1 (MCP selection) -→ Interactive Stage 2 (Component selection) - -# Proposed (efficient) -uv run superclaude install --recommended -→ Installs: core + modes + commands + agents + mcp_docs + airis-mcp-gateway -→ One command, fully working installation - -uv run superclaude install --minimal -→ Installs: core only (for testing/development) - -uv run superclaude install --all -→ Installs: everything (current 'all' behavior) - -uv run superclaude install --components core,mcp --mcp-servers airis-mcp-gateway -→ Explicit component selection (current functionality, clearer) -``` - -**Implementation**: -```python -# Add to setup/cli/commands/install.py - -parser.add_argument( - "--recommended", - action="store_true", - help="Install recommended components (core + modes + commands + agents + mcp_docs + airis-mcp-gateway)" -) - -parser.add_argument( - "--minimal", - action="store_true", - help="Minimal installation (core only)" -) - -parser.add_argument( - "--all", - action="store_true", - help="Install all components" -) - -parser.add_argument( - "--mcp-servers", - type=str, - nargs="+", - help="Specific MCP servers to install" -) -``` - -### Solution 2: Fix Auto-Selection Logic - -**Problem**: `mcp_docs` not included when user selects "Core" only - -**Fix**: -```python -# setup/cli/commands/install.py:select_framework_components - -# After line 360, add: -# ALWAYS include mcp_docs if ANY MCP server will be used -if selected_mcp_servers: - if "mcp_docs" not in selected_components: - selected_components.append("mcp_docs") - logger.info(f"Auto-included mcp_docs for {len(selected_mcp_servers)} MCP servers") - -# Additionally: If airis-mcp-gateway is detected in existing installation, -# auto-include mcp_docs even if not explicitly selected -``` - -### Solution 3: Performance Benchmark Suite - -**Create**: `tests/performance/test_installation_performance.py` - -**Test Scenarios**: -```python -import pytest -import time -from pathlib import Path - -class TestInstallationPerformance: - """Benchmark installation profiles""" - - def test_minimal_install_size(self): - """Measure minimal installation footprint""" - # Install core only - # Measure: directory size, file count, token usage - - def test_recommended_install_size(self): - """Measure recommended installation footprint""" - # Install recommended profile - # Compare to minimal baseline - - def test_full_install_size(self): - """Measure full installation footprint""" - # Install all components - # Compare to recommended baseline - - def test_context_pressure_minimal(self): - """Measure context usage with minimal install""" - # Simulate Claude Code session - # Track token usage for common operations - - def test_context_pressure_full(self): - """Measure context usage with full install""" - # Compare to minimal baseline - # Acceptable threshold: < 20% increase - - def test_load_time_comparison(self): - """Measure Claude Code initialization time""" - # Minimal vs Full install - # Load CLAUDE.md + all imported files - # Measure parsing + processing time -``` - -**Expected Metrics**: -```yaml -Minimal Install: - Size: ~5 MB - Files: ~10 files - Token Usage: ~50K tokens - Load Time: < 1 second - -Recommended Install: - Size: ~30 MB - Files: ~50 files - Token Usage: ~150K tokens (3x minimal) - Load Time: < 3 seconds - -Full Install: - Size: ~50 MB - Files: ~80 files - Token Usage: ~250K tokens (5x minimal) - Load Time: < 5 seconds - -Acceptance Criteria: - - Recommended should be < 3x minimal overhead - - Full should be < 5x minimal overhead - - Load time should be < 5 seconds for any profile -``` - -## 🎯 PM Agent Parallel Architecture Proposal - -**Current PM Agent Design**: -- Sequential sub-agent delegation -- One agent at a time execution -- Manual coordination required - -**Proposed: Deep Research-Style Parallel Execution**: -```yaml -PM Agent as Meta-Layer Commander: - - Request Analysis: - - Parse user intent - - Identify required domains (backend, frontend, security, etc.) - - Classify dependencies (parallel vs sequential) - - Parallel Execution Strategy: - Phase 1 - Independent Analysis (Parallel): - → [backend-architect] analyzes API requirements - → [frontend-architect] analyzes UI requirements - → [security-engineer] analyzes threat model - → All run simultaneously, no blocking - - Phase 2 - Design Integration (Sequential): - → PM Agent synthesizes Phase 1 results - → Creates unified architecture plan - → Identifies conflicts or gaps - - Phase 3 - Parallel Implementation (Parallel): - → [backend-architect] implements APIs - → [frontend-architect] implements UI components - → [quality-engineer] writes tests - → All run simultaneously with coordination - - Phase 4 - Validation (Sequential): - → Integration testing - → Performance validation - → Security audit - - Example Timeline: - Traditional Sequential: 40 minutes - - backend: 10 min - - frontend: 10 min - - security: 10 min - - quality: 10 min - - PM Agent Parallel: 15 minutes (62.5% faster) - - Phase 1 (parallel): 10 min (longest single task) - - Phase 2 (synthesis): 2 min - - Phase 3 (parallel): 10 min - - Phase 4 (validation): 3 min - - Total: 25 min → 15 min with tool optimization -``` - -**Implementation Sketch**: -```python -# superclaude/commands/pm.md (enhanced) - -class PMAgentParallelOrchestrator: - """ - PM Agent with Deep Research-style parallel execution - """ - - async def execute_parallel_phase(self, agents: List[str], context: Dict) -> Dict: - """Execute multiple sub-agents in parallel""" - tasks = [] - for agent_name in agents: - task = self.delegate_to_agent(agent_name, context) - tasks.append(task) - - # Run all agents concurrently - results = await asyncio.gather(*tasks) - - # Synthesize results - return self.synthesize_results(results) - - async def execute_request(self, user_request: str): - """Main orchestration flow""" - - # Phase 0: Analysis - analysis = await self.analyze_request(user_request) - - # Phase 1: Parallel Investigation - if analysis.requires_multiple_domains: - domain_agents = analysis.identify_required_agents() - results_phase1 = await self.execute_parallel_phase( - agents=domain_agents, - context={"task": "analyze", "request": user_request} - ) - - # Phase 2: Synthesis - unified_plan = await self.synthesize_plan(results_phase1) - - # Phase 3: Parallel Implementation - if unified_plan.has_independent_tasks: - impl_agents = unified_plan.identify_implementation_agents() - results_phase3 = await self.execute_parallel_phase( - agents=impl_agents, - context={"task": "implement", "plan": unified_plan} - ) - - # Phase 4: Validation - validation_result = await self.validate_implementation(results_phase3) - - return validation_result -``` - -## 🔄 Dependency Analysis - -**Current Dependency Chain**: -``` -core → (foundation) -modes → depends on core -commands → depends on core, modes -agents → depends on core, commands -mcp → depends on core (optional) -mcp_docs → depends on mcp (should always be included if mcp selected) -``` - -**Proposed Dependency Fix**: -```yaml -Strict Dependencies: - mcp_docs → MUST include if ANY mcp server selected - agents → SHOULD include for optimal PM Agent operation - commands → SHOULD include for slash command functionality - -Optional Dependencies: - modes → OPTIONAL (behavior enhancements) - specific_mcp_servers → OPTIONAL (feature enhancements) - -Recommended Profile: - - core (required) - - commands (optimal experience) - - agents (PM Agent sub-agent delegation) - - mcp_docs (if using any MCP servers) - - airis-mcp-gateway (zero-token baseline + on-demand loading) -``` - -## 📋 Action Items - -### Immediate (Critical) -1. ✅ Document current issues (this file) -2. ⏳ Fix `mcp_docs` auto-selection logic -3. ⏳ Add `--recommended` CLI flag - -### Short-term (Important) -4. ⏳ Design performance benchmark suite -5. ⏳ Run baseline performance tests -6. ⏳ Add `--minimal` and `--mcp-servers` CLI flags - -### Medium-term (Enhancement) -7. ⏳ Implement PM Agent parallel orchestration -8. ⏳ Run performance tests (before/after parallel) -9. ⏳ Prepare Pull Request with evidence - -### Long-term (Strategic) -10. ⏳ Community feedback on installation profiles -11. ⏳ A/B testing: interactive vs CLI default -12. ⏳ Documentation updates - -## 🧪 Testing Strategy - -**Before Pull Request**: -```bash -# 1. Baseline Performance Test -uv run superclaude install --minimal -→ Measure: size, token usage, load time - -uv run superclaude install --recommended -→ Compare to baseline - -uv run superclaude install --all -→ Compare to recommended - -# 2. Functional Tests -pytest tests/test_install_command.py -v -pytest tests/performance/ -v - -# 3. User Acceptance -- Install with --recommended -- Verify airis-mcp-gateway works -- Verify PM Agent can delegate to sub-agents -- Verify no warnings or errors - -# 4. Documentation -- Update README.md with new flags -- Update CONTRIBUTING.md with benchmark requirements -- Create docs/installation-guide.md -``` - -## 💡 Expected Outcomes - -**After Implementing Fixes**: -```yaml -User Experience: - Before: "Core is recommended" → Incomplete install → Confusion - After: "--recommended" → Complete working install → Clear expectations - -Performance: - Before: Unknown (no benchmarks) - After: Measured, optimized, validated - -PM Agent: - Before: Sequential sub-agent execution (slow) - After: Parallel sub-agent execution (60%+ faster) - -Developer Experience: - Before: Interactive only (slow for repeated installs) - After: CLI flags (fast, scriptable, CI-friendly) -``` - -## 🎯 Pull Request Checklist - -Before sending PR to SuperClaude-Org/SuperClaude_Framework: - -- [ ] Performance benchmark suite implemented -- [ ] Baseline tests executed (minimal, recommended, full) -- [ ] Before/After data collected and analyzed -- [ ] CLI flags (`--recommended`, `--minimal`) implemented -- [ ] `mcp_docs` auto-selection logic fixed -- [ ] All tests passing (`pytest tests/ -v`) -- [ ] Documentation updated (README, CONTRIBUTING, installation guide) -- [ ] User feedback gathered (if possible) -- [ ] PM Agent parallel architecture proposal documented -- [ ] No breaking changes introduced -- [ ] Backward compatibility maintained - -**Evidence Required**: -- Performance comparison table (minimal vs recommended vs full) -- Token usage analysis report -- Load time measurements -- Before/After installation flow screenshots -- Test coverage report (>80%) - ---- - -**Conclusion**: The installation process has clear improvement opportunities. With CLI flags, fixed auto-selection, and performance benchmarks, we can provide a much better user experience. The PM Agent parallel architecture proposal offers significant performance gains (60%+ faster) for complex multi-domain tasks. - -**Next Step**: Implement performance benchmark suite to gather evidence before making changes. diff --git a/docs/Development/installation-flow-understanding.md b/docs/Development/installation-flow-understanding.md deleted file mode 100644 index e981e14..0000000 --- a/docs/Development/installation-flow-understanding.md +++ /dev/null @@ -1,378 +0,0 @@ -# SuperClaude Installation Flow - Complete Understanding - -> **学習内容**: インストーラーがどうやって `~/.claude/` にファイルを配置するかの完全理解 - ---- - -## 🔄 インストールフロー全体像 - -### ユーザー操作 -```bash -# Step 1: パッケージインストール -pipx install SuperClaude -# または -npm install -g @bifrost_inc/superclaude - -# Step 2: セットアップ実行 -SuperClaude install -``` - -### 内部処理の流れ - -```yaml -1. Entry Point: - File: superclaude/__main__.py → main() - -2. CLI Parser: - File: superclaude/__main__.py → create_parser() - Command: "install" サブコマンド登録 - -3. Component Manager: - File: setup/cli/install.py - Role: インストールコンポーネントの調整 - -4. Commands Component: - File: setup/components/commands.py → CommandsComponent - Role: スラッシュコマンドのインストール - -5. Source Files: - Location: superclaude/commands/*.md - Content: pm.md, implement.md, test.md, etc. - -6. Destination: - Location: ~/.claude/commands/sc/*.md - Result: ユーザー環境に配置 -``` - ---- - -## 📁 CommandsComponent の詳細 - -### クラス構造 -```python -class CommandsComponent(Component): - """ - Role: スラッシュコマンドのインストール・管理 - Parent: setup/core/base.py → Component - Install Path: ~/.claude/commands/sc/ - """ -``` - -### 主要メソッド - -#### 1. `__init__()` -```python -def __init__(self, install_dir: Optional[Path] = None): - super().__init__(install_dir, Path("commands/sc")) -``` -**理解**: -- `install_dir`: `~/.claude/` （ユーザー環境） -- `Path("commands/sc")`: サブディレクトリ指定 -- 結果: `~/.claude/commands/sc/` にインストール - -#### 2. `_get_source_dir()` -```python -def _get_source_dir(self) -> Path: - # setup/components/commands.py の位置から計算 - project_root = Path(__file__).parent.parent.parent - # → ~/github/SuperClaude_Framework/ - - return project_root / "superclaude" / "commands" - # → ~/github/SuperClaude_Framework/superclaude/commands/ -``` - -**理解**: -``` -Source: ~/github/SuperClaude_Framework/superclaude/commands/*.md -Target: ~/.claude/commands/sc/*.md - -つまり: -superclaude/commands/pm.md - ↓ コピー -~/.claude/commands/sc/pm.md -``` - -#### 3. `_install()` - インストール実行 -```python -def _install(self, config: Dict[str, Any]) -> bool: - self.logger.info("Installing SuperClaude command definitions...") - - # 既存コマンドのマイグレーション - self._migrate_existing_commands() - - # 親クラスのインストール実行 - return super()._install(config) -``` - -**理解**: -1. ログ出力 -2. 旧バージョンからの移行処理 -3. 実際のファイルコピー（親クラスで実行） - -#### 4. `_migrate_existing_commands()` - マイグレーション -```python -def _migrate_existing_commands(self) -> None: - """ - 旧Location: ~/.claude/commands/*.md - 新Location: ~/.claude/commands/sc/*.md - - V3 → V4 移行時の処理 - """ - old_commands_dir = self.install_dir / "commands" - new_commands_dir = self.install_dir / "commands" / "sc" - - # 旧場所からファイル検出 - # 新場所へコピー - # 旧場所から削除 -``` - -**理解**: -- V3: `/analyze` → V4: `/sc:analyze` -- 名前空間衝突を防ぐため `/sc:` プレフィックス - -#### 5. `_post_install()` - メタデータ更新 -```python -def _post_install(self) -> bool: - # メタデータ更新 - metadata_mods = self.get_metadata_modifications() - self.settings_manager.update_metadata(metadata_mods) - - # コンポーネント登録 - self.settings_manager.add_component_registration( - "commands", - { - "version": __version__, - "category": "commands", - "files_count": len(self.component_files), - }, - ) -``` - -**理解**: -- `~/.claude/.superclaude.json` 更新 -- インストール済みコンポーネント記録 -- バージョン管理 - ---- - -## 📋 実際のファイルマッピング - -### Source（このプロジェクト） -``` -~/github/SuperClaude_Framework/superclaude/commands/ -├── pm.md # PM Agent定義 -├── implement.md # Implement コマンド -├── test.md # Test コマンド -├── analyze.md # Analyze コマンド -├── research.md # Research コマンド -├── ...（全26コマンド） -``` - -### Destination（ユーザー環境） -``` -~/.claude/commands/sc/ -├── pm.md # → /sc:pm で実行可能 -├── implement.md # → /sc:implement で実行可能 -├── test.md # → /sc:test で実行可能 -├── analyze.md # → /sc:analyze で実行可能 -├── research.md # → /sc:research で実行可能 -├── ...（全26コマンド） -``` - -### Claude Code動作 -``` -User: /sc:pm "Build authentication" - -Claude Code: - 1. ~/.claude/commands/sc/pm.md 読み込み - 2. YAML frontmatter 解析 - 3. Markdown本文を展開 - 4. PM Agent として実行 -``` - ---- - -## 🔧 他のコンポーネント - -### Modes Component -```python -File: setup/components/modes.py -Source: superclaude/modes/*.md -Target: ~/.claude/*.md - -Example: - superclaude/modes/MODE_Brainstorming.md - ↓ - ~/.claude/MODE_Brainstorming.md -``` - -### Agents Component -```python -File: setup/components/agents.py -Source: superclaude/agents/*.md -Target: ~/.claude/agents/*.md（または統合先） -``` - -### Core Component -```python -File: setup/components/core.py -Source: superclaude/core/CLAUDE.md -Target: ~/.claude/CLAUDE.md - -これがグローバル設定！ -``` - ---- - -## 💡 開発時の注意点 - -### ✅ 正しい変更方法 -```bash -# 1. ソースファイルを変更（Git管理） -cd ~/github/SuperClaude_Framework -vim superclaude/commands/pm.md - -# 2. テスト追加 -Write tests/test_pm_command.py - -# 3. テスト実行 -pytest tests/test_pm_command.py -v - -# 4. コミット -git add superclaude/commands/pm.md tests/ -git commit -m "feat: enhance PM command" - -# 5. 開発版インストール -pip install -e . -# または -SuperClaude install --dev - -# 6. 動作確認 -claude -/sc:pm "test" -``` - -### ❌ 間違った変更方法 -```bash -# ダメ！Git管理外を直接変更 -vim ~/.claude/commands/sc/pm.md - -# 変更は次回インストール時に上書きされる -SuperClaude install # ← 変更が消える！ -``` - ---- - -## 🎯 PM Mode改善の正しいフロー - -### Phase 1: 理解（今ここ！） -```bash -✅ setup/components/commands.py 理解完了 -✅ superclaude/commands/*.md の存在確認完了 -✅ インストールフロー理解完了 -``` - -### Phase 2: 現在の仕様確認 -```bash -# ソース確認（Git管理） -Read superclaude/commands/pm.md - -# インストール後確認（参考用） -Read ~/.claude/commands/sc/pm.md - -# 「なるほど、こういう仕様になってるのか」 -``` - -### Phase 3: 改善案作成 -```bash -# このプロジェクト内で（Git管理） -Write docs/development/hypothesis-pm-enhancement-2025-10-14.md - -内容: -- 現状の問題（ドキュメント寄りすぎ、PMO機能不足） -- 改善案（自律的PDCA、自己評価） -- 実装方針 -- 期待される効果 -``` - -### Phase 4: 実装 -```bash -# ソースファイル修正 -Edit superclaude/commands/pm.md - -変更例: -- PDCA自動実行の強化 -- docs/ ディレクトリ活用の明示 -- 自己評価ステップの追加 -- エラー時再学習フローの追加 -``` - -### Phase 5: テスト・検証 -```bash -# テスト追加 -Write tests/test_pm_enhanced.py - -# テスト実行 -pytest tests/test_pm_enhanced.py -v - -# 開発版インストール -SuperClaude install --dev - -# 実際に使ってみる -claude -/sc:pm "test enhanced workflow" -``` - -### Phase 6: 学習記録 -```bash -# 成功パターン記録 -Write docs/patterns/pm-autonomous-workflow.md - -# 失敗があれば記録 -Write docs/mistakes/mistake-2025-10-14.md -``` - ---- - -## 📊 Component間の依存関係 - -```yaml -Commands Component: - depends_on: ["core"] - -Core Component: - provides: - - ~/.claude/CLAUDE.md（グローバル設定） - - 基本ディレクトリ構造 - -Modes Component: - depends_on: ["core"] - provides: - - ~/.claude/MODE_*.md - -Agents Component: - depends_on: ["core"] - provides: - - エージェント定義 - -MCP Component: - depends_on: ["core"] - provides: - - MCPサーバー設定 -``` - ---- - -## 🚀 次のアクション - -理解完了！次は： - -1. ✅ `superclaude/commands/pm.md` の現在の仕様確認 -2. ✅ 改善提案ドキュメント作成 -3. ✅ 実装修正（PDCA強化、PMO機能追加） -4. ✅ テスト追加・実行 -5. ✅ 動作確認 -6. ✅ 学習記録 - -このドキュメント自体が**インストールフローの完全理解記録**として機能する。 -次回のセッションで読めば、同じ説明を繰り返さなくて済む。 diff --git a/docs/Development/pm-agent-ideal-workflow.md b/docs/Development/pm-agent-ideal-workflow.md deleted file mode 100644 index c7adf40..0000000 --- a/docs/Development/pm-agent-ideal-workflow.md +++ /dev/null @@ -1,341 +0,0 @@ -# PM Agent - Ideal Autonomous Workflow - -> **目的**: 何百回も同じ指示を繰り返さないための自律的オーケストレーションシステム - -## 🎯 解決すべき問題 - -### 現状の課題 -- **繰り返し指示**: 同じことを何百回も説明している -- **同じミスの反復**: 一度間違えたことを再度間違える -- **知識の喪失**: セッションが途切れると学習内容が失われる -- **コンテキスト制限**: 限られたコンテキストで効率的に動作できていない - -### あるべき姿 -**自律的で賢いPM Agent** - ドキュメントから学び、計画し、実行し、検証し、学習を記録するループ - ---- - -## 📋 完璧なワークフロー（理想形） - -### Phase 1: 📖 状況把握（Context Restoration） - -```yaml -1. ドキュメント読み込み: - 優先順位: - 1. タスク管理ドキュメント → 進捗確認 - - docs/development/tasks/current-tasks.md - - 前回どこまでやったか - - 次に何をすべきか - - 2. アーキテクチャドキュメント → 仕組み理解 - - docs/development/architecture-*.md - - このプロジェクトの構造 - - インストールフロー - - コンポーネント連携 - - 3. 禁止事項・ルール → 制約確認 - - CLAUDE.md（グローバル） - - PROJECT/CLAUDE.md（プロジェクト固有） - - docs/development/constraints.md - - 4. 過去の学び → 同じミスを防ぐ - - docs/mistakes/ （失敗記録） - - docs/patterns/ （成功パターン） - -2. ユーザーリクエスト理解: - - 何をしたいのか - - どこまで進んでいるのか - - 何が課題なのか -``` - -### Phase 2: 🔍 調査・分析（Research & Analysis） - -```yaml -1. 既存実装の理解: - # ソースコード側（Git管理） - - setup/components/*.py → インストールロジック - - superclaude/ → ランタイムロジック - - tests/ → テストパターン - - # インストール後（ユーザー環境・Git管理外） - - ~/.claude/commands/sc/ → 実際の配置確認 - - ~/.claude/*.md → 現在の仕様確認 - - 理解内容: - 「なるほど、ここでこう処理されて、 - こういうファイルが ~/.claude/ に作られるのね」 - -2. ベストプラクティス調査: - # Deep Research活用 - - 公式リファレンス確認 - - 他プロジェクトの実装調査 - - 最新のベストプラクティス - - 気づき: - - 「ここ無駄だな」 - - 「ここ古いな」 - - 「これはいい実装だな」 - - 「この共通化できるな」 - -3. 重複・改善ポイント発見: - - ライブラリの共通化可能性 - - 重複実装の検出 - - コード品質向上余地 -``` - -### Phase 3: 📝 計画立案（Planning） - -```yaml -1. 改善仮説作成: - # このプロジェクト内で（Git管理） - File: docs/development/hypothesis-YYYY-MM-DD.md - - 内容: - - 現状の問題点 - - 改善案 - - 期待される効果（トークン削減、パフォーマンス向上等） - - 実装方針 - - 必要なテスト - -2. ユーザーレビュー: - 「こういうプランでこんなことをやろうと思っています」 - - 提示内容: - - 調査結果のサマリー - - 改善提案（理由付き） - - 実装ステップ - - 期待される成果 - - ユーザー承認待ち → OK出たら実装へ -``` - -### Phase 4: 🛠️ 実装（Implementation） - -```yaml -1. ソースコード修正: - # Git管理されているこのプロジェクトで作業 - cd ~/github/SuperClaude_Framework - - 修正対象: - - setup/components/*.py → インストールロジック - - superclaude/ → ランタイム機能 - - setup/data/*.json → 設定データ - - # サブエージェント活用 - - backend-architect: アーキテクチャ実装 - - refactoring-expert: コード改善 - - quality-engineer: テスト設計 - -2. 実装記録: - File: docs/development/experiment-YYYY-MM-DD.md - - 内容: - - 試行錯誤の記録 - - 遭遇したエラー - - 解決方法 - - 気づき -``` - -### Phase 5: ✅ 検証（Validation） - -```yaml -1. テスト作成・実行: - # テストを書く - Write tests/test_new_feature.py - - # テスト実行 - pytest tests/test_new_feature.py -v - - # ユーザー要求を満たしているか確認 - - 期待通りの動作か？ - - エッジケースは？ - - パフォーマンスは？ - -2. エラー時の対応: - エラー発生 - ↓ - 公式リファレンス確認 - 「このエラー何でだろう？」 - 「ここの定義違ってたんだ」 - ↓ - 修正 - ↓ - 再テスト - ↓ - 合格まで繰り返し - -3. 動作確認: - # インストールして実際の環境でテスト - SuperClaude install --dev - - # 動作確認 - claude # 起動して実際に試す -``` - -### Phase 6: 📚 学習記録（Learning Documentation） - -```yaml -1. 成功パターン記録: - File: docs/patterns/[pattern-name].md - - 内容: - - どんな問題を解決したか - - どう実装したか - - なぜこのアプローチか - - 再利用可能なパターン - -2. 失敗・ミス記録: - File: docs/mistakes/mistake-YYYY-MM-DD.md - - 内容: - - どんなミスをしたか - - なぜ起きたか - - 防止策 - - チェックリスト - -3. タスク更新: - File: docs/development/tasks/current-tasks.md - - 内容: - - 完了したタスク - - 次のタスク - - 進捗状況 - - ブロッカー - -4. グローバルパターン更新: - 必要に応じて: - - CLAUDE.md更新（グローバルルール） - - PROJECT/CLAUDE.md更新（プロジェクト固有） -``` - -### Phase 7: 🔄 セッション保存（Session Persistence） - -```yaml -1. Serenaメモリー保存: - write_memory("session_summary", 完了内容) - write_memory("next_actions", 次のアクション) - write_memory("learnings", 学んだこと) - -2. ドキュメント整理: - - docs/temp/ → docs/patterns/ or docs/mistakes/ - - 一時ファイル削除 - - 正式ドキュメント更新 -``` - ---- - -## 🔧 活用可能なツール・リソース - -### MCPサーバー（フル活用） -- **Sequential**: 複雑な分析・推論 -- **Context7**: 公式ドキュメント参照 -- **Tavily**: Deep Research（ベストプラクティス調査） -- **Serena**: セッション永続化、メモリー管理 -- **Playwright**: E2Eテスト、動作確認 -- **Morphllm**: 一括コード変換 -- **Magic**: UI生成（必要時） -- **Chrome DevTools**: パフォーマンス測定 - -### サブエージェント（適材適所） -- **requirements-analyst**: 要件整理 -- **system-architect**: アーキテクチャ設計 -- **backend-architect**: バックエンド実装 -- **refactoring-expert**: コード改善 -- **security-engineer**: セキュリティ検証 -- **quality-engineer**: テスト設計・実行 -- **performance-engineer**: パフォーマンス最適化 -- **technical-writer**: ドキュメント執筆 - -### 他プロジェクト統合 -- **makefile-global**: Makefile標準化パターン -- **airis-mcp-gateway**: MCPゲートウェイ統合 -- その他有用なパターンは積極的に取り込む - ---- - -## 🎯 重要な原則 - -### Git管理の区別 -```yaml -✅ Git管理されている（変更追跡可能）: - - ~/github/SuperClaude_Framework/ - - ここで全ての変更を行う - - コミット履歴で追跡 - - PR提出可能 - -❌ Git管理外（変更追跡不可）: - - ~/.claude/ - - 読むだけ、理解のみ - - テスト時のみ一時変更（必ず戻す！） -``` - -### テスト時の注意 -```bash -# テスト前: 必ずバックアップ -cp ~/.claude/commands/sc/pm.md ~/.claude/commands/sc/pm.md.backup - -# テスト実行 -# ... 検証 ... - -# テスト後: 必ず復元！！ -mv ~/.claude/commands/sc/pm.md.backup ~/.claude/commands/sc/pm.md -``` - -### ドキュメント構造 -``` -docs/ -├── Development/ # 開発用ドキュメント -│ ├── tasks/ # タスク管理 -│ ├── architecture-*.md # アーキテクチャ -│ ├── constraints.md # 制約・禁止事項 -│ ├── hypothesis-*.md # 改善仮説 -│ └── experiment-*.md # 実験記録 -├── patterns/ # 成功パターン（清書後） -├── mistakes/ # 失敗記録と防止策 -└── (既存のuser-guide等) -``` - ---- - -## 🚀 実装優先度 - -### Phase 1（必須） -1. ドキュメント構造整備 -2. タスク管理システム -3. セッション復元ワークフロー - -### Phase 2（重要） -4. 自己評価・検証ループ -5. 学習記録自動化 -6. エラー時再学習フロー - -### Phase 3（強化） -7. PMO機能（重複検出、共通化提案） -8. パフォーマンス測定・改善 -9. 他プロジェクト統合 - ---- - -## 📊 成功指標 - -### 定量的指標 -- **繰り返し指示の削減**: 同じ指示 → 50%削減目標 -- **ミス再発率**: 同じミス → 80%削減目標 -- **セッション復元時間**: <30秒で前回の続きから開始 - -### 定性的指標 -- ユーザーが「前回の続きから」と言うだけで再開できる -- 過去のミスを自動的に避けられる -- 公式ドキュメント参照が自動化されている -- 実装→テスト→検証が自律的に回る - ---- - -## 💡 次のアクション - -このドキュメント作成後: -1. 既存のインストールロジック理解（setup/components/） -2. タスク管理ドキュメント作成（docs/development/tasks/） -3. PM Agent実装修正（このワークフローを実際に実装） - -このドキュメント自体が**PM Agentの憲法**となる。 diff --git a/docs/Development/pm-agent-improvements.md b/docs/Development/pm-agent-improvements.md deleted file mode 100644 index fe693a4..0000000 --- a/docs/Development/pm-agent-improvements.md +++ /dev/null @@ -1,149 +0,0 @@ -# PM Agent Improvement Implementation - 2025-10-14 - -## Implemented Improvements - -### 1. Self-Correcting Execution (Root Cause First) ✅ - -**Core Change**: Never retry the same approach without understanding WHY it failed. - -**Implementation**: -- 6-step error detection protocol -- Mandatory root cause investigation (context7, WebFetch, Grep, Read) -- Hypothesis formation before solution attempt -- Solution must be DIFFERENT from previous attempts -- Learning capture for future reference - -**Anti-Patterns Explicitly Forbidden**: -- ❌ "エラーが出た。もう一回やってみよう" -- ❌ Retry 1, 2, 3 times with same approach -- ❌ "Warningあるけど動くからOK" - -**Correct Patterns Enforced**: -- ✅ Error → Investigate official docs -- ✅ Understand root cause → Design different solution -- ✅ Document learning → Prevent future recurrence - -### 2. Warning/Error Investigation Culture ✅ - -**Core Principle**: 全ての警告・エラーに興味を持って調査する - -**Implementation**: -- Zero tolerance for dismissal -- Mandatory investigation protocol (context7 + WebFetch) -- Impact categorization (Critical/Important/Informational) -- Documentation requirement for all decisions - -**Quality Mindset**: -- Warnings = Future technical debt -- "Works now" ≠ "Production ready" -- Thorough investigation = Higher code quality -- Every warning is a learning opportunity - -### 3. Memory Key Schema (Standardized) ✅ - -**Pattern**: `[category]/[subcategory]/[identifier]` - -**Inspiration**: Kubernetes namespaces, Git refs, Prometheus metrics - -**Categories Defined**: -- `session/`: Session lifecycle management -- `plan/`: Planning phase (hypothesis, architecture, rationale) -- `execution/`: Do phase (experiments, errors, solutions) -- `evaluation/`: Check phase (analysis, metrics, lessons) -- `learning/`: Knowledge capture (patterns, solutions, mistakes) -- `project/`: Project understanding (context, architecture, conventions) - -**Benefits**: -- Consistent naming across all memory operations -- Easy to query and retrieve related memories -- Clear organization for knowledge management -- Inspired by proven OSS practices - -### 4. PDCA Document Structure (Normalized) ✅ - -**Location**: `docs/pdca/[feature-name]/` - -**Structure** (明確・わかりやすい): -``` -docs/pdca/[feature-name]/ - ├── plan.md # Plan: 仮説・設計 - ├── do.md # Do: 実験・試行錯誤 - ├── check.md # Check: 評価・分析 - └── act.md # Act: 改善・次アクション -``` - -**Templates Provided**: -- plan.md: Hypothesis, Expected Outcomes, Risks -- do.md: Implementation log (時系列), Learnings -- check.md: Results vs Expectations, What worked/failed -- act.md: Success patterns, Global rule updates, Checklist updates - -**Lifecycle**: -1. Start → Create plan.md -2. Work → Update do.md continuously -3. Complete → Create check.md -4. Success → Formalize to docs/patterns/ + create act.md -5. Failure → Move to docs/mistakes/ + create act.md with prevention - -## User Feedback Integration - -### Key Insights from User: -1. **同じ方法を繰り返すからループする** → Root cause analysis mandatory -2. **警告を興味を持って調べる癖** → Zero tolerance culture implemented -3. **スキーマ未定義なら定義すべき** → Kubernetes-inspired schema added -4. **plan/do/check/actでわかりやすい** → PDCA structure normalized -5. **OSS参考にアイデアをパクる** → Kubernetes, Git, Prometheus patterns adopted - -### Philosophy Embedded: -- "間違いを理解してから再試行" (Understand before retry) -- "警告 = 将来の技術的負債" (Warnings = Future debt) -- "コード品質向上 = 徹底調査文化" (Quality = Investigation culture) -- "アイデアに著作権なし" (Ideas are free to adopt) - -## Expected Impact - -### Code Quality: -- ✅ Fewer repeated errors (root cause analysis) -- ✅ Proactive technical debt prevention (warning investigation) -- ✅ Higher test coverage and security compliance -- ✅ Consistent documentation and knowledge capture - -### Developer Experience: -- ✅ Clear PDCA structure (plan/do/check/act) -- ✅ Standardized memory keys (easy to use) -- ✅ Learning captured systematically -- ✅ Patterns reusable across projects - -### Long-term Benefits: -- ✅ Continuous improvement culture -- ✅ Knowledge accumulation over sessions -- ✅ Reduced time on repeated mistakes -- ✅ Higher quality autonomous execution - -## Next Steps - -1. **Test in Real Usage**: Apply PM Agent to actual feature implementation -2. **Validate Improvements**: Measure error recovery cycles, warning handling -3. **Iterate Based on Results**: Refine based on real-world performance -4. **Document Success Cases**: Build example library of PDCA cycles -5. **Upstream Contribution**: After validation, contribute to SuperClaude - -## Files Modified - -- `superclaude/commands/pm.md`: - - Added "Self-Correcting Execution (Root Cause First)" section - - Added "Warning/Error Investigation Culture" section - - Added "Memory Key Schema (Standardized)" section - - Added "PDCA Document Structure (Normalized)" section - - ~260 lines of detailed implementation guidance - -## Implementation Quality - -- ✅ User feedback directly incorporated -- ✅ Real-world practices from Kubernetes, Git, Prometheus -- ✅ Clear anti-patterns and correct patterns defined -- ✅ Concrete examples and templates provided -- ✅ Japanese and English mixed (user preference respected) -- ✅ Philosophical principles embedded in implementation - -This improvement represents a fundamental shift from "retry on error" to "understand then solve" approach, which should dramatically improve PM Agent's code quality and learning capabilities. diff --git a/docs/Development/pm-agent-integration.md b/docs/Development/pm-agent-integration.md deleted file mode 100644 index d50c8ba..0000000 --- a/docs/Development/pm-agent-integration.md +++ /dev/null @@ -1,477 +0,0 @@ -# PM Agent Mode Integration Guide - -**Last Updated**: 2025-10-14 -**Target Version**: 4.2.0 -**Status**: Implementation Guide - ---- - -## 📋 Overview - -This guide provides step-by-step procedures for integrating PM Agent mode as SuperClaude's always-active meta-layer with session lifecycle management, PDCA self-evaluation, and systematic knowledge management. - ---- - -## 🎯 Integration Goals - -1. **Session Lifecycle**: Auto-activation at session start with context restoration -2. **PDCA Engine**: Automated Plan-Do-Check-Act cycle execution -3. **Memory Operations**: Serena MCP integration for session persistence -4. **Documentation Strategy**: Systematic knowledge evolution - ---- - -## 📐 Architecture Integration - -### PM Agent Position - -``` -┌──────────────────────────────────────────┐ -│ PM Agent Mode (Meta-Layer) │ -│ • Always Active │ -│ • Session Management │ -│ • PDCA Self-Evaluation │ -└──────────────┬───────────────────────────┘ - ↓ - [Specialist Agents Layer] - ↓ - [Commands & Modes Layer] - ↓ - [MCP Tool Layer] -``` - -See: [ARCHITECTURE.md](./ARCHITECTURE.md) for full system architecture - ---- - -## 🔧 Phase 2: Core Implementation - -### File Structure - -``` -superclaude/ -├── Commands/ -│ └── pm.md # ✅ Already updated -├── Agents/ -│ └── pm-agent.md # ✅ Already updated -└── Core/ - ├── __init__.py # Module initialization - ├── session_lifecycle.py # 🆕 Session management - ├── pdca_engine.py # 🆕 PDCA automation - └── memory_ops.py # 🆕 Memory operations -``` - -### Implementation Order - -1. `memory_ops.py` - Serena MCP wrapper (foundation) -2. `session_lifecycle.py` - Session management (depends on memory_ops) -3. `pdca_engine.py` - PDCA automation (depends on memory_ops) - ---- - -## 1️⃣ memory_ops.py Implementation - -### Purpose -Wrapper for Serena MCP memory operations with error handling and fallback. - -### Key Functions - -```python -# superclaude/Core/memory_ops.py - -class MemoryOperations: - """Serena MCP memory operations wrapper""" - - def list_memories() -> List[str]: - """List all available memories""" - - def read_memory(key: str) -> Optional[Dict]: - """Read memory by key""" - - def write_memory(key: str, value: Dict) -> bool: - """Write memory with key""" - - def delete_memory(key: str) -> bool: - """Delete memory by key""" -``` - -### Integration Points -- Connect to Serena MCP server -- Handle connection errors gracefully -- Provide fallback for offline mode -- Validate memory structure - -### Testing -```bash -pytest tests/test_memory_ops.py -v -``` - ---- - -## 2️⃣ session_lifecycle.py Implementation - -### Purpose -Auto-activation at session start, context restoration, user report generation. - -### Key Functions - -```python -# superclaude/Core/session_lifecycle.py - -class SessionLifecycle: - """Session lifecycle management""" - - def on_session_start(): - """Hook for session start (auto-activation)""" - # 1. list_memories() - # 2. read_memory("pm_context") - # 3. read_memory("last_session") - # 4. read_memory("next_actions") - # 5. generate_user_report() - - def generate_user_report() -> str: - """Generate user report (前回/進捗/今回/課題)""" - - def on_session_end(): - """Hook for session end (checkpoint save)""" - # 1. write_memory("last_session", summary) - # 2. write_memory("next_actions", todos) - # 3. write_memory("pm_context", complete_state) -``` - -### User Report Format -``` -前回: [last session summary] -進捗: [current progress status] -今回: [planned next actions] -課題: [blockers or issues] -``` - -### Integration Points -- Hook into Claude Code session start -- Read memories using memory_ops -- Generate human-readable report -- Handle missing or corrupted memory - -### Testing -```bash -pytest tests/test_session_lifecycle.py -v -``` - ---- - -## 3️⃣ pdca_engine.py Implementation - -### Purpose -Automate PDCA cycle execution with documentation generation. - -### Key Functions - -```python -# superclaude/Core/pdca_engine.py - -class PDCAEngine: - """PDCA cycle automation""" - - def plan_phase(goal: str): - """Generate hypothesis (仮説)""" - # 1. write_memory("plan", goal) - # 2. Create docs/temp/hypothesis-YYYY-MM-DD.md - - def do_phase(): - """Track experimentation (実験)""" - # 1. TodoWrite tracking - # 2. write_memory("checkpoint", progress) every 30min - # 3. Update docs/temp/experiment-YYYY-MM-DD.md - - def check_phase(): - """Self-evaluation (評価)""" - # 1. think_about_task_adherence() - # 2. think_about_whether_you_are_done() - # 3. Create docs/temp/lessons-YYYY-MM-DD.md - - def act_phase(): - """Knowledge extraction (改善)""" - # 1. Success → docs/patterns/[pattern-name].md - # 2. Failure → docs/mistakes/mistake-YYYY-MM-DD.md - # 3. Update CLAUDE.md if global pattern -``` - -### Documentation Templates - -**hypothesis-template.md**: -```markdown -# Hypothesis: [Goal Description] - -Date: YYYY-MM-DD -Status: Planning - -## Goal -What are we trying to accomplish? - -## Approach -How will we implement this? - -## Success Criteria -How do we know when we're done? - -## Potential Risks -What could go wrong? -``` - -**experiment-template.md**: -```markdown -# Experiment Log: [Implementation Name] - -Date: YYYY-MM-DD -Status: In Progress - -## Implementation Steps -- [ ] Step 1 -- [ ] Step 2 - -## Errors Encountered -- Error 1: Description, solution - -## Solutions Applied -- Solution 1: Description, result - -## Checkpoint Saves -- 10:00: [progress snapshot] -- 10:30: [progress snapshot] -``` - -### Integration Points -- Create docs/ directory templates -- Integrate with TodoWrite -- Call Serena MCP think operations -- Generate documentation files - -### Testing -```bash -pytest tests/test_pdca_engine.py -v -``` - ---- - -## 🔌 Phase 3: Serena MCP Integration - -### Prerequisites -```bash -# Install Serena MCP server -# See: docs/troubleshooting/serena-installation.md -``` - -### Configuration -```json -// ~/.claude/.claude.json -{ - "mcpServers": { - "serena": { - "command": "uv", - "args": ["run", "serena-mcp"] - } - } -} -``` - -### Memory Structure -```json -{ - "pm_context": { - "project": "SuperClaude_Framework", - "current_phase": "Phase 2", - "architecture": "Context-Oriented Configuration", - "patterns": ["PDCA Cycle", "Session Lifecycle"] - }, - "last_session": { - "date": "2025-10-14", - "accomplished": ["Phase 1 complete"], - "issues": ["Serena MCP not configured"], - "learned": ["Session Lifecycle pattern"] - }, - "next_actions": [ - "Implement session_lifecycle.py", - "Configure Serena MCP", - "Test memory operations" - ] -} -``` - -### Testing Serena Connection -```bash -# Test memory operations -python -m SuperClaude.Core.memory_ops --test -``` - ---- - -## 📁 Phase 4: Documentation Strategy - -### Directory Structure -``` -docs/ -├── temp/ # Temporary (7-day lifecycle) -│ ├── hypothesis-YYYY-MM-DD.md -│ ├── experiment-YYYY-MM-DD.md -│ └── lessons-YYYY-MM-DD.md -├── patterns/ # Formal patterns (永久保存) -│ └── [pattern-name].md -└── mistakes/ # Mistake records (永久保存) - └── mistake-YYYY-MM-DD.md -``` - -### Lifecycle Automation -```bash -# Create cleanup script -scripts/cleanup_temp_docs.sh - -# Run daily via cron -0 0 * * * /path/to/scripts/cleanup_temp_docs.sh -``` - -### Migration Scripts -```bash -# Migrate successful experiments to patterns -python scripts/migrate_to_patterns.py - -# Migrate failures to mistakes -python scripts/migrate_to_mistakes.py -``` - ---- - -## 🚀 Phase 5: Auto-Activation (Research Needed) - -### Research Questions -1. How does Claude Code handle initialization? -2. Are there plugin hooks available? -3. Can we intercept session start events? - -### Implementation Plan (TBD) -Once research complete, implement auto-activation hooks: - -```python -# superclaude/Core/auto_activation.py (future) - -def on_claude_code_start(): - """Auto-activate PM Agent at session start""" - session_lifecycle.on_session_start() -``` - ---- - -## ✅ Implementation Checklist - -### Phase 2: Core Implementation -- [ ] Implement `memory_ops.py` -- [ ] Write unit tests for memory_ops -- [ ] Implement `session_lifecycle.py` -- [ ] Write unit tests for session_lifecycle -- [ ] Implement `pdca_engine.py` -- [ ] Write unit tests for pdca_engine -- [ ] Integration testing - -### Phase 3: Serena MCP -- [ ] Install Serena MCP server -- [ ] Configure `.claude.json` -- [ ] Test memory operations -- [ ] Test think operations -- [ ] Test cross-session persistence - -### Phase 4: Documentation Strategy -- [ ] Create `docs/temp/` template -- [ ] Create `docs/patterns/` template -- [ ] Create `docs/mistakes/` template -- [ ] Implement lifecycle automation -- [ ] Create migration scripts - -### Phase 5: Auto-Activation -- [ ] Research Claude Code hooks -- [ ] Design auto-activation system -- [ ] Implement auto-activation -- [ ] Test session start behavior - ---- - -## 🧪 Testing Strategy - -### Unit Tests -```bash -tests/ -├── test_memory_ops.py # Memory operations -├── test_session_lifecycle.py # Session management -└── test_pdca_engine.py # PDCA automation -``` - -### Integration Tests -```bash -tests/integration/ -├── test_pm_agent_flow.py # End-to-end PM Agent -├── test_serena_integration.py # Serena MCP integration -└── test_cross_session.py # Session persistence -``` - -### Manual Testing -1. Start new session → Verify context restoration -2. Work on task → Verify checkpoint saves -3. End session → Verify state preservation -4. Restart → Verify seamless resumption - ---- - -## 📊 Success Criteria - -### Functional -- [ ] PM Agent activates at session start -- [ ] Context restores from memory -- [ ] User report generates correctly -- [ ] PDCA cycle executes automatically -- [ ] Documentation strategy works - -### Performance -- [ ] Session start delay <500ms -- [ ] Memory operations <100ms -- [ ] Context restoration reliable (>99%) - -### Quality -- [ ] Test coverage >90% -- [ ] No regression in existing features -- [ ] Documentation complete - ---- - -## 🔧 Troubleshooting - -### Common Issues - -**"Serena MCP not connecting"** -- Check server installation -- Verify `.claude.json` configuration -- Test connection: `claude mcp list` - -**"Memory operations failing"** -- Check network connection -- Verify Serena server running -- Check error logs - -**"Context not restoring"** -- Verify memory structure -- Check `pm_context` exists -- Test with fresh memory - ---- - -## 📚 References - -- [ARCHITECTURE.md](./ARCHITECTURE.md) - System architecture -- [ROADMAP.md](./ROADMAP.md) - Development roadmap -- [PM_AGENT.md](../PM_AGENT.md) - Status tracking -- [Commands/pm.md](../../superclaude/Commands/pm.md) - PM Agent command -- [Agents/pm-agent.md](../../superclaude/Agents/pm-agent.md) - PM Agent persona - ---- - -**Last Verified**: 2025-10-14 -**Next Review**: 2025-10-21 (1 week) -**Version**: 4.1.5 diff --git a/docs/Development/pm-agent-parallel-architecture.md b/docs/Development/pm-agent-parallel-architecture.md deleted file mode 100644 index 6320c3c..0000000 --- a/docs/Development/pm-agent-parallel-architecture.md +++ /dev/null @@ -1,716 +0,0 @@ -# PM Agent Parallel Architecture Proposal - -**Date**: 2025-10-17 -**Status**: Proposed Enhancement -**Inspiration**: Deep Research Agent parallel execution pattern - -## 🎯 Vision - -Transform PM Agent from sequential orchestrator to parallel meta-layer commander, enabling: -- **10x faster execution** for multi-domain tasks -- **Intelligent parallelization** of independent sub-agent operations -- **Deep Research-style** multi-hop parallel analysis -- **Zero-token baseline** with on-demand MCP tool loading - -## 🚨 Current Problem - -**Sequential Execution Bottleneck**: -```yaml -User Request: "Build real-time chat with video calling" - -Current PM Agent Flow (Sequential): - 1. requirements-analyst: 10 minutes - 2. system-architect: 10 minutes - 3. backend-architect: 15 minutes - 4. frontend-architect: 15 minutes - 5. security-engineer: 10 minutes - 6. quality-engineer: 10 minutes - Total: 70 minutes (all sequential) - -Problem: - - Steps 1-2 could run in parallel - - Steps 3-4 could run in parallel after step 2 - - Steps 5-6 could run in parallel with 3-4 - - Actual dependency: Only ~30% of tasks are truly dependent - - 70% of time wasted on unnecessary sequencing -``` - -**Evidence from Deep Research Agent**: -```yaml -Deep Research Pattern: - - Parallel search queries (3-5 simultaneous) - - Parallel content extraction (multiple URLs) - - Parallel analysis (multiple perspectives) - - Sequential only when dependencies exist - -Result: - - 60-70% time reduction - - Better resource utilization - - Improved user experience -``` - -## 🎨 Proposed Architecture - -### Parallel Execution Engine - -```python -# Conceptual architecture (not implementation) - -class PMAgentParallelOrchestrator: - """ - PM Agent with Deep Research-style parallel execution - - Key Principles: - 1. Default to parallel execution - 2. Sequential only for true dependencies - 3. Intelligent dependency analysis - 4. Dynamic MCP tool loading per phase - 5. Self-correction with parallel retry - """ - - def __init__(self): - self.dependency_analyzer = DependencyAnalyzer() - self.mcp_gateway = MCPGatewayManager() # Dynamic tool loading - self.parallel_executor = ParallelExecutor() - self.result_synthesizer = ResultSynthesizer() - - async def orchestrate(self, user_request: str): - """Main orchestration flow""" - - # Phase 0: Request Analysis (Fast, Native Tools) - analysis = await self.analyze_request(user_request) - - # Phase 1: Parallel Investigation - if analysis.requires_multiple_agents: - investigation_results = await self.execute_phase_parallel( - phase="investigation", - agents=analysis.required_agents, - dependencies=analysis.dependencies - ) - - # Phase 2: Synthesis (Sequential, PM Agent) - unified_plan = await self.synthesize_plan(investigation_results) - - # Phase 3: Parallel Implementation - if unified_plan.has_parallelizable_tasks: - implementation_results = await self.execute_phase_parallel( - phase="implementation", - agents=unified_plan.implementation_agents, - dependencies=unified_plan.task_dependencies - ) - - # Phase 4: Parallel Validation - validation_results = await self.execute_phase_parallel( - phase="validation", - agents=["quality-engineer", "security-engineer", "performance-engineer"], - dependencies={} # All independent - ) - - # Phase 5: Final Integration (Sequential, PM Agent) - final_result = await self.integrate_results( - implementation_results, - validation_results - ) - - return final_result - - async def execute_phase_parallel( - self, - phase: str, - agents: List[str], - dependencies: Dict[str, List[str]] - ): - """ - Execute phase with parallel agent execution - - Args: - phase: Phase name (investigation, implementation, validation) - agents: List of agent names to execute - dependencies: Dict mapping agent -> list of dependencies - - Returns: - Synthesized results from all agents - """ - - # 1. Build dependency graph - graph = self.dependency_analyzer.build_graph(agents, dependencies) - - # 2. Identify parallel execution waves - waves = graph.topological_waves() - - # 3. Execute waves in sequence, agents within wave in parallel - all_results = {} - - for wave_num, wave_agents in enumerate(waves): - print(f"Phase {phase} - Wave {wave_num + 1}: {wave_agents}") - - # Load MCP tools needed for this wave - required_tools = self.get_required_tools_for_agents(wave_agents) - await self.mcp_gateway.load_tools(required_tools) - - # Execute all agents in wave simultaneously - wave_tasks = [ - self.execute_agent(agent, all_results) - for agent in wave_agents - ] - - wave_results = await asyncio.gather(*wave_tasks) - - # Store results - for agent, result in zip(wave_agents, wave_results): - all_results[agent] = result - - # Unload MCP tools after wave (resource cleanup) - await self.mcp_gateway.unload_tools(required_tools) - - # 4. Synthesize results across all agents - return self.result_synthesizer.synthesize(all_results) - - async def execute_agent(self, agent_name: str, context: Dict): - """Execute single sub-agent with context""" - agent = self.get_agent_instance(agent_name) - - try: - result = await agent.execute(context) - return { - "status": "success", - "agent": agent_name, - "result": result - } - except Exception as e: - # Error: trigger self-correction flow - return await self.self_correct_agent_execution( - agent_name, - error=e, - context=context - ) - - async def self_correct_agent_execution( - self, - agent_name: str, - error: Exception, - context: Dict - ): - """ - Self-correction flow (from PM Agent design) - - Steps: - 1. STOP - never retry blindly - 2. Investigate root cause (WebSearch, past errors) - 3. Form hypothesis - 4. Design DIFFERENT approach - 5. Execute new approach - 6. Learn (store in mindbase + local files) - """ - # Implementation matches PM Agent self-correction protocol - # (Refer to superclaude/commands/pm.md:536-640) - pass - - -class DependencyAnalyzer: - """Analyze task dependencies for parallel execution""" - - def build_graph(self, agents: List[str], dependencies: Dict) -> DependencyGraph: - """Build dependency graph from agent list and dependencies""" - graph = DependencyGraph() - - for agent in agents: - graph.add_node(agent) - - for agent, deps in dependencies.items(): - for dep in deps: - graph.add_edge(dep, agent) # dep must complete before agent - - return graph - - def infer_dependencies(self, agents: List[str], task_context: Dict) -> Dict: - """ - Automatically infer dependencies based on domain knowledge - - Example: - backend-architect + frontend-architect = parallel (independent) - system-architect → backend-architect = sequential (dependent) - security-engineer = parallel with implementation (independent) - """ - dependencies = {} - - # Rule-based inference - if "system-architect" in agents: - # System architecture must complete before implementation - for agent in ["backend-architect", "frontend-architect"]: - if agent in agents: - dependencies.setdefault(agent, []).append("system-architect") - - if "requirements-analyst" in agents: - # Requirements must complete before any design/implementation - for agent in agents: - if agent != "requirements-analyst": - dependencies.setdefault(agent, []).append("requirements-analyst") - - # Backend and frontend can run in parallel (no dependency) - # Security and quality can run in parallel with implementation - - return dependencies - - -class DependencyGraph: - """Graph representation of agent dependencies""" - - def topological_waves(self) -> List[List[str]]: - """ - Compute topological ordering as waves - - Wave N can execute in parallel (all nodes with no remaining dependencies) - - Returns: - List of waves, each wave is list of agents that can run in parallel - """ - # Kahn's algorithm adapted for wave-based execution - # ... - pass - - -class MCPGatewayManager: - """Manage MCP tool lifecycle (load/unload on demand)""" - - async def load_tools(self, tool_names: List[str]): - """Dynamically load MCP tools via airis-mcp-gateway""" - # Connect to Docker Gateway - # Load specified tools - # Return tool handles - pass - - async def unload_tools(self, tool_names: List[str]): - """Unload MCP tools to free resources""" - # Disconnect from tools - # Free memory - pass - - -class ResultSynthesizer: - """Synthesize results from multiple parallel agents""" - - def synthesize(self, results: Dict[str, Any]) -> Dict: - """ - Combine results from multiple agents into coherent output - - Handles: - - Conflict resolution (agents disagree) - - Gap identification (missing information) - - Integration (combine complementary insights) - """ - pass -``` - -## 🔄 Execution Flow Examples - -### Example 1: Simple Feature (Minimal Parallelization) - -```yaml -User: "Fix login form validation bug in LoginForm.tsx:45" - -PM Agent Analysis: - - Single domain (frontend) - - Simple fix - - Minimal parallelization opportunity - -Execution Plan: - Wave 1 (Parallel): - - refactoring-expert: Fix validation logic - - quality-engineer: Write tests - - Wave 2 (Sequential): - - Integration: Run tests, verify fix - -Timeline: - Traditional Sequential: 15 minutes - PM Agent Parallel: 8 minutes (47% faster) -``` - -### Example 2: Complex Feature (Maximum Parallelization) - -```yaml -User: "Build real-time chat feature with video calling" - -PM Agent Analysis: - - Multi-domain (backend, frontend, security, real-time, media) - - Complex dependencies - - High parallelization opportunity - -Dependency Graph: - requirements-analyst - ↓ - system-architect - ↓ - ├─→ backend-architect (Supabase Realtime) - ├─→ backend-architect (WebRTC signaling) - └─→ frontend-architect (Chat UI) - ↓ - ├─→ frontend-architect (Video UI) - ├─→ security-engineer (Security review) - └─→ quality-engineer (Testing) - ↓ - performance-engineer (Optimization) - -Execution Waves: - Wave 1: requirements-analyst (5 min) - Wave 2: system-architect (10 min) - Wave 3 (Parallel): - - backend-architect: Realtime subscriptions (12 min) - - backend-architect: WebRTC signaling (12 min) - - frontend-architect: Chat UI (12 min) - Wave 4 (Parallel): - - frontend-architect: Video UI (10 min) - - security-engineer: Security review (10 min) - - quality-engineer: Testing (10 min) - Wave 5: performance-engineer (8 min) - -Timeline: - Traditional Sequential: - 5 + 10 + 12 + 12 + 12 + 10 + 10 + 10 + 8 = 89 minutes - - PM Agent Parallel: - 5 + 10 + 12 (longest in wave 3) + 10 (longest in wave 4) + 8 = 45 minutes - - Speedup: 49% faster (nearly 2x) -``` - -### Example 3: Investigation Task (Deep Research Pattern) - -```yaml -User: "Investigate authentication best practices for our stack" - -PM Agent Analysis: - - Research task - - Multiple parallel searches possible - - Deep Research pattern applicable - -Execution Waves: - Wave 1 (Parallel Searches): - - WebSearch: "Supabase Auth best practices 2025" - - WebSearch: "Next.js authentication patterns" - - WebSearch: "JWT security considerations" - - Context7: "Official Supabase Auth documentation" - - Wave 2 (Parallel Analysis): - - Sequential: Analyze search results - - Sequential: Compare patterns - - Sequential: Identify gaps - - Wave 3 (Parallel Content Extraction): - - WebFetch: Top 3 articles (parallel) - - Context7: Framework-specific patterns - - Wave 4 (Sequential Synthesis): - - PM Agent: Synthesize findings - - PM Agent: Create recommendations - -Timeline: - Traditional Sequential: 25 minutes - PM Agent Parallel: 10 minutes (60% faster) -``` - -## 📊 Expected Performance Gains - -### Benchmark Scenarios - -```yaml -Simple Tasks (1-2 agents): - Current: 10-15 minutes - Parallel: 8-12 minutes - Improvement: 20-25% - -Medium Tasks (3-5 agents): - Current: 30-45 minutes - Parallel: 15-25 minutes - Improvement: 40-50% - -Complex Tasks (6-10 agents): - Current: 60-90 minutes - Parallel: 25-45 minutes - Improvement: 50-60% - -Investigation Tasks: - Current: 20-30 minutes - Parallel: 8-15 minutes - Improvement: 60-70% (Deep Research pattern) -``` - -### Resource Utilization - -```yaml -CPU Usage: - Current: 20-30% (one agent at a time) - Parallel: 60-80% (multiple agents) - Better utilization of available resources - -Memory Usage: - With MCP Gateway: Dynamic loading/unloading - Peak memory similar to sequential (tool caching) - -Token Usage: - No increase (same total operations) - Actually may decrease (smarter synthesis) -``` - -## 🔧 Implementation Plan - -### Phase 1: Dependency Analysis Engine -```yaml -Tasks: - - Implement DependencyGraph class - - Implement topological wave computation - - Create rule-based dependency inference - - Test with simple scenarios - -Deliverable: - - Functional dependency analyzer - - Unit tests for graph algorithms - - Documentation -``` - -### Phase 2: Parallel Executor -```yaml -Tasks: - - Implement ParallelExecutor with asyncio - - Wave-based execution engine - - Agent execution wrapper - - Error handling and retry logic - -Deliverable: - - Working parallel execution engine - - Integration tests - - Performance benchmarks -``` - -### Phase 3: MCP Gateway Integration -```yaml -Tasks: - - Integrate with airis-mcp-gateway - - Dynamic tool loading/unloading - - Resource management - - Performance optimization - -Deliverable: - - Zero-token baseline with on-demand loading - - Resource usage monitoring - - Documentation -``` - -### Phase 4: Result Synthesis -```yaml -Tasks: - - Implement ResultSynthesizer - - Conflict resolution logic - - Gap identification - - Integration quality validation - -Deliverable: - - Coherent multi-agent result synthesis - - Quality assurance tests - - User feedback integration -``` - -### Phase 5: Self-Correction Integration -```yaml -Tasks: - - Integrate PM Agent self-correction protocol - - Parallel error recovery - - Learning from failures - - Documentation updates - -Deliverable: - - Robust error handling - - Learning system integration - - Performance validation -``` - -## 🧪 Testing Strategy - -### Unit Tests -```python -# tests/test_pm_agent_parallel.py - -def test_dependency_graph_simple(): - """Test simple linear dependency""" - graph = DependencyGraph() - graph.add_edge("A", "B") - graph.add_edge("B", "C") - - waves = graph.topological_waves() - assert waves == [["A"], ["B"], ["C"]] - -def test_dependency_graph_parallel(): - """Test parallel execution detection""" - graph = DependencyGraph() - graph.add_edge("A", "B") - graph.add_edge("A", "C") # B and C can run in parallel - - waves = graph.topological_waves() - assert waves == [["A"], ["B", "C"]] # or ["C", "B"] - -def test_dependency_inference(): - """Test automatic dependency inference""" - analyzer = DependencyAnalyzer() - agents = ["requirements-analyst", "backend-architect", "frontend-architect"] - - deps = analyzer.infer_dependencies(agents, context={}) - - # Requirements must complete before implementation - assert "requirements-analyst" in deps["backend-architect"] - assert "requirements-analyst" in deps["frontend-architect"] - - # Backend and frontend can run in parallel - assert "backend-architect" not in deps.get("frontend-architect", []) - assert "frontend-architect" not in deps.get("backend-architect", []) -``` - -### Integration Tests -```python -# tests/integration/test_parallel_orchestration.py - -async def test_parallel_feature_implementation(): - """Test full parallel orchestration flow""" - pm_agent = PMAgentParallelOrchestrator() - - result = await pm_agent.orchestrate( - "Build authentication system with JWT and OAuth" - ) - - assert result["status"] == "success" - assert "implementation" in result - assert "tests" in result - assert "documentation" in result - -async def test_performance_improvement(): - """Verify parallel execution is faster than sequential""" - request = "Build complex feature requiring 5 agents" - - # Sequential execution - start = time.perf_counter() - await pm_agent_sequential.orchestrate(request) - sequential_time = time.perf_counter() - start - - # Parallel execution - start = time.perf_counter() - await pm_agent_parallel.orchestrate(request) - parallel_time = time.perf_counter() - start - - # Should be at least 30% faster - assert parallel_time < sequential_time * 0.7 -``` - -### Performance Benchmarks -```bash -# Run comprehensive benchmarks -pytest tests/performance/test_pm_agent_parallel_performance.py -v - -# Expected output: -# - Simple tasks: 20-25% improvement -# - Medium tasks: 40-50% improvement -# - Complex tasks: 50-60% improvement -# - Investigation: 60-70% improvement -``` - -## 🎯 Success Criteria - -### Performance Targets -```yaml -Speedup (vs Sequential): - Simple Tasks (1-2 agents): ≥ 20% - Medium Tasks (3-5 agents): ≥ 40% - Complex Tasks (6-10 agents): ≥ 50% - Investigation Tasks: ≥ 60% - -Resource Usage: - Token Usage: ≤ 100% of sequential (no increase) - Memory Usage: ≤ 120% of sequential (acceptable overhead) - CPU Usage: 50-80% (better utilization) - -Quality: - Result Coherence: ≥ 95% (vs sequential) - Error Rate: ≤ 5% (vs sequential) - User Satisfaction: ≥ 90% (survey-based) -``` - -### User Experience -```yaml -Transparency: - - Show parallel execution progress - - Clear wave-based status updates - - Visible agent coordination - -Control: - - Allow manual dependency specification - - Override parallel execution if needed - - Force sequential mode option - -Reliability: - - Robust error handling - - Graceful degradation to sequential - - Self-correction on failures -``` - -## 📋 Migration Path - -### Backward Compatibility -```yaml -Phase 1 (Current): - - Existing PM Agent works as-is - - No breaking changes - -Phase 2 (Parallel Available): - - Add --parallel flag (opt-in) - - Users can test parallel mode - - Collect feedback - -Phase 3 (Parallel Default): - - Make parallel mode default - - Add --sequential flag (opt-out) - - Monitor performance - -Phase 4 (Deprecate Sequential): - - Remove sequential mode (if proven) - - Full parallel orchestration -``` - -### Feature Flags -```yaml -Environment Variables: - SC_PM_PARALLEL_ENABLED=true|false - SC_PM_MAX_PARALLEL_AGENTS=10 - SC_PM_WAVE_TIMEOUT_SECONDS=300 - SC_PM_MCP_DYNAMIC_LOADING=true|false - -Configuration: - ~/.claude/pm_agent_config.json: - { - "parallel_execution": true, - "max_parallel_agents": 10, - "dependency_inference": true, - "mcp_dynamic_loading": true - } -``` - -## 🚀 Next Steps - -1. ✅ Document parallel architecture proposal (this file) -2. ⏳ Prototype DependencyGraph and wave computation -3. ⏳ Implement ParallelExecutor with asyncio -4. ⏳ Integrate with airis-mcp-gateway -5. ⏳ Run performance benchmarks (before/after) -6. ⏳ Gather user feedback on parallel mode -7. ⏳ Prepare Pull Request with evidence - -## 📚 References - -- Deep Research Agent: Parallel search and analysis pattern -- airis-mcp-gateway: Dynamic tool loading architecture -- PM Agent Current Design: `superclaude/commands/pm.md` -- Performance Benchmarks: `tests/performance/test_installation_performance.py` - ---- - -**Conclusion**: Parallel orchestration will transform PM Agent from sequential coordinator to intelligent meta-layer commander, unlocking 50-60% performance improvements for complex multi-domain tasks while maintaining quality and reliability. - -**User Benefit**: Faster feature development, better resource utilization, and improved developer experience with transparent parallel execution. diff --git a/docs/Development/pm-agent-parallel-execution-complete.md b/docs/Development/pm-agent-parallel-execution-complete.md deleted file mode 100644 index 44441a3..0000000 --- a/docs/Development/pm-agent-parallel-execution-complete.md +++ /dev/null @@ -1,235 +0,0 @@ -# PM Agent Parallel Execution - Complete Implementation - -**Date**: 2025-10-17 -**Status**: ✅ **COMPLETE** - Ready for testing -**Goal**: Transform PM Agent to parallel-first architecture for 2-5x performance improvement - -## 🎯 Mission Accomplished - -PM Agent は並列実行アーキテクチャに完全に書き換えられました。 - -### 変更内容 - -**1. Phase 0: Autonomous Investigation (並列化完了)** -- Wave 1: Context Restoration (4ファイル並列読み込み) → 0.5秒 (was 2.0秒) -- Wave 2: Project Analysis (5並列操作) → 0.5秒 (was 2.5秒) -- Wave 3: Web Research (4並列検索) → 3秒 (was 10秒) -- **Total**: 4秒 vs 14.5秒 = **3.6x faster** ✅ - -**2. Sub-Agent Delegation (並列化完了)** -- Wave-based execution pattern -- Independent agents run in parallel -- Complex task: 50分 vs 117分 = **2.3x faster** ✅ - -**3. Documentation (完了)** -- 並列実行の具体例を追加 -- パフォーマンスベンチマークを文書化 -- Before/After 比較を明示 - -## 📊 Performance Gains - -### Phase 0 Investigation -```yaml -Before (Sequential): - Read pm_context.md (500ms) - Read last_session.md (500ms) - Read next_actions.md (500ms) - Read CLAUDE.md (500ms) - Glob **/*.md (400ms) - Glob **/*.{py,js,ts,tsx} (400ms) - Grep "TODO|FIXME" (300ms) - Bash "git status" (300ms) - Bash "git log" (300ms) - Total: 3.7秒 - -After (Parallel): - Wave 1: max(Read x4) = 0.5秒 - Wave 2: max(Glob, Grep, Bash x3) = 0.5秒 - Total: 1.0秒 - -Improvement: 3.7x faster -``` - -### Sub-Agent Delegation -```yaml -Before (Sequential): - requirements-analyst: 5分 - system-architect: 10分 - backend-architect (Realtime): 12分 - backend-architect (WebRTC): 12分 - frontend-architect (Chat): 12分 - frontend-architect (Video): 10分 - security-engineer: 10分 - quality-engineer: 10分 - performance-engineer: 8分 - Total: 89分 - -After (Parallel Waves): - Wave 1: requirements-analyst (5分) - Wave 2: system-architect (10分) - Wave 3: max(backend x2, frontend, security) = 12分 - Wave 4: max(frontend, quality, performance) = 10分 - Total: 37分 - -Improvement: 2.4x faster -``` - -### End-to-End -```yaml -Example: "Build authentication system with tests" - -Before: - Phase 0: 14秒 - Analysis: 10分 - Implementation: 60分 (sequential agents) - Total: 70分 - -After: - Phase 0: 4秒 (3.5x faster) - Analysis: 10分 (unchanged) - Implementation: 20分 (3x faster, parallel agents) - Total: 30分 - -Overall: 2.3x faster -User Experience: "This is noticeably faster!" ✅ -``` - -## 🔧 Implementation Details - -### Parallel Tool Call Pattern - -**Before (Sequential)**: -``` -Message 1: Read file1 -[wait for result] -Message 2: Read file2 -[wait for result] -Message 3: Read file3 -[wait for result] -``` - -**After (Parallel)**: -``` -Single Message: - - - -[all execute simultaneously] -``` - -### Wave-Based Execution - -```yaml -Dependency Analysis: - Wave 1: No dependencies (start immediately) - Wave 2: Depends on Wave 1 (wait for Wave 1) - Wave 3: Depends on Wave 2 (wait for Wave 2) - -Parallelization within Wave: - Wave 3: [Agent A, Agent B, Agent C] → All run simultaneously - Execution time: max(Agent A, Agent B, Agent C) -``` - -## 📝 Modified Files - -1. **superclaude/commands/pm.md** (Major Changes) - - Line 359-438: Phase 0 Investigation (並列実行版) - - Line 265-340: Behavioral Flow (並列実行パターン追加) - - Line 719-772: Multi-Domain Pattern (並列実行版) - - Line 1188-1254: Performance Optimization (並列実行の成果追加) - -## 🚀 Next Steps - -### 1. Testing (最優先) -```bash -# Test Phase 0 parallel investigation -# User request: "Show me the current project status" -# Expected: PM Agent reads files in parallel (< 1秒) - -# Test parallel sub-agent delegation -# User request: "Build authentication system" -# Expected: backend + frontend + security run in parallel -``` - -### 2. Performance Validation -```bash -# Measure actual performance gains -# Before: Time sequential PM Agent execution -# After: Time parallel PM Agent execution -# Target: 2x+ improvement confirmed -``` - -### 3. User Feedback -```yaml -Questions to ask users: - - "Does PM Agent feel faster?" - - "Do you notice parallel execution?" - - "Is the speed improvement significant?" - -Expected answers: - - "Yes, much faster!" - - "Features ship in half the time" - - "Investigation is almost instant" -``` - -### 4. Documentation -```bash -# If performance gains confirmed: -# 1. Update README.md with performance claims -# 2. Add benchmarks to docs/ -# 3. Create blog post about parallel architecture -# 4. Prepare PR for SuperClaude Framework -``` - -## 🎯 Success Criteria - -**Must Have**: -- [x] Phase 0 Investigation parallelized -- [x] Sub-Agent Delegation parallelized -- [x] Documentation updated with examples -- [x] Performance benchmarks documented -- [ ] **Real-world testing completed** (Next step!) -- [ ] **Performance gains validated** (Next step!) - -**Nice to Have**: -- [ ] Parallel MCP tool loading (airis-mcp-gateway integration) -- [ ] Parallel quality checks (security + performance + testing) -- [ ] Adaptive wave sizing based on available resources - -## 💡 Key Insights - -**Why This Works**: -1. Claude Code supports parallel tool calls natively -2. Most PM Agent operations are independent -3. Wave-based execution preserves dependencies -4. File I/O and network are naturally parallel - -**Why This Matters**: -1. **User Experience**: Feels 2-3x faster (体感で速い) -2. **Productivity**: Features ship in half the time -3. **Competitive Advantage**: Faster than sequential Claude Code -4. **Scalability**: Performance scales with parallel operations - -**Why Users Will Love It**: -1. Investigation is instant (< 5秒) -2. Complex features finish in 30分 instead of 90分 -3. No waiting for sequential operations -4. Transparent parallelization (no user action needed) - -## 🔥 Quote - -> "PM Agent went from 'nice orchestration layer' to 'this is actually faster than doing it myself'. The parallel execution is a game-changer." - -## 📚 Related Documents - -- [PM Agent Command](../../superclaude/commands/pm.md) - Main PM Agent documentation -- [Installation Process Analysis](./install-process-analysis.md) - Installation improvements -- [PM Agent Parallel Architecture Proposal](./pm-agent-parallel-architecture.md) - Original design proposal - ---- - -**Next Action**: Test parallel PM Agent with real user requests and measure actual performance gains. - -**Expected Result**: 2-3x faster execution confirmed, users notice the speed improvement. - -**Success Metric**: "This is noticeably faster!" feedback from users. diff --git a/docs/Development/project-overview.md b/docs/Development/project-overview.md deleted file mode 100644 index 28db475..0000000 --- a/docs/Development/project-overview.md +++ /dev/null @@ -1,24 +0,0 @@ -# SuperClaude Framework - プロジェクト概要 - -## プロジェクトの目的 -SuperClaudeは、Claude Code を構造化された開発プラットフォームに変換するメタプログラミング設定フレームワークです。行動指示の注入とコンポーネントのオーケストレーションを通じて、体系的なワークフロー自動化を提供します。 - -## 主要機能 -- **26個のスラッシュコマンド**: 開発ライフサイクル全体をカバー -- **16個の専門エージェント**: ドメイン固有の専門知識（セキュリティ、パフォーマンス、アーキテクチャなど） -- **7つの行動モード**: ブレインストーミング、タスク管理、トークン効率化など -- **8つのMCPサーバー統合**: Context7、Sequential、Magic、Playwright、Morphllm、Serena、Tavily、Chrome DevTools - -## テクノロジースタック -- **Python 3.8+**: コアフレームワーク実装 -- **Node.js 16+**: NPMラッパー（クロスプラットフォーム配布用） -- **setuptools**: パッケージビルドシステム -- **pytest**: テストフレームワーク -- **black**: コードフォーマッター -- **mypy**: 型チェッカー -- **flake8**: リンター - -## バージョン情報 -- 現在のバージョン: 4.1.5 -- ライセンス: MIT -- Python対応: 3.8, 3.9, 3.10, 3.11, 3.12 diff --git a/docs/Development/project-structure-understanding.md b/docs/Development/project-structure-understanding.md deleted file mode 100644 index 9083815..0000000 --- a/docs/Development/project-structure-understanding.md +++ /dev/null @@ -1,368 +0,0 @@ -# SuperClaude Framework - Project Structure Understanding - -> **Critical Understanding**: このプロジェクトとインストール後の環境の関係 - ---- - -## 🏗️ 2つの世界の区別 - -### 1. このプロジェクト（Git管理・開発環境） - -**Location**: `~/github/SuperClaude_Framework/` - -**Role**: ソースコード・開発・テスト - -``` -SuperClaude_Framework/ -├── setup/ # インストーラーロジック -│ ├── components/ # コンポーネント定義（何をインストールするか） -│ ├── data/ # 設定データ（JSON/YAML） -│ ├── cli/ # CLIインターフェース -│ ├── utils/ # ユーティリティ関数 -│ └── services/ # サービスロジック -│ -├── superclaude/ # ランタイムロジック（実行時の動作） -│ ├── core/ # コア機能 -│ ├── modes/ # 行動モード -│ ├── agents/ # エージェント定義 -│ ├── mcp/ # MCPサーバー統合 -│ └── commands/ # コマンド実装 -│ -├── tests/ # テストコード -├── docs/ # 開発者向けドキュメント -├── pyproject.toml # Python設定 -└── package.json # npm設定 -``` - -**Operations**: -- ✅ ソースコード変更 -- ✅ Git コミット・PR -- ✅ テスト実行 -- ✅ ドキュメント作成 -- ✅ バージョン管理 - ---- - -### 2. インストール後（ユーザー環境・Git管理外） - -**Location**: `~/.claude/` - -**Role**: 実際に動作する設定・コマンド（ユーザー環境） - -``` -~/.claude/ -├── commands/ -│ └── sc/ # スラッシュコマンド（インストール後） -│ ├── pm.md -│ ├── implement.md -│ ├── test.md -│ └── ... (26 commands) -│ -├── CLAUDE.md # グローバル設定（インストール後） -├── *.md # モード定義（インストール後） -│ ├── MODE_Brainstorming.md -│ ├── MODE_Orchestration.md -│ └── ... -│ -└── .claude.json # Claude Code設定 -``` - -**Operations**: -- ✅ **読むだけ**（理解・確認用） -- ✅ 動作確認 -- ⚠️ テスト時のみ一時変更（**必ず元に戻す！**） -- ❌ 永続的な変更禁止（Git追跡不可） - ---- - -## 🔄 インストールフロー - -### ユーザー操作 -```bash -# 1. インストール -pipx install SuperClaude -# または -npm install -g @bifrost_inc/superclaude - -# 2. セットアップ実行 -SuperClaude install -``` - -### 内部処理（setup/が実行） -```python -# setup/components/*.py が実行される - -1. ~/.claude/ ディレクトリ作成 -2. commands/sc/ にスラッシュコマンド配置 -3. CLAUDE.md と各種 *.md 配置 -4. .claude.json 更新 -5. MCPサーバー設定 -``` - -### 結果 -- **このプロジェクトのファイル** → **~/.claude/ にコピー** -- ユーザーがClaude起動 → `~/.claude/` の設定が読み込まれる -- `/sc:pm` 実行 → `~/.claude/commands/sc/pm.md` が展開される - ---- - -## 📝 開発ワークフロー - -### ❌ 間違った方法 -```bash -# Git管理外を直接変更 -vim ~/.claude/commands/sc/pm.md # ← ダメ！履歴追えない - -# 変更テスト -claude # 動作確認 - -# 変更が ~/.claude/ に残る -# → 元に戻すの忘れる -# → 設定がぐちゃぐちゃになる -# → Gitで追跡できない -``` - -### ✅ 正しい方法 - -#### Step 1: 既存実装を理解 -```bash -cd ~/github/SuperClaude_Framework - -# インストールロジック確認 -Read setup/components/commands.py # コマンドのインストール方法 -Read setup/components/modes.py # モードのインストール方法 -Read setup/data/commands.json # コマンド定義データ - -# インストール後の状態確認（理解のため） -ls ~/.claude/commands/sc/ -cat ~/.claude/commands/sc/pm.md # 現在の仕様確認 - -# 「なるほど、setup/components/commands.py でこう処理されて、 -# ~/.claude/commands/sc/ に配置されるのね」 -``` - -#### Step 2: 改善案をドキュメント化 -```bash -cd ~/github/SuperClaude_Framework - -# Git管理されているこのプロジェクト内で -Write docs/development/hypothesis-pm-improvement-YYYY-MM-DD.md - -# 内容例: -# - 現状の問題 -# - 改善案 -# - 実装方針 -# - 期待される効果 -``` - -#### Step 3: テストが必要な場合 -```bash -# バックアップ作成（必須！） -cp ~/.claude/commands/sc/pm.md ~/.claude/commands/sc/pm.md.backup - -# 実験的変更 -vim ~/.claude/commands/sc/pm.md - -# Claude起動して検証 -claude -# ... 動作確認 ... - -# テスト完了後、必ず復元！！ -mv ~/.claude/commands/sc/pm.md.backup ~/.claude/commands/sc/pm.md -``` - -#### Step 4: 本実装 -```bash -cd ~/github/SuperClaude_Framework - -# ソースコード側で変更 -Edit setup/components/commands.py # インストールロジック修正 -Edit setup/data/commands/pm.md # コマンド仕様修正 - -# テスト追加 -Write tests/test_pm_command.py - -# テスト実行 -pytest tests/test_pm_command.py -v - -# コミット（Git履歴に残る） -git add setup/ tests/ -git commit -m "feat: enhance PM command with autonomous workflow" -``` - -#### Step 5: 動作確認 -```bash -# 開発版インストール -cd ~/github/SuperClaude_Framework -pip install -e . - -# または -SuperClaude install --dev - -# 実際の環境でテスト -claude -/sc:pm "test request" -``` - ---- - -## 🎯 重要なルール - -### Rule 1: Git管理の境界を守る -- **変更**: このプロジェクト内のみ -- **確認**: `~/.claude/` は読むだけ -- **テスト**: バックアップ → 変更 → 復元 - -### Rule 2: テスト時は必ず復元 -```bash -# テスト前 -cp original backup - -# テスト -# ... 実験 ... - -# テスト後（必須！） -mv backup original -``` - -### Rule 3: ドキュメント駆動開発 -1. 理解 → docs/development/ に記録 -2. 仮説 → docs/development/hypothesis-*.md -3. 実験 → docs/development/experiment-*.md -4. 成功 → docs/patterns/ -5. 失敗 → docs/mistakes/ - ---- - -## 📚 理解すべきファイル - -### インストーラー側（setup/） -```python -# 優先度: 高 -setup/components/commands.py # コマンドインストール -setup/components/modes.py # モードインストール -setup/components/agents.py # エージェント定義 -setup/data/commands/*.md # コマンド仕様（ソース） -setup/data/modes/*.md # モード仕様（ソース） - -# これらが ~/.claude/ に配置される -``` - -### ランタイム側（superclaude/） -```python -# 優先度: 中 -superclaude/__main__.py # CLIエントリーポイント -superclaude/core/ # コア機能実装 -superclaude/agents/ # エージェントロジック -``` - -### インストール後（~/.claude/） -```markdown -# 優先度: 理解のため（変更不可） -~/.claude/commands/sc/pm.md # 実際に動くPM仕様 -~/.claude/MODE_*.md # 実際に動くモード仕様 -~/.claude/CLAUDE.md # 実際に読み込まれるグローバル設定 -``` - ---- - -## 🔍 デバッグ方法 - -### インストール確認 -```bash -# インストール済みコンポーネント確認 -SuperClaude install --list-components - -# インストール先確認 -ls -la ~/.claude/commands/sc/ -ls -la ~/.claude/*.md -``` - -### 動作確認 -```bash -# Claude起動 -claude - -# コマンド実行 -/sc:pm "test" - -# ログ確認（必要に応じて） -tail -f ~/.claude/logs/*.log -``` - -### トラブルシューティング -```bash -# 設定が壊れた場合 -SuperClaude install --force # 再インストール - -# 開発版に切り替え -cd ~/github/SuperClaude_Framework -pip install -e . - -# 本番版に戻す -pip uninstall superclaude -pipx install SuperClaude -``` - ---- - -## 💡 よくある間違い - -### 間違い1: Git管理外を変更 -```bash -# ❌ WRONG -vim ~/.claude/commands/sc/pm.md -git add ~/.claude/ # ← できない！Git管理外 -``` - -### 間違い2: バックアップなしテスト -```bash -# ❌ WRONG -vim ~/.claude/commands/sc/pm.md -# テスト... -# 元に戻すの忘れる → 設定ぐちゃぐちゃ -``` - -### 間違い3: ソース確認せずに変更 -```bash -# ❌ WRONG -「PMモード直したい」 -→ いきなり ~/.claude/ 変更 -→ ソースコード理解してない -→ 再インストールで上書きされる -``` - -### 正解 -```bash -# ✅ CORRECT -1. setup/components/ でロジック理解 -2. docs/development/ に改善案記録 -3. setup/ 側で変更・テスト -4. Git コミット -5. SuperClaude install --dev で動作確認 -``` - ---- - -## 🚀 次のステップ - -このドキュメント理解後: - -1. **setup/components/ 読解** - - インストールロジックの理解 - - どこに何が配置されるか - -2. **既存仕様の把握** - - `~/.claude/commands/sc/pm.md` 確認（読むだけ） - - 現在の動作理解 - -3. **改善提案作成** - - `docs/development/hypothesis-*.md` 作成 - - ユーザーレビュー - -4. **実装・テスト** - - `setup/` 側で変更 - - `tests/` でテスト追加 - - Git管理下で開発 - -これで**何百回も同じ説明をしなくて済む**ようになる。 diff --git a/docs/Development/tasks/current-tasks.md b/docs/Development/tasks/current-tasks.md deleted file mode 100644 index d839987..0000000 --- a/docs/Development/tasks/current-tasks.md +++ /dev/null @@ -1,163 +0,0 @@ -# Current Tasks - SuperClaude Framework - -> **Last Updated**: 2025-10-14 -> **Session**: PM Agent Enhancement & PDCA Integration - ---- - -## 🎯 Main Objective - -**PM Agent を完璧な自律的オーケストレーターに進化させる** - -- 繰り返し指示を不要にする -- 同じミスを繰り返さない -- セッション間で学習内容を保持 -- 自律的にPDCAサイクルを回す - ---- - -## ✅ Completed Tasks - -### Phase 1: ドキュメント基盤整備 -- [x] **PM Agent理想ワークフローをドキュメント化** - - File: `docs/development/pm-agent-ideal-workflow.md` - - Content: 完璧なワークフロー（7フェーズ） - - Purpose: 次回セッションで同じ説明を繰り返さない - -- [x] **プロジェクト構造理解をドキュメント化** - - File: `docs/development/project-structure-understanding.md` - - Content: Git管理とインストール後環境の区別 - - Purpose: 何百回も説明した内容を外部化 - -- [x] **インストールフロー理解をドキュメント化** - - File: `docs/development/installation-flow-understanding.md` - - Content: CommandsComponent動作の完全理解 - - Source: `superclaude/commands/*.md` → `~/.claude/commands/sc/*.md` - -- [x] **ディレクトリ構造作成** - - `docs/development/tasks/` - タスク管理 - - `docs/patterns/` - 成功パターン記録 - - `docs/mistakes/` - 失敗記録と防止策 - ---- - -## 🔄 In Progress - -### Phase 2: 現状分析と改善提案 - -- [ ] **superclaude/commands/pm.md 現在の仕様確認** - - Status: Pending - - Action: ソースファイルを読んで現在の実装を理解 - - File: `superclaude/commands/pm.md` - -- [ ] **~/.claude/commands/sc/pm.md 動作確認** - - Status: Pending - - Action: インストール後の実際の仕様確認（読むだけ） - - File: `~/.claude/commands/sc/pm.md` - -- [ ] **改善提案ドキュメント作成** - - Status: Pending - - Action: 仮説ドキュメント作成 - - File: `docs/development/hypothesis-pm-enhancement-2025-10-14.md` - - Content: - - 現状の問題点（ドキュメント寄り、PMO機能不足） - - 改善案（自律的PDCA、自己評価） - - 実装方針 - - 期待される効果 - ---- - -## 📋 Pending Tasks - -### Phase 3: 実装修正 - -- [ ] **superclaude/commands/pm.md 修正** - - Content: - - PDCA自動実行の強化 - - docs/ディレクトリ活用の明示 - - 自己評価ステップの追加 - - エラー時再学習フローの追加 - - PMO機能（重複検出、共通化提案） - -- [ ] **MODE_Task_Management.md 修正** - - Serenaメモリー → docs/統合 - - タスク管理ドキュメント連携 - -### Phase 4: テスト・検証 - -- [ ] **テスト追加** - - File: `tests/test_pm_enhanced.py` - - Coverage: PDCA実行、自己評価、学習記録 - -- [ ] **動作確認** - - 開発版インストール: `SuperClaude install --dev` - - 実際のワークフロー実行 - - Before/After比較 - -### Phase 5: 学習記録 - -- [ ] **成功パターン記録** - - File: `docs/patterns/pm-autonomous-workflow.md` - - Content: 自律的PDCAパターンの詳細 - -- [ ] **失敗記録（必要時）** - - File: `docs/mistakes/mistake-2025-10-14.md` - - Content: 遭遇したエラーと防止策 - ---- - -## 🎯 Success Criteria - -### 定量的指標 -- [ ] 繰り返し指示 50%削減 -- [ ] 同じミス再発率 80%削減 -- [ ] セッション復元時間 <30秒 - -### 定性的指標 -- [ ] 「前回の続きから」だけで再開可能 -- [ ] 過去のミスを自動的に回避 -- [ ] 公式ドキュメント参照が自動化 -- [ ] 実装→テスト→検証が自律的に回る - ---- - -## 📝 Notes - -### 重要な学び -- **Git管理の区別が最重要** - - このプロジェクト（Git管理）で変更 - - `~/.claude/`（Git管理外）は読むだけ - - テスト時のバックアップ・復元必須 - -- **ドキュメント駆動開発** - - 理解 → docs/development/ に記録 - - 仮説 → hypothesis-*.md - - 実験 → experiment-*.md - - 成功 → docs/patterns/ - - 失敗 → docs/mistakes/ - -- **インストールフロー** - - Source: `superclaude/commands/*.md` - - Installer: `setup/components/commands.py` - - Target: `~/.claude/commands/sc/*.md` - -### ブロッカー -- なし（現時点） - -### 次回セッション用のメモ -1. このファイル（current-tasks.md）を最初に読む -2. Completedセクションで進捗確認 -3. In Progressから再開 -4. 新しい学びを適切なドキュメントに記録 - ---- - -## 🔗 Related Documentation - -- [PM Agent理想ワークフロー](../pm-agent-ideal-workflow.md) -- [プロジェクト構造理解](../project-structure-understanding.md) -- [インストールフロー理解](../installation-flow-understanding.md) - ---- - -**次のステップ**: `superclaude/commands/pm.md` を読んで現在の仕様を確認する diff --git a/docs/PM_AGENT.md b/docs/PM_AGENT.md deleted file mode 100644 index d7fb8d9..0000000 --- a/docs/PM_AGENT.md +++ /dev/null @@ -1,332 +0,0 @@ -# PM Agent Implementation Status - -**Last Updated**: 2025-10-14 -**Version**: 1.0.0 - -## 📋 Overview - -PM Agent has been redesigned as an **Always-Active Foundation Layer** that provides continuous context preservation, PDCA self-evaluation, and systematic knowledge management across sessions. - ---- - -## ✅ Implemented Features - -### 1. Session Lifecycle (Serena MCP Memory Integration) - -**Status**: ✅ Documented (Implementation Pending) - -#### Session Start Protocol -- **Auto-Activation**: PM Agent restores context at every session start -- **Memory Operations**: - - `list_memories()` → Check existing state - - `read_memory("pm_context")` → Overall project context - - `read_memory("last_session")` → Previous session summary - - `read_memory("next_actions")` → Planned next steps -- **User Report**: Automatic status report (前回/進捗/今回/課題) - -**Implementation Details**: superclaude/Commands/pm.md:34-97 - -#### During Work (PDCA Cycle) -- **Plan Phase**: Hypothesis generation with `docs/temp/hypothesis-*.md` -- **Do Phase**: Experimentation with `docs/temp/experiment-*.md` -- **Check Phase**: Self-evaluation with `docs/temp/lessons-*.md` -- **Act Phase**: Success → `docs/patterns/` | Failure → `docs/mistakes/` - -**Implementation Details**: superclaude/Commands/pm.md:56-80, superclaude/Agents/pm-agent.md:48-98 - -#### Session End Protocol -- **Final Checkpoint**: `think_about_whether_you_are_done()` -- **State Preservation**: `write_memory("pm_context", complete_state)` -- **Documentation Cleanup**: Temporary → Formal/Mistakes - -**Implementation Details**: superclaude/Commands/pm.md:82-97, superclaude/Agents/pm-agent.md:100-135 - ---- - -### 2. PDCA Self-Evaluation Pattern - -**Status**: ✅ Documented (Implementation Pending) - -#### Plan (仮説生成) -- Goal definition and success criteria -- Hypothesis formulation -- Risk identification - -#### Do (実験実行) -- TodoWrite task tracking -- 30-minute checkpoint saves -- Trial-and-error recording - -#### Check (自己評価) -- `think_about_task_adherence()` → Pattern compliance -- `think_about_collected_information()` → Context sufficiency -- `think_about_whether_you_are_done()` → Completion verification - -#### Act (改善実行) -- Success → Extract pattern → docs/patterns/ -- Failure → Root cause analysis → docs/mistakes/ -- Update CLAUDE.md if global pattern - -**Implementation Details**: superclaude/Agents/pm-agent.md:137-175 - ---- - -### 3. Documentation Strategy (Trial-and-Error to Knowledge) - -**Status**: ✅ Documented (Implementation Pending) - -#### Temporary Documentation (`docs/temp/`) -- **Purpose**: Trial-and-error experimentation -- **Files**: - - `hypothesis-YYYY-MM-DD.md` → Initial plan - - `experiment-YYYY-MM-DD.md` → Implementation log - - `lessons-YYYY-MM-DD.md` → Reflections -- **Lifecycle**: 7 days → Move to formal or delete - -#### Formal Documentation (`docs/patterns/`) -- **Purpose**: Successful patterns ready for reuse -- **Trigger**: Verified implementation success -- **Content**: Clean approach + concrete examples + "Last Verified" date - -#### Mistake Documentation (`docs/mistakes/`) -- **Purpose**: Error records with prevention strategies -- **Structure**: - - What Happened (現象) - - Root Cause (根本原因) - - Why Missed (なぜ見逃したか) - - Fix Applied (修正内容) - - Prevention Checklist (防止策) - - Lesson Learned (教訓) - -**Implementation Details**: superclaude/Agents/pm-agent.md:177-235 - ---- - -### 4. Memory Operations Reference - -**Status**: ✅ Documented (Implementation Pending) - -#### Memory Types -- **Session Start**: `pm_context`, `last_session`, `next_actions` -- **During Work**: `plan`, `checkpoint`, `decision` -- **Self-Evaluation**: `think_about_*` operations -- **Session End**: `last_session`, `next_actions`, `pm_context` - -**Implementation Details**: superclaude/Agents/pm-agent.md:237-267 - ---- - -## 🚧 Pending Implementation - -### 1. Serena MCP Memory Operations - -**Required Actions**: -- [ ] Implement `list_memories()` integration -- [ ] Implement `read_memory(key)` integration -- [ ] Implement `write_memory(key, value)` integration -- [ ] Test memory persistence across sessions - -**Blockers**: Requires Serena MCP server configuration - ---- - -### 2. PDCA Think Operations - -**Required Actions**: -- [ ] Implement `think_about_task_adherence()` hook -- [ ] Implement `think_about_collected_information()` hook -- [ ] Implement `think_about_whether_you_are_done()` hook -- [ ] Integrate with TodoWrite completion tracking - -**Blockers**: Requires Serena MCP server configuration - ---- - -### 3. Documentation Directory Structure - -**Required Actions**: -- [ ] Create `docs/temp/` directory template -- [ ] Create `docs/patterns/` directory template -- [ ] Create `docs/mistakes/` directory template -- [ ] Implement automatic file lifecycle management (7-day cleanup) - -**Blockers**: None (can be implemented immediately) - ---- - -### 4. Auto-Activation at Session Start - -**Required Actions**: -- [ ] Implement PM Agent auto-activation hook -- [ ] Integrate with Claude Code session lifecycle -- [ ] Test context restoration across sessions -- [ ] Verify "前回/進捗/今回/課題" report generation - -**Blockers**: Requires understanding of Claude Code initialization hooks - ---- - -## 📊 Implementation Roadmap - -### Phase 1: Documentation Structure (Immediate) -**Timeline**: 1-2 days -**Complexity**: Low - -1. Create `docs/temp/`, `docs/patterns/`, `docs/mistakes/` directories -2. Add README.md to each directory explaining purpose -3. Create template files for hypothesis/experiment/lessons - -### Phase 2: Serena MCP Integration (High Priority) -**Timeline**: 1 week -**Complexity**: Medium - -1. Configure Serena MCP server -2. Implement memory operations (read/write/list) -3. Test memory persistence -4. Integrate with PM Agent workflow - -### Phase 3: PDCA Think Operations (High Priority) -**Timeline**: 1 week -**Complexity**: Medium - -1. Implement think_about_* hooks -2. Integrate with TodoWrite -3. Test self-evaluation flow -4. Document best practices - -### Phase 4: Auto-Activation (Critical) -**Timeline**: 2 weeks -**Complexity**: High - -1. Research Claude Code initialization hooks -2. Implement PM Agent auto-activation -3. Test session start protocol -4. Verify context restoration - -### Phase 5: Documentation Lifecycle (Medium Priority) -**Timeline**: 3-5 days -**Complexity**: Low - -1. Implement 7-day temporary file cleanup -2. Create docs/temp → docs/patterns migration script -3. Create docs/temp → docs/mistakes migration script -4. Automate "Last Verified" date updates - ---- - -## 🔍 Testing Strategy - -### Unit Tests -- [ ] Memory operations (read/write/list) -- [ ] Think operations (task_adherence/collected_information/done) -- [ ] File lifecycle management (7-day cleanup) - -### Integration Tests -- [ ] Session start → context restoration → user report -- [ ] PDCA cycle → temporary docs → formal docs -- [ ] Mistake detection → root cause analysis → prevention checklist - -### E2E Tests -- [ ] Full session lifecycle (start → work → end) -- [ ] Cross-session context preservation -- [ ] Knowledge accumulation over time - ---- - -## 📖 Documentation Updates Needed - -### SuperClaude Framework -- [x] `superclaude/Commands/pm.md` - Updated with session lifecycle -- [x] `superclaude/Agents/pm-agent.md` - Updated with PDCA and memory operations -- [ ] `docs/ARCHITECTURE.md` - Add PM Agent architecture section -- [ ] `docs/GETTING_STARTED.md` - Add PM Agent usage examples - -### Global CLAUDE.md (Future) -- [ ] Add PM Agent PDCA cycle to global rules -- [ ] Document session lifecycle best practices -- [ ] Add memory operations reference - ---- - -## 🐛 Known Issues - -### Issue 1: Serena MCP Not Configured -**Status**: Blocker -**Impact**: High (prevents memory operations) -**Resolution**: Configure Serena MCP server in project - -### Issue 2: Auto-Activation Hook Unknown -**Status**: Research Needed -**Impact**: High (prevents session start automation) -**Resolution**: Research Claude Code initialization hooks - -### Issue 3: Documentation Directory Structure Missing -**Status**: Can Implement Immediately -**Impact**: Medium (prevents PDCA documentation flow) -**Resolution**: Create directory structure (Phase 1) - ---- - -## 📈 Success Metrics - -### Quantitative -- **Context Restoration Rate**: 100% (sessions resume without re-explanation) -- **Documentation Coverage**: >80% (implementations documented) -- **Mistake Prevention**: <10% (recurring mistakes) -- **Session Continuity**: >90% (successful checkpoint restorations) - -### Qualitative -- Users never re-explain project context -- Knowledge accumulates systematically -- Mistakes documented with prevention checklists -- Documentation stays fresh (Last Verified dates) - ---- - -## 🎯 Next Steps - -1. **Immediate**: Create documentation directory structure (Phase 1) -2. **High Priority**: Configure Serena MCP server (Phase 2) -3. **High Priority**: Implement PDCA think operations (Phase 3) -4. **Critical**: Research and implement auto-activation (Phase 4) -5. **Medium Priority**: Implement documentation lifecycle automation (Phase 5) - ---- - -## 📚 References - -- **PM Agent Command**: `superclaude/Commands/pm.md` -- **PM Agent Persona**: `superclaude/Agents/pm-agent.md` -- **Salvaged Changes**: `tmp/salvaged-pm-agent/` -- **Original Patches**: `tmp/salvaged-pm-agent/*.patch` - ---- - -## 🔐 Commit Information - -**Branch**: master -**Salvaged From**: `/Users/kazuki/.claude` (mistaken development location) -**Integration Date**: 2025-10-14 -**Status**: Documentation complete, implementation pending - -**Git Operations**: -```bash -# Salvaged valuable changes to tmp/ -cp ~/.claude/Commands/pm.md tmp/salvaged-pm-agent/pm.md -cp ~/.claude/agents/pm-agent.md tmp/salvaged-pm-agent/pm-agent.md -git diff ~/.claude/CLAUDE.md > tmp/salvaged-pm-agent/CLAUDE.md.patch -git diff ~/.claude/RULES.md > tmp/salvaged-pm-agent/RULES.md.patch - -# Cleaned up .claude directory -cd ~/.claude && git reset --hard HEAD -cd ~/.claude && rm -rf .git - -# Applied changes to SuperClaude_Framework -cp tmp/salvaged-pm-agent/pm.md superclaude/Commands/pm.md -cp tmp/salvaged-pm-agent/pm-agent.md superclaude/Agents/pm-agent.md -``` - ---- - -**Last Verified**: 2025-10-14 -**Next Review**: 2025-10-21 (1 week) diff --git a/docs/pm-agent-implementation-status.md b/docs/pm-agent-implementation-status.md deleted file mode 100644 index d7fb8d9..0000000 --- a/docs/pm-agent-implementation-status.md +++ /dev/null @@ -1,332 +0,0 @@ -# PM Agent Implementation Status - -**Last Updated**: 2025-10-14 -**Version**: 1.0.0 - -## 📋 Overview - -PM Agent has been redesigned as an **Always-Active Foundation Layer** that provides continuous context preservation, PDCA self-evaluation, and systematic knowledge management across sessions. - ---- - -## ✅ Implemented Features - -### 1. Session Lifecycle (Serena MCP Memory Integration) - -**Status**: ✅ Documented (Implementation Pending) - -#### Session Start Protocol -- **Auto-Activation**: PM Agent restores context at every session start -- **Memory Operations**: - - `list_memories()` → Check existing state - - `read_memory("pm_context")` → Overall project context - - `read_memory("last_session")` → Previous session summary - - `read_memory("next_actions")` → Planned next steps -- **User Report**: Automatic status report (前回/進捗/今回/課題) - -**Implementation Details**: superclaude/Commands/pm.md:34-97 - -#### During Work (PDCA Cycle) -- **Plan Phase**: Hypothesis generation with `docs/temp/hypothesis-*.md` -- **Do Phase**: Experimentation with `docs/temp/experiment-*.md` -- **Check Phase**: Self-evaluation with `docs/temp/lessons-*.md` -- **Act Phase**: Success → `docs/patterns/` | Failure → `docs/mistakes/` - -**Implementation Details**: superclaude/Commands/pm.md:56-80, superclaude/Agents/pm-agent.md:48-98 - -#### Session End Protocol -- **Final Checkpoint**: `think_about_whether_you_are_done()` -- **State Preservation**: `write_memory("pm_context", complete_state)` -- **Documentation Cleanup**: Temporary → Formal/Mistakes - -**Implementation Details**: superclaude/Commands/pm.md:82-97, superclaude/Agents/pm-agent.md:100-135 - ---- - -### 2. PDCA Self-Evaluation Pattern - -**Status**: ✅ Documented (Implementation Pending) - -#### Plan (仮説生成) -- Goal definition and success criteria -- Hypothesis formulation -- Risk identification - -#### Do (実験実行) -- TodoWrite task tracking -- 30-minute checkpoint saves -- Trial-and-error recording - -#### Check (自己評価) -- `think_about_task_adherence()` → Pattern compliance -- `think_about_collected_information()` → Context sufficiency -- `think_about_whether_you_are_done()` → Completion verification - -#### Act (改善実行) -- Success → Extract pattern → docs/patterns/ -- Failure → Root cause analysis → docs/mistakes/ -- Update CLAUDE.md if global pattern - -**Implementation Details**: superclaude/Agents/pm-agent.md:137-175 - ---- - -### 3. Documentation Strategy (Trial-and-Error to Knowledge) - -**Status**: ✅ Documented (Implementation Pending) - -#### Temporary Documentation (`docs/temp/`) -- **Purpose**: Trial-and-error experimentation -- **Files**: - - `hypothesis-YYYY-MM-DD.md` → Initial plan - - `experiment-YYYY-MM-DD.md` → Implementation log - - `lessons-YYYY-MM-DD.md` → Reflections -- **Lifecycle**: 7 days → Move to formal or delete - -#### Formal Documentation (`docs/patterns/`) -- **Purpose**: Successful patterns ready for reuse -- **Trigger**: Verified implementation success -- **Content**: Clean approach + concrete examples + "Last Verified" date - -#### Mistake Documentation (`docs/mistakes/`) -- **Purpose**: Error records with prevention strategies -- **Structure**: - - What Happened (現象) - - Root Cause (根本原因) - - Why Missed (なぜ見逃したか) - - Fix Applied (修正内容) - - Prevention Checklist (防止策) - - Lesson Learned (教訓) - -**Implementation Details**: superclaude/Agents/pm-agent.md:177-235 - ---- - -### 4. Memory Operations Reference - -**Status**: ✅ Documented (Implementation Pending) - -#### Memory Types -- **Session Start**: `pm_context`, `last_session`, `next_actions` -- **During Work**: `plan`, `checkpoint`, `decision` -- **Self-Evaluation**: `think_about_*` operations -- **Session End**: `last_session`, `next_actions`, `pm_context` - -**Implementation Details**: superclaude/Agents/pm-agent.md:237-267 - ---- - -## 🚧 Pending Implementation - -### 1. Serena MCP Memory Operations - -**Required Actions**: -- [ ] Implement `list_memories()` integration -- [ ] Implement `read_memory(key)` integration -- [ ] Implement `write_memory(key, value)` integration -- [ ] Test memory persistence across sessions - -**Blockers**: Requires Serena MCP server configuration - ---- - -### 2. PDCA Think Operations - -**Required Actions**: -- [ ] Implement `think_about_task_adherence()` hook -- [ ] Implement `think_about_collected_information()` hook -- [ ] Implement `think_about_whether_you_are_done()` hook -- [ ] Integrate with TodoWrite completion tracking - -**Blockers**: Requires Serena MCP server configuration - ---- - -### 3. Documentation Directory Structure - -**Required Actions**: -- [ ] Create `docs/temp/` directory template -- [ ] Create `docs/patterns/` directory template -- [ ] Create `docs/mistakes/` directory template -- [ ] Implement automatic file lifecycle management (7-day cleanup) - -**Blockers**: None (can be implemented immediately) - ---- - -### 4. Auto-Activation at Session Start - -**Required Actions**: -- [ ] Implement PM Agent auto-activation hook -- [ ] Integrate with Claude Code session lifecycle -- [ ] Test context restoration across sessions -- [ ] Verify "前回/進捗/今回/課題" report generation - -**Blockers**: Requires understanding of Claude Code initialization hooks - ---- - -## 📊 Implementation Roadmap - -### Phase 1: Documentation Structure (Immediate) -**Timeline**: 1-2 days -**Complexity**: Low - -1. Create `docs/temp/`, `docs/patterns/`, `docs/mistakes/` directories -2. Add README.md to each directory explaining purpose -3. Create template files for hypothesis/experiment/lessons - -### Phase 2: Serena MCP Integration (High Priority) -**Timeline**: 1 week -**Complexity**: Medium - -1. Configure Serena MCP server -2. Implement memory operations (read/write/list) -3. Test memory persistence -4. Integrate with PM Agent workflow - -### Phase 3: PDCA Think Operations (High Priority) -**Timeline**: 1 week -**Complexity**: Medium - -1. Implement think_about_* hooks -2. Integrate with TodoWrite -3. Test self-evaluation flow -4. Document best practices - -### Phase 4: Auto-Activation (Critical) -**Timeline**: 2 weeks -**Complexity**: High - -1. Research Claude Code initialization hooks -2. Implement PM Agent auto-activation -3. Test session start protocol -4. Verify context restoration - -### Phase 5: Documentation Lifecycle (Medium Priority) -**Timeline**: 3-5 days -**Complexity**: Low - -1. Implement 7-day temporary file cleanup -2. Create docs/temp → docs/patterns migration script -3. Create docs/temp → docs/mistakes migration script -4. Automate "Last Verified" date updates - ---- - -## 🔍 Testing Strategy - -### Unit Tests -- [ ] Memory operations (read/write/list) -- [ ] Think operations (task_adherence/collected_information/done) -- [ ] File lifecycle management (7-day cleanup) - -### Integration Tests -- [ ] Session start → context restoration → user report -- [ ] PDCA cycle → temporary docs → formal docs -- [ ] Mistake detection → root cause analysis → prevention checklist - -### E2E Tests -- [ ] Full session lifecycle (start → work → end) -- [ ] Cross-session context preservation -- [ ] Knowledge accumulation over time - ---- - -## 📖 Documentation Updates Needed - -### SuperClaude Framework -- [x] `superclaude/Commands/pm.md` - Updated with session lifecycle -- [x] `superclaude/Agents/pm-agent.md` - Updated with PDCA and memory operations -- [ ] `docs/ARCHITECTURE.md` - Add PM Agent architecture section -- [ ] `docs/GETTING_STARTED.md` - Add PM Agent usage examples - -### Global CLAUDE.md (Future) -- [ ] Add PM Agent PDCA cycle to global rules -- [ ] Document session lifecycle best practices -- [ ] Add memory operations reference - ---- - -## 🐛 Known Issues - -### Issue 1: Serena MCP Not Configured -**Status**: Blocker -**Impact**: High (prevents memory operations) -**Resolution**: Configure Serena MCP server in project - -### Issue 2: Auto-Activation Hook Unknown -**Status**: Research Needed -**Impact**: High (prevents session start automation) -**Resolution**: Research Claude Code initialization hooks - -### Issue 3: Documentation Directory Structure Missing -**Status**: Can Implement Immediately -**Impact**: Medium (prevents PDCA documentation flow) -**Resolution**: Create directory structure (Phase 1) - ---- - -## 📈 Success Metrics - -### Quantitative -- **Context Restoration Rate**: 100% (sessions resume without re-explanation) -- **Documentation Coverage**: >80% (implementations documented) -- **Mistake Prevention**: <10% (recurring mistakes) -- **Session Continuity**: >90% (successful checkpoint restorations) - -### Qualitative -- Users never re-explain project context -- Knowledge accumulates systematically -- Mistakes documented with prevention checklists -- Documentation stays fresh (Last Verified dates) - ---- - -## 🎯 Next Steps - -1. **Immediate**: Create documentation directory structure (Phase 1) -2. **High Priority**: Configure Serena MCP server (Phase 2) -3. **High Priority**: Implement PDCA think operations (Phase 3) -4. **Critical**: Research and implement auto-activation (Phase 4) -5. **Medium Priority**: Implement documentation lifecycle automation (Phase 5) - ---- - -## 📚 References - -- **PM Agent Command**: `superclaude/Commands/pm.md` -- **PM Agent Persona**: `superclaude/Agents/pm-agent.md` -- **Salvaged Changes**: `tmp/salvaged-pm-agent/` -- **Original Patches**: `tmp/salvaged-pm-agent/*.patch` - ---- - -## 🔐 Commit Information - -**Branch**: master -**Salvaged From**: `/Users/kazuki/.claude` (mistaken development location) -**Integration Date**: 2025-10-14 -**Status**: Documentation complete, implementation pending - -**Git Operations**: -```bash -# Salvaged valuable changes to tmp/ -cp ~/.claude/Commands/pm.md tmp/salvaged-pm-agent/pm.md -cp ~/.claude/agents/pm-agent.md tmp/salvaged-pm-agent/pm-agent.md -git diff ~/.claude/CLAUDE.md > tmp/salvaged-pm-agent/CLAUDE.md.patch -git diff ~/.claude/RULES.md > tmp/salvaged-pm-agent/RULES.md.patch - -# Cleaned up .claude directory -cd ~/.claude && git reset --hard HEAD -cd ~/.claude && rm -rf .git - -# Applied changes to SuperClaude_Framework -cp tmp/salvaged-pm-agent/pm.md superclaude/Commands/pm.md -cp tmp/salvaged-pm-agent/pm-agent.md superclaude/Agents/pm-agent.md -``` - ---- - -**Last Verified**: 2025-10-14 -**Next Review**: 2025-10-21 (1 week) diff --git a/docs/templates/__init__.py b/docs/templates/__init__.py deleted file mode 100644 index e69de29..0000000