contextos-agents 2.1.0 → 2.2.0

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 (192) hide show
  1. package/.agents/adapters/aider/export.js +2 -2
  2. package/.agents/adapters/claude/export.js +53 -2
  3. package/.agents/adapters/drift-detector.js +6 -3
  4. package/.agents/adapters/pure-compiler.js +18 -6
  5. package/.agents/ctx.js +13 -8
  6. package/.agents/plugins.js +347 -26
  7. package/.agents/profiles.js +32 -11
  8. package/README.md +38 -3
  9. package/bin/commands/hook.js +50 -12
  10. package/bin/commands/scan.js +10 -3
  11. package/bin/index.js +165 -53
  12. package/bin/lib/git-snapshot.js +70 -43
  13. package/bin/lib/scan.js +108 -27
  14. package/bin/lib/ui.js +140 -0
  15. package/catalog/skills/adapters/EXAMPLES.md +19 -0
  16. package/catalog/skills/adapters/SKILL.md +101 -0
  17. package/catalog/skills/adapters/TROUBLESHOOTING.md +7 -0
  18. package/catalog/skills/adapters/VALIDATION.json +12 -0
  19. package/catalog/skills/adapters/skill.yaml +13 -0
  20. package/catalog/skills/api-design/EXAMPLES.md +91 -0
  21. package/catalog/skills/api-design/SKILL.md +63 -0
  22. package/catalog/skills/api-design/TROUBLESHOOTING.md +54 -0
  23. package/catalog/skills/api-design/VALIDATION.json +11 -0
  24. package/catalog/skills/api-design/skill.yaml +14 -0
  25. package/catalog/skills/architecture-diagrams/SKILL.md +108 -0
  26. package/catalog/skills/architecture-diagrams/VALIDATION.json +12 -0
  27. package/catalog/skills/architecture-diagrams/skill.yaml +9 -0
  28. package/catalog/skills/brutalist-design/EXAMPLES.md +59 -0
  29. package/catalog/skills/brutalist-design/SKILL.md +150 -0
  30. package/catalog/skills/brutalist-design/VALIDATION.json +12 -0
  31. package/catalog/skills/brutalist-design/skill.yaml +10 -0
  32. package/catalog/skills/ci-cd/EXAMPLES.md +79 -0
  33. package/catalog/skills/ci-cd/SKILL.md +69 -0
  34. package/catalog/skills/ci-cd/TROUBLESHOOTING.md +52 -0
  35. package/catalog/skills/ci-cd/VALIDATION.json +11 -0
  36. package/catalog/skills/ci-cd/skill.yaml +13 -0
  37. package/catalog/skills/database/EXAMPLES.md +74 -0
  38. package/catalog/skills/database/SKILL.md +101 -0
  39. package/catalog/skills/database/TROUBLESHOOTING.md +18 -0
  40. package/catalog/skills/database/VALIDATION.json +11 -0
  41. package/catalog/skills/database/skill.yaml +14 -0
  42. package/catalog/skills/ddd/EXAMPLES.md +42 -0
  43. package/catalog/skills/ddd/SKILL.md +247 -0
  44. package/catalog/skills/ddd/TROUBLESHOOTING.md +19 -0
  45. package/catalog/skills/ddd/VALIDATION.json +12 -0
  46. package/catalog/skills/ddd/skill.yaml +14 -0
  47. package/catalog/skills/decisions/EXAMPLES.md +35 -0
  48. package/catalog/skills/decisions/SKILL.md +90 -0
  49. package/catalog/skills/decisions/TROUBLESHOOTING.md +13 -0
  50. package/catalog/skills/decisions/VALIDATION.json +12 -0
  51. package/catalog/skills/decisions/skill.yaml +13 -0
  52. package/catalog/skills/docker/EXAMPLES.md +56 -0
  53. package/catalog/skills/docker/SKILL.md +169 -0
  54. package/catalog/skills/docker/TROUBLESHOOTING.md +18 -0
  55. package/catalog/skills/docker/VALIDATION.json +11 -0
  56. package/catalog/skills/docker/skill.yaml +13 -0
  57. package/catalog/skills/fastapi/EXAMPLES.md +36 -0
  58. package/catalog/skills/fastapi/SKILL.md +171 -0
  59. package/catalog/skills/fastapi/TROUBLESHOOTING.md +19 -0
  60. package/catalog/skills/fastapi/VALIDATION.json +12 -0
  61. package/catalog/skills/fastapi/skill.yaml +14 -0
  62. package/catalog/skills/generators/EXAMPLES.md +19 -0
  63. package/catalog/skills/generators/SKILL.md +110 -0
  64. package/catalog/skills/generators/TROUBLESHOOTING.md +7 -0
  65. package/catalog/skills/generators/VALIDATION.json +12 -0
  66. package/catalog/skills/generators/skill.yaml +22 -0
  67. package/catalog/skills/generators/templates/API.md +77 -0
  68. package/catalog/skills/generators/templates/ARCHITECTURE.md +70 -0
  69. package/catalog/skills/generators/templates/DATABASE.md +42 -0
  70. package/catalog/skills/generators/templates/DECISION.md +46 -0
  71. package/catalog/skills/generators/templates/PRD.md +67 -0
  72. package/catalog/skills/generators/templates/PROJECT_GRAPH.md +56 -0
  73. package/catalog/skills/generators/templates/ROADMAP.md +51 -0
  74. package/catalog/skills/generators/templates/TASKS.md +43 -0
  75. package/catalog/skills/generators/templates/UI.md +73 -0
  76. package/catalog/skills/graphify/EXAMPLES.md +73 -0
  77. package/catalog/skills/graphify/SKILL.md +130 -0
  78. package/catalog/skills/graphify/VALIDATION.json +12 -0
  79. package/catalog/skills/graphify/skill.yaml +13 -0
  80. package/catalog/skills/impeccable-design/EXAMPLES.md +26 -0
  81. package/catalog/skills/impeccable-design/SKILL.md +201 -0
  82. package/catalog/skills/impeccable-design/TROUBLESHOOTING.md +19 -0
  83. package/catalog/skills/impeccable-design/VALIDATION.json +12 -0
  84. package/catalog/skills/impeccable-design/skill.yaml +15 -0
  85. package/catalog/skills/interview-me/SKILL.md +97 -0
  86. package/catalog/skills/interview-me/VALIDATION.json +12 -0
  87. package/catalog/skills/interview-me/skill.yaml +9 -0
  88. package/catalog/skills/microservices/EXAMPLES.md +38 -0
  89. package/catalog/skills/microservices/SKILL.md +164 -0
  90. package/catalog/skills/microservices/TROUBLESHOOTING.md +19 -0
  91. package/catalog/skills/microservices/VALIDATION.json +12 -0
  92. package/catalog/skills/microservices/skill.yaml +14 -0
  93. package/catalog/skills/minimalist-design/EXAMPLES.md +58 -0
  94. package/catalog/skills/minimalist-design/SKILL.md +113 -0
  95. package/catalog/skills/minimalist-design/VALIDATION.json +12 -0
  96. package/catalog/skills/minimalist-design/skill.yaml +10 -0
  97. package/catalog/skills/nestjs/EXAMPLES.md +40 -0
  98. package/catalog/skills/nestjs/SKILL.md +139 -0
  99. package/catalog/skills/nestjs/TROUBLESHOOTING.md +19 -0
  100. package/catalog/skills/nestjs/VALIDATION.json +12 -0
  101. package/catalog/skills/nestjs/skill.yaml +14 -0
  102. package/catalog/skills/nextjs/EXAMPLES.md +40 -0
  103. package/catalog/skills/nextjs/SKILL.md +163 -0
  104. package/catalog/skills/nextjs/TROUBLESHOOTING.md +19 -0
  105. package/catalog/skills/nextjs/VALIDATION.json +12 -0
  106. package/catalog/skills/nextjs/skill.yaml +14 -0
  107. package/catalog/skills/node/EXAMPLES.md +80 -0
  108. package/catalog/skills/node/SKILL.md +128 -0
  109. package/catalog/skills/node/TROUBLESHOOTING.md +19 -0
  110. package/catalog/skills/node/VALIDATION.json +12 -0
  111. package/catalog/skills/node/skill.yaml +14 -0
  112. package/catalog/skills/performance/EXAMPLES.md +30 -0
  113. package/catalog/skills/performance/SKILL.md +75 -0
  114. package/catalog/skills/performance/TROUBLESHOOTING.md +19 -0
  115. package/catalog/skills/performance/VALIDATION.json +12 -0
  116. package/catalog/skills/performance/skill.yaml +14 -0
  117. package/catalog/skills/react/EXAMPLES.md +79 -0
  118. package/catalog/skills/react/SKILL.md +132 -0
  119. package/catalog/skills/react/TROUBLESHOOTING.md +19 -0
  120. package/catalog/skills/react/VALIDATION.json +12 -0
  121. package/catalog/skills/react/skill.yaml +14 -0
  122. package/catalog/skills/react-best-practices/SKILL.md +158 -0
  123. package/catalog/skills/react-best-practices/VALIDATION.json +12 -0
  124. package/catalog/skills/react-best-practices/skill.yaml +13 -0
  125. package/catalog/skills/redesign-audit/SKILL.md +117 -0
  126. package/catalog/skills/redesign-audit/VALIDATION.json +12 -0
  127. package/catalog/skills/redesign-audit/skill.yaml +9 -0
  128. package/catalog/skills/security-audit/EXAMPLES.md +79 -0
  129. package/catalog/skills/security-audit/SKILL.md +91 -0
  130. package/catalog/skills/security-audit/TROUBLESHOOTING.md +46 -0
  131. package/catalog/skills/security-audit/VALIDATION.json +11 -0
  132. package/catalog/skills/security-audit/skill.yaml +14 -0
  133. package/catalog/skills/soft-design/EXAMPLES.md +51 -0
  134. package/catalog/skills/soft-design/SKILL.md +108 -0
  135. package/catalog/skills/soft-design/VALIDATION.json +12 -0
  136. package/catalog/skills/soft-design/skill.yaml +10 -0
  137. package/catalog/skills/state-management/EXAMPLES.md +56 -0
  138. package/catalog/skills/state-management/SKILL.md +168 -0
  139. package/catalog/skills/state-management/TROUBLESHOOTING.md +18 -0
  140. package/catalog/skills/state-management/VALIDATION.json +11 -0
  141. package/catalog/skills/state-management/skill.yaml +14 -0
  142. package/catalog/skills/subagent-orchestrator/SKILL.md +117 -0
  143. package/catalog/skills/subagent-orchestrator/VALIDATION.json +12 -0
  144. package/catalog/skills/subagent-orchestrator/skill.yaml +9 -0
  145. package/catalog/skills/system-design/EXAMPLES.md +75 -0
  146. package/catalog/skills/system-design/SKILL.md +419 -0
  147. package/catalog/skills/system-design/TROUBLESHOOTING.md +19 -0
  148. package/catalog/skills/system-design/VALIDATION.json +12 -0
  149. package/catalog/skills/system-design/skill.yaml +14 -0
  150. package/catalog/skills/terraform/EXAMPLES.md +74 -0
  151. package/catalog/skills/terraform/SKILL.md +55 -0
  152. package/catalog/skills/terraform/TROUBLESHOOTING.md +53 -0
  153. package/catalog/skills/terraform/VALIDATION.json +11 -0
  154. package/catalog/skills/terraform/skill.yaml +14 -0
  155. package/catalog/skills/testing/EXAMPLES.md +122 -0
  156. package/catalog/skills/testing/SKILL.md +70 -0
  157. package/catalog/skills/testing/TROUBLESHOOTING.md +18 -0
  158. package/catalog/skills/testing/VALIDATION.json +11 -0
  159. package/catalog/skills/testing/skill.yaml +14 -0
  160. package/catalog/skills/typescript/EXAMPLES.md +64 -0
  161. package/catalog/skills/typescript/SKILL.md +112 -0
  162. package/catalog/skills/typescript/TROUBLESHOOTING.md +19 -0
  163. package/catalog/skills/typescript/VALIDATION.json +12 -0
  164. package/catalog/skills/typescript/skill.yaml +14 -0
  165. package/catalog/skills/ui-design/EXAMPLES.md +21 -0
  166. package/catalog/skills/ui-design/SKILL.md +124 -0
  167. package/catalog/skills/ui-design/TROUBLESHOOTING.md +19 -0
  168. package/catalog/skills/ui-design/VALIDATION.json +12 -0
  169. package/catalog/skills/ui-design/skill.yaml +16 -0
  170. package/catalog/skills/ui-ux-pro/EXAMPLES.md +62 -0
  171. package/catalog/skills/ui-ux-pro/SKILL.md +418 -0
  172. package/catalog/skills/ui-ux-pro/TROUBLESHOOTING.md +19 -0
  173. package/catalog/skills/ui-ux-pro/VALIDATION.json +12 -0
  174. package/catalog/skills/ui-ux-pro/skill.yaml +14 -0
  175. package/catalog/skills/ux-design/EXAMPLES.md +36 -0
  176. package/catalog/skills/ux-design/SKILL.md +116 -0
  177. package/catalog/skills/ux-design/TROUBLESHOOTING.md +19 -0
  178. package/catalog/skills/ux-design/VALIDATION.json +12 -0
  179. package/catalog/skills/ux-design/skill.yaml +16 -0
  180. package/catalog/skills/vercel-optimize/SKILL.md +83 -0
  181. package/catalog/skills/vercel-optimize/VALIDATION.json +12 -0
  182. package/catalog/skills/vercel-optimize/scripts/collect-signals.mjs +131 -0
  183. package/catalog/skills/vercel-optimize/scripts/gate-investigations.mjs +142 -0
  184. package/catalog/skills/vercel-optimize/scripts/merge-signals.mjs +143 -0
  185. package/catalog/skills/vercel-optimize/scripts/scan-codebase.mjs +174 -0
  186. package/catalog/skills/vercel-optimize/skill.yaml +15 -0
  187. package/catalog/skills/web-accessibility/EXAMPLES.md +39 -0
  188. package/catalog/skills/web-accessibility/SKILL.md +151 -0
  189. package/catalog/skills/web-accessibility/TROUBLESHOOTING.md +19 -0
  190. package/catalog/skills/web-accessibility/VALIDATION.json +12 -0
  191. package/catalog/skills/web-accessibility/skill.yaml +14 -0
  192. package/package.json +3 -2
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: minimalist-ui
3
+ description: Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
4
+ ---
5
+
6
+ # Protocol: Premium Utilitarian Minimalism UI Architect
7
+
8
+ ## Overview
9
+
10
+ An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
11
+
12
+ ## When to Use
13
+
14
+ - When designing clean, editorial, or Notion-like document interfaces, workspaces, or notes apps.
15
+ - When creating minimalist SaaS dashboards, personal essays, portfolios, or agency landing pages.
16
+ - When asked for a "clean", "minimalist", "warm monochrome", or "flat bento-box" layout.
17
+
18
+ ## Rules & Patterns
19
+
20
+ ### 1. Absolute Negative Constraints (Banned Elements)
21
+
22
+ The AI must strictly avoid the following generic web development defaults:
23
+
24
+ - DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
25
+ - DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
26
+ - DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
27
+ - DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections).
28
+ - DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
29
+ - DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
30
+ - DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives.
31
+ - DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
32
+ - DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
33
+
34
+ ### 2. Typographic Architecture
35
+
36
+ The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel.
37
+
38
+ - **Primary Sans-Serif (Body, UI, Buttons):** Use clean, geometric, or system-native fonts with character (`'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`).
39
+ - **Editorial Serif (Hero Headings & Quotes):** (`'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`). Apply tight tracking (`-0.02em` to `-0.04em`) and tight line-height (`1.1`).
40
+ - **Monospace (Code, Keystrokes, Meta-data):** (`'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`).
41
+ - **Text Colors:** Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous line-height of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
42
+
43
+ ### 3. Color Palette (Warm Monochrome + Spot Pastels)
44
+
45
+ Color is a scarce resource, utilized only for semantic meaning or subtle accents.
46
+
47
+ - **Canvas / Background:** Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
48
+ - **Primary Surface (Cards):** `#FFFFFF` or `#F9F9F8`.
49
+ - **Structural Borders / Dividers:** Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
50
+ - **Accent Colors:** Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds:
51
+ - Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
52
+ - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
53
+ - Pale Green: `#EDF3EC` (Text: `#346538`)
54
+ - Pale Yellow: `#FBF3DB` (Text: `#956400`)
55
+
56
+ ### 4. Component Specifications
57
+
58
+ - **Bento Box Feature Grids:** Asymmetrical CSS Grid layouts. Cards have `border: 1px solid #EAEAEA`, crisp border-radius (`8px` to `12px` max), and generous internal padding (`24px` to `40px`).
59
+ - **Primary Call-To-Action (Buttons):** Solid `#111111`, text `#FFFFFF`, radius `4px` to `6px`, no box-shadow. Micro-scale `transform: scale(0.98)` on active.
60
+ - **Tags & Status Badges:** Pill-shaped (`rounded-full`), small typography (`text-xs`), uppercase with wide tracking (`0.05em`), pastel background.
61
+ - **Accordions (FAQ):** Separated by `border-bottom: 1px solid #EAEAEA` without card boxes. Crisp `+` / `-` toggle icons.
62
+ - **Keystroke Micro-UIs:** `<kbd className="border border-[#EAEAEA] rounded bg-[#F7F6F3] font-mono px-1.5 py-0.5 text-xs">`.
63
+
64
+ ### 5. Iconography & Imagery
65
+
66
+ - **System Icons:** Phosphor Icons (Bold/Fill) or Radix UI Icons for crisp, technical strokes.
67
+ - **Photography:** Desaturated images with warm tint and subtle grain overlay (`opacity: 0.04`).
68
+ - **Depth:** Subtle ambient gradients (`radial-gradient` with warm tones at `opacity: 0.03`) or minimal geometric line patterns.
69
+
70
+ ### 6. Subtle Motion & Micro-Animations
71
+
72
+ - **Scroll Entry:** Fade-in + `translateY(12px)` over 600ms via `IntersectionObserver`.
73
+ - **Hover States:** Subtle card lift with ultra-diffuse shadow (`0 2px 8px rgba(0,0,0,0.04)`).
74
+ - **Staggered Reveals:** Cascading delay (`calc(var(--index) * 80ms)`).
75
+
76
+ ## Code Examples
77
+
78
+ ```tsx
79
+ export function BentoFeatureCard({ title, description, badge, tagColor = "blue" }: { title: string; description: string; badge: string; tagColor?: string }) {
80
+ return (
81
+ <div className="bg-[#FFFFFF] border border-[#EAEAEA] rounded-xl p-8 hover:shadow-[0_2px_8px_rgba(0,0,0,0.04)] transition-all duration-200">
82
+ <div className="flex items-center justify-between mb-4">
83
+ <span className="text-xs uppercase tracking-wider font-mono font-medium px-2.5 py-0.5 rounded-full bg-[#E1F3FE] text-[#1F6C9F]">
84
+ {badge}
85
+ </span>
86
+ </div>
87
+ <h3 className="font-serif text-2xl tracking-tight text-[#111111] mb-2">{title}</h3>
88
+ <p className="text-sm text-[#787774] leading-relaxed">{description}</p>
89
+ </div>
90
+ );
91
+ }
92
+ ```
93
+
94
+ ## Validation Checklist
95
+
96
+ - [ ] Macro-whitespace established with generous vertical section padding (`py-24` to `py-32`).
97
+ - [ ] No pure black (`#000000`) for text or backgrounds.
98
+ - [ ] Borders use crisp `1px solid #EAEAEA` or `rgba(0,0,0,0.06)`.
99
+ - [ ] No generic AI buzzwords or emojis used in copy.
100
+ - [ ] Typography uses editorial serif headers paired with clean sans-serif body.
101
+ - [ ] Card corners constrained to crisp 8px-12px radius; no pill containers.
102
+
103
+ ## Common Mistakes
104
+
105
+ - Using heavy saturated primary colors for hero backgrounds.
106
+ - Adding default Tailwind drop-shadows (`shadow-lg`).
107
+ - Cluttering interfaces with emojis instead of clean SVG icons.
108
+ - Using default Inter or Roboto fonts without editorial contrast.
109
+
110
+ ## Integration Notes
111
+
112
+ - Complements `ui-ux-pro` for color tokens and accessibility.
113
+ - Integrates with `impeccable-design` for QA and anti-pattern enforcement.
@@ -0,0 +1,12 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "type": "object",
4
+ "properties": {
5
+ "rules_followed": {
6
+ "type": "boolean"
7
+ }
8
+ },
9
+ "required": [
10
+ "rules_followed"
11
+ ]
12
+ }
@@ -0,0 +1,10 @@
1
+ schemaVersion: 2
2
+ name: minimalist-design
3
+ category: design
4
+ type: instruction-only
5
+ description: Clean editorial-style interfaces with warm monochrome palettes and flat bento grids.
6
+ version: 1.0.0
7
+ resources:
8
+ - EXAMPLES.md
9
+ - SKILL.md
10
+ - VALIDATION.json
@@ -0,0 +1,40 @@
1
+ # nestjs Examples - Anti-patterns vs ContextOS Standard
2
+
3
+ ## Example 1: Input Validation and DTOs
4
+
5
+ ### Anti-pattern: Untyped Body or Manual Validation in Controller
6
+
7
+ ```typescript
8
+ // BAD: No runtime validation, controller stuffed with business rules
9
+ @Post('users')
10
+ async create(@Body() body: any) {
11
+ if (!body.email || !body.email.includes('@')) {
12
+ throw new BadRequestException('Invalid email');
13
+ }
14
+ return this.usersService.create(body);
15
+ }
16
+ ```
17
+
18
+ ### Best practice: ContextOS Standard (Class-Validator DTO + ValidationPipe)
19
+
20
+ ```typescript
21
+ // GOOD: Declarative runtime validation with clean separation
22
+ export class CreateUserDto {
23
+ @IsEmail({}, { message: 'A valid email is required' })
24
+ email: string;
25
+
26
+ @IsString()
27
+ @MinLength(8, { message: 'Password must be at least 8 characters long' })
28
+ password: string;
29
+ }
30
+
31
+ @Controller('users')
32
+ export class UsersController {
33
+ constructor(private readonly usersService: UsersService) {}
34
+
35
+ @Post()
36
+ async create(@Body() dto: CreateUserDto) {
37
+ return this.usersService.create(dto);
38
+ }
39
+ }
40
+ ```
@@ -0,0 +1,139 @@
1
+ ---
2
+ name: NestJS
3
+ description: >
4
+ ContextOS skill for NestJS
5
+ ---
6
+
7
+ # NestJS
8
+
9
+ ## Overview
10
+
11
+ Enterprise Node.js architecture standard using NestJS, TypeScript, and RxJS. Enforces strict modularity, dependency injection, repository pattern, DTO validation via class-validator, and clean layered architecture.
12
+
13
+ ## When to Use
14
+
15
+ Activate when building enterprise Node.js microservices, complex REST/GraphQL APIs, or scalable backends requiring strict architectural structure.
16
+
17
+ ## Rules & Patterns
18
+ <!-- Source: nestjs.md -->
19
+
20
+ ## NestJS - Best Practices
21
+
22
+ ## Module Architecture
23
+
24
+ - **One module per domain** - `UsersModule`, `AuthModule`, `OrdersModule`
25
+ - **Feature modules** - encapsulate related controllers, services, repositories
26
+ - **Shared module** - for cross-cutting concerns (logging, config, utils)
27
+ - **Core module** - singleton services (database, auth guards)
28
+
29
+ ```
30
+ src/
31
+ ├── modules/
32
+ │ ├── users/
33
+ │ │ ├── users.module.ts
34
+ │ │ ├── users.controller.ts
35
+ │ │ ├── users.service.ts
36
+ │ │ ├── users.repository.ts
37
+ │ │ ├── dto/
38
+ │ │ │ ├── create-user.dto.ts
39
+ │ │ │ └── update-user.dto.ts
40
+ │ │ ├── entities/
41
+ │ │ │ └── user.entity.ts
42
+ │ │ └── users.spec.ts
43
+ │ └── auth/
44
+ ├── shared/
45
+ │ ├── guards/
46
+ │ ├── interceptors/
47
+ │ ├── pipes/
48
+ │ └── filters/
49
+ ├── config/
50
+ └── app.module.ts
51
+ ```
52
+
53
+ ## Dependency Injection
54
+
55
+ ```typescript
56
+ @Injectable()
57
+ export class UsersService {
58
+ constructor(
59
+ @InjectRepository(User) private readonly usersRepo: Repository<User>,
60
+ private readonly configService: ConfigService,
61
+ ) {}
62
+ }
63
+ ```
64
+
65
+ - Prefer constructor injection
66
+ - Use custom providers for complex setup
67
+ - Scope: default is Singleton, use REQUEST scope only when needed
68
+
69
+ ## DTOs and Validation
70
+
71
+ ```typescript
72
+ import { IsEmail, IsString, MinLength } from 'class-validator';
73
+
74
+ export class CreateUserDto {
75
+ @IsEmail()
76
+ email: string;
77
+
78
+ @IsString()
79
+ @MinLength(2)
80
+ name: string;
81
+ }
82
+ ```
83
+
84
+ - Always use DTOs for request validation
85
+ - Use `ValidationPipe` globally
86
+ - Separate Create/Update/Response DTOs
87
+
88
+ ## Guards, Interceptors, Pipes
89
+
90
+ | Type | Purpose |
91
+ | --- | --- |
92
+ | **Guards** | Authentication, authorization |
93
+ | **Interceptors** | Logging, transformation, caching |
94
+ | **Pipes** | Validation, transformation |
95
+ | **Filters** | Exception handling |
96
+
97
+ Execution order: Guards → Interceptors → Pipes → Handler → Interceptors → Filters
98
+
99
+ ## Error Handling
100
+
101
+ ```typescript
102
+ @Catch()
103
+ export class AllExceptionsFilter implements ExceptionFilter {
104
+ catch(exception: unknown, host: ArgumentsHost) {
105
+ // Transform to standard error format
106
+ }
107
+ }
108
+ ```
109
+
110
+ ## Testing
111
+
112
+ - **Unit tests** - mock dependencies with `Test.createTestingModule()`
113
+ - **E2E tests** - use `supertest` with a test module
114
+ - **Mock everything** - services should be testable in isolation
115
+
116
+ ## Anti-Patterns
117
+
118
+ - [FAIL] Business logic in controllers - use services
119
+ - [FAIL] Direct database access in controllers - use repositories
120
+ - [FAIL] Circular dependencies - refactor module structure
121
+ - [FAIL] God modules - split large modules by domain
122
+ - [FAIL] Not using DTOs - always validate input
123
+
124
+
125
+ ## Code Examples
126
+
127
+ See `EXAMPLES.md` for detailed code examples.
128
+
129
+ ## Validation Checklist
130
+
131
+ What to verify during the review phase before completing the task.
132
+
133
+ ## Common Mistakes
134
+
135
+ Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
136
+
137
+ ## Integration Notes
138
+
139
+ How this skill interacts with other skills.
@@ -0,0 +1,19 @@
1
+ # nestjs Troubleshooting & Common Mistakes
2
+
3
+ ## 1. Circular Dependency Between Modules
4
+
5
+ - **Symptom**: "Nest cannot create the module instance. Often, this is caused by circular dependencies".
6
+ - **Root Cause**: Module A imports Module B, and Module B imports Module A.
7
+ - **Fix**: Use `forwardRef(() => ModuleB)` in imports and `@Inject(forwardRef(() => ServiceB))` in constructors, or refactor shared logic into a separate CommonModule.
8
+
9
+ ## 2. Memory Leaks from REQUEST Scope
10
+
11
+ - **Symptom**: High memory usage and slow performance under load.
12
+ - **Root Cause**: Providers declared with Scope.REQUEST recreate instances on every HTTP request.
13
+ - **Fix**: Keep services as default Singletons whenever possible. Pass request-scoped parameters directly through method arguments.
14
+
15
+ ## 3. Uncaught Domain Exceptions
16
+
17
+ - **Symptom**: Custom domain exceptions bypass formatting and return generic 500 errors.
18
+ - **Root Cause**: Missing custom Global Exception Filter.
19
+ - **Fix**: Implement an AllExceptionsFilter implementing ExceptionFilter and bind it globally in main.ts.
@@ -0,0 +1,12 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "type": "object",
4
+ "properties": {
5
+ "rules_followed": {
6
+ "type": "boolean"
7
+ }
8
+ },
9
+ "required": [
10
+ "rules_followed"
11
+ ]
12
+ }
@@ -0,0 +1,14 @@
1
+ schemaVersion: 2
2
+ id: nestjs
3
+ name: NestJS
4
+ category: backend
5
+ type: instruction-only
6
+ requires: [typescript, node]
7
+ optional: [postgres, redis, docker, graphql]
8
+ conflicts: [fastapi, express]
9
+ weight: 8
10
+ resources:
11
+ - EXAMPLES.md
12
+ - SKILL.md
13
+ - TROUBLESHOOTING.md
14
+ - VALIDATION.json
@@ -0,0 +1,40 @@
1
+ # nextjs Examples - Anti-patterns vs ContextOS Standard
2
+
3
+ ## Example 1: Server Components vs Client Components
4
+
5
+ ### Anti-pattern: Marking the Entire Page as Client Component
6
+
7
+ ```tsx
8
+ // BAD: app/dashboard/page.tsx with 'use client' at top
9
+ // Bloats client bundle, loses SEO benefits, eliminates direct DB access
10
+ 'use client';
11
+
12
+ export default function DashboardPage() {
13
+ const [data, setData] = useState(null);
14
+ useEffect(() => { fetch('/api/dashboard').then(...) }, []);
15
+ return <div>...</div>;
16
+ }
17
+ ```
18
+
19
+ ### Best practice: ContextOS Standard (RSC by Default, Client Leaf Nodes)
20
+
21
+ ```tsx
22
+ // GOOD: Server Component fetches data directly with zero bundle cost
23
+ // app/dashboard/page.tsx (Server Component)
24
+ import { Suspense } from 'react';
25
+ import { db } from '@/lib/db';
26
+ import { InteractiveChart } from './InteractiveChart'; // 'use client' leaf component
27
+
28
+ export default async function DashboardPage() {
29
+ const stats = await db.analytics.getStats();
30
+ return (
31
+ <main>
32
+ <h1>Dashboard</h1>
33
+ <p>Total Revenue: {stats.revenue}</p>
34
+ <Suspense fallback={<ChartSkeleton />}>
35
+ <InteractiveChart initialData={stats.chartData} />
36
+ </Suspense>
37
+ </main>
38
+ );
39
+ }
40
+ ```
@@ -0,0 +1,163 @@
1
+ ---
2
+ name: Next.js
3
+ description: >
4
+ ContextOS skill for Next.js App Router, Server Components, Server Actions, performance optimization, and Vercel best practices.
5
+ ---
6
+
7
+ # Next.js App Router Best Practices
8
+
9
+ ## Overview
10
+
11
+ Enforces high-performance architectural patterns for Next.js App Router based on Vercel Engineering guidelines: React Server Components (RSC), zero-waterfall async pipelines, request deduplication via `React.cache()`, bundle optimization, and secure Server Actions.
12
+
13
+ ## When to Use
14
+
15
+ Activate whenever building, refactoring, or reviewing Next.js pages, layouts, Route Handlers (`app/api`), Server Actions, or components in the `app/` directory.
16
+
17
+ ## Negative Constraints (What NOT to Do)
18
+
19
+ 1. **NEVER use barrel imports for UI libraries**: Avoid `import { Button, Dialog } from '@/components'`. Import directly from the exact file (`import { Button } from '@/components/ui/button'`) to prevent bundler tree-shaking failures and trace bloat.
20
+ 2. **NEVER trust client-provided data or session state in Server Actions**: Always authenticate session and authorize tenant ownership inside the Server Action handler itself before mutating data.
21
+ 3. **NEVER introduce sequential `await` waterfalls for independent data**: Always use `Promise.all()` or parallel streaming `<Suspense>` boundaries.
22
+ 4. **NEVER pass large unneeded serialized data from Server to Client Components**: Only pass the specific primitive fields required by the client component (`server-dedup-props`).
23
+ 5. **NEVER use `useEffect` for data fetching**: Fetch directly in Server Components or use TanStack Query / SWR for client-side queries.
24
+ 6. **NEVER import server-only modules in client components**: Use the `server-only` package in data access layers to catch accidental client imports at build time.
25
+
26
+ ## Rules & Patterns
27
+
28
+ ### 1. Eliminating Async Waterfalls (Critical)
29
+
30
+ - **Parallel Fetching**: Fetch independent data concurrently at the top of the route or component.
31
+ - **Granular Streaming**: Wrap slow, non-critical subtrees in `<Suspense fallback={<Skeleton />}>` so critical above-the-fold content streams immediately.
32
+ - **Defer Awaits**: Check cheap synchronous conditions before awaiting remote resources.
33
+
34
+ ### 2. Request Deduplication & Caching (`server-cache-react`)
35
+
36
+ - Use `React.cache()` to deduplicate identical database or service calls across multiple components rendered in the same server request lifecycle.
37
+
38
+ ```tsx
39
+ import { cache } from 'react';
40
+ import { db } from '@/lib/db';
41
+
42
+ export const getCurrentUser = cache(async (userId: string) => {
43
+ return await db.user.findUnique({
44
+ where: { id: userId },
45
+ select: { id: true, name: true, role: true, email: true }
46
+ });
47
+ });
48
+ ```
49
+
50
+ ### 3. Secure Server Actions (`server-auth-actions`)
51
+
52
+ - Treat every Server Action as a public HTTP endpoint. Always validate session, authorization, and input schema with Zod.
53
+
54
+ ```tsx
55
+ 'use server';
56
+
57
+ import { z } from 'zod';
58
+ import { auth } from '@/lib/auth';
59
+ import { db } from '@/lib/db';
60
+ import { revalidatePath } from 'next/cache';
61
+
62
+ const UpdateProfileSchema = z.object({
63
+ name: z.string().min(2).max(50),
64
+ });
65
+
66
+ export async function updateProfile(formData: FormData) {
67
+ const session = await auth();
68
+ if (!session?.userId) throw new Error('Unauthorized');
69
+
70
+ const result = UpdateProfileSchema.safeParse({ name: formData.get('name') });
71
+ if (!result.success) return { error: 'Invalid input', issues: result.error.flatten() };
72
+
73
+ await db.user.update({
74
+ where: { id: session.userId },
75
+ data: { name: result.data.name },
76
+ });
77
+
78
+ revalidatePath('/settings');
79
+ return { success: true };
80
+ }
81
+ ```
82
+
83
+ ### 4. Bundle Optimization & Dynamic Imports (`bundle-dynamic-imports`)
84
+
85
+ - Heavy interactive client components (charts, rich-text editors, video players) must be dynamically loaded with `next/dynamic`.
86
+
87
+ ```tsx
88
+ import dynamic from 'next/dynamic';
89
+
90
+ const AnalyticsChart = dynamic(
91
+ () => import('@/components/analytics/chart').then(mod => mod.AnalyticsChart),
92
+ {
93
+ loading: () => <div className="h-64 animate-pulse bg-muted rounded-lg" />,
94
+ ssr: false,
95
+ }
96
+ );
97
+ ```
98
+
99
+ ### 5. Next.js 15+ Async Request APIs (`async-params`)
100
+
101
+ In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous and must be awaited:
102
+
103
+ ```tsx
104
+ // [GOOD] Next.js 15+ Page Component
105
+ interface PageProps {
106
+ params: Promise<{ id: string }>;
107
+ searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
108
+ }
109
+
110
+ export default async function UserPage({ params, searchParams }: PageProps) {
111
+ const { id } = await params;
112
+ const { tab } = await searchParams;
113
+ const user = await getUser(id);
114
+
115
+ return <UserProfile user={user} activeTab={tab as string} />;
116
+ }
117
+ ```
118
+
119
+ ### 6. Non-Blocking Background Tasks with `after()`
120
+
121
+ To execute logging, analytics, or cache priming without delaying the user's HTTP response:
122
+
123
+ ```typescript
124
+ import { after } from 'next/server';
125
+
126
+ export async function POST(request: Request) {
127
+ const data = await request.json();
128
+ const result = await processOrder(data);
129
+
130
+ // Executes asynchronously AFTER the response stream has completed
131
+ after(async () => {
132
+ await sendSlackNotification(result);
133
+ await indexOrderInSearch(result.id);
134
+ });
135
+
136
+ return Response.json({ success: true, orderId: result.id });
137
+ }
138
+ ```
139
+
140
+ ---
141
+
142
+ ## Code Examples
143
+
144
+ See `EXAMPLES.md` for detailed code examples and component templates.
145
+
146
+ ## Validation Checklist
147
+
148
+ - [ ] All database queries in RSC layers use `React.cache()` if called across multiple components.
149
+ - [ ] No barrel imports (`from '@/components'`); all imports point to exact component modules.
150
+ - [ ] Server Actions have explicit auth checks and Zod input validation.
151
+ - [ ] Heavy client widgets (charts, editors) use `next/dynamic`.
152
+ - [ ] Images use `next/image` with explicit `sizes` and `priority` on LCP elements.
153
+
154
+ ## Common Mistakes
155
+
156
+ - Using `'use client'` at page level instead of leaf components.
157
+ - Relying on client-side authentication checks for Server Actions without server-side validation.
158
+ - Chaining sequential awaits for independent data models.
159
+
160
+ ## Integration Notes
161
+
162
+ - Pairs with `react` and `ui-ux-pro` for component design and state management.
163
+ - Pairs with `security` for session authorization and input sanitization.
@@ -0,0 +1,19 @@
1
+ # nextjs Troubleshooting & Common Mistakes
2
+
3
+ ## 1. Hydration Mismatch Errors
4
+
5
+ - **Symptom**: "Text content does not match server-rendered HTML".
6
+ - **Root Cause**: Rendering dates, window dimensions, or local storage data that differs between server render and client hydration.
7
+ - **Fix**: Use suppressHydrationWarning on localized timestamps or load client-only state inside a useEffect after mount.
8
+
9
+ ## 2. Accidental Server Code Bundled to Client
10
+
11
+ - **Symptom**: "Module not found: Can't resolve 'fs' or 'pg' in client bundle".
12
+ - **Root Cause**: Client component importing a utility that transitively imports server-only database code.
13
+ - **Fix**: Separate server utilities into *.server.ts and install import 'server-only'; at the top of server files.
14
+
15
+ ## 3. Waterfall Fetches in Server Components
16
+
17
+ - **Symptom**: Page takes 3 seconds to load due to sequential await statements.
18
+ - **Root Cause**: Awaiting independent data sources one after another.
19
+ - **Fix**: Use Promise.all([fetchUsers(), fetchProducts()]) or separate into nested <Suspense> boundaries.
@@ -0,0 +1,12 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "type": "object",
4
+ "properties": {
5
+ "rules_followed": {
6
+ "type": "boolean"
7
+ }
8
+ },
9
+ "required": [
10
+ "rules_followed"
11
+ ]
12
+ }
@@ -0,0 +1,14 @@
1
+ schemaVersion: 2
2
+ id: nextjs
3
+ name: Next.js
4
+ category: frontend
5
+ type: instruction-only
6
+ requires: [react, typescript]
7
+ optional: [tailwind, prisma, next-auth, react-query]
8
+ conflicts: [vue, angular, remix]
9
+ weight: 9
10
+ resources:
11
+ - EXAMPLES.md
12
+ - SKILL.md
13
+ - TROUBLESHOOTING.md
14
+ - VALIDATION.json