nitm-ai-dev-toolkit 3.0.15

package/src/monorepo/.agents/skills/linear-cli/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: linear-cli
+description: Manage Linear issues from the command line using the linear CLI. This skill allows automating Linear issue management including creating, updating, querying, and commenting on issues.
+---
+
+# Linear CLI
+
+A CLI to manage Linear issues from the command line, with git and jj integration.
+
+## When to Use
+
+- User asks to create, view, edit, or search Linear issues
+- User needs to manage teams, projects, or cycles
+- User wants to transition issue states or add comments
+- MCP tools (`mcp_linear_*`) are unavailable or failing
+- User needs scripted/batch issue operations
+
+## Prerequisites
+
+The `linear` command must be available on PATH. To check:
+
+```bash
+linear --version
+```
+
+If not installed globally, you can run it without installing via npx:
+
+```bash
+npx @schpet/linear-cli --version
+```
+
+All subsequent commands can be prefixed with `npx @schpet/linear-cli` in place of `linear`. Otherwise, follow the install instructions at:
+https://github.com/schpet/linear-cli?tab=readme-ov-file#install
+
+## Best Practices for Markdown Content
+
+When working with issue descriptions or comment bodies that contain markdown, **always prefer using file-based flags** instead of passing content as command-line arguments:
+
+- Use `--description-file` for `issue create` and `issue update` commands
+- Use `--body-file` for `comment add` and `comment update` commands
+
+**Why use file-based flags:**
+
+- Ensures proper formatting in the Linear web UI
+- Avoids shell escaping issues with newlines and special characters
+- Prevents literal `\n` sequences from appearing in markdown
+- Makes it easier to work with multi-line content
+
+**Example workflow:**
+
+```bash
+# Write markdown to a temporary file
+cat > /tmp/description.md <<'EOF'
+## Summary
+
+- First item
+- Second item
+
+## Details
+
+This is a detailed description with proper formatting.
+EOF
+
+# Create issue using the file
+linear issue create --title "My Issue" --description-file /tmp/description.md
+
+# Or for comments
+linear issue comment add ENG-123 --body-file /tmp/comment.md
+```
+
+**Only use inline flags** (`--description`, `--body`) for simple, single-line content.
+
+## Available Commands
+
+Compact command list, generated from `linear --help`:
+
+```bash
+linear auth
+linear auth login
+linear auth logout
+linear auth list
+linear auth default
+linear auth token
+linear auth whoami
+linear auth migrate
+
+linear issue
+linear issue id
+linear issue mine
+linear issue query
+linear issue title
+linear issue start
+linear issue view
+linear issue url
+linear issue describe
+linear issue commits
+linear issue pull-request
+linear issue delete
+linear issue create
+linear issue update
+linear issue comment
+linear issue comment add
+linear issue comment delete
+linear issue comment update
+linear issue comment list
+linear issue attach
+linear issue link
+linear issue relation
+linear issue relation add
+linear issue relation delete
+linear issue relation list
+
+linear team
+linear team create
+linear team delete
+linear team list
+linear team id
+linear team autolinks
+linear team members
+
+linear project
+linear project list
+linear project view
+linear project create
+linear project update
+linear project delete
+
+linear project-update
+linear project-update create
+linear project-update list
+
+linear cycle
+linear cycle list
+linear cycle view
+
+linear milestone
+linear milestone list
+linear milestone view
+linear milestone create
+linear milestone update
+linear milestone delete
+
+linear initiative
+linear initiative list
+linear initiative view
+linear initiative create
+linear initiative archive
+linear initiative update
+linear initiative unarchive
+linear initiative delete
+linear initiative add-project
+linear initiative remove-project
+
+linear initiative-update
+linear initiative-update create
+linear initiative-update list
+
+linear label
+linear label list
+linear label create
+linear label delete
+
+linear document
+linear document list
+linear document view
+linear document create
+linear document update
+linear document delete
+
+linear config
+linear schema
+linear api
+```
+
+## Discovering Options
+
+To see available subcommands and flags, run `--help` on any command:
+
+```bash
+linear --help
+linear issue --help
+linear issue list --help
+linear issue create --help
+```
+
+Each command has detailed help output describing all available flags and options.
+
+Some commands have required flags that aren't obvious. Notable examples:
+
+- `issue list` requires a sort order — provide it via `--sort` (valid values: `manual`, `priority`), the `issue_sort` config option, or the `LINEAR_ISSUE_SORT` env var. Also requires `--team <key>` unless the team can be inferred from the directory — if unknown, run `linear team list` first.
+- `--no-pager` is only supported on `issue list` — passing it to other commands like `project list` will error.
+
+## Using the Linear GraphQL API Directly
+
+**Prefer the CLI for all supported operations.** The `api` command should only be used as a fallback for queries not covered by the CLI.
+
+### Check the schema for available types and fields
+
+Write the schema to a tempfile, then search it:
+
+```bash
+linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
+grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
+grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"
+```
+
+### Make a GraphQL request
+
+**Important:** GraphQL queries containing non-null type markers (e.g. `String` followed by an exclamation mark) must be passed via heredoc stdin to avoid escaping issues. Simple queries without those markers can be passed inline.
+
+```bash
+# Simple query (no type markers, so inline is fine)
+linear api '{ viewer { id name email } }'
+
+# Query with variables — use heredoc to avoid escaping issues
+linear api --variable teamId=abc123 <<'GRAPHQL'
+query($teamId: String!) { team(id: $teamId) { name } }
+GRAPHQL
+
+# Search issues by text
+linear api --variable term=onboarding <<'GRAPHQL'
+query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
+GRAPHQL
+
+# Pipe to jq for filtering
+linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'
+```
+
+### Advanced: Using curl directly
+
+For cases where you need full HTTP control, use `linear auth token`:
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $(linear auth token)" \
+  -d '{"query": "{ viewer { id } }"}'
+```
+
+## Common Workflows
+
+### Create and Start an Issue
+
+```bash
+linear issue create --title "Implement feature" --team ENG --description-file /tmp/desc.md
+# Note the returned issue key
+linear issue start ENG-123
+```
+
+### View My Current Issues
+
+```bash
+linear issue mine
+```
+
+### Update Issue State
+
+```bash
+linear issue update ENG-123 --state "In Progress"
+linear issue update ENG-123 --state "Done"
+```
+
+### Comment on an Issue
+
+```bash
+linear issue comment add ENG-123 --body "Working on this"
+linear issue comment add ENG-123 --body-file /tmp/update.md
+```
+
+## Limitations
+
+- Requires `linear auth login` before first use
+- Some commands require `--team` flag unless inferred from directory config
+- `issue list` requires explicit sort order
+- `--no-pager` only works on `issue list`
+- Rate limits apply based on Linear API limits

package/src/monorepo/.agents/skills/logging/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: logging
+description: Comprehensive logging standards for applications including structured logging, log levels, message formatting, and observability guidelines
+version: 1.0.0
+author: {{PROJECT_NAME}} Team
+created: 2026-01-26
+updated: 2026-01-26
+tags:
+  - logging
+  - structured-logging
+  - observability
+  - debugging
+  - monitoring
+applies_to:
+  - "**/*.{{FILE_EXTENSION}}"
+  - "services/**/*"
+  - "api/**/*"
+  - "packages/**/*"
+  - "apps/**/*"
+---
+
+# Logging Standards
+
+Comprehensive logging guidelines for consistent, structured, and maintainable logging across the monorepo.
+
+## Core Principles
+
+### 1. Structured Logging
+
+All logs MUST be structured (JSON-serializable) for efficient querying and analysis.
+
+### 2. Contextual Information
+
+Include relevant context (request ID, user ID, session ID) in every log.
+
+### 3. Appropriate Levels
+
+Use correct log levels to enable effective filtering.
+
+### 4. Performance Aware
+
+Avoid expensive operations in log statements.
+
+## Log Levels
+
+| Level     | When to Use                            | Examples                                         |
+| --------- | -------------------------------------- | ------------------------------------------------ |
+| **ERROR** | Application errors requiring attention | Unhandled exceptions, failed critical operations |
+| **WARN**  | Unexpected but recoverable situations  | Retry attempts, deprecated usage, rate limiting  |
+| **INFO**  | Significant application events         | Request handling, job completion, config changes |
+| **DEBUG** | Detailed diagnostic information        | Variable values, execution paths, timing         |
+| **TRACE** | Very detailed debugging                | Loop iterations, method entry/exit               |
+
+## Message Format Pattern
+
+**REQUIRED**: All log messages MUST follow this pattern:
+
+```
+[SERVICE_OR_CLASS]: MESSAGE
+```
+
+The prefix should be the **actual class name or service name** enclosed in square brackets.
+
+## Language-Specific Examples
+
+### TypeScript/JavaScript
+
+```typescript
+import { logger } from "@{{PROJECT_NAME}}/logging";
+
+// ✅ GOOD - Structured with context
+logger.info("[UserService]: User created", {
+	userId: user.id,
+	email: user.email,
+	source: "registration",
+});
+
+// ✅ GOOD - Error with stack trace
+logger.error("[PaymentService]: Payment processing failed", {
+	error: err.message,
+	stack: err.stack,
+	orderId: order.id,
+	amount: order.total,
+});
+
+// ❌ BAD - String interpolation loses structure
+logger.info(`User ${userId} created with email ${email}`);
+
+// ❌ BAD - Missing context
+logger.error("Payment failed");
+```
+
+### Python
+
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+# ✅ GOOD - Structured with context
+logger.info("[UserService]: User created",
+    user_id=user.id,
+    email=user.email,
+    source="registration"
+)
+
+# ✅ GOOD - Error with exception
+logger.error("[PaymentService]: Payment processing failed",
+    error=str(e),
+    order_id=order.id,
+    amount=order.total,
+    exc_info=True
+)
+
+# ❌ BAD - f-string loses structure
+logger.info(f"User {user_id} created with email {email}")
+```
+
+### C# / .NET
+
+```csharp
+// ✅ GOOD - Structured logging with named parameters
+_logger.LogInformation("[UserService]: User created - UserId: {UserId}, Email: {Email}",
+    user.Id, user.Email);
+
+// ✅ GOOD - Error with exception
+_logger.LogError(ex, "[PaymentService]: Payment failed - OrderId: {OrderId}, Amount: {Amount}",
+    order.Id, order.Total);
+
+// ❌ BAD - String interpolation
+_logger.LogInformation($"User {userId} created with email {email}");
+```
+
+### Go
+
+```go
+// ✅ GOOD - Structured with context
+logger.Info("[UserService]: User created",
+    zap.String("userId", user.ID),
+    zap.String("email", user.Email),
+    zap.String("source", "registration"),
+)
+
+// ✅ GOOD - Error with stack
+logger.Error("[PaymentService]: Payment failed",
+    zap.Error(err),
+    zap.String("orderId", order.ID),
+    zap.Float64("amount", order.Total),
+)
+
+// ❌ BAD - Printf style
+logger.Info(fmt.Sprintf("User %s created", userId))
+```
+
+## Contextual Logging
+
+### Request Context
+
+Always include request-scoped identifiers:
+
+```typescript
+// Middleware sets context
+const requestContext = {
+	requestId: req.headers["x-request-id"] || uuid(),
+	userId: req.user?.id,
+	sessionId: req.session?.id,
+	traceId: req.headers["x-trace-id"],
+};
+
+// All logs in request include context
+logger.info("[OrderController]: Order submitted", {
+	...requestContext,
+	orderId: order.id,
+	itemCount: order.items.length,
+});
+```
+
+### Correlation IDs
+
+For async operations, propagate correlation:
+
+```typescript
+async function processOrder(order: Order, correlationId: string) {
+	logger.info("[OrderProcessor]: Starting order processing", {
+		correlationId,
+		orderId: order.id,
+	});
+
+	// Pass to downstream services
+	await inventoryService.reserve(order.items, { correlationId });
+	await paymentService.charge(order.total, { correlationId });
+
+	logger.info("[OrderProcessor]: Order processing complete", {
+		correlationId,
+		orderId: order.id,
+		duration: Date.now() - startTime,
+	});
+}
+```
+
+## Performance Logging
+
+### Timing Operations
+
+```typescript
+const startTime = performance.now();
+
+await expensiveOperation();
+
+const duration = performance.now() - startTime;
+logger.info("[DataProcessor]: Operation completed", {
+	operationType: "batch-import",
+	recordCount: records.length,
+	durationMs: Math.round(duration),
+	recordsPerSecond: Math.round(records.length / (duration / 1000)),
+});
+```
+
+### Conditional Debug Logging
+
+```typescript
+// Avoid expensive serialization unless needed
+if (logger.isDebugEnabled()) {
+	logger.debug("[CacheService]: Cache contents", {
+		keys: cache.keys(),
+		size: cache.size,
+		hitRate: cache.stats.hitRate,
+	});
+}
+```
+
+## Error Logging Best Practices
+
+### Include Full Context
+
+```typescript
+try {
+	await processPayment(order);
+} catch (error) {
+	logger.error("[PaymentService]: Payment processing failed", {
+		error: error.message,
+		stack: error.stack,
+		errorCode: error.code,
+		// Business context
+		orderId: order.id,
+		userId: order.userId,
+		amount: order.total,
+		paymentMethod: order.paymentMethod,
+		// Request context
+		requestId: context.requestId,
+		// Recovery info
+		retryable: isRetryableError(error),
+		attemptNumber: attempt,
+	});
+	throw error;
+}
+```
+
+### Categorize Errors
+
+```typescript
+// Tag errors for monitoring/alerting
+logger.error("[AuthService]: Authentication failed", {
+	errorCategory: "SECURITY",
+	errorType: "INVALID_CREDENTIALS",
+	userId: attemptedUserId,
+	ipAddress: request.ip,
+	userAgent: request.headers["user-agent"],
+});
+```
+
+## Sensitive Data
+
+### Never Log
+
+- Passwords or secrets
+- Full credit card numbers
+- Social security numbers
+- API keys or tokens
+- Personal health information
+
+### Masking Patterns
+
+```typescript
+const maskEmail = (email: string) => {
+	const [local, domain] = email.split("@");
+	return `${local.slice(0, 2)}***@${domain}`;
+};
+
+const maskCardNumber = (card: string) => {
+	return `****-****-****-${card.slice(-4)}`;
+};
+
+logger.info("[PaymentService]: Payment authorized", {
+	email: maskEmail(user.email), // "jo***@example.com"
+	cardNumber: maskCardNumber(card), // "****-****-****-1234"
+	amount: order.total,
+});
+```
+
+## Monorepo Logger Package
+
+Create a shared logging package for consistency:
+
+```
+packages/
+└── logging/
+    ├── src/
+    │   └── index.ts
+    ├── package.json
+    └── README.md
+```
+
+```typescript
+// packages/logging/src/index.ts
+import pino from "pino";
+
+export const createLogger = (service: string) => {
+	return pino({
+		name: service,
+		level: process.env.LOG_LEVEL || "info",
+		formatters: {
+			level: (label) => ({ level: label }),
+		},
+		base: {
+			service,
+			environment: process.env.NODE_ENV,
+			version: process.env.APP_VERSION,
+		},
+	});
+};
+
+// Usage in apps
+// apps/{{APP_NAME_1}}/src/index.ts
+import { createLogger } from "@{{PROJECT_NAME}}/logging";
+const logger = createLogger("{{APP_NAME_1}}");
+```
+
+## Environment Configuration
+
+```bash
+# .env
+LOG_LEVEL=info              # Minimum log level
+LOG_FORMAT=json             # json | pretty
+LOG_DESTINATION=stdout      # stdout | file | service
+LOG_SERVICE_URL=            # External logging service URL
+```
+
+## Observability Integration
+
+### OpenTelemetry Context
+
+```typescript
+import { trace, context } from "@opentelemetry/api";
+
+function logWithTrace(level: string, message: string, data: object) {
+	const span = trace.getSpan(context.active());
+	const traceContext = span
+		? {
+				traceId: span.spanContext().traceId,
+				spanId: span.spanContext().spanId,
+			}
+		: {};
+
+	logger[level](message, { ...data, ...traceContext });
+}
+```
+
+## Quick Reference
+
+### Log Level Decision Tree
+
+```
+Is it an error that needs attention? → ERROR
+Is it unexpected but handled? → WARN
+Is it a significant business event? → INFO
+Is it helpful for debugging? → DEBUG
+Is it very detailed/verbose? → TRACE
+```
+
+### Checklist Before Logging
+
+- [ ] Using structured format (not string interpolation)
+- [ ] Service/class prefix in brackets
+- [ ] Relevant context included
+- [ ] Sensitive data masked
+- [ ] Appropriate log level
+- [ ] No expensive operations in log statement
+
+## Related Skills
+
+- See `.agents/skills/systematic-debugging/` for debugging workflows
+- See `.agents/skills/verification-before-completion/` for testing logs

package/src/monorepo/.agents/skills/orient-to-recent-work/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: orient-to-recent-work
+description: Build a compact mental model of recent project activity before any non-trivial task. Use proactively at the start of a session and before any investigation, planning, refactor, or multi-file change. Skip only for trivial fixes (typos, isolated docs, version bumps, mechanical refactors with a known target).
+---
+
+# Orient to recent work
+
+Before starting a non-trivial task, build a compact mental model of what has happened recently in this repository. This prevents re-litigating settled decisions and surfaces context that may not be in code or docs.
+
+## When to use
+
+**Use proactively:**
+- At the start of a session (before the first task)
+- Before any investigation, planning, refactor, or multi-file change
+- When picking up a thread after a break
+
+**Skip for:**
+- Single-line typo fixes
+- Isolated documentation updates
+- Dependency version bumps without logic changes
+- Mechanical refactors with a known target
+
+## Protocol (do once per session, hold the result)
+
+1. **Read `CHANGELOG.md` [Unreleased]** — pending changes the team is preparing
+2. **Read the most recent released section of `CHANGELOG.md`** — what just shipped
+3. **Run `git log --oneline -20`** — recent commits at a glance
+4. **For commits that touch files you'll modify, run `git show <hash> --stat`** — scope only, not the full diff
+5. **Hold this mental model in working memory** for the session; re-run only if task scope changes dramatically
+
+## Output format
+
+A 3–5 line summary capturing:
+- What's in flight (Unreleased highlights)
+- What just shipped (last release)
+- Any recent decisions affecting your task (naming, refactor, schema)
+- If your task touches recently-modified files, append: `Recent touch on <files>: <commit summary>`
+
+## Why
+
+- Decisions have non-code context (commit messages, PR descriptions)
+- Fresh sessions have no memory — this creates session-level orientation
+- Prevents re-litigating recently-settled questions