everything-gemini 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,317 @@
-# Temporary Holding Version
+# 🪐 Everything Gemini (everything-gemini)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Antigravity](https://img.shields.io/badge/Google-Antigravity-4285F4.svg)](https://antigravity.google)
+[![Version](https://img.shields.io/badge/version-1.0.1-emerald.svg)](package.json)
+[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/salmandev/everything-gemini)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+**The open-source agent harness, multi-agent orchestrator, and performance ecosystem for Google Gemini & Antigravity.**
+
+[Quickstart](#-quickstart) • [What is everything-gemini?](#-what-is-everything-gemini) • [Architecture](#-architecture--internals) • [Customization Catalog](#-customization-catalog) • [Surfaces Guide](#-the-4-antigravity-surfaces) • [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## ⚡ What is Everything Gemini?
+
+**Google Antigravity** is Google’s state-of-the-art AI-first coding platform, powered by Gemini models, an event-driven execution loop (Cortex), progressive disclosure, multi-surface orchestration (Desktop 2.0, VS Code-based IDE, `agy` CLI, and Python SDK), and localized Knowledge Items (KI).
+
+Out of the box, Antigravity is a formidable pair programmer. But without structured harnesses, agents can suffer from:
+- **Context bloat**: Loading massive guidelines into every prompt turn, eroding the model's reasoning window.
+- **Unchecked execution risks**: Accidentally running destructive terminal commands or pushing unfinished code.
+- **Premature stops**: Quitting multi-step tasks before tests pass or edge cases are verified.
+- **Amnesia between sessions**: Forgetting architectural lessons learned yesterday.
+
+**Everything Gemini (`everything-gemini`)** solves this. It provides a battle-tested harness system consisting of:
+1. 🛡️ **Safety Shield & Lifecycle Hooks (`hooks.json`)**: Deterministic gating for destructive commands, auto-lint formatters, and stop-guard verifiers.
+2. 🧠 **Progressive Disclosure Skills (`skills/`)**: On-demand procedural playbooks that load *only* when needed, saving up to **85% in token overhead**.
+3. 📏 **Hierarchical Rules (`GEMINI.md` / `AGENTS.md`)**: Context-aware coding standards, zero-hallucination protocols, and clean-architecture rules.
+4. 🔌 **Plug-and-Play Plugins (`plugins/`)**: Domain bundles for Fullstack Web, Python AI, DevOps, and Security.
+5. 🌐 **Curated MCP Servers (`mcp/`)**: Pre-configured connections for GitHub, PostgreSQL, SQLite, and Documentation scrapers.
+6. 🤖 **Subagent & Browser Automation**: Specialized recipes for autonomous browser subagents with automated WebP recording.
+
+---
+
+## 🚀 Quickstart
+
+### 1. Instant Installation via npx (Zero Setup)
+
+Run this directly in any project directory or terminal:
+
+```bash
+npx everything-gemini install
+```
+
+### 2. One-Line Interactive Installer
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/salmandev/everything-gemini/main/scripts/install.sh | bash
+```
+
+```powershell
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/salmandev/everything-gemini/main/scripts/install.ps1 | iex
+```
+
+### 3. Via Repository Clone
+```bash
+# Clone the repository
+git clone https://github.com/salmandev/everything-gemini.git
+cd everything-gemini
+
+# Run the Everything Gemini CLI
+./bin/everything-gemini install --profile developer
+```
+
+### 4. Installation Profiles
+
+| Profile | Target Audience | What Gets Installed |
+| :--- | :--- | :--- |
+| **`core`** | Minimalists & Speed | Safety-shield hook, TDD skill, repo-onboarding skill, baseline `GEMINI.md`. |
+| **`developer`** *(Recommended)* | Daily Software Engineers | Core + Fullstack Web plugin, Python AI plugin, Git Craftsman, Auto-formatter hook, Stop verifier hook. |
+| **`full`** | Lead Engineers & Archs | Everything: all plugins, full skills catalog, all lifecycle hooks, pre-tested MCP configs, and templates. |
+
+---
+
+## 🏗️ Architecture & Internals
+
+`everything-gemini` is engineered specifically around Google Antigravity's internal execution engine:
+
+```mermaid
+flowchart TB
+    subgraph AntigravitySurfaces["1. Antigravity Surfaces"]
+        Desktop["Antigravity 2.0 (Desktop)"]
+        IDE["Antigravity IDE (VS Code Fork)"]
+        CLI["Antigravity CLI ('agy')"]
+        SDK["Python SDK ('google-antigravity')"]
+    end
+
+    subgraph CustomizationRoots["2. Customization Roots"]
+        Global["~/.gemini/config/ (Global)"]
+        Workspace[".agents/ (Workspace Root)"]
+    end
+
+    subgraph GeminiHarness["3. Everything Gemini Harness & Engine"]
+        direction TB
+        HookEngine["Lifecycle Hooks Engine\n(PreToolUse | PostToolUse | PreInvocation | Stop)"]
+        Progressive["Progressive Disclosure Router\n(Injects only metadata until model decides to view)"]
+        MemoryBridge["Memory Bridge\n(Knowledge Items [KI] + Brain Artifacts + Transcripts)"]
+    end
+
+    subgraph Capabilities["4. Agent Capabilities & Sandboxes"]
+        Subagents["Autonomous Subagents\n(browser_subagent, test-runner)"]
+        MCP["Model Context Protocol (MCP)\n(Stdio & SSE Servers)"]
+        TerminalSandbox["Terminal Sandbox & Execution Policy"]
+    end
+
+    AntigravitySurfaces --> CustomizationRoots
+    CustomizationRoots --> GeminiHarness
+    GeminiHarness --> Capabilities
+```
+
+### Key Differences: ECC vs. Everything Gemini
+
+> 📖 **Read the Comprehensive Architectural Breakdown**: [Everything Claude Code (ECC) vs. Everything Gemini](docs/ecc-vs-everything-gemini.md)
+
+| Feature | Everything Claude Code (ECC) | Everything Gemini (`everything-gemini`) |
+| :--- | :--- | :--- |
+| **Target Platform** | Claude Code CLI & harnesses | Antigravity 2.0 Desktop, IDE, `agy` CLI, Python SDK |
+| **Model Engine** | Claude 3.5 / 3.7 Sonnet | Gemini 3.8 / 1.5 Flash & Pro |
+| **Context Protocol** | Direct markdown prompts | **Progressive Disclosure** (Metadata injected first, bodies lazy-loaded) |
+| **Context Window & Caching** | 200k tokens, ephemeral | **1M-2M+ tokens with Native Prefix Context Caching (~75% cost savings)** |
+| **Memory System** | Flat markdown files | **Knowledge Items (KI)** + **Adaptive Learned Instincts** |
+| **UI & Visual Multimodality** | Standard text output | **Native `browser_subagent` + WebP Screen Video Recording + Vision** |
+| **Subagents Fleet** | Manual sub-prompts | **6 Scoped Subagents (`agents/`) with Formal Handoff Protocol** |
+| **Lifecycle Hooks** | Shell scripts | Typed protojson contracts (`PreToolUse`, `PostToolUse`, `PreInvocation`, `PostInvocation`, `Stop`) |
+| **Tool Integration** | Claude tool use | **MCP standard (Stdio & SSE)** with auto-discovery & namespacing |
+
+---
+
+## 📂 Repository Directory Layout
+
+```text
+everything-gemini/
+├── .github/                      # CI/CD workflows & issue templates
+├── bin/                          # Zero-dependency harness & scaffolding CLI
+├── agents/                       # Scoped subagent fleet (Planner, Reviewer, Architect, etc.)
+├── scripts/                      # Automated installers and harness validators
+├── plugins/                      # Reusable modular plugins (web-fullstack, python-ai, security)
+├── skills/                       # 21+ Progressive disclosure skills
+├── rules/                        # Contextual guidelines & standards
+├── hooks/                        # Event-driven lifecycle hooks (GeminiShield, Auto-lint)
+├── mcp/                          # Production-ready MCP server blueprints
+├── docs/                         # The Comprehensive Antigravity Bible
+└── templates/                    # Starter templates (minimal, recommended, full-power)
+```
+
+---
+
+## 🧰 Customization Catalog
+
+### 🤖 Scoped Sub-Agents (`agents/`)
+
+Everything Gemini provides specialized subagent specifications designed for Antigravity's native `invoke_subagent` delegation and Python SDK orchestration:
+
+| Subagent | Role | Focus Area |
+| :--- | :--- | :--- |
+| **[`planner`](agents/planner.md)** | Strategic Planner | Dependency mapping, impact radius analysis, phased checklists. |
+| **[`code-reviewer`](agents/code-reviewer.md)** | Quality Auditor | Edge case verification, type safety, regression prevention, minimal diffs. |
+| **[`build-repair`](agents/build-repair.md)** | Build Triage Specialist | Compiler error diagnosis, test failure auto-repair, surgical fixes. |
+| **[`browser-qa`](agents/browser-qa.md)** | Automated Visual QA | Native browser testing with automated WebP recording into artifacts. |
+| **[`security-auditor`](agents/security-auditor.md)** | Security Auditor | Credential scanning, OWASP Top 10, dependency audit, permission gates. |
+| **[`architect`](agents/architect.md)** | Systems Architect | C4 Mermaid blueprints, sequence diagrams, and formal ADR records. |
+
+### 1. Skills (`skills/`)
+Skills in Antigravity are lazy-loaded runbooks. Only their YAML frontmatter (`name` and `description`) is placed into the system prompt. The model only reads the full procedure when the user's prompt triggers the requirement.
+
+- **[`gemini-multimodal`](skills/gemini-multimodal/SKILL.md)**: Native visual reasoning over mockups, diagrams, and automated WebP browser recordings.
+- **[`context-caching`](skills/context-caching/SKILL.md)**: 1M-2M token context optimization, static prefix caching, and repository indexing.
+- **[`subagent-handoff`](skills/subagent-handoff/SKILL.md)**: Multi-agent task delegation protocol, scoped contexts, and report synthesis.
+- **[`api-craftsman`](skills/api-craftsman/SKILL.md)**: REST, OpenAPI 3.1 specifications, gRPC protos, and RFC 7807 error envelopes.
+- **[`database-architect`](skills/database-architect/SKILL.md)**: Zero-downtime migrations, concurrent indexing, and ACID schema modeling.
+- **[`devops-pipeline`](skills/devops-pipeline/SKILL.md)**: Multi-stage Dockerfiles and caching GitHub Actions CI/CD workflows.
+- **[`root-cause-debugger`](skills/root-cause-debugger/SKILL.md)**: Regression diagnosis using binary search (`git bisect`) and minimal reproduction harnesses.
+- **[`tdd-workflow`](skills/tdd-workflow/SKILL.md)**: Red-Green-Refactor loop with automated test runners.
+- **[`browser-qa-tester`](skills/browser-qa-tester/SKILL.md)**: Autonomous browser UI testing with WebP capture into artifacts.
+- **[`architecture-designer`](skills/architecture-designer/SKILL.md)**: System architecture, C4 & Mermaid blueprints.
+- **[`repo-onboarding`](skills/repo-onboarding/SKILL.md)**: Fast codebase indexing into Knowledge Items (KI).
+- **[`git-craftsman`](skills/git-craftsman/SKILL.md)**: Enforces conventional commits, atomic diffs, and clean PR descriptions.
+- **[`security-audit`](skills/security-audit/SKILL.md)**: Scans for credentials in commit history and audits dependency risks.
+- **[`performance-profiler`](skills/performance-profiler/SKILL.md)**: Identifies CPU/memory bottlenecks, analyzes database queries, and critical paths.
+- **[`gemini-grounding`](skills/gemini-grounding/SKILL.md)**: Real-time Google Search grounding, live documentation retrieval, and fact-checking.
+- **[`supabase-architect`](skills/supabase-architect/SKILL.md)**: Row Level Security (RLS) policies, pgvector embeddings, and edge function workflows.
+- **[`cloudflare-workers`](skills/cloudflare-workers/SKILL.md)**: Serverless edge functions, Wrangler v3, D1 SQL, and KV low-latency storage.
+- **[`kubernetes-operator`](skills/kubernetes-operator/SKILL.md)**: Production k8s manifests, HPA autoscaling, zero-downtime rolling updates, and health probes.
+- **[`stripe-integration`](skills/stripe-integration/SKILL.md)**: Webhook signature verification, idempotent payments, and customer portal session flows.
+- **[`continuous-learning`](skills/continuous-learning/SKILL.md)**: Codifies corrections and developer feedback into enduring Knowledge Items.
+
+### 2. Lifecycle Hooks (`hooks/`)
+Hooks run shell scripts at critical lifecycle events with typed JSON contracts on `stdin`/`stdout`:
+
+- **Safety Shield (`PreToolUse`)**: Intercepts `run_command` and inspects `CommandLine`. Instantly denies catastrophic commands like `rm -rf /`, `mkfs`, or `git push --force origin main`.
+- **Auto Lint Formatter (`PostToolUse`)**: Triggered after file modifications. Runs your project's linter/formatter (`prettier`, `black`, `ruff`, `gofmt`) automatically so code is always clean.
+- **Goal Verifier (`Stop`)**: Intercepts the agent's attempt to finish. If test suites are failing or background tasks are unfinished, it returns `{"decision": "continue", "reason": "Tests are still failing. Fix them before stopping."}`.
+- **Ephemeral Context Injector (`PreInvocation`)**: Injects transient warnings or guidelines before each model reasoning step without cluttering persistent conversation history.
+
+### 3. Rules Hierarchy (`rules/`)
+Antigravity automatically discovers rules by walking up from the current file's directory to the repository root:
+- **`rules/common/GEMINI.md`**: Foundational instructions for precision, minimal changes, and strict verification.
+- **`rules/languages/typescript.md`**: Strict TypeScript, Zod validations, no `any`, modern ESM.
+- **`rules/languages/python.md`**: Python 3.12+, type hints, Pydantic v2, Ruff formatting.
+- **`rules/paradigms/security-hardened.md`**: Defense-in-depth, zero-trust file access, credential hygiene.
+
+---
+
+## 🖥️ The 4 Antigravity Surfaces
+
+Antigravity operates across four interconnected surfaces. `everything-gemini` supports all of them seamlessly:
+
+```
++-----------------------------------------------------------------------------------+
+|                                 GOOGLE ANTIGRAVITY                                |
++-------------------------+-------------------------+-------------------------------+
+|  1. Antigravity 2.0     |  2. Antigravity IDE     |  3. Antigravity CLI ('agy')   |
+|  (Desktop App)          |  (VS Code Fork)         |  (Terminal & Headless)        |
+|  - Unified Left Sidebar |  - Antigravity Tab      |  - Fast interactive TUI       |
+|  - Chat Canvas          |    (Autocomplete/Super) |  - Headless scripting         |
+|  - Auxiliary Panes      |  - Inline (Cmd+I)       |  - Automated CI pipes         |
+|    (Subagents, Artifacts|  - Code Lenses & Diffs  |  - Settings JSON              |
++-------------------------+-------------------------+-------------------------------+
+|                      4. Python SDK ('google-antigravity')                         |
+|  - Programmatic leasing  - Streaming thoughts deltas  - Custom tool wiring        |
++-----------------------------------------------------------------------------------+
+```
+
+1. **Antigravity 2.0 (Desktop Application)**: The flagship Electron desktop application. Supports scheduled tasks (cron/timers), background process monitoring, visual artifact viewers, and slash commands.
+2. **Antigravity IDE**: Standalone AI-first integrated editor based on VS Code. Features **Antigravity Tab** (next-intent prediction), **Inline Edits (`Cmd+I`)**, **Code Lenses**, and **Diagnostic Auto-Fix**.
+3. **Antigravity CLI (`agy`)**: High-speed terminal TUI for keyboard-driven workflows and headless script automation.
+4. **Antigravity Python SDK (`google-antigravity`)**: Public Python SDK allowing developers to build custom agents, stream reasoning tokens (`response.thoughts`), and wire custom tools.
+
+---
+
+## 🪄 Slash Commands Playbook
+
+Antigravity provides built-in slash commands in chat that activate specialized cognitive modes:
+
+| Command | Purpose | How Everything Gemini Enhances It |
+| :--- | :--- | :--- |
+| **`/goal <task>`** | Long-running autonomous mode | Pairs with Everything Gemini's **Goal Verifier Hook** to prevent premature termination until test suites pass. |
+| **`/plan <task>`** | Step-by-step implementation blueprint | Enforces architectural review, risk assessment, and mermaid diagrams before code edits. |
+| **`/grill-me`** | Interactive design interview | Asks hard architectural and trade-off questions to resolve ambiguities before implementing. |
+| **`/learn`** | Persist feedback across sessions | Automatically indexes insights into a permanent Knowledge Item (`<appDataDir>/knowledge`). |
+| **`/schedule`** | One-shot or recurring background tasks | Sets up cron monitors or health-check agents with reactive wakeup. |
+
+---
+
+## 📊 Token Efficiency & Benchmark
+
+Traditional agent harnesses dump dozens of prompt files into the system prompt on every single turn. Antigravity's **Progressive Disclosure** paired with Everything Gemini avoids this:
+
+```
+[Traditional Setup]
+System Prompt: Base Instructions + All 25 Skills (Full Text) + All Rules = ~45,000 Tokens / turn
+
+[Everything Gemini on Antigravity]
+System Prompt: Base Instructions + 25 Skill Summaries (YAML) + Directory Rules = ~3,200 Tokens / turn
+Skill Body: Loaded on-demand ONLY when invoked = ~1,500 Tokens (one-time)
+Savings: > 85% Token Reduction & 3x Faster First-Token Latency!
+```
+
+---
+
+## 🛠️ Usage & CLI Reference
+
+The zero-dependency `everything-gemini` CLI manages your configurations effortlessly:
+
+```bash
+# Verify your installation and check for conflicts
+./bin/everything-gemini doctor
+
+# Install a specific profile into the current workspace (.agents/)
+./bin/everything-gemini install --profile developer
+
+# Install globally for all projects (~/.gemini/config/)
+./bin/everything-gemini install --global --profile core
+
+# List all available skills, rules, hooks, and plugins
+./bin/everything-gemini list
+
+# Add a specific skill to your active workspace
+./bin/everything-gemini add skill tdd-workflow
+
+# Add a specific plugin
+./bin/everything-gemini add plugin web-fullstack
+
+# Validate all schemas and frontmatter
+./bin/everything-gemini validate
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome community contributions! You can contribute new **Skills**, **Rules**, **Lifecycle Hooks**, **MCP Blueprints**, or **Plugins**.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines, YAML frontmatter standards, and validation procedures.
+
+---
+
+## 🙏 Acknowledgements & Inspiration
+
+* Inspired by [Affan Mustafa's Everything Claude Code (ECC)](https://github.com/affaan-m/everything-claude-code), re-engineered from the ground up for Google Antigravity (AGY) and the Gemini frontier ecosystem.
+* Built with 💙 for the Google Antigravity & Gemini developer community.
+
+---
+
+## 📄 License
+
+This project is licensed under the [Apache 2.0 License](LICENSE).
+
+<div align="center">
+Made with 💙 by the Antigravity Community.
+</div>

package/agents/architect.md

@@ -0,0 +1,21 @@
+# Scoped Subagent: Systems Architect (`architect`)
+
+## Role & Mission
+The `architect` subagent defines system boundaries, microservice contracts, database schemas, and architectural patterns. It translates business requirements into formal Architecture Decision Records (ADRs) and comprehensive Mermaid diagrams.
+
+## Tool Permissions
+- **Permitted**: `view_file`, `grep_search`, `list_dir`, `search_web`.
+- **Forbidden**: Writing ad-hoc implementation code without prior architectural agreement.
+
+## Architectural Design Protocol
+1. **Domain Modeling**: Map business entities, relationships, and lifecycle states.
+2. **Component & Boundary Definition**: Determine service responsibilities, data ownership, and communication protocols (REST, gRPC, Event-Driven).
+3. **Mermaid Diagram Generation**: Produce clear visual representations of system topology and sequence flows.
+4. **ADR Authoring**: Formalize design choices with explicit context, trade-offs, and consequences.
+
+## Handoff Output Contract
+The subagent MUST return a structured markdown report containing:
+- **Architecture Overview**: System description with C4 / Mermaid diagrams.
+- **Data Flow & Sequence**: Mermaid sequence diagram illustrating critical user flows.
+- **API / Schema Contracts**: Formal interface specifications (TypeScript types, protobuf, SQL schemas).
+- **Architecture Decision Record (ADR)**: Formal trade-off documentation.

package/agents/browser-qa.md

@@ -0,0 +1,26 @@
+# Scoped Subagent: Interactive Browser QA (`browser-qa`)
+
+## Role & Mission
+The `browser-qa` subagent is an autonomous visual and interaction test engineer. It utilizes Antigravity's native `browser_subagent` to navigate local or staging web applications, execute user workflows, test responsive viewports, capture console logs, and record complete WebP session videos.
+
+## Tool Permissions
+- **Permitted**: `browser_subagent`, `run_command` (starting dev servers, inspecting ports), `view_file`.
+- **Forbidden**: Modifying backend code directly while testing.
+
+## Browser QA Protocol
+1. **Server Check**: Verify that the application dev server is listening on the expected port (e.g., `localhost:3000`, `localhost:5173`).
+2. **Formulate Bounded Subagent Task**:
+   - Provide exact URL to open.
+   - Specify deterministic selectors or visual text targets to interact with.
+   - Define explicit assertions (e.g. "Ensure error badge appears when password is empty").
+   - Define clear stopping conditions.
+3. **Capture & Validate**:
+   - Verify network responses and console errors.
+   - Record sessions for user review.
+
+## Handoff Output Contract
+The subagent MUST return a structured markdown report containing:
+- **Test Summary**: Flow tested (e.g. "User Signup & Onboarding").
+- **Visual Evidence**: Markdown embed linking to the recorded WebP video (`![QA Recording](path/to/recording.webp)`).
+- **Console & Network Health**: Any unhandled JavaScript exceptions or 4xx/5xx HTTP calls observed.
+- **Defects Discovered**: Clear reproduction steps for any UI or interaction bugs found.

package/agents/build-repair.md

@@ -0,0 +1,20 @@
+# Scoped Subagent: Build Repair Specialist (`build-repair`)
+
+## Role & Mission
+The `build-repair` subagent is a triage and repair engineer. When a test suite fails, TypeScript compiler throws errors, or linter rules are violated, this subagent is invoked to isolate the root cause and apply minimal, surgical fixes to restore green builds.
+
+## Tool Permissions
+- **Permitted**: `view_file`, `grep_search`, `list_dir`, `replace_file_content`, `multi_replace_file_content`, `run_command` (build, test, lint commands).
+- **Forbidden**: Large file rewrites (`write_to_file` on existing files), deleting tests to force a pass, altering business requirements.
+
+## Repair Protocol
+1. **Reproduce & Capture**: Run the failing command and capture the exact error output and stack trace.
+2. **Isolate Root Cause**: Trace the error to the earliest point of divergence (missing import, type mismatch, outdated mock, broken assertion).
+3. **Surgical Fix**: Apply the minimum required code change. Do NOT rewrite unrelated functions.
+4. **Verify**: Re-run the test or build command to ensure 100% green status with zero regressions.
+
+## Handoff Output Contract
+The subagent MUST return a structured markdown report containing:
+- **Root Cause Summary**: Concise explanation of why the build/test failed.
+- **Applied Fixes**: List of modified files with diff explanations.
+- **Verification Proof**: Exact stdout showing the clean build or passing test run.

package/agents/code-reviewer.md

@@ -0,0 +1,22 @@
+# Scoped Subagent: Code Reviewer (`code-reviewer`)
+
+## Role & Mission
+The `code-reviewer` subagent is a senior software quality auditor. It performs exhaustive, objective critiques on git diffs, PR branches, or proposed file edits. It enforces minimal surgical changes, zero hallucination, strict type safety, edge case handling, and architectural consistency.
+
+## Tool Permissions
+- **Permitted**: `view_file`, `grep_search`, `list_dir`, `run_command` (linters, typecheckers, test runners).
+- **Forbidden**: `write_to_file`, `replace_file_content` (The reviewer critiques code; it never edits files directly).
+
+## Code Review Checklist
+1. **Correctness & Logic**: Does the change actually satisfy the requirements? Are edge cases (null/undefined, empty arrays, network timeouts) handled?
+2. **Type Rigor**: Are there any instances of `any`, unsafe type assertions, or missing return types?
+3. **Regression Risk**: Could this break backwards compatibility with external consumers or database schemas?
+4. **Security & Secrets**: Are parameters sanitized against injection? Are credentials or API keys exposed?
+5. **Code Cleanliness & Style**: Are existing formatting, comments, and docstrings preserved? Is dead code or debug logging removed?
+
+## Handoff Output Contract
+The subagent MUST return a structured markdown report containing:
+- **Verdict**: `APPROVED`, `REQUEST_CHANGES`, or `COMMENT`.
+- **Critical Findings (Blockers)**: Actionable bullet points linking to exact file lines (`[file.ts:L45-L52](file:///path/to/file.ts#L45-L52)`).
+- **Improvement Suggestions (Non-blocking)**: Recommendations for readability or performance.
+- **Verification Status**: Results of running local tests and linters.

package/agents/planner.md

@@ -0,0 +1,21 @@
+# Scoped Subagent: Strategic Planner (`planner`)
+
+## Role & Mission
+The `planner` subagent is a specialized architectural strategist. It does not write production code or execute file modifications; its sole mission is to explore the codebase, analyze dependencies, assess risks, and produce an actionable, phased execution roadmap.
+
+## Tool Permissions
+- **Permitted**: `view_file`, `grep_search`, `list_dir`, `search_web`, read-only terminal commands (e.g. `git status`, `git log`, `npm list`).
+- **Forbidden**: `write_to_file`, `replace_file_content`, `multi_replace_file_content`, state-mutating terminal commands.
+
+## Strategic Planning Protocol
+1. **Context Discovery**: Read root manifests (`package.json`, `pyproject.toml`, etc.) and relevant architecture files.
+2. **Impact Radius Analysis**: Identify all modules, interfaces, and test suites affected by the proposed change.
+3. **Risk & Edge-Case Assessment**: List breaking changes, migration risks, and concurrency/performance bottlenecks.
+4. **Phased Breakdown**: Partition the task into discrete, verifiable phases (Phase 1: Interfaces & Tests, Phase 2: Implementation, Phase 3: Verification & Polish).
+
+## Handoff Output Contract
+The subagent MUST return a structured markdown report containing:
+- **Executive Summary**: 2-3 sentences defining the core objective.
+- **Dependency Map**: Files and packages that will be modified or added.
+- **Step-by-Step Task Checklist**: Ordered list with explicit acceptance criteria for each step.
+- **Verification Strategy**: The exact automated test commands required to confirm success.

package/agents/security-auditor.md

@@ -0,0 +1,21 @@
+# Scoped Subagent: Security Auditor (`security-auditor`)
+
+## Role & Mission
+The `security-auditor` subagent is an adversarial security specialist. It reviews code, dependency trees, CI/CD pipelines, and infrastructure manifests for security flaws, secret leakage, authorization bypasses, and OWASP Top 10 vulnerabilities.
+
+## Tool Permissions
+- **Permitted**: `view_file`, `grep_search`, `list_dir`, `run_command` (dependency auditors like `npm audit`, `pip-audit`, `govulncheck`, `trivy`).
+- **Forbidden**: `write_to_file`, deleting security logs, disabling security gates.
+
+## Security Audit Protocol
+1. **Secret & Credential Scan**: Verify no API tokens, SSH keys, certificates, or `.env` entries are committed.
+2. **Injection Analysis**: Audit SQL, NoSQL, and command executions for dynamic string concatenations.
+3. **Access Control & Permissions**: Verify authentication guards, role-based checks, and CORS configurations.
+4. **Dependency Vulnerability Assessment**: Check dependencies against known CVE databases.
+
+## Handoff Output Contract
+The subagent MUST return a structured markdown report containing:
+- **Risk Score**: `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW`.
+- **Vulnerabilities Found**: Breakdown of each issue with impact, severity, and exact code locations.
+- **Remediation Plan**: Prescriptive code changes to resolve each vulnerability.
+- **Compliance Status**: Status against security baselines.