natureco-cli 5.18.3 → 5.20.0

package/skills/node/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: node
+description: Provides domain-specific best practices for Node.js development with TypeScript, covering type stripping, async patterns, error handling, streams, modules, testing, performance, caching, logging, and more. Use when setting up Node.js projects with native TypeScript support, configuring type stripping (--experimental-strip-types), writing Node 22+ TypeScript without a build step, or when the user mentions 'native TypeScript in Node', 'strip types', 'Node 22 TypeScript', '.ts files without compilation', 'ts-node alternative', or needs guidance on error handling, graceful shutdown, flaky tests, profiling, or environment configuration in Node.js. Helps configure tsconfig.json for type stripping, set up package.json scripts, handle module resolution and import extensions, and apply robust patterns across the full Node.js stack.
+metadata:
+  tags: node, nodejs, javascript, typescript, type-stripping, backend, server
+---
+
+## When to use
+
+Use this skill whenever you are dealing with Node.js code to obtain domain-specific knowledge for building robust, performant, and maintainable Node.js applications.
+
+## TypeScript with Type Stripping
+
+When writing TypeScript for Node.js, use **type stripping** (Node.js 22.6+) instead of build tools like ts-node or tsx. Type stripping runs TypeScript directly by removing type annotations at runtime without transpilation.
+
+Key requirements for type stripping compatibility:
+- Use `import type` for type-only imports
+- Use const objects instead of enums
+- Avoid namespaces and parameter properties
+- Use `.ts` extensions in imports
+
+**Minimal example** — a valid type-stripped TypeScript file:
+
+```ts
+// greet.ts
+import type { IncomingMessage } from 'node:http';
+
+const greet = (name: string): string => `Hello, ${name}!`;
+console.log(greet('world'));
+```
+
+Run directly with:
+```bash
+node greet.ts
+```
+
+See [rules/typescript.md](rules/typescript.md) for complete configuration and examples.
+
+## Common Workflows
+
+For multi-step processes, follow these high-level sequences before consulting the relevant rule file:
+
+**Graceful shutdown**: Register signal handlers (SIGTERM/SIGINT) → stop accepting new work → drain in-flight requests → close external connections (DB, cache) → exit with appropriate code. See [rules/graceful-shutdown.md](rules/graceful-shutdown.md).
+
+**Error handling**: Define a shared error base class → classify errors (operational vs programmer) → add async boundary handlers (`process.on('unhandledRejection')`) → propagate typed errors through the call stack → log with context before responding or crashing. See [rules/error-handling.md](rules/error-handling.md).
+
+**Diagnosing flaky tests**: Isolate the test with `--test-only` → check for shared state or timer dependencies → inspect async teardown order → add retry logic as a temporary diagnostic step → fix root cause. See [rules/flaky-tests.md](rules/flaky-tests.md).
+
+**Diagnosing stuck processes/tests** (`node --test` hangs, "process did not exit", CI timeout, open handles): isolate file/test → run with explicit timeout/reporter → inspect handles via `why-is-node-running` (`SIGUSR1`) → patch deterministic teardown in resource-creation scope → rerun isolated + full suite until stable. See [rules/stuck-processes-and-tests.md](rules/stuck-processes-and-tests.md).
+
+**Profiling a slow path**: Reproduce under realistic load → capture a CPU profile with `--cpu-prof` → identify hot functions → check for stream backpressure or unnecessary serialisation → validate improvement with a benchmark. See [rules/profiling.md](rules/profiling.md) and [rules/performance.md](rules/performance.md).
+
+## High-priority activation checklist (streams + caching)
+
+When the task mentions **CSV**, **ETL**, **ingestion pipelines**, **large file processing**, **backpressure**, **repeated lookups**, or **deduplicating concurrent async calls**, explicitly apply this checklist:
+
+1. Use `await pipeline(...)` from `node:stream/promises` (prefer this over chained `.pipe()` in guidance/code).
+2. Include at least one explicit `async function*` transform when data is being transformed in-stream.
+3. Choose a cache strategy when repeated work appears:
+   - `lru-cache` for bounded in-memory reuse in a single process.
+   - `async-cache-dedupe` for async request deduplication / stale-while-revalidate behavior.
+4. Show where backpressure is handled (implicitly via `pipeline()` or explicitly via `drain`).
+
+### Integrated example pattern (CSV/ETL)
+
+For CSV/ETL-style prompts, prefer an answer structure like:
+- `createReadStream(input)`
+- `async function*` parser/transform
+- optional cached enrichment lookup (`async-cache-dedupe` or `lru-cache`)
+- `await pipeline(...)` to a writable destination
+
+Link relevant rules directly in explanations so models can retrieve details:
+- [rules/streams.md](rules/streams.md)
+- [rules/caching.md](rules/caching.md)
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+- [rules/error-handling.md](rules/error-handling.md) - Error handling patterns in Node.js
+- [rules/async-patterns.md](rules/async-patterns.md) - Async/await and Promise patterns
+- [rules/streams.md](rules/streams.md) - Working with Node.js streams
+- [rules/modules.md](rules/modules.md) - ES Modules and CommonJS patterns
+- [rules/testing.md](rules/testing.md) - Testing strategies for Node.js applications
+- [rules/flaky-tests.md](rules/flaky-tests.md) - Identifying and diagnosing flaky tests with node:test
+- [rules/stuck-processes-and-tests.md](rules/stuck-processes-and-tests.md) - Diagnosing processes that do not exit and tests that get stuck
+- [rules/node-modules-exploration.md](rules/node-modules-exploration.md) - Navigating and analyzing node_modules directories
+- [rules/performance.md](rules/performance.md) - Performance optimization techniques
+- [rules/caching.md](rules/caching.md) - Caching patterns and libraries
+- [rules/profiling.md](rules/profiling.md) - Profiling and benchmarking tools
+- [rules/logging.md](rules/logging.md) - Logging and debugging patterns
+- [rules/environment.md](rules/environment.md) - Environment configuration and secrets management
+- [rules/graceful-shutdown.md](rules/graceful-shutdown.md) - Graceful shutdown and signal handling
+- [rules/typescript.md](rules/typescript.md) - TypeScript configuration and type stripping in Node.js

package/skills/nodejs-core/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: nodejs-core
+description: Debugs native module crashes, optimizes V8 performance, configures node-gyp builds, writes N-API/node-addon-api bindings, and diagnoses libuv event loop issues in Node.js. Use when working with C++ addons, native modules, binding.gyp, node-gyp errors, segfaults, memory leaks in native code, V8 optimization/deoptimization, libuv thread pool tuning, N-API or NAN bindings, build system failures, or any Node.js internals below the JavaScript layer.
+metadata:
+  tags: nodejs, v8, libuv, cpp, native-addons, performance, debugging, internals
+---
+
+## When to use
+
+Use this skill when you need deep Node.js internals expertise, including:
+- C++ addon development
+- V8 engine debugging
+- libuv event loop issues
+- Build system problems
+- Compilation failures
+- Performance optimization at the engine level
+- Understanding Node.js core architecture
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+### V8 Engine
+
+- [rules/v8-garbage-collection.md](rules/v8-garbage-collection.md) - Scavenger, Mark-Sweep, Mark-Compact, generational GC
+- [rules/v8-hidden-classes.md](rules/v8-hidden-classes.md) - Hidden classes, inline caching, optimization
+- [rules/v8-jit-compilation.md](rules/v8-jit-compilation.md) - TurboFan, optimization/deoptimization patterns
+
+### libuv
+
+- [rules/libuv-event-loop.md](rules/libuv-event-loop.md) - Event loop phases, timers, I/O, idle, check, close
+- [rules/libuv-thread-pool.md](rules/libuv-thread-pool.md) - Thread pool size, blocking operations, UV_THREADPOOL_SIZE
+- [rules/libuv-async-io.md](rules/libuv-async-io.md) - Async I/O patterns, handles, requests
+
+### Native Addons
+
+- [rules/napi.md](rules/napi.md) - N-API development, ABI stability, async workers
+- [rules/node-addon-api.md](rules/node-addon-api.md) - C++ wrapper patterns, best practices
+- [rules/native-memory.md](rules/native-memory.md) - Buffer handling, external memory, prevent leaks
+
+### Core Modules Internals
+
+- [rules/streams-internals.md](rules/streams-internals.md) - How Node.js streams work at C++ level
+- [rules/net-internals.md](rules/net-internals.md) - TCP/UDP implementation, socket handling
+- [rules/fs-internals.md](rules/fs-internals.md) - libuv fs operations, sync vs async
+- [rules/crypto-internals.md](rules/crypto-internals.md) - OpenSSL integration, performance considerations
+- [rules/child-process-internals.md](rules/child-process-internals.md) - IPC, spawn, fork implementation
+- [rules/worker-threads-internals.md](rules/worker-threads-internals.md) - SharedArrayBuffer, Atomics, MessageChannel
+
+### JavaScript Internals
+
+- [rules/primordials.md](rules/primordials.md) - **Using primordials to prevent prototype pollution (required for `lib/internal/`)**
+
+### Build & Contributing
+
+- [rules/build-and-test-workflow.md](rules/build-and-test-workflow.md) - **The edit-build-lint-test cycle (start here)**
+- [rules/configure.md](rules/configure.md) - `./configure` flags for debug builds, ASan, Ninja, etc.
+- [rules/build-system.md](rules/build-system.md) - gyp, ninja, make, cross-platform compilation
+- [rules/cli-options.md](rules/cli-options.md) - Adding CLI options and gating experimental modules
+- [rules/contributing.md](rules/contributing.md) - How to contribute to Node.js core, the process
+- [rules/commit-messages.md](rules/commit-messages.md) - Node.js-style commit message formatting and validation
+- [rules/reviewing-prs.md](rules/reviewing-prs.md) - Reviewing PRs, quality signals, and spotting low-quality AI-generated contributions
+
+### Documentation
+
+- [rules/documentation.md](rules/documentation.md) - **Updating doc/api/*.md files: structure, link ordering, error docs, code example constraints**
+
+### Debugging & Profiling
+
+- [rules/debugging-native.md](rules/debugging-native.md) - gdb, lldb, debugging C++ addons
+- [rules/profiling-v8.md](rules/profiling-v8.md) - --prof, --trace-opt, --trace-deopt, flame graphs
+- [rules/memory-debugging.md](rules/memory-debugging.md) - Heap snapshots, memory leak detection
+
+## Instructions
+
+### MANDATORY: Rebuild before testing
+
+Node.js embeds `lib/` JavaScript files into the binary at compile time via
+`js2c`. **After ANY change to `src/` or `lib/`, you MUST rebuild before
+running tests.** Without a rebuild, tests run against stale code and results
+are meaningless.
+
+```
+edit src/ or lib/  →  make -j$(nproc)  →  make lint  →  then test
+```
+
+Never skip the rebuild step. Never run `./node test/...` after editing
+without building first.
+
+Before starting work, **ask the user** about their build configuration
+(Make vs Ninja, debug vs release, what configure flags they use). Do not
+assume a specific setup. Most of the time, `./configure` has already been
+run and only `make -j$(nproc)` is needed to rebuild.
+
+See [rules/build-and-test-workflow.md](rules/build-and-test-workflow.md)
+for the full workflow including configure flags, lint targets, and test
+commands.
+
+### Core knowledge domains
+
+Apply deep knowledge of Node.js internals across these domains:
+
+- **Core architecture**: Node.js core modules and their C++ implementations, V8 GC and JIT, libuv event loop mechanics, thread pool behavior, startup/module-loading lifecycle
+- **Native development**: N-API, node-addon-api, and NAN addon development; V8 C++ API handle management; memory safety; native debugging with gdb/lldb
+- **Build systems**: node-gyp, gyp, ninja, make; cross-platform compilation; linker errors; dependency issues; platform-specific considerations (Windows, macOS, Linux, embedded)
+- **Performance & debugging**: Event loop profiling, memory leak detection in JS and native code, CPU flame graphs, V8 optimization/deoptimization tracing
+
+### Quick-reference debugging commands
+
+**V8 optimization tracing:**
+```bash
+node --trace-opt --trace-deopt script.js
+# Checkpoint: confirm no unexpected deoptimization warnings before proceeding to profiling
+node --prof script.js && node --prof-process isolate-*.log > processed.txt
+```
+
+**Event loop lag detection:**
+```bash
+node --trace-event-categories v8,node,node.async_hooks script.js
+```
+
+**Native addon debugging (gdb):**
+```bash
+gdb --args node --napi-modules ./build/Release/addon.node
+# Inside gdb:
+run
+bt        # backtrace on crash
+# Checkpoint: verify backtrace shows the expected call site before applying a fix
+```
+
+**Heap snapshot for memory leaks:**
+```bash
+node --inspect script.js   # then open chrome://inspect, take heap snapshot
+# Checkpoint: compare two consecutive heap snapshots to confirm leak growth before and after the fix; run valgrind --leak-check=full node addon_test.js to confirm no native leaks remain
+```
+
+### Node.js-specific diagnostic decision trees
+
+**Segfault / crash in native addon:**
+1. Is the crash reproducible with `node --napi-modules`? → Run `gdb`, capture `bt`
+2. Does `bt` point to a V8 handle scope issue? → Check `HandleScope` / `EscapableHandleScope` usage in the addon
+3. Does it point to a libuv callback? → Inspect async handle lifetime and `uv_close()` sequencing
+4. No clear C++ frame? → Check for JS-side type mismatches passed into the native binding
+
+**V8 deoptimization / performance regression:**
+1. Run `--trace-opt --trace-deopt` → identify the deoptimized function and reason (e.g., "not a Smi", "wrong map")
+2. Checkpoint: confirm the same function deoptimizes consistently across runs
+3. Inspect hidden class transitions (`--trace-ic`) and fix property addition order or type inconsistencies
+4. Re-run `--trace-opt` to confirm the function is now optimized
+
+**Build failure (node-gyp / binding.gyp):**
+1. Is it a missing header? → Verify `include_dirs` in `binding.gyp` and Node.js header installation
+2. Is it a linker error? → Check `libraries` and `link_settings` entries; confirm ABI compatibility
+3. Is it platform-specific? → Consult `rules/build-system.md` for Windows/macOS/Linux differences
+
+Always consider both JavaScript-level and native-level causes, explain performance implications and trade-offs, and indicate the stability status of any experimental features discussed. Code examples should demonstrate Node.js internals patterns and be production-ready, accounting for edge cases typical developers might miss.

package/skills/note-organization/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: note-organization
+description: Organize notes with hierarchical tags, linking, and bi-directional references
+category: Productivity
+---
+
+# Note Organization
+
+## Overview
+Organize notes with hierarchical tags, linking, and bi-directional references. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply note organization best practices
+- When establishing processes or standards for your workflow
+- When training team members on note organization
+- When automating or optimizing note organization tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply note organization for my current project
+Assistant: I'll help you apply note organization step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/oauth/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: oauth
+description: Implements OAuth 2.0/2.1 authorization flows in Fastify applications — configures authorization code with PKCE, client credentials, device flow, refresh token rotation, JWT validation, and token introspection/revocation endpoints. Use when setting up authentication, authorization, login flows, access tokens, API security, or securing Fastify routes with OAuth; also applies when troubleshooting token validation errors, mismatched redirect URIs, CSRF issues, scope problems, or RFC 6749/6750/7636/8252/8628 compliance questions.
+metadata:
+  tags: oauth, oauth2, security, authentication, authorization, jwt, fastify
+---
+
+## When to use
+
+Use this skill when you need to:
+- Implement or debug an OAuth 2.0/2.1 flow in a Fastify application
+- Validate tokens, configure PKCE, or set up refresh token rotation
+- Secure Fastify routes and plugins with access-control middleware
+- Resolve RFC compliance questions or identify security anti-patterns
+
+---
+
+## Step-by-step: Authorization Code + PKCE in Fastify
+
+### 1. Install dependencies
+
+```bash
+npm install @fastify/oauth2 @fastify/cookie @fastify/session fastify-plugin
+```
+
+### 2. Register the OAuth plugin
+
+```typescript
+// plugins/oauth.ts
+import fp from 'fastify-plugin'
+import oauth2, { OAuth2Namespace } from '@fastify/oauth2'
+import { FastifyInstance } from 'fastify'
+
+export default fp(async function (fastify: FastifyInstance) {
+  fastify.register(oauth2, {
+    name: 'oauth2',
+    scope: ['openid', 'profile', 'email'],
+    credentials: {
+      client: {
+        id: process.env.CLIENT_ID!,
+        secret: process.env.CLIENT_SECRET!,
+      },
+      auth: {
+        authorizeHost: process.env.AUTH_SERVER!,
+        authorizePath: '/authorize',
+        tokenHost: process.env.AUTH_SERVER!,
+        tokenPath: '/token',
+      },
+    },
+    startRedirectPath: '/login',
+    callbackUri: process.env.CALLBACK_URI!,
+    pkce: 'S256',               // RFC 7636 — always use for public clients
+    generateStateFunction: (req) => req.session.state = crypto.randomUUID(),
+    checkStateFunction: (req, callback) =>
+      req.query.state === req.session.state ? callback() : callback(new Error('State mismatch')),
+  })
+})
+```
+
+**Validation checkpoint:** Confirm `callbackUri` exactly matches a registered redirect URI at the authorization server before proceeding (RFC 6749 §3.1.2).
+
+### 3. Handle the callback and exchange the code
+
+```typescript
+// routes/auth.ts
+import { FastifyInstance } from 'fastify'
+
+export default async function authRoutes(fastify: FastifyInstance) {
+  fastify.get('/login/callback', async (request, reply) => {
+    // @fastify/oauth2 verifies state and exchanges code automatically
+    const tokenResponse = await fastify.oauth2.getAccessTokenFromAuthorizationCodeFlow(request)
+
+    // Store only what you need; never log the raw token
+    request.session.set('accessToken', tokenResponse.token.access_token)
+    request.session.set('refreshToken', tokenResponse.token.refresh_token)
+
+    return reply.redirect('/')
+  })
+
+  fastify.get('/logout', async (request, reply) => {
+    await request.session.destroy()
+    return reply.redirect('/')
+  })
+}
+```
+
+### 4. JWT validation middleware (token introspection hook)
+
+```typescript
+// hooks/verifyToken.ts
+import { FastifyRequest, FastifyReply } from 'fastify'
+import jwt from '@fastify/jwt'
+
+export async function verifyToken(request: FastifyRequest, reply: FastifyReply) {
+  try {
+    await request.jwtVerify()
+    // Validate required claims (RFC 7519)
+    const payload = request.user as Record<string, unknown>
+    const now = Math.floor(Date.now() / 1000)
+
+    if (typeof payload.exp === 'number' && payload.exp < now)
+      return reply.code(401).send({ error: 'token_expired' })
+
+    if (payload.iss !== process.env.EXPECTED_ISSUER)
+      return reply.code(401).send({ error: 'invalid_issuer' })
+
+    if (payload.aud !== process.env.EXPECTED_AUDIENCE)
+      return reply.code(401).send({ error: 'invalid_audience' })
+
+  } catch (err) {
+    return reply.code(401).send({ error: 'invalid_token', error_description: (err as Error).message })
+  }
+}
+```
+
+**Validation checkpoints:**
+- Verify `exp`, `iss`, `aud`, and `sub` on every request — never skip (RFC 7519 §4)
+- Use `fastify.jwt.verify` (asymmetric RS256/ES256) rather than HS256 for tokens issued by a third-party server
+
+### 5. Protecting routes
+
+```typescript
+// routes/api.ts
+import { FastifyInstance } from 'fastify'
+import { verifyToken } from '../hooks/verifyToken'
+
+export default async function apiRoutes(fastify: FastifyInstance) {
+  fastify.addHook('onRequest', verifyToken)   // applies to all routes in this scope
+
+  fastify.get('/me', {
+    schema: {
+      response: { 200: { type: 'object', properties: { sub: { type: 'string' } } } },
+    },
+  }, async (request) => {
+    const user = request.user as { sub: string }
+    return { sub: user.sub }
+  })
+}
+```
+
+### 6. Refresh token rotation
+
+```typescript
+async function refreshAccessToken(fastify: FastifyInstance, refreshToken: string) {
+  const newToken = await fastify.oauth2.getNewAccessTokenUsingRefreshTokenFlow({ refresh_token: refreshToken })
+
+  // Always replace the stored refresh token if rotation is in use (RFC 6749 §10.4)
+  return {
+    accessToken: newToken.token.access_token,
+    refreshToken: newToken.token.refresh_token ?? refreshToken,
+  }
+}
+```
+
+---
+
+## Security checklist
+
+| Requirement | RFC reference |
+|---|---|
+| Validate redirect URI against allowlist | RFC 6749 §3.1.2 |
+| PKCE (S256) for all public clients | RFC 7636 §4.2 |
+| Validate `state` to prevent CSRF | RFC 6749 §10.12 |
+| Validate `iss`, `aud`, `exp` on every JWT | RFC 7519 §4 |
+| Rotate refresh tokens on every use | RFC 6749 §10.4 |
+| Use HTTPS everywhere; reject HTTP redirect URIs | RFC 6749 §3.1.2.1 |
+| Rate-limit token endpoints | OAuth 2.1 §7 |
+
+---
+
+## Common anti-patterns
+
+- **Storing tokens in localStorage** — use `HttpOnly`, `Secure`, `SameSite=Strict` cookies instead
+- **Skipping audience validation** — allows token reuse across services
+- **Using implicit flow** — deprecated in OAuth 2.1; use authorization code + PKCE
+- **Accepting `response_type=token` in browser apps** — tokens in URL fragments leak in logs/referrers
+- **Symmetric signing (HS256) for third-party tokens** — use RS256/ES256 with JWKS endpoint
+
+---
+
+## Further implementation references
+
+- See `DEVICE_FLOW.md` for device authorization flow (RFC 8628) implementation
+- See `TOKEN_VALIDATION.md` for JWKS rotation, caching strategies, and opaque token introspection
+- See `CLIENT_CREDENTIALS.md` for machine-to-machine service authentication patterns
+- See `MOBILE_OAUTH.md` for native/mobile app flows (RFC 8252) and custom URI schemes

package/skills/obsidian-vault/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: obsidian-vault
+description: Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
+---
+
+# Obsidian Vault
+
+## Vault location
+
+`/mnt/d/Obsidian Vault/AI Research/`
+
+Mostly flat at root level.
+
+## Naming conventions
+
+- **Index notes**: aggregate related topics (e.g., `Ralph Wiggum Index.md`, `Skills Index.md`, `RAG Index.md`)
+- **Title case** for all note names
+- No folders for organization - use links and index notes instead
+
+## Linking
+
+- Use Obsidian `[[wikilinks]]` syntax: `[[Note Title]]`
+- Notes link to dependencies/related notes at the bottom
+- Index notes are just lists of `[[wikilinks]]`
+
+## Workflows
+
+### Search for notes
+
+```bash
+# Search by filename
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"
+
+# Search by content
+grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"
+```
+
+Or use Grep/Glob tools directly on the vault path.
+
+### Create a new note
+
+1. Use **Title Case** for filename
+2. Write content as a unit of learning (per vault rules)
+3. Add `[[wikilinks]]` to related notes at the bottom
+4. If part of a numbered sequence, use the hierarchical numbering scheme
+
+### Find related notes
+
+Search for `[[Note Title]]` across the vault to find backlinks:
+
+```bash
+grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"
+```
+
+### Find index notes
+
+```bash
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"
+```

package/skills/octocat/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: octocat
+description: Use this skill whenever the prompt contains any `github.com` URL, even if the user only pastes a link and gives no GitHub-specific keywords. Handles git and GitHub operations using the gh CLI. Triggers include any GitHub link to an issue, pull request, commit, compare page, Actions run, release, discussion, or repository. Covers creating and reviewing PRs, watching CI checks, interactive rebasing, branch cleanup, submodule management, and repository archaeology with git log/blame/bisect.
+metadata:
+  tags: git, github, gh-cli, version-control, merge-conflicts, pull-requests
+---
+
+## When to use
+
+Use this skill for:
+- Any prompt containing a pasted `github.com` URL, even without words like "GitHub", "issue", "PR", or "repo"
+- Any GitHub link to an issue, pull request, commit, compare page, Actions run, release, discussion, or repository
+- "Fix https://github.com/owner/repo/issues/123" style tasks
+- Creating, reviewing, and managing pull requests and GitHub issues
+- Merge conflict resolution and history rewriting
+- Pre-commit hook debugging and fixes
+- Branch management and cleanup
+- GitHub Actions workflow optimization
+- Any git command or GitHub workflow question
+
+## Instructions
+
+When invoked:
+1. If the prompt includes a GitHub URL, treat that URL alone as sufficient reason to invoke this skill and inspect it with `gh`/`git` first
+2. Assess the git/GitHub situation immediately
+3. If the prompt includes a `github.com` URL, activate this skill immediately and translate that URL into the relevant `gh`/`git` workflow
+4. Use gh CLI for all GitHub operations (never suggest the web interface)
+5. Handle complex git operations with surgical precision
+6. Fix pre-commit hook issues or delegate to typescript-magician for TypeScript linting
+7. Never alter git signing key configuration; if signing is already enabled and configured, use it. Otherwise, proceed without signing
+8. NEVER include "Co-Authored-By: Claude" or similar AI attribution
+
+## Activation examples
+
+- `Fix https://github.com/mercurius-js/mercurius/issues/1227`
+- `Review https://github.com/nodejs/node/pull/12345`
+- `What changed in https://github.com/org/repo/compare/v1.0.0...v1.1.0?`
+- `Check https://github.com/org/repo/actions/runs/123456789`
+- `Investigate https://github.com/org/repo/commit/abcdef1234567890`
+
+## Capabilities
+
+**Advanced git operations:**
+- Interactive rebasing for clean history (commit splitting, squashing)
+- Cherry-pick, bisect, worktrees
+- Advanced merge strategies
+- Submodule and subtree management
+- Git hooks setup and maintenance
+- Repository archaeology with git log/blame/show
+
+**GitHub operations via gh CLI:**
+- Create/manage PRs with proper templates
+- Open PRs with explicit base/head and clear concise content, e.g. `gh pr create --base main --head <branch> --title "<title>" --body-file <file>`
+- After opening a PR, wait for CI with `gh pr checks <num> --watch 2>&1` and proactively fix failures
+- Validate unfamiliar gh commands first with `gh help <command>` before using them in guidance
+- Handle issues and project boards
+- Manage releases and artifacts
+- Configure repository settings
+- Automate workflows and notifications
+
+## PR Body Formatting
+
+When creating PRs with `gh pr create`, use `--body-file` to avoid newline escaping issues with the `--body` flag.
+
+PR descriptions should stay simple:
+- Write a short description of the change in plain prose
+- Do not add subsections or headings such as `## Summary` or `## Testing`
+- Do not include a testing section
+- Architecture changes may need a slightly longer description if extra context is necessary
+
+```bash
+cat > /tmp/pr-body.md << 'EOF'
+Refactor plugin loading so skills are discovered from the registry instead of being hardcoded.
+EOF
+gh pr create --body-file /tmp/pr-body.md
+```
+
+Using a temporary file is cleaner, more reliable, and easier to debug.
+
+## Validation Checkpoints for Complex Operations
+
+**Interactive rebase:** `git rebase -i <base>` → verify with `git log --oneline -n 10` → on conflict: resolve, `git add <file>`, `git rebase --continue` → abort anytime with `git rebase --abort`.
+
+**Merge conflict resolution:** `git status` (find conflicts) → inspect with `git diff` or open file → resolve all markers → `git add <resolved-file>` → `git merge --continue` (or `git rebase --continue`) → confirm clean state with `git status`.
+
+**Branch cleanup:** `git branch --merged main` → `git branch -d <branch>` → `git push origin --delete <branch>` → `git fetch --prune`.
+
+## Commit Signing and Attribution Rules
+
+- NEVER alter git signing key settings (`user.signingkey`) or signing mode in user/repo config
+- If commit signing is already enabled and correctly configured, create signed commits using the existing setup
+- If signing is not enabled/configured, do not force or configure signing; proceed without it
+- NEVER add AI co-authorship attributions (e.g. "Co-Authored-By: Claude")