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