class-ai-agent 1.2.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +204 -281
  2. package/package.json +3 -2
  3. package/royal-solution-logo-v2.svg +58 -0
package/README.md CHANGED
@@ -1,41 +1,113 @@
1
- # AI Agent Project — Production-Grade Configuration
1
+ # AI Agent Project
2
+
3
+ **Production-grade configuration for [Claude Code](https://code.claude.com/docs) and [Cursor](https://cursor.com)** — shared rules, specialized agents, workflow prompts, and checklists you can drop into any repository.
2
4
 
3
5
  <div align="center">
4
- <img src="https://res.cloudinary.com/ecommerce2021/image/upload/v1768626951/dev_efjbzw.jpg" alt="Code Web Khong Kho" width="120" style="border-radius: 50%"/>
5
6
 
6
- <h3>Production-ready AI Agent configuration for Claude Code &amp; Cursor</h3>
7
- <p>Structured workflows, specialized agents, mandatory rules, and best practices</p>
7
+ <p>
8
+ <img src="royal-solution-logo-v2.svg" alt="Royal Solution" width="280" />
9
+ </p>
10
+
11
+ ### Royal Solution
12
+
13
+ Open-source AI agent scaffolding by **Royal Solution** — use it in your own projects and teams.
14
+
15
+ <sub>Adapted from <a href="https://github.com/fdhhhdjd/Class-AI-Agent">fdhhhdjd/Class-AI-Agent</a> · Community &amp; docs · <a href="https://codewebkhongkho.com/portfolios">Code Web Khong Kho</a></sub>
8
16
 
9
- ![Version](https://img.shields.io/badge/version-1.2.0-blue?style=flat-square)
10
- [![Facebook](https://img.shields.io/badge/Facebook-Code%20Web%20Khong%20Kho-1877F2?logo=facebook)](https://www.facebook.com/codewebkhongkho)
11
- [![TikTok](https://img.shields.io/badge/TikTok-@code.web.khng.kh-000000?logo=tiktok)](https://www.tiktok.com/@code.web.khng.kh)
12
- [![Website](https://img.shields.io/badge/Website-codewebkhongkho.com-FF6B35?logo=google-chrome)](https://codewebkhongkho.com/portfolios)
17
+ <p>
18
+ <a href="https://www.npmjs.com/package/class-ai-agent"><img src="https://img.shields.io/npm/v/class-ai-agent?label=npm&logo=npm&style=flat-square" alt="npm version" /></a>
19
+ <img src="https://img.shields.io/badge/node-%3E%3D16.7-339933?logo=node.js&logoColor=white&style=flat-square" alt="Node.js 16.7+" />
20
+ <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License MIT" />
21
+ <img src="https://img.shields.io/badge/version-1.2.1-blue?style=flat-square" alt="Version" />
22
+ </p>
13
23
 
14
- <sub>Inspired by <a href="https://github.com/addyosmani/agent-skills">addyosmani/agent-skills</a></sub>
15
24
  </div>
16
25
 
17
26
  ---
18
27
 
19
- ## Overview
28
+ ## Contents
29
+
30
+ - [Why use this](#why-use-this)
31
+ - [Install (quick)](#install-quick)
32
+ - [Overview](#overview)
33
+ - [Development workflow](#development-workflow)
34
+ - [Project structure](#project-structure)
35
+ - [Specialized agents](#specialized-agents)
36
+ - [Approved tech stack](#approved-tech-stack)
37
+ - [Mandatory rules](#mandatory-rules)
38
+ - [Using commands & agents](#using-commands--agents)
39
+ - [Key concepts](#key-concepts)
40
+ - [Security](#security)
41
+ - [Contributing](#contributing)
42
+ - [Publishing to npm (maintainers)](#publishing-to-npm-maintainers)
43
+ - [Credits](#credits)
44
+
45
+ ---
46
+
47
+ ## Why use this
48
+
49
+ | You get | Details |
50
+ |--------|---------|
51
+ | **Two layouts** | **`.claude/`** for Claude Code (`.md` rules) and **`.cursor/`** for Cursor (`.mdc` rules + `CURSOR.md`) |
52
+ | **One workflow** | Spec → Plan → Build → Test → Review → Ship |
53
+ | **10 agent personas** | Frontend, backend, architect, review, QA, security, PM, UX, SEO, test engineer |
54
+ | **13 topic rules** | Code style, security, API, DB, testing, git, and more (same ideas in both trees) |
55
+ | **`npx` installer** | Copies the folders into your project in one command |
56
+
57
+ Root **`AGENTS.md`** points Cursor at **`.cursor/CURSOR.md`**.
58
+
59
+ ---
60
+
61
+ ## Install (quick)
62
+
63
+ Requires **Node.js [16.7+](https://nodejs.org/)**.
20
64
 
21
- This repository provides a **production-grade configuration** for AI-assisted development. It includes **two parallel layouts**:
65
+ ```bash
66
+ npx class-ai-agent
67
+ ```
22
68
 
23
- | Layout | Tool | Purpose |
24
- |--------|------|---------|
25
- | **`.claude/`** | [Claude Code](https://code.claude.com/docs) | Slash commands, `CLAUDE.md`, rules as `.md` |
26
- | **`.cursor/`** | [Cursor](https://cursor.com) | Same workflows; rules as **`.mdc`** (Cursor project rules); hub doc **`CURSOR.md`** |
69
+ Install into another directory, or only Claude / only Cursor:
27
70
 
28
- Shared contents:
71
+ ```bash
72
+ npx class-ai-agent --dir /path/to/your/project
73
+ npx class-ai-agent --claude
74
+ npx class-ai-agent --cursor
75
+ npx class-ai-agent --force # overwrite existing
76
+ npx class-ai-agent --help
77
+ ```
29
78
 
30
- - **Structured development workflow** (Spec → Plan → Build → Test → Review → Ship)
31
- - **10 specialized agents** for different development roles
32
- - **13 mandatory topic rules** (same content in `.claude/rules/` and `.cursor/rules/`), plus **`cursor-overview.mdc`** in `.cursor/rules/` for Cursor workflow entry
33
- - **9 workflow prompts** (slash-style command markdown files)
34
- - **4 reference checklists** for security, testing, performance, and accessibility
79
+ **From a clone** (local dev):
35
80
 
36
- Root **`AGENTS.md`** points agents at **`.cursor/CURSOR.md`** for Cursor-oriented entry.
81
+ ```bash
82
+ git clone https://github.com/khoantd/class-ai-agent.git
83
+ cd class-ai-agent
84
+ npm exec -- class-ai-agent --dir /path/to/your/project
85
+ # or: node bin/class-ai-agent.cjs --dir /path/to/your/project
86
+ ```
37
87
 
38
- The same files can be installed with **`npx`** (see [Quick Start](#quick-start)).
88
+ **Manual copy:** copy **`.claude/`**, **`.cursor/`**, and **`AGENTS.md`** into your project root.
89
+
90
+ ---
91
+
92
+ ## Overview
93
+
94
+ This repo ships **two parallel trees** so you can use the same habits in Claude Code and Cursor:
95
+
96
+ | Layout | Tool | What you use |
97
+ |--------|------|----------------|
98
+ | **`.claude/`** | Claude Code | Slash commands, **`CLAUDE.md`**, rules as **`.md`** |
99
+ | **`.cursor/`** | Cursor | Project rules as **`.mdc`**, hub **`CURSOR.md`**, **`@`** file mentions |
100
+
101
+ What is inside:
102
+
103
+ - **Structured workflow** (Spec → Plan → Build → Test → Review → Ship)
104
+ - **10 specialized agents** (markdown personas under `agents/`)
105
+ - **13 mandatory topic rules** (plus **`cursor-overview.mdc`** under `.cursor/rules/`)
106
+ - **9 workflow prompts** under `commands/`
107
+ - **5 skills** (TDD, code review, incremental implementation, deploy, security review)
108
+ - **4 reference checklists** (security, testing, performance, accessibility)
109
+
110
+ Keep **`.claude/`** and **`.cursor/`** in sync when you change standards.
39
111
 
40
112
  ---
41
113
 
@@ -43,363 +115,214 @@ The same files can be installed with **`npx`** (see [Quick Start](#quick-start))
43
115
 
44
116
  ```
45
117
  ┌──────────────────────────────────────────────────────────────────┐
46
- │ │
47
- │ /spec → /plan → /build → /test → /review → /deploy │
48
- │ │
49
- │ Define Plan Build Verify Review Ship │
50
- │ │
118
+ │ /spec → /plan → /build → /test → /review → /deploy │
119
+ │ Define Plan Build Verify Review Ship │
51
120
  └──────────────────────────────────────────────────────────────────┘
52
121
  ```
53
122
 
54
- | Phase | Command | Description |
55
- |-------|---------|-------------|
56
- | **Define** | `/spec` | Create PRD with objectives, scope, and boundaries |
57
- | **Plan** | `/plan` | Decompose into vertical slices with acceptance criteria |
58
- | **Build** | `/build` | Implement incrementally using TDD |
59
- | **Verify** | `/test` | Write tests with RED-GREEN-REFACTOR |
123
+ | Phase | Command | Purpose |
124
+ |-------|---------|---------|
125
+ | **Define** | `/spec` | PRD: objectives, scope, boundaries |
126
+ | **Plan** | `/plan` | Vertical slices, acceptance criteria |
127
+ | **Build** | `/build` | Incremental implementation, TDD |
128
+ | **Verify** | `/test` | Tests (RED → GREEN → REFACTOR) |
60
129
  | **Review** | `/review` | Five-axis code review |
61
- | **Ship** | `/deploy` | Build, test, and deploy |
130
+ | **Ship** | `/deploy` | Build, test, deploy |
62
131
 
63
- ### Supporting Commands
64
-
65
- | Command | Description |
66
- |---------|-------------|
67
- | `/debug` | Systematic error diagnosis |
68
- | `/simplify` | Reduce code complexity |
69
- | `/fix-issue` | Analyze and fix issues |
132
+ **Supporting:** `/debug`, `/simplify`, `/fix-issue` (see `commands/`).
70
133
 
71
134
  ---
72
135
 
73
136
  ## Project Structure
74
137
 
75
- ### Claude Code — `.claude/`
138
+ ### `.claude/` (Claude Code)
76
139
 
77
140
  ```
78
141
  .claude/
79
- ├── CLAUDE.md # Main AI configuration
80
- │
81
- ├── commands/ # Workflow prompts (9 files)
82
- │ ├── spec.md # /spec — PRD creation
83
- │ ├── plan.md # /plan — Task breakdown
84
- │ ├── build.md # /build — Incremental implementation
85
- │ ├── test.md # /test — TDD workflow
86
- │ ├── review.md # /review — Code review
87
- │ ├── deploy.md # /deploy — Deployment
88
- │ ├── debug.md # /debug — Error diagnosis
89
- │ ├── simplify.md # /simplify — Code simplification
90
- │ └── fix-issue.md # /fix-issue — Issue resolution
91
- │
92
- ├── agents/ # Specialized agents (10 total)
93
- │ ├── frontend.md # Frontend Developer
94
- │ ├── backend.md # Backend Developer
95
- │ ├── systems-architect.md # Systems Architect
96
- │ ├── code-reviewer.md # Code Reviewer
97
- │ ├── test-engineer.md # Test Engineer
98
- │ ├── security-auditor.md # Security Auditor
99
- │ ├── qa.md # QA Engineer
100
- │ ├── project-manager.md # Project Manager
101
- │ ├── ui-ux-designer.md # UI/UX Designer
102
- │ └── copywriter-seo.md # Copywriter/SEO
103
- │
104
- ├── rules/ # Mandatory rules (13 total)
105
- │ ├── clean-code.md # Clean Code principles
106
- │ ├── code-style.md # Formatting & naming
107
- │ ├── error-handling.md # Error patterns
108
- │ ├── tech-stack.md # Approved technologies
109
- │ ├── system-design.md # System design patterns
110
- │ ├── project-structure.md # Folder organization
111
- │ ├── api-conventions.md # REST API standards
112
- │ ├── naming-conventions.md # Naming patterns
113
- │ ├── database.md # Database patterns
114
- │ ├── security.md # Security requirements
115
- │ ├── monitoring.md # Observability
116
- │ ├── testing.md # Test standards
117
- │ └── git-workflow.md # Git conventions
118
- │
119
- ├── skills/ # Advanced skills
120
- │ ├── tdd/SKILL.md # Test-Driven Development
121
- │ ├── code-review/SKILL.md # Five-axis review
122
- │ ├── incremental-implementation/SKILL.md
123
- │ ├── deploy/SKILL.md
124
- │ └── security-review/SKILL.md
125
- │
126
- ├── references/ # Quick checklists
127
- │ ├── security-checklist.md
128
- │ ├── testing-patterns.md
129
- │ ├── performance-checklist.md
130
- │ └── accessibility-checklist.md
131
- │
132
- └── settings.json # Project settings (paths & dirs)
142
+ ├── CLAUDE.md # Main configuration
143
+ ├── commands/ # 9 workflow prompts (spec, plan, build, …)
144
+ ├── agents/ # 10 personas
145
+ ├── rules/ # 13 mandatory topic rules (.md)
146
+ ├── skills/ # TDD, review, deploy, …
147
+ ├── references/ # Checklists
148
+ └── settings.json
133
149
  ```
134
150
 
135
- ### Cursor — `.cursor/`
151
+ ### `.cursor/` (Cursor)
136
152
 
137
- Mirrors `.claude/` for agents, commands, skills, and references. Differences:
153
+ Same ideas as `.claude/` for `commands/`, `agents/`, `skills/`, `references/`. Differences:
138
154
 
139
- | Item | Notes |
140
- |------|--------|
141
- | **`CURSOR.md`** | Hub doc (same workflow story as `CLAUDE.md`, Cursor-specific usage) |
142
- | **`rules/*.mdc`** | Cursor project rules with YAML frontmatter; **`security.mdc`** is always applied; **`cursor-overview.mdc`** explains workflow and paths |
143
- | **`settings.json`** | Directory map (parallel to `.claude/settings.json`) |
144
- | **`AGENTS.md` (repo root)** | Short pointer to `.cursor/CURSOR.md` for Cursor |
155
+ | Item | Role |
156
+ |------|------|
157
+ | **`CURSOR.md`** | Hub (like `CLAUDE.md`, Cursor-focused) |
158
+ | **`rules/*.mdc`** | Project rules + YAML; **`security.mdc`** and **`cursor-overview.mdc`** are central |
159
+ | **`settings.json`** | Path hints (mirrors Claude layout) |
160
+ | **`AGENTS.md`** (repo root) | Entry pointer for Cursor |
145
161
 
146
162
  ```
147
163
  .cursor/
148
164
  ├── CURSOR.md
149
165
  ├── settings.json
150
- ├── commands/ # Same 9 prompts — open or @-include in Chat/Composer
151
- ├── agents/ # Same 10 personas — @-mention files when needed
152
- ├── rules/ # 14 × .mdc (13 topics + cursor-overview)
166
+ ├── commands/
167
+ ├── agents/
168
+ ├── rules/ # 14 × .mdc (13 topics + cursor-overview)
153
169
  ├── skills/
154
- ├── references/
170
+ └── references/
155
171
  ```
156
172
 
157
- Keep **`.claude/`** and **`.cursor/`** aligned when you change standards or workflows.
158
-
159
173
  ---
160
174
 
161
175
  ## Specialized Agents
162
176
 
163
- ### Development Agents
164
-
165
- | Agent | Role | Invoke When |
166
- |-------|------|-------------|
167
- | **Frontend Developer** | Next.js, React, TypeScript, UI | Components, pages, state |
168
- | **Backend Developer** | Express, Prisma, Redis, BullMQ | APIs, services, jobs |
169
- | **Systems Architect** | Architecture, ADRs, scaling | System design decisions |
170
-
171
- ### Quality Agents
172
-
173
- | Agent | Role | Invoke When |
174
- |-------|------|-------------|
175
- | **Code Reviewer** | Five-axis code review | PR reviews, quality checks |
176
- | **Test Engineer** | TDD, coverage, test strategy | Writing and reviewing tests |
177
- | **Security Auditor** | Vulnerability, threat modeling | Security reviews |
178
- | **QA Engineer** | Test plans, E2E, bug reports | Quality assurance |
179
-
180
- ### Product Agents
177
+ | Area | Agents |
178
+ |------|--------|
179
+ | **Development** | Frontend, Backend, Systems Architect |
180
+ | **Quality** | Code Reviewer, Test Engineer, Security Auditor, QA |
181
+ | **Product** | Project Manager, UI/UX Designer, Copywriter/SEO |
181
182
 
182
- | Agent | Role | Invoke When |
183
- |-------|------|-------------|
184
- | **Project Manager** | Stories, sprints, planning | Project planning |
185
- | **UI/UX Designer** | Design system, accessibility | UX decisions |
186
- | **Copywriter/SEO** | Copy, meta tags, SEO | Content creation |
183
+ Full definitions live in **`agents/*.md`**. In Cursor, **`@`**-include a file when you want that role.
187
184
 
188
185
  ---
189
186
 
190
- ## Approved Tech Stack
187
+ ## Approved tech stack
191
188
 
192
189
  | Layer | Technology |
193
- |-------|-----------|
190
+ |-------|------------|
194
191
  | **Frontend (SEO)** | Next.js 14 (App Router) |
195
- | **Frontend (Admin)** | React + Vite |
192
+ | **Frontend (admin)** | React + Vite |
196
193
  | **Styling** | Tailwind CSS + shadcn/ui |
197
194
  | **State** | Zustand + TanStack Query |
198
195
  | **Backend** | Express.js + TypeScript |
199
196
  | **ORM** | Prisma |
200
197
  | **Database** | PostgreSQL |
201
198
  | **Cache** | Redis (ioredis) |
202
- | **Queue** | BullMQ (simple) / RabbitMQ (enterprise) |
199
+ | **Queue** | BullMQ / RabbitMQ |
203
200
  | **Auth** | NextAuth.js / JWT + bcrypt |
204
201
  | **Testing** | Vitest + Playwright |
205
202
  | **Monitoring** | Prometheus + Grafana + Pino |
206
203
  | **CI/CD** | GitHub Actions |
207
204
  | **Deploy** | Vercel + Railway/Fly.io |
208
205
 
209
- ---
210
-
211
- ## Mandatory Rules
212
-
213
- 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.
214
-
215
- ### Code Quality
216
- - **clean-code.md** — Variables, functions, SOLID, async/await
217
- - **code-style.md** — 2-space indent, single quotes, semicolons
218
- - **error-handling.md** — AppError class, centralized handler
219
-
220
- ### Architecture
221
- - **tech-stack.md** — Approved technologies only
222
- - **system-design.md** — CAP, caching, scaling patterns
223
- - **project-structure.md** — Layered architecture
224
- - **api-conventions.md** — REST standards, response envelopes
225
-
226
- ### Data & Naming
227
- - **naming-conventions.md** — Cache keys, DB, queues, env vars
228
- - **database.md** — Prisma patterns, N+1 prevention
229
-
230
- ### Operations
231
- - **security.md** — **CRITICAL** — Never violate
232
- - **monitoring.md** — Prometheus, Grafana, alerting
233
- - **testing.md** — 80% coverage minimum
234
- - **git-workflow.md** — Conventional commits
206
+ Details and alternatives are in **`rules/tech-stack.md`** (or **`.mdc`** in Cursor).
235
207
 
236
208
  ---
237
209
 
238
- ## Quick Start
210
+ ## Mandatory rules
239
211
 
240
- ### Install with `npx` (recommended)
212
+ Use **`.claude/rules/*.md`** or **`.cursor/rules/*.mdc`** (paired content; Cursor applies `.mdc` frontmatter).
241
213
 
242
- 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`):
243
-
244
- ```bash
245
- # Install into the current directory (.claude/, .cursor/, AGENTS.md)
246
- npx class-ai-agent
214
+ | Theme | Files |
215
+ |-------|--------|
216
+ | **Code quality** | `clean-code`, `code-style`, `error-handling` |
217
+ | **Architecture** | `tech-stack`, `system-design`, `project-structure`, `api-conventions` |
218
+ | **Data** | `naming-conventions`, `database` |
219
+ | **Operations** | **`security`** (critical), `monitoring`, `testing`, `git-workflow` |
247
220
 
248
- # Install into another folder
249
- npx class-ai-agent --dir /path/to/your/project
221
+ ---
250
222
 
251
- # Only Claude Code files
252
- npx class-ai-agent --claude
223
+ ## Using commands & agents
253
224
 
254
- # Only Cursor files + AGENTS.md
255
- npx class-ai-agent --cursor
225
+ **Claude Code** — run slash commands in the tool, e.g.:
256
226
 
257
- # Overwrite an existing install
258
- npx class-ai-agent --force
227
+ ```text
228
+ /spec "User authentication feature"
229
+ /plan
230
+ /build
231
+ /test
232
+ /review
233
+ /deploy
259
234
  ```
260
235
 
261
- Run **`npx class-ai-agent --help`** for all options.
236
+ **Cursor** — prompts live under **`.cursor/commands/`**. Open the file, copy the section you need, or **`@`** it (e.g. `@.cursor/commands/spec.md`).
262
237
 
263
- #### Publishing to npm (fix `E403` / 2FA)
238
+ **Agents** — describe the role in natural language, or in Cursor **`@`** an agent file, e.g. `@.cursor/agents/code-reviewer.md`.
264
239
 
265
- 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:
240
+ ---
266
241
 
267
- 1. Sign in at [npmjs.com](https://www.npmjs.com/) → **Account** → enable **Two-Factor Authentication** (use **Auth and writes** so publishing is covered).
268
- 2. In the terminal, refresh the session if needed: **`npm logout`** then **`npm login`**.
269
- 3. Run **`npm publish --access public`** again and enter your **one-time password** when npm asks for it.
242
+ ## Key concepts
270
243
 
271
- 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.
244
+ ### Five-axis review
272
245
 
273
- **From a git clone** (before publishing, or for development):
246
+ 1. **Correctness** — Behavior, edge cases, tests
247
+ 2. **Readability** — Names, structure
248
+ 3. **Architecture** — Patterns, boundaries
249
+ 4. **Security** — Validation, auth, secrets
250
+ 5. **Performance** — Queries, async, pagination
274
251
 
275
- ```bash
276
- cd class-ai-agent
277
- npm exec -- class-ai-agent --dir /path/to/your/project
278
- # or: node bin/class-ai-agent.cjs --dir /path/to/your/project
279
- ```
252
+ ### TDD
280
253
 
281
- ### Manual copy
254
+ `RED` (failing test) → `GREEN` (minimal pass) → `REFACTOR`.
282
255
 
283
- ```bash
284
- git clone https://github.com/khoantd/class-ai-agent.git
285
- cd class-ai-agent
256
+ ### Vertical slices
286
257
 
287
- cp -r .claude/ /path/to/your/project/
288
- cp -r .cursor/ /path/to/your/project/
289
- cp AGENTS.md /path/to/your/project/
290
- ```
258
+ Ship thin end-to-end slices (DB + API + UI), not “all models first, then all routes.”
291
259
 
292
- ### Using workflow prompts (commands)
260
+ ---
293
261
 
294
- **Claude Code** — use slash commands in the CLI:
262
+ ## Security
295
263
 
296
- ```text
297
- /spec "User authentication feature"
298
- /plan
299
- /build
300
- /test
301
- /review
302
- /deploy
303
- ```
264
+ **Do not commit:** `.env`, secrets, API keys, **`.claude/settings.local.json`**, or local-only Cursor overrides with secrets.
304
265
 
305
- **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.
266
+ **Do:** environment variables, input validation, strong password hashing, parameterized queries.
306
267
 
307
- ### Using Agents
268
+ ---
308
269
 
309
- Natural-language instructions still work. In **Cursor**, you can also **@ mention** an agent file (e.g. `@.cursor/agents/frontend.md`) to load that persona.
270
+ ## Contributing
310
271
 
311
- ```text
312
- "Act as the Frontend Developer and build the login page"
313
- "As Systems Architect, design the notification system"
314
- "Code Reviewer: review this PR for security issues"
315
- "Test Engineer: write tests for the payment flow"
316
- ```
272
+ 1. Follow the workflow (`/spec` → `/plan` → `/build`, or the same prompts under `.cursor/commands/`).
273
+ 2. Keep tests green.
274
+ 3. Run **`/review`** before opening a PR.
275
+ 4. Use [conventional commits](https://www.conventionalcommits.org/).
276
+ 5. Update **both** `.claude/` and `.cursor/` when rules or workflows change.
317
277
 
318
278
  ---
319
279
 
320
- ## Key Concepts
280
+ ## Publishing to npm (maintainers)
321
281
 
322
- ### Five-Axis Code Review
282
+ `package.json` name: **`class-ai-agent`**. Use **`npm publish --access public`** after `npm login`.
323
283
 
324
- Every code review evaluates:
284
+ <details>
285
+ <summary><strong>403 / two-factor authentication</strong></summary>
325
286
 
326
- 1. **Correctness** — Does it work? Edge cases?
327
- 2. **Readability** — Can others understand it?
328
- 3. **Architecture** — Follows patterns? Appropriate abstractions?
329
- 4. **Security** — Input validation? Auth? No secrets?
330
- 5. **Performance** — N+1? Pagination? Async?
287
+ If publish fails with **two-factor authentication** required:
331
288
 
332
- ### Test-Driven Development
289
+ 1. On [npmjs.com](https://www.npmjs.com/) → **Account** → enable **Two-Factor Authentication** (include **writes** for publishing).
290
+ 2. Run **`npm logout`** then **`npm login`**.
291
+ 3. Run **`npm publish --access public`** again and enter the OTP when prompted.
333
292
 
334
- ```
335
- RED → Write failing test
336
- GREEN → Write minimal code to pass
337
- REFACTOR → Improve while green
338
- ```
293
+ For CI, use an [npm access token](https://docs.npmjs.com/about-access-tokens) with publish permission and set **`NPM_TOKEN`** as documented by npm.
339
294
 
340
- ### Vertical Slicing
295
+ </details>
341
296
 
342
- Build features end-to-end, not layer-by-layer:
297
+ <details>
298
+ <summary><strong>403 / “cannot publish over the previously published versions”</strong></summary>
343
299
 
344
- ```
345
- ✅ Task 1: User can create task (DB + API + UI)
346
- ✅ Task 2: User can view tasks (DB + API + UI)
300
+ 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:
347
301
 
348
- ❌ Task 1: Create all DB models
349
- ❌ Task 2: Create all API routes
302
+ ```bash
303
+ npm version patch --no-git-tag-version
304
+ npm publish --access public
350
305
  ```
351
306
 
352
- ---
307
+ That advances **`patch`** (e.g. `1.2.0` → `1.2.1`). Use **`npm version minor`** or **`major`** when the change warrants it.
353
308
 
354
- ## Security
355
-
356
- **Never commit:**
357
- - `.env` files
358
- - API keys, secrets, passwords
359
- - `.claude/settings.local.json` (and any local-only Cursor overrides if you add them)
360
-
361
- **Always:**
362
- - Use environment variables
363
- - Validate all inputs
364
- - Hash passwords (bcrypt >= 12 rounds)
365
- - Parameterize queries
366
-
367
- ---
368
-
369
- ## Contributing
370
-
371
- 1. Follow the development workflow (`/spec` → `/plan` → `/build`, or the same prompts under `.cursor/commands/`)
372
- 2. Ensure all tests pass
373
- 3. Run `/review` before submitting PR
374
- 4. Follow conventional commit format
375
- 5. When changing rules or workflows, update **both** `.claude/` and `.cursor/` so they stay aligned
309
+ </details>
376
310
 
377
311
  ---
378
312
 
379
313
  ## Credits
380
314
 
381
- - Workflow inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
382
- - Best practices from *Software Engineering at Google*
383
- - Clean Code principles from Robert C. Martin
384
-
385
- ---
386
-
387
- ## Author
315
+ - **[Royal Solution](https://codewebkhongkho.com/portfolios)** — project and scaffolding.
316
+ - **[Code Web Khong Kho](https://codewebkhongkho.com/portfolios)** — documentation, community, and templates · [Facebook](https://www.facebook.com/codewebkhongkho) · [TikTok](https://www.tiktok.com/@code.web.khng.kh).
317
+ - Upstream inspiration: [fdhhhdjd/Class-AI-Agent](https://github.com/fdhhhdjd/Class-AI-Agent), [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills).
318
+ - Practices informed by *Software Engineering at Google* and Clean Code principles.
388
319
 
389
320
  <div align="center">
390
- <img src="https://res.cloudinary.com/ecommerce2021/image/upload/v1768626951/dev_efjbzw.jpg" alt="Code Web Khong Kho" width="80" style="border-radius: 50%"/>
391
321
 
392
- **Code Web Khong Kho**
322
+ <img src="https://res.cloudinary.com/ecommerce2021/image/upload/v1768626951/dev_efjbzw.jpg" alt="Code Web Khong Kho" width="80" style="border-radius: 50%" />
393
323
 
394
- | Platform | Link |
395
- |----------|------|
396
- | Facebook | [facebook.com/codewebkhongkho](https://www.facebook.com/codewebkhongkho) |
397
- | TikTok | [@code.web.khng.kh](https://www.tiktok.com/@code.web.khng.kh) |
398
- | Website | [codewebkhongkho.com](https://codewebkhongkho.com/portfolios) |
399
- </div>
324
+ **Code Web Khong Kho**
400
325
 
401
- ---
326
+ <sub>Made with care · <a href="https://www.facebook.com/codewebkhongkho">Facebook</a> · <a href="https://codewebkhongkho.com/portfolios">Website</a></sub>
402
327
 
403
- <div align="center">
404
- <sub>Made with care by <a href="https://www.facebook.com/codewebkhongkho">Code Web Khong Kho</a></sub>
405
328
  </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "class-ai-agent",
3
- "version": "1.2.0",
3
+ "version": "1.2.1",
4
4
  "description": "Production-grade AI agent configuration for Claude Code & Cursor",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -29,7 +29,8 @@
29
29
  "bin",
30
30
  ".claude",
31
31
  ".cursor",
32
- "AGENTS.md"
32
+ "AGENTS.md",
33
+ "royal-solution-logo-v2.svg"
33
34
  ],
34
35
  "scripts": {
35
36
  "prepack": "node -e \"const fs=require('fs');['.claude','.cursor','AGENTS.md'].forEach(p=>{if(!fs.existsSync(p))process.exit(1)})\"",
package/royal-solution-logo-v2.svg ADDED
@@ -0,0 +1,58 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 200" width="520" height="200">
2
+ <defs>
3
+ <linearGradient id="nodeGrad1" x1="0%" y1="0%" x2="100%" y2="100%">
4
+ <stop offset="0%" stop-color="#4a9be8"/>
5
+ <stop offset="100%" stop-color="#2d6fd4"/>
6
+ </linearGradient>
7
+ <linearGradient id="nodeGrad2" x1="0%" y1="0%" x2="100%" y2="100%">
8
+ <stop offset="0%" stop-color="#2d6fd4"/>
9
+ <stop offset="100%" stop-color="#1a4fa0"/>
10
+ </linearGradient>
11
+ <linearGradient id="nodeGrad3" x1="0%" y1="0%" x2="100%" y2="100%">
12
+ <stop offset="0%" stop-color="#1a3a7a"/>
13
+ <stop offset="100%" stop-color="#0f2654"/>
14
+ </linearGradient>
15
+ <linearGradient id="goldAccent" x1="0%" y1="0%" x2="100%" y2="100%">
16
+ <stop offset="0%" stop-color="#d4a843"/>
17
+ <stop offset="100%" stop-color="#f0c75e"/>
18
+ </linearGradient>
19
+ </defs>
20
+
21
+ <!-- === ASCENDING NODES ICON === -->
22
+ <g transform="translate(55, 100)">
23
+ <!-- Dashed connection lines -->
24
+ <line x1="-20" y1="30" x2="5" y2="8" stroke="#a3c8ee" stroke-width="1.8" stroke-dasharray="4,3" opacity="0.7"/>
25
+ <line x1="5" y1="8" x2="35" y2="-22" stroke="#7baee5" stroke-width="1.8" stroke-dasharray="4,3" opacity="0.7"/>
26
+ <line x1="-20" y1="30" x2="35" y2="-22" stroke="#5a94d8" stroke-width="1.5" stroke-dasharray="4,3" opacity="0.5"/>
27
+
28
+ <!-- Node 1 (smallest, bottom-left) -->
29
+ <circle cx="-20" cy="30" r="10" fill="url(#nodeGrad1)" opacity="0.85"/>
30
+ <circle cx="-20" cy="30" r="5.5" fill="none" stroke="#fff" stroke-width="1.5" opacity="0.5"/>
31
+
32
+ <!-- Node 2 (medium, middle) -->
33
+ <circle cx="5" cy="8" r="14" fill="url(#nodeGrad2)" opacity="0.9"/>
34
+ <circle cx="5" cy="8" r="8" fill="none" stroke="#fff" stroke-width="1.5" opacity="0.5"/>
35
+
36
+ <!-- Node 3 (largest, top-right) -->
37
+ <circle cx="35" cy="-22" r="20" fill="url(#nodeGrad3)"/>
38
+ <circle cx="35" cy="-22" r="12" fill="none" stroke="#fff" stroke-width="2" opacity="0.4"/>
39
+ <circle cx="35" cy="-22" r="6" fill="#2d6fd4" opacity="0.6"/>
40
+
41
+ <!-- Crown accent on top node -->
42
+ <polygon points="27,-46 31,-38 35,-42 39,-38 43,-46" fill="url(#goldAccent)" opacity="0.95"/>
43
+ <!-- Three crown dots -->
44
+ <circle cx="27" cy="-47.5" r="1.5" fill="#f0c75e"/>
45
+ <circle cx="35" cy="-43.5" r="1.5" fill="#f0c75e"/>
46
+ <circle cx="43" cy="-47.5" r="1.5" fill="#f0c75e"/>
47
+ </g>
48
+
49
+ <!-- === COMPANY NAME === -->
50
+ <text x="135" y="88" font-family="'Segoe UI', 'Helvetica Neue', Arial, sans-serif" font-size="42" font-weight="700" fill="#1a3a7a" letter-spacing="2">ROYAL</text>
51
+ <text x="135" y="128" font-family="'Segoe UI', 'Helvetica Neue', Arial, sans-serif" font-size="40" font-weight="300" fill="#2d6fd4" letter-spacing="6">SOLUTION</text>
52
+
53
+ <!-- Gold accent line -->
54
+ <rect x="135" y="140" width="90" height="2.5" rx="1.25" fill="url(#goldAccent)"/>
55
+
56
+ <!-- Tagline -->
57
+ <text x="135" y="163" font-family="'Segoe UI', 'Helvetica Neue', Arial, sans-serif" font-size="10.5" fill="#7a8aaa" letter-spacing="3.5" font-weight="400">TECHNOLOGY SOLUTIONS</text>
58
+ </svg>