Skip to content

Copilot Engineering Configuration Plan

This document defines production-grade engineering configuration for plugin development with GitHub Copilot, Gemini CLI, and antigravity development mode.

1. Goals

  • Standardize plugin engineering workflow for AI-assisted development.
  • Support dual assistant stack:
  • GitHub Copilot (primary in-editor agent)
  • Gemini CLI (secondary external execution/research lane)
  • Introduce antigravity development mode for safer, reversible, high-velocity iteration.

2. Scope

This plan applies to:

  • Plugin development (actions, filters, pipes, pipelines, tools)
  • Documentation synchronization
  • File generation/delivery workflow in OpenWebUI
  • Streaming/tool-call rendering compatibility

3. Engineering Configuration (Copilot-centered)

3.1 Source of truth

  • Primary standard file: .github/copilot-instructions.md
  • Agent workflow file: .agent/workflows/plugin-development.md
  • Runtime guidance docs:
  • docs/development/plugin-guide.md
  • docs/development/plugin-guide.zh.md

3.2 Required development contract

  • Single-file i18n plugin source.
  • Bilingual README (README.md + README_CN.md).
  • Safe context extraction (_get_user_context, _get_chat_context).
  • Structured event handling (status, notification, execute).
  • No silent failures; logging + user-visible status.

3.3 Tool definition contract (Copilot SDK)

  • Define tool params explicitly with pydantic.BaseModel.
  • Use params_type in tool registration.
  • Preserve defaults by avoiding forced null overrides.
  • Keep tool names normalized and deterministic.

4. Gemini CLI Compatibility Profile

Gemini CLI is treated as a parallel capability channel, not a replacement.

4.1 Usage boundary

  • Use for:
  • rapid drafts
  • secondary reasoning
  • cross-checking migration plans
  • Do not bypass repository conventions or plugin contracts.

4.2 Output normalization

All Gemini CLI outputs must be normalized before merge:

  • Match repository style and naming rules.
  • Preserve OpenWebUI plugin signatures and context methods.
  • Convert speculative outputs into explicit, testable implementation points.

4.3 Conflict policy

When Copilot and Gemini suggestions differ:

  1. Prefer repository standard compliance.
  2. Prefer safer fallback behavior.
  3. Prefer lower integration risk.

5. Antigravity Development Mode

Antigravity mode means high-speed delivery with strict reversibility.

5.1 Core principles

  • Small, isolated edits
  • Deterministic interfaces
  • Multi-level fallback paths
  • Roll-forward and rollback both feasible

5.2 Required patterns

  • Timeout guards on frontend execution calls.
  • Path sandbox validation for all workspace file operations.
  • Dual-channel upload fallback (API first, local/DB fallback).
  • Progressive status reporting for long-running tasks.

6. File Creation & Delivery Standard

6.1 Create files in controlled workspace

  • Write artifacts in current workspace scope.
  • Never use paths outside workspace boundary for deliverables.

6.2 Publish protocol

Use 3-step delivery:

  1. local write
  2. publish from workspace
  3. present /api/v1/files/{id}/content link

6.3 Metadata policy

  • Set skip_rag=true for generated downloadable artifacts where applicable.
  • Keep filename generation deterministic (chat_title -> markdown_title -> user+date).

7. Plugin Development Norms for Multi-Agent Stack

  • Compatible with GitHub Copilot and Gemini CLI under same coding contract.
  • Keep streaming compatible with OpenWebUI native blocks (<think>, <details type="tool_calls">).
  • Escape tool card attributes safely (&quot;) for parser stability.
  • Preserve async non-blocking behavior.

8. Documentation Sync Rule

Any meaningful plugin engineering change must sync:

  1. plugin code
  2. plugin bilingual README
  3. docs plugin detail pages (EN/ZH)
  4. docs plugin indexes (EN/ZH)
  5. root README update badge/date when release is prepared

9. Acceptance Checklist

  • Copilot config and workflow references are valid.
  • Gemini CLI outputs can be merged without violating conventions.
  • Antigravity safety mechanisms are present.
  • File creation and publication flow is reproducible.
  • Streaming/tool-card output format remains OpenWebUI-compatible.