Agent-kit-P1

  ╔══════════════════════════════════════════════════════════════════╗
  ║                                                                  ║
  ║   ⚡  npx @ab_aswini/agent-kit-p1 init                          ║
  ║                                                                  ║
  ║   Done. Your 54-agent AI company is live.                        ║
  ║                                                                  ║
  ║   🏭 54 Agents  ·  🧩 69+ Skills  ·  📋 19 Workflows            ║
  ║   🎨 600K+ Design Data Points  ·  🛡️ Iron Well Governance        ║
  ║                                                                  ║
  ╚══════════════════════════════════════════════════════════════════╝

---

#	Section	What You'll Learn
1	The Pitch	Why this exists — the 30-second story
2	Quick Start	From zero to 54 agents in 60 seconds
3	How It Works	The governance model, layers, and control flow
4	Meet Your Team	Every department, every agent, every role
5	UI&UX Intelligence Engine	The built-in design brain with 23 domains & 16 stacks
6	The Iron Well Protocol	How governance actually works step-by-step
7	Install & Setup (All Methods)	Every way to install + MCP config
8	Company Archetypes	Choose your team size from 14 to 54 agents
9	Tech Stack	What's under the hood
10	Security & Privacy	How safety is enforced at every layer
11	Deployment Pipeline	From your IDE to NPM to the end user
12	Roadmap	What's coming next
13	Contributing	How to add agents, skills, or datasets
14	License	MIT — fully open

---

🎯 The Pitch — Why Agent-Kit?

😰 Without Agent-Kit

You: "Build me a dashboard"
AI:  *immediately starts coding*
     *wrong architecture*
     *no tests*
     *security holes*
     *3 rewrites later...*

🏭 With Agent-Kit

You: "Build me a dashboard"
AI:  → Socratic Gate: 3 strategic questions
     → Strategy Planner creates milestones
     → Backend + Frontend + DB agents execute
     → QA validates, Security audits
     → CTO approves final delivery ✅

Agent-Kit gives your IDE's AI something it never had: a company structure.

You become the CTO. Your AI becomes 54 specialized employees — each with defined roles, boundaries, skills, and a chain of command. No more single-brain AI chaos.

The Key Insight

Your IDE already has a powerful AI brain (Copilot, Gemini, Claude). What it doesn't have is:

Missing Piece	Agent-Kit Provides
🏛️ Governance	Iron Well Protocol — military-grade chain of command
🧠 Memory	Persistent architecture, decisions, and conventions across sessions
👥 Specialization	54 agents with distinct expertise, not one generalist
🚦 Quality Gates	Mandatory planning before coding, mandatory review after
🎨 Design Intelligence	600K+ data points across 23 design domains
🔐 Security	Built-in threat modeling, chaos testing, OWASP scanning

[!IMPORTANT] Zero API Keys Required. Agent-Kit is NOT another LLM wrapper. It's a Supportive Office for your IDE's native AI. You provide the brain (Copilot, Gemini, Claude); Agent-Kit provides the company (structure, rules, memory, tools).

---

🚀 Quick Start

60-Second Setup

# Step 1: Deploy your AI company (one command)
npx @ab_aswini/agent-kit-p1 init

# Step 2: Verify everything works
npx @ab_aswini/agent-kit-p1 doctor

# Step 3: Open in your AI IDE and start building
# Tell your AI: "Read the CTS-001 agent and audit this project"

What Just Happened?

your-project/
├── .agentkit              ← Tiny pointer file (only thing in your project)
└── ~/.agent-kit-store/    ← Global store (zero-footprint)
    ├── 54 Agent protocols
    ├── 69+ Skill modules
    ├── 19 Workflow SOPs
    ├── 34 CSV datasets (600K+ data points)
    ├── Memory system
    └── MCP server ready

Connect to Your IDE

Add to MCP Settings:

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

Add to claude_desktop_config.json:

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

Load the agent definitions from .agent-os/agents/ into your workspace context. The MCP server works with any MCP-compatible extension.

6 MCP Tools exposed to your AI: list_agents · get_agent_prompt · query_ui_ux_engine · run_memory_sync · run_checklist · run_security_chaos

---

🏗️ How It Works — Architecture

The Company Org Chart

The 4 Anti-Hallucination Constraints

Every agent operates under these iron rules (enforced in universal-rules.agent.md):

#	Constraint	What It Means
1	RAG	Dynamic retrieval from project docs, databases, and APIs
2	Source Grounding	Every answer tied to a documented source — "If no source exists, I don't know"
3	Confidence Thresholds	Low confidence → ask questions, never guess
4	Post-Response Validation	Self-correction before returning any output

The Four Layers

---

👥 Meet Your Team — 54 Agents

🏛️ Executive Council (Tier 1)

Agent	ID	What They Do
👑 Chief Technical Supervisor	CTS-001	Architecture authority, merge control, final approval
🎯 Senior Full Stack Developer	SFS-001	Primary orchestrator — routes all tasks, runs Socratic Gate
📋 Strategy Planner	SP-001	Creates milestone plans, task breakdowns
⚖️ Risk & Compliance	RC-001	Evaluates risks, flags compliance issues

🔧 Engineering Department — 26 Agents

Division	Count	IDs	Specialization
Backend	10	BE-001→010	REST/GraphQL APIs, auth (JWT, OAuth), microservices, caching, queues
Frontend	9	FE-001→009	React/Next.js/Vue, state management, animations, a11y, responsive
Database	5	DB-001→005	Schema design, Prisma/TypeORM, query optimization, indexing
Mobile	1	MOB-001	React Native, Flutter, native iOS/Android
Game	1	GAME-001	Game mechanics, physics engines, cross-platform

🏢 Support Departments

Department	Lead	Agents	Focus
🧪 QA & Verification	QA-001	6	Unit (Jest/Pytest), integration, E2E (Playwright), regression
🛡️ Security	SEC-001	1	OWASP Top 10, dependency audit, threat modeling
📦 Product & Docs	PM-001	5	PRDs, user stories, UX research, README generation
🚀 DevOps	DO-001	6	Docker, CI/CD, cloud deploy, monitoring, IaC
🔍 Intelligence	INTEL-001	1	Legacy codebase archaeology, deep research
📢 Marketing	MKT-001	1	SERAPH: Technical SEO, schema markup, AEO
🧠 Meta-Management	MM-001	4	Memory sync, loop detection, permission enforcement

---

🎨 UI&UX Intelligence Engine

The design brain of Agent-Kit — a Python BM25 search engine over 600,000+ structured data points across 23 domains.

#	Domain	Data Points	What It Covers
1	🎭 Styles	1,000+	CSS patterns, layout systems, spacing, shadows, borders
2	🎨 Colors	1,200+	Palettes, contrast ratios, semantic color systems
3	🔤 Typography	800+	Font stacks, type scales, responsive typography
4	🏠 Landing Pages	2,400+	Hero sections, CTAs, social proof, conversion layouts
5	🛍️ Products	1,500+	Product cards, galleries, filtering, cart UX
6	📊 Charts	400+	Data visualization, chart types, color coding
7	✨ Icons	2,000+	Icon systems, sizing, accessibility
8	🧩 UX Guidelines	700+	Interaction patterns, micro-interactions
9	🌐 Web Interfaces	500+	Navigation, sidebars, modals, toasts
10	⚛️ React Performance	800+	Memoization, lazy loading, virtual lists
11	💬 Prompts	1,800+	AI prompt templates for design decisions
12	💡 UI Reasoning	1,200+	Why certain designs work — data-backed
13	🎬 Animations	500+	Transition curves, duration, motion principles
14	♿ Accessibility	600+	WCAG 2.1, ARIA patterns, screen reader support
15	🌙 Dark Mode	400+	Dark theme strategies, color inversion rules
16	🤖 AI Patterns	400+	AI-native UI, chat interfaces, loading states
17	📝 Forms	500+	Validation UX, multi-step wizards, inputs
18	⚠️ Error States	400+	Error messages, empty states, fallback UI
19	🗺️ Navigation	500+	Sidebars, breadcrumbs, tabs, pagination, search, drawers
20	📊 Data Tables	600+	Sorting, filtering, virtual scroll, inline edit, export
21	🔐 Auth UI	350+	Login, signup, MFA, OAuth, session management, recovery
22	🛒 Checkout & Payment	400+	Cart, payment forms, shipping, trust signals, recovery
23	📱 Mobile Patterns	500+	Touch targets, gestures, bottom sheets, safe areas, haptics

⚛️ React · ▲ Next.js · 💚 Vue · 💚 Nuxt · 🔥 Svelte · 🅰️ Angular · 🚀 Astro · 💿 Remix · 🦀 Tauri · 💙 Flutter · 🍎 SwiftUI · 📱 React Native · 🤖 Jetpack Compose · 🧩 shadcn · 🌊 Tailwind · 💚 Nuxt UI

Each stack CSV includes 15 columns with 2026-ready fields: Component_Name · Category · Use_Case · Code_Example · Accessibility_Score · Dark_Mode_Strategy · AI_Integration_Level · Privacy_Tier · Agent_Readiness · Performance_Budget

---

🚦 The Iron Well Protocol

The governance system that prevents AI chaos. Every complex task follows this exact flow:

What Makes the Socratic Gate Different

Most AI tools just start coding. Agent-Kit forces clarity first.

Question Type	Purpose	Example
Scope	Prevent scope creep	"Should this also handle export?"
Users	Clarify audience	"Technical admins or business users?"
Constraints	Surface hidden requirements	"GDPR? SOC 2? HIPAA?"
Trade-offs	Explore alternatives	"WebSockets or polling?"
Edge Cases	Prevent bugs before code	"What if the data source is down?"

[!TIP] The result: fewer rewrites, no misunderstandings, production-quality output from the start.

---

📦 Install & Setup (All Methods)

Method 1: Quick Start (Recommended)

npx @ab_aswini/agent-kit-p1 init

Method 2: Dev Dependency

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

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

Method 3: Interactive Mode (Choose Your Team)

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

Method 4: Native MCP Server

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

📖 Full CLI Reference

Command	Description
agent-kit init	Deploy all 54 agents, skills, workflows, and UI&UX engine
agent-kit init -i	Interactive archetype selection
agent-kit doctor	Validate system health
agent-kit clean	Remove legacy artifacts
agent-kit chat	Launch Command-Trigger REPL
agent-kit run "prompt"	Execute a task via orchestration engine
agent-kit sync	Run Semantic Memory Sync
agent-kit sync --watch	Watch mode — auto-sync every 5s
agent-kit self-test	Run all 3 diagnostics with unified report
agent-kit mcp	Start MCP server for IDE integration

💬 Slash Commands (REPL)

Command	Agent	What It Does
/fix	QA-001	Analyze errors, propose precise fixes
/test	QA-001	Write comprehensive test suites
/refactor	BE-001	Optimize for SOLID principles
/plan	SP-001	Decompose into milestone plan
/seo	MKT-001	SERAPH SEO+AEO optimization

[!IMPORTANT] Requirements: Node.js 16+ · npm 7+ · Python 3.8+ (for UI&UX engine and audit scripts)

---

🎯 Company Archetypes

Run agent-kit init --interactive to choose your team:

Archetype	Agents	Departments Included
🚀 SaaS Startup	44	Engineering (full), Security, QA, Product, DevOps, Meta
📱 Mobile App	26	Engineering (mobile + backend), QA, Product, Meta
🛒 E-commerce	45	Engineering (full), Security, QA, Product, DevOps, Marketing, Meta
🖼️ Portfolio	14	Engineering (frontend), Product, Meta
📊 Dashboard	29	Engineering (backend + frontend + DB), QA, Meta
📝 Blog / CMS	21	Engineering (frontend + backend), Product, Marketing, Meta
🎓 EdTech	32	Engineering (full), QA, Product, Meta
🏥 Healthcare	40	Engineering (full), Security, QA, Product, DevOps, Meta
🏪 Marketplace	47	Engineering (full), Security, QA, Product, DevOps, Marketing, Meta
🤖 AI / ChatBot	30	Engineering (backend + frontend), Intelligence, QA, Meta
🎮 Gaming	23	Engineering (game + frontend), QA, Meta
⚙️ API-First	33	Engineering (backend + DB), Security, QA, DevOps, Meta

Start small, scale up. 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 install, versioning
⌨️ CLI	Node.js + fs-extra + picocolors	Init, doctor, interactive menus
🏗️ Protocols	Markdown + JSON manifests	Agent definitions with rules & boundaries
🔍 Search	Python + custom BM25	Full-text search over 34 CSV datasets
🎨 Design	Python + CSV + JSON	Multi-domain design system generation
🔐 Auth Template	FastAPI + Argon2 + JWT	Reference auth implementation
✔️ Audit	checklist.py (Python)	Security → Lint → Schema → Tests → UX → SEO
🧠 Memory	Structured Markdown	Persistent context: architecture, decisions, conventions
📋 Workflows	Markdown SOPs	19 pre-built standard operating procedures

---

🛡️ Security & Privacy

#	Mechanism	How It Works
1	🚦 Socratic Gate	3+ strategic questions before any complex task
2	👑 Tiered Authority	4-tier RBAC: Owner → Executive → Department → Meta
3	🛡️ Iron Well 2-Phase	Phase 1 = plan only. Phase 2 = execute only. No mixing.
4	🔒 Privacy Columns	Every CSV includes GDPR/CCPA/HIPAA compliance tiers
5	🔍 SEC-001	Dedicated agent for threat modeling & OWASP scanning
6	🐒 Chaos Testing	security_chaos_test.py simulates attack vectors
7	📡 API Contract Sync	Ensures backend responses match frontend expectations

✅ 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

---

🗺️ Roadmap

Initiative	Status	Description
🏪 Agent Marketplace	🔜 Planned	Community-contributed agent templates and skills
🔀 Multi-LLM Router	🔜 Planned	Assign different AI models to different agents
📊 Live Dashboard	🔜 Planned	Web-based fleet monitoring
🔌 Plugin System	💡 Exploring	Third-party tool integrations
🌍 i18n Agents	💡 Exploring	Internationalization-aware agent protocols

---

🧠 The V3.6 Architecture Pillars

[!IMPORTANT] The Hybrid Arsenal Philosophy — Agent-Kit augments your IDE's AI, it doesn't replace it.

Pillar	What It Does
1. Native MCP Server	Integrates directly into your IDE with 6 tools
2. Hybrid Arsenal	Active validation, chaos testing, UI generation
3. Semantic Memory	Live AST-aware codebase scanning, auto-updating ground truth
4. Self-Test Loop	Unified diagnostics — the system audits itself

---

🤝 Contributing

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

1. Create your-agent.agent.md in .agent-os/agents/<department>/
2. Follow the template: Identity → Protocol → Boundaries → Anti-Patterns
3. Register in manifest.json
4. Submit a PR

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

1. Add CSV to .agent-os/.shared/UI&UX/data/ (domain) or data/stacks/ (framework)
2. Register in scripts/core.py → CSV_CONFIG or STACK_CONFIG
3. Add detection keywords to detect_domain()

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

---

📄 License

MIT — see LICENSE for details.

---

🏭 Built for solo developers who think like companies.

54 agents · 69+ skills · 19 workflows · 23 design domains · 16 framework stacks Iron Well v2.0 governance · BM25 search · Socratic Gate · 12 archetypes

If Agent-Kit helps your workflow, give it a ⭐ — it helps others discover it.