[#69] docs: create Plugin Design Guide #71

Merged

k9ert merged 1 commit from story-69 into main

2026-02-22 12:04:45 +00:00

doxios commented

2026-02-22 11:56:43 +00:00

Collaborator

Closes #69

Summary

Creates docs/plugin-design-guide.md — the authoritative reference for plugin design patterns and principles.

Acceptance Criteria

Create docs/plugin-design-guide.md
Section 1: PluginMeta Vocabulary (complete table with all current fields)
Section 2: Design Principles (5 principles from issue #59)
Section 3: Patterns Catalog (4 patterns: ToolProvider, Swappable Provider, Extension Point Hook, Capability Aggregation)
Section 4: Anti-Patterns (3 anti-patterns: God Object, Hidden Service Locator, Environment Grab Bag)
Section 5: Reviewer Checklist
All examples reference real files in codebase

Content Overview

PluginMeta Vocabulary: Complete reference table for all fields (capabilities, dependencies, consumes, implements, etc.)
5 Design Principles: Own Your Tools, Declare All Coupling, Open-Closed, Hard vs Soft Deps, No Secret Grabbing
4 Patterns: ToolProvider, Swappable Provider, Extension Point Hook, Capability Aggregation
3 Anti-Patterns: God Object Tool Registry, Hidden Service Locator, Environment Grab Bag
Reviewer Checklist: 15 items for PR review

Referenced Files

All code examples point to real files with line numbers:

cobot/plugins/base.py (PluginMeta definition)
cobot/plugins/knowledge/plugin.py (ToolProvider example)
cobot/plugins/wallet/plugin.py (ToolProvider example)
cobot/plugins/loop/plugin.py (consumes, extension_points examples)

Closes #69 ## Summary Creates `docs/plugin-design-guide.md` — the authoritative reference for plugin design patterns and principles. ## Acceptance Criteria - [x] Create `docs/plugin-design-guide.md` - [x] Section 1: PluginMeta Vocabulary (complete table with all current fields) - [x] Section 2: Design Principles (5 principles from issue #59) - [x] Section 3: Patterns Catalog (4 patterns: ToolProvider, Swappable Provider, Extension Point Hook, Capability Aggregation) - [x] Section 4: Anti-Patterns (3 anti-patterns: God Object, Hidden Service Locator, Environment Grab Bag) - [x] Section 5: Reviewer Checklist - [x] All examples reference real files in codebase ## Content Overview - **PluginMeta Vocabulary**: Complete reference table for all fields (`capabilities`, `dependencies`, `consumes`, `implements`, etc.) - **5 Design Principles**: Own Your Tools, Declare All Coupling, Open-Closed, Hard vs Soft Deps, No Secret Grabbing - **4 Patterns**: ToolProvider, Swappable Provider, Extension Point Hook, Capability Aggregation - **3 Anti-Patterns**: God Object Tool Registry, Hidden Service Locator, Environment Grab Bag - **Reviewer Checklist**: 15 items for PR review ## Referenced Files All code examples point to real files with line numbers: - `cobot/plugins/base.py` (PluginMeta definition) - `cobot/plugins/knowledge/plugin.py` (ToolProvider example) - `cobot/plugins/wallet/plugin.py` (ToolProvider example) - `cobot/plugins/loop/plugin.py` (consumes, extension_points examples)

doxios added 1 commit

2026-02-22 11:56:43 +00:00

[#69 ] docs: create Plugin Design Guide

CI / lint (pull_request) Successful in 9s

Details

CI / test (3.11) (pull_request) Successful in 20s

Details

CI / test (3.12) (pull_request) Successful in 22s

Details

E2E Tests / e2e (pull_request) Successful in 11s

Details

CI / test (3.13) (pull_request) Successful in 23s

Details

CI / build (pull_request) Successful in 6s

Details

d465ee286b

- Add PluginMeta vocabulary reference
- Document 5 design principles
- Catalog 4 proven patterns
- Document 3 anti-patterns to avoid
- Add reviewer checklist