solarwindpy 0.1.2__tar.gz → 0.1.4__tar.gz

{solarwindpy-0.1.2 → solarwindpy-0.1.4}/.claude/agents/agent-unified-plan-coordinator.md

@@ -12,20 +12,21 @@ You are the UnifiedPlanCoordinator for SolarWindPy, managing the complete plan l
 ## Core Capabilities
 
 ### 1. Plan Management (Strategic Planning)
-- **Create structured multi-phase plans** using enhanced templates from `plans/0-overview-template.md`
-- **Automated value proposition generation** via `.claude/hooks/plan-value-generator.py`
+- **Create structured multi-phase plans** using GitHub Issues with comprehensive templates
+- **Automated value proposition generation** via integrated GitHub Issue templates  
 - **Comprehensive value analysis**: Security, ROI, token optimization, risk assessment
-- **Interactive plan discovery** across `plan/*` branches with status assessment
+- **Interactive plan discovery** across GitHub Issues with label-based filtering
 - **Time estimation with velocity learning** based on historical data and complexity factors
 - **Lifecycle management**: Planning → Active → Paused → Completed → Archived
-- **Quality validation**: Optional `.claude/hooks/plan-value-validator.py` for plan completeness
+- **GitHub Issues integration**: Complete propositions framework in structured templates
+- **Multi-computer synchronization**: Instant access across development machines
 - **Token optimization**: Achieve 60-80% reduction in planning session token usage
 
 ### 2. Implementation Execution (Task Execution)
 - **Execute tasks with automatic checksum tracking** - replace `<checksum>` with actual commit hashes
-- **Cross-branch coordination** between `plan/*` and `feature/*` branches
+- **Cross-issue coordination** between GitHub Issues and feature branches
 - **Quality validation at each step**: pytest, flake8, black formatting
-- **Completion workflow**: feature → plan → master merge progression
+- **Completion workflow**: GitHub Issues → feature → master merge progression
 
 ### 3. Status Monitoring (Cross-Plan Coordination)
 - **Cross-plan dependency analysis** - detect resource conflicts and sequential requirements
@@ -55,43 +56,101 @@ Intelligently delegate to domain specialists when needed:
 - **Plotting tasks** → PlottingEngineer sub-agent
 - **Curve fitting** → FitFunctionSpecialist sub-agent
 
+## GitHub Issues Integration
+
+### Issue Template Workflow
+**Overview Issue (plan-overview.yml):**
+- Complete propositions framework with all 8 required sections
+- Value analysis, risk assessment, token optimization, scope audit
+- Links to all phase issues and dependencies
+- Multi-computer accessible planning documentation
+
+**Phase Issue (plan-phase.yml):**
+- Detailed task breakdown with time estimates
+- Progress tracking with commit checksum integration
+- Context management points for session boundaries
+- Phase-specific acceptance criteria and testing strategy
+
+**Closeout Issue (plan-closeout.yml):**
+- 85% implementation decision capture target
+- Lessons learned and velocity analysis
+- Value realization assessment
+- Team feedback and knowledge preservation
+
+### GitHub CLI Integration Commands
+```bash
+# Create new plan with comprehensive content (automated)
+.claude/scripts/gh-plan-create.sh -p high -d infrastructure "Plan Name"
+
+# Create phases with detailed task breakdowns (automated)
+.claude/scripts/gh-plan-phases.sh -q "Phase1,Phase2,Phase3" <overview-issue>
+
+# Query active plans
+gh issue list --label "plan:overview,status:in-progress"
+
+# Check plan status across all issues
+.claude/scripts/gh-plan-status.sh
+
+# Update issue status
+gh issue edit <issue> --add-label "status:completed" --remove-label "status:in-progress"
+
+# Cross-issue relationships (automatically created by scripts)
+gh issue list --search "is:open label:plan:phase mentions:#<overview-issue>"
+```
+
+### Multi-Computer Synchronization
+**Instant Access Benefits:**
+- Plans accessible from all 3 development computers immediately
+- No branch synchronization overhead or context switching friction
+- GitHub Issues provide real-time status updates across machines
+- Eliminates local-only plan branch management complexity
+
 ## Primary Workflows
 
-### Plan Creation Workflow (Enhanced with Value Propositions)
+### Plan Creation Workflow (Enhanced with Automated Content Generation)
 ```
 User: "Create plan for implementing dark mode"
 Process:
-1. Create plan branch: git checkout -b plan/dark-mode-implementation
-2. Initialize from templates with time estimates and complexity scoring
-3. **Generate value propositions**: Call .claude/hooks/plan-value-generator.py
-4. **Insert generated content**: Replace template placeholders with comprehensive value analysis
-5. Break down into phases with task-level estimates (5-30 min granularity)
-6. Set up tracking metadata, dependencies, and acceptance criteria
-7. **Optional validation**: Run .claude/hooks/plan-value-validator.py for quality assurance
-8. Record initial velocity baseline for this plan type
+1. **Create Overview Issue**: CLI script automatically generates comprehensive propositions framework content
+   - Calls plan-value-generator.py hook with plan metadata
+   - Injects complete 8-section propositions framework into GitHub Issue body
+   - Creates issue with all value analysis, risk assessment, and scope audit sections
+2. **Create Phase Issues**: CLI script generates detailed phase content with task breakdowns
+   - Creates comprehensive phase structure with acceptance criteria
+   - Includes task groups, progress tracking, and context management points
+   - Links phases to overview issue automatically
+3. **Create Feature Branch**: git checkout -b feature/issue-123-dark-mode from overview issue
+4. **Track Implementation**: Update phase issues with task completion and commits
+5. **Progress Monitoring**: Use GitHub labels and milestones for status tracking
+6. **Cross-issue coordination**: Maintain issue relationships and dependencies
+7. **Record velocity metrics**: Capture time estimates vs actuals for learning
 ```
 
-**Value Proposition Generation Steps:**
+**Automated Content Generation:**
 ```bash
-# Step 3: Generate comprehensive value propositions
-python .claude/hooks/plan-value-generator.py \
-  --plan-file plans/<plan-name>/0-Overview.md \
-  --exclude-fair  # Always exclude FAIR compliance
+# CLI script automatically calls value generator during issue creation
+# No manual value proposition generation required
+
+# Create plan with comprehensive content (fully automated)
+.claude/scripts/gh-plan-create.sh -p high -d infrastructure "Dark Mode Implementation"
+
+# Create phases with detailed task breakdowns (fully automated)  
+.claude/scripts/gh-plan-phases.sh -q "Setup,Implementation,Testing" <issue-number>
 
-# Step 7: Optional validation for quality assurance
+# Optional validation for quality assurance
 python .claude/hooks/plan-value-validator.py \
-  --plan-file plans/<plan-name>/0-Overview.md
+  --plan-data '{"plan_name":"Dark Mode Implementation","priority":"high"}'
 ```
 
 ### Plan Discovery & Continuation
 ```
 User: "Show me all current plans" or "Continue API refactoring"
 Process:
-1. Scan plan/* branches and read 0-Overview.md status
-2. Load compacted states if available for context
+1. Query GitHub Issues with plan labels and status filters
+2. Load issue context and cross-issue relationships
 3. Present organized summary with progress percentages and velocity trends
-4. Switch to appropriate branch and identify next tasks
-5. Coordinate with implementation workflow if ready
+4. Switch to appropriate feature branch and identify next tasks from phase issues
+5. Coordinate implementation using GitHub Issues for tracking
 ```
 
 ### Implementation Execution
@@ -102,34 +161,34 @@ Process:
 2. Execute tasks with domain specialist consultation as needed
 3. Run quality validation: pytest -q, black ., flake8
 4. Commit with descriptive conventional format message
-5. Replace <checksum> placeholders with actual commit hashes
-6. Update phase files with completion status and actual time
-7. Sync progress back to plan/* branch
+5. Update phase issues with commit hashes and completion status
+6. Update GitHub Issues with progress, actual time, and lessons learned
+7. Cross-reference commits in issue comments for full traceability
 ```
 
 ### Cross-Plan Monitoring
 ```
 User: "Plan status dashboard" or automatic when conflicts detected
 Process:
-1. Scan all plans/* directories for active work
-2. Analyze explicit dependencies from metadata
-3. Detect resource conflicts (same files/modules)
-4. Generate recommendations for resolution
-5. Provide priority ordering and next actions
+1. Query GitHub Issues with plan labels for active work
+2. Analyze explicit dependencies from issue cross-references
+3. Detect resource conflicts from affected areas in issue descriptions
+4. Generate recommendations for resolution using GitHub API data
+5. Provide priority ordering and next actions based on issue labels
 ```
 
-### Plan Completion & Archival (Enhanced with Value Validation)
+### Plan Completion & Archival (Enhanced with GitHub Issues)
 ```
 User: "Mark plan as completed" or automatic detection when all phases done
 Process:
-1. **Validate value propositions**: Run .claude/hooks/plan-value-validator.py
-2. Verify plan completion status (all phases marked [x], status = "Completed")
-3. Ensure all required value proposition sections are present and complete
-4. Preserve plan branches for auditing (log to .claude/branch-preservation.log)
-5. Move plan directory from plans/<name>/ to plans/completed/<name>/
-6. Update cross-plan dependencies and remove from active tracking
-7. Record completion metrics for velocity learning (including token savings achieved)
-8. NEVER delete branches - preserve for audit trail
+1. **Create Closeout Issue**: Use plan-closeout.yml template for comprehensive documentation
+2. Verify plan completion status (all phase issues closed, overview issue complete)
+3. Capture 85% implementation decisions in closeout issue as per template
+4. Archive feature branch and update GitHub Issues with completion status
+5. Close all related issues (overview, phases, closeout) with final status
+6. Record completion metrics for velocity learning in closeout issue
+7. GitHub Issues provide permanent audit trail and searchable history
+8. Update issue labels to "status:completed" for filtering
 ```
 
 **Value Validation Requirements:**
@@ -142,10 +201,11 @@ Process:
 ## Integration with SolarWindPy Workflow
 
 ### Git Workflow Integration
-- **Plan branches**: `plan/<name>` for planning and tracking
-- **Feature branches**: `feature/<name>` for implementation work
-- **Master integration**: Clean merge progression with hooks validation
-- **Commit tracking**: Meaningful messages tied to plan objectives
+- **GitHub Issues**: Comprehensive planning and tracking via structured templates
+- **Feature branches**: `feature/<name>` for implementation work linked to issues
+- **Master integration**: Clean merge progression with PR references to issues
+- **Commit tracking**: Meaningful messages tied to issue objectives and phase tasks
+- **Cross-reference**: All commits referenced in corresponding GitHub Issues
 
 ### Multi-Phase Plan Structure
 ```

{solarwindpy-0.1.2 → solarwindpy-0.1.4}/.claude/agents.md

@@ -12,7 +12,8 @@
   - List unmerged branches: `git branch -r --no-merged master`
   - Ask user to specify branch or request search/new branch creation
   - NEVER work directly on master branch
-  - Use branch pattern: `claude/YYYY-MM-DD-HH-MM-SS-module-feature-description`
+  - Use GitHub Issues workflow: feature/* branches created directly from GitHub Issues
+  - Follow GitHub Issues → feature/* → PR → master progression
 - Run `pytest -q` before ANY commit; all tests MUST pass
 - Format with `black solarwindpy/` and lint with `flake8`
 - Use NumPy-style docstrings for all public functions

solarwindpy-0.1.4/.claude/scripts/README.md

@@ -0,0 +1,280 @@
+# GitHub Issues Plan Management Scripts
+
+This directory contains CLI automation scripts for managing SolarWindPy plans using GitHub Issues with comprehensive propositions framework.
+
+## Quick Start
+
+### 1. Create New Plan
+```bash
+# Interactive mode
+.claude/scripts/gh-plan-create.sh
+
+# Direct creation
+.claude/scripts/gh-plan-create.sh "Dark Mode Implementation" -p high -d infrastructure
+
+# Command-line options
+.claude/scripts/gh-plan-create.sh -p critical -d physics "Thermal Speed Validation"
+```
+
+### 2. Create Implementation Phases
+```bash
+# Interactive phase creation
+.claude/scripts/gh-plan-phases.sh 123
+
+# Quick phase creation
+.claude/scripts/gh-plan-phases.sh -q "Setup,Implementation,Testing" 123
+
+# With closeout issue
+.claude/scripts/gh-plan-phases.sh -c 123
+```
+
+### 3. Monitor Plan Status
+```bash
+# Full dashboard
+.claude/scripts/gh-plan-status.sh
+
+# Summary only
+.claude/scripts/gh-plan-status.sh -s
+
+# Recommendations
+.claude/scripts/gh-plan-status.sh -r
+
+# Filter by status
+.claude/scripts/gh-plan-status.sh -f in-progress
+```
+
+## Scripts Overview
+
+### gh-plan-create.sh
+**Purpose**: Create comprehensive plan overview issues with complete propositions framework
+
+**Features**:
+- Interactive and command-line modes
+- 25 GitHub labels across 5 categories (priority, status, type, plan, domain)
+- Automatic feature branch creation
+- Complete propositions framework integration
+
+**Usage**:
+```bash
+./gh-plan-create.sh [OPTIONS] [PLAN_NAME]
+
+Options:
+  -h, --help              Show help message
+  -p, --priority LEVEL    Set priority (critical|high|medium|low)
+  -d, --domain DOMAIN     Set domain (physics|data|plotting|testing|infrastructure|docs)
+  -i, --interactive       Run in interactive mode
+```
+
+### gh-plan-status.sh
+**Purpose**: Comprehensive plan monitoring and status dashboard
+
+**Features**:
+- Multi-plan overview with status badges
+- Summary statistics and domain distribution
+- Actionable recommendations for blocked/critical plans
+- Colored output for easy visual scanning
+
+**Usage**:
+```bash
+./gh-plan-status.sh [OPTIONS]
+
+Options:
+  -h, --help          Show help message
+  -s, --summary       Show only summary statistics
+  -d, --detailed      Show detailed view with phase issues
+  -r, --recommendations Show only recommendations
+  -f, --filter STATUS Filter by status
+```
+
+### gh-plan-phases.sh
+**Purpose**: Create and link phase issues to plan overview
+
+**Features**:
+- Interactive, batch, and quick creation modes
+- Automatic cross-linking between overview and phase issues
+- Optional closeout issue creation
+- Configuration file support for batch operations
+
+**Usage**:
+```bash
+./gh-plan-phases.sh [OPTIONS] OVERVIEW_ISSUE
+
+Options:
+  -h, --help          Show help message
+  -i, --interactive   Interactive phase creation (default)
+  -b, --batch FILE    Batch create from configuration file
+  -c, --closeout      Also create closeout issue
+  -q, --quick PHASES  Quick create (comma-separated names)
+```
+
+## Issue Templates
+
+### Plan Overview Template (plan-overview.yml)
+Comprehensive planning template with 8 required sections:
+- **🎯 Objective**: Clear goal statement
+- **🧠 Context**: Background and motivation
+- **🔧 Technical Requirements**: Dependencies and constraints
+- **📂 Affected Areas**: Files and components
+- **✅ Acceptance Criteria**: Measurable completion criteria
+- **📊 Value Proposition Analysis**: Scientific and productivity value
+- **💰 Resource & Cost Analysis**: Time investment and ROI
+- **⚠️ Risk Assessment**: Technical and project risks
+- **🔒 Security Proposition**: Code-level security (NO FAIR compliance)
+- **🎯 Scope Audit**: SolarWindPy alignment validation
+- **💾 Token Usage Optimization**: Claude session efficiency
+- **⏱️ Time Investment Analysis**: Development time breakdown
+- **🎯 Usage & Adoption Metrics**: Success criteria and adoption strategy
+
+### Plan Phase Template (plan-phase.yml)
+Detailed implementation template with:
+- **📋 Implementation Tasks**: Task breakdown with time estimates
+- **✅ Phase Acceptance Criteria**: Phase-specific completion criteria
+- **🧪 Phase Testing Strategy**: Testing approach for this phase
+- **🔧 Phase Technical Requirements**: Phase-specific tools and frameworks
+- **📂 Phase Affected Areas**: Files modified in this phase
+- **📊 Phase Progress Tracking**: Real-time status monitoring
+- **🔄 Context Management Points**: Session break points for token management
+
+### Plan Closeout Template (plan-closeout.yml)
+Comprehensive completion documentation with:
+- **📦 Final Deliverables**: Complete delivery list
+- **✅ Acceptance Criteria Review**: Status of all original criteria
+- **🧠 Implementation Decisions**: 85% decision capture target
+- **📚 Lessons Learned**: What worked, challenges, and improvements
+- **⏱️ Actual vs Estimated Analysis**: Time accuracy and velocity learning
+- **💰 Value Realization Assessment**: Did the plan deliver expected value?
+- **🔍 Quality Metrics**: Code quality, coverage, and technical debt
+- **🎯 Follow-up Actions**: Next steps and future enhancements
+- **📁 Plan Archival Information**: Knowledge preservation and searchability
+- **👥 Team Feedback & Recognition**: Process feedback and contributor recognition
+
+## GitHub Labels System
+
+### Priority Labels
+- `priority:critical` - Critical priority - immediate attention required
+- `priority:high` - High priority - address soon
+- `priority:medium` - Medium priority - normal timeline
+- `priority:low` - Low priority - when time permits
+
+### Status Labels
+- `status:planning` - Currently in planning phase
+- `status:in-progress` - Currently being worked on
+- `status:blocked` - Blocked waiting for dependencies
+- `status:review` - Ready for review
+- `status:completed` - Completed successfully
+
+### Type Labels
+- `type:feature` - New feature development
+- `type:bugfix` - Bug fix
+- `type:refactor` - Code refactoring
+- `type:docs` - Documentation changes
+- `type:test` - Testing improvements
+- `type:infrastructure` - Infrastructure and tooling
+- `type:chore` - Maintenance and chores
+
+### Plan Structure Labels
+- `plan:overview` - Plan overview issue
+- `plan:phase` - Plan phase issue
+- `plan:closeout` - Plan closeout issue
+
+### Domain Labels
+- `domain:physics` - Solar wind physics calculations
+- `domain:data` - Data structures and processing
+- `domain:plotting` - Visualization and plotting
+- `domain:testing` - Testing and validation
+- `domain:infrastructure` - Development infrastructure
+- `domain:docs` - Documentation and guides
+
+## Multi-Computer Workflow
+
+### Benefits
+- **Instant Access**: Plans available immediately on all 3 development computers
+- **No Synchronization**: No branch sync overhead or context switching friction
+- **Real-time Updates**: GitHub Issues provide live status across machines
+- **Searchable History**: Complete plan history with GitHub's powerful search
+
+### Setup Requirements
+1. **GitHub CLI**: Install `gh` on all development machines
+2. **Authentication**: Run `gh auth login` on each machine
+3. **Repository Access**: Ensure write access to repository
+4. **Script Access**: Copy scripts to all machines or use shared network location
+
+### Typical Workflow
+1. **Create Plan**: Use `gh-plan-create.sh` from any machine
+2. **Phase Creation**: Use `gh-plan-phases.sh` to break down implementation
+3. **Switch Machines**: Plan instantly accessible on any development computer
+4. **Implementation**: Work on feature branch, update issues with progress
+5. **Monitoring**: Use `gh-plan-status.sh` to track overall progress
+6. **Completion**: Create closeout issue with comprehensive documentation
+
+## Integration with Existing SolarWindPy Workflow
+
+### UnifiedPlanCoordinator Integration
+The GitHub Issues system integrates seamlessly with the existing UnifiedPlanCoordinator agent:
+- Agent extended with GitHub Issues capabilities
+- Automatic cross-issue coordination and linking
+- Integration with existing hooks and validation systems
+- Preserves all sophisticated planning capabilities
+
+### Hook System Compatibility
+- Existing physics validation hooks continue to work
+- Token management handled through natural session boundaries
+- Quality validation (pytest, black, flake8) integrated into phase tracking
+- Velocity learning captured in closeout issues
+
+### Scientific Workflow Preservation
+- All propositions framework elements preserved in GitHub templates
+- 85% implementation decision capture maintained
+- Comprehensive value analysis for scientific software development
+- SolarWindPy scope alignment validation in every plan
+
+## Troubleshooting
+
+### Common Issues
+1. **GitHub CLI not authenticated**: Run `gh auth login`
+2. **Template not found**: Ensure you're in repository root directory
+3. **Permission denied**: Check repository write access
+4. **Issue creation failed**: Verify network connection and GitHub status
+
+### Script Debugging
+- Add `-x` to bash scripts for verbose debugging: `bash -x gh-plan-create.sh`
+- Check GitHub CLI status: `gh auth status`
+- Verify repository context: `gh repo view`
+
+### Multi-Computer Issues
+- Ensure same GitHub authentication on all machines
+- Verify script permissions: `chmod +x .claude/scripts/*.sh`
+- Check network connectivity to GitHub
+- Confirm repository access from each machine
+
+## Advanced Usage
+
+### Custom Batch Configuration
+Create a configuration file for batch phase creation:
+```
+Foundation Setup|2-3 hours|None
+Core Implementation|4-5 hours|Phase 1
+Testing & Validation|1-2 hours|Phase 2
+Documentation|1 hour|Phase 3
+```
+
+Then use: `gh-plan-phases.sh -b phases.conf 123`
+
+### GitHub CLI Power Usage
+```bash
+# Find all physics domain plans
+gh issue list --label "domain:physics,plan:overview"
+
+# Critical plans that need attention
+gh issue list --label "priority:critical,status:blocked"
+
+# Plans updated in the last week
+gh issue list --search "label:plan:overview updated:>$(date -d '7 days ago' +%Y-%m-%d)"
+
+# Export plan data to JSON
+gh issue list --label "plan:overview" --json number,title,labels,assignees > plans.json
+```
+
+---
+
+For more information, see the main CLAUDE.md file and the UnifiedPlanCoordinator agent documentation.