feat: initial project setup with bash-based NREL analysis
- Add bash script (siter-solar-analysis.sh) for NREL PVWatts API - Add BATS test suite with 19 tests (all passing) - Add Docker test environment with shellcheck, bats, curl, jq, bc - Add pre-commit hooks enforcing SDLC rules - Mark Python scripts as deprecated (kept for reference) - Add comprehensive README.md and AGENTS.md documentation - Add .env.example for configuration template - Add .gitignore excluding private data (base-bill/, .env) - Add SVG diagrams for presentation - Redact all private location data (use SITER placeholder) All work done following SDLC: Docker-only development, TDD approach, conventional commits, code/docs/tests synchronized. Generated with Crush Assisted-by: GLM-5 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
161
AGENTS.md
Normal file
161
AGENTS.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# SITER Solar Project - Agent Documentation
|
||||
|
||||
This document provides technical reference for AI agents working on this project.
|
||||
|
||||
## Software Development Lifecycle (SDLC)
|
||||
|
||||
### Host System: Git and Docker ONLY
|
||||
|
||||
**All work must be done inside Docker containers.** The host system is ONLY for:
|
||||
|
||||
1. **Git operations** - commit, push, pull, branch, etc.
|
||||
2. **Docker operations** - build, run, exec, etc.
|
||||
|
||||
**Never run code, tests, or other tools directly on the host system.**
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Build Docker image:**
|
||||
```bash
|
||||
docker build -f Dockerfile.test -t siter-solar-test .
|
||||
```
|
||||
|
||||
2. **Run tests inside Docker:**
|
||||
```bash
|
||||
docker run --rm siter-solar-test
|
||||
```
|
||||
|
||||
3. **Run analysis inside Docker:**
|
||||
```bash
|
||||
docker run --rm -e NREL_API_KEY=your_key siter-solar-test /app/solar-analysis/siter-solar-analysis.sh --scenarios
|
||||
```
|
||||
|
||||
4. **Make atomic commits** using conventional commit format:
|
||||
- `feat:` - New feature
|
||||
- `fix:` - Bug fix
|
||||
- `docs:` - Documentation only
|
||||
- `test:` - Adding/updating tests
|
||||
- `refactor:` - Code refactoring
|
||||
- `chore:` - Maintenance tasks
|
||||
|
||||
### Code/Docs/Tests Synchronization
|
||||
|
||||
**Code, documentation, and tests MUST be kept in sync at all times.**
|
||||
|
||||
- When changing code, update tests and documentation in the same commit
|
||||
- When changing documentation, verify code still matches
|
||||
- When changing tests, ensure code passes new tests
|
||||
- Pre-commit hooks enforce this synchronization
|
||||
|
||||
## Privacy Requirements
|
||||
|
||||
**CRITICAL: This is a public repository. All private data must be removed.**
|
||||
|
||||
### What MUST NOT be committed:
|
||||
- Real addresses or locations (use "SITER" as placeholder)
|
||||
- Account numbers, contract IDs, or meter numbers
|
||||
- The `base-bill/` directory (contains personal billing data)
|
||||
- `.env` file (contains real coordinates and API keys)
|
||||
|
||||
### What should be committed:
|
||||
- `.env.example` - Template with placeholder values
|
||||
- All code and documentation with "SITER" as location identifier
|
||||
- SVG images and analysis scripts
|
||||
|
||||
### Location Data:
|
||||
- Use configurable environment variables: `SITER_LAT`, `SITER_LON`
|
||||
- Default to central Texas coordinates (30.44, -97.62)
|
||||
- Never commit specific addresses
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
siter-solar/
|
||||
├── AGENTS.md # This file
|
||||
├── README.md # Project documentation
|
||||
├── .env.example # Environment template
|
||||
├── .env # Gitignored - actual values
|
||||
├── .gitignore # Excludes private data
|
||||
├── Dockerfile.test # Test environment
|
||||
├── v2-siter-solar-plan.md # Main proposal document
|
||||
├── images/ # SVG diagrams for presentation
|
||||
│ ├── v2-image-1.svg # System architecture diagram
|
||||
│ ├── v2-image-2.svg # Monthly production chart
|
||||
│ ├── v2-image-3.svg # ROI/payback timeline
|
||||
│ └── v2-image-4.svg # System size comparison
|
||||
└── solar-analysis/ # NREL PVWatts analysis tools
|
||||
├── siter-solar-analysis.sh # Main bash script (production)
|
||||
├── tests/ # BATS test suite
|
||||
│ └── siter-solar-analysis.bats
|
||||
├── solar_estimate.py # DEPRECATED - kept for reference
|
||||
├── solar_optimal.py # DEPRECATED - kept for reference
|
||||
├── solar_optimized.py # DEPRECATED - kept for reference
|
||||
├── Dockerfile # Production image
|
||||
└── run-analysis.sh # Docker wrapper
|
||||
```
|
||||
|
||||
## Running NREL Analysis
|
||||
|
||||
### Using Bash Script (Recommended)
|
||||
|
||||
Inside Docker:
|
||||
```bash
|
||||
# Basic analysis
|
||||
./siter-solar-analysis.sh
|
||||
|
||||
# With custom API key
|
||||
./siter-solar-analysis.sh -k YOUR_API_KEY
|
||||
|
||||
# Compare system sizes
|
||||
./siter-solar-analysis.sh --scenarios
|
||||
|
||||
# JSON output
|
||||
./siter-solar-analysis.sh --json
|
||||
|
||||
# Custom configuration
|
||||
./siter-solar-analysis.sh -p 20 -w 400 --lat 30.5 --lon -97.7
|
||||
```
|
||||
|
||||
### Python Scripts (DEPRECATED)
|
||||
|
||||
The Python scripts are kept for reference only. Use the bash script instead.
|
||||
|
||||
## Key Parameters
|
||||
|
||||
| Parameter | Value | Notes |
|
||||
|-----------|-------|-------|
|
||||
| System Capacity | 4.0 kW DC | 16 × 250W panels |
|
||||
| Array Type | Fixed Open Rack | Ground mount |
|
||||
| Tilt | 30° | Optimal for latitude |
|
||||
| Azimuth | 180° | South-facing |
|
||||
| Losses | 14% (default) | Can optimize to 8% |
|
||||
|
||||
## Base Power Contract Details
|
||||
|
||||
- **Energy Rate:** $0.085/kWh (fixed through Oct 2028)
|
||||
- **Solar Buyback:** $0.04/kWh (credits apply to entire bill)
|
||||
- **Subscription Fee:** $10/month
|
||||
|
||||
## ROI Calculation Method
|
||||
|
||||
1. Annual production from NREL PVWatts (kWh/year)
|
||||
2. Self-consumption: 60% × production × $0.085/kWh
|
||||
3. Grid export: 40% × production × $0.04/kWh
|
||||
4. Total annual value = self-consumption + export
|
||||
5. Payback = Total investment / annual value
|
||||
|
||||
## Testing
|
||||
|
||||
Run tests inside Docker:
|
||||
```bash
|
||||
docker build -f Dockerfile.test -t siter-solar-test .
|
||||
docker run --rm siter-solar-test
|
||||
```
|
||||
|
||||
## Updating the Analysis
|
||||
|
||||
1. Modify `siter-solar-analysis.sh` as needed
|
||||
2. Update tests in `tests/siter-solar-analysis.bats`
|
||||
3. Run tests to verify changes
|
||||
4. Update `v2-siter-solar-plan.md` with new estimates
|
||||
5. Commit all changes together in atomic commit
|
||||
Reference in New Issue
Block a user