AI Agent Framework

A Clean, Extensible AI Agent Framework for Project Management and QGIS Plugin Development

This repository contains the core configuration, custom skills, and architectural templates (Vault) used to power AI code assistants (specifically tailored for QGIS/PyQt6 development). By separating the agent framework from the source code, projects remain clean, deterministic, and free of AI-generated noise.

---

Repository Structure

The framework is divided into three core components:

1. rules/ (Behavioral Constraints)

Contains markdown rules (e.g., ponytail.md, AGENTS.md) that enforce strict behavioral guidelines for the AI. These rules dictate coding standards, code boundaries, UI/UX consistency requirements, and workflows.

2. skills/ (Specialized Capabilities)

Contains specific toolsets and standard operating procedures (SOPs) that give the AI agent advanced capabilities, including:

• pyqgis-advanced-debugging: Deep tracking and exception handling in PyQGIS.
• pyqgis-performance-optimization: Vector data and memory optimization.
• pyqt6-clean-architecture: Maintainability patterns and Clean Architecture for PyQt6.
• qgis-plugin-zinc-uxui: Zinc UI/UX minimalist design guidelines.
• qgis-qa-tester-suite: Comprehensive QA, visual auditing, and performance benchmark suites.
• vn-cadastral-standards: Legal standards and workflows for Vietnamese land administration.

3. vault/ (Project Memory & Architecture)

A structured memory system for the AI to track state, features, and architecture without cluttering the main codebase's Git history:

• 00_index.md: Vault index and navigation.
• 01_architecture.md: Generic component architecture template.
• 02_active_bugs.md: Tracking open issues and archive.
• 03_features.md: Tracking feature implementation.
• 04_changelog.md: AI session logs and decision records.

---

Installation & Usage

To integrate this framework into your project:

1. Clone or copy this repository into a hidden directory (e.g., .agents) within your project root.
2. The AI agent will automatically detect the customization roots.
3. Update the vault templates as the project progresses to maintain a clean project memory.

---

Design Principles

• Zero Traces: Keep AI operational logs completely separate from the production software.
• Strict Boundaries: Prevent AI from refactoring architecture without an explicit Vault update.
• High Compatibility: Tested extensively with PyQt6 and QGIS 4.0+.

---

License

This framework is open-sourced under the MIT License.