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

Working rules for AI assistants

Project-specific rules for any AI coding assistant working in this repository. Keep the "Non-negotiables" section intact.

1. Non-negotiables

Never run git commit. The human does every commit on this repo. Proposing a commit message they can copy is fine; performing the commit is not.
Never offer or ask to commit. Staging or showing a diff on request is fine.
Never push, force-push, rebase-onto-shared, or rewrite published history without an explicit request.
No attribution lines in commit messages or pull request descriptions - no "Generated with", no "Co-Authored-By", no link back to the assistant session.
Never skip or disable hooks / signing / CI unless explicitly asked. If a hook fails, fix the cause.
Report outcomes honestly. If tests fail, say so and show the output.

2. Before you write any code

Read CONTRIBUTING.md, this file, and the relevant docs/*.md for the subsystem you are about to touch: docs/README.md indexes them - ARCHITECTURE.md (topology), API.md (contract), ALGORITHMS.md (the maths), DEPLOYMENT.md (config), DESIGN.md (the frontend visual system).
Match the surrounding code: naming, idioms, comment density, file layout, error-handling style.
Prefer editing existing files over adding new ones. Do not introduce a new framework, dependency, or architectural pattern to solve a local problem.

3. Language and text

All code, comments, docstrings, commit messages, PR text, and backend-owned user-facing strings (API error messages, log lines) in English.
Frontend UI text is translated: FR + EN, frontend/src/i18n/translations/*.json (en.json is the reference language). Add a UI string as a key there and read it with useTranslation()'s t() (@/hooks/useTranslation), never hardcode text in a component. Every language file must carry the same keys, leaf types, and {placeholder} names as en.json - python scripts/validate_i18n.py checks this and runs in CI.
ASCII punctuation only in source text (this still applies within each language's translation values, French included). Straight apostrophe ' (U+0027), never the curly U+2019. Hyphen-minus - (U+002D), never en/em dashes.

4. Logging and output

Backend: use from app.logging_config import get_logger then logger = get_logger(__name__).
Never use print() / console.log for diagnostics in committed code.
Never import the raw logging library directly or configure your own handlers.
Pick the right level and include context (inputs, paths, ids) in the message.

5. Frontend

No innerHTML or equivalent HTML-string sinks. Build UI with React / explicit DOM APIs; use textContent for any user- or API-derived text.
No static inline styles. Put static presentation in a CSS class or a Tailwind utility. Allowed: runtime show/hide and genuinely per-instance dynamic values (a computed pixel offset for the depth-shift parallax, a progress-bar width).
Both themes, always. The app ships light (default) and dark, switched from the footer. Style through the semantic tokens in src/styles/index.css (bg-surface, text-muted, hover:bg-hover, ...) - never a hardcoded light/dark-specific colour (bg-white/10, text-white, a raw hex). A missing token gets added with a .dark override. Exception: chrome layered on top of an image stays dark in both themes (see docs/DESIGN.md). Verify new surfaces in both themes.
Surfaces: .panel or .panel-inset, nothing else. .panel frames a region; .panel-inset is a block nested inside one. Don't hand-roll rounded border bg-surface.
Keep the existing stack (React 19 + Vite + Tailwind v4). No new frameworks.
Mobile-first / responsive: verify layout at small widths.

6. Architecture and module boundaries

One class / responsibility per file where practical; separate data loading, business logic, and presentation.
routes/ may import services/; services/ must not import routes/.
A helper needed by two features belongs in app/utils/. Do not add a module-level import that closes a dependency cycle.

7. Data correctness

Validate all external/user input before saving it, using it in a file path (use app/utils/validators.py, do not roll your own), or returning it in a response.
No hardcoded data that silently goes stale.

8. Refactoring safety

After any rename of a cross-file contract (function signature, kwarg, dict key, config key, API route), grep the entire repo for the old identifier before calling it done.
After a large mechanical change, run the full test suite, not just the touched file.

9. Tests

Place tests mirroring the source layout (app/services/foo.py -> tests/services/test_foo.py).
Descriptive test names with a docstring stating the behavior under test.
Never cite source line numbers or coverage branch-arcs in test docstrings.
Test the success path, the failure path, and edge/boundary cases. Mock external dependencies (network, containers, clock, third-party APIs).
New behavior ships with tests that prove it works.

10. Git workflow

Work on a branch named feature/<short-description> or fix/<short-description>. If you find yourself on the default branch, branch first.

Commit message format (for messages you propose):

<type>: <subject in imperative mood, <= 72 chars>

<body: what and why, wrapped>

<footer: "Fixes #123" etc.>

Types: feat, fix, docs, style, refactor, test, chore.

11. Definition of done

Do not report a change as complete until the project check set passes:

Report which commands you actually ran and their results.

myastroshine

About