opencode-andev-rules 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# @thaiannguyen-05/opencode-rules
+
+Global coding rules for TypeScript & NestJS. Plugin for opencode.
+
+## Cài Plugin
+
+```bash
+opencode plugin @thaiannguyen-05/opencode-rules
+```
+
+hoặc:
+
+```bash
+cd ~/.config/opencode
+npm install @thaiannguyen-05/opencode-rules
+```
+
+Thêm vào `opencode.json`:
+
+```json
+{
+  "plugins": ["@thaiannguyen-05/opencode-rules"]
+}
+```
+
+## Cài Skill
+
+```bash
+npx @thaiannguyen-05/skills-cli add improve-codenase-systems
+```
+
+hoặc:
+
+```bash
+cp -r skills/improve-codenase-systems ~/.agents/skills/
+```
+
+## Sử dụng
+
+### Rules
+
+Nói "follow the rule of andev" trong prompt.
+
+### Skill
+
+Nói "scan codebase" hoặc "improve codebase" trong prompt.
+
+## Rules
+
+Xem `RULES.md` — covers TypeScript, NestJS, validation, error handling, database, security, API design, testing, and code style.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `improve-codenase-systems` | Scan codebase for architecture issues |

package/RULES.md

@@ -0,0 +1,253 @@
+# Rules for TypeScript & NestJS
+
+## TypeScript
+
+- Use `strict: true` in `tsconfig.json`
+- No `any` type — use `unknown` and narrow with type guards
+- Use `interface` for object shapes, `type` for unions/intersections
+- Prefer `readonly` for immutable data
+- Avoid type assertions (`as`) — use type guards or `satisfies` instead
+- Use `!` non-null assertion only when value is guaranteed (add comment why)
+- Export types from barrel files (`index.ts`)
+
+## NestJS
+
+- Use CLI to generate: `nest g module`, `nest g controller`, `nest g service`
+- One module per feature (e.g., `users/`, `auth/`, `orders/`)
+- Controllers handle HTTP — no business logic in controllers
+- Services handle business logic — no HTTP concerns in services
+- Use `@nestjs/swagger` decorators on DTOs and controllers
+- Inject dependencies via constructor — never instantiate manually
+- Use `@InjectRepository()` for TypeORM/Prisma repositories
+- Use guards for auth (`@UseGuards`), interceptors for logging/transformation
+- Use `ConfigModule` for environment variables — no `process.env` in code
+- Use `@nestjs/schedule` for cron jobs — no `setInterval`
+
+## Types
+
+- Every module must have a `types.ts` file for module-specific types
+- Export all types from `types.ts` — import from there in other files
+- Use `type.ts` for: enums, interfaces, type aliases, return types
+- Do NOT put types in `dto/` — DTOs are for validation, types are for contracts
+- Import pattern: `import { UserRole } from './types'`
+- Put constants in `types.ts`: event names, URLs, status codes, config values
+- Use `enum` for constants — no hardcoded strings in business logic
+
+```typescript
+// types.ts
+export enum EventName {
+  CREATED = 'user.created',
+  UPDATED = 'user.updated',
+  DELETED = 'user.deleted',
+}
+
+export enum ApiUrl {
+  BASE = '/api/v1',
+  USERS = '/api/v1/users',
+}
+
+export interface User { id: string; name: string; }
+```
+
+## Validation
+
+- Handle ALL validation before controller and service
+- Use global `ValidationPipe` in `main.ts` — reject invalid requests early
+- Use `class-validator` decorators on DTOs
+- Use `class-transformer` with `ValidationPipe` globally
+- Validate nested objects with `@ValidateNested()`
+- Use `@IsString()`, `@IsNumber()`, `@IsEmail()`, `@IsOptional()` etc.
+- Controllers and services receive only valid data — no validation logic inside
+- Use `WhitelistStrategy` + `ForbidNonWhitelisted` to reject unknown fields
+- Use `TransformPipe` to auto-transform payloads to DTO instances
+
+```typescript
+// main.ts
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true,
+    forbidNonWhitelisted: true,
+    transform: true,
+  }),
+);
+```
+
+## Error Handling
+
+- Handle errors with exceptions — use custom `AppException` classes
+- Create `src/error/` directory with exception classes and global filter
+- `errorCode` = uppercase snake_case (e.g., `RESOURCE_NOT_FOUND`)
+- Always return consistent JSON: `{ statusCode, timestamp, path, message, errorCode?, details? }`
+- Log unhandled (non-HttpException) errors with logger
+- Create helper files for domain-specific error scenarios
+
+```typescript
+// app.exception.ts
+export class AppException extends HttpException {
+  constructor(
+    message: string,
+    statusCode: HttpStatus,
+    public readonly errorCode?: string,
+    public readonly details?: unknown,
+  ) {
+    super({ message, errorCode, details, timestamp: new Date().toISOString() }, statusCode);
+  }
+}
+
+export class ResourceNotFoundException extends AppException {
+  constructor(resourceType: string, identifier: string | number) {
+    super(`${resourceType} with identifier ${identifier} not found`, HttpStatus.NOT_FOUND, 'RESOURCE_NOT_FOUND');
+  }
+}
+```
+
+```typescript
+// main.ts
+app.useGlobalFilters(new GlobalExceptionFilter(logger));
+```
+
+## Database
+
+- Use Prisma or TypeORM — pick one, don't mix
+- Keep migrations in `prisma/migrations` or `src/migrations`
+- Use repositories or Prisma client for data access
+- Never write raw SQL unless performance-critical (add comment why)
+- Use `select` when only a subset of fields is required — don't over-fetch
+- Avoid N+1 queries — use `include` or joins, not loops
+- Run independent queries in parallel — don't `await` sequentially
+- Use `findFirst` only when `findUnique` is possible
+- Paginate `findMany` — never return unbounded results
+- Use cursor pagination for large datasets, offset for small
+- Always `orderBy` deterministic fields for pagination
+- Handle Prisma errors — never leak raw Prisma errors to API responses
+- Use transactions for multi-step operations — no partial writes
+- Keep transaction scope small — no external calls inside transactions
+- Race conditions on read-modify-write — use transactions or locks
+- Add unique constraints for data that must be unique
+- Soft-delete: always filter `deletedAt` in queries
+- Avoid `include` for large relation collections — paginate or select
+
+## Testing
+
+- Use Jest (built into NestJS)
+- Unit tests: `*.spec.ts` next to source files
+- E2E tests: `test/*.e2e-spec.ts`
+- Mock dependencies with `@nestjs/testing` `Test.createTestingModule()`
+- Test controllers and services separately
+- Use `supertest` for HTTP assertions in e2e
+
+## Async & Concurrency
+
+- Run independent async operations in parallel — don't `await` sequentially
+- Always handle promise rejections — no fire-and-forget without error handling
+- Add timeout for external service calls
+- Use idempotency keys for retryable operations
+- Retry with limits and exponential backoff
+- Never retry non-idempotent operations unsafely
+- Race conditions: use transactions or locks for read-modify-write
+
+## Security
+
+- Never hardcode secrets or credentials — use `ConfigModule`
+- Never expose sensitive data in API responses
+- Validate and sanitize all user input
+- Prevent IDOR — check resource ownership
+- Use parameterized queries — no raw SQL concatenation
+- Validate file uploads: size, type, content
+- Never trust client-provided file metadata
+- Secure CORS configuration — no wildcard in production
+- Rate limit sensitive endpoints (login, register, password reset)
+- Never log sensitive data (passwords, tokens, PII)
+- Use guards for auth — no manual auth checks in controllers
+
+## API Design
+
+- Consistent REST naming: plural nouns, HTTP verbs for actions
+- Consistent error response format: `{ statusCode, message, errorCode }`
+- Paginate all list endpoints — no unbounded responses
+- Filter and limit query parameters
+- Version API when making breaking changes
+- Use appropriate HTTP status codes (201 for create, 204 for delete)
+- Never expose internal implementation details in responses
+
+## Observability
+
+- Use structured logging (nestjs-pino)
+- Never log sensitive data
+- Propagate request/correlation IDs
+- Add health check endpoints for critical dependencies
+- Handle graceful shutdown — clean up connections
+- Clean up timers, listeners, subscriptions
+- Handle background job failures
+
+## File Structure
+
+```
+andev-skill-agent/
+├── .git/
+├── package.json        # @thaiannguyen-05/opencode-rules
+├── plugin.js           # trigger detection + GitHub fetch
+├── README.md           # usage docs
+└── RULES.md            # this file — rules for agents
+```
+
+### NestJS Project Structure
+
+```
+src/
+├── app.module.ts
+├── main.ts
+├── config/
+│   └── configuration.ts
+├── common/
+│   ├── guards/
+│   ├── interceptors/
+│   ├── pipes/
+│   └── decorators/
+├── error/
+│   ├── app.exception.ts
+│   ├── global.exception.ts
+│   └── [domain]-error.helper.ts
+├── modules/
+│   ├── users/
+│   │   ├── users.module.ts
+│   │   ├── users.controller.ts
+│   │   ├── users.service.ts
+│   │   ├── types.ts
+│   │   ├── dto/
+│   │   └── entities/
+│   ├── auth/
+│   │   ├── auth.module.ts
+│   │   ├── auth.controller.ts
+│   │   ├── auth.service.ts
+│   │   ├── types.ts
+│   │   ├── dto/
+│   │   └── entities/
+│   └── orders/
+│       ├── orders.module.ts
+│       ├── orders.controller.ts
+│       ├── orders.service.ts
+│       ├── types.ts
+│       ├── dto/
+│       └── entities/
+```
+
+## Code Style
+
+- Use Prettier for formatting
+- Use ESLint with `@typescript-eslint` rules
+- Max 300 lines per file — split if超过
+- One export per file — no barrel exports in middle of file
+- Sort imports: node builtins → external → internal → relative
+- Use `path aliases` (`@/`) for clean imports
+- Prefer `async/await` over `.then()` chains
+- Use `enum` for constants — no hardcoded strings
+
+```json
+// .eslintrc
+{
+  "rules": {
+    "max-lines": ["error", { "max": 300, "skipBlankLines": true, "skipComments": true }]
+  }
+}
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "opencode-andev-rules",
+  "version": "1.0.0",
+  "description": "On-demand rule injection plugin for opencode. Say 'follow the rule of andev' to load rules from GitHub.",
+  "type": "module",
+  "main": "plugin.js",
+  "exports": {
+    ".": "./plugin.js"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "rules",
+    "nestjs",
+    "typescript"
+  ],
+  "author": "thaiannguyen-05",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.15.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.17.11"
+  }
+}

package/plugin.js

@@ -0,0 +1,96 @@
+// @thaiannguyen-05/opencode-rules
+//
+// On-demand rule injection plugin for opencode.
+// When user says "follow the rule of andev" (or similar), fetches RULES.md
+// from GitHub and injects it into the system prompt.
+//
+// Hooks:
+//   - chat.message: detect trigger phrase in user input
+//   - experimental.chat.system.transform: inject rules into system prompt
+
+const RULES_URL = 'https://raw.githubusercontent.com/thaiannguyen-05/rules-for-global-agents/main/RULES.md';
+
+// Trigger patterns — case-insensitive
+const TRIGGER_PATTERNS = [
+  /follow\s+(the\s+)?rules?\s+of\s+andev/i,
+  /follow\s+andev\s+rules?/i,
+  /use\s+andev\s+rules?/i,
+  /apply\s+andev\s+rules?/i,
+  /andev\s+rules/i,
+];
+
+// In-memory cache: rules text per session
+let cachedRules = null;
+let fetchFailed = false;
+
+function detectTrigger(text) {
+  if (!text) return false;
+  return TRIGGER_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+async function fetchRules() {
+  // Return cache if available
+  if (cachedRules !== null) return cachedRules;
+
+  // Don't retry if fetch already failed
+  if (fetchFailed) return null;
+
+  try {
+    const response = await fetch(RULES_URL, {
+      headers: { Accept: 'text/plain' },
+    });
+
+    if (!response.ok) {
+      fetchFailed = true;
+      return null;
+    }
+
+    const text = await response.text();
+
+    if (!text || text.trim().length === 0) {
+      fetchFailed = true;
+      return null;
+    }
+
+    cachedRules = text;
+    return cachedRules;
+  } catch {
+    fetchFailed = true;
+    return null;
+  }
+}
+
+export const AndevRulesPlugin = async (_ctx) => {
+  let triggerDetected = false;
+
+  return {
+    // Detect trigger phrase in user messages
+    'chat.message': async (_input, output) => {
+      if (!output || !output.parts) return;
+
+      for (const part of output.parts) {
+        if (part && part.type === 'text' && part.text) {
+          if (detectTrigger(part.text)) {
+            triggerDetected = true;
+          }
+        }
+      }
+    },
+
+    // Inject rules into system prompt when trigger was detected
+    'experimental.chat.system.transform': async (_input, output) => {
+      if (!output || !Array.isArray(output.system)) return;
+      if (!triggerDetected) return;
+
+      const rules = await fetchRules();
+      if (rules) {
+        output.system.push(`## Rules from andev (follow these rules)\n\n${rules}`);
+      }
+
+      // Reset trigger for next message
+      triggerDetected = false;
+    },
+  };
+};
+
+export default AndevRulesPlugin;

package/skills/improve-codenase-systems/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review for {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files**: monospaced list, `font-mono text-sm`.
+- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
+- **Problem**: one sentence. What hurts.
+- **Solution**: one sentence. What changes.
+- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable): one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow: interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"*, because those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

package/skills/improve-codenase-systems/SKILL.md

@@ -0,0 +1,429 @@
+---
+name: improve-codenase-systems
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codenase Systems
+
+Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Scan Checklist
+
+### Architecture & Code Organization
+
+- duplicated or highly similar code that should be reused
+- business logic placed directly inside UI components when it should be extracted
+- API/data fetching logic duplicated across components
+- API calls implemented directly in components instead of an appropriate service/query layer
+- components with too many responsibilities
+- components that are unnecessarily large and should be split
+- hooks that contain unrelated responsibilities
+- utilities/helpers duplicated across the codebase
+- inappropriate abstraction or abstraction created without actual reuse
+- unnecessary abstraction or over-engineering
+- tight coupling between unrelated components or modules
+- circular dependencies
+- incorrect dependency direction
+- feature-specific logic placed in global/shared modules unnecessarily
+- shared/common modules becoming dumping grounds
+- inconsistent project structure for similar features
+
+### React / Next.js
+
+- unnecessary useEffect
+- useEffect used for derived state
+- state that can be derived instead of stored
+- duplicated state
+- unnecessary local state
+- state synchronization that can cause inconsistent data
+- stale closure issues
+- missing cleanup for effects, subscriptions, timers, or event listeners
+- side effects executed during render
+- unnecessary re-renders
+- expensive computation executed on every render
+- incorrect or unnecessary useMemo/useCallback
+- memoization used without measurable benefit
+- missing memoization for clearly expensive operations
+- unstable keys in list rendering
+- array index used as key when list order can change
+- prop drilling that should be solved with a more appropriate state/data architecture
+- unnecessary Context usage causing broad re-renders
+- incorrect dependency array
+- disabling eslint hook dependency rules without a valid reason
+
+### Next.js Specific
+
+- unnecessary "use client"
+- Server Components unnecessarily converted into Client Components
+- data fetching on the client when server-side fetching is more appropriate
+- duplicated server and client data fetching
+- incorrect caching strategy
+- missing or incorrect revalidation strategy
+- unnecessary dynamic rendering
+- unnecessary dynamic imports
+- heavy client-side dependencies that could remain server-side
+- server-only code imported into client code
+- environment variables exposed to the client unnecessarily
+- incorrect usage of Server Actions
+- missing loading or error boundaries where appropriate
+
+### Data Fetching & State Management
+
+- duplicated API requests
+- unnecessary repeated fetching
+- missing request cancellation where race conditions can occur
+- stale data issues
+- race conditions between requests
+- missing loading states
+- missing error states
+- missing empty states
+- inconsistent error handling
+- data transformed repeatedly in multiple places
+- server state incorrectly stored as local/global client state
+- global state used for local component state
+- local state used where shared state management is required
+- missing debounce or throttle for search, resize, scroll, or frequent user input
+- unnecessary polling
+- incorrect cache invalidation
+
+### Performance
+
+- unnecessary re-renders
+- expensive operations during render
+- large lists rendered without virtualization when necessary
+- unnecessary large bundle dependencies
+- importing entire libraries when smaller imports are available
+- duplicate dependencies with overlapping functionality
+- unnecessary images/assets loaded eagerly
+- missing lazy loading where beneficial
+- unnecessary network requests
+- sequential independent requests that can run in parallel
+- unnecessary client-side computation
+- avoidable bundle size increase
+- memory leaks caused by listeners, timers, subscriptions, or retained references
+
+### UI / UX
+
+- duplicated UI patterns that should be reusable components
+- hardcoded UI that should be generated from reusable components or configuration
+- hardcoded values that should come from constants/configuration
+- inconsistent loading behavior
+- inconsistent error handling
+- inconsistent empty states
+- missing disabled/loading state for async actions
+- duplicate submissions
+- missing feedback for long-running operations
+- UI state that can become inconsistent with server state
+- forms without proper validation
+- validation logic duplicated across components
+- validation rules inconsistent with backend constraints
+- missing responsive behavior where applicable
+
+### Accessibility
+
+- non-semantic HTML where semantic elements are appropriate
+- interactive elements implemented with non-interactive elements
+- missing accessible labels
+- missing aria attributes when required
+- keyboard inaccessible interactions
+- missing focus management
+- dialogs/modals without proper focus handling
+- images without meaningful alt text
+- form controls without associated labels
+
+### TypeScript
+
+- usage of any
+- unnecessary type assertions using "as"
+- unsafe type assertions
+- duplicated type definitions
+- manually defined types that should be inferred
+- ambiguous or overly generic types
+- missing explicit types where inference is insufficient
+- inconsistent nullable/optional handling
+- type definitions placed in inappropriate files
+- feature/domain types mixed with unrelated UI files
+- API response types duplicated instead of reused
+- incorrect use of interface vs type based on project conventions
+
+### Code Quality
+
+- ambiguous function names
+- ambiguous variable names
+- misleading names
+- dead code
+- unused imports
+- unused dependencies
+- commented-out code
+- magic numbers or strings
+- duplicated constants
+- hardcoded configuration
+- unnecessary complexity
+- deeply nested conditions that can be simplified
+- duplicated conditional logic
+- functions doing too many things
+- components doing too many things
+- unclear or inconsistent error messages
+
+### Backend / NestJS
+
+- business logic implemented inside controllers
+- database logic implemented inside controllers
+- infrastructure logic mixed with business/domain logic
+- duplicated business logic across services
+- duplicated database access logic
+- services with too many responsibilities
+- classes violating single responsibility
+- functions with too many responsibilities
+- overly large services that should be split
+- inappropriate abstraction
+- unnecessary abstraction or over-engineering
+- circular dependencies
+- incorrect dependency direction
+- module boundary violations
+- tight coupling between modules
+- direct access to another module's internal implementation
+- feature-specific logic placed in shared/common modules unnecessarily
+- shared/common modules becoming dumping grounds
+- duplicated utilities/helpers
+
+### NestJS Framework
+
+- controller containing business logic
+- controller directly accessing Prisma/database
+- missing DTO for request input where DTO validation is appropriate
+- missing validation decorators
+- validation implemented manually when DTO validation should handle it
+- incorrect DTO validation
+- DTO used for unrelated responsibilities
+- entity/database model exposed directly as API response
+- missing or inconsistent serialization/transformation
+- guards implemented incorrectly
+- authorization checks missing
+- resource ownership checks missing
+- authentication handled manually instead of using appropriate guards/middleware
+- business logic implemented inside guards/interceptors unnecessarily
+- incorrect usage of middleware, guards, interceptors, pipes, or filters
+- duplicated exception handling
+- missing global exception handling where appropriate
+- dependency injected but not actually needed
+- unnecessary request-scoped providers
+- incorrect provider/module scope
+
+### API Design
+
+- ambiguous endpoint naming
+- inconsistent REST conventions
+- inconsistent request/response structure
+- inconsistent error response format
+- sensitive data returned in API response
+- missing pagination for potentially large datasets
+- missing filtering limits
+- unbounded request parameters
+- missing validation for query/path/body parameters
+- API exposing internal implementation details
+- inconsistent status codes
+- idempotency issues
+- duplicate request processing
+- missing rate limiting for sensitive endpoints
+- breaking API changes without versioning strategy where applicable
+
+### Prisma & Database
+
+- Prisma/database query directly inside controller
+- duplicated Prisma query logic
+- Prisma access scattered across unrelated modules without clear data access boundaries
+- N+1 queries
+- database queries inside loops
+- sequential independent queries that can run in parallel
+- fetching unnecessary fields
+- missing select when only a subset of fields is required
+- unnecessary include
+- over-fetching relations
+- loading large relation collections into memory
+- findMany without pagination for potentially large datasets
+- offset pagination used for very large datasets where cursor pagination is more appropriate
+- incorrect cursor pagination
+- pagination without deterministic orderBy
+- missing filtering constraints
+- duplicate count/data queries that can be optimized
+- unnecessary database round trips
+- findFirst used when findUnique is possible
+- findUnique used with fields that are not actually unique
+- unsafe raw SQL
+- unnecessary raw SQL when Prisma can handle the query
+- Prisma errors leaked directly to API responses
+- missing handling for expected Prisma errors
+- inconsistent nullable/optional handling between DTO, application code, and Prisma schema
+- incorrect usage of checked/unchecked Prisma inputs
+
+### Transactions & Data Integrity
+
+- multi-step database operations without a required transaction
+- transaction scope unnecessarily large
+- external API/network calls executed inside database transactions
+- long-running operations inside transactions
+- incorrect interactive transaction usage
+- transaction used where a batch transaction would be sufficient
+- operations that can leave partial/inconsistent data
+- race conditions during read-modify-write operations
+- missing unique constraints for data that must be unique
+- missing database constraints for important invariants
+- application-only validation where database constraints are also required
+- incorrect cascade delete behavior
+- dangerous cascade delete
+- inconsistent soft-delete filtering
+- queries that accidentally include soft-deleted records
+- operations that bypass soft-delete rules
+
+### Prisma Schema
+
+- missing index for frequently queried fields
+- missing composite index for common multi-field queries
+- unnecessary indexes
+- duplicated or redundant indexes
+- incorrect unique constraints
+- missing unique constraints
+- incorrect nullable/required fields
+- incorrect relation definitions
+- missing or inappropriate onDelete/onUpdate behavior
+- string fields that should use enums
+- duplicated enum/value definitions
+- inconsistent naming
+- schema changes that may cause data loss
+- schema changes inconsistent with existing migrations
+- migration risks that require manual data migration
+
+### Async & Concurrency
+
+- unnecessary sequential await operations
+- independent async operations that can run in parallel
+- unhandled promise rejection
+- fire-and-forget async operations without error handling
+- race conditions
+- missing concurrency control
+- duplicate processing caused by concurrent requests
+- missing idempotency for retryable operations
+- retry logic without limits
+- retry logic without backoff where appropriate
+- retrying non-idempotent operations unsafely
+- missing timeout for external service calls
+- blocking/synchronous operations inside request handling
+
+### Error Handling
+
+- empty catch blocks
+- swallowed errors
+- catch blocks that lose the original error/context
+- generic Error used instead of appropriate application/domain exceptions
+- inconsistent exception handling
+- sensitive internal information exposed in errors
+- missing error handling for external dependencies
+- errors logged but not propagated when they should be
+- errors propagated without meaningful context
+- retryable and non-retryable errors handled identically
+
+### Security
+
+- missing authentication
+- missing authorization
+- IDOR/resource ownership vulnerabilities
+- trusting user input without validation
+- unsafe raw SQL
+- SQL injection risk
+- command injection risk
+- path traversal
+- SSRF
+- unsafe file upload handling
+- missing file size validation
+- missing MIME/type validation
+- trusting client-provided file metadata
+- hardcoded secrets or credentials
+- secrets exposed in logs
+- sensitive information logged
+- sensitive information returned in API responses
+- insecure CORS configuration
+- missing rate limiting for sensitive operations
+- insecure token handling
+- missing permission checks
+- unsafe deserialization
+
+### Observability & Reliability
+
+- missing structured logging
+- inconsistent log format
+- sensitive data in logs
+- missing error context
+- missing correlation/request ID propagation where appropriate
+- missing logging for critical failures
+- excessive logging in hot paths
+- missing health checks for critical dependencies
+- missing graceful shutdown handling
+- resource leaks
+- timers/listeners/subscriptions not cleaned up
+- connections not closed properly
+- background jobs without failure handling
+- critical operations without metrics or monitoring hooks where appropriate
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow**, with an interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files**: which files/modules are involved
+- **Problem**: why the current architecture is causing friction
+- **Solution**: plain English description of what would change
+- **Benefits**: explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.

package/skills/improve-codenase-systems/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "Find and grill architecture improvements"
+policy:
+  allow_implicit_invocation: false

package/skills/improve-codenase-systems/meta.json

@@ -0,0 +1,8 @@
+{
+  "name": "improve-codenase-systems",
+  "version": "1.0.0",
+  "description": "Scan codebase for architecture issues and deepening opportunities",
+  "author": "thaiannguyen-05",
+  "tags": ["architecture", "review", "nestjs", "react"],
+  "files": ["SKILL.md", "HTML-REPORT.md", "agents/openai.yaml"]
+}

package/skills/registry.json

@@ -0,0 +1,15 @@
+{
+  "name": "andev-skills",
+  "version": "1.0.0",
+  "description": "AI agent skills by thaiannguyen-05",
+  "skills": [
+    {
+      "name": "improve-codenase-systems",
+      "description": "Scan codebase for architecture issues and deepening opportunities",
+      "version": "1.0.0",
+      "tags": ["architecture", "review", "nestjs", "react", "codebase"],
+      "path": "skills/improve-codenase-systems",
+      "files": ["SKILL.md", "HTML-REPORT.md", "agents/openai.yaml"]
+    }
+  ]
+}