ss-tools/.ai/standards/plugin_design.md

[DEF:Std:Plugin:Standard]

@TIER: CRITICAL

@PURPOSE: Standards for building and integrating Plugins.

@LAYER: Domain (Plugin)

@INVARIANT: All plugins MUST inherit from PluginBase.

@INVARIANT: All plugins MUST be located in backend/src/plugins/.

1. PLUGIN CONTRACT

Every plugin must implement the following properties and methods:

• id: Unique string (e.g., "my-plugin").
• name: Human-readable name.
• description: Brief purpose.
• version: Semantic version.
• get_schema(): Returns JSON schema for input validation.
• execute(params: Dict[str, Any], context: TaskContext): Core async logic.

2. STRUCTURED LOGGING (TASKCONTEXT)

Plugins MUST use TaskContext for logging to ensure proper source attribution:

• Source Attribution: Use context.logger.with_source("src_name") for specific operations (e.g., "superset_api", "git", "llm").
• Levels:
  • DEBUG: Detailed diagnostics (API responses).
  • INFO: Operational milestones (start/end).
  • WARNING: Recoverable issues.
  • ERROR: Failures stopping execution.
• Progress: Use context.logger.progress("msg", percent=XX) for long-running tasks.

3. BEST PRACTICES

1. Asynchronous Execution: Always use async/await for I/O operations.
2. Schema Validation: Ensure the get_schema() precisely matches the execute() input expectations.
3. Isolation: Plugins should be self-contained and not depend on other plugins directly. Use core services (ConfigManager, TaskManager) via dependency injection or the provided context.

[/DEF:Std:Plugin]