moai/.planning/phases/02-bot-core/02-02-PLAN.md

---
phase: 02-bot-core
plan: 02
type: execute
---

<objective>
Implement /help and /status command handlers completing M1 milestone.

Purpose: Get the bot responding to basic commands, proving the infrastructure works end-to-end.
Output: Working /help and /status commands that respond in Telegram.
</objective>

<execution_context>
~/.claude/get-shit-done/workflows/execute-phase.md
~/.claude/get-shit-done/templates/summary.md
~/.claude/get-shit-done/references/checkpoints.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/02-bot-core/02-01-SUMMARY.md (created in previous plan)
@src/moai/bot/main.py
@src/moai/bot/config.py
@src/moai/bot/handlers/__init__.py
@SPEC.md (for command format reference)

**From SPEC.md:**
- /help - Show commands
- /status - Show current project/discussion state

**Tech stack available:**
- python-telegram-bot v21+ with ApplicationBuilder
- Async handlers with Update, ContextTypes

**Constraining decisions:**
- Phase 2-01: Handlers registered via register_handlers() in handlers/__init__.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create commands.py with /help and /start handlers</name>
  <files>src/moai/bot/handlers/commands.py</files>
  <action>
Create commands.py with help_command and start_command handlers:

```python
"""Basic command handlers for MoAI bot."""

from telegram import Update
from telegram.ext import ContextTypes

HELP_TEXT = """
*MoAI - Master of AIs*

Multi-AI collaborative brainstorming platform.

*Project Commands:*
/projects - List all projects
/project new "Name" - Create new project
/project select <id|name> - Switch to project
/project delete <id> - Delete project
/project models claude,gpt - Set models
/project info - Show current project

*Discussion Commands:*
/open <question> - Ask all models (parallel)
/discuss [rounds] - Start discussion (default: 3)
/next - Trigger next round
/stop - Stop current discussion

*Output Commands:*
/consensus - Generate consensus summary
/export - Export project as markdown

*Utility:*
/status - Show current state
/help - Show this message
""".strip()

async def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Handle /start command - welcome message."""
    await update.message.reply_text(
        "Welcome to MoAI! 🤖\n\n"
        "Use /help to see available commands.\n"
        "Use /project new \"Name\" to create your first project."
    )

async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Handle /help command - show available commands."""
    await update.message.reply_text(HELP_TEXT, parse_mode="Markdown")
```

Note: Use Markdown parse_mode for formatting. Keep HELP_TEXT as a module constant for easy updates.
  </action>
  <verify>python -c "from moai.bot.handlers.commands import help_command, start_command; print('Commands module loads')"</verify>
  <done>commands.py has start_command and help_command handlers with proper docstrings</done>
</task>

<task type="auto">
  <name>Task 2: Create status.py with /status handler</name>
  <files>src/moai/bot/handlers/status.py</files>
  <action>
Create status.py with status_command handler:

```python
"""Status command handler for MoAI bot."""

from telegram import Update
from telegram.ext import ContextTypes

async def status_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Handle /status command - show current project/discussion state.

    For now, shows a placeholder since project management isn't implemented yet.
    Will be expanded in Phase 3 to show actual project state.
    """
    # TODO: Phase 3 - Query actual project/discussion state from database
    status_text = (
        "*MoAI Status*\n\n"
        "Bot: ✅ Online\n"
        "Database: ✅ Connected\n\n"
        "_No project selected. Use /project new \"Name\" to create one._"
    )
    await update.message.reply_text(status_text, parse_mode="Markdown")
```

This is a placeholder that will be enhanced in Phase 3 when project CRUD is implemented.
  </action>
  <verify>python -c "from moai.bot.handlers.status import status_command; print('Status module loads')"</verify>
  <done>status.py has status_command handler with placeholder implementation</done>
</task>

<task type="auto">
  <name>Task 3: Register handlers in __init__.py</name>
  <files>src/moai/bot/handlers/__init__.py</files>
  <action>
Update handlers/__init__.py to import and register all command handlers:

```python
"""Telegram command handlers for MoAI bot."""

from telegram.ext import Application, CommandHandler

from moai.bot.handlers.commands import help_command, start_command
from moai.bot.handlers.status import status_command


def register_handlers(app: Application) -> None:
    """Register all command handlers with the application.

    Args:
        app: The telegram Application instance.
    """
    # Basic commands
    app.add_handler(CommandHandler("start", start_command))
    app.add_handler(CommandHandler("help", help_command))

    # Status
    app.add_handler(CommandHandler("status", status_command))
```
  </action>
  <verify>python -c "from moai.bot.handlers import register_handlers; from telegram.ext import ApplicationBuilder; print('Handler registration ready')"</verify>
  <done>register_handlers imports and registers start, help, and status command handlers</done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] `python -c "from moai.bot.handlers.commands import help_command, start_command"` succeeds
- [ ] `python -c "from moai.bot.handlers.status import status_command"` succeeds
- [ ] `python -c "from moai.bot.handlers import register_handlers"` succeeds
- [ ] `ruff check src/moai/bot/` passes
- [ ] All handler files have module and function docstrings
</verification>

<success_criteria>
- All tasks completed
- All verification checks pass
- /start, /help, and /status handlers implemented
- Handlers registered via register_handlers()
- M1 milestone requirements met (bot responds to /help, /status)
</success_criteria>

<output>
After completion, create `.planning/phases/02-bot-core/02-02-SUMMARY.md` using summary template.

Note: Phase 2 complete after this plan. Ready for Phase 3 (Project CRUD).
</output>