# 🏭 Agent-Kit (V3.6) — The Hybrid AI Arsenal

> <!-- SEO METADATA FOR GITHUB ARCHITECTURE SEARCH -->
> <!-- keywords: google antigravity, model context protocol, mcp server, cursor agent, claude desktop, windsurf, copilot, autonomous agents, multi-agent framework, semantic memory, tree-of-thought, ai ide augmentation, developer tools, local-first ai -->

## The Ultimate MCP Server that supercharges Google Antigravity, Cursor, Claude Desktop, and Windsurf

> _You are a CTO with 54 autonomous AI employees acting as a native extension to your IDE._

[![Version](https://img.shields.io/badge/v3.5-stable-7C3AED?style=for-the-badge&logo=semver&logoColor=white)](https://www.npmjs.com/package/@ab_aswini/agent-kit-p1) [![Agents](https://img.shields.io/badge/54_Agents-9_Departments-06B6D4?style=for-the-badge&logo=dependabot&logoColor=white)](https://github.com/Ab-aswini/Agent-kit-P1) [![NPM](https://img.shields.io/badge/NPM-Install-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@ab_aswini/agent-kit-p1) [![License](https://img.shields.io/badge/MIT-License-10B981?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](LICENSE) [![Stars](https://img.shields.io/github/stars/Ab-aswini/Agent-kit-P1?style=for-the-badge&color=F59E0B&logo=github)](https://github.com/Ab-aswini/Agent-kit-P1)

```text
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│    ⚡ npx @ab_aswini/agent-kit-p1 init                      │
│                                                             │
│    ↳ That's it. Your 54-agent AI company is now deployed.   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## 📋 Table of Contents

|  #  | Section                                                        | What You'll Learn                                     |
| :-: | :------------------------------------------------------------- | :---------------------------------------------------- |
|  1  | [🧩 What Is Agent-Kit?](#-what-is-agent-kit)                   | The big picture — why this exists                     |
|  2  | [💡 The Problem We Solve](#-the-problem-we-solve)              | The pain point and how we fix it                      |
|  3  | [🏗️ How It Works — Architecture](#️-how-it-works--architecture) | The governance model, layers, and control flow        |
|  4  | [👥 Meet Your Team — 54 Agents](#-meet-your-team--54-agents)   | Every department, every agent, every role             |
|  5  | [🎨 UI&UX Intelligence Engine](#-uiux-intelligence-engine)     | The built-in design brain with 18 domains & 16 stacks |
|  6  | [🚦 The Iron Well Protocol](#-the-iron-well-protocol)          | How governance actually works step-by-step            |
|  7  | [⚡ Install & Setup](#-install--setup)                         | Every way to install + first steps                    |
|  8  | [🎯 Company Archetypes](#-company-archetypes)                  | Choose your team size from 14 to 54 agents            |
|  9  | [⚙️ Tech Stack](#️-tech-stack)                                  | What's under the hood                                 |
| 10  | [🛡️ Security & Privacy](#️-security--privacy)                   | How safety is enforced at every layer                 |
| 11  | [🚢 Deployment Pipeline](#-deployment-pipeline)                | From your IDE to NPM to the end user                  |
| 12  | [🗺️ Roadmap](#️-roadmap)                                        | What's coming next                                    |
| 13  | [🤝 Contributing](#-contributing)                              | How to add agents, skills, or datasets                |
| 14  | [📄 License](#-license)                                        | MIT — fully open                                      |

---

## 🧩 What Is Agent-Kit?

**Agent-Kit is an NPM package that turns any project directory into an AI-powered software company.**

When you run `npx @ab_aswini/agent-kit-p1 init`, it creates a **zero-footprint** global store and drops a single `.agentkit` pointer file in your project. The global store contains:

```text
your-project/
├── .agent-os/                    ← The AI Operating System
│   ├── agents/                   ← 54 AI agent definitions (.md files)
│   │   ├── tier-1/               ← Executive council (CTS, SFS, SP, RC)
│   │   ├── engineering/          ← Backend, Frontend, Database, Mobile, Game
│   │   ├── qa/                   ← Testing, coverage, regression
│   │   ├── security/             ← Threat modeling, pen testing
│   │   ├── product/              ← PRDs, UX research, README architect
│   │   ├── devops/               ← CI/CD, Docker, monitoring
│   │   ├── intelligence/         ← Legacy archaeology, research
│   │   ├── marketing-growth/     ← SEO/GEO, brand authority
│   │   └── meta/                 ← Memory, loops, permissions
│   │
│   ├── skills/                   ← 69+ reusable skill modules
│   │   ├── clean-code/           ← Code quality standards
│   │   ├── api-patterns/         ← REST/GraphQL conventions
│   │   ├── database-design/      ← Schema, migration patterns
│   │   ├── page-cro/             ← Conversion Rate Optimization
│   │   ├── schema-markup/        ← SEO JSON-LD implementation
│   │   ├── testing-patterns/     ← TDD, pyramid, coverage
│   │   └── ... 63 more (Including 25 Advanced Marketing Skills)
│   │
│   ├── .shared/
│   │   └── UI&UX/                ← Design intelligence engine
│   │       ├── data/             ← 18 domain CSVs (styles, colors, etc.)
│   │       │   └── stacks/       ← 16 framework-specific CSVs
│   │       └── scripts/          ← BM25 search engine + design generator
│   │
│   ├── workflows/                ← 19 pre-built SOPs (create, debug, deploy...)
│   ├── rules/                    ← Universal rules, Socratic Gate, GEMINI config
│   ├── templates/                ← 12 company archetype configurations
│   ├── hub-logic.md              ← Central intelligence hub
│   └── manifest.json             ← Master registry of all 54 agents
│
├── scripts/                      ← Automation scripts
│   ├── checklist.py              ← 360° project health audit
│   ├── spawn_agent.py            ← Generate system prompts for any agent
│   ├── security_chaos_test.py    ← Simulated attack testing
│   └── sync_api_contracts.py     ← Backend-frontend contract alignment
│
├── memory/                       ← Persistent context across sessions
│   ├── global/                   ← Architecture, decisions, conventions
│   ├── backend/                  ← Backend-specific context
│   ├── frontend/                 ← Frontend-specific context
│   └── product/                  ← Product-specific context
│
└── bin/cli.js                    ← CLI entry point
```

**Every `.md` file is an agent definition** — a detailed protocol document that tells your AI IDE (whether you use **Google Antigravity**, **Cursor**, **VS Code + GitHub Copilot**, **Windsurf**, or **Claude Desktop**) exactly how to behave for a specific role. When you tell your AI assistant to "read the backend specialist agent", it loads that agent's rules, boundaries, skills, and decision frameworks.

**🚀 V3.6 Features: Native MCP Server + Self-Test + Multi-Model**
Agent-Kit now runs natively as a **Model Context Protocol (MCP)** server with **6 tools**: `list_agents`, `get_agent_prompt`, `query_ui_ux_engine`, `run_memory_sync`, `run_checklist`, and `run_security_chaos`. It also ships with a `self-test` command to run all diagnostics, supports `AGENT_KIT_MODEL` env var for multi-model routing, and logs all agent actions.

> [!IMPORTANT]
> **The Supportive Office Philosophy**: Agent-Kit does **not** require external LLM APIs (no OpenAI/Anthropic keys needed). It acts as a **Supportive Office** for your IDE's native AI (Copilot, Gemini, Claude). You provide the built-in IDE LLM; Agent-Kit provides the company structure, the rules, the memory, and the tools so the LLM can complete the work smarter.

---

## 💡 The Problem We Solve

Building production software requires coordinated expertise across many domains:

```mermaid
%%{init: {'theme': 'default'}}%%

flowchart LR
  subgraph NEED["What Production Software Needs"]
    direction TB
    A["🏗️ Architecture"]
    B["🔧 Backend APIs"]
    C["🎨 Frontend UI"]
    D["🗄️ Database Design"]
    E["🧪 Testing & QA"]
    F["🛡️ Security Audit"]
    G["🎯 Product Strategy"]
    H["🚀 DevOps & CI/CD"]
    I["📱 Mobile Development"]
    J["📢 SEO & Marketing"]
  end

  subgraph WITHOUT["Without Agent-Kit"]
    direction TB
    X["😰 One dev doing everything"]
    Y["💸 Hire 10+ specialists"]
    Z["🐛 Gaps in coverage"]
  end

  subgraph WITH["With Agent-Kit"]
    direction TB
    W["🏭 54 AI specialists"]
    V["🛡️ Governed by Iron Well"]
    U["⚡ Zero hiring cost"]
  end

  NEED --> WITHOUT
  NEED --> WITH

  style X fill:#EF4444,stroke:#DC2626,color:#fff,stroke-width:2px
  style Y fill:#EF4444,stroke:#DC2626,color:#fff,stroke-width:2px
  style Z fill:#EF4444,stroke:#DC2626,color:#fff,stroke-width:2px
  style W fill:#10B981,stroke:#047857,color:#fff,stroke-width:2px
  style V fill:#10B981,stroke:#047857,color:#fff,stroke-width:2px
  style U fill:#10B981,stroke:#047857,color:#fff,stroke-width:2px
```

**The typical solo developer** writes code, tests improperly, skips security audits, struggles with UX, and deploys with crossed fingers.

**Agent-Kit gives you a full company:**

| Role                | Agent      | What It Actually Does                                              |
| :------------------ | :--------- | :----------------------------------------------------------------- |
| CTO                 | CTS-001    | Reviews every decision, enforces architecture, has merge authority |
| Lead Developer      | SFS-001    | Orchestrates multi-file tasks, routes work to specialists          |
| Strategist          | SP-001     | Creates milestone plans before any code is written                 |
| Risk Officer        | RC-001     | Flags compliance issues, evaluates trade-offs                      |
| 10 Backend Devs     | BE-001→010 | API design, auth, microservices, caching, queues                   |
| 9 Frontend Devs     | FE-001→009 | Components, state management, animations, a11y, asset architecture |
| 5 DB Engineers      | DB-001→005 | Schema design, migrations, query optimization                      |
| 6 QA Engineers      | QA-001→006 | Unit tests, integration, E2E, regression                           |
| Security Specialist | SEC-001    | OWASP compliance, vulnerability scanning                           |
| 6 DevOps Engineers  | DO-001→006 | Docker, CI/CD, monitoring, deployment                              |
| Product Manager     | PM-001     | PRDs, user stories, acceptance criteria                            |
| UX Researcher       | PM-002     | Usability analysis, design patterns                                |
| README Architect    | RA-001     | Documentation generation (that's me!)                              |
| SEO+AEO Specialist  | MKT-001    | SERAPH: Technical SEO, schema markup, AEO, search submission       |
| Intel Agent         | INTEL-001  | Legacy code analysis, deep research                                |
| 4 Meta Agents       | MM-001→004 | Memory management, loop detection, permissions                     |

---

## 🏗️ How It Works — Architecture

### The Governance Model

Agent-Kit uses a **military-style chain of command** called the **Iron Well Protocol**. No agent can go rogue — every action flows through approval gates.

```mermaid
%%{init: {'theme': 'default'}}%%

graph TD
  subgraph HUMAN["🧑‍💻 YOU — THE OWNER"]
    H(("👤 Developer"))
  end

  subgraph EXECUTIVE["🏛️ TIER 1 — EXECUTIVE COUNCIL"]
    SFS["🎯 SFS-001 (Orchestrator)"]
    CTS["👑 CTS-001 (Supervisor)"]
    SP["📋 SP-001 (Planner)"]
    RC["⚖️ RC-001 (Risk & Compliance)"]
  end

  subgraph DEPARTMENTS["⚡ TIER 2 — 9 SPECIALIZED DEPARTMENTS"]
    direction LR
    ENG["🔧 Engineering (26)"]
    QA["🧪 QA (6)"]
    SEC["🛡️ Security (1)"]
    PROD["📦 Product (5)"]
    DX["🚀 DevOps (6)"]
    INTEL["🔍 Intel (1)"]
    MKT["📢 Marketing (1)"]
  end

  subgraph META["🧠 TIER 3 — META-MANAGEMENT"]
    MM["🧠 Memory + Loops + Permissions"]
  end

  subgraph INTELLIGENCE["🎨 SHARED INTELLIGENCE LAYER"]
    UX["🎨 UI&UX Engine"]
  end

  H -->|"📝 You give a task"| SFS
  SFS -->|"🚦 Socratic Gate:<br/>3 strategic questions"| H
  H -->|"✅ You answer"| SFS
  SFS -->|"📋 Creates plan"| SP
  SP -->|"📄 milestones.md"| SFS
  SFS -->|"📤 Delegates to specialists"| DEPARTMENTS
  DEPARTMENTS -->|"🧪 Submit for review"| QA
  QA -->|"✔️ Approval"| CTS
  CTS -->|"🚀 Final delivery"| H

  META -.->|"🔗 Context sync"| DEPARTMENTS
  INTELLIGENCE -.->|"🎨 Design data"| DEPARTMENTS

  style H fill:#10B981,stroke:#047857,stroke-width:3px,color:#fff
  style SFS fill:#7C3AED,stroke:#5B21B6,stroke-width:2px,color:#fff
  style CTS fill:#7C3AED,stroke:#5B21B6,stroke-width:2px,color:#fff
  style SP fill:#8B5CF6,stroke:#6D28D9,stroke-width:2px,color:#fff
  style RC fill:#8B5CF6,stroke:#6D28D9,stroke-width:2px,color:#fff
  style ENG fill:#2563EB,stroke:#1D4ED8,stroke-width:2px,color:#fff
  style QA fill:#06B6D4,stroke:#0891B2,stroke-width:2px,color:#fff
  style SEC fill:#EF4444,stroke:#DC2626,stroke-width:2px,color:#fff
  style PROD fill:#F59E0B,stroke:#D97706,stroke-width:2px,color:#000
  style DX fill:#EC4899,stroke:#DB2777,stroke-width:2px,color:#fff
  style INTEL fill:#14B8A6,stroke:#0D9488,stroke-width:2px,color:#fff
  style MKT fill:#F97316,stroke:#EA580C,stroke-width:2px,color:#fff
  style MM fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
  style UX fill:#F59E0B,stroke:#D97706,stroke-width:3px,color:#000
```

### The Anti-Hallucination Protocol (The 4 Core Constraints)

To ensure Agent-Kit operates with zero hallucinations and grounded intelligence, all 54 agents rigidly adhere to the **4 Core Constraints** (enforced globally in `universal-rules.agent.md`):

1. **RAG (Retrieval-Augmented Generation)**: Dynamic connection to project docs, databases, and APIs.
2. **Source Grounding**: Every answer must be tied to a documented source. Absolute rule: "If no reliable source exists, I don't have enough information to answer."
3. **Confidence Thresholds**: If confidence is low, agents abstain and ask clarifying questions instead of guessing.
4. **Post-Response Validation**: Self-correction checks for factual errors, rule violations, format issues, and safety before returning the final plan or code.

### The Four Layers

Every component in Agent-Kit lives in one of four layers:

```mermaid
%%{init: {'theme': 'default'}}%%

graph TD
  subgraph L4["🖥️ LAYER 4 — INTERFACE  (How You Interact)"]
    CLI["⌨️ CLI Commands"]
    IDE["💻 AI IDE (Cursor / Windsurf)"]
    NPX["📦 NPX/NPM"]
  end

  subgraph L3["🎛️ LAYER 3 — ORCHESTRATION  (How Agents Coordinate)"]
    GATE["🚦 Socratic Gate"]
    PHASE["⚡ 2-Phase Engine"]
    GOV["👑 Tiered Authority"]
    WF["📋 19 Workflows"]
  end

  subgraph L2["🧠 LAYER 2 — INTELLIGENCE  (How Agents Think)"]
    BM25["🔍 BM25 Search Engine"]
    DSG["🎨 Design System Generator"]
    REASON["💡 Reasoning Engine"]
    SPAWN["🤖 Agent Spawner"]
  end

  subgraph L1["💾 LAYER 1 — DATA  (What Agents Know)"]
    AGENTS["📄 54 Agent Protocols"]
    SKILLS["🧩 69+ Skill Modules"]
    CSV["📊 34 CSV Datasets"]
    MEM["🧠 Memory Hubs"]
  end

  L4 --> L3
  L3 --> L2
  L2 --> L1

  style CLI fill:#7C3AED,stroke:#5B21B6,stroke-width:2px,color:#fff
  style IDE fill:#8B5CF6,stroke:#6D28D9,stroke-width:2px,color:#fff
  style NPX fill:#A78BFA,stroke:#7C3AED,stroke-width:2px,color:#fff
  style GATE fill:#EF4444,stroke:#DC2626,stroke-width:2px,color:#fff
  style PHASE fill:#EC4899,stroke:#DB2777,stroke-width:2px,color:#fff
  style GOV fill:#F43F5E,stroke:#E11D48,stroke-width:2px,color:#fff
  style WF fill:#FB7185,stroke:#F43F5E,stroke-width:2px,color:#fff
  style BM25 fill:#F59E0B,stroke:#D97706,stroke-width:2px,color:#000
  style DSG fill:#F97316,stroke:#EA580C,stroke-width:2px,color:#fff
  style REASON fill:#FBBF24,stroke:#F59E0B,stroke-width:2px,color:#000
  style SPAWN fill:#FCD34D,stroke:#FBBF24,stroke-width:2px,color:#000
  style AGENTS fill:#10B981,stroke:#047857,stroke-width:2px,color:#fff
  style SKILLS fill:#06B6D4,stroke:#0891B2,stroke-width:2px,color:#fff
  style CSV fill:#14B8A6,stroke:#0D9488,stroke-width:2px,color:#fff
  style MEM fill:#2DD4BF,stroke:#14B8A6,stroke-width:2px,color:#000
```

---

## 👥 Meet Your Team — 54 Agents

### Executive Council (Tier 1)

These four agents govern everything. They are loaded first, always active, and have the highest authority.

| Agent                              | ID      | Authority | Core Responsibility                                                                            |
| :--------------------------------- | :------ | :-------- | :--------------------------------------------------------------------------------------------- |
| 👑 **Chief Technical Supervisor**  | CTS-001 | Highest   | Architecture authority, merge control, final approval on all deployments and DB changes        |
| 🎯 **Senior Full Stack Developer** | SFS-001 | High      | Primary orchestrator — routes all tasks, activates the Socratic Gate, delegates to departments |
| 📋 **Strategy Planner**            | SP-001  | High      | Creates milestone plans, defines task breakdowns, manages the 4-phase planning methodology     |
| ⚖️ **Risk & Compliance**           | RC-001  | High      | Evaluates risks, flags compliance issues, assesses cost/benefit trade-offs                     |

### Engineering Department (26 Agents)

| Sub-Division    | Agents | ID Range   | What They Build                                                                                                           |
| :-------------- | :----: | :--------- | :------------------------------------------------------------------------------------------------------------------------ |
| 🔧 **Backend**  |   10   | BE-001→010 | REST/GraphQL APIs, authentication (JWT, OAuth), microservices, caching, message queues, middleware                        |
| 🎨 **Frontend** |   9    | FE-001→009 | React/Next.js/Vue components, state management, routing, responsive design, animations, accessibility, asset architecture |
| 🗄️ **Database** |   5    | DB-001→005 | Schema design, Prisma/TypeORM migrations, query optimization, indexing, data modeling                                     |
| 📱 **Mobile**   |   1    | MOB-001    | React Native, Flutter, platform-native iOS/Android                                                                        |
| 🎮 **Game**     |   1    | GAME-001   | Game mechanics, physics engines, cross-platform game development                                                          |

### Support Departments

| Department               | Lead      | Agents | Focus                                                                                            |
| :----------------------- | :-------- | :----: | :----------------------------------------------------------------------------------------------- |
| 🧪 **QA & Verification** | QA-001    |   6    | Unit tests (Jest, Pytest), integration tests, E2E (Playwright), regression, code coverage audits |
| 🛡️ **Security**          | SEC-001   |   1    | OWASP Top 10 scanning, dependency auditing, threat modeling, shift-left security practices       |
| 📦 **Product & Docs**    | PM-001    |   5    | PRDs, user stories, acceptance criteria, UX research, README generation                          |
| 🚀 **DevOps**            | DO-001    |   6    | Docker containerization, CI/CD pipelines, cloud deployment, monitoring, infrastructure-as-code   |
| 🔍 **Intelligence**      | INTEL-001 |   1    | Legacy codebase archaeology, deep technical research, knowledge extraction                       |
| 📢 **Marketing**         | MKT-001   |   1    | SERAPH: Technical SEO, schema markup, AEO, search engine submission                              |
| 🧠 **Meta-Management**   | MM-001    |   4    | Memory file management, infinite loop detection, permission boundary enforcement                 |

---

## 🎨 UI&UX Intelligence Engine

The **UI&UX Engine** is Agent-Kit's built-in design brain. It's a Python-powered intelligence layer that gives every agent instant access to **600,000+ data points** of structured design knowledge.

### How It Works

When any agent needs design guidance (colors, typography, layout, component patterns, accessibility, dark mode), it queries the UI&UX Engine:

```mermaid
%%{init: {'theme': 'default'}}%%

flowchart TD
  Q["🔍 Agent asks: SaaS dashboard..."] --> DD["🧭 Domain Detector"]
  DD --> BM["⚡ BM25 Search Engine"]
  BM --> D1["📚 18 Domain CSVs"]
  BM --> D2["📦 16 Stack CSVs"]
  D1 --> DSG["🎨 Design System Generator"]
  D2 --> DSG
  DSG --> OUT["✅ Complete Design System Output"]

  style Q fill:#7C3AED,stroke:#5B21B6,stroke-width:2px,color:#fff
  style DD fill:#2563EB,stroke:#1D4ED8,stroke-width:2px,color:#fff
  style BM fill:#06B6D4,stroke:#0891B2,stroke-width:2px,color:#fff
  style D1 fill:#EC4899,stroke:#DB2777,stroke-width:2px,color:#fff
  style D2 fill:#F97316,stroke:#EA580C,stroke-width:2px,color:#fff
  style DSG fill:#F59E0B,stroke:#D97706,stroke-width:3px,color:#000
  style OUT fill:#10B981,stroke:#047857,stroke-width:3px,color:#fff
```

### The 18 Search Domains

Every design question maps to one or more of these knowledge bases:

> ### 18 Search Domains
>
> 1. 🎭 **Styles** (1,000+) - CSS patterns, layout systems, spacing scales, shadows, borders
> 2. 🎨 **Colors** (1,200+) - Color palettes, contrast ratios, semantic color systems, brand guidelines
> 3. 🔤 **Typography** (800+) - Font stacks, type scales, line heights, responsive typography
> 4. 🏠 **Landing Pages** (2,400+) - Hero sections, CTAs, social proof patterns, conversion layouts
> 5. 🛍️ **Products** (1,500+) - Product cards, galleries, filtering patterns, cart UX
> 6. 📊 **Charts** (400+) - Data visualization, chart types, color coding for data
> 7. ✨ **Icons** (2,000+) - Icon systems, sizing conventions, accessibility for icons
> 8. 🧩 **UX Guidelines** (700+) - Interaction patterns, micro-interactions, user flow best practices
> 9. 🌐 **Web Interfaces** (500+) - Navigation, sidebars, modals, toast notifications
> 10. ⚛️ **React Performance** (800+) - Memoization, lazy loading, virtual lists, bundle optimization
> 11. 💬 **Prompts** (1,800+) - AI prompt templates for design decisions
> 12. 💡 **UI Reasoning** (1,200+) - Why certain designs work — backed by data
> 13. 🎬 **Animations** (500+) - Transition curves, duration guidelines, motion principles
> 14. ♿ **Accessibility** (600+) - WCAG 2.1, ARIA patterns, screen reader support
> 15. 🌙 **Dark Mode** (400+) - Dark theme strategies, color inversion rules, contrast in dark
> 16. 🤖 **AI Patterns** (400+) - AI-native UI components, chat interfaces, loading states
> 17. 📝 **Forms** (500+) - Form validation UX, multi-step wizards, input patterns
> 18. ⚠️ **Error States** (400+) - Error messages, empty states, fallback UI, retry patterns

### The 16 Framework Stacks

Framework-specific guidance with 15-column schema including **2026-ready columns:**

> ### 16 Framework Stacks & Data Schema
>
> **Stack Includes:** ⚛️ React, ▲ Next.js, 💚 Vue, 💚 Nuxt, 🔥 Svelte, 🅰️ Angular, 🚀 Astro, 💿 Remix, 🦀 Tauri, 💙 Flutter, 🍎 SwiftUI, 📱 React Native, 🤖 Jetpack Compose, 🧩 shadcn, 🌊 Tailwind, 💚 Nuxt UI
>
> **Columns Include:** `Component_Name`, `Category`, `Use_Case`, `Code_Example`, `Accessibility_Score`, `Dark_Mode_Strategy`, `AI_Integration_Level`, `Privacy_Tier`, `Agent_Readiness`, `Performance_Budget`
>
> [!NOTE]
> **2026 Columns Explained:**
>
> - `Dark_Mode_Strategy` — How to implement dark mode for each component
> - `AI_Integration_Level` — How AI-ready the component is (chat, voice, generative)
> - `Privacy_Tier` — GDPR/CCPA/HIPAA compliance tier
> - `Agent_Readiness` — Whether the component works with AI agent workflows
> - `Performance_Budget` — Max acceptable load time / bundle size

---

## 🚦 The Iron Well Protocol

This is the governance system that prevents chaos. Every complex task goes through this exact flow:

```mermaid
%%{init: {'theme': 'default'}}%%

sequenceDiagram
  autonumber
  actor Dev as 🧑‍💻 You (Developer)
  participant SFS as 🎯 SFS-001<br/>Orchestrator
  participant GATE as 🚦 Socratic Gate
  participant SP as 📋 SP-001<br/>Planner
  participant ENG as 🔧 Engineering<br/>Agent(s)
  participant UX as 🎨 UI&UX Engine
  participant QA as 🧪 QA Agent(s)
  participant CTS as 👑 CTS-001<br/>Supervisor

  Dev->>SFS: "Build a user dashboard with real-time analytics"

  Note over SFS,GATE: PHASE 0 — SOCRATIC GATE (Mandatory)
  SFS->>Dev: Question 1: What data sources feed the dashboard?
  Dev->>SFS: PostgreSQL + WebSocket events
  SFS->>Dev: Question 2: Who are the users — admins or end users?
  Dev->>SFS: Admin users only, internal tool
  SFS->>Dev: Question 3: Any compliance constraints?
  Dev->>SFS: SOC 2 — no PII displayed

  Note over SFS,SP: PHASE 1 — PLANNING (No Code Allowed)
  SFS->>SP: Create milestone plan
  SP-->>SFS: milestones.md with task breakdown
  SFS->>Dev: Here is the plan — approve?
  Dev->>SFS: ✅ Approved with one change
  SFS->>SP: Update plan
  SP-->>SFS: Updated milestones.md

  Note over SFS,QA: PHASE 2 — EXECUTION (Code Allowed)
  SFS->>ENG: Execute: Build dashboard API
  ENG->>UX: Need design system for admin dashboard
  UX-->>ENG: Color palette + typography + component patterns
  ENG->>ENG: Implementing API + frontend + tests
  ENG->>QA: Ready for review

  Note over QA,CTS: VERIFICATION
  QA->>QA: Run checklist.py audit
  QA-->>CTS: All checks passed ✅
  CTS->>Dev: 🚀 Dashboard delivered — ready for deployment
```

### What the Socratic Gate Actually Does

The Socratic Gate is **not optional**. For any complex request (build, create, implement, refactor), the AI must ask **at least 3 strategic questions** before writing a single line of code.

| Question Type   | Purpose                        | Example                                                         |
| :-------------- | :----------------------------- | :-------------------------------------------------------------- |
| **Scope**       | Prevent scope creep            | "Should this dashboard also handle reporting export?"           |
| **Users**       | Clarify audience               | "Is this for technical admins or business stakeholders?"        |
| **Constraints** | Surface hidden requirements    | "Any regulatory compliance? GDPR? SOC 2?"                       |
| **Trade-offs**  | Explore alternatives           | "Real-time via WebSockets or polling every 30s?"                |
| **Edge Cases**  | Prevent bugs before they exist | "What happens when the data source is temporarily unavailable?" |

> [!TIP]
> **Why this matters:** Most AI coding tools just start building. Agent-Kit forces clarity first. The result: fewer rewrites, no misunderstandings, and production-quality output from the start.

---

## ⚡ Install & Setup

### Method 1: Quick Start (Recommended)

The fastest way — one command, zero configuration:

```bash
npx @ab_aswini/agent-kit-p1 init
```

This scaffolds the complete agent system into a **zero-footprint global store** — only a `.agentkit` pointer file touches your project. All 54 agents, 42+ skills, 19 workflows, and the UI&UX engine are deployed.

This is the core of the V3.6 **Hybrid Arsenal** philosophy. Agent-Kit does not try to be an LLM IDE; instead, it is the ultimate super-weapon _for_ your IDE.

By running the MCP server, you give Cursor/Claude access to Agent-Kit's powerful internal Python tools:

- `list_agents` / `get_agent_prompt` — Query and generate system prompts for any of 54 agents
- `run_checklist` — Cursor can natively trigger `checklist.py` to ensure your project complies with Iron Well architecture standards
- `run_security_chaos` — Cursor can trigger the Security Chaos Monkey to scan for exposed secrets and risky patterns
- `query_ui_ux_engine` — Cursor can query the internal BM25 search engine to pull complete, enterprise-grade Design Systems
- `run_memory_sync` — Auto-generate `architecture.md`, `api-contracts.md`, `dependencies.md`

**The Workflow:**
You tell Cursor: _"Audit my project using Agent-Kit."_
Cursor hits our MCP server → Agent-Kit runs the Python audit on your local files → Cursor reads the output and fixes the code for you.

### Method 2: Dev Dependency

```bash
npm install --save-dev @ab_aswini/agent-kit-p1

```

Then add a setup script:

```json
{
  "scripts": {
    "setup:agents": "agent-kit init",
    "health": "agent-kit doctor"
  }
}
```

### Method 3: Interactive Mode (Choose Your Team)

Don't need all 54 agents? Pick a company archetype:

```bash
npx @ab_aswini/agent-kit-p1 init --interactive
```

This walks you through an interactive menu to select your project type (SaaS, Mobile, E-commerce, etc.) and deploys only the agents you need.

### Method 4: Add to package.json

```bash
npm install --save-dev @ab_aswini/agent-kit-p1
```

Then add a setup script:

```json
{
  "scripts": {
    "setup:agents": "agent-kit init",
    "health": "agent-kit doctor"
  }
}
```

### 🔌 Method 5: Native MCP Server (Google Antigravity / Cursor / Claude)

Agent-Kit can run as a **Model Context Protocol (MCP)** server, securely attaching all 54 agents directly to your IDE.

**For Google Antigravity & Cursor:** Add this to your MCP Settings:

- Name: `Agent-Kit`
- Type: `command`
- Command: `npx @ab_aswini/agent-kit-p1 mcp`

**For Claude Desktop:** Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agent-kit": {
      "command": "npx",
      "args": ["@ab_aswini/agent-kit-p1", "mcp"]
    }
  }
}
```

_Tools exposed natively to your AI:_ `list_agents`, `get_agent_prompt`, `query_ui_ux_engine`, `run_memory_sync`, `run_checklist`, `run_security_chaos`.

### 🩺 Health Check

After installation, verify everything is in place:

```bash
npx @ab_aswini/agent-kit-p1 doctor
```

This validates: agent files exist, directory structure is correct, manifest is consistent, and skills are properly linked.

### 🎬 First Steps After Install

| Step | Command / Action                                                                     | What Happens                                                           |
| :--: | :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
|  1   | Open project in **Google Antigravity / Cursor / Windsurf**                           | Your AI IDE is ready                                                   |
|  2   | Tell your AI: _"Read `.agent-os/agents/tier-1/chief-technical-supervisor.agent.md`"_ | CTS-001 activates as your technical authority                          |
|  3   | Run `python scripts/checklist.py`                                                    | Validates full project health                                          |
|  4   | Run `python scripts/spawn_agent.py BE-001`                                           | Generates a ready-to-paste system prompt for Backend Agent 001         |
|  5   | Start building                                                                       | Tell your AI what to build — the Socratic Gate activates automatically |

### 📖 Full CLI Reference

| Command                                              | Description                                                                                                     |
| :--------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| `agent-kit init`                                     | Deploy all 54 agents, skills, workflows, and UI&UX engine                                                       |
| `agent-kit init -i` / `agent-kit init --interactive` | Interactive archetype selection (choose your team size)                                                         |
| `agent-kit doctor`                                   | Validate system health and flag missing components                                                              |
| `agent-kit clean`                                    | Remove legacy zero-footprint migration artifacts                                                                |
| `agent-kit chat`                                     | Launch the interactive Command-Trigger REPL                                                                     |
| `agent-kit run "prompt"`                             | **[V3.5]** Execute a task via the orchestration engine with action logging                                      |
| `agent-kit sync`                                     | **[V3]** Run a one-shot Semantic Memory Sync — updates `architecture.md`, `api-contracts.md`, `dependencies.md` |
| `agent-kit sync --watch`                             | **[V3]** Watch mode — auto-re-syncs agent memory every 5s when project files change                             |
| `agent-kit self-test`                                | **[V3.5]** Run all 3 diagnostics (memory sync + security chaos + health check) with unified report              |
| `agent-kit mcp`                                      | **[V3]** Start the Model Context Protocol (MCP) server for native Cursor / Claude Desktop integration           |

### 💬 Command-Trigger REPL (Slash Commands)

Run `npx @ab_aswini/agent-kit-p1 chat` to open an interactive session. You can type natural language or use slash commands to instantly route context to specialized agents:

| Command     | Agent Triggered | Core Responsibility                                                                                |
| :---------- | :-------------- | :------------------------------------------------------------------------------------------------- |
| `/help`     | _System_        | List available commands                                                                            |
| `/fix`      | QA-001          | Analyzes errors/code for logical flaws and proposes precise fixes                                  |
| `/test`     | QA-001          | Writes comprehensive, edge-case resilient unit/integration tests                                   |
| `/refactor` | BE-001          | Optimizes code for efficiency, readability, and SOLID principles                                   |
| `/plan`     | SP-001          | Decomposes a request into a granular, step-by-step milestone plan                                  |
| `/seo`      | MKT-001         | **[V3.5]** Triggers SERAPH SEO+AEO agent for technical SEO, schema markup, and search optimization |
| _(default)_ | SFS-001         | Standard orchestrator routing for general inquiries                                                |

> [!IMPORTANT]
> **Requirements:** Node.js 16+ and npm 7+. Python 3.8+ is needed for the UI&UX engine and audit scripts.

---

## 🎯 Company Archetypes

When you run `agent-kit init --interactive`, you choose from **12 pre-configured company archetypes**. Each archetype deploys a curated subset of agents, skills, and departments tailored to your project type.

```mermaid
%%{init: {'theme': 'default'}}%%

flowchart TD
  START(("🏗️ Choose Your Company")) --> S["🚀 SaaS Startup (44)"]
  START --> M["📱 Mobile App (26)"]
  START --> EC["🛒 E-commerce (45)"]
  START --> P["🖼️ Portfolio (14)"]
  START --> D["📊 Dashboard (29)"]
  START --> B["📝 Blog / CMS (21)"]
  START --> ED["🎓 EdTech (32)"]
  START --> HC["🏥 Healthcare (40)"]
  START --> MP["🏪 Marketplace (47)"]
  START --> AI["🤖 AI / ChatBot (30)"]
  START --> G["🎮 Gaming (23)"]
  START --> API["⚙️ API-First (33)"]

  style START fill:#7C3AED,stroke:#5B21B6,stroke-width:3px,color:#fff
  style S fill:#2563EB,stroke:#1D4ED8,stroke-width:2px,color:#fff
  style M fill:#EC4899,stroke:#DB2777,stroke-width:2px,color:#fff
  style EC fill:#F97316,stroke:#EA580C,stroke-width:2px,color:#fff
  style P fill:#10B981,stroke:#047857,stroke-width:2px,color:#fff
  style D fill:#06B6D4,stroke:#0891B2,stroke-width:2px,color:#fff
  style B fill:#14B8A6,stroke:#0D9488,stroke-width:2px,color:#fff
  style ED fill:#8B5CF6,stroke:#7C3AED,stroke-width:2px,color:#fff
  style HC fill:#EF4444,stroke:#DC2626,stroke-width:2px,color:#fff
  style MP fill:#F59E0B,stroke:#D97706,stroke-width:2px,color:#000
  style AI fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
  style G fill:#84CC16,stroke:#65A30D,stroke-width:2px,color:#000
  style API fill:#FBBF24,stroke:#F59E0B,stroke-width:2px,color:#000
```

### What Each Archetype Includes

> ### The 12 Pre-Configured Archetypes
>
> - 🚀 **SaaS Startup** (44 Agents) — Engineering (full), Security, QA, Product, DevOps, Meta
> - 📱 **Mobile App** (26 Agents) — Engineering (mobile + backend), QA, Product, Meta
> - 🛒 **E-commerce** (45 Agents) — Engineering (full), Security, QA, Product, DevOps, Marketing, Meta
> - 🖼️ **Portfolio** (14 Agents) — Engineering (frontend), Product, Meta
> - 📊 **Dashboard** (29 Agents) — Engineering (backend + frontend + DB), QA, Meta
> - 📝 **Blog / CMS** (21 Agents) — Engineering (frontend + backend), Product, Marketing, Meta
> - 🎓 **EdTech** (32 Agents) — Engineering (full), QA, Product, Meta
> - 🏥 **Healthcare** (40 Agents) — Engineering (full), Security, QA, Product, DevOps, Meta
> - 🏪 **Marketplace** (47 Agents) — Engineering (full), Security, QA, Product, DevOps, Marketing, Meta
> - 🤖 **AI / ChatBot** (30 Agents) — Engineering (backend + frontend), Intelligence, QA, Meta
> - 🎮 **Gaming** (23 Agents) — Engineering (game + frontend), QA, Meta
> - ⚙️ **API-First** (33 Agents) — Engineering (backend + DB), Security, QA, DevOps, Meta [!TIP]
>   **Start small, scale up.** You can always run `agent-kit init` later to upgrade to the full 54-agent fleet. The CLI is additive — it won't overwrite existing agents.

---

## ⚙️ Tech Stack

|          Layer          | Technology                      | Purpose                                                                                |
| :---------------------: | :------------------------------ | :------------------------------------------------------------------------------------- |
|   📦 **Distribution**   | NPM / NPX                       | One-command installation, versioning, global installs                                  |
|       ⌨️ **CLI**        | Node.js + fs-extra + picocolors | Init scaffolding, doctor validation, interactive archetype menu                        |
| 🏗️ **Agent Protocols**  | Markdown (.md) + JSON manifests | Agent definitions with identity, rules, boundaries, anti-patterns                      |
|  🔍 **Search Engine**   | Python + custom BM25            | Full-text search over 34 CSV datasets with tokenization and IDF weighting              |
| 🎨 **Design Generator** | Python + CSV + JSON             | Multi-domain aggregation → automated design system output                              |
|  🔐 **Auth Reference**  | FastAPI + Bcrypt + JWT          | Production-ready authentication template for backend agents                            |
|   ✔️ **Audit Engine**   | `checklist.py` (Python)         | Priority-ordered health validation: Security → Lint → Schema → Tests → UX → SEO        |
|  🧠 **Memory System**   | Structured Markdown             | Persistent project context: architecture.md, decisions.md, conventions.md, risk-log.md |
|    📋 **Workflows**     | Markdown SOPs                   | 19 pre-built standard operating procedures with step-by-step execution                 |

---

## 🛡️ Security & Privacy

Agent-Kit enforces security through **seven distinct mechanisms**:

|  #  | Mechanism                      | How It Works                                                                                                                          |
| :-: | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
|  1  | 🚦 **Socratic Gate**           | Forces 3+ strategic questions before any complex task — prevents the AI from acting on misunderstood requirements                     |
|  2  | 👑 **Tiered Authority (RBAC)** | 4-tier access control: Owner → Executive → Department → Meta. No agent can exceed its tier permissions                                |
|  3  | 🛡️ **Iron Well 2-Phase**       | Phase 1 = planning only (no code). Phase 2 = execution only (plan must be approved first). No mixing.                                 |
|  4  | 🔒 **Privacy Columns**         | Every CSV dataset includes `Privacy_Tier` (GDPR, CCPA, HIPAA levels), consent-before-track patterns, and data minimization guidelines |
|  5  | 🔍 **SEC-001 Agent**           | Dedicated security specialist that performs threat modeling, dependency auditing, and OWASP Top 10 scanning                           |
|  6  | 🐒 **Chaos Testing**           | `security_chaos_test.py` simulates real-world attack vectors against your codebase to find vulnerabilities proactively                |
|  7  | 📡 **API Contract Sync**       | `sync_api_contracts.py` ensures backend API responses match what the frontend expects — preventing integration bugs at deploy time    |

### CTS-001 Approval Checklist

Before any code reaches production, CTS-001 verifies:

```text
✅ Code follows project conventions
✅ No security vulnerabilities introduced
✅ Performance impact is acceptable
✅ Tests are adequate (unit + integration)
✅ Documentation is updated
✅ Memory files are current
✅ No permission boundaries violated
```

---

## 🚢 Deployment Pipeline

From your IDE to your end user's project:

```mermaid
%%{init: {'theme': 'default'}}%%

flowchart LR
  DEV["🧑‍💻 Developer"] -->|"git push"| GH["🐙 GitHub Repo"]
  GH -->|"CI triggers"| LINT["🔍 Lint & Type Check"]
  LINT -->|"pass"| TEST["🧪 Component Tests"]
  TEST -->|"pass"| AUDIT["✔️ checklist.py Audit"]
  AUDIT -->|"✅ all pass"| VSN["📋 Version Bump"]
  VSN --> PUB["📦 npm publish"]
  PUB --> USER["🚀 End User (npx init)"]

  AUDIT -->|"❌ fail"| DEV

  style DEV fill:#6366F1,color:#fff,stroke:#4F46E5,stroke-width:2px
  style GH fill:#7C3AED,color:#fff,stroke:#5B21B6,stroke-width:2px
  style LINT fill:#2563EB,color:#fff,stroke:#1D4ED8,stroke-width:2px
  style TEST fill:#06B6D4,color:#fff,stroke:#0891B2,stroke-width:2px
  style AUDIT fill:#F59E0B,color:#000,stroke:#D97706,stroke-width:2px
  style VSN fill:#EC4899,color:#fff,stroke:#DB2777,stroke-width:2px
  style PUB fill:#10B981,color:#fff,stroke:#047857,stroke-width:3px
  style USER fill:#7C3AED,color:#fff,stroke:#5B21B6,stroke-width:3px
```

---

## 🗺️ Roadmap

| Initiative               |   Status   | Description                                                                                           |
| :----------------------- | :--------: | :---------------------------------------------------------------------------------------------------- |
| 🏪 **Agent Marketplace** | 🔜 Planned | Community-contributed agent templates, skills, and CSV datasets                                       |
| 🔀 **Multi-LLM Router**  | 🔜 Planned | Assign different AI models to different agents (GPT for planning, Claude for code, Gemini for design) |
| 📊 **Live Dashboard**    | 🔜 Planned | Web-based fleet monitoring through the orchestrator                                                   |

---

## 🧠 The Agent-Kit Architecture (V3.6+)

> [!IMPORTANT]
> **The Hybrid Arsenal Pivot**
> Agent-Kit V3.6 introduces four distinct intelligence pillars designed to **augment** your existing IDE AI (like **Google Antigravity**, Cursor, Copilot, or Windsurf), rather than compete with them.

1. **Pillar 1: Native MCP Server** — Agent-Kit integrates directly into your AI IDE as an active tool server with 6 tools.
2. **Pillar 2: The Hybrid Arsenal** — Provides active validation (`checklist.py`), security chaos testing, and UI generation scripts that your IDE AI can trigger autonomously.
3. **Pillar 3: Semantic Project Memory** — Live AST-aware codebase scanning that updates agent ground-truth over time (`architecture.md`, `api-contracts.md`, etc.).
4. **Pillar 4: Self-Test Loop** — `self-test` command runs all 3 diagnostics and produces a unified health report, enabling the system to audit itself.

---

## 🤝 Contributing

Agent-Kit is fully modular — every agent, skill, and dataset is an independent file. Contributing is straightforward.

### Add a New Agent

1. Create `your-agent.agent.md` in `.agent-os/agents/<department>/`
2. Follow the standard template:
   - **Identity** — Agent ID, tier, role description
   - **Protocol** — Step-by-step operational procedure
   - **Boundaries** — What files it can read/write
   - **Anti-Patterns** — Common mistakes to avoid
3. Register in `manifest.json` under the appropriate department
4. Submit a PR with a description of the agent's purpose

### Add a New Skill

1. Create `.agent-os/skills/your-skill/SKILL.md`
2. Add YAML frontmatter with `name` and `description`
3. Include helper scripts in `scripts/` and examples in `examples/` if applicable

### Add a New CSV Dataset

1. Add your CSV file:
   - **Domain CSVs** → `.agent-os/.shared/UI&UX/data/your-domain.csv`
   - **Stack CSVs** → `.agent-os/.shared/UI&UX/data/stacks/your-stack.csv`
2. Register it in `scripts/core.py` → `CSV_CONFIG` or `STACK_CONFIG`
3. Add detection keywords to `detect_domain()` so the BM25 engine can auto-route queries

### Workflow

```text
Fork → Branch → Implement → Test → PR → Review → Merge
```

---

## 📄 License

This project is licensed under the **MIT License** — see [LICENSE](LICENSE) for details.

---

> ### 🏭 Built for solo developers who think like companies
>
> **54 agents · 42+ skills · 19 workflows · 18 design domains · 16 framework stacks**
>
> **Iron Well v2.0 governance · BM25 search · Socratic Gate · 12 company archetypes**
>
> [![Install via NPM](https://img.shields.io/badge/📦_Install_via_NPM-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@ab_aswini/agent-kit-p1) [![View on GitHub](https://img.shields.io/badge/🐙_View_on_GitHub-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/Ab-aswini/Agent-kit-P1) [![Report Issue](https://img.shields.io/badge/🐛_Report_Issue-EF4444?style=for-the-badge)](https://github.com/Ab-aswini/Agent-kit-P1/issues)
>
> ⭐ **If Agent-Kit helps your workflow, star this repo — it helps others find it.**