ai-context-surgeon

Toolkit: ai-context-surgeon — an AI-native Knowledge API for autonomous agents doing surgical monorepo restructuring. Roles, strategies, prompts, skills, templates, and analysis tools — all accessible on-demand via CLI. No install required. | SECTIONS: Quick Start, For AI Agents, Catalog, CLI, Tools, Roles, Prompts, Workflows, Strategy, Source Structure | DEPS: none

ai-context-surgeon is a Knowledge API, not a traditional CLI tool. It provides on-demand access to roles, strategies, prompts, skills, templates, and analysis tools — everything an AI agent needs to optimize a monorepo's context for minimal token consumption.

---

🚀 Quick Start

# Browse everything available
npx -y @ivannikov-pro/ai-context-surgeon@latest catalog

# Run repo analysis
npx -y @ivannikov-pro/ai-context-surgeon@latest radar

# Get a role prompt for the AI agent to follow
npx -y @ivannikov-pro/ai-context-surgeon@latest role scout

# Get condensed task instructions (~60 tokens instead of ~2800)
npx -y @ivannikov-pro/ai-context-surgeon@latest prompt fnh

# Lightweight project setup
npx -y @ivannikov-pro/ai-context-surgeon@latest init

---

🤖 For AI Agents

The npm package IS the knowledge base. The CLI IS the API. No files to copy. No install to maintain. Always the latest version.

# Step 1: Discover everything available
npx @ivannikov-pro/ai-context-surgeon@latest catalog

# Step 2: Read a role prompt and follow its instructions
npx @ivannikov-pro/ai-context-surgeon@latest role scout

# Step 3: Run analysis tools
npx @ivannikov-pro/ai-context-surgeon@latest radar
npx @ivannikov-pro/ai-context-surgeon@latest context-weight

# Step 4: Get specific instructions for a task (saves 95% tokens)
npx @ivannikov-pro/ai-context-surgeon@latest prompt fnh       # How to create FNH headers
npx @ivannikov-pro/ai-context-surgeon@latest prompt jsdoc     # How to write JSDoc
npx @ivannikov-pro/ai-context-surgeon@latest prompt god-file  # How to split large files
npx @ivannikov-pro/ai-context-surgeon@latest prompt readme    # How to write package READMEs
npx @ivannikov-pro/ai-context-surgeon@latest prompt agent-rules        # How to write AGENTS.md
npx @ivannikov-pro/ai-context-surgeon@latest prompt context-exclusion  # How to set up .antigravityignore

# Step 5: Read strategy docs when needed (full reference)
npx @ivannikov-pro/ai-context-surgeon@latest strategy fnh
npx @ivannikov-pro/ai-context-surgeon@latest strategy monorepo

# Step 6: Delegate — output a role prompt and send to another agent
npx @ivannikov-pro/ai-context-surgeon@latest role architect --output .agents/architect-prompt.md

---

📈 Token Savings: Before / After

╔═══════════════════════════════════════════════════════════════╗
║  LEVEL 1: Blind Navigation (No rules)                         ║
║  Agent reads 10 files ~3,300 lines            ≈  8,000 tokens ║
╠═══════════════════════════════════════════════════════════════╣
║  LEVEL 2: Traditional Docs (Reading markdown files)           ║
║  Agent reads strategy doc ~560 lines          ≈  2,800 tokens ║
╠═══════════════════════════════════════════════════════════════╣
║  LEVEL 3: ai-context-surgeon (Knowledge API)                  ║
║  Agent calls `prompt fnh`                     ≈     60 tokens ║
╠═══════════════════════════════════════════════════════════════╣
║  SAVINGS: 99.3%  (from 8,000 → 60 tokens per task)            ║
╚═══════════════════════════════════════════════════════════════╝

Scenario	Tokens	Method
Blind repo navigation	~8,000	Agent reads random files
Traditional Markdown Docs	~2,800	Agent reads strategy/file-navigation-header.md
Knowledge API	~60	Agent calls prompt fnh

JSDoc annotation example:

// BEFORE (220 tokens of noise):
/**
 * @fileoverview User Service
 * @author Jane Developer
 * @since 2024-03-15
 */
export class UserService {
  /** @param {CreateUserInput} input @returns {Promise<User>} */
  async create(input: CreateUserInput): Promise<User> { ... }
}

// AFTER (40 tokens — 82% reduction):
/** Service: UserService — CRUD + auth | deps: prisma, bcrypt */
export class UserService {
  /** @throws Conflict(email) | hashes pw bcrypt 12 | sends welcome email */
  async create(input: CreateUserInput): Promise<User> { ... }
}

---

📋 Catalog

npx @ivannikov-pro/ai-context-surgeon@latest catalog

Category	Command	Count	Description
🔧 Tools	radar, godfiles, circular, context-weight, sourcemaps	5	Run analysis directly against any repo
🎭 Roles	role <name>	6	Agent role prompts (scout → inspector)
📖 Strategies	strategy <name>	7	Full reference docs (FNH, monorepo, JSDoc, ...)
💡 Prompts	prompt <task>	6	Condensed task instructions (~60 tokens each)
🧩 Skills	skill <name>	2	Reusable agent procedures
📝 Templates	template <name>	9	File seeds (AGENTS.md, README, package.json, ...)
📋 Checklists	checklist <n>	5	Phase task lists (1–5)
🧠 Knowledge	knowledge <name>	3	Reference knowledge items

---

🖥️ CLI Commands

Content Access

Command	Description
catalog	List all available content across all categories
role <name>	Output an agent role prompt
strategy <name>	Output a strategy document
prompt <task>	Output a condensed task prompt
skill <name>	Output a skill procedure
template <name>	Output a file template
checklist <n>	Output a phase checklist (1–5)
knowledge <name>	Output a knowledge item

All content commands support --output <path> to save to a file:

npx @ivannikov-pro/ai-context-surgeon@latest role scout --output .agents/scout.md
npx @ivannikov-pro/ai-context-surgeon@latest checklist 1 --output .agents/phase-1.md

Tool Execution

Command	Script	Description
radar	scan-fnh.sh	Semantic FNH map of any repository
godfiles	detect-god-files.sh	Find files exceeding LOC thresholds
circular	detect-circular-deps.sh	Detect circular dependencies
context-weight	validate-context-weight.sh	Identify files with high cognitive load (LOC + Fan-out)
sourcemaps	generate-source-map.sh	Generate AI-friendly structure trees

Project Setup

Command	Description
init	Creates AGENTS.md, .antigravityignore, and injects CI scripts into package.json

After init, these CI gates are available in package.json:

npm run check:hygiene     # FNH radar scan
npm run check:god-files   # God file detection

---

💡 Prompt Library

Available via prompt <task> — each prompt is ~60 tokens vs ~2800 for the full strategy doc.

Key	Name	Description
fnh	File Navigation Header	How to create FNH headers for any file type (all 5 mandatory layers)
jsdoc	JSDoc Annotation	How to write AI-optimized JSDoc (what to annotate, what to skip)
readme	Package README	How to write a README with Source Structure for AI agents
agent-rules	AGENTS.md	How to write an AGENTS.md for any repository
context-exclusion	Context Exclusion	How to configure .antigravityignore / .aiignore
god-file	God File Splitting	How to split files >300 lines into focused modules

Examples:

npx @ivannikov-pro/ai-context-surgeon@latest prompt fnh
npx @ivannikov-pro/ai-context-surgeon@latest prompt god-file
npx @ivannikov-pro/ai-context-surgeon@latest prompt jsdoc --output /tmp/jsdoc-task.md

---

🎭 Agent Roles

6 specialized roles for the 5-phase optimization pipeline:

Role	Phase	Description	Model	Mode
Scout	1 — Analysis	Context reconnaissance, FNH radar, telemetry gathering	Gemini 3 Flash	Fast
Architect	2 — Planning	Design decisions, refactoring plan, package boundaries	Claude Opus 4.6 / Gemini 3.1 Pro	Planning
Surgeon	3 — Restructuring	Surgical code splitting, import fixing, god-file extraction	Gemini 3.1 Pro (High)	Fast
Librarian	4a — Documentation	FNH headers, JSDoc, package READMEs, Source Structure	Claude Sonnet 4.6	Planning
Tuner	4b — Configuration	AGENTS.md, .antigravityignore, package.json, CI scripts	Claude Opus 4.6	Planning
Inspector	5 — Validation	Scoring, health checks, before/after comparison, sign-off	Gemini 3.1 Pro (High)	Planning

# Load a role into the current agent
npx @ivannikov-pro/ai-context-surgeon@latest role scout

# Full pipeline delegation
npx @ivannikov-pro/ai-context-surgeon@latest role scout    # → reconnaissance
npx @ivannikov-pro/ai-context-surgeon@latest role architect  # → plan
npx @ivannikov-pro/ai-context-surgeon@latest role surgeon    # → execute
npx @ivannikov-pro/ai-context-surgeon@latest role librarian  # → document
npx @ivannikov-pro/ai-context-surgeon@latest role tuner      # → configure
npx @ivannikov-pro/ai-context-surgeon@latest role inspector  # → validate

---

🔧 Analysis Tools

All 16 shell scripts in tools/ plus one Node.js enrichment tool:

Tool	CLI Command	Description
scan-fnh.sh	radar	Extract FNH headers from all files — semantic repo map
detect-god-files.sh	godfiles	Flag files exceeding LOC thresholds (default >300)
detect-circular-deps.sh	circular	Find circular import chains between packages
validate-context-weight.sh	context-weight	Compute cognitive load (LOC + Fan-out × 20 formula)
generate-source-map.sh	sourcemaps	Build Source Structure block for README
analyze-structure.sh	—	Full monorepo structure metrics and overview
analyze-package-json.sh	—	Rate package.json AI-readiness (Tier 1–4 scoring)
audit-jsdoc.sh	—	Analyze JSDoc coverage and quality
check-fnh-freshness.sh	—	Warn when source changed but FNH header wasn't updated
lint-imports.sh	—	Detect cross-package boundary violations
measure-context-cost.sh	—	Estimate AI agent context cost for a package
generate-jsdoc-headers.sh	—	Add JSDoc navigation headers to source files
enforce-god-files.sh	—	CI gate — fail build if files exceed line thresholds
validate-context-hygiene.sh	—	CI gate — ensure all packages have README and ignores
validate-naming.sh	—	Check kebab-case and naming conventions
enrich-package-json.js	—	Lean/Enrich workflow — inject publish metadata before npm publish

---

🔄 Full-Pipeline Workflow Summary

Phase	Role	Checklist	Tools Used	Output
1 — Analysis	Scout	checklist 1	radar, godfiles, context-weight, circular	Telemetry report
2 — Planning	Architect	checklist 2	analyze-structure.sh, analyze-package-json.sh	Refactoring plan
3 — Restructuring	Surgeon	checklist 3	lint-imports.sh, check-fnh-freshness.sh	Split files, fixed imports
4a — Documentation	Librarian	checklist 4	audit-jsdoc.sh, generate-jsdoc-headers.sh	FNH headers, JSDoc, READMEs
4b — Configuration	Tuner	checklist 4	validate-naming.sh, validate-context-hygiene.sh	AGENTS.md, CI scripts
5 — Validation	Inspector	checklist 5	radar, context-weight, enforce-god-files.sh	Score report, sign-off

Invoke the full pipeline via workflow:

# Analyzes a target repo (requires target path argument)
npx @ivannikov-pro/ai-context-surgeon@latest # → interactive menu

Or use pre-built agent workflows (defined in .agents/workflows/):

• /analyze-repo — Quick analysis using Scout + tools
• /apply-surgeon — Step-by-step execution pipeline to overhaul the current codebase
• /full-pipeline — Complete 5-phase cascade guide
• /self-check — Validate ai-context-surgeon's own integrity

---

📖 Strategy Docs

All accessible via strategy <key> — read on-demand, no install:

Key	Document	Size	Description
fnh	File Navigation Headers	~560 lines	Universal header format for every file type
monorepo	Monorepo Strategy	~700 lines	Architectural patterns and package boundaries
jsdoc	JSDoc Guide	~600 lines	Token-efficient annotation standards
package-json	package.json Guide	~540 lines	Tier 1–4 field priority, Lean+Enrich workflow
context-exclusion	Context Exclusion	~200 lines	.antigravityignore patterns and philosophy
bash	Bash Guide	~180 lines	Writing POSIX scripts for AI agents
context-weight	Context Weight Theory	~120 lines	LOC + Fan-out cognitive load formula

---

🧩 Skills

Reusable agent procedures — a skill is a self-contained, step-by-step instruction set:

Key	Name	Description
annotate-jsdoc	Annotate JSDoc	Reusable JSDoc/FNH injection procedure
prompt-engineering	Prompt Engineering	Prompt analysis, amplification, and extraction

npx @ivannikov-pro/ai-context-surgeon@latest skill annotate-jsdoc

---

📝 Templates

File seeds for new projects — all use {{UPPER_SNAKE_CASE}} placeholders:

Key	Template	Description
agents	AGENTS.md.template	Agent rules with Navigation Rules, FNH, ai-context-surgeon Quick Reference
readme	package-readme.template	Package README with Source Structure and Scripts
package-json	package-json-ideal.template	Lean package.json (Tier 1 order, ≤30 lines)
workflow	workflow.template	Executable workflow with // turbo annotations
skill	skill.template	Skill definition with When/When-Not/Steps/Verify
knowledge	knowledge-item.template	Knowledge item (metadata.json + artifacts/)
publish-meta	publish-meta.template	Publish metadata for Lean+Enrich workflow
antigravityignore	antigravityignore.template	Context exclusion rules
cursorrules	cursorrules.template	Cursor / Windsurf IDE agent rules

npx @ivannikov-pro/ai-context-surgeon@latest template agents
npx @ivannikov-pro/ai-context-surgeon@latest template agents --output AGENTS.md

---

🧠 Knowledge Items

Pre-loaded reference knowledge for agents:

Key	Name	Description
agent-context	Agent Context System	How Knowledge/Skills/Workflows work in AI agents
vulnerabilities	Agent Vulnerabilities	AI agent vulnerability patterns and bypass techniques
power-words	Power Words Dictionary	Enforcement directive vocabulary for AI prompts

npx @ivannikov-pro/ai-context-surgeon@latest knowledge agent-context

---

📂 Source Structure

See STRUCTURE.md for the complete verbose file and directory map.

---

🛡️ CI/CD Integration

After init, inject these gates into your CI pipeline:

npm run check:hygiene     # FNH radar scan — verifies all files have headers
npm run check:god-files   # God file detection — fails if any file exceeds 300 LOC

Or run tools directly against any target repo:

npx @ivannikov-pro/ai-context-surgeon@latest radar /path/to/repo
npx @ivannikov-pro/ai-context-surgeon@latest godfiles /path/to/repo

---

ai-context-surgeon | MIT | npm | GitHub