@ivannikov-pro/ai-context-surgeon 1.0.0

package/templates/antigravityignore.template

@@ -0,0 +1,64 @@
+# Config: antigravityignore — files to exclude from AI agent context
+# Syntax: same as .gitignore | Each level is self-contained
+# THREE SYSTEMS: .gitignore (git), .antigravityignore (agent context), .npmignore (npm publish)
+
+# ─ Lock files (massive, zero context value)
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+bun.lockb
+
+# ─ Build artifacts
+dist/
+build/
+.next/
+.nuxt/
+out/
+
+# ─ Cache
+.turbo/
+.cache/
+.parcel-cache/
+*.tsbuildinfo
+
+# ─ Coverage & reports
+coverage/
+.nyc_output/
+
+# ─ Generated files
+*.generated.ts
+*.generated.js
+*.d.ts.map
+
+# ─ Minified files
+*.min.js
+*.min.css
+
+# ─ Source maps
+*.map
+
+# ─ IDE / OS
+.DS_Store
+.idea/
+.vscode/settings.json
+
+# ─ Changelog (history, not context)
+CHANGELOG.md
+
+# ─ Web3 / Solidity Generated Files
+artifacts/
+cache/
+cache_forge/
+out/
+out_forge/
+typechain/
+typechain-types/
+broadcast/
+broadcast_forge/
+flatten/
+flattened/
+build/contracts/
+# Common Foundry dependencies that kill context limits:
+lib/forge-std/
+lib/openzeppelin-contracts*/
+lib/erc721a*/

package/templates/cursorrules.template

@@ -0,0 +1,7 @@
+# ai-context-surgeon Rules Trigger
+
+Follow the architectural instructions located in:
+.agents/AGENTS.md
+
+If requested to refactor, adopt roles from:
+.agents/surgeon/roles/

package/templates/knowledge-item.template

@@ -0,0 +1,44 @@
+<!-- FNH: Template — Knowledge Item (metadata.json) | SECTIONS: Metadata, Artifacts | DEPS: none -->
+<!-- Knowledge Item Template -->
+<!-- Directory: .agents/knowledge/{{KI_NAME}}/ -->
+
+<!-- FILE: metadata.json -->
+{
+  "title": "{{KI_TITLE}}",
+  "summary": "{{KI_SUMMARY_1_2_SENTENCES}}",
+  "references": [
+    {
+      "type": "file",
+      "path": "artifacts/{{ARTIFACT_NAME}}.md"
+    }
+  ]
+}
+
+<!-- FILE: artifacts/{{ARTIFACT_NAME}}.md -->
+
+# {{KI_TITLE}}
+
+> {{KI_SUMMARY_1_2_SENTENCES}}
+
+## {{SECTION_1}}
+
+{{CONCRETE_SPECIFIC_INFORMATION}}
+
+## {{SECTION_2}}
+
+{{MORE_CONCRETE_INFORMATION}}
+
+<!-- 
+RULES FOR WRITING KNOWLEDGE ITEMS:
+1. ATOMIC — One topic per KI. Not "everything about the project".
+2. CONCRETE — Specific values, rules, patterns. Not "our API is modern".
+3. ACTIONABLE — Agent should know WHAT TO DO after reading.
+4. STRUCTURED — Headers, tables, code blocks. Easy to scan.
+5. SMALL — Keep under 200 lines. Agent loads full KI into context.
+
+GOOD EXAMPLE:
+  "API responses use: { data: T, error: null } | { data: null, error: { code, message } }"
+
+BAD EXAMPLE:
+  "Our API supports many flexible response formats"
+-->

package/templates/package-json-ideal.template

@@ -0,0 +1,26 @@
+<!-- FNH: Template — ideal package.json | SECTIONS: Fields Tier, Sort Order | DEPS: strategy/package-json-guide.md -->
+{
+  "name": "@{{SCOPE}}/{{PACKAGE_NAME}}",
+  "version": "1.0.0",
+  "description": "{{ONE_LINE_DESCRIPTION}}",
+  "private": true,
+  "type": "module",
+
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+
+  "scripts": {
+    "dev": "{{DEV_COMMAND}}",
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/"
+  },
+
+  "dependencies": {
+    {{RUNTIME_DEPENDENCIES}}
+  },
+
+  "devDependencies": {
+    {{MINIMAL_DEV_DEPENDENCIES}}
+  }
+}

package/templates/package-readme.template

@@ -0,0 +1,45 @@
+<!-- FNH: Template — package README for new packages | EXPORTS: domain logic, API | DEPS: none -->
+# packages/{{PACKAGE_NAME}}
+
+> Package: {{PACKAGE_DESCRIPTION}} | SECTIONS: Source Structure, Scripts, Meta | DEPS: none
+
+## Source Structure
+
+```
+src/
+  index.ts              ← Public API exports
+  types.ts              ← Type contracts (interfaces, DTOs)
+  {{FILE_TREE}}
+```
+
+## Dependencies
+
+| Package | Purpose |
+|----|----|
+| `@{{SCOPE}}/{{DEP_NAME}}` | {{DEP_PURPOSE}} |
+
+## Public API
+
+```typescript
+// Key exports from src/index.ts
+export { {{EXPORTS}} } from './...';
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----|----|----|
+| `{{ENV_VAR}}` | {{REQUIRED}} | {{ENV_DESC}} |
+
+## Scripts
+
+```bash
+# Build
+{{BUILD_CMD}}
+
+# Test
+{{TEST_CMD}}
+
+# Lint
+{{LINT_CMD}}
+```

package/templates/publish-meta.template

@@ -0,0 +1,34 @@
+<!-- FNH: Template — publish-meta.json for bulk metadata injection | SECTIONS: Shared Meta, Overrides | DEPS: tools/enrich-package-json.js -->
+{
+  "_comment": "Publish metadata — injected into package.json before npm publish, stripped after",
+
+  "shared": {
+    "author": "{{AUTHOR_NAME}} <{{AUTHOR_EMAIL}}>",
+    "license": "MIT",
+    "engines": {
+      "node": ">=18.0.0"
+    }
+  },
+
+  "repositoryPattern": "git+https://github.com/{{ORG}}/{{REPO}}.git",
+  "homepagePattern": "https://github.com/{{ORG}}/{{REPO}}/tree/main/packages/{{package}}",
+  "bugsUrl": "https://github.com/{{ORG}}/{{REPO}}/issues",
+
+  "defaultFiles": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+
+  "packages": {
+    "@{{SCOPE}}/core": {
+      "keywords": ["core", "domain", "entities"]
+    },
+    "@{{SCOPE}}/api": {
+      "keywords": ["api", "rest", "express"]
+    },
+    "@{{SCOPE}}/shared": {
+      "keywords": ["shared", "types", "utils"]
+    }
+  }
+}

package/templates/skill.template

@@ -0,0 +1,50 @@
+<!-- FNH: Template — skill definition (SKILL.md) | SECTIONS: Use, Prerequisites, Steps | DEPS: none -->
+---
+name: {{SKILL_NAME}}
+description: >-
+  {{SKILL_DESCRIPTION_ONE_LINE}}
+  Use when {{TRIGGER_CONDITION}}.
+---
+
+# {{SKILL_TITLE}}
+
+## When to Use
+- {{TRIGGER_1}}
+- {{TRIGGER_2}}
+
+## When NOT to Use
+- {{ANTI_TRIGGER_1}}
+- {{ANTI_TRIGGER_2}}
+
+## Prerequisites
+- {{PREREQ_1}}
+
+## Steps
+
+1. {{STEP_1}}
+2. {{STEP_2}}
+3. {{STEP_3}}
+4. Verify: `{{VERIFY_COMMAND}}`
+
+## Template Code
+
+### {{TEMPLATE_FILE_1}}
+
+```{{LANGUAGE}}
+{{TEMPLATE_CODE}}
+```
+
+## Gotchas
+
+- ⚠️ {{GOTCHA_1}}
+- ⚠️ {{GOTCHA_2}}
+
+<!--
+RULES FOR WRITING SKILLS:
+1. SELF-CONTAINED — Everything needed is in this file + assets/
+2. SPECIFIC TRIGGERS — Clear "when to use" / "when NOT to use"
+3. STEP-BY-STEP — Numbered steps, not prose
+4. TEMPLATES — Copy-paste ready code
+5. VERIFY — Always include a verification step
+6. CONCISE — Agent context is limited. Don't waste it.
+-->

package/templates/workflow.template

@@ -0,0 +1,33 @@
+<!-- FNH: Template — executable workflow | SECTIONS: Steps, Annotations | DEPS: none -->
+---
+description: {{WORKFLOW_DESCRIPTION}}
+---
+
+{{TURBO_ANNOTATION}}
+<!-- Use '// turbo-all' above to auto-approve ALL commands -->
+<!-- Use '// turbo' above individual steps to auto-approve that step only -->
+<!-- Omit both for manual approval of every command -->
+
+1. {{STEP_1_DESCRIPTION}}
+```bash
+{{COMMAND_1}}
+```
+
+2. {{STEP_2_DESCRIPTION}}
+```bash
+{{COMMAND_2}}
+```
+
+3. Verify result:
+```bash
+{{VERIFY_COMMAND}}
+```
+
+<!--
+RULES FOR WRITING WORKFLOWS:
+1. IDEMPOTENT — Running twice should not break anything
+2. EXPLICIT — Every command fully specified (no "run the usual build")
+3. VERIFIABLE — Last step always verifies success
+4. SAFE — Use '// turbo' only for read-only/safe commands
+5. PARAMETERIZED — Use {{PLACEHOLDERS}} for variable parts
+-->

package/tools/analyze-package-json.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+# Tool: analyze-package-json — Analyze package.json files for AI-readiness | DEPS: none
+# USAGE: bash tools/analyze-package-json.sh /path/to/monorepo
+# OUTPUT: analysis report in scout-report.md
+# MODE: read-only analysis
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+  echo "Usage: bash tools/analyze-package-json.sh /path/to/monorepo"
+  echo ""
+  echo "Analyzes all package.json files in a monorepo for AI-agent readiness."
+  echo "Checks for:"
+  echo "  - Inline configs (jest, eslint, prettier, babel) — should be separate files"
+  echo "  - Missing critical fields (name, description, scripts)"
+  echo "  - Excessive dependencies"
+  echo "  - Field ordering"
+  echo "  - Token cost estimation"
+  exit 0
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "📦 Analyzing package.json files in: $TARGET"
+echo "════════════════════════════════════════════════════════"
+
+TOTAL_ISSUES=0
+TOTAL_FILES=0
+
+# Find all package.json files (excluding node_modules)
+find "$TARGET" -name "package.json" \
+  -not -path "*/node_modules/*" -not -path "*/lib/forge-std/*" -not -path "*/lib/openzeppelin-contracts*" -not -path "*/lib/erc721a*" \
+  -not -path "*/dist/*" \
+  -not -path "*/.git/*" \
+ | sort \
+ | while read -r pkg_file; do
+
+  TOTAL_FILES=$((TOTAL_FILES + 1))
+  ISSUES=0
+  
+  rel_path="${pkg_file#$TARGET/}"
+  line_count=$(wc -l < "$pkg_file" | tr -d ' ')
+  byte_count=$(wc -c < "$pkg_file" | tr -d ' ')
+  token_estimate=$((byte_count / 4))
+  
+  echo ""
+  echo "────────────────────────────────────────"
+  echo "📄 $rel_path"
+  echo "   Lines: $line_count | Tokens: ~$token_estimate"
+  echo ""
+  
+  # ── Tier 1: Critical fields check ──
+  
+  pkg_name=$(python3 -c "import json; d=json.load(open('$pkg_file')); print(d.get('name',''))" 2>/dev/null || echo "")
+  pkg_desc=$(python3 -c "import json; d=json.load(open('$pkg_file')); print(d.get('description',''))" 2>/dev/null || echo "")
+  has_scripts=$(python3 -c "import json; d=json.load(open('$pkg_file')); print('yes' if d.get('scripts') else 'no')" 2>/dev/null || echo "no")
+  has_main=$(python3 -c "import json; d=json.load(open('$pkg_file')); print('yes' if d.get('main') or d.get('exports') else 'no')" 2>/dev/null || echo "no")
+  has_type=$(python3 -c "import json; d=json.load(open('$pkg_file')); print('yes' if d.get('type') else 'no')" 2>/dev/null || echo "no")
+  
+  if [[ -z "$pkg_name" ]]; then
+    echo "   🔴 MISSING: name"
+    ISSUES=$((ISSUES + 1))
+  fi
+  
+  if [[ -z "$pkg_desc" ]]; then
+    echo "   🟡 MISSING: description — agent won't understand purpose"
+    ISSUES=$((ISSUES + 1))
+  fi
+  
+  if [[ "$has_scripts" == "no" ]]; then
+    echo "   🟡 MISSING: scripts — agent won't know how to build/test"
+    ISSUES=$((ISSUES + 1))
+  fi
+  
+  if [[ "$has_main" == "no" ]]; then
+    echo "   🟢 MISSING: main/exports — no entry point defined"
+  fi
+  
+  if [[ "$has_type" == "no" ]]; then
+    echo "   🟢 MISSING: type — module system unclear (CJS assumed)"
+  fi
+  
+  # ── Tier 4: Inline configs check ──
+  
+  python3 -c "
+import json, sys
+
+d = json.load(open('$pkg_file'))
+issues = 0
+
+# Inline config detection
+inline_configs = {
+    'jest': 'jest.config.ts',
+    'eslintConfig': '.eslintrc.js or eslint.config.js',
+    'prettier': '.prettierrc',
+    'babel': 'babel.config.js',
+    'browserslist': '.browserslistrc',
+    'lint-staged': '.lintstagedrc',
+    'husky': '.husky/',
+    'commitlint': 'commitlint.config.js',
+    'stylelint': '.stylelintrc',
+    'postcss': 'postcss.config.js',
+    'ava': 'ava.config.js',
+    'mocha': '.mocharc.yml',
+    'nyc': '.nycrc',
+    'c8': 'c8 CLI flags',
+    'release-it': '.release-it.json',
+    'standard-version': '.versionrc',
+}
+
+for field, target in inline_configs.items():
+    if field in d:
+        val = d[field]
+        lines = len(json.dumps(val, indent=2).split('\n'))
+        tokens = len(json.dumps(val)) // 4
+        print(f'   🔴 INLINE CONFIG: \"{field}\" ({lines} lines, ~{tokens} tokens) → move to {target}')
+        issues += 1
+
+# Dependency counts
+deps = d.get('dependencies', {})
+dev_deps = d.get('devDependencies', {})
+peer_deps = d.get('peerDependencies', {})
+
+dep_count = len(deps)
+dev_dep_count = len(dev_deps)
+
+if dep_count > 25:
+    print(f'   🟡 MANY dependencies: {dep_count} — consider splitting package')
+    issues += 1
+elif dep_count > 50:
+    print(f'   🔴 TOO MANY dependencies: {dep_count} — package does too much')
+    issues += 1
+
+if dev_dep_count > 20:
+    print(f'   🟡 MANY devDependencies: {dev_dep_count} — consider hoisting to root')
+    issues += 1
+
+# Resolutions/overrides
+if 'resolutions' in d:
+    res_count = len(d['resolutions'])
+    res_tokens = len(json.dumps(d['resolutions'])) // 4
+    if res_count > 5:
+        print(f'   🟡 resolutions: {res_count} entries (~{res_tokens} tokens) — keep only in root')
+        issues += 1
+
+if 'overrides' in d:
+    ovr_count = len(d['overrides']) if isinstance(d['overrides'], dict) else 0
+    ovr_tokens = len(json.dumps(d['overrides'])) // 4
+    if ovr_count > 5:
+        print(f'   🟡 overrides: {ovr_count} entries (~{ovr_tokens} tokens) — keep only in root')
+        issues += 1
+
+# Scripts count
+scripts = d.get('scripts', {})
+script_count = len(scripts)
+if script_count > 12:
+    print(f'   🟡 TOO MANY scripts: {script_count} — simplify to 4-8 key scripts')
+    issues += 1
+
+# Long script values
+for name, cmd in scripts.items():
+    if len(cmd) > 150:
+        print(f'   🟡 LONG script \"{name}\": {len(cmd)} chars — move to scripts/*.sh')
+        issues += 1
+
+# Size check
+if lines_count := len(json.dumps(d, indent=2).split('\n')):
+    if lines_count > 60:
+        print(f'   🔴 FILE TOO LARGE: {lines_count} lines — target ≤30 lines')
+        issues += 1
+    elif lines_count > 30:
+        print(f'   🟡 FILE LARGE: {lines_count} lines — target ≤30 lines')
+        issues += 1
+
+# Token budget assessment
+total_tokens = len(json.dumps(d)) // 4
+if total_tokens > 2000:
+    emoji = '🔴'
+    label = 'HARMFUL'
+elif total_tokens > 800:
+    emoji = '🟡'
+    label = 'HIGH'
+elif total_tokens > 300:
+    emoji = '🟢'
+    label = 'OK'
+else:
+    emoji = '⭐'
+    label = 'EXCELLENT'
+
+print(f'')
+print(f'   {emoji} Context cost: ~{total_tokens} tokens ({label})')
+print(f'   deps: {dep_count} | devDeps: {dev_dep_count} | scripts: {script_count}')
+
+if issues == 0:
+    print(f'   ✅ No issues found')
+
+sys.exit(issues)
+" 2>/dev/null || true
+
+done
+
+echo ""
+echo "════════════════════════════════════════════════════════"
+echo "✅ Analysis complete"
+echo ""
+echo "📖 See strategy/package-json-guide.md for full optimization guide"

package/tools/analyze-structure.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# Tool: analyze-structure — Analyze monorepo structure and generate metrics | DEPS: none
+# USAGE: bash tools/analyze-structure.sh /path/to/monorepo
+# OUTPUT: structural metrics and directory map
+# MODE: read-only analysis
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+DIVIDER="────────────────────────────────────────"
+
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+  echo "Usage: bash tools/analyze-structure.sh /path/to/monorepo"
+  echo ""
+  echo "Analyzes monorepo structure and outputs key metrics:"
+  echo "  - Total files and directories"
+  echo "  - Files per directory (top 10 densest)"
+  echo "  - Deepest nesting level"
+  echo "  - Package inventory with README/index.ts/types.ts presence"
+  echo "  - Overall health indicators"
+  exit 0
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "🔍 Analyzing: $TARGET"
+echo "$DIVIDER"
+
+# Exclude common non-source directories
+EXCLUDE="-not -path '*/node_modules/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/.next/*' -not -path '*/.turbo/*'"
+
+# 1. Total file counts
+echo ""
+echo "📊 FILE METRICS"
+echo "$DIVIDER"
+
+TOTAL_FILES=$(eval "find '$TARGET' -type f $EXCLUDE" | wc -l | tr -d ' ')
+TOTAL_DIRS=$(eval "find '$TARGET' -type d $EXCLUDE" | wc -l | tr -d ' ')
+SRC_FILES=$(eval "find '$TARGET' -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' \) $EXCLUDE" | wc -l | tr -d ' ')
+
+echo "Total files:       $TOTAL_FILES"
+echo "Total directories: $TOTAL_DIRS"
+echo "Source files:      $SRC_FILES (ts/tsx/js/jsx)"
+
+# 2. Deepest nesting
+MAX_DEPTH=$(eval "find '$TARGET' -type f $EXCLUDE" | awk -F/ '{print NF}' | sort -n | tail -1)
+echo "Max nesting depth: $MAX_DEPTH levels"
+
+# 3. Densest directories (most files in one dir)
+echo ""
+echo "📁 DENSEST DIRECTORIES (top 10)"
+echo "$DIVIDER"
+
+eval "find '$TARGET' -type d $EXCLUDE" | while read -r dir; do
+  count=$(find "$dir" -maxdepth 1 -type f 2>/dev/null | wc -l | tr -d ' ')
+  if [[ $count -gt 0 ]]; then
+    echo "$count $dir"
+  fi
+done | sort -rn | head -10
+
+# 4. Package inventory
+echo ""
+echo "📦 PACKAGE INVENTORY"
+echo "$DIVIDER"
+
+for pkg_dir in "$TARGET"/packages/* "$TARGET"/apps/*; do
+  if [[ -d "$pkg_dir" ]]; then
+    pkg_name=$(basename "$pkg_dir")
+    has_readme="❌"
+    has_index="❌"
+    has_types="❌"
+    has_tests="❌"
+    
+    [[ -f "$pkg_dir/README.md" ]] && has_readme="✅"
+    [[ -f "$pkg_dir/src/index.ts" || -f "$pkg_dir/src/index.js" ]] && has_index="✅"
+    [[ -f "$pkg_dir/src/types.ts" || -d "$pkg_dir/src/types" ]] && has_types="✅"
+    [[ -d "$pkg_dir/tests" || -d "$pkg_dir/__tests__" || -d "$pkg_dir/test" ]] && has_tests="✅"
+    
+    file_count=$(eval "find '$pkg_dir' -type f $EXCLUDE" | wc -l | tr -d ' ')
+    
+    echo "$pkg_name: ${file_count} files | README:${has_readme} index:${has_index} types:${has_types} tests:${has_tests}"
+  fi
+done
+
+# 5. AGENTS.md check
+echo ""
+echo "🧠 AI-READINESS"
+echo "$DIVIDER"
+
+[[ -f "$TARGET/.agents/AGENTS.md" ]] && echo "AGENTS.md: ✅" || echo "AGENTS.md: ❌ MISSING"
+[[ -d "$TARGET/.agents/knowledge" ]] && echo "Knowledge Items: ✅ ($(ls "$TARGET/.agents/knowledge" 2>/dev/null | wc -l | tr -d ' ') items)" || echo "Knowledge Items: ❌ MISSING"
+[[ -d "$TARGET/.agents/skills" ]] && echo "Skills: ✅ ($(ls "$TARGET/.agents/skills" 2>/dev/null | wc -l | tr -d ' ') skills)" || echo "Skills: ❌ MISSING"
+[[ -d "$TARGET/.agents/workflows" ]] && echo "Workflows: ✅ ($(ls "$TARGET/.agents/workflows" 2>/dev/null | wc -l | tr -d ' ') workflows)" || echo "Workflows: ❌ MISSING"
+
+echo ""
+echo "✅ Analysis complete"