AI Agent Project — Production-Grade Configuration

Inspired by addyosmani/agent-skills

Installation

Install as a dev dependency in any project. On install, agent files are copied additively into your project root (existing files are never overwritten).

npm install -D cursor-agents
# or
yarn add -D cursor-agents
pnpm add -D cursor-agents

pnpm 10+: lifecycle scripts are blocked by default. Allow this package once:

pnpm approve-builds cursor-agents
# or add to package.json: "pnpm": { "onlyBuiltDependencies": ["cursor-agents"] }

This creates or updates:

• AGENTS.md — workspace AI instructions
• .cursor/ — rules, commands, agents, skills, references, settings.json

Brownfield / existing projects

Defaults assume Node, Express, Prisma, Next.js. For ongoing projects with a different stack:

npm install -D cursor-agents

Then in Cursor:

/calibrate              # discover stack + dry-run manifest
/calibrate --apply      # write project-stack.mdc + patches

This generates .cursor/rules/project-stack.mdc (overrides generic tech-stack.mdc for your repo). Commit project-stack.mdc and .cursor/calibration/stack-profile.json to git.

Invoke Master Agent or the project-calibration skill for details. Spec: docs/specs/master-agent-project-calibration.md.

Behavior

| Situation | What happens | |-----------|----------------| | New project | Full .cursor/ tree + AGENTS.md | | Existing AGENTS.md or .cursor/** | Skipped — your files are kept (same path wins) | | Same command/skill name, different path | Both may exist — resolve manually; see name collision playbook | | Brownfield stack mismatch | Run /calibrate after install | | CI (CI=true) | Same additive install (missing files are added) | | Need overwrite | npx cursor-agents init --force |

Opt-out

# Skip automatic copy on npm install
CURSOR_AGENTS_SKIP_INSTALL=1 npm install -D cursor-agents

# Or install then run manually
npm install -D cursor-agents --ignore-scripts
npx cursor-agents init

CLI

npx cursor-agents init           # additive install
npx cursor-agents init --dry-run # preview changes
npx cursor-agents init --force   # overwrite existing config
npx cursor-agents --help

Monorepos: run install in the workspace package where you want Cursor config (INIT_CWD / project root). Config is never written into node_modules/.

Developing this package

CURSOR_AGENTS_SKIP_INSTALL=1 npm ci
npm run build:template
npm test

Overview

This repository provides a production-grade configuration for Cursor AI agents. It includes:

• Structured development workflow (Spec → Plan → Build → Test → Review → Ship)
• 11 specialized agents for different development roles (including Master Agent for brownfield calibration)
• 14 mandatory rules covering code quality, architecture, and operations
• 9 slash commands for common workflows (including /calibrate)
• 6 reference guides for security, testing, performance, accessibility, stack detection, and name collisions

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 | | /calibrate | Discover stack and align .cursor/ for brownfield projects |

Project Structure

.cursor/
├── AGENTS.md                    # Main AI configuration
│
├── commands/                    # Slash commands (9 total)
│   ├── 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
│   └── calibrate.md             # /calibrate — Brownfield stack calibration
│
├── agents/                      # Specialized agents (11 total)
│   ├── master-agent.md          # Master Agent — brownfield calibration
│   ├── 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, .mdc format)
│   ├── clean-code.mdc           # Clean Code principles
│   ├── code-style.mdc           # Formatting & naming
│   ├── error-handling.mdc       # Error patterns
│   ├── tech-stack.mdc           # Approved technologies
│   ├── system-design.mdc        # System design patterns
│   ├── project-structure.mdc    # Folder organization
│   ├── api-conventions.mdc      # REST API standards
│   ├── naming-conventions.mdc   # Naming patterns
│   ├── database.mdc             # Database patterns
│   ├── security.mdc             # Security requirements
│   ├── monitoring.mdc           # Observability
│   ├── testing.mdc              # Test standards
│   └── git-workflow.mdc         # 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
│   └── frontend-performance/SKILL.md  # Core Web Vitals & UI performance
│
├── references/                  # Quick checklists
│   ├── security-checklist.md
│   ├── testing-patterns.md
│   ├── performance-checklist.md
│   └── accessibility-checklist.md
│
└── settings.json                # Project settings

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

All 13 rules in .cursor/rules/ must be followed:

Code Quality

• clean-code.mdc — Variables, functions, SOLID, async/await
• code-style.mdc — 2-space indent, single quotes, semicolons
• error-handling.mdc — AppError class, centralized handler

Architecture

• tech-stack.mdc — Approved technologies only
• system-design.mdc — CAP, caching, scaling patterns
• project-structure.mdc — Layered architecture
• api-conventions.mdc — REST standards, response envelopes

Data & Naming

• naming-conventions.mdc — Cache keys, DB, queues, env vars
• database.mdc — Prisma patterns, N+1 prevention

Operations

• security.mdc — CRITICAL — Never violate
• monitoring.mdc — Prometheus, Grafana, alerting
• testing.mdc — 80% coverage minimum
• git-workflow.mdc — Conventional commits

Quick Start

# Clone repository
git clone <repo-url>
cd ai-agent

# Copy to your project
cp -r .cursor/ /path/to/your/project/
cp AGENTS.md /path/to/your/project/   # Root-level agent instructions (optional)

# Or use as template

Using Commands

# In Cursor, use slash commands:
/spec "User authentication feature"
/plan
/build
/test
/review
/deploy

Using Agents

"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
• .cursor/settings.local.json
• .cursor/AGENTS.local.md

Always:

• Use environment variables
• Validate all inputs
• Hash passwords (bcrypt >= 12 rounds)
• Parameterize queries

Contributing

1. Follow the development workflow (/spec → /plan → /build)
2. Ensure all tests pass
3. Run /review before submitting PR
4. Follow conventional commit format

Credits

• Workflow inspired by addyosmani/agent-skills
• Best practices from Software Engineering at Google
• Clean Code principles from Robert C. Martin

Author

Code Web Khong Kho

| Platform | Link | |----------|------| | Facebook | facebook.com/codewebkhongkho | | TikTok | @code.web.khng.kh | | Website | codewebkhongkho.com |