nitm-ai-dev-toolkit 3.0.15

package/src/repo/.claude/rules-snippets/logging.md

@@ -0,0 +1,352 @@
+# Logging Standards
+
+## Overview
+
+Consistent logging is critical for debugging, monitoring, and understanding application behavior in production.
+
+## Log Format
+
+### Structured Logging
+
+Use bracketed tags to identify the source:
+
+```{{FILE_EXTENSION}}
+[ComponentName]: message
+[ServiceName]: operation completed
+[UtilityName]: processing data
+```
+
+### Log Message Structure
+
+```
+[Source] [Context]: Action/Event | Additional details
+```
+
+**Examples:**
+
+```javascript
+// Good
+console.log("[UserService] [fetchUser]: Retrieved user data | userId:", userId);
+console.error(
+	"[PaymentService] [processPayment]: Payment failed | error:",
+	error.message,
+);
+console.warn("[CacheService] [invalidate]: Cache miss | key:", cacheKey);
+
+// Bad
+console.log("got user");
+console.error("error");
+console.log(data);
+```
+
+## Log Levels
+
+### error
+
+**Use for:** Critical failures that require immediate attention
+
+- Unhandled exceptions
+- Database connection failures
+- External API failures
+- Data corruption
+- Security violations
+
+```{{FILE_EXTENSION}}
+console.error('[DatabaseService]: Connection failed | error:', error);
+```
+
+### warn
+
+**Use for:** Issues that don't stop execution but need attention
+
+- Deprecated API usage
+- Rate limit approaching
+- Fallback behavior triggered
+- Configuration issues
+- Unexpected but handled states
+
+```{{FILE_EXTENSION}}
+console.warn('[AuthService]: Using fallback auth method | reason:', reason);
+```
+
+### info
+
+**Use for:** Significant application events
+
+- Application startup/shutdown
+- Configuration loaded
+- User authentication
+- Major state changes
+- Background job completion
+
+```{{FILE_EXTENSION}}
+console.info('[Application]: Started successfully | port:', port);
+```
+
+### debug
+
+**Use for:** Detailed diagnostic information
+
+- Function entry/exit
+- Variable values
+- Conditional branches taken
+- Loop iterations
+- Algorithm steps
+
+```{{FILE_EXTENSION}}
+console.debug('[Validator]: Checking constraints | input:', input);
+```
+
+## Logging Best Practices
+
+### Do
+
+✅ **Include context**: User IDs, request IDs, timestamps
+✅ **Log at boundaries**: API calls, database queries, external services
+✅ **Use appropriate levels**: Match severity to log level
+✅ **Include error stack traces**: For debugging
+✅ **Log state changes**: Before and after important operations
+✅ **Use structured data**: Objects for complex data
+✅ **Sanitize sensitive data**: Remove passwords, tokens, PII
+
+### Don't
+
+❌ **Log in tight loops**: Can impact performance
+❌ **Log sensitive data**: Passwords, API keys, tokens, PII
+❌ **Use console.log in production**: Use proper logging library
+❌ **Log entire objects blindly**: Can expose sensitive data
+❌ **Ignore error context**: Include stack traces and related data
+❌ **Use vague messages**: "Error occurred", "Success", "Done"
+❌ **Log at wrong level**: Info for errors, error for warnings
+
+## Sensitive Data Handling
+
+### Never Log
+
+- Passwords (plain or hashed)
+- API keys and tokens
+- Private keys and certificates
+- Credit card numbers
+- Social security numbers
+- Personal health information
+- Authentication cookies/sessions
+
+### Sanitization Examples
+
+```javascript
+// Bad
+console.log("[AuthService]: Login attempt", { username, password });
+
+// Good
+console.log("[AuthService]: Login attempt | username:", username);
+
+// Bad
+console.log("[PaymentService]: Processing payment", paymentData);
+
+// Good
+const sanitized = {
+	...paymentData,
+	cardNumber: "****" + paymentData.cardNumber.slice(-4),
+	cvv: "***",
+};
+console.log("[PaymentService]: Processing payment", sanitized);
+```
+
+## Performance Considerations
+
+### Conditional Logging
+
+```javascript
+// Only log in development
+if (process.env.NODE_ENV === "development") {
+	console.debug("[DataProcessor]: Intermediate result", data);
+}
+
+// Use log level checks
+if (logger.level <= LogLevel.DEBUG) {
+	console.debug("[Service]: Expensive computation", expensiveOperation());
+}
+```
+
+### Avoid Logging in Hot Paths
+
+```javascript
+// Bad - logs on every iteration
+for (const item of items) {
+	console.log("[Processor]: Processing item", item);
+	process(item);
+}
+
+// Good - log summary
+console.info("[Processor]: Processing batch | count:", items.length);
+for (const item of items) {
+	process(item);
+}
+console.info("[Processor]: Batch complete | processed:", items.length);
+```
+
+## Error Logging
+
+### Complete Error Context
+
+```javascript
+try {
+	await riskyOperation();
+} catch (error) {
+	console.error("[ServiceName] [operation]: Operation failed", {
+		error: error.message,
+		stack: error.stack,
+		context: { userId, requestId, timestamp: Date.now() },
+	});
+	// Re-throw or handle
+}
+```
+
+### Structured Error Logging
+
+```javascript
+const logError = (source, operation, error, context = {}) => {
+	console.error(`[${source}] [${operation}]: ${error.message}`, {
+		error: {
+			name: error.name,
+			message: error.message,
+			stack: error.stack,
+		},
+		...context,
+	});
+};
+
+// Usage
+logError("UserService", "createUser", error, { userId, email });
+```
+
+## Framework-Specific Guidelines
+
+### Next.js
+
+```typescript
+// Server components
+import { logger } from "@/lib/logger";
+
+export default async function Page() {
+	logger.info("[HomePage]: Rendering");
+	// ...
+}
+
+// API routes
+export async function POST(request: Request) {
+	try {
+		logger.info("[API] [/users]: Create user request");
+		// ...
+	} catch (error) {
+		logger.error("[API] [/users]: Failed to create user", { error });
+	}
+}
+```
+
+### Django
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+class UserView(View):
+    def get(self, request):
+        logger.info(f'[UserView] [get]: Request | user_id={request.user.id}')
+        try:
+            # ...
+        except Exception as e:
+            logger.error(f'[UserView] [get]: Failed | error={str(e)}', exc_info=True)
+```
+
+### Laravel
+
+```php
+use Illuminate\Support\Facades\Log;
+
+class UserController extends Controller
+{
+    public function store(Request $request)
+    {
+        Log::info('[UserController] [store]: Creating user');
+
+        try {
+            // ...
+        } catch (\Exception $e) {
+            Log::error('[UserController] [store]: Failed', [
+                'error' => $e->getMessage(),
+                'trace' => $e->getTraceAsString()
+            ]);
+        }
+    }
+}
+```
+
+## Production Logging
+
+### Log Aggregation
+
+Integrate with log aggregation services:
+
+- Sentry (errors)
+- Datadog
+- CloudWatch
+- LogRocket
+- Papertrail
+
+### Correlation IDs
+
+```javascript
+// Add to all logs in a request
+const requestId = generateId();
+context.set("requestId", requestId);
+
+console.info("[API]: Request started | requestId:", requestId);
+console.info("[Service]: Processing | requestId:", requestId);
+console.info("[API]: Request complete | requestId:", requestId);
+```
+
+## Monitoring and Alerts
+
+### Log-Based Alerts
+
+Set up alerts for:
+
+- High error rates
+- Specific error patterns
+- Performance degradation
+- Security events
+- Business-critical failures
+
+### Metrics from Logs
+
+Extract metrics:
+
+- Request duration
+- Error rates by endpoint
+- User activity patterns
+- Cache hit rates
+- External API latency
+
+## Testing Logs
+
+### Test Log Output
+
+```javascript
+// Jest example
+const consoleSpy = jest.spyOn(console, "error");
+
+test("logs error on failure", async () => {
+	await failingOperation();
+
+	expect(consoleSpy).toHaveBeenCalledWith(
+		expect.stringContaining("[ServiceName]"),
+		expect.any(Object),
+	);
+});
+```
+
+---
+
+**Last Updated**: {{DATE}}

package/src/repo/.claude/rules-snippets/patterns.md

@@ -0,0 +1,29 @@
+# Patterns and conventions
+
+## State management
+
+- State modules live in `{{STATE_DIR}}`.
+- Use {{STATE_MANAGEMENT}} for state management.
+- {{STATE_PATTERN_DESCRIPTION}}
+
+## API patterns
+
+- API services live in `{{SERVICES_DIR}}`.
+- {{API_PATTERN_DESCRIPTION}}
+
+## Component patterns
+
+- Components follow {{COMPONENT_PATTERN}} pattern.
+- {{COMPONENT_PATTERN_DESCRIPTION}}
+
+## Utilities
+
+- Shared utilities live in `{{UTILS_DIR}}`.
+- {{UTILITY_PATTERN_DESCRIPTION}}
+
+## SRP and reuse-first principle
+
+- **Before implementing new functionality, review existing patterns** in `{{COMPOSABLES_PATH}}`, `{{UTILS_PATH}}`, and `{{HELPERS_PATH}}` for capabilities that already solve the problem.
+- **Prefer extending existing utilities** over creating new ones or duplicating logic inline — a new solution is only warranted when the existing one genuinely cannot accommodate the use case.
+- **Never duplicate state or behavior** that an existing utility already manages (e.g., loading flags, error state, async wrappers). Inline duplication violates SRP and makes behavior inconsistent across the codebase.
+- When in doubt, extend the existing pattern and keep consumers (components, controllers, handlers) thin.

package/src/repo/.claude/rules-snippets/ponytail.md

@@ -0,0 +1,24 @@
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does the standard library already do this? Use it.
+3. Does a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one line? Make it one line.
+6. Only then: write the minimum code that works.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark intentional simplifications with a `ponytail:` comment. If the shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), the comment names the ceiling and the upgrade path.
+
+Not lazy about: input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

package/src/repo/.claude/rules-snippets/prisma-migrations.md

@@ -0,0 +1,8 @@
+# Database Migrations
+
+- {{DATABASE_SYNC_RULE}}
+- Create migrations with descriptive names.
+- Apply migrations to development database before committing.
+- Maintain corresponding model definitions for database entities.
+- Update affected services after schema changes.
+- Run tests after schema modifications.

package/src/repo/.claude/rules-snippets/project-context.md

@@ -0,0 +1,25 @@
+# {{PROJECT_NAME}} architecture
+
+- **Framework:** {{FRAMEWORK}}
+- **Language:** {{LANGUAGE}}
+- Entry point: {{ENTRY_POINT}}
+
+## Directory structure
+
+- `src/components/` - UI components
+- `src/pages/` - Page components/routes
+- `src/services/` - API and business logic
+- `src/stores/` - State management
+- `src/types/` - TypeScript definitions
+
+## Data flow
+
+- {{DATA_FLOW_DESCRIPTION}}
+
+## Authentication
+
+- {{AUTH_DESCRIPTION}}
+
+## API integration
+
+- {{API_INTEGRATION_DESCRIPTION}}

package/src/repo/.claude/rules-snippets/server-client-separation.md

@@ -0,0 +1,7 @@
+# Server-Client Separation
+
+- Never import server-only code in client components.
+- Use API endpoints to expose server functionality to clients.
+- Create shared types for cross-boundary use.
+- Use appropriate data fetching patterns for the framework.
+- Mark server-only modules clearly (e.g., `.server.{{LANGUAGE_EXTENSION}}`).

package/src/repo/.claude/rules-snippets/subagent-workflow.md

@@ -0,0 +1,134 @@
+# Subagent Workflow
+
+## 🛑 BEFORE STARTING: Orchestration Checkpoint
+
+**READ THIS SECTION FIRST if you are about to start work.** This instruction file is loaded automatically for multi-step tasks, meaning:
+
+1. **You are likely handling 2+ of:** research, planning, implementation, testing, review, validation
+2. **You MUST answer:** Does this task involve independent subtasks or multiple domains?
+3. **If YES:** Use a coordinator agent (Feature Builder, TDD, or other) instead of single-agent execution
+4. **If NO (single focused task):** Document why you're using a single agent, then proceed
+
+### Signs You Should Use Orchestrator-First
+
+- ✅ Multiple files across different directories
+- ✅ Planning phase + implementation phase
+- ✅ Multiple independent reviewable chunks
+- ✅ Different domain areas (backend + frontend + docs)
+- ✅ Test coverage needed alongside changes
+- ✅ Architecture decisions before coding
+- ✅ Direct code review feedback (no implementation)
+- ✅ Research task (no code changes)
+
+### Signs Single Agent Is OK
+
+- ✅ Single file edit
+- ✅ Quick typo/syntax fix
+- ✅ Small documentation update
+
+**When in doubt, use orchestrator-first.** It is lower-cost than sequential agent work and provides better code review isolation.
+
+---
+
+## Orchestrator-First Principle
+
+**Default to using a coordinator agent for non-trivial work.** Coordinators break complex tasks into focused subtasks and dispatch specialized subagents with context isolation.
+
+## When to Use Orchestrator + Subagents
+
+- Features spanning multiple files or domains
+- Tasks requiring planning → implementation → review cycles
+- Work that benefits from domain specialization (backend, frontend, API)
+- Any task with 2+ independent subtasks
+
+## When to Use a Single Agent Directly
+
+- Quick one-file fixes or small edits
+- Research questions that don't require code changes
+- Ad-hoc code reviews (invoke Reviewer directly)
+- Simple documentation updates
+- Domain-specific advice without implementation
+
+## Available Coordinators
+
+| Coordinator         | Purpose                                      | Dispatches                                                                                                                  |
+| ------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Feature Builder** | End-to-end feature development orchestration | Planner, Implementer, Reviewer, Researcher, Backend Architect, Frontend Developer, API Specialist, Admin Portal, Documenter |
+| **TDD**             | Red-green-refactor cycle coordination        | Red, Green, Refactor                                                                                                        |
+
+## Domain Specialist Selection
+
+When dispatching implementation tasks, match the specialist to the domain:
+
+| Domain                             | Specialist             |
+| ---------------------------------- | ---------------------- |
+| API design, databases, system arch | **Backend Architect**  |
+| UI components, state, responsive   | **Frontend Developer** |
+| API contracts, docs, versioning    | **API Specialist**     |
+| Admin dashboards, RBAC, reporting  | **Admin Portal**       |
+| Project documentation              | **Documenter**         |
+| General / cross-cutting            | **Implementer**        |
+
+## Orchestration Patterns
+
+### Sequential (default)
+
+Tasks with dependencies are implemented one at a time in dependency order. Each must pass review before the next begins.
+
+### Parallel
+
+Independent tasks can be dispatched to multiple specialist subagents simultaneously. Use when tasks don't share files or state.
+
+### Parallelization Analysis (REQUIRED before dispatching)
+
+Before executing any task list, the orchestrator MUST run this analysis:
+
+1. **Scan for `[P]` markers** in the task list — these are pre-identified parallel candidates
+   - If no `[P]` markers exist, do **not** assume sequential-only work. Treat all tasks as candidates and infer parallel-safe groups via the independence test.
+2. **Build a dependency graph**: For each task, list which files it reads and writes
+3. **Apply the independence test**:
+   - Tasks that write to **different files** with **no shared state** → parallel-safe
+   - Tasks that share any writable file → sequential (dependency edge)
+   - Tasks where one reads what another writes → sequential (data dependency)
+4. **Group by domain** for specialist routing:
+   - Backend tasks → Backend Architect
+   - Frontend tasks → Frontend Developer
+   - API contract tasks → API Specialist
+   - Documentation tasks → Documenter
+   - Cross-cutting → Implementer
+5. **Dispatch decision**:
+   - **3+ independent tasks** → Use `dispatching-parallel-agents` skill, one agent per task
+   - **2 independent tasks** → Parallel dispatch (simpler coordination)
+   - **All tasks dependent** → Sequential with `subagent-driven-development` skill
+   - **Mixed** → Dispatch independent group in parallel, then continue sequential chain
+
+```
+Example: 5 tasks → T001 (setup) → T002 [P] (backend API) + T003 [P] (frontend UI) + T004 [P] (docs) → T005 (integration tests)
+         Dispatch: T001 sequential → T002+T003+T004 parallel → T005 sequential
+```
+
+## Quality Gates
+
+- Every implementation must pass **Reviewer** before proceeding
+- Every plan must pass **Reviewer** before final acceptance during a commit or before implementation begins
+- Coordinators should not skip review even for "simple" changes
+- If a reviewer requests changes, the original specialist fixes them and re-review occurs
+
+## Skills Integration
+
+These skills complement subagent workflows:
+
+| Skill                            | When to Use                                      |
+| -------------------------------- | ------------------------------------------------ |
+| `writing-plans`                  | Creating implementation plans before execution   |
+| `subagent-driven-development`    | Executing plans with fresh subagent per task     |
+| `executing-plans`                | Following through on plans in a separate session |
+| `dispatching-parallel-agents`    | Multiple independent problems to solve           |
+| `requesting-code-review`         | Structured review between implementation stages  |
+| `receiving-code-review`          | Responding constructively to review feedback     |
+| `verification-before-completion` | Quality checks before claiming work done         |
+| `finishing-a-development-branch` | Completing work after all tasks pass review      |
+| `orient-to-recent-work`          | Build context from recent project activity       |
+| `brainstorming`                  | Structured ideation when scope is fuzzy          |
+| `systematic-debugging`           | Structured root cause investigation              |
+| `using-superpowers`              | Leveraging the full skill system                 |

package/src/repo/.claude/rules-snippets/testing-quality.md

@@ -0,0 +1,5 @@
+- Ensure lint, test, and build pass before committing.
+- Use {{TEST_FRAMEWORK}} for unit/component tests.
+- Use {{E2E_FRAMEWORK}} for end-to-end tests.
+- Place tests alongside implementation files or in `tests/` directory.
+- Aim for meaningful test coverage of business logic.

package/src/repo/.claude/rules-snippets/testing.md

@@ -0,0 +1,38 @@
+# Testing Standards
+
+## Commands
+
+```bash
+# Run all tests
+{{TEST_COMMAND}}
+
+# Run tests with coverage
+{{TEST_COVERAGE_COMMAND}}
+
+# Run E2E tests
+{{E2E_TEST_COMMAND}}
+```
+
+## Test Structure
+
+```{{FILE_EXTENSION}}
+{{TEST_EXAMPLE}}
+```
+
+## Test File Naming
+
+- Unit tests: `{{TEST_FILE_PATTERN}}`
+- Integration tests: `{{INTEGRATION_TEST_PATTERN}}`
+- E2E tests: `{{E2E_TEST_PATTERN}}`
+
+## Test Location
+
+- Unit tests live alongside source files or in `{{TEST_DIR}}/`
+- Integration tests in `{{INTEGRATION_TEST_DIR}}/`
+- E2E tests in `{{E2E_TEST_DIR}}/`
+
+## Coverage Requirements
+
+- Minimum coverage: {{COVERAGE_THRESHOLD}}
+- Critical paths must have integration or E2E coverage
+- New features require tests before merging

package/src/repo/.claude/rules-snippets/ui-accessibility.md

@@ -0,0 +1,7 @@
+# UI & Accessibility
+
+- Develop with a mobile-first approach.
+- Adhere to WCAG 2.1 AA accessibility standards.
+- Use semantic HTML elements.
+- Ensure keyboard navigation and focus management.
+- Use loading states during async operations.

package/src/repo/.claude/rules-snippets/version-control.md

@@ -0,0 +1,6 @@
+# Version Control
+
+- Use conventional commit format: `<type>(<scope>): <description>`.
+- Types: feat, fix, docs, refactor, test, chore, style, perf.
+- Include ticket reference when applicable: `feat(auth): add login flow [{{ISSUE_PREFIX}}-123]`.
+- Follow the PR template for pull requests.

package/src/repo/.claude/rules-snippets/what-to-avoid.md

@@ -0,0 +1,8 @@
+# Anti-Patterns (What to Avoid)
+
+- No deprecated {{FRAMEWORK}} features.
+- No global CSS outside {{STYLING}} configuration.
+- No direct DOM manipulation; use framework reactivity.
+- No custom solutions for problems solved by core libraries.
+- No inconsistent naming for events or handlers.
+- No mixing server and client code inappropriately.

package/src/repo/.claude/rules-snippets/workflows.md

@@ -0,0 +1,25 @@
+# Workflows
+
+## Development
+
+- **Start dev server:** `{{PACKAGE_MANAGER}} run dev` (port {{DEV_PORT}})
+- **Build:** `{{PACKAGE_MANAGER}} run build`
+- **Type check:** `{{PACKAGE_MANAGER}} run type-check`
+
+## Testing
+
+- **Unit tests:** `{{PACKAGE_MANAGER}} run test`
+- **Coverage:** `{{PACKAGE_MANAGER}} run test:coverage`
+- **E2E tests:** `{{PACKAGE_MANAGER}} run test:e2e`
+
+## Code quality
+
+- **Lint:** `{{PACKAGE_MANAGER}} run lint`
+- **Format:** `{{PACKAGE_MANAGER}} run format`
+
+## Environment variables
+
+| Variable        | Purpose            | Required |
+| --------------- | ------------------ | -------- |
+| `{{ENV_VAR_1}}` | {{ENV_VAR_1_DESC}} | Yes      |
+| `{{ENV_VAR_2}}` | {{ENV_VAR_2_DESC}} | No       |

package/src/repo/.claude/settings.json

@@ -0,0 +1,7 @@
+{
+    "permissions": {
+        "allow": [],
+        "deny": []
+    },
+    "env": {}
+}