AI Agent Project

Production-grade configuration for Claude Code and Cursor — shared rules, specialized agents, workflow prompts, and checklists you can drop into any repository.

Royal Solution

Open-source AI agent scaffolding by Royal Solution — use it in your own projects and teams.

Adapted from fdhhhdjd/Class-AI-Agent · Community & docs · Code Web Khong Kho

Contents

• Why use this
• Install (quick)
• Overview
• Development workflow
• Project structure
• Specialized agents
• Approved tech stack
• Mandatory rules
• Using commands & agents
• Key concepts
• Security
• Contributing
• Publishing to npm (maintainers)
• Credits

Why use this

| You get | Details | |--------|---------| | Two layouts | .claude/ for Claude Code (.md rules) and .cursor/ for Cursor (.mdc rules + CURSOR.md) | | One workflow | Spec → Plan → Build → Test → Review → Ship | | 10 agent personas | Frontend, backend, architect, review, QA, security, PM, UX, SEO, test engineer | | 13 topic rules | Code style, security, API, DB, testing, git, and more (same ideas in both trees) | | npx installer | Copies the folders into your project in one command |

Root AGENTS.md points Cursor at .cursor/CURSOR.md.

Install (quick)

Requires Node.js 16.7+.

npx class-ai-agent

Install into another directory, or only Claude / only Cursor:

npx class-ai-agent --dir /path/to/your/project
npx class-ai-agent --claude
npx class-ai-agent --cursor
npx class-ai-agent --force    # overwrite existing
npx class-ai-agent --help

From a clone (local dev):

git clone https://github.com/khoantd/class-ai-agent.git
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: copy .claude/, .cursor/, and AGENTS.md into your project root.

Overview

This repo ships two parallel trees so you can use the same habits in Claude Code and Cursor:

| Layout | Tool | What you use | |--------|------|----------------| | .claude/ | Claude Code | Slash commands, CLAUDE.md, rules as .md | | .cursor/ | Cursor | Project rules as .mdc, hub CURSOR.md, @ file mentions |

What is inside:

• Structured workflow (Spec → Plan → Build → Test → Review → Ship)
• 10 specialized agents (markdown personas under agents/)
• 13 mandatory topic rules (plus cursor-overview.mdc under .cursor/rules/)
• 9 workflow prompts under commands/
• 6 skills (TDD, code review, incremental implementation, deploy, security review, UI/UX Pro Max)
• 4 reference checklists (security, testing, performance, accessibility)

Keep .claude/ and .cursor/ in sync when you change standards.

Development Workflow

┌──────────────────────────────────────────────────────────────────┐
│   /spec  →  /plan  →  /build  →  /test  →  /review  →  /deploy   │
│   Define     Plan     Build      Verify    Review      Ship      │
└──────────────────────────────────────────────────────────────────┘

| Phase | Command | Purpose | |-------|---------|---------| | Define | /spec | PRD: objectives, scope, boundaries | | Plan | /plan | Vertical slices, acceptance criteria | | Build | /build | Incremental implementation, TDD | | Verify | /test | Tests (RED → GREEN → REFACTOR) | | Review | /review | Five-axis code review | | Ship | /deploy | Build, test, deploy |

Supporting: /debug, /simplify, /fix-issue (see commands/).

Project Structure

.claude/ (Claude Code)

.claude/
├── CLAUDE.md                 # Main configuration
├── commands/                 # 9 workflow prompts (spec, plan, build, …)
├── agents/                   # 10 personas
├── rules/                    # 13 mandatory topic rules (.md)
├── skills/                   # TDD, review, deploy, …
├── references/               # Checklists
└── settings.json

.cursor/ (Cursor)

Same ideas as .claude/ for commands/, agents/, skills/, references/. Differences:

| Item | Role | |------|------| | CURSOR.md | Hub (like CLAUDE.md, Cursor-focused) | | rules/*.mdc | Project rules + YAML; security.mdc and cursor-overview.mdc are central | | settings.json | Path hints (mirrors Claude layout) | | AGENTS.md (repo root) | Entry pointer for Cursor |

.cursor/
├── CURSOR.md
├── settings.json
├── commands/
├── agents/
├── rules/                    # 14 × .mdc (13 topics + cursor-overview)
├── skills/
└── references/

Skill notes

• ui-ux-pro-max/: A UI/UX-oriented skill bundle (includes datasets under data/ and helper scripts under scripts/) to support design-system decisions and UX guidelines.

Specialized Agents

| Area | Agents | |------|--------| | Development | Frontend, Backend, Systems Architect | | Quality | Code Reviewer, Test Engineer, Security Auditor, QA | | Product | Project Manager, UI/UX Designer, Copywriter/SEO |

Full definitions live in agents/*.md. In Cursor, @-include a file when you want that role.

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 / RabbitMQ | | Auth | NextAuth.js / JWT + bcrypt | | Testing | Vitest + Playwright | | Monitoring | Prometheus + Grafana + Pino | | CI/CD | GitHub Actions | | Deploy | Vercel + Railway/Fly.io |

Details and alternatives are in rules/tech-stack.md (or .mdc in Cursor).

Mandatory rules

Use .claude/rules/*.md or .cursor/rules/*.mdc (paired content; Cursor applies .mdc frontmatter).

| Theme | Files | |-------|--------| | Code quality | clean-code, code-style, error-handling | | Architecture | tech-stack, system-design, project-structure, api-conventions | | Data | naming-conventions, database | | Operations | security (critical), monitoring, testing, git-workflow |

Using commands & agents

Claude Code — run slash commands in the tool, e.g.:

/spec "User authentication feature"
/plan
/build
/test
/review
/deploy

Cursor — prompts live under .cursor/commands/. Open the file, copy the section you need, or @ it (e.g. @.cursor/commands/spec.md).

Agents — describe the role in natural language, or in Cursor @ an agent file, e.g. @.cursor/agents/code-reviewer.md.

Key concepts

Five-axis review

1. Correctness — Behavior, edge cases, tests
2. Readability — Names, structure
3. Architecture — Patterns, boundaries
4. Security — Validation, auth, secrets
5. Performance — Queries, async, pagination

TDD

RED (failing test) → GREEN (minimal pass) → REFACTOR.

Vertical slices

Ship thin end-to-end slices (DB + API + UI), not “all models first, then all routes.”

Security

Do not commit: .env, secrets, API keys, .claude/settings.local.json, or local-only Cursor overrides with secrets.

Do: environment variables, input validation, strong password hashing, parameterized queries.

Contributing

1. Follow the workflow (/spec → /plan → /build, or the same prompts under .cursor/commands/).
2. Keep tests green.
3. Run /review before opening a PR.
4. Use conventional commits.
5. Update both .claude/ and .cursor/ when rules or workflows change.

Publishing to npm (maintainers)

package.json name: class-ai-agent. Use npm publish --access public after npm login.

If publish fails with two-factor authentication required:

1. On npmjs.com → Account → enable Two-Factor Authentication (include writes for publishing).
2. Run npm logout then npm login.
3. Run npm publish --access public again and enter the OTP when prompted.

For CI, use an npm access token with publish permission and set NPM_TOKEN as documented by npm.

Each version number can only be published once. After 1.2.0 is on the registry, you must bump before the next upload, for example:

npm version patch --no-git-tag-version
npm publish --access public

That advances patch (e.g. 1.2.0 → 1.2.1). Use npm version minor or major when the change warrants it.

Credits

• Royal Solution — project and scaffolding.
• Upstream inspiration: fdhhhdjd/Class-AI-Agent, addyosmani/agent-skills.