awesome-agv 2.1.0 → 3.1.0

package/README.md

@@ -38,9 +38,9 @@ For example, the principles of the [Rugged Software Constitution](.agents/rules/
 ### 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.
-*   🛠️ **53 Skills** — specialized capabilities loaded on demand: language idioms, debugging, design, performance, CI/CD, and more.
+*   🛠️ **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.
-*   🤖 **16 Agent Personas** — specialized sub-agents for multi-agent orchestration (tech-lead, architect, backend-engineer, security-engineer, etc.).
+*   🤖 **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.
@@ -62,27 +62,42 @@ To equip your AI agent with these superpowers, follow these steps.
 npx awesome-agv
 ```
 
-This downloads and installs the latest `.agents/` directory into your current project. Your AI agent will automatically pick it up — no additional configuration needed.
+This launches an interactive installer where you choose your installation mode:
 
-**Options:**
+| Mode | Description |
+|---|---|
+| 🚀 **Default** | Install everything — the full arsenal (recommended) |
+| 🎯 **Curated** | Pick your languages & frameworks. Core rules and skills always included. |
+| ⚙️ **Advanced** | Full granular control over every component. |
+
+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:**
 
-| Flag           | Description                                    |
-| -------------- | ---------------------------------------------- |
-| `[target-dir]` | Directory to install into (default: `./`)       |
-| `--force, -f`  | Overwrite existing `.agents/` without prompting |
-| `--help, -h`   | Show help                                       |
+| Flag | Description |
+| --- | --- |
+| `--stacks <list>` | Comma-separated stacks to include (**additive** with existing config) |
+| `--all` | Install everything (equivalent to Default mode) |
+| `--force, -f` | Replace existing `.agents/` — re-prompts from scratch |
+| `--help, -h` | Show help |
 
 ### Examples
 
 ```bash
-# Install into current directory
+# Interactive — choose your mode
 npx awesome-agv
 
-# Install into a specific project
-npx awesome-agv ./my-project
+# 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
 
-# Overwrite existing installation without prompting
-npx awesome-agv --force
+# CI/CD: specific stacks, no prompts
+npx awesome-agv --stacks typescript,vue --force
 ```
 
 **Manual Install:**
@@ -284,7 +299,7 @@ Activated by the model only when relevant — zero overhead when not applicable.
 *   **[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 (53)
+### Specialized Skills (57)
 
 Skills are deep expertise modules loaded on demand — agents only pay the token cost when the skill is relevant.
 
@@ -311,7 +326,11 @@ Skills are deep expertise modules loaded on demand — agents only pay the token
 *   **[Mobile Design](.agents/skills/mobile-design/SKILL.md)**: Platform-native mobile interfaces for Flutter and React Native
 
 #### 🔀 Multi-Agent Orchestration Skills
+*   **[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.
 
@@ -365,19 +384,22 @@ Language-specific patterns, tooling, project layout, and quality commands. Each
 *   **[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 (16)
+### 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 |
 |---|---|---|
-| **Orchestration** | `tech-lead` | Anchor persona: elicits requirements, composes primitives, enforces standards, owns all quality gates |
+| **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 recursive parallel dispatch with MECE file ownership and DAG-based execution ordering.
 
@@ -426,14 +448,15 @@ Includes 11 workflow templates (A-K) for common scenarios: full features, bug fi
 
 ```
 .agents/
-├── agents/            # 16 agent personas (multi-agent orchestration)
-│   ├── tech-lead.md             # Orchestration anchor — elicits, composes, gates
+├── 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
+│   └── ...            # 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
@@ -442,7 +465,7 @@ Includes 11 workflow templates (A-K) for common scenarios: full features, bug fi
 │   ├── architectural-pattern.md          # always_on: I/O isolation, testability
 │   ├── rule-priority.md                  # always_on: conflict resolution
 │   └── ...            # 5 more always-on + 15 contextual principles
-├── skills/            # 53 specialized skills — loaded on demand, not always
+├── 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
@@ -480,13 +503,14 @@ Includes 11 workflow templates (A-K) for common scenarios: full features, bug fi
 <!-- ROADMAP -->
 ## Roadmap
 
-- [x] Include more specialized skills to aid development process (53 skills shipped).
+- [x] Include more specialized skills to aid development process (57 skills shipped).
 - [x] Add development workflows for structured feature delivery (12 workflows shipped).
 - [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 16 specialized agent personas (including tech-lead anchor) and consolidated parallel dispatch.
+- [x] Add multi-agent orchestration with 21 specialized agent personas in a 4-tier RMAS hierarchy.
 - [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.
+- [x] Selective CLI installer — 3-tier modes (Default/Curated/Advanced) with auto-detection and manifest-driven extraction.
 - [ ] Add automated validation scripts to check if an agent is following the constitution.
 - [x] Publish comprehensive documentation site (GitHub Pages).
 

package/agv.config.json

@@ -0,0 +1,253 @@
+{
+  "version": "3.1.0",
+  "core": {
+    "paths": ["rules/", "workflows/", "agents/"]
+  },
+  "skills": {
+    "core": [
+      "acceptance-review",
+      "adr",
+      "api-documentation",
+      "audit-checklist",
+      "browser-automation",
+      "chaos-testing",
+      "ci-cd",
+      "cli-development",
+      "code-review",
+      "convergence-loop",
+      "data-engineering",
+      "debugging-protocol",
+      "embedded-systems",
+      "fault-recovery",
+      "feature-flags",
+      "frontend-design",
+      "guardrails",
+      "incident-response",
+      "integrity-enforcement",
+      "logging-implementation",
+      "ml-engineering",
+      "mobile-design",
+      "omni",
+      "parallel-dispatch",
+      "payment-integration",
+      "perf-optimization",
+      "refactoring-patterns",
+      "research-methodology",
+      "scope-decomposition",
+      "sequential-thinking",
+      "supply-chain-security",
+      "testability-patterns",
+      "testing-strategy"
+    ],
+    "stacks": {
+      "go": {
+        "label": "Go",
+        "description": "stdlib, error wrapping, gofumpt",
+        "group": "core",
+        "detect": ["go.mod", "go.sum"],
+        "skills": ["go-idioms"]
+      },
+      "typescript": {
+        "label": "TypeScript",
+        "description": "strict mode, type narrowing, Zod, vitest",
+        "group": "core",
+        "detect": ["tsconfig.json"],
+        "skills": ["typescript-idioms"]
+      },
+      "flutter": {
+        "label": "Flutter",
+        "description": "Riverpod 3, freezed, go_router",
+        "group": "core",
+        "detect": ["pubspec.yaml"],
+        "skills": ["flutter-idioms"]
+      },
+      "rust": {
+        "label": "Rust",
+        "description": "tokio, thiserror/anyhow, clippy pedantic",
+        "group": "core",
+        "detect": ["Cargo.toml"],
+        "skills": ["rust-idioms"]
+      },
+      "python": {
+        "label": "Python",
+        "description": "ruff, mypy strict, pytest, Pydantic",
+        "group": "core",
+        "detect": ["pyproject.toml", "requirements.txt", "setup.py"],
+        "skills": ["python-idioms"]
+      },
+      "vue": {
+        "label": "Vue",
+        "description": "Composition API, Pinia, composables",
+        "group": "core",
+        "requires": ["typescript"],
+        "detect": ["*.vue"],
+        "skills": ["vue-idioms"]
+      },
+      "angular": {
+        "label": "Angular",
+        "description": "components, signals, DI, RxJS",
+        "group": "core",
+        "requires": ["typescript"],
+        "detect": ["angular.json"],
+        "skills": ["angular-idioms"]
+      },
+      "react": {
+        "label": "React",
+        "description": "hooks, Suspense, Server Components",
+        "group": "core",
+        "requires": ["typescript"],
+        "detect": [],
+        "skills": ["react-idioms"]
+      },
+      "nextjs": {
+        "label": "Next.js",
+        "description": "App Router, RSC, ISR",
+        "group": "community",
+        "requires": ["react"],
+        "detect": ["next.config.js", "next.config.mjs", "next.config.ts"],
+        "skills": ["nextjs-idioms"]
+      },
+      "axum": {
+        "label": "Axum",
+        "description": "Rust HTTP routing, extractors, middleware",
+        "group": "community",
+        "requires": ["rust"],
+        "detect": [],
+        "skills": ["axum-idioms"]
+      },
+      "django": {
+        "label": "Django",
+        "description": "ORM, views, middleware",
+        "group": "community",
+        "requires": ["python"],
+        "detect": ["manage.py"],
+        "skills": ["django-idioms"]
+      },
+      "laravel": {
+        "label": "Laravel",
+        "description": "Eloquent, middleware, queues",
+        "group": "community",
+        "requires": ["php"],
+        "detect": ["artisan"],
+        "skills": ["laravel-idioms"]
+      },
+      "rails": {
+        "label": "Rails",
+        "description": "ActiveRecord, conventions, RSpec",
+        "group": "community",
+        "requires": ["ruby"],
+        "detect": ["Rakefile"],
+        "skills": ["rails-idioms"]
+      },
+      "spring-boot": {
+        "label": "Spring Boot",
+        "description": "Spring DI, JPA, WebFlux",
+        "group": "community",
+        "requires": ["java"],
+        "detect": [],
+        "skills": ["spring-boot-idioms"]
+      },
+      "dotnet": {
+        "label": ".NET",
+        "description": "ASP.NET Core, Entity Framework",
+        "group": "community",
+        "requires": ["csharp"],
+        "detect": ["global.json", "*.fsproj"],
+        "skills": ["dotnet-idioms"]
+      },
+      "cpp": {
+        "label": "C++",
+        "description": "modern C++, RAII, smart pointers, CMake",
+        "group": "community",
+        "detect": ["CMakeLists.txt"],
+        "skills": ["cpp-idioms"]
+      },
+      "csharp": {
+        "label": "C#",
+        "description": ".NET, async/await, LINQ, records",
+        "group": "community",
+        "detect": ["*.csproj", "*.sln"],
+        "skills": ["csharp-idioms"]
+      },
+      "elixir": {
+        "label": "Elixir",
+        "description": "OTP, GenServer, supervision trees",
+        "group": "community",
+        "detect": ["mix.exs"],
+        "skills": ["elixir-idioms"]
+      },
+      "java": {
+        "label": "Java",
+        "description": "streams, records, sealed classes",
+        "group": "community",
+        "detect": ["pom.xml", "build.gradle"],
+        "skills": ["java-idioms"]
+      },
+      "javascript": {
+        "label": "JavaScript",
+        "description": "ES2024+, async patterns, ESM",
+        "group": "community",
+        "detect": [],
+        "skills": ["javascript-idioms"]
+      },
+      "kotlin": {
+        "label": "Kotlin",
+        "description": "coroutines, sealed classes, Android",
+        "group": "community",
+        "detect": ["build.gradle.kts"],
+        "skills": ["kotlin-idioms"]
+      },
+      "php": {
+        "label": "PHP",
+        "description": "PHP 8+, type declarations, Composer",
+        "group": "community",
+        "detect": ["composer.json"],
+        "skills": ["php-idioms"]
+      },
+      "ruby": {
+        "label": "Ruby",
+        "description": "blocks, modules, metaprogramming",
+        "group": "community",
+        "detect": ["Gemfile"],
+        "skills": ["ruby-idioms"]
+      },
+      "sql": {
+        "label": "SQL",
+        "description": "query optimization, indexes, migrations",
+        "group": "community",
+        "detect": [],
+        "skills": ["sql-idioms"]
+      },
+      "swift": {
+        "label": "Swift",
+        "description": "SwiftUI, Combine, async/await",
+        "group": "community",
+        "detect": ["Package.swift"],
+        "skills": ["swift-idioms"]
+      }
+    }
+  },
+  "warnings": {
+    "always_on_rules": [
+      "rugged-software-constitution",
+      "security-mandate",
+      "rule-priority",
+      "logging-and-observability-mandate",
+      "architectural-pattern",
+      "code-idioms-and-conventions",
+      "code-organization-principles",
+      "core-design-principles",
+      "project-structure",
+      "documentation-principles"
+    ],
+    "rmas_critical_skills": [
+      "convergence-loop",
+      "fault-recovery",
+      "integrity-enforcement",
+      "parallel-dispatch",
+      "scope-decomposition",
+      "audit-checklist",
+      "acceptance-review"
+    ]
+  }
+}