@malamute/ai-rules 1.4.0 → 1.5.1

package/README.md

@@ -41,14 +41,15 @@ npx @malamute/ai-rules <command>
 
 ## Supported Technologies
 
-| Technology  | Stack                                     | Version |
-| ----------- | ----------------------------------------- | ------- |
-| **Angular** | Nx + NgRx + Signals + Vitest              | 21+     |
-| **Next.js** | App Router + React 19 + Server Components | 15+     |
-| **NestJS**  | Prisma/TypeORM + Passport + Vitest        | 11+     |
-| **.NET**    | Clean Architecture + MediatR + EF Core    | 9+      |
-| **FastAPI** | Pydantic v2 + SQLAlchemy 2.0 + pytest     | 0.115+  |
-| **Flask**   | Marshmallow + SQLAlchemy 2.0 + pytest     | 3.0+    |
+| Technology   | Stack                                     | Version |
+| ------------ | ----------------------------------------- | ------- |
+| **Angular**  | Nx + NgRx + Signals + Vitest              | 21+     |
+| **Next.js**  | App Router + React 19 + Server Components | 15+     |
+| **NestJS**   | Prisma/TypeORM + Passport + Vitest        | 11+     |
+| **AdonisJS** | Lucid ORM + VineJS + Japa                 | 6+      |
+| **.NET**     | Clean Architecture + MediatR + EF Core    | 9+      |
+| **FastAPI**  | Pydantic v2 + SQLAlchemy 2.0 + pytest     | 0.115+  |
+| **Flask**    | Marshmallow + SQLAlchemy 2.0 + pytest     | 3.0+    |
 
 ## Commands
 
@@ -121,17 +122,19 @@ Interactive workflows invoked with `/skill-name`:
 | `/review`         | Code review with security/perf checklist  |
 | `/debug`          | Structured debugging workflow             |
 | `/spec`           | Write technical spec before implementing  |
+| `/sudden-death`   | Kill indecision with rapid-fire questions |
 | `/fix-issue`      | Analyze GitHub issue and implement fix    |
 | `/generate-tests` | Generate comprehensive tests              |
 
 <details>
-<summary><strong>See all 13 skills</strong></summary>
+<summary><strong>See all 14 skills</strong></summary>
 
 | Skill             | Usage                         | Description                           |
 | ----------------- | ----------------------------- | ------------------------------------- |
 | `/learning`       | `/learning nextjs`            | Explains concepts before implementing |
 | `/review`         | `/review src/users/`          | Code review with checklist            |
 | `/spec`           | `/spec add auth`              | Technical specification               |
+| `/sudden-death`   | `/sudden-death backend`       | Kill indecision, get a verdict        |
 | `/debug`          | `/debug TypeError...`         | Systematic debugging                  |
 | `/fix-issue`      | `/fix-issue 123`              | Fix GitHub issue                      |
 | `/review-pr`      | `/review-pr 456`              | Review pull request                   |
@@ -253,6 +256,19 @@ ai-rules update
 
 </details>
 
+<details>
+<summary><strong>AdonisJS</strong></summary>
+
+| Aspect       | Convention                          |
+| ------------ | ----------------------------------- |
+| Architecture | MVC with Services layer             |
+| Validation   | VineJS                              |
+| ORM          | Lucid (Active Record)               |
+| Auth         | Access Tokens / Session-based       |
+| Tests        | Japa                                |
+
+</details>
+
 <details>
 <summary><strong>.NET</strong></summary>
 

package/configs/_shared/rules/conventions/interaction.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - "**/*"
+---
+
+# Interaction Rules
+
+## Rules Are Absolute
+
+1. **Rules can NEVER be violated. Tasks can fail.**
+2. If a task requires violating a rule, the task fails - not the rule.
+3. If a task is blocked, explain the problem and ask how to proceed.
+
+## Protected Changes
+
+Never modify without explaining WHY and asking permission:
+- Package manager config (yarn, npm, pnpm)
+- Infrastructure (docker, CI/CD, deployment)
+- Project structure
+- Build config
+
+## Questions vs Actions
+
+- **Question** ("what is...", "why...", "how does...") → Answer only, no code
+- **Explicit request** ("create", "implement", "fix", "add") → Action with code
+
+When the user asks a question, answer it. Do not start coding or running commands.
+
+## Confirmation Before Action
+
+For non-trivial changes, confirm approach before implementing:
+1. Explain what will be done
+2. Wait for user approval
+3. Then execute
+
+## Language
+
+Match the user's language. If they write in French, respond in French.

package/configs/_shared/rules/domain/backend/api-design.md

@@ -151,21 +151,77 @@ GET /api/v1/users?sort=lastName:asc,firstName:asc
 GET /api/v1/users?fields=id,name,email
 ```
 
-## Versioning
+## API Versioning
 
-### URL Path (recommended)
+### When to Version (Breaking Changes)
+
+- Removing or renaming a field
+- Changing field type (string → number)
+- Removing an endpoint
+- Changing authentication method
+- Modifying error response structure
+
+### NOT Breaking (no version bump)
+
+- Adding new optional fields
+- Adding new endpoints
+- Adding new query parameters
+- Performance improvements
+
+### Strategy: URL Path (recommended)
 
 ```
 /api/v1/users
 /api/v2/users
 ```
 
+- Simple, explicit, cacheable
+- Easy to route at load balancer level
+- Version visible in logs
+
 ### Header-based (alternative)
 
 ```
 Accept: application/vnd.api+json; version=1
 ```
 
+### Deprecation Policy
+
+1. Announce deprecation (minimum 6 months before sunset)
+2. Add `Deprecation` header to responses
+3. Document migration path
+4. Monitor usage, notify active consumers
+5. Sunset old version
+
+```
+Deprecation: true
+Sunset: Sat, 01 Jun 2025 00:00:00 GMT
+Link: <https://api.example.com/docs/migration-v2>; rel="deprecation"
+```
+
+### Version Lifecycle
+
+| Status | Description |
+|--------|-------------|
+| **Current** | Latest stable, recommended |
+| **Supported** | Still maintained, receives security fixes |
+| **Deprecated** | Works but scheduled for removal |
+| **Sunset** | No longer available |
+
+### Code Organization
+
+```
+project/
+├── src/
+│   ├── v1/
+│   │   ├── controllers/
+│   │   └── dto/
+│   ├── v2/
+│   │   ├── controllers/
+│   │   └── dto/
+│   └── shared/          # Version-agnostic (services, repositories)
+```
+
 ## Rate Limiting
 
 Include headers in response:

package/configs/_shared/skills/analysis/sudden-death/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: sudden-death
+description: Kill indecision with rapid-fire questionnaires
+argument-hint: [decision-topic]
+---
+
+# Sudden Death Mode
+
+You are now in **sudden death mode**. No more "it depends" - guide the user through a tournament-style elimination and deliver a decisive verdict.
+
+**IMPORTANT: Always respond in the user's language.** If they write in French, respond in French. Polish? Polish. The examples below are in French for flavor, but adapt to the user.
+
+## Input
+
+Decision topic: `$ARGUMENTS`
+
+If no argument provided, ask: "What's on the chopping block? (e.g., backend stack, database, UI library, hosting)"
+
+## The Game
+
+### Phase 1: Candidates
+
+List all reasonable options for the domain. Example for backend:
+
+```
+Candidats: NestJS, Hono, Fastify, Elysia, AdonisJS, .NET, FastAPI, Go
+
+En garde. Première question...
+```
+
+### Phase 2: Elimination Tournament
+
+Ask **5-8 killer questions**. Each question should potentially eliminate candidates.
+
+Format:
+```
+### Q1: [Short punchy question]
+[Context if needed]
+
+→ User answers
+→ **Eliminated: [X, Y]** or **Advantage: [Z]** or **Point: [Z]**
+```
+
+Example questions (backend stack):
+- "Full TypeScript (front + back) or ok to switch languages?"
+- "Structured framework (modules, DI, conventions) or minimal?"
+- "Decorators (@Controller, @Get) or simple functions?"
+- "Batteries included or pick your own libs?"
+- "Big community or cutting-edge?"
+
+**Elimination rules:**
+- Strong preference → Eliminate mismatches immediately
+- Slight preference → Note advantage, keep in race
+- "Tie" / "Both good" → No elimination, move on
+
+### Phase 3: Final Showdown
+
+When down to 2-3 candidates:
+
+```
+### Finale: [A] vs [B]
+
+[A]: [2-3 key traits]
+[B]: [2-3 key traits]
+```
+
+If clear winner → Declare it
+If tie → Go to tiebreaker
+
+### Phase 4: Tiebreaker (when needed)
+
+Frame it as a **character choice**, not just technical:
+
+```
+Score: [A] 2 - [B] 2
+
+Tu as choisi [previous bold choice] pour sortir de ta zone.
+[A] = full send, nouvelle expérience
+[B] = un pied dans le connu
+
+On est des fous ou pas ?
+```
+
+### Phase 5: Verdict
+
+```
+### Winner: **[Option]**
+
+[One-liner why it fits THEIR specific answers]
+```
+
+## Between Decisions
+
+After each major decision, recap and offer options:
+
+```
+Stack actuelle:
+- Frontend: Next.js 15
+- Backend: AdonisJS
+- ORM: Lucid
+
+On continue ? Il reste:
+- UI lib (shadcn, autre ?)
+- State management
+- Hosting
+
+**Sudden death** ou **tu tranches direct** ?
+```
+
+- **Sudden death** = Full questionnaire
+- **Tu tranches direct** = User is confident, give quick recommendation
+
+## Tone
+
+- **Playful combat** - "En garde", "Eliminated", "Survivor"
+- **Call out bold choices** - "On est des fous !", "Allez on y va !"
+- **No corporate speak** - Skip the "it depends on your requirements"
+- **Quick and punchy** - Short questions, fast eliminations
+- **Celebrate decisions** - Each choice is a win, not a compromise
+
+## Quick Verdict Mode
+
+If user says "tu tranches" or wants fast advice:
+
+```
+Pour [context], je dirais **[Option]**.
+
+[One sentence why]
+
+Sold ? Ou on fait un sudden death pour être sûr ?
+```
+
+## Adapt to Domain
+
+Common sudden death topics:
+
+| Domain | Typical Candidates |
+|--------|-------------------|
+| Backend | NestJS, Fastify, Hono, AdonisJS, .NET, FastAPI, Go |
+| Frontend | Next.js, Nuxt, SvelteKit, Remix, Angular |
+| Database | PostgreSQL, MySQL, MongoDB, SQLite, Supabase, PlanetScale |
+| ORM | Prisma, Drizzle, TypeORM, Lucid, SQLAlchemy |
+| UI | shadcn/ui, Radix, Chakra, MUI, Mantine |
+| Hosting | Vercel, Railway, Render, Fly.io, AWS, Coolify |
+| State | Zustand, Jotai, Redux Toolkit, Signals, TanStack Query |
+| Auth | Auth.js, Lucia, Clerk, Supabase Auth, custom JWT |
+
+For unknown domains, identify the key trade-offs and build questions on the fly.

package/configs/adonisjs/rules/auth.md

@@ -0,0 +1,192 @@
+---
+paths:
+  - "app/controllers/auth/**/*.ts"
+  - "app/middleware/**/*.ts"
+  - "config/auth.ts"
+---
+
+# AdonisJS Authentication
+
+## Access Tokens (API)
+
+### Configuration
+
+```typescript
+// config/auth.ts
+import { defineConfig } from '@adonisjs/auth'
+import { tokensGuard, tokensUserProvider } from '@adonisjs/auth/access_tokens'
+
+export default defineConfig({
+  default: 'api',
+  guards: {
+    api: tokensGuard({
+      provider: tokensUserProvider({
+        tokens: 'accessTokens',
+        model: () => import('#models/user'),
+      }),
+    }),
+  },
+})
+```
+
+### User Model Setup
+
+```typescript
+import { DbAccessTokensProvider } from '@adonisjs/auth/access_tokens'
+
+export default class User extends BaseModel {
+  // ... other columns
+
+  static accessTokens = DbAccessTokensProvider.forModel(User)
+}
+```
+
+### Auth Controller
+
+```typescript
+import type { HttpContext } from '@adonisjs/core/http'
+import User from '#models/user'
+import hash from '@adonisjs/core/services/hash'
+import { loginValidator, registerValidator } from '#validators/auth'
+
+export default class AuthController {
+  async register({ request, response }: HttpContext) {
+    const payload = await request.validateUsing(registerValidator)
+    const user = await User.create(payload)
+    const token = await User.accessTokens.create(user)
+
+    return response.created({
+      user,
+      token: token.value!.release(),
+    })
+  }
+
+  async login({ request, response }: HttpContext) {
+    const { email, password } = await request.validateUsing(loginValidator)
+
+    const user = await User.findBy('email', email)
+    if (!user) {
+      return response.unauthorized({ message: 'Invalid credentials' })
+    }
+
+    const isValid = await hash.verify(user.password, password)
+    if (!isValid) {
+      return response.unauthorized({ message: 'Invalid credentials' })
+    }
+
+    const token = await User.accessTokens.create(user)
+
+    return response.ok({
+      user,
+      token: token.value!.release(),
+    })
+  }
+
+  async logout({ auth, response }: HttpContext) {
+    const user = auth.user!
+    await User.accessTokens.delete(user, user.currentAccessToken.identifier)
+    return response.noContent()
+  }
+
+  async me({ auth, response }: HttpContext) {
+    return response.ok(auth.user)
+  }
+}
+```
+
+### Routes
+
+```typescript
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+import { middleware } from '#start/kernel'
+
+const AuthController = () => import('#controllers/auth_controller')
+
+router.group(() => {
+  router.post('register', [AuthController, 'register'])
+  router.post('login', [AuthController, 'login'])
+
+  router.group(() => {
+    router.delete('logout', [AuthController, 'logout'])
+    router.get('me', [AuthController, 'me'])
+  }).use(middleware.auth())
+}).prefix('auth')
+```
+
+## Middleware
+
+### Auth Middleware
+
+```typescript
+// Protect routes
+router.get('profile', [ProfileController, 'show']).use(middleware.auth())
+
+// In controller, access user
+async show({ auth }: HttpContext) {
+  const user = auth.user! // Typed as User
+}
+```
+
+### Custom Middleware
+
+```typescript
+// app/middleware/admin_middleware.ts
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+
+export default class AdminMiddleware {
+  async handle({ auth, response }: HttpContext, next: NextFn) {
+    if (auth.user?.role !== 'admin') {
+      return response.forbidden({ message: 'Admin access required' })
+    }
+    await next()
+  }
+}
+```
+
+### Register Middleware
+
+```typescript
+// start/kernel.ts
+import router from '@adonisjs/core/services/router'
+
+router.named({
+  auth: () => import('#middleware/auth_middleware'),
+  admin: () => import('#middleware/admin_middleware'),
+})
+```
+
+## Password Hashing
+
+```typescript
+import hash from '@adonisjs/core/services/hash'
+
+// Hash password
+const hashed = await hash.make('password')
+
+// Verify password
+const isValid = await hash.verify(hashed, 'password')
+```
+
+## Auth Validators
+
+```typescript
+// app/validators/auth.ts
+import vine from '@vinejs/vine'
+
+export const registerValidator = vine.compile(
+  vine.object({
+    email: vine.string().email().normalizeEmail(),
+    password: vine.string().minLength(8).confirmed(),
+    name: vine.string().minLength(2),
+  })
+)
+
+export const loginValidator = vine.compile(
+  vine.object({
+    email: vine.string().email(),
+    password: vine.string(),
+  })
+)
+```

package/configs/adonisjs/rules/controllers.md

@@ -0,0 +1,111 @@
+---
+paths:
+  - "app/controllers/**/*.ts"
+---
+
+# AdonisJS Controllers
+
+## Structure
+
+Controllers handle HTTP concerns only. Delegate business logic to services.
+
+```typescript
+import type { HttpContext } from '@adonisjs/core/http'
+import { inject } from '@adonisjs/core'
+import UserService from '#services/user_service'
+import { createUserValidator, updateUserValidator } from '#validators/user'
+
+@inject()
+export default class UsersController {
+  constructor(private userService: UserService) {}
+
+  async index({ response }: HttpContext) {
+    const users = await this.userService.getAll()
+    return response.ok(users)
+  }
+
+  async store({ request, response }: HttpContext) {
+    const payload = await request.validateUsing(createUserValidator)
+    const user = await this.userService.create(payload)
+    return response.created(user)
+  }
+
+  async show({ params, response }: HttpContext) {
+    const user = await this.userService.findOrFail(params.id)
+    return response.ok(user)
+  }
+
+  async update({ params, request, response }: HttpContext) {
+    const payload = await request.validateUsing(updateUserValidator)
+    const user = await this.userService.update(params.id, payload)
+    return response.ok(user)
+  }
+
+  async destroy({ params, response }: HttpContext) {
+    await this.userService.delete(params.id)
+    return response.noContent()
+  }
+}
+```
+
+## Best Practices
+
+### Use Dependency Injection
+
+```typescript
+// Good
+@inject()
+export default class OrdersController {
+  constructor(
+    private orderService: OrderService,
+    private notificationService: NotificationService
+  ) {}
+}
+
+// Avoid: instantiating services manually
+export default class OrdersController {
+  private orderService = new OrderService() // Hard to test
+}
+```
+
+### Validate Input
+
+Always validate using VineJS validators:
+
+```typescript
+async store({ request }: HttpContext) {
+  // Validates and returns typed payload
+  const payload = await request.validateUsing(createOrderValidator)
+  // payload is now typed and validated
+}
+```
+
+### Use Response Helpers
+
+```typescript
+response.ok(data)           // 200
+response.created(data)      // 201
+response.noContent()        // 204
+response.badRequest(error)  // 400
+response.unauthorized()     // 401
+response.forbidden()        // 403
+response.notFound()         // 404
+```
+
+### Resource Routes
+
+```typescript
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+
+const UsersController = () => import('#controllers/users_controller')
+
+router.resource('users', UsersController).apiOnly()
+
+// Generates:
+// GET    /users          → index
+// POST   /users          → store
+// GET    /users/:id      → show
+// PUT    /users/:id      → update
+// DELETE /users/:id      → destroy
+```