antigravity-ai-kit 2.1.0 → 3.0.1

package/README.md

@@ -1,11 +1,13 @@
 # 🚀 Antigravity AI Kit
 
-![version](https://img.shields.io/badge/version-2.1.0-blue)
+![version](https://img.shields.io/badge/version-3.0.0-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 ![AI Agents](https://img.shields.io/badge/AI%20Agents-19-purple)
-![Skills](https://img.shields.io/badge/Skills-27-orange)
+![Skills](https://img.shields.io/badge/Skills-31-orange)
 ![Commands](https://img.shields.io/badge/Commands-31-red)
-![Workflows](https://img.shields.io/badge/Workflows-11-teal)
+![Workflows](https://img.shields.io/badge/Workflows-14-teal)
+![Runtime Modules](https://img.shields.io/badge/Runtime%20Modules-21-blueviolet)
+![Tests](https://img.shields.io/badge/Tests-261%20passing-brightgreen)
 ![Checklists](https://img.shields.io/badge/Checklists-3-yellow)
 
 <p align="center">
@@ -13,16 +15,17 @@
 </p>
 
 <p align="center">
-  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> that brings <b>19 specialized agents</b>, <b>31 commands</b>, <b>27 skills</b>, and <b>11 workflows</b> to help you code 10x faster with governance-first principles.
+  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> with a <b>21-module runtime engine</b>, <b>19 specialized agents</b>, <b>31 commands</b>, <b>31 skills</b>, and <b>14 workflows</b> — all backed by <b>261 tests</b> and governance-first principles.
 </p>
 
 <p align="center">
   🚀 <a href="#-quick-start">Quick Start</a> •
-  🤖 <a href="#-agents-17">Agents</a> •
-  🛠️ <a href="#%EF%B8%8F-skills-26">Skills</a> •
+  🤖 <a href="#-agents-19">Agents</a> •
+  🛠️ <a href="#%EF%B8%8F-skills-31">Skills</a> •
   ⌨️ <a href="#%EF%B8%8F-commands-31">Commands</a> •
   🔄 <a href="#-session-management">Sessions</a> •
-  ⚖️ <a href="#%EF%B8%8F-operating-constraints">Governance</a>
+  ⚖️ <a href="#%EF%B8%8F-operating-constraints">Governance</a> •
+  📖 <a href="#-contributor-guide">Contributor Guide</a>
 </p>
 
 ---
@@ -33,14 +36,16 @@
 - [Key Features](#-key-features)
 - [Quick Start](#-quick-start)
 - [Architecture](#%EF%B8%8F-architecture-overview)
-- [Agents](#-agents-17)
+- [Agents](#-agents-19)
 - [Commands](#%EF%B8%8F-commands-31)
-- [Skills](#%EF%B8%8F-skills-26)
-- [Workflows](#-workflows-11)
+- [Skills](#%EF%B8%8F-skills-31)
+- [Runtime Engine](#%EF%B8%8F-runtime-engine-21-modules)
+- [Workflows](#-workflows-14)
 - [Operating Constraints](#%EF%B8%8F-operating-constraints)
 - [Session Management](#-session-management)
 - [How to Extend](#-how-to-extend)
-- [Contributing](#-contributing)
+- [Contributor Guide](#-contributor-guide)
+- [Acknowledgments](#-acknowledgments)
 
 ---
 
@@ -51,19 +56,22 @@
 | Feature           | Count | Description                                                            |
 | :---------------- | :---- | :--------------------------------------------------------------------- |
 | 🤖 **AI Agents**  | 19    | Specialized roles (Mobile, DevOps, Database, Security, Performance...) |
-| 🛠️ **Skills**     | 27    | Domain knowledge modules (API, Testing, Architecture, Docker...)       |
+| 🛠️ **Skills**     | 31    | Domain knowledge modules (API, Testing, MCP, Architecture, Docker...) |
 | ⌨️ **Commands**   | 31    | Slash commands for every development workflow                          |
-| 🔄 **Workflows**  | 11    | Process templates (/create, /debug, /deploy, /test...)                 |
+| 🔄 **Workflows**  | 14    | Process templates (/create, /debug, /deploy, /test...)                 |
+| ⚙️ **Runtime**    | 21    | Runtime engine modules (governance, reputation, self-healing...)       |
 | ✅ **Checklists** | 3     | Quality gates (session-start, session-end, pre-commit)                 |
 | ⚖️ **Rules**      | 5     | Immutable governance constraints                                       |
-| 🔗 **Hooks**      | 4     | Event-driven automation                                                |
+| 🔗 **Hooks**      | 6     | Event-driven automation (runtime + git-hook enforcement)               |
+| 🧪 **Tests**      | 261   | Unit, structural, and security tests (25 test files)                   |
 
 ---
 
 ## ✨ Key Features
 
 - **🔒 Trust-Grade Governance**: `/explore → /plan → /work → /review` — Each iteration builds context
-- **🤖 Multi-Agent System**: 17 specialized agents that collaborate (Mobile Developer, DevOps, Database Architect...)
+- **🤖 Multi-Agent System**: 19 specialized agents that collaborate (Mobile Developer, DevOps, Database Architect, Sprint Orchestrator...)
+- **⚙️ Runtime Engine**: 21 modules enforcing workflow transitions, task governance, agent reputation, self-healing, and marketplace
 - **📦 Context as Artifact**: Persistent markdown files for plans, specs, and decisions
 - **🔄 Continuous Learning**: PAAL cycle extracts patterns from every session
 - **🛡️ Security First**: Built-in secret detection, vulnerability scanning, and compliance checks
@@ -76,7 +84,17 @@
 
 ## ⚡ Quick Start
 
-### Option 1: NPX (Recommended)
+### Option 1: Create New Project (Recommended)
+
+```bash
+npx create-antigravity-app my-project
+npx create-antigravity-app my-api --template node-api
+npx create-antigravity-app my-app --template nextjs
+```
+
+Creates a new project with `.agent/` pre-configured. Templates: `minimal`, `node-api`, `nextjs`.
+
+### Option 2: Add to Existing Project
 
 ```bash
 npx antigravity-ai-kit init
@@ -84,7 +102,7 @@ npx antigravity-ai-kit init
 
 This automatically copies the `.agent/` folder to your project.
 
-### Option 2: Manual Installation
+### Option 3: Manual Installation
 
 ```bash
 # 1. Clone the repository
@@ -97,56 +115,84 @@ cp -r antigravity-ai-kit/.agent/ your-project/.agent/
 /status
 ```
 
-### Option 3: Direct Download
+That's it! The kit is now active and ready to accelerate your development.
 
-1. Download the `.agent/` folder from this repository
-2. Place it in your project root
-3. Run `/status` in your AI-powered IDE
+### ✅ Verify Installation
 
-That's it! The kit is now active and ready to accelerate your development.
+```bash
+ag-kit verify     # Manifest integrity check
+ag-kit scan       # Security scan
+```
 
 ---
 
 ## 🏗️ Architecture Overview
 
+```mermaid
+graph TB
+    subgraph "User Interface Layer"
+        CMD["Slash Commands<br/>31 commands"]
+        WF["Workflows<br/>14 templates"]
+    end
+
+    subgraph "Intelligence Layer"
+        IR[Intelligent Router]
+        WS[Workflow State Machine]
+        CB[Context Budget Engine]
+        LR[Loading Rules]
+    end
+
+    subgraph "Agent Layer"
+        CORE["Core Agents<br/>Planner, Architect, Reviewer"]
+        DOMAIN["Domain Agents<br/>Mobile, Frontend, Backend, DB, DevOps"]
+        SUPPORT["Support Agents<br/>Security, Perf, Docs, Explorer"]
+        AUTO["Autonomy Agents<br/>Sprint Orchestrator, Reliability Engineer"]
+    end
+
+    subgraph "Skill Layer"
+        ORCH["Orchestration Skills<br/>Routing, Parallel, Modes"]
+        OPER["Operational Skills<br/>Verification, Learning, Budget"]
+        DOM["Domain Skills<br/>API, Arch, Testing, Security, MCP"]
+    end
+
+    subgraph "Governance Layer"
+        RULES["rules.md<br/>Immutable Constraints"]
+        HOOKS["hooks.json<br/>6 Event Hooks"]
+        MANIFEST["manifest.json<br/>Integrity Verification"]
+    end
+
+    CMD --> IR
+    WF --> WS
+    IR --> CORE & DOMAIN & SUPPORT & AUTO
+    WS --> IR
+    CB --> LR
+    LR --> IR
+    CORE & DOMAIN & SUPPORT & AUTO --> ORCH & OPER & DOM
+    ORCH & OPER & DOM --> RULES & HOOKS & MANIFEST
 ```
-┌─────────────────────────────────────────────────────────────────────┐
-│                      ANTIGRAVITY AI KIT v2.0.0                       │
-├─────────────────────────────────────────────────────────────────────┤
-│                                                                      │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐      │
-│  │   17 AGENTS     │  │   31 COMMANDS   │  │   26 SKILLS     │      │
-│  │                 │  │                 │  │                 │      │
-│  │ • Architect     │  │ • /plan         │  │ • api-patterns  │      │
-│  │ • Mobile Dev    │  │ • /implement    │  │ • architecture  │      │
-│  │ • DevOps        │  │ • /verify       │  │ • clean-code    │      │
-│  │ • DB Architect  │  │ • /deploy       │  │ • testing       │      │
-│  │ • Security      │  │ • /debug        │  │ • docker        │      │
-│  │ • + 12 more     │  │ • + 26 more     │  │ • + 21 more     │      │
-│  └─────────────────┘  └─────────────────┘  └─────────────────┘      │
-│                              │                                       │
-│           ┌──────────────────┴──────────────────┐                   │
-│           ▼                                      ▼                   │
-│  ┌─────────────────────────────────────────────────────────┐        │
-│  │                    11 WORKFLOWS                          │        │
-│  │  /brainstorm • /create • /debug • /deploy • /enhance    │        │
-│  │  /orchestrate • /plan • /preview • /test • /status      │        │
-│  │  /ui-ux-pro-max                                          │        │
-│  └─────────────────────────────────────────────────────────┘        │
-│                              │                                       │
-│           ┌──────────────────┴──────────────────┐                   │
-│           ▼                                      ▼                   │
-│  ┌─────────────────┐                   ┌─────────────────┐          │
-│  │     RULES       │                   │     HOOKS       │          │
-│  │  (Governance)   │                   │  (Automation)   │          │
-│  └─────────────────┘                   └─────────────────┘          │
-│                                                                      │
-└─────────────────────────────────────────────────────────────────────┘
+
+### How It Works: The Autonomy Engine
+
+Antigravity AI Kit uses a **6-phase workflow state machine** that guides development:
+
+```
+EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 ```
 
+| Phase | What Happens | Transition Guard |
+|:------|:-------------|:-----------------|
+| **EXPLORE** | Codebase discovery, research | Exploration artifact exists |
+| **PLAN** | Implementation plan with user approval | Plan approved by user |
+| **IMPLEMENT** | Code generation with agent routing | Auto on commit |
+| **VERIFY** | Quality gates, tests, lint | All gates pass |
+| **REVIEW** | Code review (human or Copilot) | Review approved |
+| **DEPLOY** | Production deployment | Deployment checklist complete |
+
+**Intelligent Routing**: The kit analyzes your request keywords and automatically loads the right agents and skills (max 4 agents + 6 skills per session to stay within context budgets).
+
 ---
 
-## 🤖 Agents (17)
+## 🤖 Agents (19)
 
 ### Core Development
 
@@ -168,17 +214,23 @@ That's it! The kit is now active and ready to accelerate your development.
 | **Security Auditor**     | Vulnerabilities, compliance   | security, auth, audit        |
 | **Performance Engineer** | Optimization, profiling       | performance, speed, metrics  |
 
-### Support
+### Support & Intelligence
 
 | Agent                    | Role                       | Triggers              |
 | :----------------------- | :------------------------- | :-------------------- |
 | **Documentation Writer** | Docs, READMEs, guides      | documentation, readme |
-| **Debugger**             | Systematic debugging       | debug, error, fix     |
+| **Build Error Resolver** | Rapid build fixes          | build, error, compile |
 | **Refactorer**           | Code cleanup, optimization | refactor, cleanup     |
-| **Frontend Specialist**  | React, Next.js, UI architecture | frontend, component, CSS |
-| **Backend Specialist**   | Node.js, NestJS, API design | backend, API, server  |
-| **Sprint Orchestrator**  | Sprint planning, velocity tracking | sprint, roadmap, velocity |
-| **Reliability Engineer** | SRE, production readiness | reliability, SLA, monitoring |
+| **Explorer Agent**       | Codebase discovery         | explore, scout, discover |
+| **Knowledge Agent**      | RAG retrieval              | knowledge, search, context |
+
+### Autonomy Agents
+
+| Agent                    | Role                              | Triggers                      |
+| :----------------------- | :-------------------------------- | :---------------------------- |
+| **Planner**              | Task breakdown, Socratic analysis | plan, breakdown, requirements |
+| **Sprint Orchestrator**  | Sprint planning, velocity         | sprint, roadmap, velocity     |
+| **Reliability Engineer** | SRE, production readiness         | reliability, SLA, monitoring  |
 
 ---
 
@@ -248,13 +300,13 @@ That's it! The kit is now active and ready to accelerate your development.
 | `/compact`    | Compress context  |
 | `/eval`       | Evaluate metrics  |
 | `/setup`      | Configure project |
-| `/help`       | Show help         |
+| `/help`       | **Comprehensive reference** — commands, workflows, agents, skills, rules, checklists |
 
 ---
 
-## 🛠️ Skills (27)
+## 🛠️ Skills (31)
 
-### Operational Skills (4)
+### Operational Skills (5)
 
 | Skill                 | Purpose                   |
 | :-------------------- | :------------------------ |
@@ -262,14 +314,16 @@ That's it! The kit is now active and ready to accelerate your development.
 | `continuous-learning` | Pattern extraction (PAAL) |
 | `strategic-compact`   | Context window management |
 | `eval-harness`        | Performance evaluation    |
+| `context-budget`      | Active token budget management |
 
-### Orchestration Skills (3)
+### Orchestration Skills (4)
 
 | Skill                 | Purpose                   |
 | :-------------------- | :------------------------ |
 | `intelligent-routing` | Auto agent selection      |
 | `parallel-agents`     | Multi-agent orchestration |
 | `behavioral-modes`    | Adaptive AI operation     |
+| `mcp-integration`     | MCP server integration    |
 
 ### Domain Skills (12)
 
@@ -302,7 +356,54 @@ That's it! The kit is now active and ready to accelerate your development.
 
 ---
 
-## 🔄 Workflows (11)
+## ⚙️ Runtime Engine (21 Modules)
+
+Antigravity AI Kit v3.0.0 includes a **full runtime engine** built across 4 phases — all using Node.js built-ins with zero external dependencies.
+
+### Phase 1 — Foundation Hardening
+
+| Module | Purpose |
+|:---|:---|
+| `workflow-engine` | Runtime state machine enforcement |
+| `session-manager` | Active session state management |
+| `verify` | Manifest integrity verification |
+| `updater` | Diff-based CLI update |
+| `error-budget` | Error budget tracking with metrics |
+
+### Phase 2 — Runtime Engine
+
+| Module | Purpose |
+|:---|:---|
+| `workflow-persistence` | Persistent state + checkpoints |
+| `agent-registry` | Agent contract validation |
+| `loading-engine` | Keyword matching + context budget |
+| `hook-system` | Event-driven lifecycle hooks |
+| `task-model` | Task CRUD with status tracking |
+
+### Phase 3 — Collaboration & Security
+
+| Module | Purpose |
+|:---|:---|
+| `identity` | Developer identity system |
+| `task-governance` | Locking, assignment, audit trail |
+| `skill-sandbox` | Runtime skill permission enforcement |
+| `conflict-detector` | Agent conflict detection |
+| `security-scanner` | Runtime injection & secret scanning |
+| `plugin-system` | Full plugin lifecycle management |
+
+### Phase 4 — Platform Leadership
+
+| Module | Purpose |
+|:---|:---|
+| `agent-reputation` | Score tracking, trends, rankings |
+| `engineering-manager` | Sprint planning, auto-assignment |
+| `self-healing` | CI failure detection & JSON patch generation |
+| `marketplace` | Community skill search & install |
+| `cli-commands` | Extracted CLI handlers for marketplace & heal |
+
+---
+
+## 🔄 Workflows (14)
 
 | Workflow          | Description              | Command          |
 | :---------------- | :----------------------- | :--------------- |
@@ -314,6 +415,9 @@ That's it! The kit is now active and ready to accelerate your development.
 | **orchestrate**   | Multi-agent coordination | `/orchestrate`   |
 | **plan**          | Implementation planning  | `/plan`          |
 | **preview**       | Preview changes          | `/preview`       |
+| **quality-gate**  | Pre-task validation      | `/quality-gate`  |
+| **retrospective** | Sprint audit & review    | `/retrospective` |
+| **review**        | Code review pipeline     | `/review`        |
 | **status**        | Project status check     | `/status`        |
 | **test**          | Test writing workflow    | `/test`          |
 | **ui-ux-pro-max** | Premium UI design        | `/ui-ux-pro-max` |
@@ -507,18 +611,33 @@ Usage and instructions...
 ```
 antigravity-ai-kit/
 ├── .agent/                    # Core AI Kit
-│   ├── agents/               # 17 specialized agents
+│   ├── agents/               # 19 specialized agents
 │   ├── commands/             # 31 slash commands
-│   ├── skills/               # 26 capability modules
-│   ├── workflows/            # 11 process templates
-│   ├── hooks/                # Event automation
-│   ├── rules/                # Governance rules
-│   ├── checklists/           # Verification checklists
-│   ├── templates/            # Feature templates
-│   └── decisions/            # ADR system
-├── docs/                      # Documentation
-├── examples/                  # Usage examples
-├── scripts/                   # Utility scripts
+│   ├── skills/               # 31 capability modules
+│   ├── workflows/            # 14 process templates
+│   ├── engine/               # Autonomy Engine (state machine, loading rules, configs)
+│   ├── hooks/                # 6 event hooks (runtime + git-hook)
+│   ├── rules.md              # Governance rules
+│   ├── checklists/           # Verification checklists (3)
+│   ├── templates/            # ADR, feature-request, bug-report templates
+│   ├── decisions/            # Architecture Decision Records
+│   └── manifest.json         # Machine-readable capability registry
+├── lib/                       # Runtime Engine (21 modules)
+│   ├── workflow-engine.js    # State machine enforcement
+│   ├── task-governance.js    # Locking, audit trail, decision timeline
+│   ├── agent-reputation.js   # Score tracking & rankings
+│   ├── self-healing.js       # CI failure detection & patch generation
+│   ├── marketplace.js        # Community skill marketplace
+│   └── + 16 more modules     # Identity, plugins, hooks, registry...
+├── bin/                       # CLI (ag-kit)
+├── create-antigravity-app/    # Project scaffolder (separate npm package)
+├── tests/                     # Test suites (261 tests, 25 files)
+│   ├── unit/                 # 21 module tests
+│   ├── structural/           # Inventory + schema validation
+│   └── security/             # Injection scan + leakage detection
+├── docs/                      # MkDocs documentation site
+├── .github/workflows/         # CI pipeline
+├── .githooks/                 # Secret detection pre-commit hook
 ├── README.md                  # This file
 ├── LICENSE                    # MIT License
 └── CHANGELOG.md               # Version history
@@ -565,6 +684,24 @@ MIT License — See [LICENSE](LICENSE) for details.
 
 ---
 
+## 📖 Contributor Guide
+
+Want to use Antigravity AI Kit in your project? The **[Contributor Guide](https://besync-labs.github.io/antigravity-ai-kit/contributor-guide/)** covers the full end-to-end lifecycle:
+
+| Phase | What You’ll Learn |
+|:---|:---|
+| **Onboard** | Install with `ag-kit init`, verify with `ag-kit status` |
+| **Identity** | Set up developer identity with role-based access |
+| **Sprint Planning** | Create sprints, define tasks, auto-assign agents |
+| **Task Management** | Lifecycle: `pending → in_progress → review → completed` |
+| **Development** | Trust-Grade workflow: `/explore → /plan → /work → /review` |
+| **Quality Gates** | 5-gate pipeline: lint, types, tests, security, build |
+| **Completion** | Sprint retrospective, tracking updates, next sprint |
+
+👉 **[Read the full guide →](https://besync-labs.github.io/antigravity-ai-kit/contributor-guide/)**
+
+---
+
 ## 🙏 Acknowledgments
 
 - Initial patterns from [vudovn/antigravity-kit](https://github.com/vudovn/antigravity-kit)
@@ -572,7 +709,7 @@ MIT License — See [LICENSE](LICENSE) for details.
 - Context-driven development from [Google Conductor](https://developers.googleblog.com/en/conductor-introducing-context-driven-development-for-gemini-cli/)
 - Hook concepts from [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
 
-_Antigravity AI Kit v2.1.0 extends these foundations with Trust-Grade governance, session management, and 90+ capabilities._
+_Antigravity AI Kit v3.0.0 extends these foundations with a 21-module runtime engine, Trust-Grade governance, session management, and 100+ capabilities._
 
 ---