Development Guidelines

Before Making Changes

1. Understand the current state by reading relevant test files.
2. Check cosmo/core/config/settings.yaml for configuration that affects behavior.
3. Verify changes against the actual source code, not documentation.
4. Run focused tests before hardware-dependent tests.

When Adding Features

1. Define event names in cosmo/core/events/event_types.py if event-driven.
2. Add listener registration in cosmo/core/bootstrap/bootstrap.py.
3. Emit events from implementation code with correct priority.
4. Add tests that match the real emitted lifecycle.
5. Update configuration in settings.yaml if adding configurable behavior.

Documentation Rules

1. Documentation must reflect actual code state, not intended design.
2. If a module is experimental, mark it as experimental.
3. Keep diagrams updated after architectural changes.
4. When adding a new subsystem, update overview, architecture, configuration, testing, troubleshooting, known limitations, and roadmap.
5. Do not describe roadmap items as implemented features.

When Modifying Audio/Wakeword

1. Verify Vosk model directory exists: cosmo/models/vosk/vosk-model-small-pt-0.3/.
2. Check sample rate, chunk size, and silence thresholds are consistent.
3. Test with actual microphone and audio files.
4. Monitor CPU usage; adjust energy_threshold and idle_sleep if needed.
5. Run test_tts_pipeline.py to validate end-to-end audio flow.

When Modifying Personality

1. Test parser behavior with test_persona_command_parser.py.
2. Verify JSON persistence with test_persona_persistance.py.
3. Test prompt construction with test_persona_command_integration.py.
4. Check that parameter values clamp to 0-100.
5. Validate database aliases are loaded correctly.

When Modifying Memory

1. Validate extraction rules do not fire on normal conversation.
2. Run filter tests: test_memory_filter.py.
3. Test duplicate prevention: test_memory_manager.py.
4. Verify SQLite storage and retrieval: test_database.py.
5. Check memory context injection in prompts.

When Adding Local Commands

1. Add to the local_commands table in SQLite.
2. Test phrase matching with normalization: test_local_command_db.py.
3. Keep handler logic deterministic and quick.
4. Avoid LLM calls; use fallback responses for errors.
5. Save conversation through MemoryManager.process_interaction() for audit.

High-Signal Validation by Subsystem

Common Patterns to Follow

1. Import singletons: from cosmo.core.config.settings_manager import config.
2. Emit events with priority: await async_event_bus.emit(name, data, priority=PRIORITY_AUDIO).
3. Check guards before state changes: if not runtime_state.can_start_thinking(): return.
4. Use repository pattern for data access: memory_repository.add_memory(...).
5. Create background tasks for non-blocking work: asyncio.create_task(long_running_coro()).
6. Log lifecycle events: logger.info(f"Starting component...").

Code Quality Standards

• Use type hints where practical.
• Follow existing naming conventions: snake_case for functions and variables.
• Keep methods focused on single responsibility.
• Test error paths, not just happy paths.
• Document non-obvious behavior in docstrings or comments.
• Avoid global state except singletons: logger, config, db, event bus, runtime_state.