Agent Protocol: A Tool-Agnostic Engineering Workflow Framework for AI Programming Assistants

Agent Protocol is a tool-agnostic engineering methodology framework designed to address the lack of systematic change management in code generation by AI programming assistants (such as Claude Code, Cursor, etc.). Through core mechanisms like four-surface analysis, source-of-truth management, and structured change checklists, it helps AI assistants establish full-lifecycle change management capabilities before, during, and after code writing, improving software engineering quality and efficiency.

With the popularity of AI programming assistants like Claude Code, Cursor, and Gemini CLI, developers have gained powerful code generation tools, but these tools often overlook a core challenge in software engineering—systematic change management. In real projects, AI-generated code tends to have issues such as API contract changes not considering downstream impacts, database schema modifications not syncing with documents/migration scripts, and partial UI adjustments breaking internationalization support. As an open-source project, Agent Protocol is not tied to specific languages, frameworks, or AI tools, and provides general engineering workflow plugins to address this dilemma.

The core design philosophy of Agent Protocol focuses on full-lifecycle change management rather than just code generation. Core principles include: 1. Surface-first analysis: Answer questions like source of truth, affected surfaces/consumers, and verification evidence before making changes; 2. Source-of-truth discipline: Clarify the unique source of truth and ensure it is updated first when changes are made; 3. Evidence-driven delivery: Changes must be accompanied by verifiable evidence (tests, performance benchmarks, etc.). Additionally, it defines a four-surface analysis framework: User Surface (UI, routing, etc.), System Interface Surface (API, Webhook, etc.), Information Surface (database schema, validation rules, etc.), and Operations Surface (logs, documents, etc.) to fully understand the scope of change impacts.

Agent Protocol offers two work modes: Lean mode is suitable for simple, low-risk single-surface changes (e.g., isolated UI fixes), skipping some phases but retaining basic analysis and evidence collection; Full mode is for complex, high-risk cross-surface changes (e.g., core data model refactoring), including eight phases: Initiation, Discovery, Analysis, Specification, Planning, Implementation, Verification, and Observation, each with clear entry criteria and deliverables. Mode selection is automatically determined via decision trees/checklists to balance rigor and efficiency.

Agent Protocol requires non-trivial changes to be accompanied by a structured change checklist in YAML format, including metadata such as affected surfaces, source-of-truth mappings, evidence plans, consumer notifications, and rollback strategies, serving as a standardized contract for AI agent collaboration. Additionally, an innovative runtime hook mechanism is embedded into the AI execution loop: phase gating hooks (check change checklists before submission), evidence existence hooks (verify evidence output), source-of-truth drift hooks (check source-of-truth changes after editing), and completion audit hooks (gatekeeping at the end of the session) to achieve real-time quality control.

Agent Protocol supports multi-agent collaboration, defining three roles: Planning (analysis and design), Implementation (code writing), and Review (verification and gatekeeping). It ensures checks and balances through a permission matrix (e.g., review agents have no write permissions). For cross-platform support, it integrates with mainstream AI tools like Claude Code (plugin), Cursor (rule files), and Gemini CLI (GEMINI.md), and provides bridge documents for tech stacks such as Flutter and Android Kotlin, achieving tool agnosticism and tech stack customization.

The core value of Agent Protocol lies in upgrading AI-assisted programming from code generation to systematic change management, improving engineering standards through mechanisms like four surfaces and source-of-truth discipline. For development teams, it reduces rework and hidden defects, enhancing overall efficiency. As an open-source project, the community can contribute bridge documents, improve hooks, or share experiences to promote the methodology's implementation in more scenarios.