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

phase	plan	type
02-bot-core	02	execute

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.

<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>

@.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

Task 1: Create commands.py with /help and /start handlers src/moai/bot/handlers/commands.py Create commands.py with help_command and start_command handlers:

"""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. python -c "from moai.bot.handlers.commands import help_command, start_command; print('Commands module loads')" commands.py has start_command and help_command handlers with proper docstrings

Task 2: Create status.py with /status handler src/moai/bot/handlers/status.py Create status.py with status_command handler:

"""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. python -c "from moai.bot.handlers.status import status_command; print('Status module loads')" status.py has status_command handler with placeholder implementation

Task 3: Register handlers in __init__.py src/moai/bot/handlers/__init__.py Update handlers/__init__.py to import and register all command handlers:

"""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))

python -c "from moai.bot.handlers import register_handlers; from telegram.ext import ApplicationBuilder; print('Handler registration ready')" register_handlers imports and registers start, help, and status command handlers 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

<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>

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).