About Awesome AGV

Awesome AGV provides a comprehensive sets of standards and practices designed to elevate the capabilities of AI coding agents. It provides a suite of strict rules distilled from software engineering best practices that ensure generated code is secure, defensible, and maintainable. It also provides specialized skills that will help throughout software development.

Instead of just generating code that works, the rules and skills ensures agents generate code that survives.

While this configuration is originally designed for Antigravity, it is built on standard markdown-based context protocols that are easily portable to other AI coding tools. As a matter of fact, the original form Technical Constitution was first created for Gemini CLI

You can drop this configuration into the context or custom rule settings of:

• Roo Code
• Claude Code
• Any other agentic tool that supports custom system prompts or context loading.

For example, the principles of the Rugged Software Constitution which is based on Rugged Software Manifesto are universal and will improve the output of any LLM-based coding assistant.

Key Features

• 📏 30 Rules — covering security, reliability, architecture, maintainability, and DevOps.
• 🛠️ 7 Skills — specialized capabilities for debugging, design, code review, and more.
• 🔄 10 Workflows — end-to-end development processes from research to ship.
• 🏗️ Two-Tier Rule System — always-on mandates + contextual principles for zero-noise enforcement.

💡 Everything is modular. Rules and skills work independently — you don't need workflows to benefit from them. Use only what you need, modify anything, or build your own workflows. It's a toolkit, not a framework.

Getting Started

To equip your AI agent with these superpowers, follow these steps.

Prerequisites

• An AI Coding Assistant (Antigravity, Roo Code, Cline, etc.)
• A project where you want to enforce high standards.

Installation

Quick Install (recommended):

npx awesome-agv

This downloads and installs the latest .agent/ directory into your current project. Your AI agent will automatically pick it up — no additional configuration needed.

Options:

| Flag | Description | | -------------- | ---------------------------------------------- | | [target-dir] | Directory to install into (default: ./) | | --force, -f | Overwrite existing .agent/ without prompting | | --help, -h | Show help |

Examples

# Install into current directory
npx awesome-agv

# Install into a specific project
npx awesome-agv ./my-project

# Overwrite existing installation without prompting
npx awesome-agv --force

Manual Install:

1. Clone this repository or copy the .agent folder into the root of your project.

   cp -r /path/to/awesome-agv/.agent ./your-project-root/

2. Ensure your AI agent is configured to read from the .agent directory (most of well-known AI coding assistant are adhering to the .agent convention by default, no action needed) or manually ingest the .agent/rules/** as part of its system prompt.

Usage

Once installed, the rules and skills in this repository become active for your agent.

Rule Architecture

The setup uses a two-tier rule system to minimize noise while maximizing coverage:

| Type | Trigger | Purpose | | -------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Mandates | always_on | Non-negotiable constraints loaded in every session (security, logging, code completion). | | Principles | model_decision | Contextual guidance activated only when working on relevant areas (e.g., database rules activate only when writing queries). |

Conflicts between rules are resolved by Rule Priority — security always wins.

Comprehensive Rule Suite

The power of the setup comes from its extensive collection of rules covering every aspect of software engineering.

🛡️ Security & Integrity

• Rugged Software Constitution: The core philosophy of defensible coding.
• Security Mandate: Non-negotiable security requirements.
• Security Principles: Best practices for secure design.

⚡ Reliability & Performance

• Error Handling Principles: Techniques for robust error management.
• Concurrency & Threading: Safe parallel execution and deadlock prevention.
• Concurrency & Threading Mandate: When to use (and not use) concurrency.
• Performance Optimization: Writing efficient and scalable code.
• Resource Management: Handling memory and system resources responsibly.
• Monitoring & Alerting: Health checks, metrics, and graceful degradation.
• Configuration Management: Environment variables, secrets, and config hierarchy.

🏗️ Architecture & Design

• Core Design Principles: Fundamental software design rules (SOLID, DRY, etc.).
• API Design Principles: Creating clean, intuitive, and versionable APIs.
• Architectural Pattern: Testability-first design with I/O isolation.
• Project Structure: Feature-based organization (the single source of truth for layout).
• Database Design: Schema design, migrations, and query safety.
• Data Serialization: Safe data handling and formats.
• Command Execution: Principles for running system commands securely.
• Avoid Circular Dependencies: Preventing module import cycles.

🧩 Maintainability & Quality

• Code Organization: Structuring projects for readability.
• Code Idioms: Following language-specific best practices.
• Testing Strategy: Ensuring code is verifiable and tested.
• Dependency Management: Managing external libraries safely.
• Documentation Principles: Writing clear and helpful documentation.
• Logging & Observability: Ensuring system visibility.
• Logging & Observability Mandate: All operations must be logged — no exceptions.
• Accessibility Principles: WCAG 2.1 AA compliance for UIs.
• Git Workflow: Conventional commits, branch naming, and PR hygiene.

🔄 DevOps & Operations

• CI/CD Principles: Pipeline design, Docker, and GitHub Actions.
• Code Completion Mandate: Automated quality checks before every delivery.
• Rule Priority: Conflict resolution when rules contradict each other.

Specialized Skills

• Debugging Protocol: Systematic approach to solving errors.
• Frontend Design: Guidelines for creating visually appealing UIs, based on Anthropic Frontend-Design Skills
• Mobile Design: Production-grade mobile interfaces for Flutter and React Native.
• Sequential Thinking: A tool for breaking down complex problems, an adaptation from Sequential Thinking MCP Server
• Code Review: Structured code review protocol against the full rule set.
• Guardrails: Pre-flight checklist and post-implementation self-review.
• ADR (Architecture Decision Records): Document significant architectural decisions with context and trade-offs.

Development Workflows

The setup includes opinionated, end-to-end workflows that chain rules and skills into structured development processes.

🏭 Feature Workflow (/orchestrator)

The primary workflow for building features. Phases execute sequentially — no skipping.

Research → Implement (TDD) → Integrate → E2E (conditional) → Verify → Ship

| Phase | Workflow | Purpose | | ------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | 1. Research | /1-research | Understand context, search docs, create ADRs, uses Qurio default to web search | | 2. Implement | /2-implement | TDD cycle: Red → Green → Refactor | | 3. Integrate | /3-integrate | Integration tests with Testcontainers | | 3.5. E2E | /e2e-test | End-to-end validation with Playwright | | 4. Verify | /4-verify | Full lint, test, and build validation | | 5. Ship | /5-commit | Git commit with conventional format |

🔧 Specialized Workflows

| Workflow | When to Use | | --------------------------------------------- | ---------------------------------------------------- | | /quick-fix | Bug fixes with known root cause (<50 lines) | | /refactor | Safely restructure code while preserving behavior | | /audit | Code review and quality inspection (no new features) |

Directory Structure

.agent/
├── rules/             # 30 rules (mandates + principles)
│   ├── rugged-software-constitution.md
│   ├── security-mandate.md
│   ├── rule-priority.md
│   └── ...            
├── skills/            # 7 specialized skills
│   ├── debugging-protocol/
│   ├── frontend-design/
│   ├── mobile-design/
│   ├── sequential-thinking/
│   ├── code-review/
│   ├── guardrails/
│   └── adr/
└── workflows/         # 10 development workflows
    ├── orchestrator.md
    ├── 1-research.md
    ├── 2-implement.md
    ├── 3-integrate.md
    ├── 4-verify.md
    ├── 5-commit.md
    ├── quick-fix.md
    ├── refactor.md
    ├── audit.md
    └── e2e-test.md

Roadmap

• [x] Include more specialized skills to aid development process (7 skills shipped).
• [x] Add development workflows for structured feature delivery (10 workflows shipped).
• [ ] Add more language-specific security rules (Python, Go, Rust).
• [x] Create a CLI tool for easier installation (npx awesome-agv).
• [ ] Add automated validation scripts to check if an agent is following the constitution.
• [x] Publish comprehensive documentation site (GitHub Pages).

Project Adaptation Guide

This setup supports different project structures:

| Project Type | Adaptation | | ----------------------- | ---------------------------------------------------------------- | | Monorepo (default) | Use as-is | | Single backend | Remove frontend rules/workflows, keep backend paths | | Single frontend | Remove backend rules/workflows, keep frontend paths | | Microservices | Adapt project-structure.md per service, add service mesh rules | | Mobile (Flutter/RN) | Adapt frontend rules, add mobile-specific accessibility/testing |

To adapt: Edit project-structure.md and 4-verify.md to match your project layout.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See the LICENSE file for details.