class-ai-agent 1.2.0

package/README.md

@@ -0,0 +1,405 @@
+# AI Agent Project — Production-Grade Configuration
+
+<div align="center">
+  <img src="https://res.cloudinary.com/ecommerce2021/image/upload/v1768626951/dev_efjbzw.jpg" alt="Code Web Khong Kho" width="120" style="border-radius: 50%"/>
+
+  <h3>Production-ready AI Agent configuration for Claude Code &amp; Cursor</h3>
+  <p>Structured workflows, specialized agents, mandatory rules, and best practices</p>
+
+  ![Version](https://img.shields.io/badge/version-1.2.0-blue?style=flat-square)
+  [![Facebook](https://img.shields.io/badge/Facebook-Code%20Web%20Khong%20Kho-1877F2?logo=facebook)](https://www.facebook.com/codewebkhongkho)
+  [![TikTok](https://img.shields.io/badge/TikTok-@code.web.khng.kh-000000?logo=tiktok)](https://www.tiktok.com/@code.web.khng.kh)
+  [![Website](https://img.shields.io/badge/Website-codewebkhongkho.com-FF6B35?logo=google-chrome)](https://codewebkhongkho.com/portfolios)
+
+  <sub>Inspired by <a href="https://github.com/addyosmani/agent-skills">addyosmani/agent-skills</a></sub>
+</div>
+
+---
+
+## Overview
+
+This repository provides a **production-grade configuration** for AI-assisted development. It includes **two parallel layouts**:
+
+| Layout | Tool | Purpose |
+|--------|------|---------|
+| **`.claude/`** | [Claude Code](https://code.claude.com/docs) | Slash commands, `CLAUDE.md`, rules as `.md` |
+| **`.cursor/`** | [Cursor](https://cursor.com) | Same workflows; rules as **`.mdc`** (Cursor project rules); hub doc **`CURSOR.md`** |
+
+Shared contents:
+
+- **Structured development workflow** (Spec → Plan → Build → Test → Review → Ship)
+- **10 specialized agents** for different development roles
+- **13 mandatory topic rules** (same content in `.claude/rules/` and `.cursor/rules/`), plus **`cursor-overview.mdc`** in `.cursor/rules/` for Cursor workflow entry
+- **9 workflow prompts** (slash-style command markdown files)
+- **4 reference checklists** for security, testing, performance, and accessibility
+
+Root **`AGENTS.md`** points agents at **`.cursor/CURSOR.md`** for Cursor-oriented entry.
+
+The same files can be installed with **`npx`** (see [Quick Start](#quick-start)).
+
+---
+
+## Development Workflow
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                                                                  │
+│   /spec  →  /plan  →  /build  →  /test  →  /review  →  /deploy  │
+│                                                                  │
+│   Define    Plan     Build     Verify    Review      Ship        │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+| Phase | Command | Description |
+|-------|---------|-------------|
+| **Define** | `/spec` | Create PRD with objectives, scope, and boundaries |
+| **Plan** | `/plan` | Decompose into vertical slices with acceptance criteria |
+| **Build** | `/build` | Implement incrementally using TDD |
+| **Verify** | `/test` | Write tests with RED-GREEN-REFACTOR |
+| **Review** | `/review` | Five-axis code review |
+| **Ship** | `/deploy` | Build, test, and deploy |
+
+### Supporting Commands
+
+| Command | Description |
+|---------|-------------|
+| `/debug` | Systematic error diagnosis |
+| `/simplify` | Reduce code complexity |
+| `/fix-issue` | Analyze and fix issues |
+
+---
+
+## Project Structure
+
+### Claude Code — `.claude/`
+
+```
+.claude/
+├── CLAUDE.md                    # Main AI configuration
+│
+├── commands/                    # Workflow prompts (9 files)
+│   ├── spec.md                  # /spec — PRD creation
+│   ├── plan.md                  # /plan — Task breakdown
+│   ├── build.md                 # /build — Incremental implementation
+│   ├── test.md                  # /test — TDD workflow
+│   ├── review.md                # /review — Code review
+│   ├── deploy.md                # /deploy — Deployment
+│   ├── debug.md                 # /debug — Error diagnosis
+│   ├── simplify.md              # /simplify — Code simplification
+│   └── fix-issue.md             # /fix-issue — Issue resolution
+│
+├── agents/                      # Specialized agents (10 total)
+│   ├── frontend.md              # Frontend Developer
+│   ├── backend.md               # Backend Developer
+│   ├── systems-architect.md     # Systems Architect
+│   ├── code-reviewer.md         # Code Reviewer
+│   ├── test-engineer.md         # Test Engineer
+│   ├── security-auditor.md      # Security Auditor
+│   ├── qa.md                    # QA Engineer
+│   ├── project-manager.md       # Project Manager
+│   ├── ui-ux-designer.md        # UI/UX Designer
+│   └── copywriter-seo.md        # Copywriter/SEO
+│
+├── rules/                       # Mandatory rules (13 total)
+│   ├── clean-code.md            # Clean Code principles
+│   ├── code-style.md            # Formatting & naming
+│   ├── error-handling.md        # Error patterns
+│   ├── tech-stack.md            # Approved technologies
+│   ├── system-design.md         # System design patterns
+│   ├── project-structure.md     # Folder organization
+│   ├── api-conventions.md       # REST API standards
+│   ├── naming-conventions.md    # Naming patterns
+│   ├── database.md              # Database patterns
+│   ├── security.md              # Security requirements
+│   ├── monitoring.md            # Observability
+│   ├── testing.md               # Test standards
+│   └── git-workflow.md          # Git conventions
+│
+├── skills/                      # Advanced skills
+│   ├── tdd/SKILL.md             # Test-Driven Development
+│   ├── code-review/SKILL.md     # Five-axis review
+│   ├── incremental-implementation/SKILL.md
+│   ├── deploy/SKILL.md
+│   └── security-review/SKILL.md
+│
+├── references/                  # Quick checklists
+│   ├── security-checklist.md
+│   ├── testing-patterns.md
+│   ├── performance-checklist.md
+│   └── accessibility-checklist.md
+│
+└── settings.json                # Project settings (paths & dirs)
+```
+
+### Cursor — `.cursor/`
+
+Mirrors `.claude/` for agents, commands, skills, and references. Differences:
+
+| Item | Notes |
+|------|--------|
+| **`CURSOR.md`** | Hub doc (same workflow story as `CLAUDE.md`, Cursor-specific usage) |
+| **`rules/*.mdc`** | Cursor project rules with YAML frontmatter; **`security.mdc`** is always applied; **`cursor-overview.mdc`** explains workflow and paths |
+| **`settings.json`** | Directory map (parallel to `.claude/settings.json`) |
+| **`AGENTS.md` (repo root)** | Short pointer to `.cursor/CURSOR.md` for Cursor |
+
+```
+.cursor/
+├── CURSOR.md
+├── settings.json
+├── commands/                    # Same 9 prompts — open or @-include in Chat/Composer
+├── agents/                      # Same 10 personas — @-mention files when needed
+├── rules/                       # 14 × .mdc (13 topics + cursor-overview)
+├── skills/
+├── references/
+```
+
+Keep **`.claude/`** and **`.cursor/`** aligned when you change standards or workflows.
+
+---
+
+## Specialized Agents
+
+### Development Agents
+
+| Agent | Role | Invoke When |
+|-------|------|-------------|
+| **Frontend Developer** | Next.js, React, TypeScript, UI | Components, pages, state |
+| **Backend Developer** | Express, Prisma, Redis, BullMQ | APIs, services, jobs |
+| **Systems Architect** | Architecture, ADRs, scaling | System design decisions |
+
+### Quality Agents
+
+| Agent | Role | Invoke When |
+|-------|------|-------------|
+| **Code Reviewer** | Five-axis code review | PR reviews, quality checks |
+| **Test Engineer** | TDD, coverage, test strategy | Writing and reviewing tests |
+| **Security Auditor** | Vulnerability, threat modeling | Security reviews |
+| **QA Engineer** | Test plans, E2E, bug reports | Quality assurance |
+
+### Product Agents
+
+| Agent | Role | Invoke When |
+|-------|------|-------------|
+| **Project Manager** | Stories, sprints, planning | Project planning |
+| **UI/UX Designer** | Design system, accessibility | UX decisions |
+| **Copywriter/SEO** | Copy, meta tags, SEO | Content creation |
+
+---
+
+## Approved Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Frontend (SEO)** | Next.js 14 (App Router) |
+| **Frontend (Admin)** | React + Vite |
+| **Styling** | Tailwind CSS + shadcn/ui |
+| **State** | Zustand + TanStack Query |
+| **Backend** | Express.js + TypeScript |
+| **ORM** | Prisma |
+| **Database** | PostgreSQL |
+| **Cache** | Redis (ioredis) |
+| **Queue** | BullMQ (simple) / RabbitMQ (enterprise) |
+| **Auth** | NextAuth.js / JWT + bcrypt |
+| **Testing** | Vitest + Playwright |
+| **Monitoring** | Prometheus + Grafana + Pino |
+| **CI/CD** | GitHub Actions |
+| **Deploy** | Vercel + Railway/Fly.io |
+
+---
+
+## Mandatory Rules
+
+Follow the rules in **`.claude/rules/`** (Markdown) when using Claude Code, and **`.cursor/rules/`** (`.mdc`) when using Cursor. Content matches; Cursor loads `.mdc` frontmatter automatically.
+
+### Code Quality
+- **clean-code.md** — Variables, functions, SOLID, async/await
+- **code-style.md** — 2-space indent, single quotes, semicolons
+- **error-handling.md** — AppError class, centralized handler
+
+### Architecture
+- **tech-stack.md** — Approved technologies only
+- **system-design.md** — CAP, caching, scaling patterns
+- **project-structure.md** — Layered architecture
+- **api-conventions.md** — REST standards, response envelopes
+
+### Data & Naming
+- **naming-conventions.md** — Cache keys, DB, queues, env vars
+- **database.md** — Prisma patterns, N+1 prevention
+
+### Operations
+- **security.md** — **CRITICAL** — Never violate
+- **monitoring.md** — Prometheus, Grafana, alerting
+- **testing.md** — 80% coverage minimum
+- **git-workflow.md** — Conventional commits
+
+---
+
+## Quick Start
+
+### Install with `npx` (recommended)
+
+Requires [Node.js](https://nodejs.org/) **16.7+**. After you publish this repository to the npm registry (`npm publish`; package name **`class-ai-agent`** in `package.json`):
+
+```bash
+# Install into the current directory (.claude/, .cursor/, AGENTS.md)
+npx class-ai-agent
+
+# Install into another folder
+npx class-ai-agent --dir /path/to/your/project
+
+# Only Claude Code files
+npx class-ai-agent --claude
+
+# Only Cursor files + AGENTS.md
+npx class-ai-agent --cursor
+
+# Overwrite an existing install
+npx class-ai-agent --force
+```
+
+Run **`npx class-ai-agent --help`** for all options.
+
+#### Publishing to npm (fix `E403` / 2FA)
+
+If **`npm publish`** fails with **`403 Forbidden`** and a message about **two-factor authentication**, npm is blocking the upload until your account meets its publish policy:
+
+1. Sign in at [npmjs.com](https://www.npmjs.com/) → **Account** → enable **Two-Factor Authentication** (use **Auth and writes** so publishing is covered).
+2. In the terminal, refresh the session if needed: **`npm logout`** then **`npm login`**.
+3. Run **`npm publish --access public`** again and enter your **one-time password** when npm asks for it.
+
+For **CI or tokens only**: create a [granular access token](https://docs.npmjs.com/about-access-tokens) with permission to publish this package, using type **Automation** (or a token that can bypass 2FA where npm allows it), set **`NPM_TOKEN`** in the environment, and use an **`.npmrc`** that references `${NPM_TOKEN}` per npm’s docs.
+
+**From a git clone** (before publishing, or for development):
+
+```bash
+cd class-ai-agent
+npm exec -- class-ai-agent --dir /path/to/your/project
+# or: node bin/class-ai-agent.cjs --dir /path/to/your/project
+```
+
+### Manual copy
+
+```bash
+git clone https://github.com/khoantd/class-ai-agent.git
+cd class-ai-agent
+
+cp -r .claude/ /path/to/your/project/
+cp -r .cursor/ /path/to/your/project/
+cp AGENTS.md /path/to/your/project/
+```
+
+### Using workflow prompts (commands)
+
+**Claude Code** — use slash commands in the CLI:
+
+```text
+/spec "User authentication feature"
+/plan
+/build
+/test
+/review
+/deploy
+```
+
+**Cursor** — the same prompts live as markdown under **`.cursor/commands/`**. Open the file, copy the section you need, or **@ mention** it (e.g. `@.cursor/commands/spec.md`) in Chat or Composer.
+
+### Using Agents
+
+Natural-language instructions still work. In **Cursor**, you can also **@ mention** an agent file (e.g. `@.cursor/agents/frontend.md`) to load that persona.
+
+```text
+"Act as the Frontend Developer and build the login page"
+"As Systems Architect, design the notification system"
+"Code Reviewer: review this PR for security issues"
+"Test Engineer: write tests for the payment flow"
+```
+
+---
+
+## Key Concepts
+
+### Five-Axis Code Review
+
+Every code review evaluates:
+
+1. **Correctness** — Does it work? Edge cases?
+2. **Readability** — Can others understand it?
+3. **Architecture** — Follows patterns? Appropriate abstractions?
+4. **Security** — Input validation? Auth? No secrets?
+5. **Performance** — N+1? Pagination? Async?
+
+### Test-Driven Development
+
+```
+RED    → Write failing test
+GREEN  → Write minimal code to pass
+REFACTOR → Improve while green
+```
+
+### Vertical Slicing
+
+Build features end-to-end, not layer-by-layer:
+
+```
+✅ Task 1: User can create task (DB + API + UI)
+✅ Task 2: User can view tasks (DB + API + UI)
+
+❌ Task 1: Create all DB models
+❌ Task 2: Create all API routes
+```
+
+---
+
+## Security
+
+**Never commit:**
+- `.env` files
+- API keys, secrets, passwords
+- `.claude/settings.local.json` (and any local-only Cursor overrides if you add them)
+
+**Always:**
+- Use environment variables
+- Validate all inputs
+- Hash passwords (bcrypt >= 12 rounds)
+- Parameterize queries
+
+---
+
+## Contributing
+
+1. Follow the development workflow (`/spec` → `/plan` → `/build`, or the same prompts under `.cursor/commands/`)
+2. Ensure all tests pass
+3. Run `/review` before submitting PR
+4. Follow conventional commit format
+5. When changing rules or workflows, update **both** `.claude/` and `.cursor/` so they stay aligned
+
+---
+
+## Credits
+
+- Workflow inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
+- Best practices from *Software Engineering at Google*
+- Clean Code principles from Robert C. Martin
+
+---
+
+## Author
+
+<div align="center">
+  <img src="https://res.cloudinary.com/ecommerce2021/image/upload/v1768626951/dev_efjbzw.jpg" alt="Code Web Khong Kho" width="80" style="border-radius: 50%"/>
+
+  **Code Web Khong Kho**
+
+  | Platform | Link |
+  |----------|------|
+  | Facebook | [facebook.com/codewebkhongkho](https://www.facebook.com/codewebkhongkho) |
+  | TikTok | [@code.web.khng.kh](https://www.tiktok.com/@code.web.khng.kh) |
+  | Website | [codewebkhongkho.com](https://codewebkhongkho.com/portfolios) |
+</div>
+
+---
+
+<div align="center">
+  <sub>Made with care by <a href="https://www.facebook.com/codewebkhongkho">Code Web Khong Kho</a></sub>
+</div>

package/bin/class-ai-agent.cjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function readPkg() {
+  const p = path.join(PKG_ROOT, 'package.json');
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function printHelp() {
+  console.log(`class-ai-agent — Install Claude Code & Cursor AI agent scaffolding
+
+Usage:
+  npx class-ai-agent [init] [options]
+
+Options:
+  -d, --dir <path>   Target directory (default: current working directory)
+      --claude       Install only .claude/
+      --cursor       Install only .cursor/ and AGENTS.md
+  -f, --force        Overwrite existing files or directories
+  -h, --help         Show help
+  -v, --version      Print version
+
+Examples:
+  npx class-ai-agent
+  npx class-ai-agent --dir ./my-app
+  npx class-ai-agent --cursor --force
+`);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    command: 'init',
+    dir: process.cwd(),
+    claudeOnly: false,
+    cursorOnly: false,
+    force: false,
+    help: false,
+    version: false,
+  };
+
+  let i = 0;
+  if (argv[0] === 'init') {
+    i = 1;
+  }
+
+  for (; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') {
+      opts.help = true;
+      continue;
+    }
+    if (a === '-v' || a === '--version') {
+      opts.version = true;
+      continue;
+    }
+    if (a === '-f' || a === '--force') {
+      opts.force = true;
+      continue;
+    }
+    if (a === '--claude') {
+      opts.claudeOnly = true;
+      continue;
+    }
+    if (a === '--cursor') {
+      opts.cursorOnly = true;
+      continue;
+    }
+    if (a === '-d' || a === '--dir') {
+      const v = argv[++i];
+      if (!v) {
+        console.error('Error: missing value for --dir');
+        process.exit(1);
+      }
+      opts.dir = path.resolve(v);
+      continue;
+    }
+    console.error(`Unknown argument: ${a}`);
+    process.exit(1);
+  }
+
+  return opts;
+}
+
+function ensureParentDir(filePath) {
+  const d = path.dirname(filePath);
+  fs.mkdirSync(d, { recursive: true });
+}
+
+function copyDir(src, dest, { force }) {
+  if (!fs.existsSync(src)) {
+    console.error(`Error: template missing from package: ${src}`);
+    process.exit(1);
+  }
+  if (fs.existsSync(dest)) {
+    if (!force) {
+      console.error(`Error: already exists (use --force to overwrite): ${dest}`);
+      process.exit(1);
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function copyFile(src, dest, { force }) {
+  if (!fs.existsSync(src)) {
+    console.error(`Error: template missing from package: ${src}`);
+    process.exit(1);
+  }
+  if (fs.existsSync(dest) && !force) {
+    console.error(`Error: already exists (use --force to overwrite): ${dest}`);
+    process.exit(1);
+  }
+  ensureParentDir(dest);
+  fs.copyFileSync(src, dest);
+}
+
+function run(opts) {
+  const full =
+    (!opts.claudeOnly && !opts.cursorOnly) ||
+    (opts.claudeOnly && opts.cursorOnly);
+
+  const installClaude = full || (opts.claudeOnly && !opts.cursorOnly);
+  const installCursor = full || (opts.cursorOnly && !opts.claudeOnly);
+  const installAgents = full || opts.cursorOnly;
+
+  fs.mkdirSync(opts.dir, { recursive: true });
+
+  const copyOpts = { force: opts.force };
+
+  if (installClaude) {
+    const src = path.join(PKG_ROOT, '.claude');
+    const dest = path.join(opts.dir, '.claude');
+    copyDir(src, dest, copyOpts);
+    console.log(`Installed: ${dest}`);
+  }
+
+  if (installCursor) {
+    const src = path.join(PKG_ROOT, '.cursor');
+    const dest = path.join(opts.dir, '.cursor');
+    copyDir(src, dest, copyOpts);
+    console.log(`Installed: ${dest}`);
+  }
+
+  if (installAgents) {
+    const src = path.join(PKG_ROOT, 'AGENTS.md');
+    const dest = path.join(opts.dir, 'AGENTS.md');
+    copyFile(src, dest, copyOpts);
+    console.log(`Installed: ${dest}`);
+  }
+
+  const hints = [];
+  if (installClaude) hints.push('.claude/CLAUDE.md');
+  if (installCursor) hints.push('.cursor/CURSOR.md');
+  console.log(`\nDone. Next steps: read ${hints.join(' and ')}.`);
+}
+
+const argv = process.argv.slice(2);
+const opts = parseArgs(argv);
+
+if (opts.help) {
+  printHelp();
+  process.exit(0);
+}
+
+if (opts.version) {
+  console.log(readPkg().version);
+  process.exit(0);
+}
+
+run(opts);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "class-ai-agent",
+  "version": "1.2.0",
+  "description": "Production-grade AI agent configuration for Claude Code & Cursor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khoantd/class-ai-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/khoantd/class-ai-agent/issues"
+  },
+  "homepage": "https://github.com/khoantd/class-ai-agent#readme",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "cursor",
+    "ai",
+    "agent",
+    "scaffold"
+  ],
+  "engines": {
+    "node": ">=16.7.0"
+  },
+  "bin": {
+    "class-ai-agent": "bin/class-ai-agent.cjs"
+  },
+  "files": [
+    "bin",
+    ".claude",
+    ".cursor",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "prepack": "node -e \"const fs=require('fs');['.claude','.cursor','AGENTS.md'].forEach(p=>{if(!fs.existsSync(p))process.exit(1)})\"",
+    "test:cli": "node bin/class-ai-agent.cjs --help && node bin/class-ai-agent.cjs --version"
+  }
+}