@malamute/ai-rules 1.0.0

package/README.md

@@ -0,0 +1,174 @@
+# AI Rules
+
+[![npm version](https://badge.fury.io/js/@malamute/ai-rules.svg)](https://www.npmjs.com/package/@malamute/ai-rules)
+
+CLI to install Claude Code configuration boilerplates for Angular, Next.js, NestJS, .NET, Python and more.
+
+## Installation
+
+```bash
+# Global install
+npm install -g @malamute/ai-rules
+
+# Or use directly with npx
+npx @malamute/ai-rules init angular
+```
+
+## Usage
+
+```bash
+# Single technology
+ai-rules init angular
+ai-rules init nestjs
+ai-rules init python
+
+# Fullstack (combines multiple configs)
+ai-rules init angular nestjs
+ai-rules init nextjs python
+ai-rules init nextjs dotnet
+
+# With extras
+ai-rules init angular --with-skills              # /learning, /review, /spec, /debug
+ai-rules init angular nestjs --with-commands     # fix-issue, review-pr, generate-tests
+ai-rules init nextjs --with-rules                # security, performance, accessibility
+ai-rules init angular nestjs --all               # Everything
+
+# Custom target directory
+ai-rules init dotnet --target ./my-project
+
+# List available technologies
+ai-rules list
+```
+
+## Available Technologies
+
+| Technology | Stack                                 |
+| ---------- | ------------------------------------- |
+| `angular`  | Angular 21 + Nx + NgRx + Signals      |
+| `nextjs`   | Next.js 15 + React 19 + App Router    |
+| `nestjs`   | NestJS 10 + Prisma/TypeORM + Passport |
+| `dotnet`   | .NET 8 + ASP.NET Core + EF Core       |
+| `python`   | FastAPI/Flask + SQLAlchemy 2.0        |
+
+## What Gets Installed
+
+```
+your-project/
+├── CLAUDE.md              # Main instructions for Claude
+└── .claude/
+    ├── settings.json      # Permissions
+    ├── rules/             # Technology-specific rules
+    ├── skills/            # Optional: /learning, /review, /spec, /debug
+    └── commands/          # Optional: fix-issue, review-pr, generate-tests
+```
+
+## Available Skills
+
+| Skill       | Usage                 | Description                                     |
+| ----------- | --------------------- | ----------------------------------------------- |
+| `/learning` | `/learning nextjs`    | Pedagogical mode - explains before implementing |
+| `/review`   | `/review src/users/`  | Code review with structured checklist           |
+| `/spec`     | `/spec add auth`      | Technical specification before implementing     |
+| `/debug`    | `/debug TypeError...` | Systematic debugging workflow                   |
+
+## Available Commands
+
+| Command          | Usage                                | Description                          |
+| ---------------- | ------------------------------------ | ------------------------------------ |
+| `fix-issue`      | `/project:fix-issue 123`             | Fetch GitHub issue and implement fix |
+| `review-pr`      | `/project:review-pr 456`             | Review PR diff with checklist        |
+| `generate-tests` | `/project:generate-tests src/users/` | Generate tests for a file            |
+
+## Shared Rules
+
+When using `--with-rules` or `--all`, these transversal rules are included:
+
+- **security.md** - OWASP Top 10 (injection, XSS, CSRF, auth, secrets)
+- **performance.md** - N+1 queries, caching, memoization, lazy loading
+- **accessibility.md** - WCAG 2.1 (semantic HTML, ARIA, keyboard nav)
+
+## Technology Details
+
+### Angular
+
+| Aspect         | Convention                                  |
+| -------------- | ------------------------------------------- |
+| Components     | Standalone by default, OnPush required      |
+| Templates      | Always in separate `.html` files            |
+| Inputs/Outputs | `input()`, `output()`, `model()` functions  |
+| State          | NgRx + Entity Adapter + Functional Effects  |
+| Tests          | Vitest + Marble testing (no `.subscribe()`) |
+
+### Next.js
+
+| Aspect            | Convention                                 |
+| ----------------- | ------------------------------------------ |
+| Components        | Server Components by default               |
+| Client Components | Add `'use client'` directive               |
+| Data Fetching     | Server Components + `fetch()`              |
+| Mutations         | Server Actions                             |
+| State             | Zustand (simple) / Redux Toolkit (complex) |
+
+### NestJS
+
+| Aspect       | Convention                             |
+| ------------ | -------------------------------------- |
+| Architecture | Modular Monolith                       |
+| Validation   | class-validator + class-transformer    |
+| Database     | Prisma (modern) / TypeORM (decorators) |
+| Auth         | Passport + JWT                         |
+| Tests        | Jest + Supertest                       |
+
+### .NET
+
+| Aspect       | Convention                                |
+| ------------ | ----------------------------------------- |
+| Architecture | Clean Architecture (Domain → App → Infra) |
+| API Style    | Minimal APIs or Controllers               |
+| CQRS         | MediatR (Commands/Queries)                |
+| ORM          | Entity Framework Core                     |
+| Tests        | xUnit + NSubstitute + FluentAssertions    |
+
+### Python
+
+| Aspect     | Convention                                  |
+| ---------- | ------------------------------------------- |
+| Frameworks | FastAPI (async) / Flask (traditional)       |
+| Validation | Pydantic v2 (FastAPI) / Marshmallow (Flask) |
+| ORM        | SQLAlchemy 2.0 (async support)              |
+| Tests      | pytest + httpx                              |
+| Migrations | Alembic                                     |
+
+## Package Structure
+
+```
+claude-code-configs/
+├── package.json
+├── bin/
+│   └── cli.js              # CLI entry point
+├── src/
+│   └── install.js          # Installation logic
+└── configs/
+    ├── angular/
+    ├── nextjs/
+    ├── nestjs/
+    ├── dotnet/
+    ├── python/
+    └── _shared/
+        ├── CLAUDE.md
+        └── .claude/
+            ├── skills/
+            ├── commands/
+            └── rules/
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a new technology folder in `configs/`
+3. Add `CLAUDE.md` and `.claude/rules/`
+4. Submit a PR
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { run } = require('../src/install.js');
+
+run(process.argv.slice(2));

package/configs/_shared/.claude/commands/fix-issue.md

@@ -0,0 +1,38 @@
+# Fix GitHub Issue
+
+Fix the GitHub issue #$ARGUMENTS
+
+## Steps
+
+1. **Fetch the issue**
+   ```bash
+   gh issue view $ARGUMENTS
+   ```
+
+2. **Analyze the issue**
+   - Understand what's being reported
+   - Identify acceptance criteria
+   - Note any labels (bug, feature, etc.)
+
+3. **Investigate the codebase**
+   - Find relevant files
+   - Understand current behavior
+   - Identify root cause (if bug)
+
+4. **Plan the fix**
+   - List files to modify
+   - Describe the approach
+   - Ask for confirmation before implementing
+
+5. **Implement**
+   - Make minimal, focused changes
+   - Follow project conventions
+   - Add/update tests if needed
+
+6. **Verify**
+   - Run tests
+   - Manually verify the fix addresses the issue
+
+7. **Prepare for PR**
+   - Summarize changes
+   - Reference the issue number in commit message: `fix: description (#$ARGUMENTS)`

package/configs/_shared/.claude/commands/generate-tests.md

@@ -0,0 +1,49 @@
+# Generate Tests
+
+Generate tests for: $ARGUMENTS
+
+## Steps
+
+1. **Analyze the target**
+   - Read the file/function to test
+   - Understand its purpose and behavior
+   - Identify dependencies to mock
+
+2. **Identify test cases**
+
+   ### Happy path
+   - Normal inputs → expected outputs
+
+   ### Edge cases
+   - Empty inputs
+   - Null/undefined
+   - Boundary values
+   - Large inputs
+
+   ### Error cases
+   - Invalid inputs
+   - Missing dependencies
+   - Network/DB failures (if applicable)
+
+3. **Check existing patterns**
+   - Find similar test files in the project
+   - Follow the same structure and conventions
+   - Use the same testing utilities
+
+4. **Generate tests**
+   - Use project's test framework (Jest, Vitest, pytest, xUnit, etc.)
+   - Follow AAA pattern: Arrange, Act, Assert
+   - One assertion per test when possible
+   - Descriptive test names
+
+5. **Verify**
+   - Run the new tests
+   - Ensure they pass
+   - Check coverage if available
+
+## Output
+
+Create the test file following project conventions:
+- `*.spec.ts` or `*.test.ts` (JS/TS)
+- `test_*.py` or `*_test.py` (Python)
+- `*Tests.cs` (C#)

package/configs/_shared/.claude/commands/review-pr.md

@@ -0,0 +1,77 @@
+# Review Pull Request
+
+Review the GitHub PR #$ARGUMENTS
+
+## Steps
+
+1. **Fetch PR details**
+   ```bash
+   gh pr view $ARGUMENTS
+   gh pr diff $ARGUMENTS
+   ```
+
+2. **Understand context**
+   - Read PR title and description
+   - Check linked issues
+   - Note the scope of changes
+
+3. **Review the diff**
+   Go through each changed file and check:
+
+   ### Correctness
+   - Logic errors
+   - Edge cases
+   - Error handling
+
+   ### Security
+   - Input validation
+   - Injection risks
+   - Auth/authz issues
+
+   ### Performance
+   - N+1 queries
+   - Unnecessary operations
+   - Memory concerns
+
+   ### Code Quality
+   - Naming clarity
+   - Single responsibility
+   - Code duplication
+
+   ### Tests
+   - Coverage of new code
+   - Edge cases tested
+
+   ### Conventions
+   - Project style followed
+   - Consistent with codebase
+
+4. **Provide feedback**
+
+   Format your review as:
+
+   ```
+   ## Summary
+   [Overall assessment: approve/request changes/comment]
+
+   ## Critical (must fix)
+   - [ ] Issue 1 (file:line)
+   - [ ] Issue 2 (file:line)
+
+   ## Suggestions (nice to have)
+   - [ ] Suggestion 1
+   - [ ] Suggestion 2
+
+   ## Questions
+   - Question about design choice?
+
+   ## Positive
+   - What's done well
+   ```
+
+5. **Optional: Submit review via CLI**
+   ```bash
+   gh pr review $ARGUMENTS --approve
+   gh pr review $ARGUMENTS --request-changes --body "..."
+   gh pr review $ARGUMENTS --comment --body "..."
+   ```

package/configs/_shared/.claude/rules/accessibility.md

@@ -0,0 +1,270 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
+  - "**/components/**/*.ts"
+---
+
+# Accessibility Rules (WCAG 2.1)
+
+## Semantic HTML
+
+### Use Correct Elements
+```html
+<!-- Bad -->
+<div onclick="submit()">Submit</div>
+<div class="heading">Title</div>
+
+<!-- Good -->
+<button type="submit">Submit</button>
+<h1>Title</h1>
+```
+
+### Heading Hierarchy
+```html
+<!-- Bad - skipping levels -->
+<h1>Page Title</h1>
+<h3>Section</h3>
+
+<!-- Good - sequential -->
+<h1>Page Title</h1>
+<h2>Section</h2>
+<h3>Subsection</h3>
+```
+
+### Landmarks
+```html
+<header role="banner">...</header>
+<nav role="navigation">...</nav>
+<main role="main">...</main>
+<aside role="complementary">...</aside>
+<footer role="contentinfo">...</footer>
+```
+
+## Images
+
+### Alt Text
+```html
+<!-- Informative image -->
+<img src="chart.png" alt="Sales increased 25% in Q4 2024" />
+
+<!-- Decorative image -->
+<img src="decoration.png" alt="" role="presentation" />
+
+<!-- Complex image -->
+<figure>
+  <img src="diagram.png" alt="System architecture diagram" />
+  <figcaption>Detailed description of the system architecture...</figcaption>
+</figure>
+```
+
+## Forms
+
+### Labels
+```html
+<!-- Bad -->
+<input type="email" placeholder="Email" />
+
+<!-- Good -->
+<label for="email">Email</label>
+<input type="email" id="email" name="email" />
+
+<!-- Or with aria-label -->
+<input type="search" aria-label="Search products" />
+```
+
+### Error Messages
+```html
+<label for="email">Email</label>
+<input
+  type="email"
+  id="email"
+  aria-describedby="email-error"
+  aria-invalid="true"
+/>
+<span id="email-error" role="alert">
+  Please enter a valid email address
+</span>
+```
+
+### Required Fields
+```html
+<label for="name">
+  Name <span aria-hidden="true">*</span>
+</label>
+<input type="text" id="name" required aria-required="true" />
+```
+
+## Keyboard Navigation
+
+### Focus Management
+```typescript
+// Trap focus in modals
+function trapFocus(element: HTMLElement) {
+  const focusableElements = element.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  const firstElement = focusableElements[0] as HTMLElement;
+  const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
+
+  element.addEventListener('keydown', (e) => {
+    if (e.key === 'Tab') {
+      if (e.shiftKey && document.activeElement === firstElement) {
+        lastElement.focus();
+        e.preventDefault();
+      } else if (!e.shiftKey && document.activeElement === lastElement) {
+        firstElement.focus();
+        e.preventDefault();
+      }
+    }
+  });
+}
+```
+
+### Visible Focus
+```css
+/* Never remove focus outline without replacement */
+/* Bad */
+*:focus { outline: none; }
+
+/* Good */
+*:focus {
+  outline: 2px solid #0066cc;
+  outline-offset: 2px;
+}
+
+/* Or custom focus styles */
+*:focus-visible {
+  box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.5);
+}
+```
+
+### Skip Links
+```html
+<a href="#main-content" class="skip-link">
+  Skip to main content
+</a>
+
+<style>
+.skip-link {
+  position: absolute;
+  left: -9999px;
+}
+.skip-link:focus {
+  left: 0;
+  top: 0;
+  z-index: 9999;
+}
+</style>
+```
+
+## ARIA
+
+### When to Use
+```html
+<!-- Use ARIA only when HTML semantics aren't enough -->
+
+<!-- Custom components need ARIA -->
+<div
+  role="button"
+  tabindex="0"
+  aria-pressed="false"
+  onkeydown="handleKeyDown(event)"
+>
+  Toggle
+</div>
+
+<!-- Prefer native elements when possible -->
+<button type="button">Toggle</button>
+```
+
+### Live Regions
+```html
+<!-- Announce dynamic content changes -->
+<div aria-live="polite" aria-atomic="true">
+  {{ statusMessage }}
+</div>
+
+<!-- Urgent announcements -->
+<div role="alert">
+  Error: Form submission failed
+</div>
+```
+
+### State Management
+```html
+<!-- Expanded/collapsed -->
+<button aria-expanded="false" aria-controls="menu">
+  Menu
+</button>
+<ul id="menu" hidden>...</ul>
+
+<!-- Selected -->
+<li role="option" aria-selected="true">Option 1</li>
+
+<!-- Loading -->
+<button aria-busy="true" aria-disabled="true">
+  <span class="spinner" aria-hidden="true"></span>
+  Loading...
+</button>
+```
+
+## Color & Contrast
+
+### Minimum Contrast
+- Normal text: 4.5:1 ratio
+- Large text (18px+ or 14px+ bold): 3:1 ratio
+- UI components: 3:1 ratio
+
+### Don't Rely on Color Alone
+```html
+<!-- Bad -->
+<span class="error" style="color: red;">Invalid</span>
+
+<!-- Good -->
+<span class="error" style="color: red;">
+  ⚠️ Invalid - please check this field
+</span>
+```
+
+## Motion
+
+### Respect User Preferences
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Testing
+
+### Automated Tools
+- axe-core (browser extension)
+- eslint-plugin-jsx-a11y (React)
+- @angular-eslint (Angular)
+
+### Manual Testing
+1. Navigate with keyboard only (Tab, Enter, Escape, Arrow keys)
+2. Test with screen reader (VoiceOver, NVDA)
+3. Zoom to 200% - check content reflows
+4. Test with high contrast mode
+
+## Quick Checklist
+
+- [ ] All images have appropriate alt text
+- [ ] Form inputs have associated labels
+- [ ] Heading hierarchy is logical (h1 → h2 → h3)
+- [ ] Interactive elements are keyboard accessible
+- [ ] Focus is visible and managed correctly
+- [ ] Color contrast meets WCAG requirements
+- [ ] ARIA is used correctly (roles, states, properties)
+- [ ] Dynamic content changes are announced
+- [ ] Motion respects prefers-reduced-motion