awesome-agv 2.0.0 → 3.0.0

package/README.md

@@ -7,7 +7,7 @@
     <br />
     <a href="#getting-started">Getting Started</a>
     ·
-    <a href="#usage">View Rules & Skills</a>
+    <a href="#usage">View Rules &amp; Skills</a>
     ·
     <a href="https://github.com/irahardianto/awesome-agv/issues">Request Feature</a>
     ·
@@ -19,9 +19,9 @@
 <!-- ABOUT THE PROJECT -->
 ## 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.
+**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 ensures agents generate code that **survives**.
+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](#opinionated-technology-choices) for details and how to customize.
 
@@ -37,11 +37,11 @@ For example, the principles of the [Rugged Software Constitution](.agents/rules/
 
 ### Key Features
 
-*   📏 **42 Rules** — covering security, reliability, architecture, maintainability, language idioms, and DevOps.
-*   🛠️ **43 Skills** — specialized capabilities for debugging, design, performance optimization, language idioms, and more.
+*   📏 **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.
+*   🛠️ **57 Skills** — specialized capabilities loaded on demand: language idioms, debugging, design, performance, CI/CD, and more.
 *   🔄 **12 Workflows** — end-to-end development processes from research to ship.
-*   🤖 **15 Agent Personas** — specialized sub-agents for multi-agent orchestration (architect, backend-engineer, security-engineer, etc.).
-*   🏗️ **Two-Tier Rule System** — always-on mandates + contextual principles for zero-noise enforcement.
+*   🤖 **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.
 
@@ -91,7 +91,7 @@ npx awesome-agv --force
     ```sh
     cp -r /path/to/awesome-agv/.agents ./your-project-root/
     ```
-2.  Ensure your AI agent is configured to read from the `.agents` directory (most of well-known AI coding assistant are adhering to the `.agents` convention by default, no action needed) or manually ingest the `.agents/rules/**` as part of its system prompt.
+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 -->
 ## Usage
@@ -100,18 +100,31 @@ Once installed, the rules and skills in this repository become active for your a
 
 ### Rule Architecture
 
-The setup uses a **two-tier rule system** to minimize noise while maximizing coverage:
+The setup uses a **three-tier loading 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). |
+| Tier | Type | Trigger | Purpose |
+| --- | --- | --- | --- |
+| **1** | **Mandates** | `always_on` | Non-negotiable constraints loaded in every session (security, logging, code completion, architecture). |
+| **2** | **Principles** | `model_decision` | Contextual guidance activated only when working on relevant areas (e.g., database rules activate only when writing queries). |
+| **3** | **Skills** | `paths:` or rule reference | Deep expertise loaded on demand — language idioms when touching source files, CI/CD when editing pipelines, testability patterns when architectural rules reference them. |
 
 Conflicts between rules are resolved by [Rule Priority](.agents/rules/rule-priority.md) — security always wins.
 
+### Skill Loading Design
+
+Skills use one of three loading mechanisms, chosen by type:
+
+| Mechanism | When used | Examples |
+| --- | --- | --- |
+| **`paths:` triggers** | Language-specific idiom skills | `go-idioms` loads on `**/*.go`; `vue-idioms` loads on `**/*.vue`, `**/store/**/*.ts` |
+| **`name:` + `description:` only** | Cross-cutting skills loaded via rule reference | `testability-patterns` (referenced from `architectural-pattern.md`); `logging-implementation` (referenced from `logging-and-observability-mandate.md`) |
+| **Both `paths:` + `name:`/`description:`** | Infrastructure/domain skills | `ci-cd` (Dockerfiles, CI configs); `feature-flags` (feature flag files) |
+
+> **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 highly interconnected to provide comprehensive coverage. You can explore these relationships using the **[Interactive Rule Dependency Graph](https://irahardianto.github.io/awesome-agv/rule_dependency_graph.html)**, or view the static diagram below.
+The rules are interconnected to provide comprehensive coverage. You can explore these relationships using the **[Interactive Rule Dependency Graph](https://irahardianto.github.io/awesome-agv/rule_dependency_graph.html)**, or view the static diagram below.
 
 <details>
 <summary>View Dependency Graph (Mermaid)</summary>
@@ -121,12 +134,9 @@ graph TD
   accessibility_principles["accessibility-principles.md"]
   api_design_principles["api-design-principles.md"]
   architectural_pattern["architectural-pattern.md"]
-  ci_cd_principles["ci-cd-principles.md"]
-  code_completion_mandate["code-completion-mandate.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_mandate["concurrency-and-threading-mandate.md"]
   concurrency_and_threading_principles["concurrency-and-threading-principles.md"]
   configuration_management_principles["configuration-management-principles.md"]
   core_design_principles["core-design-principles.md"]
@@ -135,31 +145,17 @@ graph TD
   dependency_management_principles["dependency-management-principles.md"]
   documentation_principles["documentation-principles.md"]
   error_handling_principles["error-handling-principles.md"]
-  flutter_idioms_and_patterns["flutter-idioms-and-patterns.md"]
   git_workflow_principles["git-workflow-principles.md"]
-  go_idioms_and_patterns["go-idioms-and-patterns.md"]
   logging_and_observability_mandate["logging-and-observability-mandate.md"]
-  logging_and_observability_principles["logging-and-observability-principles.md"]
   monitoring_and_alerting_principles["monitoring-and-alerting-principles.md"]
   performance_optimization_principles["performance-optimization-principles.md"]
-  project_structure_flutter_mobile["project-structure-flutter-mobile.md"]
-  project_structure_go_backend["project-structure-go-backend.md"]
-  project_structure_rust_cargo["project-structure-rust-cargo.md"]
-  project_structure_vue_frontend["project-structure-vue-frontend.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"]
-  rust_idioms_and_patterns["rust-idioms-and-patterns.md"]
   security_mandate["security-mandate.md"]
   security_principles["security-principles.md"]
   testing_strategy["testing-strategy.md"]
-  typescript_idioms_and_patterns["typescript-idioms-and-patterns.md"]
-  vue_idioms_and_patterns["vue-idioms-and-patterns.md"]
-  python_idioms_and_patterns["python-idioms-and-patterns.md"]
-  project_structure_python_backend["project-structure-python-backend.md"]
-  feature_flags_principles["feature-flags-principles.md"]
-  ci_cd_gitops_kubernetes["ci-cd-gitops-kubernetes.md"]
   accessibility_principles --> core_design_principles
   accessibility_principles --> security_principles
   accessibility_principles --> testing_strategy
@@ -173,32 +169,15 @@ graph TD
   architectural_pattern --> database_design_principles
   architectural_pattern --> project_structure
   architectural_pattern --> testing_strategy
-  ci_cd_principles --> code_completion_mandate
-  ci_cd_principles --> git_workflow_principles
-  ci_cd_principles --> project_structure
-  ci_cd_principles --> security_mandate
-  ci_cd_principles --> testing_strategy
-  code_completion_mandate --> code_idioms_and_conventions
-  code_completion_mandate --> flutter_idioms_and_patterns
-  code_completion_mandate --> go_idioms_and_patterns
-  code_completion_mandate --> rugged_software_constitution
-  code_completion_mandate --> rust_idioms_and_patterns
-  code_completion_mandate --> typescript_idioms_and_patterns
-  code_completion_mandate --> vue_idioms_and_patterns
-  code_idioms_and_conventions --> code_completion_mandate
+  code_idioms_and_conventions --> rugged_software_constitution
   code_idioms_and_conventions --> core_design_principles
-  code_idioms_and_conventions --> flutter_idioms_and_patterns
-  code_idioms_and_conventions --> go_idioms_and_patterns
-  code_idioms_and_conventions --> rust_idioms_and_patterns
-  code_idioms_and_conventions --> typescript_idioms_and_patterns
-  code_idioms_and_conventions --> vue_idioms_and_patterns
   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
-  concurrency_and_threading_mandate --> concurrency_and_threading_principles
-  concurrency_and_threading_mandate --> performance_optimization_principles
+  core_design_principles --> concurrency_and_threading_principles
+  core_design_principles --> performance_optimization_principles
   concurrency_and_threading_principles --> error_handling_principles
   concurrency_and_threading_principles --> resources_and_memory_management_principles
   concurrency_and_threading_principles --> testing_strategy
@@ -220,254 +199,194 @@ graph TD
   documentation_principles --> code_organization_principles
   documentation_principles --> core_design_principles
   error_handling_principles --> api_design_principles
-  error_handling_principles --> concurrency_and_threading_mandate
+  error_handling_principles --> core_design_principles
   error_handling_principles --> logging_and_observability_mandate
   error_handling_principles --> security_mandate
   error_handling_principles --> security_principles
   error_handling_principles --> testing_strategy
-  flutter_idioms_and_patterns --> architectural_pattern
-  flutter_idioms_and_patterns --> code_idioms_and_conventions
-  flutter_idioms_and_patterns --> dependency_management_principles
-  flutter_idioms_and_patterns --> error_handling_principles
-  flutter_idioms_and_patterns --> project_structure_flutter_mobile
-  flutter_idioms_and_patterns --> testing_strategy
-  git_workflow_principles --> code_completion_mandate
+  git_workflow_principles --> code_idioms_and_conventions
   git_workflow_principles --> security_mandate
   git_workflow_principles --> testing_strategy
-  go_idioms_and_patterns --> code_idioms_and_conventions
-  go_idioms_and_patterns --> concurrency_and_threading_principles
-  go_idioms_and_patterns --> dependency_management_principles
-  go_idioms_and_patterns --> error_handling_principles
-  go_idioms_and_patterns --> logging_and_observability_principles
-  go_idioms_and_patterns --> project_structure_go_backend
-  go_idioms_and_patterns --> testing_strategy
   logging_and_observability_mandate --> api_design_principles
   logging_and_observability_mandate --> error_handling_principles
-  logging_and_observability_mandate --> logging_and_observability_principles
   logging_and_observability_mandate --> monitoring_and_alerting_principles
-  logging_and_observability_principles --> api_design_principles
-  logging_and_observability_principles --> error_handling_principles
-  logging_and_observability_principles --> logging_and_observability_mandate
-  logging_and_observability_principles --> monitoring_and_alerting_principles
-  logging_and_observability_principles --> security_mandate
-  logging_and_observability_principles --> security_principles
-  monitoring_and_alerting_principles --> concurrency_and_threading_principles
   monitoring_and_alerting_principles --> error_handling_principles
   monitoring_and_alerting_principles --> logging_and_observability_mandate
-  monitoring_and_alerting_principles --> logging_and_observability_principles
   monitoring_and_alerting_principles --> resources_and_memory_management_principles
-  performance_optimization_principles --> concurrency_and_threading_mandate
+  performance_optimization_principles --> core_design_principles
   performance_optimization_principles --> concurrency_and_threading_principles
   performance_optimization_principles --> resources_and_memory_management_principles
-  project_structure_flutter_mobile --> flutter_idioms_and_patterns
-  project_structure_flutter_mobile --> project_structure
-  project_structure_go_backend --> go_idioms_and_patterns
-  project_structure_go_backend --> project_structure
-  project_structure_rust_cargo --> project_structure
-  project_structure_rust_cargo --> rust_idioms_and_patterns
-  project_structure_vue_frontend --> project_structure
-  project_structure_vue_frontend --> typescript_idioms_and_patterns
-  project_structure_vue_frontend --> vue_idioms_and_patterns
   project_structure --> architectural_pattern
   project_structure --> code_organization_principles
-  project_structure --> project_structure_flutter_mobile
-  project_structure --> project_structure_go_backend
-  project_structure --> project_structure_rust_cargo
-  project_structure --> project_structure_vue_frontend
-  resources_and_memory_management_principles --> concurrency_and_threading_mandate
+  resources_and_memory_management_principles --> core_design_principles
   resources_and_memory_management_principles --> concurrency_and_threading_principles
   resources_and_memory_management_principles --> error_handling_principles
   rugged_software_constitution --> architectural_pattern
-  rugged_software_constitution --> code_idioms_and_conventions
-  rugged_software_constitution --> core_design_principles
   rugged_software_constitution --> error_handling_principles
   rugged_software_constitution --> logging_and_observability_mandate
-  rugged_software_constitution --> resources_and_memory_management_principles
   rugged_software_constitution --> security_mandate
-  rugged_software_constitution --> testing_strategy
   rule_priority --> architectural_pattern
-  rule_priority --> code_completion_mandate
+  rule_priority --> code_idioms_and_conventions
   rule_priority --> logging_and_observability_mandate
   rule_priority --> rugged_software_constitution
   rule_priority --> security_mandate
-  rust_idioms_and_patterns --> code_idioms_and_conventions
-  rust_idioms_and_patterns --> concurrency_and_threading_mandate
-  rust_idioms_and_patterns --> concurrency_and_threading_principles
-  rust_idioms_and_patterns --> dependency_management_principles
-  rust_idioms_and_patterns --> error_handling_principles
-  rust_idioms_and_patterns --> performance_optimization_principles
-  rust_idioms_and_patterns --> resources_and_memory_management_principles
-  rust_idioms_and_patterns --> security_mandate
-  rust_idioms_and_patterns --> testing_strategy
   security_mandate --> security_principles
   security_principles --> api_design_principles
   security_principles --> command_execution_principles
   security_principles --> configuration_management_principles
   security_principles --> error_handling_principles
   security_principles --> logging_and_observability_mandate
-  security_principles --> logging_and_observability_principles
   testing_strategy --> architectural_pattern
   testing_strategy --> error_handling_principles
   testing_strategy --> project_structure
-  typescript_idioms_and_patterns --> code_idioms_and_conventions
-  typescript_idioms_and_patterns --> concurrency_and_threading_mandate
-  typescript_idioms_and_patterns --> dependency_management_principles
-  typescript_idioms_and_patterns --> error_handling_principles
-  typescript_idioms_and_patterns --> security_principles
-  typescript_idioms_and_patterns --> testing_strategy
-  typescript_idioms_and_patterns --> vue_idioms_and_patterns
-  vue_idioms_and_patterns --> architectural_pattern
-  vue_idioms_and_patterns --> code_idioms_and_conventions
-  vue_idioms_and_patterns --> logging_and_observability_principles
-  vue_idioms_and_patterns --> project_structure_vue_frontend
-  vue_idioms_and_patterns --> testing_strategy
-  vue_idioms_and_patterns --> typescript_idioms_and_patterns
-  python_idioms_and_patterns --> code_idioms_and_conventions
-  python_idioms_and_patterns --> project_structure_python_backend
-  python_idioms_and_patterns --> testing_strategy
-  python_idioms_and_patterns --> error_handling_principles
-  python_idioms_and_patterns --> concurrency_and_threading_mandate
-  python_idioms_and_patterns --> logging_and_observability_principles
-  python_idioms_and_patterns --> security_principles
-  python_idioms_and_patterns --> dependency_management_principles
-  project_structure_python_backend --> project_structure
-  project_structure_python_backend --> python_idioms_and_patterns
-  code_idioms_and_conventions --> python_idioms_and_patterns
-  code_completion_mandate --> python_idioms_and_patterns
 ```
 
 </details>
 
-### 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](.agents/rules/rugged-software-constitution.md)**: The core philosophy of defensible coding.
-*   **[Security Mandate](.agents/rules/security-mandate.md)**: Non-negotiable security requirements.
-*   **[Security Principles](.agents/rules/security-principles.md)**: Best practices for secure design.
-
-#### ⚡ Reliability & Performance
-*   **[Error Handling Principles](.agents/rules/error-handling-principles.md)**: Techniques for robust error management.
-*   **[Concurrency & Threading](.agents/rules/concurrency-and-threading-principles.md)**: Safe parallel execution and deadlock prevention.
-*   **[Concurrency & Threading Mandate](.agents/rules/concurrency-and-threading-mandate.md)**: When to use (and not use) concurrency.
-*   **[Performance Optimization](.agents/rules/performance-optimization-principles.md)**: Writing efficient and scalable code.
-*   **[Resource Management](.agents/rules/resources-and-memory-management-principles.md)**: Handling memory and system resources responsibly.
-*   **[Monitoring & Alerting](.agents/rules/monitoring-and-alerting-principles.md)**: Health checks, metrics, and graceful degradation.
-*   **[Configuration Management](.agents/rules/configuration-management-principles.md)**: Environment variables, secrets, and config hierarchy.
-
-#### 🏗️ Architecture & Design
-*   **[Core Design Principles](.agents/rules/core-design-principles.md)**: Fundamental software design rules (SOLID, DRY, etc.).
-*   **[API Design Principles](.agents/rules/api-design-principles.md)**: Creating clean, intuitive, and versionable APIs.
-*   **[Architectural Pattern](.agents/rules/architectural-pattern.md)**: Testability-first design with I/O isolation.
-*   **[Project Structure](.agents/rules/project-structure.md)**: Feature-based organization (the single source of truth for layout).
-*   **[Project Structure — Go Backend](.agents/rules/project-structure-go-backend.md)**: Go-specific directory layout.
-*   **[Project Structure — Vue Frontend](.agents/rules/project-structure-vue-frontend.md)**: Vue/React frontend layout.
-*   **[Project Structure — Flutter Mobile](.agents/rules/project-structure-flutter-mobile.md)**: Flutter/RN mobile app layout.
-*   **[Project Structure — Rust/Cargo](.agents/rules/project-structure-rust-cargo.md)**: Rust workspace and crate layout.
-*   **[Project Structure — Python Backend](.agents/rules/project-structure-python-backend.md)**: Python service and API layout.
-*   **[Database Design](.agents/rules/database-design-principles.md)**: Schema design, migrations, and query safety.
-*   **[Data Serialization](.agents/rules/data-serialization-and-interchange-principles.md)**: Safe data handling and formats.
-*   **[Command Execution](.agents/rules/command-execution-principles.md)**: Principles for running system commands securely.
-
-#### 🧩 Maintainability & Quality
-*   **[Code Organization](.agents/rules/code-organization-principles.md)**: Structuring projects for readability.
-*   **[Code Idioms](.agents/rules/code-idioms-and-conventions.md)**: Following language-specific best practices.
-*   **[Go Idioms](.agents/rules/go-idioms-and-patterns.md)**: Go-specific patterns, error handling, concurrency, and tooling.
-*   **[TypeScript Idioms](.agents/rules/typescript-idioms-and-patterns.md)**: TypeScript type system, strict mode, async patterns.
-*   **[Vue Idioms](.agents/rules/vue-idioms-and-patterns.md)**: Vue 3 Composition API, Pinia stores, composables.
-*   **[Flutter Idioms](.agents/rules/flutter-idioms-and-patterns.md)**: Flutter/Dart, Riverpod state management, freezed models.
-*   **[Rust Idioms](.agents/rules/rust-idioms-and-patterns.md)**: Ownership, error handling, async with tokio, clippy.
-*   **[Python Idioms](.agents/rules/python-idioms-and-patterns.md)**: Type hints, Protocols, pytest, ruff/mypy tooling.
-*   **[Testing Strategy](.agents/rules/testing-strategy.md)**: Ensuring code is verifiable and tested.
-*   **[Dependency Management](.agents/rules/dependency-management-principles.md)**: Managing external libraries safely.
-*   **[Documentation Principles](.agents/rules/documentation-principles.md)**: Writing clear and helpful documentation.
-*   **[Logging & Observability](.agents/rules/logging-and-observability-principles.md)**: Ensuring system visibility.
-*   **[Logging & Observability Mandate](.agents/rules/logging-and-observability-mandate.md)**: All operations must be logged — no exceptions.
-*   **[Accessibility Principles](.agents/rules/accessibility-principles.md)**: WCAG 2.1 AA compliance for UIs.
-*   **[Git Workflow](.agents/rules/git-workflow-principles.md)**: Conventional commits, branch naming, and PR hygiene.
-
-#### 🔄 DevOps & Operations
-*   **[CI/CD Principles](.agents/rules/ci-cd-principles.md)**: Pipeline design, Docker, and GitHub Actions.
-*   **[CI/CD GitOps Kubernetes](.agents/rules/ci-cd-gitops-kubernetes.md)**: ArgoCD, Kubernetes deployment patterns (PRD-gated).
-*   **[Feature Flags Principles](.agents/rules/feature-flags-principles.md)**: Flag types, lifecycle, and rollout strategies (PRD-gated).
-*   **[Code Completion Mandate](.agents/rules/code-completion-mandate.md)**: Automated quality checks before every delivery.
-*   **[Rule Priority](.agents/rules/rule-priority.md)**: Conflict resolution when rules contradict each other.
-
-### Specialized Skills (43)
+### Comprehensive Rule Suite (25)
+
+The rules encode **project-specific decisions that override model defaults** — not general knowledge the model already knows. Every line of a rule answers: *"What would this model get wrong without this instruction?"*
+
+#### 🔒 Always-On Mandates (10)
+
+Loaded in every session — non-negotiable constraints that fire regardless of what you're working on.
+
+| Rule | What it enforces |
+| --- | --- |
+| **[Rugged Software Constitution](.agents/rules/rugged-software-constitution.md)** | Hostile-environment posture: refuse insecure patterns even if asked, proactively add validation, fail securely |
+| **[Security Mandate](.agents/rules/security-mandate.md)** | Deny by default, trust no input, fail closed — security always wins over convenience |
+| **[Rule Priority](.agents/rules/rule-priority.md)** | Conflict resolution order: Security → Rugged → Completion/Logging → Testability → Idioms → YAGNI |
+| **[Logging & Observability Mandate](.agents/rules/logging-and-observability-mandate.md)** | Every operation entry point must log start/success/failure with correlationId — no exceptions |
+| **[Architectural Pattern](.agents/rules/architectural-pattern.md)** | I/O isolation, pure business logic, dependency inversion — testability-first design |
+| **[Code Idioms & Conventions](.agents/rules/code-idioms-and-conventions.md)** | Language-to-skill routing table + completion workflow: generate → validate → remediate → verify → deliver |
+| **[Code Organization Principles](.agents/rules/code-organization-principles.md)** | Feature-based vertical slices, public API boundaries, no circular dependencies |
+| **[Core Design Principles](.agents/rules/core-design-principles.md)** | Maintainability > UX; Composition > inheritance; Rule of Three for DRY; profile before parallelizing |
+| **[Project Structure](.agents/rules/project-structure.md)** | Single source of truth for directory layout — organize by feature, not by layer |
+| **[Documentation Principles](.agents/rules/documentation-principles.md)** | Code shows WHAT; comments explain WHY; function docs for API contracts |
+
+#### 🎯 Contextual Principles (15)
+
+Activated by the model only when relevant — zero overhead when not applicable.
+
+*   **[Security Principles](.agents/rules/security-principles.md)**: Auth, authorization, input validation, cryptographic operations
+*   **[Error Handling Principles](.agents/rules/error-handling-principles.md)**: Error types, recovery strategies, resource cleanup
+*   **[API Design Principles](.agents/rules/api-design-principles.md)**: REST/HTTP endpoints, handlers, response formatting
+*   **[Database Design Principles](.agents/rules/database-design-principles.md)**: Schemas, migrations, queries, transaction boundaries
+*   **[Testing Strategy](.agents/rules/testing-strategy.md)**: Pyramid ratios, naming, co-location, test doubles
+*   **[Concurrency & Threading Principles](.agents/rules/concurrency-and-threading-principles.md)**: Race prevention, deadlock avoidance, message passing
+*   **[Performance Optimization Principles](.agents/rules/performance-optimization-principles.md)**: Profile-first, bottleneck identification
+*   **[Configuration Management Principles](.agents/rules/configuration-management-principles.md)**: Environment variables, secrets, settings hierarchy
+*   **[Monitoring & Alerting Principles](.agents/rules/monitoring-and-alerting-principles.md)**: Health checks, metrics, SLIs/SLOs
+*   **[Resource Management Principles](.agents/rules/resources-and-memory-management-principles.md)**: Files, connections, locks — always clean up
+*   **[Data Serialization Principles](.agents/rules/data-serialization-and-interchange-principles.md)**: JSON, Protobuf, validation at boundaries
+*   **[Dependency Management Principles](.agents/rules/dependency-management-principles.md)**: Packages, pinning, license compliance
+*   **[Command Execution Principles](.agents/rules/command-execution-principles.md)**: Shell commands, injection prevention, non-interactive flags
+*   **[Accessibility Principles](.agents/rules/accessibility-principles.md)**: WCAG 2.1 AA, semantic HTML, keyboard navigation
+*   **[Git Workflow Principles](.agents/rules/git-workflow-principles.md)**: Conventional commits, branch naming, PR hygiene
+
+### Specialized Skills (57)
+
+Skills are deep expertise modules loaded on demand — agents only pay the token cost when the skill is relevant.
 
 #### 🔧 Core Engineering Skills
-*   **[Debugging Protocol](.agents/skills/debugging-protocol/SKILL.md)**: Systematic approach to solving errors.
-*   **[Sequential Thinking](.agents/skills/sequential-thinking/SKILL.md)**: A tool for breaking down complex problems, an adaptation from [Sequential Thinking MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)
-*   **[Code Review](.agents/skills/code-review/SKILL.md)**: Structured code review protocol against the full rule set.
-*   **[Guardrails](.agents/skills/guardrails/SKILL.md)**: Pre-flight checklist and post-implementation self-review.
-*   **[ADR (Architecture Decision Records)](.agents/skills/adr/SKILL.md)**: Document significant architectural decisions with context and trade-offs.
-*   **[Performance Optimization](.agents/skills/perf-optimization/SKILL.md)**: Profile-driven optimization with Go pprof, frontend Lighthouse, and bundle analysis tooling.
-*   **[Refactoring Patterns](.agents/skills/refactoring-patterns/SKILL.md)**: Code smell taxonomy, safe transformation techniques, and metrics tracking.
-*   **[Research Methodology](.agents/skills/research-methodology/SKILL.md)**: Structured research protocol for investigating technologies and patterns.
-*   **[Omni](.agents/skills/omni/SKILL.md)**: Token-efficient communication protocol — opt-in for concise output or agent-to-agent messaging.
+*   **[Debugging Protocol](.agents/skills/debugging-protocol/SKILL.md)**: Systematic hypothesis-driven approach to solving errors
+*   **[Sequential Thinking](.agents/skills/sequential-thinking/SKILL.md)**: Dynamic, reflective problem-solving through iterative thought chains, adapted from [Sequential Thinking MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)
+*   **[Code Review](.agents/skills/code-review/SKILL.md)**: Structured code review protocol against the full rule set
+*   **[Guardrails](.agents/skills/guardrails/SKILL.md)**: Pre-flight checklist and post-implementation self-review
+*   **[ADR](.agents/skills/adr/SKILL.md)**: Architecture Decision Records — document significant decisions with context and trade-offs
+*   **[Performance Optimization](.agents/skills/perf-optimization/SKILL.md)**: Profile-driven optimization (pprof, Lighthouse, bundle analysis)
+*   **[Refactoring Patterns](.agents/skills/refactoring-patterns/SKILL.md)**: Code smell taxonomy, safe transformation techniques, behavior preservation
+*   **[Research Methodology](.agents/skills/research-methodology/SKILL.md)**: Structured research protocol for technologies and patterns
+*   **[Omni](.agents/skills/omni/SKILL.md)**: Token-efficient communication protocol — opt-in for concise output or agent-to-agent messaging
+
+#### 🏛️ Architecture & Infrastructure Skills
+*   **[Testability Patterns](.agents/skills/testability-patterns/SKILL.md)**: I/O isolation, pure logic, dependency direction — code examples across Go, TypeScript, Python, Rust, Dart. *Loaded via reference from `architectural-pattern.md`.*
+*   **[Logging Implementation](.agents/skills/logging-implementation/SKILL.md)**: Structured logging patterns, log levels, per-language libraries (Go slog, pino, structlog), PII scrubbing. *Loaded via reference from `logging-and-observability-mandate.md`.*
+*   **[CI/CD](.agents/skills/ci-cd/SKILL.md)**: Pipeline design, multi-stage Docker builds, image scanning, SBOM attestation, environment promotion (Level 0–2)
+*   **[CI/CD GitOps & Kubernetes](.agents/skills/ci-cd/references/gitops-kubernetes.md)**: ArgoCD, Kubernetes deployment patterns — bundled with `ci-cd`
+*   **[Feature Flags](.agents/skills/feature-flags/SKILL.md)**: Release flags, kill switches, experiment flags, lifecycle rules — PRD-gated, loaded only when required
 
 #### 🎨 Design & UI Skills
-*   **[Frontend Design](.agents/skills/frontend-design/SKILL.md)**: Guidelines for creating visually appealing UIs, based on [Anthropic Frontend-Design Skills](https://github.com/anthropics/skills/tree/main/skills/frontend-design)
-*   **[Mobile Design](.agents/skills/mobile-design/SKILL.md)**: Production-grade mobile interfaces for Flutter and React Native.
+*   **[Frontend Design](.agents/skills/frontend-design/SKILL.md)**: Production-grade frontend interfaces, bold aesthetics, typography, motion
+*   **[Mobile Design](.agents/skills/mobile-design/SKILL.md)**: Platform-native mobile interfaces for Flutter and React Native
 
 #### 🔀 Multi-Agent Orchestration Skills
-*   **[Parallel Dispatch Decomposition](.agents/skills/parallel-dispatch-decomposition/SKILL.md)**: MECE task decomposition into scope cards for parallel sub-agent execution.
-*   **[Parallel Dispatch DAG](.agents/skills/parallel-dispatch-dag/SKILL.md)**: Directed acyclic graph construction and topological sort for safe dispatch ordering.
-*   **[Parallel Dispatch Ownership](.agents/skills/parallel-dispatch-ownership/SKILL.md)**: MECE file boundary enforcement to prevent merge conflicts between parallel agents.
-*   **[Parallel Dispatch Merge](.agents/skills/parallel-dispatch-merge/SKILL.md)**: Sequential merge protocol with quality gates for integrating parallel worktree branches.
+*   **[Convergence Loop](.agents/skills/convergence-loop/SKILL.md)**: Iterative problem solving protocol for coordinators.
+*   **[Fault Recovery](.agents/skills/fault-recovery/SKILL.md)**: Structured fault tolerance and escalation ladder.
+*   **[Integrity Enforcement](.agents/skills/integrity-enforcement/SKILL.md)**: Zero-tolerance compliance checking for the arbiter agent.
+*   **[Parallel Dispatch](.agents/skills/parallel-dispatch/SKILL.md)**: MECE task decomposition, file ownership enforcement, DAG-based execution, and safe merge protocol for intra-domain parallel dispatch. The safety invariants that prevent merge chaos when multiple agents write in parallel. Applies recursively at every nesting depth.
+*   **[Scope Decomposition](.agents/skills/scope-decomposition/SKILL.md)**: Project and mission decomposition techniques.
+*   **[Audit Checklist](.agents/skills/audit-checklist/SKILL.md)**: Consolidated audit checklists for code review and verification — loaded by `/audit` workflow and multi-agent review pipelines.
+*   **[Acceptance Review](.agents/skills/acceptance-review/SKILL.md)**: Spec adherence and deliverable completeness verification — ensures what was delivered matches what was requested.
 
-#### 🌐 Language & Framework Idioms (18)
+#### 🌐 Language & Framework Idioms (24)
+
+Language-specific patterns, tooling, project layout, and quality commands. Each skill auto-loads via `paths:` triggers when the agent touches files in that language.
+
+**Core stacks (with bundled project structure references):**
+
+| Skill | Ecosystem | Auto-loads on |
+|---|---|---|
+| [Go Idioms](.agents/skills/go-idioms/SKILL.md) + [layout](./agents/skills/go-idioms/references/project-structure.md) | Go stdlib, error wrapping, table-driven tests, gofumpt | `**/*.go`, `**/go.mod` |
+| [TypeScript Idioms](.agents/skills/typescript-idioms/SKILL.md) + [layout](.agents/skills/typescript-idioms/references/project-structure.md) | Strict mode, type narrowing, Zod, vitest | `**/*.ts`, `**/*.tsx` |
+| [Vue Idioms](.agents/skills/vue-idioms/SKILL.md) + [layout](.agents/skills/vue-idioms/references/project-structure.md) | Vue 3 Composition API, Pinia (Setup Store), composables | `**/*.vue`, `**/store/**/*.ts`, `**/*.store.ts` |
+| [Flutter Idioms](.agents/skills/flutter-idioms/SKILL.md) + [layout](.agents/skills/flutter-idioms/references/project-structure.md) | Riverpod 3, freezed, go_router, const widgets | `**/*.dart`, `**/pubspec.yaml`, `**/analysis_options.yaml` |
+| [Rust Idioms](.agents/skills/rust-idioms/SKILL.md) + [layout](.agents/skills/rust-idioms/references/project-structure.md) | Ownership, tokio, thiserror/anyhow, clippy pedantic | `**/*.rs`, `**/Cargo.toml` |
+| [Python Idioms](.agents/skills/python-idioms/SKILL.md) + [layout](.agents/skills/python-idioms/references/project-structure.md) | Type hints, Protocols, ruff, mypy strict, pytest | `**/*.py`, `**/pyproject.toml` |
 
-Language-specific patterns, tooling, and conventions for ecosystems beyond the core rules:
+**Community language skills:**
 
 | Skill | Ecosystem |
 |---|---|
-| [Angular](.agents/skills/angular-idioms/SKILL.md) | Angular components, DI, RxJS |
-| [C++](.agents/skills/cpp-idioms/SKILL.md) | Modern C++ (RAII, smart pointers) |
-| [C#](.agents/skills/csharp-idioms/SKILL.md) | .NET, async/await, LINQ |
+| [Angular](.agents/skills/angular-idioms/SKILL.md) | Angular components, signals, DI, RxJS |
+| [C++](.agents/skills/cpp-idioms/SKILL.md) | Modern C++ (RAII, smart pointers, CMake) |
+| [C#](.agents/skills/csharp-idioms/SKILL.md) | .NET, async/await, LINQ, records |
 | [Django](.agents/skills/django-idioms/SKILL.md) | Django ORM, views, middleware |
 | [.NET](.agents/skills/dotnet-idioms/SKILL.md) | ASP.NET Core, Entity Framework |
-| [Elixir](.agents/skills/elixir-idioms/SKILL.md) | OTP, GenServer, supervision |
-| [Java](.agents/skills/java-idioms/SKILL.md) | Streams, records, Spring patterns |
-| [JavaScript](.agents/skills/javascript-idioms/SKILL.md) | ES2024+, async patterns |
-| [Kotlin](.agents/skills/kotlin-idioms/SKILL.md) | Coroutines, sealed classes |
+| [Elixir](.agents/skills/elixir-idioms/SKILL.md) | OTP, GenServer, supervision trees |
+| [Java](.agents/skills/java-idioms/SKILL.md) | Streams, records, sealed classes |
+| [JavaScript](.agents/skills/javascript-idioms/SKILL.md) | ES2024+, async patterns, ESM |
+| [Kotlin](.agents/skills/kotlin-idioms/SKILL.md) | Coroutines, sealed classes, Android |
 | [Laravel](.agents/skills/laravel-idioms/SKILL.md) | Eloquent, middleware, queues |
 | [Next.js](.agents/skills/nextjs-idioms/SKILL.md) | App Router, RSC, ISR |
-| [PHP](.agents/skills/php-idioms/SKILL.md) | PHP 8+, type declarations |
-| [Rails](.agents/skills/rails-idioms/SKILL.md) | ActiveRecord, conventions |
+| [PHP](.agents/skills/php-idioms/SKILL.md) | PHP 8+, type declarations, Composer |
+| [Rails](.agents/skills/rails-idioms/SKILL.md) | ActiveRecord, conventions, RSpec |
 | [React](.agents/skills/react-idioms/SKILL.md) | Hooks, Suspense, Server Components |
-| [Ruby](.agents/skills/ruby-idioms/SKILL.md) | Blocks, modules, RSpec |
+| [Ruby](.agents/skills/ruby-idioms/SKILL.md) | Blocks, modules, metaprogramming |
 | [Spring Boot](.agents/skills/spring-boot-idioms/SKILL.md) | Spring DI, JPA, WebFlux |
-| [SQL](.agents/skills/sql-idioms/SKILL.md) | Query optimization, indexes |
+| [SQL](.agents/skills/sql-idioms/SKILL.md) | Query optimization, indexes, migrations |
 | [Swift](.agents/skills/swift-idioms/SKILL.md) | SwiftUI, Combine, async/await |
 
 #### 🏢 Domain Skills
-*   **[API Documentation](.agents/skills/api-documentation/SKILL.md)**: OpenAPI 3.1 specs, request/response examples, versioning.
-*   **[Browser Automation](.agents/skills/browser-automation/SKILL.md)**: Playwright MCP-first automation for E2E testing and UI review.
-*   **[Chaos Testing](.agents/skills/chaos-testing/SKILL.md)**: Controlled failure injection and resilience verification.
-*   **[CLI Development](.agents/skills/cli-development/SKILL.md)**: CLI tool design, argument parsing, and distribution.
-*   **[Data Engineering](.agents/skills/data-engineering/SKILL.md)**: ETL/ELT patterns, data quality, and orchestration.
-*   **[Embedded Systems](.agents/skills/embedded-systems/SKILL.md)**: Real-time patterns, RTOS, and hardware abstraction.
-*   **[Incident Response](.agents/skills/incident-response/SKILL.md)**: Severity classification, triage, diagnosis, and postmortem.
-*   **[ML Engineering](.agents/skills/ml-engineering/SKILL.md)**: ML pipelines, feature engineering, and MLOps.
-*   **[Payment Integration](.agents/skills/payment-integration/SKILL.md)**: PCI DSS compliance, tokenization, and webhook reliability.
-*   **[Supply Chain Security](.agents/skills/supply-chain-security/SKILL.md)**: SBOM generation, CVE scanning, and license compliance.
+*   **[API Documentation](.agents/skills/api-documentation/SKILL.md)**: OpenAPI 3.1 specs, request/response examples, versioning
+*   **[Browser Automation](.agents/skills/browser-automation/SKILL.md)**: Playwright MCP-first automation for E2E testing, UI review, and Playwright MCP interactive development
+*   **[Chaos Testing](.agents/skills/chaos-testing/SKILL.md)**: Controlled failure injection and resilience verification
+*   **[CLI Development](.agents/skills/cli-development/SKILL.md)**: CLI tool design, argument parsing, and distribution
+*   **[Data Engineering](.agents/skills/data-engineering/SKILL.md)**: ETL/ELT patterns, data quality, and orchestration
+*   **[Embedded Systems](.agents/skills/embedded-systems/SKILL.md)**: Real-time patterns, RTOS, and hardware abstraction
+*   **[Incident Response](.agents/skills/incident-response/SKILL.md)**: Severity classification, triage, diagnosis, and blameless postmortem
+*   **[ML Engineering](.agents/skills/ml-engineering/SKILL.md)**: ML pipelines, feature engineering, model serving, and MLOps
+*   **[Payment Integration](.agents/skills/payment-integration/SKILL.md)**: PCI DSS compliance, tokenization, and webhook reliability
+*   **[Supply Chain Security](.agents/skills/supply-chain-security/SKILL.md)**: SBOM generation, CVE scanning, and license compliance
 
-### Agent Personas (15)
+### Agent Personas (21)
 
-Agent personas are specialized sub-agents designed for multi-agent orchestration. Each agent has an exclusive domain, clear boundaries, and never crosses into another agent's territory — enforcing MECE at the architecture level.
+Agent personas are specialized sub-agents designed for multi-agent orchestration. The system uses a Recursive Multi-Agent System (RMAS) with a 4-tier orchestration hierarchy. Each agent has an exclusive domain, clear boundaries, and never crosses into another agent's territory — enforcing MECE at the architecture level.
 
 #### Layers
 
 | Layer | Agents | Purpose |
 |---|---|---|
+| **L1 Strategic** | `overseer` | Program director: aligns multiple domain streams and manages cross-domain dependencies |
+| **L2 Domain** | `rally-lead` | Domain coordinator: orchestrates multiple missions within a business vertical |
+| **L3 Execution** | `mission-lead` | Mission manager: drives a specific feature slice to completion |
+| **Compliance** | `arbiter`, `tech-lead` | Hard gate authorities: independent verification of rules, skills, and specs |
 | **Research** | `scout` | Codebase exploration, pattern discovery, technology research |
-| **Design** | `architect` + optional `ux-reviewer`, `database-expert`, `security-engineer` | System design, ADRs, API contracts |
+| **Design** | `architect` + optional `ux-craftsman`, `database-expert`, `security-engineer` | System design, ADRs, API contracts |
 | **Build** | `backend-engineer`, `frontend-engineer`, `mobile-engineer`, `database-expert`, `devops-engineer`, `technical-writer`, `test-automation-engineer`, `performance-engineer`, `refactoring-specialist` | Implementation with isolated worktrees |
-| **Review** | `qa-analyst`, `security-engineer`, `ux-reviewer`, `incident-responder` | Quality gates, security audits, UX review |
+| **Review** | `qa-analyst`, `security-engineer`, `ux-craftsman`, `incident-responder`, `acceptance-reviewer` | Quality gates, security audits, UX review |
 
-See the [workflow-team](.agents/workflows/workflow-team.md) workflow for the full dispatch protocol, including parallel dispatch with MECE file ownership and DAG-based execution ordering.
+See the [workflow-team](.agents/workflows/workflow-team.md) workflow for the full dispatch protocol, including recursive parallel dispatch with MECE file ownership and DAG-based execution ordering.
 
 ### Development Workflows (12)
 
@@ -498,7 +417,7 @@ The pipeline manager workflow for dispatching specialized sub-agents across laye
 SCOUT → DESIGN → PRE-MORTEM → BUILD (parallel) → REVIEW (parallel) → REMEDIATE → VERIFY
 ```
 
-Includes 12 workflow templates (A-L) for common scenarios: full features, bug fixes, audits, mobile features, security hardening, infrastructure, documentation sprints, incident response, and technical debt.
+Includes 11 workflow templates (A-K) for common scenarios: full features, bug fixes, audits, mobile features, security hardening, infrastructure, documentation sprints, incident response, and technical debt.
 
 #### 🔧 Specialized Workflows
 
@@ -514,27 +433,43 @@ Includes 12 workflow templates (A-L) for common scenarios: full features, bug fi
 
 ```
 .agents/
-├── agents/            # 15 agent personas (multi-agent orchestration)
+├── agents/            # 21 agent personas (multi-agent orchestration)
+│   ├── overseer.md              # L1 Strategic Director
+│   ├── rally-lead.md            # L2 Domain Coordinator
+│   ├── mission-lead.md          # L3 Execution Manager
+│   ├── arbiter.md               # Independent compliance authority
+│   ├── tech-lead.md             # Quality gate authority
 │   ├── architect.md
 │   ├── backend-engineer.md
-│   ├── frontend-engineer.md
-│   ├── scout.md
-│   ├── qa-analyst.md
-│   └── ...            # 10 more specialized agents
-├── rules/             # 42 rules (mandates + principles + language idioms)
-│   ├── rugged-software-constitution.md
-│   ├── security-mandate.md
-│   ├── rule-priority.md
-│   └── ...            
-├── skills/            # 43 specialized skills
-│   ├── debugging-protocol/      # Core engineering
-│   ├── frontend-design/
+│   └── ...            # 14 more specialized agents
+├── rules/             # 25 rules: 10 always-on mandates + 15 contextual principles
+│   │                  # Each rule = project-specific decisions only (not model knowledge)
+│   ├── rugged-software-constitution.md   # always_on: hostile-environment posture
+│   ├── security-mandate.md               # always_on: deny by default
+│   ├── logging-and-observability-mandate.md  # always_on: all ops must log
+│   ├── architectural-pattern.md          # always_on: I/O isolation, testability
+│   ├── rule-priority.md                  # always_on: conflict resolution
+│   └── ...            # 5 more always-on + 15 contextual principles
+├── skills/            # 57 specialized skills — loaded on demand, not always
+│   ├── go-idioms/               # paths: **/*.go — includes references/project-structure.md
+│   ├── typescript-idioms/       # paths: **/*.ts, **/*.tsx
+│   ├── vue-idioms/              # paths: **/*.vue, **/store/**/*.ts, **/*.store.ts
+│   ├── flutter-idioms/          # paths: **/*.dart, **/analysis_options.yaml
+│   ├── rust-idioms/             # paths: **/*.rs, **/Cargo.toml
+│   ├── python-idioms/           # paths: **/*.py, **/pyproject.toml
+│   ├── testability-patterns/    # reference-loaded from architectural-pattern.md
+│   ├── logging-implementation/  # reference-loaded from logging-and-observability-mandate.md
+│   ├── ci-cd/                   # paths: Dockerfile, .github/workflows/*, Jenkinsfile, ...
+│   ├── feature-flags/           # paths: feature*flag*, feature*toggle* (PRD-gated)
+│   ├── debugging-protocol/      # Core engineering (reference-loaded)
 │   ├── code-review/
-│   ├── parallel-dispatch-*/     # Multi-agent orchestration (4 skills)
-│   ├── java-idioms/             # Language & framework idioms (22 skills)
+│   ├── guardrails/
+│   ├── parallel-dispatch/       # Multi-agent orchestration — consolidated safety invariants
+│   ├── angular-idioms/          # Community language skills (18 ecosystems)
 │   ├── react-idioms/
+│   ├── java-idioms/
 │   ├── incident-response/       # Domain skills
-│   └── ...            
+│   └── ...
 └── workflows/         # 12 development workflows
     ├── workflow-solo.md          # Composite: single-agent feature workflow
     ├── workflow-team.md          # Composite: multi-agent pipeline manager
@@ -553,27 +488,29 @@ Includes 12 workflow templates (A-L) for common scenarios: full features, bug fi
 <!-- ROADMAP -->
 ## Roadmap
 
-- [x] Include more specialized skills to aid development process (43 skills shipped).
+- [x] Include more specialized skills to aid development process (53 skills shipped).
 - [x] Add development workflows for structured feature delivery (12 workflows shipped).
-- [x] Add language-specific idiom and pattern rules (Go, TypeScript, Vue, Flutter, Rust, Python + 22 community language skills).
+- [x] Add language-specific idiom skills (Go, TypeScript, Vue, Flutter, Rust, Python + 18 community language skills).
 - [x] Create a CLI tool for easier installation (`npx awesome-agv`).
-- [x] Add multi-agent orchestration with 15 specialized agent personas and parallel dispatch.
+- [x] Add multi-agent orchestration with 16 specialized agent personas (including tech-lead anchor) and consolidated parallel dispatch.
+- [x] Distill rules to decisions-only: strip generic knowledge, keep project-specific overrides (25 rules, -71% from peak).
+- [x] Migrate language idioms from rules to on-demand skills — only load when relevant to the task.
 - [ ] Add automated validation scripts to check if an agent is following the constitution.
 - [x] Publish comprehensive documentation site (GitHub Pages).
 
 ## Opinionated Technology Choices
 
-Awesome AGV ships with **opinionated defaults** for specific technology stacks. Each stack has dedicated idiom files with patterns, tooling, and verification commands.
+Awesome AGV ships with **opinionated defaults** for specific technology stacks. Each stack has a dedicated idiom skill that auto-loads when touching files in that language, providing patterns, tooling, project layout, and quality commands.
 
-| Stack            | Default Choice                                      | Idiom File(s)                                                     |
+| Stack            | Default Choice                                      | Idiom Skill                                                       |
 | ---------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
-| **Backend**      | Go — vanilla stdlib, minimal deps                   | `go-idioms-and-patterns.md`                                       |
-| **Frontend**     | TypeScript + Vue 3 — Composition API, Pinia, Vitest | `typescript-idioms-and-patterns.md`, `vue-idioms-and-patterns.md` |
-| **Mobile**       | Flutter + Riverpod — freezed models, go_router      | `flutter-idioms-and-patterns.md`                                  |
-| **Systems**      | Rust — tokio, thiserror/anyhow, clippy pedantic     | `rust-idioms-and-patterns.md`                                     |
-| **Scripting/AI** | Python — ruff, mypy strict, pytest, Pydantic        | `python-idioms-and-patterns.md`                                   |
+| **Backend**      | Go — vanilla stdlib, minimal deps                   | [go-idioms](.agents/skills/go-idioms/SKILL.md)                   |
+| **Frontend**     | TypeScript + Vue 3 — Composition API, Pinia, Vitest | [typescript-idioms](.agents/skills/typescript-idioms/SKILL.md) + [vue-idioms](.agents/skills/vue-idioms/SKILL.md) |
+| **Mobile**       | Flutter + Riverpod 3 — freezed models, go_router    | [flutter-idioms](.agents/skills/flutter-idioms/SKILL.md)         |
+| **Systems**      | Rust — tokio, thiserror/anyhow, clippy pedantic     | [rust-idioms](.agents/skills/rust-idioms/SKILL.md)               |
+| **Scripting/AI** | Python — ruff, mypy strict, pytest, Pydantic        | [python-idioms](.agents/skills/python-idioms/SKILL.md)           |
 
-**Using a different framework?** The idiom files are modular — swap or edit them to match your stack. See the [Adapting guide](https://irahardianto.github.io/awesome-agv/adapting) for which files to change.
+**Using a different framework?** The idiom skills are modular — swap or edit them to match your stack. Community language skills are available for Angular, React, Next.js, Spring Boot, Django, Laravel, Rails, and more. See the [Adapting guide](https://irahardianto.github.io/awesome-agv/adapting) for which files to change.
 
 ## Project Adaptation Guide
 
@@ -582,12 +519,12 @@ 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              |
+| **Single backend**      | Remove frontend workflows, keep backend idiom skill              |
+| **Single frontend**     | Remove backend workflows, keep frontend idiom skills             |
 | **Microservices**       | Adapt `project-structure.md` per service, add service mesh rules |
-| **Mobile (Flutter/RN)** | Adapt frontend rules, add mobile-specific accessibility/testing  |
+| **Mobile (Flutter/RN)** | Use flutter-idioms or react-idioms skill                        |
 
-**To adapt:** Edit `project-structure.md`, the relevant idiom file, and `phase-verify.md` to match your project layout.
+**To adapt:** Edit `project-structure.md`, the relevant idiom skill's `references/project-structure.md`, and `phase-verify.md` to match your project layout.
 
 <!-- CONTRIBUTING -->
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awesome-agv",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "1-click installer for Awesome AGV — a rugged, high-quality configuration suite for AI Agents.",
   "bin": {
     "awesome-agv": "./bin/awesome-agv.js"