antigravity-ai-kit 3.7.0 → 3.9.0

package/.agent/workflows/pr.md

@@ -1,8 +1,8 @@
 ---
-description: Production-grade PR creation with pre-flight checks, branch sync, and CI verification.
-version: 2.1.0
+description: Production-grade PR creation with branch strategy validation, size/scope guards, pre-flight checks, and CI verification.
+version: 3.0.0
 sdlc-phase: ship
-skills: [git-workflow, verification-loop]
+skills: [git-workflow, pr-toolkit, verification-loop]
 commit-types: [feat, fix, refactor, perf, chore, docs, test]
 ---
 
@@ -35,13 +35,15 @@ commit-types: [feat, fix, refactor, perf, chore, docs, test]
 
 ## Critical Rules
 
-1. **ALWAYS** sync with target branch before creating PR — prevents merge conflicts
-2. **ALWAYS** run pre-flight `/review` locally before pushing — catches issues pre-CI
-3. **NEVER** create a PR from `main` or `production` branches
-4. **NEVER** create a PR with known conflicts — resolve first
-5. **NEVER** merge without all CI checks passing
-6. **ATOMIC** PRs — one logical unit of work per PR, not multi-sprint kitchen sinks
-7. **CONVENTIONAL** titles — `type(scope): description` format
+1. **ALWAYS** detect the project's branch strategy before validating target — prevents wrong-base PRs
+2. **ALWAYS** sync with target branch before creating PR — prevents merge conflicts
+3. **ALWAYS** run pre-flight `/review` locally before pushing — catches issues pre-CI
+4. **NEVER** create a PR from `main` or `production` branches
+5. **NEVER** create a PR with known conflicts — resolve first
+6. **NEVER** merge without all CI checks passing
+7. **ATOMIC** PRs — one logical unit of work per PR, not multi-sprint kitchen sinks
+8. **CONVENTIONAL** titles — `type(scope): description` format, validated before creation
+9. **SIZE GUARD** — PRs exceeding XL threshold (50+ files or 1500+ LOC) must be split
 
 ---
 
@@ -60,11 +62,11 @@ commit-types: [feat, fix, refactor, perf, chore, docs, test]
 
 Execute IN ORDER. Stop at first failure.
 
-### Step 1: Verify Branch State
+### Step 1: Verify Branch State & Detect Branch Strategy
 
 // turbo
 
-```powershell
+```bash
 git branch --show-current
 git status --porcelain
 ```
@@ -72,24 +74,89 @@ git status --porcelain
 - If on `main` or `production` → **STOP**, instruct user to create feature branch
 - If working tree dirty → prompt to commit or stash
 
+**1a. Detect Branch Strategy** (per `pr-toolkit` skill):
+
+```bash
+# Check for GitFlow indicators
+git branch -r | grep -E 'origin/(dev|develop)$'
+```
+
+- If `dev`/`develop` exists → **GitFlow** detected
+- If only `main`/`master` → **Trunk-Based** detected
+- Record detected strategy for Step 1b validation
+
+**1b. Validate Target Branch**:
+
+| Strategy | Source Pattern | Valid Target | Invalid Target |
+| :--- | :--- | :--- | :--- |
+| GitFlow | `feature/*`, `bugfix/*`, `chore/*`, `docs/*` | `dev`, `develop` | `main` → **BLOCK** |
+| GitFlow | `hotfix/*` | `main` | — |
+| GitFlow | `release/*`, `dev` | `main` | — |
+| Trunk-Based | Any feature branch | `main` | — |
+
+- If target is invalid → **STOP**: "Branch strategy violation — `{branch}` should target `{valid_target}`, not `{invalid_target}`"
+- If user explicitly provided target via `/pr [target]` → validate against strategy, warn if non-standard
+
 ### Step 2: Sync with Target Branch
 
 // turbo
 
-```powershell
+```bash
 git fetch origin <target>
 git merge origin/<target> --no-edit
 ```
 
 - If conflicts detected → invoke **Conflict Resolution Protocol** (see below)
-- If clean merge → proceed to Step 3
+- If clean merge → proceed to Step 2.5
+
+### Step 2.5: PR Size & Scope Guard
+
+// turbo
+
+**2.5a. Size Classification** (per `pr-toolkit` size matrix):
+
+```bash
+# Count changed files and lines
+git diff --name-only origin/<target>..HEAD | wc -l
+git diff --stat origin/<target>..HEAD | tail -1
+```
+
+| Size | Files | LOC | Action |
+| :--- | :--- | :--- | :--- |
+| XS-M | 1-30 | < 700 | Proceed |
+| L | 31-50 | 700-1500 | **WARN**: "Large PR — consider splitting for faster review" |
+| XL | 50+ | 1500+ | **BLOCK**: "PR exceeds reviewability threshold — split into focused PRs" |
+
+**2.5b. Scope Coherence Check**:
+
+```bash
+# Categorize changed files by directory/purpose
+git diff --name-only origin/<target>..HEAD
+```
+
+Detect mixed concerns:
+- Source code (`src/`, `lib/`, `app/`) alongside framework config (`.agent/`, `.github/`)
+- Feature code alongside unrelated dependency bumps
+- Multiple unrelated modules changed with no shared dependency
+
+If scope violation detected → **WARN**: "PR contains mixed concerns — recommend splitting: [split suggestions]"
 
 > [!WARNING]
 > If the branch has diverged significantly from the target, expect conflicts in shared files like `.gitignore`, `package.json`, or lock files. Always check `git diff --name-only origin/<target>..HEAD` before creating the PR.
 
 ### Step 3: Run Pre-Flight Checks
 
-Delegate to `/review` pipeline (Gates 1-5: lint, type-check, test, security, build).
+// turbo
+
+**3a. Verify /preflight status** (for `feat`, `fix`, `refactor`, `perf` commit types):
+- Check if `/preflight` scorecard exists in conversation context
+- If scorecard exists and status is Production Ready or Conditionally Ready → proceed
+- If no scorecard found → warn: "Consider running `/preflight` before `/pr` for full production readiness validation"
+- For lightweight commit types (`chore`, `docs`, `test`) → skip this check
+
+**3b. Run /review pipeline** (Gates 1-5: lint, type-check, test, security, build):
+
+Delegate to `/review` pipeline.
 
 - Scope filter applies:
   - `docs()` → skip all gates
@@ -110,18 +177,29 @@ git push origin HEAD
 - If rejected (upstream diverged) → re-run Step 2, then retry push
 - If authentication error → guide user to configure credentials
 
-### Step 5: Generate PR Title & Body
+### Step 5: Generate & Validate PR Title & Body
 
 // turbo
 
-**Title generation:**
-- Parse branch name: `feature/ABC-123-add-user-auth` → `feat(auth): add user auth`
-- Fallback: use first commit message subject line
-- Format: `type(scope): description` (conventional commits)
+**Title generation** (per `pr-toolkit` title parser):
+
+1. Parse branch name using branch-to-title algorithm:
+   - Extract type: `feature/` → `feat`, `bugfix/` → `fix`, `hotfix/` → `fix`, `chore/` → `chore`
+   - Remove ticket prefix: `ABC-123-` → strip
+   - Extract scope from first segment, description from remainder
+   - Compose: `type(scope): description`
+2. Fallback: use first commit message subject line
+3. **Validate** the generated title:
+   - Must match `type(scope): description` or `type: description`
+   - Type must be one of: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`
+   - Description must be imperative mood, under 72 characters, no trailing period
+   - If validation fails → prompt user to provide/correct title
 
 **Body generation:**
 - Populate from `git log origin/<target>..HEAD --oneline` and `git diff --stat origin/<target>..HEAD`
+- Include **PR Size Label**: `[XS/S/M/L]` in body metadata
 - Use **PR Body Template** (see below)
+- Verify body contains: Summary, Changes, Test Plan sections
 
 ### Step 6: Create PR
 
@@ -247,19 +325,25 @@ git commit -m "merge: resolve conflicts with <target>"
 
 **PROHIBITED:**
 - Creating PRs from `main` or `production` branches
+- Creating PRs targeting wrong branch per detected strategy (e.g., feature→main in GitFlow)
 - Creating PRs with unresolved merge conflicts
+- Creating XL PRs (50+ files or 1500+ LOC) without splitting
 - Pushing without local pre-flight `/review` passing
 - Merging PRs with failing CI checks
 - Including generated files, PII, secrets, or `.env` in diff
 - Multi-sprint mega-PRs — keep PRs focused and reviewable
+- Non-conventional PR titles (raw branch names, vague descriptions)
 - Using `// turbo` on state-mutating steps (push, create, merge)
 - Skipping failed steps · proceeding without resolution
 
 **REQUIRED:**
+- Branch strategy detection before target validation
+- Target branch validation against detected strategy
+- PR size classification and scope coherence check
 - Branch sync with target before every PR
 - Local pre-flight via `/review` before push
-- Conventional commit PR title format
-- Structured PR body using template
+- Conventional commit PR title format (validated)
+- Structured PR body using template (Summary, Changes, Test Plan)
 - CI verification after PR creation
 - Human approval before push and PR creation (non-turbo)
 - MCP-first with graceful fallback strategy
@@ -270,11 +354,16 @@ git commit -m "merge: resolve conflicts with <target>"
 ## Completion Criteria
 
 - [ ] On feature branch (not `main`/`production`)
+- [ ] Branch strategy detected (GitFlow / Trunk-Based)
+- [ ] Target branch validated against strategy
 - [ ] Working tree clean (committed or stashed)
 - [ ] Target branch synced (no conflicts)
+- [ ] PR size classified (XS/S/M/L — XL blocked)
+- [ ] Scope coherence verified (single logical unit)
 - [ ] Pre-flight `/review` passes (scope-filtered)
 - [ ] Pushed to remote
-- [ ] PR created with conventional title and structured body
+- [ ] PR title validated (conventional commits format)
+- [ ] PR created with structured body (Summary, Changes, Test Plan)
 - [ ] CI checks monitored and passed (or draft acknowledged)
 - [ ] Review requested (if applicable)
 - [ ] After CI passes: proceed to `/deploy` when ready
@@ -285,7 +374,8 @@ git commit -m "merge: resolve conflicts with <target>"
 
 - **Previous**: `/preflight` (production readiness verified) · `/review` (code quality gates)
 - **Next**: `/deploy` (deployment after PR is merged)
-- **Skills**: `.agent/skills/git-workflow/SKILL.md` · `.agent/skills/verification-loop/SKILL.md`
-- **Global Rule**: Production Merge Discipline (see global rules)
-- **Related**: `/status` (check PR and CI status)
+- **Skills**: `.agent/skills/pr-toolkit/SKILL.md` · `.agent/skills/git-workflow/SKILL.md` · `.agent/skills/verification-loop/SKILL.md`
+- **Related**: `/pr-review` (review existing PRs) · `/pr-fix` (fix review findings) · `/status` (check PR and CI status)
+- **Agent**: `.agent/agents/pr-reviewer.md` (Senior Staff Engineer PR review specialist)
+- **Rule**: `.agent/rules/git-workflow.md` — branching and commit conventions
 - **Note**: PR body template supersedes the basic template in `git-workflow` skill

package/.agent/workflows/preflight.md

@@ -24,10 +24,10 @@ commit-types: [feat, fix, refactor, perf]
 
 ## Critical Rules
 
-1. **Evidence-backed scoring** — every domain score must cite observable proof (file, command output, observation)
+1. **Evidence-backed scoring** — every domain score must cite observable proof (file, command output, observation, or N/A justification)
 2. **Never bypass blockers** — blocker rule violations override total score (see skill for precedence)
 3. **Human approval required** — Go/No-Go recommendation requires explicit user decision
-4. **Non-destructive** — all checks are read-only analysis; no files modified, no commands with side effects
+4. **Non-destructive** — checks do not modify source code; verification commands (test suites, linters, builds) may run but must not alter project state
 5. **Skill-mediated delegation** — domain checks reference existing skills, never duplicate their logic
 6. **Fail-safe defaults** — unverifiable checks score 0, not assumed pass
 

package/.agent/workflows/upgrade.md

@@ -0,0 +1,196 @@
+---
+description: Non-destructive Antigravity AI Kit framework upgrade with preservation verification.
+version: 1.0.0
+sdlc-phase: maintenance
+skills: [verification-loop]
+commit-types: [chore]
+---
+
+# /upgrade — Framework Upgrade
+
+> **Trigger**: `/upgrade [sub-command]`
+> **Lifecycle**: Maintenance — invoked when a new Antigravity AI Kit version is available
+
+> [!CAUTION]
+> Framework upgrades modify `.agent/` files on disk. The Preservation Contract
+> (defined in `.agent/rules/agent-upgrade-policy.md`) protects user-specific state.
+> Always verify integrity after upgrade. Never use `init --force` for routine upgrades.
+
+> [!TIP]
+> This workflow references the **agent-upgrade-policy** rule for the canonical list of
+> protected files. Read `.agent/rules/agent-upgrade-policy.md` for the full Preservation Contract.
+
+---
+
+## Critical Rules
+
+1. **Non-destructive only** — use `ag-kit update`, never `init --force` for routine upgrades
+2. **Preservation Contract** — user-specific state (rules, checklists, sessions, decisions, contexts, identity) must survive upgrades
+3. **Verify after upgrade** — always run `ag-kit verify` post-upgrade to confirm manifest integrity
+4. **Rollback capability** — uncommitted upgrades can be reverted via `git checkout -- .agent/`
+5. **Human confirmation** — the upgrade step requires explicit user approval before execution
+
+---
+
+## Scope Filter
+
+| Change Type | Upgrade Applies? | Rationale |
+| :---------- | :--------------- | :-------- |
+| New kit version available | Yes | Core use case |
+| User wants to refresh `.agent/` | Yes | Non-destructive merge |
+| First-time setup | No | Use `npx antigravity-ai-kit init` instead |
+| Catastrophic repair | No | Use `init --force` (destructive — last resort) |
+
+---
+
+## Argument Parsing
+
+| Command | Action |
+| :----------------------- | :----------------------------------------------- |
+| `/upgrade` | Interactive upgrade — detect, preview, apply, verify |
+| `/upgrade --dry-run` | Preview changes without applying |
+| `/upgrade --verify-only` | Run post-upgrade verification checks only |
+
+---
+
+## Steps
+
+// turbo
+1. **Pre-Upgrade Assessment**
+   - Check current kit version: read `manifest.json` → `kitVersion`
+   - Verify no uncommitted critical work: `git status --porcelain`
+   - If dirty working tree → prompt to commit or stash before proceeding
+   - Record current state for rollback reference: `git rev-parse HEAD`
+
+// turbo
+2. **Preservation Snapshot**
+   - Verify all Preservation Contract items exist (see rule for canonical list):
+     - `.agent/session-state.json`
+     - `.agent/session-context.md`
+     - `.agent/identity.json`
+     - `.agent/rules/` (user customizations)
+     - `.agent/checklists/` (user customizations)
+     - `.agent/decisions/` (ADRs)
+     - `.agent/contexts/` (learning data)
+   - Record file checksums for post-upgrade comparison
+
+3. **Execute Upgrade**
+   - Run the non-destructive AST merger:
+     ```bash
+     ag-kit update
+     ```
+   - For preview-only mode: `ag-kit update --dry-run`
+   - Monitor output for warnings or conflicts
+
+// turbo
+4. **Verify Integrity**
+   - Run manifest verification:
+     ```bash
+     ag-kit verify
+     ```
+   - Confirm capability counts match the new version
+   - Verify all Preservation Contract items remain intact (compare checksums from Step 2)
+   - If any protected file was modified or deleted → **STOP** and report violation
+
+// turbo
+5. **Post-Upgrade Summary**
+   - Report version change (old → new)
+   - List new capabilities added (agents, skills, workflows, rules)
+   - Confirm Preservation Contract compliance
+   - Complete the task-complete protocol
+
+---
+
+## Output Template
+
+### Successful Upgrade
+
+```markdown
+## Upgrade Complete
+
+| Field | Value |
+| :--- | :--- |
+| Previous Version | [old version] |
+| New Version | [new version] |
+| Preservation Contract | All protected files intact |
+| Manifest Verify | Passed |
+
+### New Capabilities
+
+| Type | Added | Details |
+| :--- | :--- | :--- |
+| Agents | [+N] | [names] |
+| Skills | [+N] | [names] |
+| Workflows | [+N] | [names] |
+| Rules | [+N] | [names] |
+
+### Preservation Verification
+
+All 7 protected items verified intact.
+
+**Next**: Run `/status` to confirm project health.
+```
+
+### Failed Upgrade
+
+```markdown
+## Upgrade Failed
+
+### Error
+
+[Error description from ag-kit update output]
+
+### Rollback
+
+To restore previous state:
+```bash
+git checkout -- .agent/
+```
+
+### Resolution
+
+1. [Fix steps based on error]
+2. Re-run: `/upgrade`
+```
+
+---
+
+## Governance
+
+**PROHIBITED:**
+- Using `init --force` for routine upgrades — this is a destructive wipe
+- Deleting or modifying Preservation Contract files during upgrade
+- Skipping post-upgrade verification
+- Proceeding if `ag-kit verify` fails
+- Auto-executing the upgrade step without user confirmation
+
+**REQUIRED:**
+- Pre-upgrade working tree check
+- Preservation snapshot before upgrade execution
+- `ag-kit verify` after every upgrade
+- Preservation Contract compliance verification
+- Human approval before executing Step 3 (upgrade)
+- Rollback instructions available in case of failure
+
+---
+
+## Completion Criteria
+
+- [ ] Current version identified
+- [ ] Working tree clean (committed or stashed)
+- [ ] Preservation Contract items inventoried
+- [ ] Upgrade executed via `ag-kit update` (not `init --force`)
+- [ ] `ag-kit verify` passes
+- [ ] All Preservation Contract items verified intact
+- [ ] Version change and new capabilities reported to user
+- [ ] After upgrade: proceed to `/status` for health check
+
+---
+
+## Related Resources
+
+- **Rule**: `.agent/rules/agent-upgrade-policy.md` (Preservation Contract)
+- **Next**: `/status` (post-upgrade health check)
+- **Skill**: `.agent/skills/verification-loop/SKILL.md`
+- **Related**: `/deploy` (deployment after code changes) · `/review` (post-upgrade quality check)
+- **CLI**: `ag-kit update`, `ag-kit update --dry-run`, `ag-kit verify`

package/README.md

@@ -1,13 +1,13 @@
 # 🚀 Antigravity AI Kit
 
-![version](https://img.shields.io/badge/version-3.7.0-blue)
+![version](https://img.shields.io/badge/version-3.9.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-33-orange)
-![Commands](https://img.shields.io/badge/Commands-31-red)
-![Workflows](https://img.shields.io/badge/Workflows-16-teal)
+![AI Agents](https://img.shields.io/badge/AI%20Agents-20-purple)
+![Skills](https://img.shields.io/badge/Skills-34-orange)
+![Commands](https://img.shields.io/badge/Commands-37-red)
+![Workflows](https://img.shields.io/badge/Workflows-21-teal)
 ![Runtime Modules](https://img.shields.io/badge/Runtime%20Modules-29-blueviolet)
-![Tests](https://img.shields.io/badge/Tests-341%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/Tests-349%20passing-brightgreen)
 ![Checklists](https://img.shields.io/badge/Checklists-4-yellow)
 
 <p align="center">
@@ -15,14 +15,14 @@
 </p>
 
 <p align="center">
-  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> with a <b>29-module runtime engine</b>, <b>19 specialized agents</b>, <b>31 commands</b>, <b>33 skills</b>, and <b>16 workflows</b> — all backed by <b>341 tests</b> and governance-first principles.
+  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> with a <b>29-module runtime engine</b>, <b>20 specialized agents</b>, <b>37 commands</b>, <b>34 skills</b>, and <b>21 workflows</b> — all backed by <b>349 tests</b> and governance-first principles.
 </p>
 
 <p align="center">
   🚀 <a href="#-quick-start">Quick Start</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="#-agents-20">Agents</a> •
+  🛠️ <a href="#%EF%B8%8F-skills-34">Skills</a> •
+  ⌨️ <a href="#%EF%B8%8F-commands-37">Commands</a> •
   🔄 <a href="#-session-management">Sessions</a> •
   ⚖️ <a href="#%EF%B8%8F-operating-constraints">Governance</a> •
   📖 <a href="#-contributor-guide">Contributor Guide</a>
@@ -36,11 +36,11 @@
 - [Key Features](#-key-features)
 - [Quick Start](#-quick-start)
 - [Architecture](#%EF%B8%8F-architecture-overview)
-- [Agents](#-agents-19)
-- [Commands](#%EF%B8%8F-commands-31)
-- [Skills](#%EF%B8%8F-skills-32)
+- [Agents](#-agents-20)
+- [Commands](#%EF%B8%8F-commands-37)
+- [Skills](#%EF%B8%8F-skills-34)
 - [Runtime Engine](#%EF%B8%8F-runtime-engine-29-modules)
-- [Workflows](#-workflows-15)
+- [Workflows](#-workflows-21)
 - [Operating Constraints](#%EF%B8%8F-operating-constraints)
 - [Session Management](#-session-management)
 - [How to Extend](#-how-to-extend)
@@ -55,22 +55,22 @@
 
 | Feature           | Count | Description                                                            |
 | :---------------- | :---- | :--------------------------------------------------------------------- |
-| 🤖 **AI Agents**  | 19    | Specialized roles (Mobile, DevOps, Database, Security, Performance...) |
-| 🛠️ **Skills**     | 33    | Domain knowledge modules (API, Testing, MCP, Architecture, Docker...) |
-| ⌨️ **Commands**   | 31    | Slash commands for every development workflow                          |
-| 🔄 **Workflows**  | 16    | Process templates (/create, /debug, /deploy, /pr, /test...)            |
+| 🤖 **AI Agents**  | 20    | Specialized roles (Mobile, DevOps, Database, Security, Performance...) |
+| 🛠️ **Skills**     | 34    | Domain knowledge modules (API, Testing, MCP, Architecture, Docker...) |
+| ⌨️ **Commands**   | 37    | Slash commands for every development workflow                          |
+| 🔄 **Workflows**  | 21    | Process templates (/create, /debug, /deploy, /pr, /pr-merge, /test...)  |
 | ⚙️ **Runtime**    | 29    | Runtime engine modules (governance, reputation, self-healing...)       |
 | ✅ **Checklists** | 4     | Quality gates (session-start, session-end, pre-commit, task-complete)  |
-| ⚖️ **Rules**      | 8     | Modular governance constraints (coding, security, testing, git, docs, sprint)  |
+| ⚖️ **Rules**      | 9     | Modular governance constraints (coding, security, testing, git, docs, sprint)  |
 | 🔗 **Hooks**      | 8     | Event-driven automation (runtime + git-hook enforcement)               |
-| 🧪 **Tests**      | 327   | Unit, structural, integration, and security tests (32 test files)      |
+| 🧪 **Tests**      | 349   | Unit, structural, integration, and security tests (34 test files)      |
 
 ---
 
 ## ✨ Key Features
 
 - **🔒 Trust-Grade Governance**: `/explore → /plan → /work → /review` — Each iteration builds context
-- **🤖 Multi-Agent System**: 19 specialized agents that collaborate (Mobile Developer, DevOps, Database Architect, Sprint Orchestrator...)
+- **🤖 Multi-Agent System**: 20 specialized agents that collaborate (Mobile Developer, DevOps, Database Architect, Sprint Orchestrator...)
 - **⚙️ Runtime Engine**: 29 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
@@ -149,7 +149,7 @@ Antigravity AI Kit is designed to **never touch your project files**. All operat
 ┌─────────────────────────────────────────────────────────────────────┐
 │                    USER INTERFACE LAYER                              │
 │  ┌─────────────────────────┐  ┌─────────────────────────┐          │
-│  │  Slash Commands (31)    │  │  Workflows (15)         │          │
+│  │  Slash Commands (37)    │  │  Workflows (21)         │          │
 │  └────────────┬────────────┘  └────────────┬────────────┘          │
 ├───────────────┼────────────────────────────┼────────────────────────┤
 │               ▼         INTELLIGENCE LAYER ▼                        │
@@ -158,7 +158,7 @@ Antigravity AI Kit is designed to **never touch your project files**. All operat
 │  │ Router           │  │ Machine          │  │ Engine           │  │
 │  └────────┬─────────┘  └──────────────────┘  └──────────────────┘  │
 ├───────────┼────────────────────────────────────────────────────────-┤
-│           ▼              AGENT LAYER (19)                            │
+│           ▼              AGENT LAYER (20)                            │
 │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
 │  │ Core Agents      │  │ Domain Agents    │  │ Support Agents   │  │
 │  │ Planner          │  │ Mobile Dev       │  │ Security         │  │
@@ -167,7 +167,7 @@ Antigravity AI Kit is designed to **never touch your project files**. All operat
 │  │ TDD Specialist   │  │ DB, DevOps       │  │ Knowledge        │  │
 │  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │
 ├───────────┼─────────────────────┼─────────────────────┼────────────┤
-│           ▼              SKILL LAYER (32)              ▼            │
+│           ▼              SKILL LAYER (34)              ▼            │
 │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
 │  │ Orchestration    │  │ Operational      │  │ Domain Skills    │  │
 │  │ Routing, Modes   │  │ Verification     │  │ API, Testing     │  │
@@ -208,7 +208,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → CHECKPOINT → REVIEW → DEPLOY
 
 ---
 
-## 🤖 Agents (19)
+## 🤖 Agents (20)
 
 ### Core Development
 
@@ -245,12 +245,13 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → CHECKPOINT → REVIEW → DEPLOY
 | Agent                    | Role                              | Triggers                      |
 | :----------------------- | :-------------------------------- | :---------------------------- |
 | **Planner**              | Multi-agent plan synthesis, tiered quality schema, specialist coordination | plan, breakdown, requirements |
+| **PR Reviewer**          | Pull request review & fixes       | pr, pull-request, review      |
 | **Sprint Orchestrator**  | Sprint planning, velocity         | sprint, roadmap, velocity     |
 | **Reliability Engineer** | SRE, production readiness         | reliability, SLA, monitoring  |
 
 ---
 
-## ⌨️ Commands (31)
+## ⌨️ Commands (37)
 
 ### Core Workflow
 
@@ -280,6 +281,12 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → CHECKPOINT → REVIEW → DEPLOY
 | `/changelog` | Generate changelog           |
 | `/git`       | Git operations               |
 | `/pr`        | Create/manage pull requests  |
+| `/pr-review` | Automated PR code review     |
+| `/pr-fix`    | Auto-fix PR review findings  |
+| `/pr-merge`  | Safe PR merge with validation|
+| `/pr-split`  | Split oversized PRs          |
+| `/pr-status` | PR triage and merge readiness|
+| `/pr-describe`| Auto-generate PR description|
 
 ### Exploration & Research
 
@@ -320,7 +327,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → CHECKPOINT → REVIEW → DEPLOY
 
 ---
 
-## 🛠️ Skills (33)
+## 🛠️ Skills (34)
 
 ### Operational Skills (6)
 
@@ -360,7 +367,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → CHECKPOINT → REVIEW → DEPLOY
 | `git-workflow`         | Branching, commits              |
 | `i18n-localization`    | Internationalization patterns   |
 
-### Development Skills (10)
+### Development Skills (11)
 
 | Skill                   | Purpose                 |
 | :---------------------- | :---------------------- |
@@ -373,6 +380,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → CHECKPOINT → REVIEW → DEPLOY
 | `plan-writing`          | Structured planning with tiered quality schema |
 | `plan-validation`       | Quality gate with completeness scoring |
 | `shell-conventions`     | PowerShell/Bash conventions |
+| `pr-toolkit`            | PR review & fix workflows |
 | `ui-ux-pro-max`         | Premium UI/UX design system |
 
 ---
@@ -424,7 +432,7 @@ Antigravity AI Kit v3.2.0 includes a **full runtime engine** built across 4 phas
 
 ---
 
-## 🔄 Workflows (16)
+## 🔄 Workflows (21)
 
 | Workflow          | Description              | Command          |
 | :---------------- | :----------------------- | :--------------- |
@@ -436,6 +444,10 @@ Antigravity AI Kit v3.2.0 includes a **full runtime engine** built across 4 phas
 | **orchestrate**   | Multi-agent coordination | `/orchestrate`   |
 | **plan**          | Implementation planning  | `/plan`          |
 | **pr**            | Production-grade PR creation | `/pr`        |
+| **pr-review**     | Automated PR code review     | `/pr-review` |
+| **pr-fix**        | Auto-fix PR review findings  | `/pr-fix`    |
+| **pr-merge**      | Safe PR merge with validation| `/pr-merge`  |
+| **pr-split**      | Split oversized PRs          | `/pr-split`  |
 | **preflight**     | Production readiness assessment | `/preflight`    |
 | **preview**       | Preview changes          | `/preview`       |
 | **quality-gate**  | Pre-task validation      | `/quality-gate`  |
@@ -444,6 +456,7 @@ Antigravity AI Kit v3.2.0 includes a **full runtime engine** built across 4 phas
 | **status**        | Project status check     | `/status`        |
 | **test**          | Test writing workflow    | `/test`          |
 | **ui-ux-pro-max** | Premium UI design        | `/ui-ux-pro-max` |
+| **upgrade**       | Non-destructive framework updates | `/upgrade` |
 
 ---
 
@@ -634,13 +647,13 @@ Usage and instructions...
 ```
 antigravity-ai-kit/
 ├── .agent/                    # Core AI Kit
-│   ├── agents/               # 19 specialized agents
-│   ├── commands/             # 31 slash commands
-│   ├── skills/               # 32 capability modules
-│   ├── workflows/            # 15 process templates
+│   ├── agents/               # 20 specialized agents
+│   ├── commands/             # 37 slash commands
+│   ├── skills/               # 34 capability modules
+│   ├── workflows/            # 21 process templates
 │   ├── engine/               # Autonomy Engine (state machine, loading rules, configs)
 │   ├── hooks/                # 8 event hooks (runtime + git-hook)
-│   ├── rules/                # 8 modular governance rules
+│   ├── rules/                # 9 modular governance rules
 │   ├── checklists/           # Verification checklists (4)
 │   ├── templates/            # ADR, feature-request, bug-report templates
 │   ├── decisions/            # Architecture Decision Records
@@ -654,7 +667,7 @@ antigravity-ai-kit/
 │   └── + 16 more modules     # Identity, plugins, hooks, registry...
 ├── bin/                       # CLI (ag-kit)
 ├── create-antigravity-app/    # Project scaffolder (separate npm package)
-├── tests/                     # Test suites (327 tests, 32 files)
+├── tests/                     # Test suites (349 tests, 34 files)
 │   ├── unit/                 # Module tests (loading-engine, self-healing, plugins...)
 │   ├── structural/           # Inventory + schema validation
 │   └── security/             # Injection scan + leakage detection