@musashishao/agent-kit 1.8.2 → 1.9.1

package/docs/AI_DATA_INFRASTRUCTURE.md

@@ -1,288 +0,0 @@
-# AI Data Infrastructure - User Guide
-
-> Transform your project into an "AI-Ready" smart repository with Agent Kit's integrated data infrastructure.
-
----
-
-## 🎯 Overview
-
-Agent Kit provides a 4-layer AI Data Infrastructure that makes your project deeply understandable to AI agents:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    AI DATA INFRASTRUCTURE                        │
-├─────────────────────────────────────────────────────────────────┤
-│  Layer 1: AGENTS.md         → Project overview & navigation     │
-│  Layer 2: graph-mapper      → Dependency relationships          │
-│  Layer 3: rag-engineering   → Semantic code search              │
-│  Layer 4: MCP Gateway       → Live connection to AI agents      │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 🚀 Quick Start
-
-### For New Projects
-
-```bash
-# Create a new project with AI infrastructure
-npx @musashishao/agent-kit init
-npx @musashishao/agent-kit ai init
-```
-
-### For Existing Projects
-
-```bash
-# Add AI infrastructure to existing project
-cd your-project
-npx @musashishao/agent-kit init
-npx @musashishao/agent-kit ai init
-```
-
-After initialization, your project will have:
-- `AGENTS.md` - AI navigation map
-- `.agent/graph.json` - Dependency graph
-- `.agent/mcp-gateway/` - MCP server for AI connectivity
-- `.cursor/mcp.json` - Auto-configured for Cursor
-
----
-
-## 📋 Commands Reference
-
-### `ai init`
-Initialize AI infrastructure for your project.
-
-```bash
-npx @musashishao/agent-kit ai init
-npx @musashishao/agent-kit ai init --force  # Regenerate existing files
-```
-
-**What it does:**
-1. Creates `.agent/` directory structure
-2. Generates `AGENTS.md` with auto-detected tech stack
-3. Builds dependency graph from your source code
-4. Configures AI hosts (Claude, Cursor, VS Code)
-
-### `ai sync`
-Update AI data after code changes.
-
-```bash
-npx @musashishao/agent-kit ai sync                # Sync everything
-npx @musashishao/agent-kit ai sync --target graph # Sync only graph
-npx @musashishao/agent-kit ai sync --target rag   # Sync only RAG
-```
-
-**When to use:**
-- After significant code changes
-- After adding/removing files
-- Before major AI-assisted refactoring
-
-### `ai status`
-Show current AI infrastructure status.
-
-```bash
-npx @musashishao/agent-kit ai status
-```
-
-**Output example:**
-```
-📊 Agent Kit Status
-📦 Core Components:
-  ✅ AGENTS.md
-  ✅ MCP Gateway
-  ✅ Dependency Graph
-  ❌ RAG Chunks: Not found
-
-⏰ Sync Status:
-  Last sync: 2026-01-24T16:50:00
-```
-
-### `ai config`
-Configure AI hosts to use Agent Kit.
-
-```bash
-npx @musashishao/agent-kit ai config          # Auto-configure all
-npx @musashishao/agent-kit ai config --list   # List detected hosts
-npx @musashishao/agent-kit ai config --copy   # Copy config to clipboard
-```
-
----
-
-## 🔧 How It Works
-
-### Auto-Sync (Magic!)
-
-When AI agents query your project through the MCP Gateway, the system automatically:
-
-1. **Checks timestamps** - Are source files newer than cached data?
-2. **Syncs if needed** - Only updates changed files (incremental)
-3. **Debounces** - Prevents excessive syncing (30s cooldown)
-4. **Returns fresh data** - AI always gets accurate information
-
-```
-AI asks "What does login.ts do?"
-        │
-        ▼
-MCP Gateway checks: Is data fresh?
-        │
-    ┌───┴───┐
-    │       │
-   YES      NO
-    │       │
-    ▼       ▼
-Return    Auto-sync
-cached    changed files
-data          │
-              ▼
-         Return fresh data
-```
-
-### Impact Analysis
-
-Before editing a file, ask AI: "What will be affected if I change auth.ts?"
-
-The system uses the dependency graph to show:
-- Which files import `auth.ts`
-- Which files import THOSE files
-- Total impact radius
-
----
-
-## 📁 File Structure
-
-After initialization, your project will have:
-
-```
-your-project/
-├── AGENTS.md               # AI navigation map (Layer 1)
-├── .agent/
-│   ├── graph.json          # Dependency graph (Layer 2)
-│   ├── graph.md            # Human-readable dependencies
-│   ├── mcp-gateway/        # MCP server (Layer 4)
-│   │   ├── src/
-│   │   └── dist/
-│   ├── rag/                # RAG data (Layer 3)
-│   │   └── chunks.json
-│   ├── .cache/             # Sync timestamps
-│   └── scripts/            # CLI scripts
-├── .cursor/
-│   └── mcp.json            # Cursor MCP config
-└── .vscode/
-    └── settings.json       # VS Code MCP config (if applicable)
-```
-
----
-
-## 🔌 MCP Tools Available
-
-When connected via MCP, AI agents have access to:
-
-| Tool | Description |
-|------|-------------|
-| `get_project_context` | Read project overview from AGENTS.md |
-| `analyze_dependencies` | Get imports/exports for a file |
-| `search_code_logic` | Semantic search through codebase |
-| `get_impact_zone` | Find all affected files for a change |
-| `force_sync` | Manually refresh all AI data |
-
----
-
-## 🎯 Best Practices
-
-### 1. Keep AGENTS.md Updated
-While auto-generated, customize `AGENTS.md` with:
-- Current sprint focus
-- Team conventions not in linter config
-- Known gotchas
-
-### 2. Sync Before Big Changes
-```bash
-npx @musashishao/agent-kit ai sync
-```
-Then ask AI to help with refactoring.
-
-### 3. Use Impact Analysis
-Before editing shared utilities:
-```
-Me: What happens if I change the Button component?
-AI: [Uses get_impact_zone] Button is imported by 12 components...
-```
-
-### 4. Trust the Auto-Sync
-You don't need to manually sync after every save. The MCP Gateway handles this automatically when AI makes queries.
-
----
-
-## 🔍 Troubleshooting
-
-### "MCP Gateway not found"
-```bash
-cd .agent/mcp-gateway
-npm install
-npm run build
-```
-
-### "Dependency graph is empty"
-Make sure you have a `src/` or `app/` directory with code files.
-
-### "AI host not configured"
-```bash
-npx @musashishao/agent-kit ai config --copy
-# Paste into your AI host's MCP settings
-```
-
-### "Sync takes too long"
-For large projects (100k+ LOC), initial sync may take 30-60 seconds. Subsequent syncs are incremental and faster.
-
----
-
-## 🏗️ Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        YOUR PROJECT                              │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  Source Code          AI Infrastructure                         │
-│  ┌─────────┐          ┌────────────────────────────────────┐   │
-│  │ src/    │◄────────►│ AGENTS.md (Navigation Map)         │   │
-│  │ app/    │          │ graph.json (Dependency Graph)      │   │
-│  │ lib/    │          │ rag/chunks.json (Code Chunks)      │   │
-│  └─────────┘          └────────────────────────────────────┘   │
-│                                      ▲                          │
-│                                      │                          │
-│                        ┌─────────────┴─────────────┐           │
-│                        │     MCP GATEWAY SERVER     │           │
-│                        │                            │           │
-│                        │  • Auto-sync on query      │           │
-│                        │  • Debounced updates       │           │
-│                        │  • Incremental changes     │           │
-│                        └─────────────┬─────────────┘           │
-│                                      │                          │
-└──────────────────────────────────────┼──────────────────────────┘
-                                       │ MCP Protocol
-                                       ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                         AI HOSTS                                 │
-│                                                                  │
-│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
-│   │ Claude       │  │ Cursor       │  │ Antigravity  │         │
-│   │ Desktop      │  │ / Windsurf   │  │ IDE / Codex  │         │
-│   └──────────────┘  └──────────────┘  └──────────────┘         │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 📚 Related Documentation
-
-- [AGENTS.md Template](/.agent/skills/documentation-templates/agents-template.md)
-- [Graph Mapper Skill](/.agent/skills/graph-mapper/SKILL.md)
-- [RAG Engineering Skill](/.agent/skills/rag-engineering/SKILL.md)
-- [MCP Builder Skill](/.agent/skills/mcp-builder/SKILL.md)
-
----
-
-*Generated by Agent Kit v1.0.0*

package/docs/CHANGELOG_AI_INFRA.md

@@ -1,111 +0,0 @@
-# AI Data Infrastructure - Changelog
-
-All notable changes to the AI Data Infrastructure are documented here.
-
----
-
-## [1.0.0] - 2026-01-24
-
-### Added
-
-#### Phase 1: MCP Gateway Server Core
-- Created MCP Gateway Server (`/.agent/mcp-gateway/`)
-- Implemented 5 MCP tools:
-  - `get_project_context` - Read AGENTS.md sections
-  - `analyze_dependencies` - Query dependency graph
-  - `search_code_logic` - Semantic code search
-  - `get_impact_zone` - Find affected files for changes
-  - `force_sync` - Refresh all AI data
-- TypeScript implementation with strict mode
-- Compatible with Claude Desktop, Cursor, VS Code, Windsurf
-
-#### Phase 2: Auto-Sync Engine
-- `TimestampChecker` - Tracks file modification times
-- `IncrementalSyncer` - Updates only changed files
-- `Debouncer` - 30-second cooldown between syncs
-- Integrated auto-sync into MCP tools
-- Just-in-time data refresh on AI queries
-
-#### Phase 3: Auto-Config System
-- `setup_host.py` - Auto-configures AI hosts
-- Config templates for Claude Desktop, Cursor, VS Code
-- OS detection (Mac, Windows, Linux)
-- Backup before modifying existing configs
-- Clipboard copy for manual setup
-- `verify_install.py` - Installation health check
-
-#### Phase 4: CLI Wrapper
-- `ak_cli.py` - Main CLI entry point
-- Commands:
-  - `ai init` - Initialize AI infrastructure
-  - `ai sync` - Sync AI data
-  - `ai status` - Show infrastructure status
-  - `ai config` - Configure AI hosts
-- Integrated into `bin/cli.js` as `ai` subcommand group
-
-#### Phase 5: Documentation
-- `docs/AI_DATA_INFRASTRUCTURE.md` - Comprehensive user guide
-- Updated `ARCHITECTURE.md` with AI Infrastructure section
-- Added skill references and documentation links
-
-### New Skills Added
-- `graph-mapper` - Lightweight Knowledge Graph generator
-- `rag-engineering` - Smart code chunking and semantic search
-- `documentation-templates/agents-template.md` - AGENTS.md template
-
-### Updated Skills
-- `app-builder` - Added AI Infrastructure generation step
-- `documentation-templates` - Added AGENTS.md reference
-
-### Updated Workflows
-- `/create` - Now includes AI Infrastructure setup (Step 4)
-
----
-
-## File Summary
-
-| Category | Files Created |
-|----------|---------------|
-| **MCP Gateway** | 8 files (`/mcp-gateway/src/`) |
-| **Skills** | 9 files (`graph-mapper/`, `rag-engineering/`) |
-| **Scripts** | 4 files (`ak_cli.py`, `setup_host.py`, etc.) |
-| **Templates** | 4 files (`mcp_configs/`, `agents-template.md`) |
-| **Documentation** | 2 files |
-| **Total** | ~27 new files |
-
----
-
-## Architecture
-
-```
-Agent Kit v5.0+ with AI Data Infrastructure
-============================================
-
-     ┌─────────────────────────────────────────┐
-     │            USER PROJECT                 │
-     └───────────────────┬─────────────────────┘
-                         │
-     ┌───────────────────▼─────────────────────┐
-     │          AI DATA INFRASTRUCTURE         │
-     │                                         │
-     │  ┌─────────┐ ┌─────────┐ ┌─────────┐   │
-     │  │AGENTS.md│ │ Graph   │ │   RAG   │   │
-     │  │ (Map)   │ │ (KG)    │ │(Chunks) │   │
-     │  └────┬────┘ └────┬────┘ └────┬────┘   │
-     │       └───────────┼───────────┘        │
-     │                   │                     │
-     │          ┌────────▼────────┐           │
-     │          │   MCP GATEWAY   │           │
-     │          │  (Auto-Sync)    │           │
-     │          └────────┬────────┘           │
-     └───────────────────┼─────────────────────┘
-                         │ MCP Protocol
-     ┌───────────────────▼─────────────────────┐
-     │              AI HOSTS                   │
-     │  Claude │ Cursor │ Windsurf │ Codex    │
-     └─────────────────────────────────────────┘
-```
-
----
-
-*Documented by Agent Kit on 2026-01-24*