mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
chore: remove redundant docs after PLANNING.md migration
Cleanup after Self-Improvement Loop implementation: **Deleted (21 files, ~210KB)**: - docs/Development/ - All content migrated to PLANNING.md & TASK.md * ARCHITECTURE.md (15KB) → PLANNING.md * TASKS.md (3.7KB) → TASK.md * ROADMAP.md (11KB) → TASK.md * PROJECT_STATUS.md (4.2KB) → outdated * 13 PM Agent research files → archived in KNOWLEDGE.md - docs/PM_AGENT.md - Old implementation status - docs/pm-agent-implementation-status.md - Duplicate - docs/templates/ - Empty directory **Retained (valuable documentation)**: - docs/memory/ - Active session metrics & context - docs/patterns/ - Reusable patterns - docs/research/ - Research reports - docs/user-guide*/ - User documentation (4 languages) - docs/reference/ - Reference materials - docs/getting-started/ - Quick start guides - docs/agents/ - Agent-specific guides - docs/testing/ - Test procedures **Result**: - Eliminated redundancy after Root Documents consolidation - Preserved all valuable content in PLANNING.md, TASK.md, KNOWLEDGE.md - Maintained user-facing documentation structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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. ユーザーガイド更新
|
||||
@@ -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.
|
||||
@@ -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/ # サービスロジック
|
||||
```
|
||||
|
||||
### エラーハンドリング
|
||||
- 包括的なエラーハンドリングとログ記録
|
||||
- ユーザーフレンドリーなエラーメッセージ
|
||||
- アクション可能なエラーガイダンス
|
||||
@@ -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` の修正を開始します。
|
||||
@@ -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.
|
||||
@@ -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. ✅ 学習記録
|
||||
|
||||
このドキュメント自体が**インストールフローの完全理解記録**として機能する。
|
||||
次回のセッションで読めば、同じ説明を繰り返さなくて済む。
|
||||
@@ -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の憲法**となる。
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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:
|
||||
<invoke Read file1>
|
||||
<invoke Read file2>
|
||||
<invoke Read file3>
|
||||
[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.
|
||||
@@ -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
|
||||
@@ -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管理下で開発
|
||||
|
||||
これで**何百回も同じ説明をしなくて済む**ようになる。
|
||||
@@ -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` を読んで現在の仕様を確認する
|
||||
332
docs/PM_AGENT.md
332
docs/PM_AGENT.md
@@ -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)
|
||||
@@ -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)
|
||||
0
docs/templates/__init__.py
vendored
0
docs/templates/__init__.py
vendored
Reference in New Issue
Block a user