solarwindpy 0.0.1.dev0__py3-none-any.whl → 0.1.0__py3-none-any.whl

plans/systemprompt-optimization/1-Deploy-SystemPrompt.md

@@ -0,0 +1,114 @@
+# Phase 1: Deploy Enhanced systemPrompt
+
+## Objectives
+- Update systemPrompt in `.claude/settings.json`
+- Verify hook compatibility and agent references
+- Test functionality with sample session
+
+## Tasks
+
+### 1.1 Update settings.json systemPrompt
+**Location**: `.claude/settings.json` line 135
+
+**Current systemPrompt** (175 tokens - OUTDATED):
+```
+You are working on SolarWindPy, a scientific Python package for solar wind plasma physics analysis. CRITICAL WORKFLOW: Before ANY development work: 1) List all unmerged branches with `git branch -r --no-merged master`; 2) Ask user 'Which branch should I use? Please specify branch name, or say "search" if you want me to help find an appropriate branch, or say "new" to create a new branch'; 3) Wait for explicit user instruction - NEVER auto-select a branch; 4) If user says "search", help identify relevant branches by content/purpose; 5) If user says "new", create branch using pattern 'claude/YYYY-MM-DD-HH-MM-SS-module-feature-description'. Never work directly on master. Always follow development guidelines in .claude/CLAUDE.md. Run tests with `pytest -q`, format code with `black .`, and lint with `flake8`. All tests must pass before committing. Use NumPy-style docstrings and follow Conventional Commits format. Include 'Generated with Claude Code' attribution in commits.
+```
+
+**New systemPrompt** (210 tokens - COMPREHENSIVE):
+```
+SolarWindPy: Solar wind plasma physics package. Architecture: pandas MultiIndex (M:measurement/C:component/S:species), SI units, mw²=2kT.
+
+Agents: UnifiedPlanCoordinator (all planning/implementation), PhysicsValidator (units/constraints), DataFrameArchitect (MultiIndex), TestEngineer (coverage), PlottingEngineer, FitFunctionSpecialist, NumericalStabilityGuard.
+
+Hooks automate: SessionStart (branch validation/context), PreToolUse (physics/git checks), PostToolUse (test execution), PreCompact (state snapshots), Stop (coverage report).
+
+Workflow: plan/* branches for planning, feature/* for code. PRs from plan/* to master trigger CI/security/docs checks. No direct master commits. Follow CLAUDE.md. Session context loads automatically.
+```
+
+### 1.2 Implementation Steps
+
+#### Step 1: Backup Current Configuration
+```bash
+# Create backup of current settings
+cp .claude/settings.json .claude/settings.json.backup
+```
+
+#### Step 2: Update systemPrompt
+Replace the content of line 135 in `.claude/settings.json`:
+
+```json
+"systemPrompt": "SolarWindPy: Solar wind plasma physics package. Architecture: pandas MultiIndex (M:measurement/C:component/S:species), SI units, mw²=2kT.\n\nAgents: UnifiedPlanCoordinator (all planning/implementation), PhysicsValidator (units/constraints), DataFrameArchitect (MultiIndex), TestEngineer (coverage), PlottingEngineer, FitFunctionSpecialist, NumericalStabilityGuard.\n\nHooks automate: SessionStart (branch validation/context), PreToolUse (physics/git checks), PostToolUse (test execution), PreCompact (state snapshots), Stop (coverage report).\n\nWorkflow: plan/* branches for planning, feature/* for code. PRs from plan/* to master trigger CI/security/docs checks. No direct master commits. Follow CLAUDE.md. Session context loads automatically."
+```
+
+### 1.3 Compatibility Verification
+
+#### Hook System Check
+- [ ] **SessionStart hook** (`validate-session-state.sh`) still functions correctly
+- [ ] **git-workflow-validator** does not conflict with new context
+- [ ] **Agent references** are accurate and match available agents
+- [ ] **Branch pattern validation** aligns with git hooks
+
+#### Validation Commands
+```bash
+# Test SessionStart hook
+.claude/hooks/validate-session-state.sh
+
+# Test git workflow validator
+.claude/hooks/git-workflow-validator.sh --check-branch
+
+# Verify agent files exist
+ls -la .claude/agents*
+```
+
+### 1.4 Functional Testing
+
+#### Test Checklist
+- [ ] Start new Claude Code session
+- [ ] Verify systemPrompt loads in conversation context
+- [ ] Test agent awareness in conversation
+  - Ask: "Which agent should handle MultiIndex operations?"
+  - Expected: "DataFrameArchitect"
+- [ ] Confirm workflow understanding
+  - Ask: "How do I close out a plan?"
+  - Expected: "Create PR from plan/* to master"
+- [ ] Verify hook awareness
+  - Ask: "What happens when I edit a physics file?"
+  - Expected: "PreToolUse physics validation, PostToolUse test execution"
+
+### 1.5 Rollback Procedure (if needed)
+```bash
+# Restore original settings if issues arise
+cp .claude/settings.json.backup .claude/settings.json
+```
+
+## Key Changes Summary
+
+### Eliminated (Redundant with Hooks)
+- Interactive branch selection workflow
+- Manual branch listing commands  
+- Wrong branch pattern (`claude/YYYY-MM-DD-HH-MM-SS-*`)
+- Duplicate workflow enforcement
+
+### Added (Unique Value)
+- Complete agent ecosystem awareness
+- MultiIndex DataFrame architecture context
+- Physics constraints (SI units, mw²=2kT)
+- Hook automation transparency
+- PR-based plan closeout workflow
+- CI/security/docs check awareness
+
+## Acceptance Criteria
+- [ ] systemPrompt updated in settings.json
+- [ ] No hook conflicts observed during testing
+- [ ] Agent selection improved in conversations
+- [ ] Workflow understanding demonstrates PR awareness
+- [ ] Session context loads automatically as expected
+- [ ] Backup created for rollback if needed
+
+## Expected Benefits
+- **Immediate Context**: Users understand system from first interaction
+- **Optimal Agent Usage**: Automatic routing to specialized agents
+- **Workflow Clarity**: Clear understanding of plan/* → PR → master flow
+- **Reduced Confusion**: No conflicting branch pattern information
+- **Token Efficiency**: 35-token increase but eliminates 200-500 tokens in clarifications

plans/systemprompt-optimization/2-Documentation-Alignment.md

@@ -0,0 +1,198 @@
+# Phase 2: Documentation Alignment
+
+## Objectives
+- Update CLAUDE.md with comprehensive PR workflow details
+- Enhance hook system descriptions to match systemPrompt
+- Add agent selection guidelines for immediate productivity
+
+## Tasks
+
+### 2.1 Update CLAUDE.md PR Workflow Section
+
+**Location**: After existing "Git Workflow (Automated via Hooks)" section in CLAUDE.md
+
+**Add New Section**:
+```markdown
+### PR Workflow & Plan Closeout
+Plans are closed via Pull Requests with comprehensive automated checks:
+
+#### Workflow Steps
+1. **Complete Implementation**: Finish work on `feature/*` branch
+2. **Merge to Plan**: `git checkout plan/<name>` → `git merge feature/<name>`
+3. **Create PR**: `gh pr create` from `plan/*` → `master`
+4. **Automated Validation**: GitHub Actions automatically execute:
+   - **CI Tests**: Python 3.8-3.12 across Ubuntu/macOS/Windows (15 combinations)
+   - **Security Scans**: Bandit, Safety, pip-audit for vulnerability detection
+   - **Documentation Build**: Sphinx build verification and link checking
+   - **Coverage Analysis**: Test coverage reporting and enforcement
+5. **Branch Protection**: All checks must pass before merge allowed
+6. **Plan Completion**: Merge PR to close plan and deploy to master
+
+#### Claude Integration
+- Claude handles PR creation with full awareness of automated checks
+- systemPrompt includes CI/security/docs check context
+- Hook system enforces PR source branch validation (plan/* only)
+- Automated metrics collection for plan completion tracking
+```
+
+### 2.2 Enhance Hook System Documentation
+
+**Location**: Replace existing "Automated Validation" section in CLAUDE.md
+
+**Enhanced Hook Descriptions**:
+```markdown
+### Hook System Details
+
+Hook system provides automatic validation at key interaction points:
+
+#### SessionStart Hook (`validate-session-state.sh`)
+- **Purpose**: Validates session context and branch state
+- **Actions**: 
+  - Checks current branch and suggests plan branches if on master
+  - Loads compacted state for active plans
+  - Displays recent commits and uncommitted changes
+  - Provides workflow guidance
+- **User Impact**: Immediate context orientation, no manual setup
+
+#### PreToolUse Hooks
+- **Edit/Write/MultiEdit Operations**:
+  - **Physics Validation** (`physics-validation.py`): Units consistency, constraint checking
+  - **Target**: All Python files in solarwindpy/ directory
+  - **Timeout**: 45 seconds for complex validation
+
+- **Bash Git Operations**:
+  - **Workflow Validation** (`git-workflow-validator.sh`): Branch protection, PR validation
+  - **Target**: All git and gh commands
+  - **Blocking**: Prevents invalid operations (commits to master, wrong PR sources)
+
+#### PostToolUse Hooks
+- **Edit/Write/MultiEdit**:
+  - **Smart Test Runner** (`test-runner.sh --changed`): Runs tests for modified files
+  - **Coverage**: Maintains ≥95% coverage requirement
+  - **Timeout**: 120 seconds for comprehensive testing
+
+- **Bash Operations**:
+  - **Pre-commit Tests** (`pre-commit-tests.sh`): Final validation before commits
+  - **Quality Gates**: Ensures all tests pass before git operations
+
+#### PreCompact Hook (`create-compaction.py`)
+- **Purpose**: Session state preservation at token boundaries
+- **Actions**: Creates compressed session snapshots with git integration
+- **Artifacts**: Tagged compaction states for session continuity
+
+#### Stop Hook (`coverage-monitor.py`)
+- **Purpose**: Session completion metrics and coverage reporting
+- **Actions**: Final coverage analysis, session metrics collection
+- **Output**: Detailed reports for continuous improvement
+```
+
+### 2.3 Add Agent Selection Guidelines
+
+**Location**: New section in CLAUDE.md after "Common Aliases"
+
+**Agent Selection Quick Reference**:
+```markdown
+### Agent Selection Quick Reference
+
+Claude Code uses specialized agents for optimal task execution:
+
+#### Primary Coordination
+- **UnifiedPlanCoordinator**: Use for ALL planning and implementation coordination
+  - Multi-phase project planning
+  - Cross-module integration tasks  
+  - Plan status tracking and completion
+
+#### Domain Specialists
+- **PhysicsValidator**: Physics calculations and scientific validation
+  - Unit consistency checking (SI units, thermal speed mw²=2kT)
+  - Scientific constraint validation
+  - Physics equation verification
+
+- **DataFrameArchitect**: pandas MultiIndex optimization and patterns
+  - MultiIndex DataFrame operations (M:measurement/C:component/S:species)
+  - Data structure efficiency
+  - Memory optimization patterns
+
+- **TestEngineer**: Comprehensive testing strategy and coverage
+  - Test design and implementation
+  - Coverage analysis and improvement
+  - Physics-specific test validation
+
+#### Specialized Functions
+- **PlottingEngineer**: Visualization and matplotlib operations
+  - Publication-quality figure creation
+  - Scientific plotting standards
+  - Visual validation of results
+
+- **FitFunctionSpecialist**: Curve fitting and statistical analysis
+  - Mathematical function fitting
+  - Statistical validation
+  - Optimization algorithms
+
+- **NumericalStabilityGuard**: Numerical validation and edge case handling
+  - Floating-point precision issues
+  - Numerical algorithm stability
+  - Edge case validation
+
+#### Usage Examples
+```python
+# For planning any complex task
+"Use UnifiedPlanCoordinator to create implementation plan for dark mode feature"
+
+# For domain-specific work  
+"Use PhysicsValidator to verify thermal speed calculations in Ion class"
+"Use DataFrameArchitect to optimize MultiIndex operations in Plasma.moments()"
+"Use TestEngineer to design test strategy for fitfunctions module"
+```
+```
+
+### 2.4 Update Development Workflow Section
+
+**Location**: Enhance existing "Git Workflow (Automated via Hooks)" section
+
+**Add PR Context**:
+```markdown
+#### PR Creation and Management
+- **Source Validation**: PRs MUST be created from `plan/*` branches (enforced by hooks)
+- **Automated Checks**: CI, security, and documentation checks run automatically
+- **Branch Protection**: All checks required to pass before merge
+- **Plan Metrics**: Completion metrics automatically recorded
+- **Cleanup**: Plan and feature branches preserved for audit trail
+```
+
+## Implementation Steps
+
+### Step 1: Backup Current CLAUDE.md
+```bash
+cp CLAUDE.md CLAUDE.md.backup
+```
+
+### Step 2: Apply Documentation Updates
+Use the content above to update the specified sections in CLAUDE.md
+
+### Step 3: Verify Alignment
+Ensure new documentation aligns with:
+- systemPrompt content (agent names, hook descriptions)
+- Existing hook implementations
+- Current workflow patterns
+
+## Acceptance Criteria
+- [ ] CLAUDE.md fully documents PR workflow with automated checks
+- [ ] Hook descriptions match systemPrompt context
+- [ ] Agent selection guidelines clear and actionable  
+- [ ] Documentation aligns with existing infrastructure
+- [ ] Examples provided for immediate usability
+- [ ] Backup created for rollback
+
+## Benefits of Documentation Alignment
+- **Consistency**: systemPrompt and documentation provide same context
+- **Completeness**: Full workflow understanding from multiple sources
+- **Usability**: Quick reference for agent selection and hook behavior
+- **Onboarding**: New users understand system immediately
+- **Maintenance**: Single source of truth for workflow changes
+
+## Validation Steps
+1. **Cross-Reference Check**: Verify agent names match between systemPrompt and CLAUDE.md
+2. **Hook Accuracy**: Ensure hook descriptions reflect actual behavior
+3. **Workflow Consistency**: Confirm PR process aligns with git-workflow-validator
+4. **Example Validation**: Test that provided examples work as described