# [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]