mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
docs: add project index and PR documentation
Add comprehensive project documentation: - PROJECT_INDEX.json: Machine-readable project structure - PROJECT_INDEX.md: Human-readable project overview - PR_DOCUMENTATION.md: Pull request preparation documentation - PARALLEL_INDEXING_PLAN.md: Parallel indexing implementation plan Provides structured project knowledge base and contribution guidelines. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
320
PR_DOCUMENTATION.md
Normal file
320
PR_DOCUMENTATION.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# PR: PM Mode as Default - Phase 1 Implementation
|
||||
|
||||
**Status**: ✅ Ready for Review
|
||||
**Test Coverage**: 26 tests, all passing
|
||||
**Breaking Changes**: None
|
||||
|
||||
---
|
||||
|
||||
## 📋 Summary
|
||||
|
||||
This PR implements **Phase 1** of the PM-as-Default architecture: **PM Mode Initialization** and **Validation Infrastructure**.
|
||||
|
||||
### What This Enables
|
||||
|
||||
- ✅ **Automatic Context Contract generation** (project-specific rules)
|
||||
- ✅ **Reflexion Memory system** (learning from mistakes)
|
||||
- ✅ **5 Core Validators** (security, dependencies, runtime, tests, contracts)
|
||||
- ✅ **Foundation for 4-phase workflow** (PLANNING/TASKLIST/DO/ACTION)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Problem Solved
|
||||
|
||||
### Before
|
||||
- PM Mode was **optional** and rarely used
|
||||
- No enforcement of project-specific rules (Kong, Infisical, .env禁止)
|
||||
- Same mistakes repeated (no learning system)
|
||||
- No pre-execution validation (implementations broke rules)
|
||||
|
||||
### After
|
||||
- PM Mode **initializes automatically** at session start
|
||||
- Context Contract **enforces rules** before execution
|
||||
- Reflexion Memory **prevents recurring mistakes**
|
||||
- Validators **block problematic code** before execution
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### 1. PM Mode Init Hook
|
||||
|
||||
**Location**: `superclaude/core/pm_init/`
|
||||
|
||||
```python
|
||||
from superclaude.core.pm_init import initialize_pm_mode
|
||||
|
||||
# Runs automatically at session start
|
||||
init_data = initialize_pm_mode()
|
||||
# Returns: Context Contract + Reflexion Memory + Project Structure
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Git repository detection
|
||||
- Lightweight structure scan (paths only, no content reading)
|
||||
- Context Contract auto-generation
|
||||
- Reflexion Memory loading
|
||||
|
||||
---
|
||||
|
||||
### 2. Context Contract
|
||||
|
||||
**Location**: `docs/memory/context-contract.yaml` (auto-generated)
|
||||
|
||||
**Purpose**: Enforce project-specific rules
|
||||
|
||||
```yaml
|
||||
version: 1.0.0
|
||||
principles:
|
||||
use_infisical_only: true
|
||||
no_env_files: true
|
||||
outbound_through: kong
|
||||
runtime:
|
||||
node:
|
||||
manager: pnpm
|
||||
source: lockfile-defined
|
||||
validators:
|
||||
- deps_exist_on_registry
|
||||
- tests_must_run
|
||||
- no_env_file_creation
|
||||
- outbound_through_proxy
|
||||
```
|
||||
|
||||
**Detection Logic**:
|
||||
- Infisical → `no_env_files: true`
|
||||
- Kong → `outbound_through: kong`
|
||||
- Traefik → `outbound_through: traefik`
|
||||
- pnpm-lock.yaml → `manager: pnpm`
|
||||
|
||||
---
|
||||
|
||||
### 3. Reflexion Memory
|
||||
|
||||
**Location**: `docs/memory/reflexion.jsonl`
|
||||
|
||||
**Purpose**: Learn from mistakes, prevent recurrence
|
||||
|
||||
```jsonl
|
||||
{"ts": "2025-10-19T...", "task": "auth", "mistake": "forgot kong routing", "rule": "all services route through kong", "fix": "added kong route", "tests": ["test_kong.py"], "status": "adopted"}
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Add entries: `memory.add_entry(ReflexionEntry(...))`
|
||||
- Search similar: `memory.search_similar_mistakes("kong routing")`
|
||||
- Get rules: `memory.get_rules()`
|
||||
|
||||
---
|
||||
|
||||
### 4. Validators
|
||||
|
||||
**Location**: `superclaude/validators/`
|
||||
|
||||
#### ContextContractValidator
|
||||
- Enforces project-specific rules
|
||||
- Checks .env file creation (禁止)
|
||||
- Detects hardcoded secrets
|
||||
- Validates Kong/Traefik routing
|
||||
|
||||
#### DependencySanityValidator
|
||||
- Validates package.json/pyproject.toml
|
||||
- Checks package name format
|
||||
- Detects version inconsistencies
|
||||
|
||||
#### RuntimePolicyValidator
|
||||
- Validates Node.js/Python versions
|
||||
- Checks engine specifications
|
||||
- Ensures lockfile consistency
|
||||
|
||||
#### TestRunnerValidator
|
||||
- Detects test files in changes
|
||||
- Runs tests automatically
|
||||
- Fails if tests don't pass
|
||||
|
||||
#### SecurityRoughcheckValidator
|
||||
- Detects hardcoded secrets (Stripe, Supabase, OpenAI, Infisical)
|
||||
- Blocks .env file creation
|
||||
- Warns on unsafe patterns (eval, exec, shell=True)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Test Coverage
|
||||
|
||||
**Total**: 26 tests, all passing
|
||||
|
||||
### PM Init Tests (11 tests)
|
||||
- ✅ Git repository detection
|
||||
- ✅ Structure scanning
|
||||
- ✅ Context Contract generation (Infisical, Kong, Traefik)
|
||||
- ✅ Runtime detection (Node, Python, pnpm, uv)
|
||||
- ✅ Reflexion Memory (load, add, search)
|
||||
|
||||
### Validator Tests (15 tests)
|
||||
- ✅ Context Contract validation
|
||||
- ✅ Dependency sanity checks
|
||||
- ✅ Runtime policy validation
|
||||
- ✅ Security roughcheck (secrets, .env, unsafe patterns)
|
||||
- ✅ Validator chain (all pass, early stop)
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
uv run pytest tests/core/pm_init/ tests/validators/ -v
|
||||
|
||||
# Results
|
||||
============================== 26 passed in 0.08s ==============================
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Automatic Initialization
|
||||
|
||||
```python
|
||||
# Session start (automatic)
|
||||
from superclaude.core.pm_init import initialize_pm_mode
|
||||
|
||||
init_data = initialize_pm_mode()
|
||||
|
||||
# Returns
|
||||
{
|
||||
"status": "initialized",
|
||||
"git_root": "/path/to/repo",
|
||||
"structure": {...}, # Docker, Infra, Package managers
|
||||
"context_contract": {...}, # Project-specific rules
|
||||
"reflexion_memory": {
|
||||
"total_entries": 5,
|
||||
"rules": ["all services route through kong", ...],
|
||||
"recent_mistakes": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manual Validation
|
||||
|
||||
```python
|
||||
from superclaude.validators import (
|
||||
ContextContractValidator,
|
||||
SecurityRoughcheckValidator,
|
||||
ValidationStatus
|
||||
)
|
||||
|
||||
# Create validator
|
||||
validator = SecurityRoughcheckValidator()
|
||||
|
||||
# Validate changes
|
||||
result = validator.validate({
|
||||
"changes": {
|
||||
".env": "SECRET_KEY=abc123"
|
||||
}
|
||||
})
|
||||
|
||||
# Check result
|
||||
if result.failed:
|
||||
print(result.message) # "CRITICAL security issues detected"
|
||||
print(result.details) # {"critical": ["❌ .env file detected"]}
|
||||
print(result.suggestions) # ["Remove hardcoded secrets", ...]
|
||||
```
|
||||
|
||||
### Reflexion Memory
|
||||
|
||||
```python
|
||||
from superclaude.core.pm_init import ReflexionMemory, ReflexionEntry
|
||||
|
||||
memory = ReflexionMemory(git_root)
|
||||
|
||||
# Add entry
|
||||
entry = ReflexionEntry(
|
||||
task="auth implementation",
|
||||
mistake="forgot kong routing",
|
||||
evidence="direct connection detected",
|
||||
rule="all services must route through kong",
|
||||
fix="added kong service in docker-compose.yml",
|
||||
tests=["test_kong_routing.py"]
|
||||
)
|
||||
memory.add_entry(entry)
|
||||
|
||||
# Search similar mistakes
|
||||
similar = memory.search_similar_mistakes("kong routing missing")
|
||||
# Returns: List[ReflexionEntry] with similar past mistakes
|
||||
|
||||
# Get all rules
|
||||
rules = memory.get_rules()
|
||||
# Returns: ["all services must route through kong", ...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Files Added
|
||||
|
||||
```
|
||||
superclaude/
|
||||
├── core/pm_init/
|
||||
│ ├── __init__.py # Exports
|
||||
│ ├── init_hook.py # Main initialization
|
||||
│ ├── context_contract.py # Contract generation
|
||||
│ └── reflexion_memory.py # Memory management
|
||||
├── validators/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py # Base validator classes
|
||||
│ ├── context_contract.py
|
||||
│ ├── dep_sanity.py
|
||||
│ ├── runtime_policy.py
|
||||
│ ├── test_runner.py
|
||||
│ └── security_roughcheck.py
|
||||
|
||||
tests/
|
||||
├── core/pm_init/
|
||||
│ └── test_init_hook.py # 11 tests
|
||||
└── validators/
|
||||
└── test_validators.py # 15 tests
|
||||
|
||||
docs/memory/ (auto-generated)
|
||||
├── context-contract.yaml
|
||||
└── reflexion.jsonl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 What's Next (Phase 2)
|
||||
|
||||
**Not included in this PR** (will be in Phase 2):
|
||||
|
||||
1. **PLANNING Phase** (`commands/pm/plan.py`)
|
||||
- Generate 3-5 plans → Self-critique → Prune bad plans
|
||||
|
||||
2. **TASKLIST Phase** (`commands/pm/tasklist.py`)
|
||||
- Break into parallel/sequential tasks
|
||||
|
||||
3. **DO Phase** (`commands/pm/do.py`)
|
||||
- Execute with validator gates
|
||||
|
||||
4. **ACTION Phase** (`commands/pm/reflect.py`)
|
||||
- Post-implementation reflection and learning
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist
|
||||
|
||||
- [x] PM Init Hook implemented
|
||||
- [x] Context Contract auto-generation
|
||||
- [x] Reflexion Memory system
|
||||
- [x] 5 Core Validators implemented
|
||||
- [x] 26 tests written and passing
|
||||
- [x] Documentation complete
|
||||
- [ ] Code review
|
||||
- [ ] Merge to integration branch
|
||||
|
||||
---
|
||||
|
||||
## 📚 References
|
||||
|
||||
1. **Reflexion: Language Agents with Verbal Reinforcement Learning** (2023)
|
||||
- Self-reflection for 94% error detection rate
|
||||
|
||||
2. **Context7 MCP** - Pattern for project-specific configuration
|
||||
|
||||
3. **SuperClaude Framework** - Behavioral Rules and Principles
|
||||
|
||||
---
|
||||
|
||||
**Review Ready**: This PR establishes the foundation for PM-as-Default. All tests pass, no breaking changes.
|
||||
Reference in New Issue
Block a user