@musashishao/agent-kit 1.2.2 → 1.3.0

package/.agent/workflows/create.md

@@ -10,7 +10,7 @@ $ARGUMENTS
 
 ## Task
 
-This command starts a new application creation process.
+This command starts a new application creation process with **AI-Ready Infrastructure**.
 
 ### Steps:
 
@@ -31,12 +31,67 @@ This command starts a new application creation process.
      - `backend-specialist` → API
      - `frontend-specialist` → UI
 
-4. **Preview**
+4. **AI Infrastructure Setup** ⭐ NEW
+   - Generate `AGENTS.md` using `documentation-templates/agents-template.md`
+   - Create `.agent/` directory structure:
+     ```
+     .agent/
+     ├── AGENTS.md           # AI Navigation Map
+     ├── graph.json          # Dependency graph (generated)
+     └── rag/                # RAG data directory
+         └── chunks.json     # Code chunks (generated later)
+     ```
+   - Run `graph-mapper` script to generate initial dependency graph
+   - Configure `.cursor/mcp.json` or equivalent for MCP servers
+
+5. **Preview**
    - Start with `auto_preview.py` when complete
    - Present URL to user
 
 ---
 
+## AI Infrastructure Generation
+
+After building the application, automatically generate:
+
+### Step 4.1: Generate AGENTS.md
+
+Create `AGENTS.md` in project root with:
+- Project name and status
+- Tech stack detected from package.json/requirements.txt
+- Directory structure explanation
+- Coding conventions based on detected linter config
+- Available commands (from package.json scripts)
+
+Template: `.agent/skills/documentation-templates/agents-template.md`
+
+### Step 4.2: Generate Dependency Graph
+
+```bash
+# Run graph-mapper to create dependency map
+python .agent/skills/graph-mapper/scripts/generate_graph.py \
+  --src ./src \
+  --output .agent/graph.json \
+  --format both
+```
+
+This creates:
+- `.agent/graph.json` - Machine-readable graph
+- `.agent/graph.md` - Human-readable dependency docs
+
+### Step 4.3: Setup RAG Structure
+
+Create directory structure for future RAG indexing:
+```
+.agent/rag/
+├── .gitkeep
+└── README.md (instructions for chunking)
+```
+
+The `rag-engineering` skill can later be used to index the codebase.
+
+---
+
 ## Usage Examples
 
 ```
@@ -57,3 +112,16 @@ If request is unclear, ask these questions:
 - Who will use it?
 
 Use defaults, add details later.
+
+---
+
+## Output Checklist
+
+After `/create` completes, verify:
+
+- [ ] Application code is generated
+- [ ] `AGENTS.md` exists in project root
+- [ ] `.agent/graph.json` exists with dependencies
+- [ ] Preview is running and accessible
+- [ ] User can continue development with AI assistance
+

package/bin/cli.js

@@ -37,6 +37,7 @@ ${colors.bright}Usage:${colors.reset}
 
 ${colors.bright}Commands:${colors.reset}
   ${colors.cyan}init${colors.reset}          Install .agent folder into current project
+  ${colors.cyan}ai${colors.reset}            AI Infrastructure management (init, sync, status)
   ${colors.cyan}setup-codex${colors.reset}   Sync workflows with Codex CLI slash commands
   ${colors.cyan}codex${colors.reset}         Generate AGENTS.md for Codex CLI (use --template)
   ${colors.cyan}mcp${colors.reset}           MCP server management (setup, list, build)
@@ -47,6 +48,12 @@ ${colors.bright}Commands:${colors.reset}
   ${colors.cyan}update${colors.reset}        Update .agent folder to latest version
   ${colors.cyan}status${colors.reset}        Check installation status
 
+${colors.bright}AI Subcommands:${colors.reset}
+  ${colors.cyan}ai init${colors.reset}       Initialize AI infrastructure (AGENTS.md, Graph, RAG)
+  ${colors.cyan}ai sync${colors.reset}       Sync AI data after code changes
+  ${colors.cyan}ai status${colors.reset}     Show AI infrastructure status
+  ${colors.cyan}ai config${colors.reset}     Auto-configure AI hosts (Claude, Cursor, etc.)
+
 ${colors.bright}MCP Subcommands:${colors.reset}
   ${colors.cyan}mcp setup${colors.reset}     Configure MCP servers for Claude/Cursor
   ${colors.cyan}mcp list${colors.reset}      List available MCP servers
@@ -64,6 +71,8 @@ ${colors.bright}Options:${colors.reset}
 
 ${colors.bright}Examples:${colors.reset}
   npx ${PACKAGE_NAME} init
+  npx ${PACKAGE_NAME} ai init              # Setup AI infrastructure
+  npx ${PACKAGE_NAME} ai sync              # Update after code changes
   npx ${PACKAGE_NAME} mcp setup --client claude
   npx ${PACKAGE_NAME} codex --template web
   npx ${PACKAGE_NAME} doctor
@@ -517,6 +526,85 @@ function doctorCommand() {
   }
 }
 
+// ============================================================================
+// AI Infrastructure Command
+// ============================================================================
+
+function aiCommand(subArgs, options) {
+  const subCommand = subArgs[0];
+  const agentDir = path.join(process.cwd(), '.agent');
+  const cliScript = path.join(agentDir, 'scripts', 'ak_cli.py');
+  
+  // Show help if no subcommand
+  if (!subCommand || subCommand === '--help' || subCommand === '-h') {
+    console.log(`
+${colors.bright}${colors.cyan}🤖 Agent Kit AI Infrastructure${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  ${colors.cyan}ai init${colors.reset}       Initialize AI infrastructure (AGENTS.md, Graph, RAG)
+  ${colors.cyan}ai sync${colors.reset}       Sync AI data after code changes
+  ${colors.cyan}ai status${colors.reset}     Show AI infrastructure status
+  ${colors.cyan}ai config${colors.reset}     Auto-configure AI hosts (Claude, Cursor, etc.)
+
+${colors.bright}Options:${colors.reset}
+  --force       Force regenerate existing files
+  --target      Sync target: all, graph, rag (for sync command)
+
+${colors.bright}Examples:${colors.reset}
+  npx @musashishao/agent-kit ai init
+  npx @musashishao/agent-kit ai sync
+  npx @musashishao/agent-kit ai sync --target graph
+  npx @musashishao/agent-kit ai config --list
+`);
+    return;
+  }
+  
+  // Check if CLI script exists
+  if (!fs.existsSync(cliScript)) {
+    log.error('AI CLI script not found. Make sure Agent Kit is properly installed.');
+    log.info('Run: npx @musashishao/agent-kit init');
+    process.exit(1);
+  }
+  
+  // Build arguments for Python script
+  const pythonArgs = [cliScript, subCommand];
+  
+  // Pass through relevant options
+  if (options.force) {
+    pythonArgs.push('--force');
+  }
+  
+  // Find --target option
+  const targetIndex = subArgs.indexOf('--target');
+  if (targetIndex !== -1 && subArgs[targetIndex + 1]) {
+    pythonArgs.push('--target', subArgs[targetIndex + 1]);
+  }
+  
+  // Find --list option
+  if (subArgs.includes('--list')) {
+    pythonArgs.push('--list');
+  }
+  
+  // Find --copy option
+  if (subArgs.includes('--copy')) {
+    pythonArgs.push('--copy');
+  }
+  
+  // Execute Python CLI
+  try {
+    const { spawnSync } = require('child_process');
+    const result = spawnSync('python3', pythonArgs, {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+    });
+    
+    process.exit(result.status || 0);
+  } catch (error) {
+    log.error(`Failed to run AI command: ${error.message}`);
+    process.exit(1);
+  }
+}
+
 // ============================================================================
 // MCP Command
 // ============================================================================
@@ -1251,6 +1339,9 @@ switch (command) {
   case 'status':
     statusCommand();
     break;
+  case 'ai':
+    aiCommand(args.slice(1), options);
+    break;
   case '--version':
   case '-v':
     showVersion();

package/docs/AI_DATA_INFRASTRUCTURE.md

@@ -0,0 +1,288 @@
+# 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

@@ -0,0 +1,111 @@
+# 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*

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@musashishao/agent-kit",
-  "version": "1.2.2",
-  "description": "AI Agent templates - Skills, Agents, Workflows, and MCP servers for enhanced coding assistance",
+  "version": "1.3.0",
+  "description": "AI Agent templates - Skills, Agents, Workflows, and AI-Ready Data Infrastructure Gateway",
   "main": "index.js",
   "bin": {
     "agent-kit": "./bin/cli.js",
@@ -9,9 +9,14 @@
   },
   "files": [
     "bin",
+    "docs",
     ".agent/agents",
     ".agent/mcp",
+    ".agent/mcp-gateway/dist",
+    ".agent/mcp-gateway/package.json",
+    ".agent/mcp-gateway/src",
     ".agent/rules",
+    ".agent/scripts",
     ".agent/skills",
     ".agent/templates",
     ".agent/workflows",