@ivannikov-pro/ai-context-surgeon 1.0.0

package/checklists/phase-5-validation.md

@@ -0,0 +1,91 @@
+<!-- FNH: Checklist — Phase 5 Validation | ROLE: Inspector | MODEL: Gemini 3.1 Pro -->
+
+# Phase 5: Validation — Checklist
+
+> **Role:** Inspector | **Model:** Gemini 3.1 Pro (High) | **Mode:** Planning | **Goal:** Verify everything works and measure improvement | **SECTIONS:** Linting, Freshness, Context Cost, Self-Check | **DEPS:** Phase 4
+
+## Pre-flight
+
+- [ ] Read `roles/inspector.md` for full instructions
+- [ ] Ensure ALL previous phases completed
+- [ ] This phase is read-only + run commands
+
+## Build & Tests
+
+- [ ] Full build: `{{BUILD_COMMAND}}` → must pass
+- [ ] Full tests: `{{TEST_COMMAND}}` → must pass (≥80%)
+- [ ] Type check: `tsc --noEmit` → no errors
+- [ ] Lint: `{{LINT_COMMAND}}` → no errors (warnings OK)
+
+## Structure Validation
+
+- [ ] Run `tools/analyze-structure.sh {{TARGET_REPO_PATH}}`
+- [ ] Every package has `README.md`
+- [ ] Every package has `src/index.ts`
+- [ ] Every package has `src/types.ts` or `src/types/`
+- [ ] No god-files remain: `tools/detect-god-files.sh {{TARGET_REPO_PATH}}`
+- [ ] No circular dependencies: `tools/detect-circular-deps.sh {{TARGET_REPO_PATH}}`
+- [ ] No direct internal imports (cross-package)
+- [ ] All `.antigravityignore` configurations are correct
+
+## Documentation Validation
+
+- [ ] `.agents/AGENTS.md` exists and has key rules
+- [ ] AGENTS.md has "Read README first" rule
+- [ ] AGENTS.md has "Stay within package" rule
+- [ ] AGENTS.md has English-only rule
+- [ ] AGENTS.md has build/test commands
+- [ ] Knowledge Items exist (≥1)
+- [ ] Knowledge Items have `metadata.json`
+- [ ] Skills exist (≥1) with `SKILL.md`
+- [ ] Workflows exist (≥1)
+- [ ] READMEs have Source Structure sections
+
+## FNH / JSDoc Validation
+
+- [ ] ALL source files have FNH headers
+- [ ] FNH headers have real descriptions (not TODO)
+- [ ] ALL FNH headers are in English
+- [ ] No verbose tags (no @author, @version)
+
+## Context Cost Measurement
+
+- [ ] Run `tools/measure-context-cost.sh` for each major package
+- [ ] Record "Before" metrics (from scout-report.md)
+- [ ] Record "After" metrics
+- [ ] Calculate reduction percentage
+- [ ] Target: ≥70% reduction
+
+## Agent Smoke Test
+
+In a **new conversation** (fresh context), ask the agent:
+
+- [ ] "Add a new field `phone` to the User entity"
+  - Did agent read README first?
+  - How many files did agent read?
+  - Did agent follow AGENTS.md rules?
+  - Quality of result?
+
+## Scoring
+
+| Category | Score (0-10) | Notes |
+| --- | --- | --- |
+| Structure | | |
+| Documentation | | |
+| Context Optimization | | |
+| **Total** | **/30** | |
+
+### Scoring Guide
+
+- **0-10:** 🔴 Needs re-work — go back to Architect
+- **11-20:** 🟡 Acceptable but gaps — targeted fixes needed
+- **21-27:** 🟢 Good — minor improvements possible
+- **28-30:** ⭐ Excellent — production-ready
+
+## Deliverable
+
+- [ ] `{{TARGET_REPO_PATH}}/validation-report.md` created
+- [ ] All sections filled with measurements
+- [ ] Context cost Before/After table
+- [ ] Final score assigned
+- [ ] Remaining issues listed (if any)

package/examples/before-after/README.md

@@ -0,0 +1,139 @@
+<!-- FNH: Examples — Before and after comparison of monorepo restructuring | SECTIONS: Case Study A, Findings | DEPS: none -->
+
+# Before & After — ai-context-surgeon examples
+
+> Examples of monorepo restructuring results | SECTIONS: Example 1, Example 2 | DEPS: none
+
+### ❌ BEFORE
+
+```
+packages/api/src/
+  app.ts                    (150 lines)
+  routes.ts                 (1200 lines — GOD FILE)
+  middleware.ts              (400 lines)
+  utils.ts                  (800 lines — GOD FILE)
+  types.ts                  (50 lines)
+  db.ts                     (100 lines)
+  auth.ts                   (200 lines)
+  validation.ts             (300 lines)
+  logger.ts                 (50 lines)
+  errors.ts                 (80 lines)
+```
+
+**Context cost:** Agent reads 10 files (~3,300 lines) = ~8K tokens just to understand the package.
+
+**Problems:**
+
+- `routes.ts` — 1200 lines with ALL routes for ALL domains
+- `utils.ts` — 800 lines of mixed utilities
+- No README, no Source Structure
+- No clear domain boundaries
+
+### ✅ AFTER
+
+```
+packages/api/
+  README.md                                ← Source Structure map
+  src/
+    index.ts                               ← App setup, exports
+    types.ts                               ← API-specific types
+    routes/
+      v1/
+        index.ts                           ← Route registration
+        users.ts                           ← /api/v1/users (120 lines)
+        orders.ts                          ← /api/v1/orders (150 lines)
+        products.ts                        ← /api/v1/products (100 lines)
+        auth.ts                            ← /api/v1/auth (80 lines)
+    middleware/
+      auth.ts                              ← JWT verification (60 lines)
+      validation.ts                        ← Zod middleware (40 lines)
+      error-handler.ts                     ← Error handler (50 lines)
+      logger.ts                            ← Request logging (30 lines)
+    validation/
+      user.schema.ts                       ← User validation (40 lines)
+      order.schema.ts                      ← Order validation (45 lines)
+    utils/
+      response.ts                          ← Response formatting (30 lines)
+      pagination.ts                        ← Pagination helpers (25 lines)
+```
+
+**Context cost:** Agent reads README (~300 tokens) + 1 target file (~200 tokens) = ~500 tokens.
+
+**Improvement:** 8K → 500 tokens = **94% reduction**
+
+---
+
+## Example 2: Mixed Monorepo Root
+
+### ❌ BEFORE
+
+```
+project/
+  src/
+    (87 files all in one directory)
+    UserController.ts
+    UserService.ts
+    UserRepository.ts
+    OrderController.ts
+    OrderService.ts
+    ... (82 more files)
+  package.json
+  tsconfig.json
+  (no README, no AGENTS.md, no docs)
+```
+
+**Problems:**
+
+- 87 files in one flat directory — impossible to navigate
+- No packages — everything coupled
+- No README — agent has no map
+- No AGENTS.md — no rules
+- No Knowledge Items — agent has no memory
+
+### ✅ AFTER
+
+```
+project/
+  .agents/
+    AGENTS.md                              ← Navigation rules
+    knowledge/
+      database-schema/                     ← DB knowledge
+      api-conventions/                     ← API patterns
+    skills/
+      create-endpoint/                     ← How to add endpoints
+    workflows/
+      test.md                              ← /test workflow
+  packages/
+    core/
+      README.md                            ← Source Structure
+      src/
+        index.ts
+        types.ts
+        entities/ (5 files)
+        services/ (5 files)
+        repositories/ (5 files)
+    api/
+      README.md
+      src/
+        index.ts
+        types.ts
+        routes/ (8 files)
+        middleware/ (4 files)
+        validation/ (5 files)
+    shared/
+      README.md
+      src/
+        index.ts
+        types.ts
+        utils/ (6 files)
+  README.md                               ← Architecture map
+  package.json
+  turbo.json
+```
+
+**Improvement:**
+
+- 87 files in one dir → 3 packages, max 15 files each
+- No docs → README + AGENTS.md + KI + Skills + Workflows
+- Context cost: from ~25K tokens down to ~1.5K tokens per task
+- **94% reduction**

package/examples/ideal-monorepo/README.md

@@ -0,0 +1,127 @@
+<!-- FNH: Examples — Ideal monorepo structure reference | SECTIONS: Directory Map, Core Standards | DEPS: none -->
+
+# Ideal Monorepo Structure — Reference
+
+> Guide: Perfectly optimized monorepo structure after ai-context-surgeon treatment | SECTIONS: Root Structure, Package Structure, Metadata | DEPS: none
+
+```
+project-root/
+│
+├── .agents/                                    ← 🧠 AI Agent Configuration
+│   ├── AGENTS.md                               ← Rules (HIGHEST PRIORITY)
+│   ├── knowledge/                              ← Persistent memory
+│   │   ├── database-schema/
+│   │   │   ├── metadata.json                   ← title, summary
+│   │   │   └── artifacts/
+│   │   │       └── schema.md                   ← Tables, relations, indexes
+│   │   ├── api-conventions/
+│   │   │   ├── metadata.json
+│   │   │   └── artifacts/
+│   │   │       └── conventions.md              ← Response format, error codes
+│   │   └── auth-flow/
+│   │       ├── metadata.json
+│   │       └── artifacts/
+│   │           └── flow.md                     ← JWT lifecycle, roles
+│   ├── skills/
+│   │   ├── create-endpoint/
+│   │   │   └── SKILL.md                        ← How to add a new API endpoint
+│   │   └── create-package/
+│   │       └── SKILL.md                        ← How to add a new package
+│   └── workflows/
+│       ├── test.md                             ← /test — run package tests
+│       ├── build.md                            ← /build — build verification
+│       └── deploy.md                           ← /deploy — deploy procedure
+│
+├── packages/                                   ← 📦 Isolated Packages
+│   ├── shared/                                 ← Shared types & utilities
+│   │   ├── README.md                           ← Source Structure + API
+│   │   ├── package.json                        ← @project/shared
+│   │   ├── tsconfig.json                       ← Standalone config
+│   │   └── src/
+│   │       ├── index.ts                        ← Public API (re-exports)
+│   │       ├── types.ts                        ← All shared type contracts
+│   │       ├── constants.ts                    ← Shared constants
+│   │       └── utils/
+│   │           ├── string.ts                   ← String utilities
+│   │           └── date.ts                     ← Date utilities
+│   │
+│   ├── core/                                   ← Domain logic
+│   │   ├── README.md                           ← Source Structure + API
+│   │   ├── package.json                        ← @project/core
+│   │   ├── tsconfig.json
+│   │   └── src/
+│   │       ├── index.ts                        ← Public API
+│   │       ├── types.ts                        ← Core type contracts
+│   │       ├── entities/
+│   │       │   ├── user.ts                     ← User entity
+│   │       │   └── order.ts                    ← Order entity
+│   │       ├── services/
+│   │       │   ├── user.service.ts             ← User business logic
+│   │       │   └── order.service.ts            ← Order business logic
+│   │       └── repositories/
+│   │           ├── user.repository.ts          ← User data access
+│   │           └── order.repository.ts         ← Order data access
+│   │
+│   └── api/                                    ← REST API
+│       ├── README.md                           ← Source Structure + API
+│       ├── package.json                        ← @project/api
+│       ├── tsconfig.json
+│       └── src/
+│           ├── index.ts                        ← App setup, server start
+│           ├── types.ts                        ← API-specific types
+│           ├── routes/
+│           │   └── v1/
+│           │       ├── index.ts                ← Route registration
+│           │       ├── users.ts                ← /api/v1/users
+│           │       └── orders.ts               ← /api/v1/orders
+│           ├── middleware/
+│           │   ├── auth.ts                     ← JWT verification
+│           │   ├── validation.ts               ← Zod schema middleware
+│           │   └── error-handler.ts            ← Global error handler
+│           └── validation/
+│               ├── user.schema.ts              ← User input schemas
+│               └── order.schema.ts             ← Order input schemas
+│
+├── apps/                                       ← 🚀 Deployable Applications
+│   └── dashboard/
+│       ├── README.md
+│       ├── package.json
+│       └── src/
+│
+├── README.md                                   ← 📋 Project overview + architecture map
+├── package.json                                ← Root manifest
+├── turbo.json                                  ← Build pipeline
+├── tsconfig.json                               ← Root TypeScript config
+└── .gitignore
+```
+
+## Key Properties
+
+| Property | Value |
+| --- | --- |
+| Every package has `README.md` | ✅ |
+| Every package has `src/index.ts` | ✅ |
+| Every package has `src/types.ts` | ✅ |
+| No god-files (>500 lines) | ✅ |
+| No circular dependencies | ✅ |
+| AGENTS.md with navigation rules | ✅ |
+| Knowledge Items for stable knowledge | ✅ |
+| Skills for recurring tasks | ✅ |
+| Workflows for routine procedures | ✅ |
+| Consistent naming (kebab-case files) | ✅ |
+| Dependency direction enforced | ✅ |
+
+## Context Cost Estimate
+
+```
+Agent needs to add a new /api/v1/products endpoint:
+
+1. Read packages/api/README.md         → ~300 tokens (knows structure)
+2. Read packages/api/src/routes/v1/users.ts → ~200 tokens (pattern reference)
+3. Read packages/core/src/types.ts     → ~150 tokens (type contracts)
+─────────────────────────────────────────
+Total: ~650 tokens to understand everything needed
+
+Without this structure: ~6,000+ tokens of blind scanning
+Savings: 89%
+```

package/knowledge/agent-context-system/artifacts/guide.md

@@ -0,0 +1,183 @@
+# Agent Context System — Knowledge, Skills & Workflows
+
+> Production-level reference for AI agent systems.
+> Primary target: Google Antigravity IDE. Applicable to any agent framework.
+> Last updated: 2026-04-01
+
+---
+
+## The Core Triad
+
+Every AI agent system is built on three pillars:
+
+```
+User Input → Agent Reasoning → [1] Retrieve Knowledge → [2] Select Skills → [3] Execute Workflow → Response
+```
+
+| Aspect | Knowledge | Skills | Workflows |
+| --- | --- | --- | --- |
+| **Role** | Background context | Professional tools | Strict procedures |
+| **Activation** | Automatic (when relevant) | On-demand (when task requires) | Explicit (slash command) |
+| **Format** | Markdown, JSON, YAML | SKILL.md + code/scripts | Markdown with bash commands |
+| **Side effects** | None (read-only) | Yes (executes code) | Yes (runs commands) |
+| **Who invokes** | System (auto-injected) | Agent (decision-based) | User or agent (exact match) |
+
+**Deep dives:** [Knowledge](knowledge.md) · [Skills](skills.md) · [Workflows](workflows.md)
+
+### Additional Components
+
+| Component | Role |
+| --- | --- |
+| **AGENTS.md** | User rules — highest priority, overrides everything |
+| **Plugins** | Bundles grouping skills + subagents + config |
+| **MCP Servers** | External tool providers via JSON-RPC 2.0 |
+
+---
+
+## AGENTS.md — Highest Priority Override
+
+`AGENTS.md` (in `.agents/`) contains user-defined rules that **override everything** — skills, knowledge, workflows, and built-in agent behavior.
+
+> "These rules take precedence over any following instructions."
+
+**Good for:** Language rules, code style mandates, security policies, inviolable conventions.
+**Bad for:** General knowledge (use KIs), how-to guides (use Skills), procedures (use Workflows).
+
+### Context Optimization Patterns
+
+Best practices for helping agents navigate large codebases efficiently:
+
+1. **Source Structure in README.md** — every package/app README should have an annotated `src/` tree with `←` descriptions. This is the agent's "routing table" for navigating code.
+2. **JSDoc navigation headers** — in directories with 20+ files, every file starts with a JSDoc comment (`/** Tool: name — one-line description */`). Agents can scan these without reading full files.
+3. **Threshold rule:** ≤10 files → semantic names sufficient; 10-20 → expand Source Structure in README; 20+ → Source Structure + JSDoc headers.
+
+---
+
+## Plugins
+
+Plugins are **organizational bundles** grouping related skills, subagents, and configuration:
+
+```
+plugins/{name}/
+  plugin.json       # Metadata
+  skills/           # Skills for this plugin
+  agents/           # Subagents for complex tasks
+```
+
+Use plugins when multiple related skills need shared config. Use standalone skills for independent capabilities.
+
+---
+
+## MCP Servers — External Tools
+
+MCP servers extend the agent beyond built-in tools. They provide tools, resources, and prompts via JSON-RPC 2.0 (stdio or Streamable HTTP).
+
+**Context budget:** ~100 tools total across ALL servers, ~20K tokens for definitions. Too many tools → degraded selection quality. Prefer a single `search` tool with dynamic routing over 100+ individual endpoint wrappers.
+
+---
+
+## Conversation Logs — Raw Memory
+
+Beyond KIs, the agent can access raw logs from past conversations:
+
+```
+~/.gemini/antigravity/brain/{conversation-id}/.system_generated/logs/overview.txt
+```
+
+**Priority:** KIs first → Conversation Logs → Fresh research.
+
+Use logs only when: user references a past conversation, a KI is insufficient, or you have a specific Conversation ID.
+
+---
+
+## Planning Mode
+
+The agent's decision-making framework that determines whether to plan before acting:
+
+```
+Phase 1: Research → Read knowledge, explore codebase (NO code changes)
+Phase 2: Plan    → Create implementation_plan.md
+Phase 3: Approve → User reviews and approves
+Phase 4: Execute → Follow plan, track in task.md
+Phase 5: Verify  → Run tests, create walkthrough.md
+```
+
+**Plan required for:** Major architecture changes, extensive research, significant ambiguity.
+**No plan for:** Simple questions, trivial fixes, minor follow-ups.
+
+Artifacts live in: `~/.gemini/antigravity/brain/{conversation-id}/`
+
+---
+
+## How Components Interact
+
+### Example 1: "Create a new MCP server"
+
+1. **Knowledge** → checks KIs for tool limits, conventions
+2. **Skill** → loads `mcp-server-creation` SKILL.md
+3. **Workflow** → follows `mcp-dev.md` for IDE restart cycle
+
+### Example 2: User runs `/deploy`
+
+1. **Workflow** → activates immediately, follows steps
+2. **Knowledge** → checks KI for deployment conventions
+3. **Skills** → references Docker skill if needed
+
+### Example 3: "Fix the login bug"
+
+1. **Knowledge** → checks KIs for known bugs, auth patterns
+2. No specific skill or workflow needed — ad-hoc debugging
+
+---
+
+## Antigravity System Prompt Integration
+
+| Section | Provides |
+| --- | --- |
+| `<skills>` | Available skills list (name + description + path) |
+| `<persistent_context>` | KI system rules + KI summaries |
+| `<workflows>` | Workflow discovery + slash command mapping |
+| `<user_rules>` | AGENTS.md content (highest priority) |
+| `<mcp_servers>` | MCP server definitions |
+
+---
+
+## File Structure Reference
+
+```
+project-root/
+  .agents/
+    AGENTS.md                    # User rules (HIGHEST PRIORITY)
+    knowledge/                   # Per-project KIs
+      {ki-name}/
+        metadata.json
+        artifacts/{content}.md
+    skills/                      # Per-project skills
+      {skill-name}/
+        SKILL.md
+        assets/
+        workflows/
+    workflows/                   # Slash commands
+      {workflow-name}.md
+
+~/.gemini/antigravity/
+  knowledge/                     # Global KIs
+  skills/                        # Global skills
+  settings.json                  # MCP server configs
+  brain/{conversation-id}/       # Logs & artifacts
+    .system_generated/logs/overview.txt
+    implementation_plan.md
+    task.md
+    walkthrough.md
+```
+
+---
+
+## Key Insight
+
+> **AGENTS.md** sets the law — inviolable rules.
+> **Knowledge** makes an agent _useful_ — it understands the domain.
+> **Skills** make it _competent_ — it knows the right tools.
+> **Workflows** make it _reliable_ — consistent execution.
+> **MCP Servers** make it _extensible_ — connected to the world.
+> **Planning Mode** makes it _disciplined_ — thinks before acting.