# CloudTeam AI-Toolkit — Enterprise AI Development Framework

> **Spec-driven development powered by AI — Build with specifications first, implementation second**

[![Framework Status](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)](https://github.com/cloudteam/ai-toolkit)
[![Version](https://img.shields.io/badge/Version-2.1.3-blue)](https://www.npmjs.com/package/@cloudteam-dev/ai-toolkit)
[![Platform](https://img.shields.io/badge/Platform-Claude%20Code-blue)](https://claude.ai/code)
[![Setup Time](https://img.shields.io/badge/Setup%20Time-%3C%205%20min-blue)]()
[![Compliance](https://img.shields.io/badge/Compliance-ISO%2FCMMI%20Level%203-blue)]()

## ⚡ Quick Install

```bash
# Install globally (required)
npm install -g @cloudteam-dev/ai-toolkit

# Then init in your project
cd your-project && cteam-init
```

---

## ⚡ Quick Start

```bash
# Install globally (required)
npm install -g @cloudteam-dev/ai-toolkit

# Initialize in your project
cd your-project && cteam-init

# Check version
cteam-version

# Initialize documentation structure
/docs:init
```

**Setup time:** < 5 minutes from install to productive use.

---

## 📖 What Is CloudTeam AI-Toolkit?

CloudTeam AI-Toolkit is an **enterprise-grade AI development framework** that standardizes how development teams work with AI assistance. Instead of ad-hoc prompts and inconsistent workflows, every task follows proven patterns backed by compliance standards.

### Core Philosophy

**Specification → Implementation → Validation**

Every change starts with clear requirements. Every implementation follows established patterns. Every deployment is validated against standards.

### What You Get

- **18 Specialist AI Agents** — Expert agents for every development role
- **61 Reusable Skills** — Pre-built capabilities for common tasks
- **20 Slash Commands** — Quick shortcuts for key workflows
- **13 Lifecycle Hooks** — Automated guardrails across 6 event types
- **Compliance Built-In** — Automatic ISO/IEC 27001/27701/27002 + CMMI Level 3 validation
- **MCP Integration** — Context7, Playwright, and more

---

## 🏗️ Architecture Overview

### Component Breakdown

```
┌─────────────────────────────────────────────────────────┐
│                  CloudTeam AI-Toolkit                   │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │18 Agents │ │61 Skills │ │20 Commands│ │13 Hooks  │ │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │         Compliance Validation Engine             │  │
│  │    (ISO 27001/27701/27002 + CMMI Level 3)        │  │
│  └──────────────────────────────────────────────────┘  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │              MCP Server Integration              │  │
│  │         (Context7, Playwright, etc.)             │  │
│  └──────────────────────────────────────────────────┘  │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### Technology Stack

**Core:**
- Node.js 18+ (runtime)
- TypeScript (compliance validation)
- Markdown (specifications & documentation)
- Git (version control)

**Optional:**
- Python 3.8+ (document parser utilities)
- Database drivers (PostgreSQL, MySQL, SQLite)
- Docker (for MCP servers)

---

## 🚀 Installation

### Prerequisites

- **Claude Code** (for AI agents and MCP integration)
- **Node.js 18+** (for package management)
- **Git** (for version control)

### Step 1: Global Installation

**macOS/Linux:**
```bash
npm install -g @cloudteam-dev/ai-toolkit
```

The installer automatically:
- Creates `~/.npm-global` directory if needed
- Configures npm user-prefix
- Adds to shell PATH (`.zshrc` or `.bashrc`)

**Note:** After install, restart terminal or run `source ~/.zshrc` (or `source ~/.bashrc`)

**Windows:**
```bash
npm install -g @cloudteam-dev/ai-toolkit
```

No additional setup needed — npm uses user folder by default.

### Step 2: Initialize in Project

Navigate to your project directory:

```bash
cd my-project

# Initialize the toolkit
cteam-init
# or
cloudteam-ai-init

# Check installed version
cteam-version
```

This copies framework files to your project:

```
your-project/
├── .claude/           # AI agents, commands, and skills
├── docs/              # Documentation templates
├── .mcp.json          # MCP server configuration
├── CLAUDE.md          # Project instructions for Claude
└── LICENSE            # License information
```

### Step 3: Initialize Documentation

**CRITICAL:** Before starting development:

```bash
/docs:init
```

This creates essential documentation structure:
- `code-standards.md` - Coding standards and best practices
- `codebase-summary.md` - High-level codebase overview
- `project-overview-pdr.md` - Product Development Requirements
- `system-architecture.md` - System architecture documentation

### Step 4: Keep Updated

When new versions are released:

```bash
cteam-update
```

This command:
- Checks npm registry for latest version
- Updates global package if newer version exists
- Re-syncs project files with latest toolkit

---

## 🤖 AI Agents Reference

CTEAM AI Toolkit includes **18 specialist agents** covering the full development lifecycle:

| Agent | Purpose |
|---|---|
| **brainstormer** | Solution ideation and technical debates |
| **code-reviewer** | Code quality validation, security review, best practices |
| **code-simplifier** | Code refinement and clarity improvement |
| **copywriter** | Marketing and technical content creation |
| **database-admin** | Database design, optimization, and administration |
| **debugger** | Issue investigation, error analysis, diagnostics |
| **docs-manager** | Documentation generation, maintenance, updates |
| **fullstack-developer** | Full-stack implementation across frontend and backend |
| **git-manager** | Git operations and conventional commits |
| **journal-writer** | Critical issue and decision documentation |
| **mcp-manager** | MCP server management and configuration |
| **planner** | Implementation planning, task breakdown, research coordination |
| **project-manager** | Project oversight, progress tracking, documentation updates |
| **researcher** | Technical research and documentation |
| **scout** | File location and codebase exploration |
| **scout-external** | External resource and API exploration |
| **tester** | Test execution, coverage analysis, test report generation |
| **ui-ux-designer** | Interface design and user experience |

### How to Use Agents

**Direct invocation:**
```
I need backend development help for [task description]
```

The framework automatically routes to appropriate specialist agents based on context.

---

## 🎯 Claude Skills Catalog

CTEAM AI Toolkit includes **61 reusable skills** providing specialized capabilities. Skills activate automatically when relevant — or invoke explicitly:

```
Use the ai-multimodal skill to analyze this image
```

### AI & Multimodal (3 skills)

- **ai-artist** — Craft prompts for AI models (Midjourney, DALL-E, Stable Diffusion)
- **ai-multimodal** — Analyze images/audio/video with Gemini API, generate images/videos
- **sequential-thinking** — Structured problem-solving for complex tasks

### Development (10 skills)

- **backend-development** — Node.js, Python, Go, APIs, databases, security
- **frontend-development** — React, TypeScript, MUI, TanStack Router
- **frontend-design** — UI/UX design, Figma integration, animations
- **golang-pro** — Go language expertise and idiomatic patterns
- **mobile-development** — React Native, Flutter, Swift, Kotlin
- **react-best-practices** — React/Next.js performance optimization
- **tanstack** — TanStack Router, Query, Table integration
- **web-frameworks** — Next.js, Turborepo, SSR, ISR
- **bootstrap** — Project bootstrapping and scaffolding
- **agentation** — AI agent development patterns

### Infrastructure & DevOps (3 skills)

- **devops** — Cloudflare, Docker, GCP deployment, CI/CD
- **better-auth** — Authentication framework, OAuth, 2FA, sessions
- **agent-browser** — Browser automation and headless testing

### Database & Data (1 skill)

- **databases** — MongoDB, PostgreSQL schema design and queries

### Tools & Utilities (14 skills)

- **chrome-devtools** — Browser automation with Puppeteer
- **code-review** — Quality assessment and security review
- **common** — Shared utilities and helper functions
- **context-engineering** — Context usage optimization
- **debug** — Systematic debugging and root cause analysis
- **document-skills** — Document processing and management
- **docs-seeker** — Documentation search via llms.txt
- **find-skills** — Locate and activate relevant skills
- **fix** — Bug fixes with intelligent routing
- **image-nano** — Lightweight image processing utilities
- **mcp-builder** — Build MCP servers for LLM integration
- **mcp-management** — Manage MCP servers and capabilities
- **media-processing** — FFmpeg, ImageMagick for media manipulation
- **repomix** — Pack repositories into AI-friendly files

### Content & Design (8 skills)

- **copywriting** — Conversion copywriting formulas and templates
- **markdown-novel-viewer** — View markdown with book-like experience
- **mermaidjs-v11** — Diagrams with Mermaid.js v11
- **mintlify** — Mintlify documentation platform integration
- **shader** — WebGL shader development
- **threejs** — 3D web apps with Three.js
- **ui-styling** — shadcn/ui components with Tailwind CSS
- **ui-ux-pro-max** — Complete UI/UX design intelligence
- **web-design-guidelines** — Web Interface Guidelines compliance

### Planning & Process (9 skills)

- **brainstorm** — Solution brainstorming with trade-off analysis
- **ccs-delegation** — CCS CLI delegation for tasks
- **gkg** — Knowledge graph generation
- **plan** — Implementation planning and architecture design
- **plans-kanban** — Plan progress tracking and visualization
- **problem-solving** — Systematic problem-solving techniques
- **project-management** — Project coordination and tracking
- **research** — Technical research and solution analysis
- **scout** — File and codebase scouting

### Integrations & Platforms (9 skills)

- **cook** — Quick feature implementation workflows
- **git** — Git operations and workflow automation
- **google-adk-python** — Build AI agents with Google ADK
- **payment-integration** — SePay and Polar payment integration
- **remotion** — Video creation with React and Remotion
- **shopify** — Build Shopify apps and extensions
- **team** — Team collaboration workflows
- **web-testing** — Playwright, Vitest, k6 for testing
- **xlsx** — Excel/spreadsheet processing

### Other (5 skills)

- **skill-creator** — Create or update Claude skills
- **template-skill** — Template for creating new skills

---

## 💬 Slash Commands Reference

CTEAM AI Toolkit provides **20 slash commands** for quick workflows. Note: many capabilities (cook, fix, debug, git, design, etc.) are now invoked as **skills** rather than commands.

### Core Commands

```bash
/ask               # Ask questions and get guidance
/ck-help           # Get help with the toolkit
/coding-level      # Set coding expertise level
/preview           # Preview changes before applying
/use-mcp           # Use MCP servers
/watzup            # Project status overview
/worktree          # Git worktree management
```

### Documentation

```bash
/docs/init         # Initialize project documentation
/docs/update       # Update existing documentation
/docs/summarize    # Summarize documentation
```

### Planning

```bash
/plan/archive      # Archive a completed plan
/plan/validate     # Validate a plan
/plan/red-team     # Red-team review of a plan
```

### Testing & Quality

```bash
/test              # Run test suite
/test/ui           # UI/UX testing
```

### Code Review

```bash
/review/codebase         # Review entire codebase
/review/codebase/parallel # Parallel codebase review
```

### Utility

```bash
/bootstrap         # Bootstrap project setup
/journal           # Write journal entry
/kanban            # View kanban board
```

---

## 🪝 Hooks System

CTEAM AI Toolkit includes **13 lifecycle hooks** across **6 event types** that provide automated guardrails:

| Event | Hooks | Purpose |
|---|---|---|
| **SessionStart** | `session-init` | Initialize session context, detect project type |
| **SubagentStart** | `subagent-init`, `team-context-inject` | Inject context into subagents and team members |
| **UserPromptSubmit** | `dev-rules-reminder`, `usage-context-awareness` | Enforce dev rules, monitor token/resource usage |
| **PreToolUse** | `privacy-block`, `scout-block`, `descriptive-name`, `skill-dedup` | Block sensitive file access, enforce naming, deduplicate skills |
| **PostToolUse** | `post-edit-simplify-reminder`, `cook-after-plan-reminder`, `task-completed-handler` | Remind simplification after edits, track task completion |
| **SubagentStop** | `teammate-idle-handler` | Handle idle teammates in agent teams |

Hooks run automatically — no manual configuration needed after `cteam-init`.

---

## 📁 Project Structure

```
.claude/
├── agents/                     # 18 AI Agents
│   ├── brainstormer.md
│   ├── code-reviewer.md
│   ├── code-simplifier.md
│   ├── copywriter.md
│   ├── database-admin.md
│   ├── debugger.md
│   ├── docs-manager.md
│   ├── fullstack-developer.md
│   ├── git-manager.md
│   ├── journal-writer.md
│   ├── mcp-manager.md
│   ├── planner.md
│   ├── project-manager.md
│   ├── researcher.md
│   ├── scout.md
│   ├── scout-external.md
│   ├── tester.md
│   └── ui-ux-designer.md
├── commands/                   # 20 Slash Commands
│   ├── docs/                   # Documentation commands
│   ├── plan/                   # Planning commands
│   ├── review/                 # Code review commands
│   ├── test/                   # Testing commands
│   └── ... (utility commands)
├── skills/                     # 61 Reusable Skills
│   ├── agentation/
│   ├── agent-browser/
│   ├── ai-artist/
│   ├── ai-multimodal/
│   ├── backend-development/
│   ├── better-auth/
│   ├── bootstrap/
│   ├── brainstorm/
│   ├── ccs-delegation/
│   ├── chrome-devtools/
│   ├── code-review/
│   ├── common/
│   ├── context-engineering/
│   ├── cook/
│   ├── databases/
│   ├── debug/
│   ├── devops/
│   ├── docs-seeker/
│   ├── document-skills/
│   ├── find-skills/
│   ├── fix/
│   ├── frontend-design/
│   ├── frontend-development/
│   ├── git/
│   ├── gkg/
│   ├── golang-pro/
│   ├── google-adk-python/
│   ├── image-nano/
│   ├── markdown-novel-viewer/
│   ├── mcp-builder/
│   ├── mcp-management/
│   ├── media-processing/
│   ├── mermaidjs-v11/
│   ├── mintlify/
│   ├── mobile-development/
│   ├── payment-integration/
│   ├── plan/
│   ├── plans-kanban/
│   ├── problem-solving/
│   ├── project-management/
│   ├── react-best-practices/
│   ├── remotion/
│   ├── repomix/
│   ├── research/
│   ├── scout/
│   ├── sequential-thinking/
│   ├── shader/
│   ├── shopify/
│   ├── skill-creator/
│   ├── tanstack/
│   ├── team/
│   ├── template-skill/
│   ├── test/
│   ├── threejs/
│   ├── ui-styling/
│   ├── ui-ux-pro-max/
│   ├── web-design-guidelines/
│   ├── web-frameworks/
│   ├── web-testing/
│   └── xlsx/
├── hooks/                      # 13 Lifecycle Hooks
│   ├── session-init.cjs
│   ├── subagent-init.cjs
│   ├── privacy-block.cjs
│   └── ... (13 hook files)
├── scripts/                    # Utility Scripts
│   ├── generate_catalogs.py
│   ├── scan_skills.py
│   ├── worktree.cjs
│   └── ... (18 script files)
└── rules/                      # Development Rules
    ├── primary-workflow.md
    ├── development-rules.md
    ├── orchestration-protocol.md
    └── documentation-management.md

docs/
├── compliances/                # ISO/CMMI/PCI-DSS standards
├── brd/                        # Business requirements
├── prd/                        # Product requirements
├── epics/                      # Epic-level documentation
├── tasks/                      # Technical tasks
└── user-stories/               # User stories

plans/                          # (created during usage)
└── reports/                    # Agent reports

.mcp.json                       # MCP server configuration
CLAUDE.md                       # Project instructions for Claude
LICENSE                         # License information
```

---

## 🔒 Compliance & Standards

CTEAM AI Toolkit automatically validates implementations against:

- ✅ **ISO/IEC 27001:2022** — Information Security Management
- ✅ **ISO/IEC 27701:2019** — Privacy Information Management
- ✅ **ISO/IEC 27002:2022** — Security Controls
- ✅ **CMMI Level 3** — Defined Process Maturity
- ✅ **PCI-DSS v4.0** — Payment Card Industry Data Security (when applicable)

Compliance validation runs automatically during implementation workflows.

---

## 🔧 Advanced Topics

### Custom Skill Creation

Create specialized skills for your team's needs:

```bash
Use the skill-creator skill to create a new skill
```

### MCP Server Configuration

Configure MCP servers in `.mcp.json`:

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    },
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "@cloudteam-dev/mcp-server-mongodb"]
    }
  }
}
```

### Workflow Customization

Customize workflows in `.claude/rules/`:
- `primary-workflow.md` — Main development workflow
- `development-rules.md` — Coding standards and practices
- `orchestration-protocol.md` — Agent coordination rules
- `documentation-management.md` — Documentation processes

---

## ❓ FAQs

**Q: Can I use this without Claude Code?**
A: No, Claude Code is required for AI agent functionality and MCP integration.

**Q: Does this work with other IDEs?**
A: The framework is optimized for Claude Code but documentation and compliance tools work anywhere.

**Q: How do I update to latest version?**
A: Run `cteam-update` to check for updates and sync project files.

**Q: Can I customize the agents?**
A: Yes, edit agent files in `.claude/agents/` or create new ones following the existing format.

**Q: What's the difference between agents and skills?**
A: Agents are specialist AI personas for roles (Planner, Tester, etc.). Skills are reusable capability modules that agents and workflows invoke.

**Q: Do I need all 61 skills?**
A: No, skills activate automatically when needed. No manual management required.

**Q: How does compliance validation work?**
A: Framework includes ISO/CMMI standards that agents reference during implementation to ensure compliance.

**Q: Can I use this for non-software projects?**
A: The framework is optimized for software development but documentation and planning workflows work for any project type.

---

## 🛠️ Troubleshooting

### Installation Issues

**Problem:** `command not found: cteam-init`
**Solution:**
- Restart terminal after installation
- Run `source ~/.zshrc` (or `source ~/.bashrc`)
- Verify npm global bin is in PATH: `npm config get prefix`

**Problem:** Permission errors on macOS/Linux
**Solution:** Never use `sudo`. Framework automatically configures user-prefix.

**Problem:** Old version installed after `npm install -g` (e.g. still showing v2.0.3)
**Solution:**
```bash
# Clear npm cache and force latest version
npm cache clean --force
npm uninstall -g @cloudteam-dev/ai-toolkit
npm install -g @cloudteam-dev/ai-toolkit@latest

# Verify version (shown in cteam-init output header)
cteam-init
# Should display: "CTEAM AI Kit Setup v2.1.x"
```

**Problem:** `pywin32` error on macOS/Linux during skills setup
**Solution:** Fixed in v2.1.1 — Windows-only packages are automatically skipped on macOS/Linux. Update to latest version.

**Problem:** `^M: bad interpreter` or CRLF errors on macOS/Linux
**Solution:** Fixed in v2.1.2 — `.gitattributes` now enforces correct line endings. Run `cteam-update` to get the fix.

### MCP Server Issues

**Problem:** MCP servers not connecting
**Solution:**
- Verify `.mcp.json` configuration
- Check MCP server packages are installed
- Restart Claude Code

### Agent Not Responding

**Problem:** Agent not activating
**Solution:**
- Check agent file exists in `.claude/agents/`
- Restart Claude Code to reload configuration

---

## 📞 Support

- **Documentation**: Check `docs/` directory and `.claude/README.md`
- **Contact**: phuc.phan@cloudteam.vn / ty.pham@cloudteam.vn
- **Compliance Standards**: See `docs/compliances/` for ISO/CMMI documentation
- **Issues**: Report at https://github.com/cloudteam/ai-toolkit/issues

---

## 📜 Version History

### v2.1.3 (March 2026)
- Remove unused Atlassian, Oracle, MongoDB MCP server configs from `.mcp.json`
- Fix shell scripts CRLF line endings normalization for macOS/Linux
- Add `cteam-version` CLI command for quick version check
- Sync latest skills from WSL2 and fix npm packaging

### v2.1.2 (March 2026)
- Add `.gitattributes` for cross-OS line ending enforcement (LF for `.sh`/`.py`/`.js`, CRLF for `.ps1`/`.cmd`)
- New utility scripts: `generate_catalogs.py`, `scan_skills.py`, `scan_commands.py`, `worktree.cjs`
- Non-destructive `copyDir` in `setup.js` — preserves user files not in source
- Remove deprecated `openspec/` references
- Fix shell scripts shipped with CRLF causing execution failures on macOS/Linux

### v2.1.1 (February 2026)
- Display version number in `cteam-init` output for easy diagnostics
- Skip Windows-only packages (`pywin32`, etc.) on macOS/Linux during skills setup
- Add `update.js` explicitly to npm `files` field
- Add troubleshooting guide for npm cache issues

### v2.1.0 (February 2026)
- Migrate commands to skills for better performance and workflows after Claude Code update
- Async spawn for skills install to prevent timeout
- Use `-Command` instead of `-File` for PowerShell to prevent hang
- Remove misleading project directory warning from `cteam-init`
- Prevent terminal hang after skills install script completes

### v2.0.3 (February 2026)
- Fix README not showing on npm registry

### v2.0.2 (January 2026)
- Documentation sync fix for npm registry

### v2.0.0 (January 2026)
- Enhanced agent system: 24 specialized agents
- Expanded skills catalog: 51 reusable skills
- Comprehensive commands: 88 slash commands
- Improved MCP integration
- Enhanced compliance validation

### v1.0.0 (November 2025)
- Initial release
- Claude Code framework with department-based agent organization
- MCP integration
- 10 agents, 16 commands, 12 skills
- ISO/CMMI compliance foundation

---

## 📝 License

ISC License - See LICENSE file for details

---

## 🔗 Quick Links

- [AI Agents Reference](.claude/agents/) — 18 specialist agents
- [Claude Skills Catalog](.claude/skills/) — 61 reusable skills
- [Slash Commands](.claude/commands/) — 20 commands
- [Lifecycle Hooks](.claude/hooks/) — 13 hooks across 6 event types
- [Compliance Standards](docs/compliances/) — ISO/IEC 27001/27701/27002, CMMI, PCI-DSS
- [Development Rules](.claude/rules/development-rules.md) — Coding standards
- [Primary Workflow](.claude/rules/primary-workflow.md) — Main development workflow

---

**Framework Version**: 2.1.3
**Last Updated**: March 4, 2026
**Platform**: Claude Code
**Package**: [@cloudteam-dev/ai-toolkit](https://www.npmjs.com/package/@cloudteam-dev/ai-toolkit)
**Repository**: [github.com/cloudteam/ai-toolkit](https://github.com/cloudteam/ai-toolkit)

---

Made with ❤️ by CloudTeam