# Tara — Claude Code Instructions
## Project Identity
**Tara** (Sanskrit: तारा — star) — Stellar astrophysics engine for the AGNOS science stack
- **Type**: Flat library crate
- **License**: GPL-3.0
- **MSRV**: 1.89
- **Version**: 1.0.0
## Consumers
AGNOS science stack, kiran, joshua, simulation apps.
## Development Process
### P(-1): Scaffold Hardening (before any new features)
0. Read roadmap, CHANGELOG, and open issues — know what was intended before auditing what was built
1. Test + benchmark sweep of existing code
2. Cleanliness check: `cargo fmt --check`, `cargo clippy --all-features --all-targets -- -D warnings`, `cargo audit`, `cargo deny check`, `RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps`
3. Get baseline benchmarks (`./scripts/bench-history.sh`)
4. Internal deep review — gaps, optimizations, security, logging/errors, docs
5. External research — domain completeness, missing capabilities, best practices, world-class accuracy
6. Cleanliness check — must be clean after review
7. Additional tests/benchmarks from findings
8. Post-review benchmarks — prove the wins
9. Repeat if heavy
### Work Loop / Working Loop (continuous)
1. Work phase — new features, roadmap items, bug fixes
2. Cleanliness check: `cargo fmt --check`, `cargo clippy --all-features --all-targets -- -D warnings`, `cargo audit`, `cargo deny check`, `RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps`
3. Test + benchmark additions for new code
4. Run benchmarks (`./scripts/bench-history.sh`)
5. Internal review — performance, memory, security, throughput, correctness
6. Cleanliness check — must be clean after review
7. Deeper tests/benchmarks from review observations
8. Run benchmarks again — prove the wins
9. If review heavy → return to step 5
10. Documentation — update CHANGELOG, roadmap, docs
11. Version check — VERSION, Cargo.toml, recipe all in sync
12. Return to step 1
### Task Sizing
- **Low/Medium effort**: Batch freely — multiple items per work loop cycle
- **Large effort**: Small bites only — break into sub-tasks, verify each before moving to the next. Never batch large items together
- **If unsure**: Treat it as large. Smaller bites are always safer than overcommitting
### Refactoring
- Refactor when the code tells you to — duplication, unclear boundaries, performance bottlenecks
- Never refactor speculatively. Wait for the third instance before extracting an abstraction
- Refactoring is part of the work loop, not a separate phase. If a review (step 5) reveals structural issues, refactor before moving to step 6
- Every refactor must pass the same cleanliness + benchmark gates as new code
### Key Principles
- Never skip benchmarks
- Own the stack — tara IS the stellar astrophysics vocabulary
- `#[non_exhaustive]` on ALL public enums (forward compatibility)
- `#[must_use]` on all pure functions
- Every type must be Serialize + Deserialize (serde)
- Feature-gate optional modules — consumers pull only what they need
- Zero unwrap/panic in library code
- All types must have serde roundtrip tests
## DO NOT
- **Do not commit or push** — the user handles all git operations
- **NEVER use `gh` CLI** — use `curl` to GitHub API only
- Do not add unnecessary dependencies
- Do not break backward compatibility without a major version bump
- Do not skip benchmarks before claiming performance improvements
- **Do not update VERSION, Cargo.toml version, or CLAUDE.md version without explicit user permission**
## Documentation Structure
```
Root files (required):
README.md, CHANGELOG.md, CLAUDE.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, LICENSE
docs/ (required):
architecture/overview.md — module map, data flow, consumers
development/roadmap.md — completed, backlog, future, v1.0 criteria
docs/ (when earned):
adr/ — architectural decision records
guides/usage.md — patterns and examples
```
## CHANGELOG Format
Follow [Keep a Changelog](https://keepachangelog.com/). Performance claims MUST include benchmark numbers. Breaking changes get a **Breaking** section with migration guide.