prose-contracts/build-zulip-plugin.prose.md

kind, name, description

kind	name	description
responsibility	build-zulip-plugin	Generates and iteratively improves a Hermes Zulip platform plugin. Each run can produce a new version of the plugin, learning from previous runs and incrementally improving the adapter code. The contract itself can be updated to capture new patterns.

Maintains

• plugin_version: string — Current version of the generated plugin
• generation_count: number — How many generations have been produced
• last_generation: timestamp — When the last generation was created
• known_issues: array — Issues discovered in the current version

Parameters

• zulip_site: string — Zulip server URL (default: "https://chat.sysloggh.net")
• bot_email_prefix: string — Prefix for bot emails (default: "abiba-bot")
• output_dir: string — Where to write the plugin (default: "plugins/platforms/zulip")
• generation_goal: string — What to improve this generation (default: "fix bugs and improve reliability")

Continuity

The improvement cycle is event-driven, not just cron-based:

• On check failure: If any Success Criteria fails, wake immediately to fix
• On user request: prose run build-zulip-plugin — explicit upgrade
• On new pattern: If another plugin or agent reports a better pattern, wake to assimilate
• Retrospective: Every 24 hours if no other trigger fired — scan for subtle degradation
• On first deploy: Always run Generation 1 when no plugin exists yet

Success Criteria (What Makes a Plugin "Good")

The plugin is considered GOOD when ALL of these pass:

Connectivity

• plugin.connected == true — Establishes and maintains Zulip event queue
• plugin.reconnect_on_failure == true — Reconnects after queue expiry
• plugin.recovers_from_network_loss == true — Handles temporary network drops

Message Flow

• dm_response_time_ms < 10000 — DMs get a response within 10 seconds
• stream_mention_detection == true — @mentions in streams are detected and routed
• all_bots_detection == true — @all-bots mentions are detected
• echo_loop_prevention == true — Never replies to its own messages

Code Quality

• syntax_check == "pass" — All Python files are valid
• has_register_function == true — Exposes register(ctx) entry point
• plugin_yaml_valid == true — plugin.yaml parses correctly
• follows_base_adapter_pattern == true — Extends BasePlatformAdapter

Reliability

• graceful_disconnect == true — shutdown doesn't crash
• handles_malformed_messages == true — Bad JSON doesn't kill the poll loop
• typing_indicators_work == true — Sends typing notifications

Remembers

Each generation stores:

• What worked well (success patterns)
• What broke (failure modes)
• What the user complained about (pain points)
• Which Success Criteria passed and failed

Generation Rules

Rule 1: First Generation

• Generate complete plugin.yaml, adapter.py, __init__.py
• Follow Hermes BasePlatformAdapter pattern
• Include: connect, disconnect, send, edit_message, send_typing
• Include: DM-first routing, @mention detection, @all-bots support

Rule 2: Subsequent Generations

• Read the previous generation's output and known issues
• Apply improvements based on generation_goal
• Fix any issues from the previous generation
• Add new capabilities if needed

Rule 3: Testing

• After generating, run syntax check on the Python code
• Verify plugin.yaml is valid YAML
• Log the generation result to knowledge graph

Rule 4: Self-Improvement

• After N generations, review the contract itself
• If new patterns emerged, update the Generation Rules
• If old rules are no longer relevant, remove them

Execution

1. Read state — Check previous generations from knowledge graph
2. Generate or improve — Based on generation count:
   • Generation 1: Scaffold full plugin from scratch
   • Generation N: Read previous code, apply improvements
3. Validate — Syntax check, structure check, dependency check
4. Log — Save generation result to knowledge graph as [LEARN]
5. Report — Output what was generated, what changed, what needs review

Example Output

{
  "generation": 1,
  "version": "1.0.0",
  "files_written": [
    "plugins/platforms/zulip/plugin.yaml",
    "plugins/platforms/zulip/__init__.py",
    "plugins/platforms/zulip/adapter.py"
  ],
  "syntax_check": "pass",
  "known_issues": [],
  "next_generation_goal": "add streaming responses via placeholder->edit pattern"
}