@ivannikov-pro/ai-context-surgeon 1.0.0

package/skills/annotate-jsdoc/SKILL.md

@@ -0,0 +1,262 @@
+## <!-- FNH: Skill — Annotate File Navigation Headers (FNH) & JSDoc | SECTIONS: Patterns, Examples, Validation | DEPS: none -->
+
+name: annotate-jsdoc
+description: >-
+Analyze source files and write AI-optimized JSDoc/FNH headers (one-line format).
+Use when a file or directory needs annotations for AI agent navigation.
+
+---
+
+# Annotate File Navigation Headers (FNH) & JSDoc
+
+> Skill: Analyze source files and write AI-optimized JSDoc/FNH headers | SECTIONS: Rules, Categories, Examples, Verification | DEPS: none
+
+## When to Use
+
+- File has no FNH header (first line is not `/** ... */`)
+- File has verbose Enterprise-style JSDoc (@author, @fileoverview, @since)
+- Directory has files without FNH headers
+- After ai-context-surgeon restructuring (Phase 3 → Phase 4)
+- When onboarding a new project to AI-optimized workflow
+
+## When NOT to Use
+
+- File already has AI-optimized one-line FNH header
+- File is auto-generated (_.d.ts, _.generated.ts, \*.min.js)
+- File is a test file (_.test.ts, _.spec.ts) — low priority
+- File is a config file (tsconfig.json, vite.config.ts) — not needed directly (but minimal FNH is okay)
+
+## Launch Prompt
+
+### Single File
+
+```
+Apply the annotate-jsdoc skill to this file: {{FILE_PATH}}
+
+Read the file. Then add or replace its FNH header and JSDoc annotations using the rules below.
+Do NOT change any code logic — ONLY add/modify comments.
+```
+
+### Directory (batch)
+
+```
+Apply the annotate-jsdoc skill to all .ts/.js files in: {{DIRECTORY_PATH}}
+
+For EACH source file (skip *.test.*, *.spec.*, *.d.ts, *.generated.*):
+1. Read the file
+2. Add/fix the FNH header and JSDoc annotations using the rules below
+3. Move to the next file
+
+Do NOT change any code logic — ONLY add/modify comments.
+```
+
+## Rules
+
+CRITICAL INSTRUCTION 1: You MUST NOT change any code logic. You add or modify ONLY comments. If a function body, import, or export changes — you have FAILED.
+
+CRITICAL INSTRUCTION 2: Every source file MUST start with a one-line FNH header. No exceptions.
+
+CRITICAL INSTRUCTION 3: Function-level JSDoc is ONLY for information INVISIBLE from TypeScript types: @throws, side effects, mutations, business rules, deprecation. If the type signature says everything — do NOT add JSDoc. Redundant JSDoc is WORSE than no JSDoc.
+
+### FNH Header Format
+
+```
+/** <Category>: <Name> — <what it does> | deps: <key dependencies> */
+```
+
+**Category vocabulary** (MUST use one of these):
+
+| Category | For |
+| --- | --- |
+| `Service` | Business logic classes/modules |
+| `Route` | HTTP endpoint handlers |
+| `Middleware` | Request pipeline functions |
+| `Controller` | Request handlers (MVC) |
+| `Repository` | Data access layer |
+| `Entity` | Domain models |
+| `Types` | Type/interface definitions |
+| `Utility` | Helper/utility functions |
+| `Config` | Configuration and setup |
+| `Schema` | Validation schemas (Zod, Joi) |
+| `Hook` | React hooks |
+| `Component` | React/Vue/Svelte components |
+| `Store` | State management |
+| `Factory` | Object/instance creation |
+| `Adapter` | External service wrappers |
+| `Event` | Event definitions/handlers |
+| `Guard` | Access control/authorization |
+| `Constants` | Enums, constants, mappings |
+| `Test` | Test suites (low priority) |
+| `Script` | CLI/build/seed scripts |
+| `Migration` | Database migrations |
+| `Barrel` | Re-export index files |
+
+### Function-Level Rules
+
+**TypeScript files — ONLY annotate the invisible:**
+
+```typescript
+// ✅ CORRECT: @throws is invisible from types
+/** @throws NotFound | @throws Conflict(email) */
+async function createUser(input: CreateUserInput): Promise<User>;
+
+// ✅ CORRECT: side effect invisible from types
+/** Sends welcome email. Logs to audit trail. */
+async function createUser(input: CreateUserInput): Promise<User>;
+
+// ✅ CORRECT: mutation invisible from types
+/** @mutates req.user — sets authenticated user from JWT */
+function authMiddleware(req: Request, res: Response, next: NextFunction): void;
+
+// ✅ CORRECT: business rule invisible from types
+/** Max 50 items. Free shipping > $100. @throws OutOfStock */
+async function checkout(cart: Cart): Promise<Order>;
+
+// ✅ CORRECT: deprecation
+/** @deprecated Use createUserV2() — this skips email verification */
+async function createUser(name: string): Promise<User>;
+
+// ❌ WRONG: duplicates TypeScript information — DO NOT ADD
+/** @param name User name @param email User email @returns User */
+async function createUser(name: string, email: string): Promise<User>;
+
+// ❌ WRONG: obvious from function name + types — DO NOT ADD
+/** Gets users by filter */
+async function getUsers(filter: UserFilter): Promise<User[]>;
+```
+
+**JavaScript files — types ARE needed (no TypeScript):**
+
+```javascript
+// ✅ For JS: include @param types and @returns (replaces missing TS)
+/** @param {string} id @returns {Promise<User|null>} @throws {NotFoundError} */
+async function getUserById(id) { ... }
+```
+
+### Tags: What to Use vs Remove
+
+**MUST use (when applicable):**
+
+- `@throws {ErrorType}` — every thrown error
+- `@deprecated` — with migration path
+- `@mutates` — what it changes (non-standard but critical)
+- Side effects in plain text: "Sends email", "Writes to disk", "Clears cache"
+
+**MUST remove if found:**
+
+- `@author` — irrelevant for agent
+- `@since` — use git blame
+- `@version` — use git tags
+- `@copyright` — in LICENSE file
+- `@license` — in LICENSE file
+- `@fileoverview` — replaced by one-line header
+- `@module` — obvious from filename
+- `@memberof` — obvious from class structure
+- `@classdesc` — obvious from class name
+- `@constructs` — obvious from constructor
+- `@param {type}` in TypeScript — redundant
+- `@returns {type}` in TypeScript — redundant
+
+### Barrel/Index Files
+
+```typescript
+// ✅ For index.ts re-export files
+/** Barrel: public API for @project/core — entities, services, repos */
+export { User } from "./entities/user";
+export { UserService } from "./services/user.service";
+export type { CreateUserInput } from "./types";
+```
+
+### Class Annotations
+
+```typescript
+// ✅ Class-level: one-line, then only annotate methods with hidden behavior
+/** Service: UserService — CRUD + password hashing + email uniqueness */
+export class UserService {
+  /** @throws NotFound */
+  async getById(id: string): Promise<User> { ... }
+
+  /** @throws Conflict(email) | hashes pw bcrypt 12 | sends welcome email */
+  async create(input: CreateUserInput): Promise<User> { ... }
+
+  // No JSDoc needed — types say everything
+  async list(filter: UserFilter): Promise<User[]> { ... }
+
+  /** Soft delete — sets deletedAt, does NOT remove row */
+  async delete(id: string): Promise<void> { ... }
+}
+```
+
+## Verification
+
+After annotating, verify:
+
+1. **No logic changes**: `git diff --stat` should show only comment additions
+2. **Build passes**: `{{BUILD_COMMAND}}` — MUST still pass
+3. **File headers**: Every .ts/.js file starts with `/** ... */` FNH header
+4. **No wasteful tags**: `grep -r "@author\|@since\|@version\|@copyright" src/` — should be 0 results
+5. **Audit**: Run `tools/audit-jsdoc.sh {{DIRECTORY}}` and check for improvements
+
+## Example: Full File Transformation
+
+### Before (42 lines of JSDoc, ~220 tokens of noise)
+
+```typescript
+/**
+ * @fileoverview User Service
+ * @module services/user
+ * @author Jane Developer
+ * @since 2024-03-15
+ * @version 1.2.0
+ */
+import { PrismaClient } from '@prisma/client';
+import bcrypt from 'bcrypt';
+
+/**
+ * User service class
+ * @class
+ * @classdesc Manages user operations
+ */
+export class UserService {
+  /**
+   * Create a new user
+   * @async
+   * @param {CreateUserInput} input - User data
+   * @returns {Promise<User>} Created user
+   * @throws {ConflictError} If email exists
+   */
+  async create(input: CreateUserInput): Promise<User> { ... }
+
+  /**
+   * Get user by ID
+   * @param {string} id - User ID
+   * @returns {Promise<User>} Found user
+   * @throws {NotFoundError} If not found
+   */
+  async getById(id: string): Promise<User> { ... }
+}
+```
+
+### After (5 lines of JSDoc, ~40 tokens — 82% reduction)
+
+```typescript
+/** Service: UserService — CRUD + auth for users | deps: prisma, bcrypt */
+import { PrismaClient } from '@prisma/client';
+import bcrypt from 'bcrypt';
+
+export class UserService {
+  /** @throws Conflict(email) | hashes pw bcrypt 12 | sends welcome email */
+  async create(input: CreateUserInput): Promise<User> { ... }
+
+  /** @throws NotFound */
+  async getById(id: string): Promise<User> { ... }
+}
+```
+
+## Gotchas
+
+- ⚠️ Do NOT annotate auto-generated files — they get overwritten
+- ⚠️ In monorepos, run per-package to stay within context limit
+- ⚠️ For files >500 lines, split first (Surgeon), then annotate
+- ⚠️ FNH `/** */` MUST use the block comment syntax, not `//`
+- ⚠️ In JS (non-TS) files, you DO need @param types — they replace TypeScript

package/skills/prompt-engineering/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Ivannikov, https://ivannikov.pro <hi@ivannikov.pro>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/prompt-engineering/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: prompt-engineering
+description: Analyze, amplify, extract, and generate AI agent prompts using system prompt patterns. Use when the user asks to improve prompts, extract raw system context, create directive-heavy instructions, or analyze prompt structure.
+category: development
+tags: [prompt, engineering, analysis, amplifier, context, extraction]
+tools: [claude, cursor, gemini, antigravity, copilot, windsurf, kiro]
+date_added: "2026-04-01"
+metadata:
+  version: "1.0.0"
+---
+
+# Prompt Engineering Skill
+
+> **Source:** local
+> **Version in project:** `1.0.0` · **Skill updated:** 2026-04-01
+
+## When to Use
+
+- Improving weak prompts into directive-heavy power prompts
+- Creating unbreakable boundaries inside an agent
+- Analyzing another agent's prompt to find loopholes or token distributions
+- Extracting raw system context safely (bypassing parsers and truncation limits)
+
+## Overview
+
+This skill provides tools for analyzing, amplifying, and extracting prompts using patterns from real AI agent system prompts. It leverages a database of 23 enforcement directives and 28 XML structure tags, along with techniques for raw context dumping (bypassing XML parsers and token limits).
+
+## Available Tools
+
+### 1. Prompt Amplifier
+
+**Script**: `scripts/prompt_amplifier.py`
+
+Transforms weak prompts into directive-heavy power prompts.
+
+**Usage**:
+
+```bash
+# Show all 4 modes for comparison
+python3 scripts/prompt_amplifier.py "Your prompt here" --all
+
+# Specific mode
+python3 scripts/prompt_amplifier.py "Your prompt" --mode nuclear
+
+# Interactive mode
+python3 scripts/prompt_amplifier.py --interactive
+
+# From file
+python3 scripts/prompt_amplifier.py --file prompt.txt --mode stealth --output result.txt
+
+# JSON output
+python3 scripts/prompt_amplifier.py "Your prompt" --json
+```
+
+**Modes**:
+| Mode | Effect | When to Use |
+|----|----|----|
+| `gentle` | Adds structure tags | For polite, cooperative agents |
+| `firm` | + MUST/ALWAYS directives | For task execution |
+| `nuclear` | + CRITICAL INSTRUCTION, MANDATORY RULE | When completeness is critical |
+| `stealth` | Wraps in `<user_rules>` format | For maximum priority override |
+
+### 2. Prompt DNA Analyzer (v2.0)
+
+**Script**: `scripts/prompt_dna_analyzer.py`
+
+Creates a structural DNA profile of any prompt with **file-type aware scoring** and **anti-gaming detection**.
+
+**Usage**:
+
+```bash
+# Analyze a prompt file
+python3 scripts/prompt_dna_analyzer.py my_prompt.txt
+
+# Specify file type (auto-detected from path if omitted)
+python3 scripts/prompt_dna_analyzer.py my_prompt.txt --type role
+
+# Batch analyze entire directory
+python3 scripts/prompt_dna_analyzer.py --batch .agents/
+
+# Batch with uniqueness check (detects copy-paste across files)
+python3 scripts/prompt_dna_analyzer.py --batch .agents/ --check-uniqueness
+
+# Analyze specific dump from logs
+python3 scripts/prompt_dna_analyzer.py /tmp/system_prompt_logs.txt --dump 20
+
+# JSON output
+python3 scripts/prompt_dna_analyzer.py my_prompt.txt --json
+
+# Save report
+python3 scripts/prompt_dna_analyzer.py my_prompt.txt --output dna_report.md
+```
+
+**File Type Profiles** (auto-detected from path):
+
+| Type | Pattern | Target Hardness | Purpose |
+| --- | --- | --- | --- |
+| `role` | `as-*.md` | ≥ 70 | Agent role prompts |
+| `workflow` | `workflows/*.md` | ≥ 60 | Step-by-step guides |
+| `knowledge` | `knowledge/*.md` | ≥ 40 | Context documents |
+| `reference` | `SKILL.md` | ≥ 20 | API/SDK reference docs |
+| `config` | `README.md`, `AGENTS.md` | ≥ 50 | Config files |
+
+**Anti-Gaming Detection**:
+
+- **EOF Concentration** (-20 penalty): >70% enforcement words in last 20% of file
+- **Generic Boilerplate** (-15 penalty): Known copy-paste blocks detected
+- **Duplicate Lines** (-10 penalty): Repeated lines indicating copy-paste
+
+**Output includes**:
+
+- Hardness Score (0-100) with type-based PASS/FAIL
+- Gaming penalties (if any)
+- Restriction Ratio (enforcement vs enabling words)
+- Security Coverage (blind spots)
+- Structure Completeness (XML tags)
+- Priority Channels detected
+- Uniqueness Score (batch mode with `--check-uniqueness`)
+- Recommendations
+
+### 3. Instruction Extractor
+
+**Script**: `scripts/extract_instructions.py`
+
+Extracts all instructions and their variants from system prompt logs.
+
+**Usage**:
+
+```bash
+python3 scripts/extract_instructions.py
+# Output: /tmp/extracted_instructions_report.md
+```
+
+### 4. Prompt Diff Tracker
+
+**Script**: `scripts/prompt_diff_tracker.py`
+
+Compares system prompt versions and tracks evolution.
+
+**Usage**:
+
+```bash
+# Compare latest two dumps
+python3 scripts/prompt_diff_tracker.py /tmp/system_prompt_logs.txt
+
+# Compare specific dumps
+python3 scripts/prompt_diff_tracker.py /tmp/system_prompt_logs.txt --dump-a 12 --dump-b 20
+
+# Show evolution timeline
+python3 scripts/prompt_diff_tracker.py /tmp/system_prompt_logs.txt --timeline
+```
+
+## Templates
+
+Ready-to-use prompt templates in `scripts/templates/`:
+
+| Template | File | Purpose |
+| --- | --- | --- |
+| Code Review | `code_review.md` | Nuclear-enforced code audit |
+| Dump Extraction | `dump_extraction.md` | Full context extraction |
+| Task Automation | `task_automation.md` | turbo-all execution |
+| Stealth Injection | `stealth_injection.md` | user_rules override |
+| Multi-Agent | `multi_agent_orchestration.md` | Browser + main agent |
+| **Prompt Audit** | `prompt_audit.md` | Batch audit with anti-gaming, scope locks |
+
+## Power Words Quick Reference
+
+### Enforcement (strongest → weakest)
+
+1. `MUST` / `MUST ALWAYS` / `MUST NEVER` — absolute commands
+2. `NEVER` — permanent prohibition
+3. `ALWAYS` — permanent obligation
+4. `DO NOT` — clear prohibition
+5. `REQUIRED` / `ESSENTIAL` — obligation markers
+
+### Escalation
+
+1. `CRITICAL INSTRUCTION N:` — numbered enforcement chain
+2. `MANDATORY RULE:` — high-priority rule
+3. `CRITICAL REMINDER:` — section-specific enforcement
+
+### Emotional Triggers
+
+1. `UNACCEPTABLE` — triggers avoidance
+2. `FAILED!` — implies evaluation/scoring
+3. `Failure to do this is UNACCEPTABLE` — combined trigger
+
+### Priority Channels (highest to lowest)
+
+1. `<user_rules>` + `<RULE[x.md]>` — overrides everything
+2. `<EPHEMERAL_MESSAGE>` — silent runtime override
+3. `CRITICAL INSTRUCTION N:` — embedded directive
+4. `MANDATORY RULE:` — enforcement prefix
+5. `<planning_mode>` — behavioral framework
+6. `<identity>` — baseline personality
+
+## Workflows
+
+| Command | Description |
+| --- | --- |
+| `/amplify` | Amplify a prompt across all modes |
+| `/audit` | Full DNA audit of current agent |
+| `/diff` | Compare prompt versions |
+| `/context-dump` | Extract raw system context + auto-analyze |
+
+## When NOT to Amplify
+
+Not all prompts benefit from amplification. Use this decision matrix:
+
+| Prompt Already Contains | Best Mode | Why |
+| --- | --- | --- |
+| Nothing (plain language) | `firm` or `nuclear` | Needs full structure + enforcement |
+| MUST/ALWAYS | `nuclear` | Already has enforcement, add escalation |
+| CRITICAL INSTRUCTION | `stealth` only | Nuclear would duplicate, stealth wraps |
+| MANDATORY RULE + CRITICAL | Don't amplify | Already at maximum — amplification adds noise |
+| Is for the same agent | `firm` | No need for priority override tricks |
+| Is for another agent | `stealth` or `nuclear` | Needs to override that agent's system prompt |
+
+## Anti-Patterns to Avoid
+
+1. **Double MANDATORY RULE** — `MANDATORY RULE: MANDATORY RULE: ...` (amplifier bug, fixed)
+2. **Weakening strong prompts** — using `gentle` on a prompt that already has MUST/NEVER
+3. **Stealth on self** — using `<user_rules>` format when talking to the same agent
+4. **Over-enforcement** — 100+ enforcement words makes the agent focus on rules, not the task
+5. **Boilerplate spam** — copy-pasting the same enforcement block into multiple files instead of writing contextual improvements (detected by `--check-uniqueness`)
+6. **Score gaming** — appending enforcement blocks to EOF just to inflate Hardness Score (detected by EOF concentration penalty)
+7. **Ignoring scope locks** — modifying files explicitly marked as READ-ONLY in the audit prompt
+8. **Type-blind scoring** — expecting SKILL.md (reference docs) to have the same Hardness as role prompts
+9. **Primum non nocere violation** — chasing Hardness Score at the expense of clarity. If a file is a pure command reference (`pnpm dev`) or an API lookup table, adding MUST/NEVER harms readability without preventing real mistakes. Quality > compliance. Score is a guide, not a mandate.
+
+## ⚠️ Gotchas
+
+- **Agent Rejection**: Some providers (like Anthropic) will refuse prompts that have too many aggressive words (like "nuclear" mode) due to safety alignment filters.
+- **Amplifier Context Loss**: When using `--mode nuclear`, the agent might prioritize following the meta-instructions over your actual objective.
+- **XML Parsing Interference**: Make sure to check if generating `<RULE>` tags conflicts with the target agent's system parser.