Module system: standard framework for autonomous capabilities

[mmx003]

Summary

PR review and issue triage are bolted onto webhook.py as ad-hoc if-branches with hardcoded patterns (cooldown, fire-and-forget, send-message). They run as isolated one-shot claude --print subprocesses with no workspace, no history, and no way for the user or Claude to interact with them. Adding similar capabilities (CI watcher, deploy manager, release manager) means copying patterns and adding more if-branches.

Proposal

Introduce a module system — a standard framework for autonomous programs that live alongside the agent.

A module:

• Does its own work reactively (webhook) or on schedule
• Keeps a journal in its own directory (modules/{name}/events/)
• Has isolated history separate from main chat (history/{chat_id}/{module}/)
• Can notify the user via Telegram (topic per module)
• Can be managed by Claude via HTTP API (/api/modules/{name}/invoke)
• Can ask the user for input via checkpoint/resume pattern (no hanging processes)

Module interface

async def handle(ctx: ModuleContext) -> ModuleResult:
    # Module receives context (trigger data, config, saved state)
    # Returns done (with journal entry), paused (with question), or error

Kai manages the lifecycle: trigger matching, context building, state serialization, resume dispatch, journal writes, notifications.

Key design decisions

• Modules are stateless processes — run, do work, exit. State serialized to disk between runs (serverless-style checkpoint/resume)
• Claude is a helper, not orchestrator — module does the actual work, calls claude --print only when it needs reasoning or to formulate a question
• File-based journal — Claude in the main session reads module journals directly from filesystem
• Registry-based dispatch replaces if-branches — module.yaml manifests declare triggers

User interaction

• Quick queries without context switch: "what happened in pr-review?" (Claude reads events/)
• Deep work via /module pr-review (context switch analogous to /workspace)
• Module questions via pending/ directory + Telegram notification

Migration path

1. Extract pr-review into module with manifest and journal
2. Extract issue-triage the same way
3. Replace if-branches in webhook.py with registry dispatch
4. Add /module command to bot.py
5. Add module summary to Claude session context injection

Full proposal: PROPOSAL-modules.md in repo root

[dcellison]

Triage by Kai

Triage summary: Proposes replacing ad-hoc if-branches in webhook.py with a standardized module system that gives autonomous capabilities (PR review, issue triage, CI watcher, etc.) isolated state, journaling, scheduling, and a checkpoint/resume pattern for user interaction. Well-scoped architectural refactor with a clear migration path.

Priority: medium
Labels applied: enhancement

[dcellison]

@mmx003 I really like this idea. It has been bugging me that I have no visibility into whether the review agent is running or not.

I am first going to complete all of the sub-issues related to #196 and the turn my attention toward this issue. 196 is a current deficiency so I would like to get it resolved before anything else.

[mmx003]

Great news! Happy to help with the implementation when you're ready.