Agent Notes & Decision Governance

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• scripts/verify-admin-catalog.ts
• scripts/verify-consumer-contract.ts
• SECURITY.md
• web/src/App.tsx

Agent Notes and Decision Governance establish the framework for AI agents to interact with the HX-ProxyGroup project. This system ensures that all AI-driven modifications adhere to strict architectural boundaries, security protocols, and documented decision-making processes. It prevents "drift" between the implementation and the agent's understanding of the system through mandatory automated validation gates.

The governance model treats agent "memory" as a filesystem-based artifact rather than internal state. Agents must persist decision records, lessons, and rationales to specific directories under .agents/notes/, ensuring that human developers and future agent sessions can audit and understand past technical choices.

Agent Development Constraints

All AI agents must follow a set of hard rules when modifying the HX-ProxyGroup codebase. These rules prioritize maintainability, security, and the separation of the control plane from the data plane.

Project Boundaries and Stack

Agents must respect the following constraints:

• Control Plane Isolation: HX-ProxyGroup is a management layer; it must not participate in actual proxy traffic forwarding. Data forwarding is handled exclusively by the Mihomo data plane.
• Fixed Technology Stack: Agents must use Go for the backend (standard library prioritized), SQLite with WAL for persistence, and React with TypeScript/Tailwind/shadcn for the frontend.
• Layered Architecture: Agents must maintain the flow: api -> application service -> domain/interface -> repository/dataplane.

Code Governance Rules

Category	Rule
File Size	Single source files should target a maximum of 500 lines.
Concurrency	Every goroutine must have an owner, exit condition, and cancellation path.
Persistence	Database "Desired State" is the source of truth; updates must be atomic.
Security	Secrets (tokens, passwords) must never be logged or committed to the repository.

Sources: AGENTS.md:16-104

Decision Governance (Agent Notes)

Decision Governance uses "Agent Notes" to document non-trivial changes, including behavior shifts, architectural adjustments, and contract modifications.

Note Lifecycle

Agents follow a specific workflow for recording decisions:

1. Proposed: New directions begin in .agents/notes/proposed/{class}/.
2. Implementation: During implementation, the note moves to implemented/{class}/ in the same commit as the code change.
3. Referencing: Code comments or JSDoc must link to the relevant note using the path .agents/notes/<lifecycle>/<class>/<file>.md.
4. Alternatives: Every active note must include an ## Alternatives considered section, including the "do nothing" option.

Lifecycle Flow Diagram

The following diagram illustrates how a decision transitions from a proposal to a permanent implementation record.

Automated Contract Verification

To prevent agents from hallucinating capabilities or calling non-existent endpoints, the project employs automated "gates." These scripts verify that the documentation (SKILL.md), the agent scripts, and the actual Go implementation are synchronized.

Admin Catalog Gate

The verify-admin-catalog.ts script ensures three sides agree:

1. Server: internal/api/capabilities_catalog.go (published endpoints).
2. Skill: .agents/skills/hx-proxy-admin/SKILL.md (what the agent reads).
3. Script: .agents/skills/hx-proxy-admin/scripts/hx-catalog.py (what the agent runs).

If a skill documents an endpoint the server does not serve, or a script hard-codes a path instead of learning it from the catalog at runtime, the gate fails.
Sources: scripts/verify-admin-catalog.ts:2-42

Consumer Integration Gate

The verify-consumer-contract.ts script enforces the public consumer API contract. It ensures that the documentation for external consumers matches the server's rendering logic and the agent skills.

Security Governance

Agents are prohibited from modifying security-critical configurations that would expose the system to the public internet by default.

• Bind Restrictions: Management APIs and the Mihomo External Controller must bind to loopback addresses. Public exposure requires explicit configuration.
• Authentication Requirements: Public proxy listeners that bypass Cloudflare/WAF must use mandatory authentication and firewall restrictions.
• Terminal Access: The browser terminal requires a multi-step verification process, including TOTP second factor and same-origin WebSocket checks. Agents must not bypass these requirements when modifying the terminal logic.

Sources: SECURITY.md:13-33, web/src/App.tsx:94-101

Conclusion

Agent Notes and Decision Governance transform AI interactions from black-box modifications into a structured, auditable development process. By enforcing strict architectural boundaries and using automated scripts to verify cross-component contracts, the project maintains high reliability and prevents technical debt caused by agent hallucinations or undocumented changes.