awesome-agv

About Awesome AGV

Awesome AGV provides a comprehensive set 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 agents load on demand.

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

⚠️ Opinionated by design. Awesome AGV ships with opinionated defaults for specific technology stacks. See Opinionated Technology Choices for details and how to customize.

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

• 📏 25 Rules — covering security, reliability, architecture, and maintainability. Distilled to project-specific decisions only — rules encode what overrides model defaults, not what models already know.
• 🛠️ 56 Skills — specialized capabilities loaded on demand: language idioms, debugging, design, testing, performance, CI/CD, and more.
• 🔄 10 Workflows — end-to-end development processes from research to ship, plus specialized testing pipelines.
• 🤖 21 Agent Personas — specialized sub-agents for multi-agent orchestration arranged in a 4-tier hierarchy.
• 🏗️ Three-Tier Loading System — always-on mandates + contextual principles + on-demand skills for zero-noise enforcement.

💡 Everything is modular. Rules, skills, agents, and workflows work independently — you don't need everything to benefit. Use only what you need, modify anything, or build your own. 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 launches an interactive installer where you choose your installation mode:

In Curated and Advanced modes, the installer auto-detects your project's tech stack from files like go.mod, Cargo.toml, tsconfig.json, pubspec.yaml, etc. and pre-selects matching stacks.

CLI Flags:

Examples

# Interactive — choose your mode
npx awesome-agv

# Non-interactive: specific stacks, core always included
npx awesome-agv --stacks go,python

# Add React to existing installation (additive)
npx awesome-agv --stacks react

# Full install, no prompts
npx awesome-agv --all --force

# CI/CD: specific stacks, no prompts
npx awesome-agv --stacks typescript,vue --force

Manual Install:

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

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

2. Ensure your AI agent is configured to read from the .agents directory (most well-known AI coding assistants adhere to the .agents convention by default, no action needed) or manually ingest the .agents/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 three-tier loading system to minimize noise while maximizing coverage:

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

Skill Loading Design

Skills use one of three loading mechanisms, chosen by type:

Design invariant: Cross-cutting skills that apply to all languages (testability, logging) are never loaded via language-specific paths: triggers. They are always referenced from always-on rules so they load regardless of language.

Rule Dependencies

The rules are interconnected to provide comprehensive coverage. You can explore these relationships using the Interactive Rule Dependency Graph, or view the static diagram below.

graph TD
  accessibility_principles["accessibility-principles.md"]
  api_design_principles["api-design-principles.md"]
  architectural_pattern["architectural-pattern.md"]
  code_idioms_and_conventions["code-idioms-and-conventions.md"]
  code_organization_principles["code-organization-principles.md"]
  command_execution_principles["command-execution-principles.md"]
  concurrency_and_threading_principles["concurrency-and-threading-principles.md"]
  configuration_management_principles["configuration-management-principles.md"]
  core_design_principles["core-design-principles.md"]
  data_serialization_and_interchange_principles["data-serialization-and-interchange-principles.md"]
  database_design_principles["database-design-principles.md"]
  dependency_management_principles["dependency-management-principles.md"]
  documentation_principles["documentation-principles.md"]
  error_handling_principles["error-handling-principles.md"]
  git_workflow_principles["git-workflow-principles.md"]
  logging_and_observability_mandate["logging-and-observability-mandate.md"]
  monitoring_and_alerting_principles["monitoring-and-alerting-principles.md"]
  performance_optimization_principles["performance-optimization-principles.md"]
  project_structure["project-structure.md"]
  resources_and_memory_management_principles["resources-and-memory-management-principles.md"]
  rugged_software_constitution["rugged-software-constitution.md"]
  rule_priority["rule-priority.md"]
  security_mandate["security-mandate.md"]
  security_principles["security-principles.md"]
  testing_strategy["testing-strategy.md"]
  accessibility_principles --> core_design_principles
  accessibility_principles --> security_principles
  accessibility_principles --> testing_strategy
  api_design_principles --> data_serialization_and_interchange_principles
  api_design_principles --> error_handling_principles
  api_design_principles --> logging_and_observability_mandate
  api_design_principles --> security_mandate
  api_design_principles --> security_principles
  architectural_pattern --> code_organization_principles
  architectural_pattern --> core_design_principles
  architectural_pattern --> database_design_principles
  architectural_pattern --> project_structure
  architectural_pattern --> testing_strategy
  code_idioms_and_conventions --> rugged_software_constitution
  code_idioms_and_conventions --> core_design_principles
  code_organization_principles --> architectural_pattern
  code_organization_principles --> core_design_principles
  code_organization_principles --> project_structure
  command_execution_principles --> security_mandate
  command_execution_principles --> security_principles
  core_design_principles --> concurrency_and_threading_principles
  core_design_principles --