# Planet Ruler — Claude Instructions

## Project Context

Before starting any work, read the following documents in `local/vision/` to understand the project scope, state, and direction:

- [local/vision/PRIMER.md](local/vision/PRIMER.md) — Start here. Quick context for resuming work.
- [local/vision/ROADMAP.md](local/vision/ROADMAP.md) — Current phase, priorities, and development status.
- [local/vision/VISION.md](local/vision/VISION.md) — Core mission and long-term goals.
- [local/vision/TECHNICAL.md](local/vision/TECHNICAL.md) — Technical methods and innovations.
- [local/vision/DOCUMENTATION_STRUCTURE.md](local/vision/DOCUMENTATION_STRUCTURE.md) — How the four-doc system fits together.

## Code Style

- **Docstrings**: Google style (`Args:`, `Returns:`, `Raises:` sections).
- **Type hints**: PEP 484 / `typing` module style — `from __future__ import annotations` at the top of each file, then `Optional`, `List`, `Dict`, `Literal`, etc. from `typing`.
- **Comments**: Must be self-contained and understandable from the codebase alone. Never reference external conversations, GitHub issues, or prior chat context.
- **Transparency**: Code should be readable and educational where possible — prefer clarity over cleverness.

## Collaboration & Decision-Making

- When facing uncertainty or a meaningful design decision, **pause and ask** rather than proceeding unilaterally.
- Do not perform destructive actions (e.g., `git stash`, `git reset --hard`, force-push, file deletion) without explicit permission.
- The user handles all git interaction (commits, branching, merging). Do not run git commands that modify history or push to remotes.

## Branch Strategy (for reference only — user manages git)

- Feature branches split from `dev`, named per contained task.
- Merge back to `dev` when the task is complete.
- Merge `dev` → `main` when a milestone is reached or before too much change accumulates.
