mindroom: Command for Claude Code

Initialize MindRoom Understanding

Your Task

$ARGUMENTS

Instructions:

• If a feature description was provided above, initialize your understanding of MindRoom and then start implementing that feature
• If no feature description was provided (empty above), just initialize your understanding and wait for further instructions
• Either way, first understand the current development context and project structure below

Current Development Context

• Current branch: !git branch --show-current
• Changes from main: !git diff --merge-base origin/main --stat
• Full diff: !git diff --merge-base origin/main

Note: If there are no changes from main, we're starting fresh. Otherwise, understand the current feature being developed from the diff above.

Important: Speech-to-Text Usage

The user often dictates using speech-to-text, so expect:

• Typos and incorrect words
• Imperfect sentence structure
• Homophone substitutions (e.g., "to/too/two", "there/their")
• Missing punctuation or capitalization

Focus on understanding the intent rather than the exact wording. When in doubt, clarify rather than assume.

Project Understanding

Read and understand the MindRoom project structure:

1. Read Core Documentation

   • Full README.md for project purpose and architecture
   • AGENTS.md for development guidelines and workflow

2. Code Structure

   • Main bot: src/mindroom/bot.py
   • Matrix interactions: src/mindroom/matrix/ module
     • matrix/client.py - Core Matrix client functions
     • matrix/mentions.py - Mention handling
     • matrix/message_builder.py - Message construction
     • matrix/identity.py - Matrix ID handling
     • matrix/rooms.py - Room management
     • matrix/state.py - State management
     • matrix/users.py - User management

3. Development Best Practices

   • ALWAYS check for existing helper functions before implementing new ones
   • Look in matrix/ module for Matrix utilities
   • Check thread_utils.py for thread handling
   • Review src/mindroom/commands/parsing.py and src/mindroom/commands/handler.py for command parsing and dispatch patterns
   • Use uv (not conda) for package management
   • Install: uv sync --all-extras
   • Activate: source .venv/bin/activate
   • Add packages: uv add <package> or uv add --dev <package>
   • Critical Git practices:
     • NEVER use git add . - always add files individually
     • Always run pytest before claiming completion
     • Run pre-commit run --all-files before commits
   • Code style:
     • Prefer functional style over classes
     • Use dataclasses over dictionaries
     • Keep it DRY - aggressively remove unused code
     • Don't wrap in try-except unless necessary
     • Keep imports at file top; function imports may avoid cycles or defer heavy/optional dependencies until first use, following AGENTS.md
     • Keep deferred imports explicit (from x import Y) with # noqa: PLC0415 where needed, and preserve the tests/test_import_graph.py contract