mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor(docs): normalize documentation naming to lowercase for PEP8 compliance (#434)
* refactor(docs): rename directories to lowercase for PEP8 compliance - Developer-Guide → developer-guide - Getting-Started → getting-started - Reference → reference - Templates → templates - User-Guide → user-guide - User-Guide-jp → user-guide-jp - User-Guide-kr → user-guide-kr - User-Guide-zh → user-guide-zh This change aligns with Python PEP8 package naming conventions. All 43 files affected. * refactor: rename root documentation files to lowercase - CHANGELOG.md → changelog.md - CODE_OF_CONDUCT.md → code_of_conduct.md - CONTRIBUTING.md → contributing.md - SECURITY.md → security.md Aligns with Python package naming conventions (PEP8). README files remain uppercase as per convention. * refactor: move documentation files to docs/ for cleaner root Moved OSS standard files to docs/: - CHANGELOG.md → docs/CHANGELOG.md - CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md - CONTRIBUTING.md → docs/CONTRIBUTING.md - SECURITY.md → docs/SECURITY.md Root now contains only essential files: ✓ README files (表紙: en, ja, kr, zh) ✓ LICENSE (法的要件) ✓ Build configs (pyproject.toml, setup.py, MANIFEST.in) ✓ VERSION Rationale: Cleaner root structure following modern Python project conventions. All detailed documentation consolidated in docs/ directory. * refactor: update documentation links after restructure Auto-updated internal documentation links to reflect new structure: - docs/ subdirectories now lowercase (PEP8) - Root files moved to docs/ - All cross-references updated This commit includes linter-generated link updates. * chore(docs): keep OSS-standard uppercase root files (CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY) * chore(docs): remove duplicated PR docs from repo root (moved under docs) * docs: rename pm-agent-implementation-status.md -> PM_AGENT.md for clarity * docs: update links to PM_AGENT.md after rename --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local>
This commit is contained in:
kazuki nakai
@@ -1,191 +0,0 @@
|
||||
# Pull Request: Redesign PM Agent as Self-Improvement Meta-Layer
|
||||
|
||||
## Summary
|
||||
|
||||
Redesigned PM Agent from task orchestration system to self-improvement workflow executor (meta-layer agent). PM Agent now complements existing auto-activation by systematically documenting implementations, analyzing mistakes, and maintaining knowledge base quality.
|
||||
|
||||
## Motivation
|
||||
|
||||
**Problem**: Initial PM Agent design competed with existing auto-activation system for task routing, creating confusion about responsibilities and adding unnecessary complexity.
|
||||
|
||||
**Solution**: Redefined PM Agent as a meta-layer that operates AFTER specialist agents complete tasks, focusing on:
|
||||
- Post-implementation documentation
|
||||
- Immediate mistake analysis and prevention
|
||||
- Monthly documentation maintenance
|
||||
- Pattern extraction and knowledge synthesis
|
||||
|
||||
**Value Proposition**: Transforms SuperClaude into a continuously learning system that accumulates knowledge, prevents recurring mistakes, and maintains fresh documentation without manual intervention.
|
||||
|
||||
## Changes
|
||||
|
||||
### 1. PM Agent Agent File (`SuperClaude/Agents/pm-agent.md`)
|
||||
**Status**: Complete rewrite
|
||||
|
||||
**Before**:
|
||||
- Category: orchestration
|
||||
- Triggers: All user interactions (default mode)
|
||||
- Role: Task router and sub-agent coordinator
|
||||
- Competed with existing auto-activation
|
||||
|
||||
**After**:
|
||||
- Category: meta
|
||||
- Triggers: Post-implementation, mistake detection, monthly maintenance
|
||||
- Role: Self-improvement workflow executor
|
||||
- Complements existing auto-activation
|
||||
|
||||
**Key Additions**:
|
||||
- Behavioral Mindset: "Think like a continuous learning system"
|
||||
- Focus Areas: Implementation Documentation, Mistake Analysis, Pattern Recognition, Knowledge Maintenance, Self-Improvement Loop
|
||||
- Self-Improvement Workflow Integration: BEFORE/DURING/AFTER/MISTAKE RECOVERY/MAINTENANCE phases
|
||||
- Quality Standards: Latest, Minimal, Clear, Practical documentation criteria
|
||||
- Performance Metrics: Documentation coverage, mistake prevention effectiveness, knowledge maintenance health
|
||||
|
||||
**Workflow Examples**:
|
||||
1. Post-Implementation Documentation: Backend architect implements JWT → PM Agent documents pattern
|
||||
2. Immediate Mistake Analysis: Kong Gateway bypass detected → PM Agent stops, analyzes, documents prevention
|
||||
3. Monthly Documentation Maintenance: PM Agent prunes outdated docs, merges duplicates, updates versions
|
||||
|
||||
### 2. Framework Rules (`SuperClaude/Core/RULES.md`)
|
||||
**Status**: Agent Orchestration section updated (lines 17-44)
|
||||
|
||||
**Changes**:
|
||||
- Split orchestration into two clear layers:
|
||||
- **Task Execution Layer**: Existing auto-activation (unchanged)
|
||||
- **Self-Improvement Layer**: PM Agent meta-layer (new)
|
||||
- Added orchestration flow diagram showing task execution → documentation cycle
|
||||
- Clarified examples: ✅ Right patterns and ❌ Wrong anti-patterns
|
||||
- Emphasized PM Agent activates AFTER task completion, not before/during
|
||||
|
||||
**Purpose**: Eliminate confusion between task routing (auto-activation) and learning (PM Agent)
|
||||
|
||||
### 3. README.md
|
||||
**Status**: PM Agent description updated (line 208)
|
||||
|
||||
**Before**: "PM Agent orchestrates all interactions seamlessly"
|
||||
|
||||
**After**: "PM Agent ensures continuous learning through systematic documentation"
|
||||
|
||||
**Impact**: Accurate representation of PM Agent's meta-layer role in main documentation
|
||||
|
||||
### 4. Agents Guide (`Docs/User-Guide/agents.md`)
|
||||
**Status**: PM Agent section completely rewritten (lines 140-208)
|
||||
|
||||
**Changes**:
|
||||
- Section title: "Orchestration Agent" → "Meta-Layer Agent"
|
||||
- Expertise: Project orchestration → Self-improvement workflow executor
|
||||
- Auto-Activation: Default mode for all interactions → Post-implementation, mistake detection, monthly maintenance
|
||||
- Capabilities: Workflow orchestration → Implementation documentation, mistake analysis, pattern recognition, knowledge maintenance
|
||||
- Examples: Vague feature requests → Post-implementation documentation, immediate mistake analysis, monthly maintenance
|
||||
- Integration: Orchestrates entire ecosystem → Documents specialist agents' work
|
||||
|
||||
**Purpose**: User-facing documentation accurately reflects PM Agent's actual behavior
|
||||
|
||||
## Two-Layer Orchestration System
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Task Execution Layer (Existing Auto-Activation) │
|
||||
│ ─────────────────────────────────────────────────────── │
|
||||
│ User Request → Context Analysis → Specialist Selection │
|
||||
│ backend-architect | frontend-architect | security, etc. │
|
||||
│ │
|
||||
│ ↓ Implementation Complete ↓ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Self-Improvement Layer (PM Agent Meta-Layer) │
|
||||
│ ─────────────────────────────────────────────────────── │
|
||||
│ PM Agent Auto-Triggers → Documentation → Learning │
|
||||
│ Pattern Recording | Mistake Analysis | Maintenance │
|
||||
│ │
|
||||
│ ↓ Knowledge Base Updated ↓ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Flow**:
|
||||
1. User: "Add JWT authentication"
|
||||
2. Task Execution Layer: Auto-activation → security-engineer + backend-architect → Implementation
|
||||
3. Self-Improvement Layer: PM Agent auto-triggers → Documents JWT pattern in docs/authentication.md → Records security decisions → Updates CLAUDE.md
|
||||
|
||||
## Testing
|
||||
|
||||
**Validation Method**: Verified integration with existing self-improvement workflow
|
||||
|
||||
**Test Case**: agiletec project
|
||||
- ✅ Reviewed `/Users/kazuki/github/agiletec/docs/self-improvement-workflow.md`
|
||||
- ✅ Confirmed PM Agent design aligns with BEFORE/DURING/AFTER/MISTAKE RECOVERY phases
|
||||
- ✅ Verified PM Agent complements (not competes with) existing workflow
|
||||
- ✅ Confirmed agiletec workflow defines WHAT, PM Agent defines WHO executes it
|
||||
|
||||
**Integration Check**:
|
||||
- ✅ PM Agent operates as meta-layer above specialist agents
|
||||
- ✅ Existing auto-activation handles task routing (unchanged)
|
||||
- ✅ PM Agent handles post-implementation documentation (new capability)
|
||||
- ✅ No conflicts with existing agent activation patterns
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
**None**. This is a design clarification and documentation update:
|
||||
|
||||
- ✅ Existing auto-activation continues to work identically
|
||||
- ✅ Specialist agents (backend-architect, frontend-architect, etc.) unchanged
|
||||
- ✅ User workflows remain the same
|
||||
- ✅ Manual `@agent-[name]` override still works
|
||||
- ✅ Commands (`/sc:implement`, `/sc:build`, etc.) unchanged
|
||||
|
||||
**New Capability**: PM Agent now automatically documents implementations and maintains knowledge base without user intervention.
|
||||
|
||||
## Impact on User Experience
|
||||
|
||||
**Before**:
|
||||
- User requests task → Specialist agents implement → User manually documents (if at all)
|
||||
- Mistakes repeated due to lack of systematic documentation
|
||||
- Documentation becomes outdated over time
|
||||
|
||||
**After**:
|
||||
- User requests task → Specialist agents implement → PM Agent auto-documents patterns
|
||||
- Mistakes automatically analyzed with prevention checklists created
|
||||
- Documentation systematically maintained through monthly reviews
|
||||
|
||||
**Result**: Zero additional user effort, continuous improvement built into framework
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [x] PM Agent agent file completely rewritten with meta-layer design
|
||||
- [x] RULES.md Agent Orchestration section updated with two-layer system
|
||||
- [x] README.md PM Agent description updated
|
||||
- [x] agents.md PM Agent section completely rewritten
|
||||
- [x] Integration validated with agiletec project self-improvement workflow
|
||||
- [x] All files properly formatted and consistent
|
||||
- [x] No breaking changes to existing functionality
|
||||
- [x] Documentation accurately reflects implementation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
**Potential Additions** (not included in this PR):
|
||||
1. `/sc:pm status` - Show documentation coverage and maintenance health
|
||||
2. `/sc:pm review` - Manual trigger for documentation review
|
||||
3. Performance metrics dashboard - Track mistake prevention effectiveness
|
||||
4. Integration with CI/CD - Auto-generate documentation on PR merge
|
||||
|
||||
**These are OPTIONAL** and should be separate PRs based on user feedback.
|
||||
|
||||
## Related Issues
|
||||
|
||||
Addresses internal design discussion about PM Agent role clarity and integration with existing auto-activation system.
|
||||
|
||||
## Reviewer Notes
|
||||
|
||||
**Key Points to Review**:
|
||||
1. **pm-agent.md**: Complete rewrite - verify behavioral mindset, focus areas, and workflow examples make sense
|
||||
2. **RULES.md**: Two-layer orchestration system - verify clear distinction between task execution and self-improvement
|
||||
3. **agents.md**: User-facing documentation - verify accurate representation of PM Agent behavior
|
||||
4. **Integration**: Verify PM Agent complements (not competes with) existing auto-activation
|
||||
|
||||
**Expected Outcome**: PM Agent transforms SuperClaude into a continuously learning system through systematic documentation, mistake analysis, and knowledge maintenance.
|
||||
|
||||
---
|
||||
|
||||
**PR Type**: Enhancement (Design Clarification)
|
||||
**Complexity**: Medium (Documentation-focused, no code changes)
|
||||
**Risk**: Low (No breaking changes, purely additive capability)
|
||||
Reference in New Issue
Block a user