Imported from ergetie/darkstar (AGENTS.md). Install upstream with npx skills add ergetie/darkstar. Copyright stays with the author.

AGENTS.md - Darkstar Energy Manager

Name: darkstar
Author: ergetie

Core Philosophy

Production-grade only. No shortcuts, no quick fixes. Clean, maintainable, robust implementations.
NEVER ASSUME. Verify everything. If uncertain, ask the user.
Respond concisely. No unsolicited code, no lengthy explanations unless asked.

Environment

Python: 3.12 (see .python-version)
Package manager: uv (virtual env in .venv/)
Frontend: React + Vite, managed with pnpm

Commands

Task	Command
Install dependencies	`uv pip install -r requirements.txt`
Run dev environment	`pnpm run dev`
Run single test	`UV_NO_SYNC=1 uv run python -m pytest tests/test_file.py::test_name -v`
Run all checks	`./scripts/lint.sh`

Always prefix ad-hoc uv run ... commands with UV_NO_SYNC=1 — without it, uv regenerates a meaningless uv.lock stub on every call (deps are pinned via requirements*.txt, not uv's lockfile; see pyproject.toml [tool.uv] package = false).

Project Structure

backend/            - FastAPI API, Strategy Engine, Executor
frontend/           - React + Vite UI
planner/            - MPC scheduling logic (Kepler MILP solver)
ml/                 - Aurora ML pipeline (train.py, forward.py)
config.yaml         - Local configuration (environment-specific, never commit)
config.default.yaml - Shipped template with defaults

UI Design System

All UI changes must follow the design system:

Guidelines: docs/design-system/AI_GUIDELINES.md
Live preview: /design-system route
SSOT for tokens: frontend/src/index.css

Boundaries

⚠️ Ask First

Modifying files in docs/ directory
Database schema changes
Adding new dependencies
Major architectural changes
Staging or committing git changes

🚫 Never

Commit runtime data: *.db, schedule.json, data/scheduler_status.json
Commit config.yaml — defaults go in config.default.yaml
Commit secrets or API keys
Modify docs/RELEASE_NOTES.md unless explicitly instructed
Push git changes unless explicitly instructed

Git & Commits

Format: Conventional commits with multi--m flags for detail:

git commit -m "feat(executor): migrate to async aiohttp HTTP client" \
  -m "- Replace sync requests with async aiohttp for HA API calls" \
  -m "- Add 5-second timeout to prevent executor freezing" \
  -m "- Implement exponential backoff retry for transient errors" \
  -m "Fixes critical issue where executor froze when inverter became unresponsive."

Troubleshooting

AI Extension UI Desync

If a command completes but the UI still shows "Running":

Cause: Multi-line strings inside -m quotes confuse the terminal parser
Prevention: Always use single-line -m strings
Fix: pkill -9 -f "shellIntegration-bash"

{ "ocm": "1", "id": "ergetie-darkstar-darkstar", "kind": "skill", "name": "darkstar", "description": "Always prefix ad-hoc `uv run ...` commands with `UV_NO_SYNC=1` — without it, uv regenerates a meaningless `uv.lock` stub on every call (deps are pinned via `requirements*.txt`, not uv's lockfile; see `pyproject.toml` `[tool.uv] package = false`).", "publisher": "ergetie", "version": "1.0.0", "capabilities": { "domains": [ "general" ], "tags": [ "skill-md", "github-agents" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "Always prefix ad-hoc `uv run ...` commands with `UV_NO_SYNC=1` — without it, uv regenerates a meaningless `uv.lock` stub on every call (deps are pinned via `requirements*.txt`, not uv's lockfile; see `pyproject.toml` `[tool.uv] package = false`)." ], "primary": false, "metadata": { "source": { "provider": "github-agents", "repository": "https://github.com/ergetie/darkstar", "path": "AGENTS.md", "ref": "68c19b608d67b3163a752001d0ea59545488ea8c", "url": "https://github.com/ergetie/darkstar/blob/68c19b608d67b3163a752001d0ea59545488ea8c/AGENTS.md", "key": "ergetie/darkstar/AGENTS.md" } }, "instructions": "# AGENTS.md - Darkstar Energy Manager\n\n---\n\n## Core Philosophy\n\n- **Production-grade only**. No shortcuts, no quick fixes. Clean, maintainable, robust implementations.\n- **NEVER ASSUME**. Verify everything. If uncertain, ask the user.\n- **Respond concisely**. No unsolicited code, no lengthy explanations unless asked.\n\n---\n\n## Environment\n\n- **Python**: 3.12 (see `.python-version`)\n- **Package manager**: `uv` (virtual env in `.venv/`)\n- **Frontend**: React + Vite, managed with `pnpm`\n\n## Commands\n\n| Task | Command |\n|------|---------|\n| Install dependencies | `uv pip install -r requirements.txt", "cost": { "context_tokens": 720 } }

darkstar

About