oscilla

Write or modify Oscilla game content YAML manifests for any game package. Use when: creating a new game package, writing adventures, enemies, items, quests, regions, locations, skills, buffs, archetypes, recipes, loot tables, or conditions; designing progression systems; configuring game.yaml or character_config.yaml; authoring template expressions; setting up cooldowns or passive effects; validating content with the CLI; or any task that touches files under a content/ game package directory.

Work with the Oscilla Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology.

Create or modify FastAPI routes in the Oscilla codebase. Use when: adding new API endpoints, creating Pydantic request/response models, registering routers, designing REST APIs, or following route conventions for this project.

Work on the Oscilla frontend (SvelteKit/Vite). Use when: writing or modifying any Svelte components, routes, stores, styles, or frontend tests; adding new UI features or pages; fixing frontend bugs; running frontend tests or type checks; managing npm dependencies; working on accessibility or usability; building production assets; or any task that touches files under frontend/.

Complete reference for all make targets in the Oscilla project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, frontend, packaging, or cleanup.

Use the Oscilla CLI to assist content authors writing YAML manifests. Use when: setting up JSON schema validation for YAML manifests, running validate or oscilla content test, inspecting manifest content with list/show, tracing adventure paths, graphing world structure, scaffolding new manifests with oscilla content create, debugging content errors, checking cross-references. Knows all oscilla content subcommands: schema, test, list, show, graph, trace, create. Also covers oscilla validate.

Add or modify application configuration settings in Oscilla. Use when: adding new environment variables, adding new settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings.

Write or modify Python tests in Oscilla. Use when: adding new tests, understanding testing conventions, working with fixtures, writing FastAPI route tests, database tests, or game engine tests. Covers pytest patterns, fixture structure, and the game engine testing constraints.

Create or modify SQLAlchemy models, queries, and Alembic migrations in the Oscilla codebase. Use when: defining new database tables, writing queries, creating migrations, checking model conventions, or understanding the database layer.

Add or modify CLI commands in Oscilla using Typer. Use when: adding new CLI subcommands, wrapping async functions for CLI use, understanding the CLI entrypoint structure, or following the @syncify pattern for async commands.

Add or modify content for the Testlandia development and QA environment. Use when: developing test content, creating manifests for engine feature validation, adding test adventures/items/enemies, testing game mechanics, QA validation scenarios, debugging content issues. FOR HUMAN MANUAL TESTING ONLY - automated unit/integration testing is out of scope. Includes built-in validation, content structure guidance, and test-friendly naming conventions. SELF-UPDATING: Always validates against current system and updates itself when outdated.