@musashishao/agent-kit 1.2.2 → 1.3.0

package/.agent/skills/documentation-templates/agents-template.md

@@ -0,0 +1,202 @@
+# AGENTS.md Template
+
+> Template for creating `AGENTS.md` - The AI Navigation Map for your project.
+
+---
+
+## What is AGENTS.md?
+
+`AGENTS.md` is the **first file AI reads** when entering your codebase. It provides:
+- Project overview and current state
+- Directory structure explanation
+- Coding conventions and rules
+- Tool/MCP configuration hints
+
+---
+
+## Template
+
+Copy and customize this template for your project:
+
+```markdown
+# AGENTS.md
+
+> AI Navigation Map for [PROJECT_NAME]
+
+---
+
+## 📊 Project Pulse
+
+| Metric | Value |
+|--------|-------|
+| **Status** | 🟢 Active / 🟡 Maintenance / 🔴 Legacy |
+| **Version** | 1.0.0 |
+| **Last Updated** | YYYY-MM-DD |
+| **Primary Language** | TypeScript / Python / Go |
+
+---
+
+## 🛠️ Tech Stack
+
+| Layer | Technology | Notes |
+|-------|------------|-------|
+| **Frontend** | Next.js 15 + React 19 | App Router |
+| **Styling** | Tailwind CSS v4 | CSS-first config |
+| **Backend** | Node.js / FastAPI | REST API |
+| **Database** | PostgreSQL + Prisma | Neon serverless |
+| **Auth** | NextAuth.js v5 | OAuth + Credentials |
+| **Testing** | Vitest + Playwright | Unit + E2E |
+
+---
+
+## 📁 Directory Map
+
+```
+project-root/
+├── src/
+│   ├── app/           # Next.js App Router pages
+│   ├── components/    # React components
+│   │   ├── ui/        # Base UI primitives
+│   │   └── features/  # Feature-specific components
+│   ├── lib/           # Utilities and helpers
+│   ├── hooks/         # Custom React hooks
+│   └── types/         # TypeScript type definitions
+├── prisma/            # Database schema & migrations
+├── public/            # Static assets
+├── tests/             # Test files (mirrors src/)
+└── .agent/            # AI agent configuration
+```
+
+### Critical Paths
+
+| Path | Purpose | ⚠️ Caution |
+|------|---------|------------|
+| `src/lib/auth.ts` | Auth configuration | Security-critical |
+| `prisma/schema.prisma` | Database schema | Requires migration |
+| `.env.local` | Environment secrets | Never commit |
+
+### Off-Limits (Do Not Modify)
+
+- `node_modules/` - Dependencies
+- `.next/` - Build artifacts
+- `legacy/` - Deprecated code (reference only)
+
+---
+
+## 📜 Rules & Conventions
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase | `UserProfile.tsx` |
+| Hooks | camelCase with `use` prefix | `useAuth.ts` |
+| Utils | camelCase | `formatDate.ts` |
+| Types | PascalCase with suffix | `UserType.ts` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
+
+### Code Style
+
+- **TypeScript Strict Mode** - No `any` types allowed
+- **Functional Components** - No class components
+- **Server-First** - Prefer Server Components, use `'use client'` sparingly
+- **Barrel Exports** - Use `index.ts` for clean imports
+
+### Git Commit Format
+
+```
+type(scope): description
+
+feat(auth): add OAuth login
+fix(api): handle null response
+docs(readme): update installation guide
+```
+
+---
+
+## 🔧 Commands Reference
+
+| Task | Command |
+|------|---------|
+| Dev server | `npm run dev` |
+| Build | `npm run build` |
+| Test | `npm run test` |
+| Lint | `npm run lint` |
+| DB migrate | `npx prisma migrate dev` |
+| DB studio | `npx prisma studio` |
+
+---
+
+## 🤖 AI Agent Instructions
+
+### When Modifying Code
+
+1. **Check Dependencies First** - Before editing a file, trace its imports/exports
+2. **Run Tests After Changes** - Always verify with `npm run test`
+3. **Update Types** - If changing data structures, update `types/` accordingly
+
+### When Creating New Features
+
+1. Follow existing folder structure patterns
+2. Create component in appropriate directory
+3. Add types to `types/` folder
+4. Write tests in `tests/` mirroring source path
+
+### MCP Servers Available
+
+| Server | Purpose | When to Use |
+|--------|---------|-------------|
+| `filesystem` | Read/write project files | File operations |
+| `database` | Query PostgreSQL | Data operations |
+| `github` | GitHub API access | PR/Issue management |
+
+---
+
+## 📈 Current Sprint Focus
+
+> Update this section to guide AI on current priorities
+
+- [ ] Feature: User dashboard redesign
+- [ ] Bug: Fix mobile navigation
+- [ ] Tech debt: Migrate to React 19
+
+---
+
+## 🔗 Related Documentation
+
+- [API Documentation](./docs/api.md)
+- [Component Storybook](./docs/components.md)
+- [Database Schema](./docs/database.md)
+
+---
+
+*Last generated: YYYY-MM-DD*
+```
+
+---
+
+## Usage Guidelines
+
+### When to Create AGENTS.md
+
+- ✅ New projects (create during `/create` workflow)
+- ✅ Before major AI-assisted refactoring
+- ✅ When onboarding new team members
+
+### Maintenance
+
+- Update when directory structure changes
+- Review monthly for accuracy
+- Automate updates with `graph-mapper` skill (if available)
+
+### Placement
+
+Always place `AGENTS.md` in the **project root** directory.
+
+---
+
+## Integration with Agent Kit
+
+When using Agent Kit's `/create` workflow, this template will be automatically generated with project-specific values filled in.
+
+The `explorer-agent` uses this file as its primary navigation source before diving into code analysis.

package/.agent/skills/graph-mapper/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: graph-mapper
+description: Lightweight Knowledge Graph generator for codebases. Analyzes imports/exports to create dependency maps without external databases. Helps AI understand code relationships and impact zones.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+skills:
+  - architecture
+  - systematic-debugging
+---
+
+# Graph Mapper
+
+> Build a **Lightweight Knowledge Graph** from your codebase - no Neo4j required.
+
+## 🎯 Purpose
+
+This skill generates a **static dependency graph** that helps AI agents:
+1. **Understand Relationships:** Which files import/export what
+2. **Analyze Impact:** What breaks if I change this file?
+3. **Navigate Smartly:** Find related code without RAG guessing
+
+---
+
+## 🔧 Quick Reference
+
+| File | Purpose |
+|------|---------|
+| [scripts/analyze_js.py](scripts/analyze_js.py) | JavaScript/TypeScript dependency analyzer |
+| [scripts/analyze_py.py](scripts/analyze_py.py) | Python dependency analyzer |
+| [scripts/generate_graph.py](scripts/generate_graph.py) | Main graph generator (orchestrates analyzers) |
+
+---
+
+## 📊 Output Formats
+
+### 1. DEPENDENCIES.md (Human + AI readable)
+
+```markdown
+# Dependency Graph
+
+## src/components/Button.tsx
+**Imports:**
+- react
+- ./styles.css
+- ../hooks/useTheme
+
+**Imported by:**
+- src/components/Form.tsx
+- src/pages/Home.tsx
+
+**Impact Zone:** 3 files
+```
+
+### 2. graph.json (Machine readable)
+
+```json
+{
+  "nodes": [
+    {"id": "src/components/Button.tsx", "type": "component"},
+    {"id": "src/hooks/useTheme.ts", "type": "hook"}
+  ],
+  "edges": [
+    {"from": "src/components/Button.tsx", "to": "src/hooks/useTheme.ts", "type": "imports"}
+  ]
+}
+```
+
+---
+
+## 🚀 Usage
+
+### Generate Graph for JavaScript/TypeScript Project
+
+```bash
+python .agent/skills/graph-mapper/scripts/generate_graph.py \
+  --src ./src \
+  --output .agent/graph.json \
+  --format both \
+  --lang typescript
+```
+
+### Generate Graph for Python Project
+
+```bash
+python .agent/skills/graph-mapper/scripts/generate_graph.py \
+  --src ./src \
+  --output .agent/graph.json \
+  --format both \
+  --lang python
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--src` | Source directory to analyze | `./src` |
+| `--output` | Output file path | `.agent/graph.json` |
+| `--format` | Output format: `json`, `markdown`, `both` | `both` |
+| `--lang` | Language: `typescript`, `python`, `auto` | `auto` |
+| `--depth` | Max depth for transitive dependencies | `3` |
+| `--exclude` | Glob patterns to exclude | `node_modules,__pycache__` |
+
+---
+
+## 🧠 How It Works
+
+### 1. Static Analysis (No Runtime)
+
+```
+Source Files → AST Parsing → Extract Imports/Exports → Build Graph
+```
+
+- **TypeScript/JavaScript:** Regex + AST-like parsing for `import`/`export`/`require`
+- **Python:** Parse `import`/`from...import` statements
+
+### 2. Graph Construction
+
+```
+Nodes = Files (components, modules, utilities)
+Edges = Dependencies (imports, exports, extends)
+```
+
+### 3. Impact Analysis
+
+For any given file, calculate:
+- **Direct dependents:** Files that import this file
+- **Transitive dependents:** Files that depend on dependents
+- **Impact score:** Number of files affected by changes
+
+---
+
+## 🔄 Integration with AI Agents
+
+### When Agent Modifies Code
+
+1. Agent reads `AGENTS.md` for project overview
+2. Agent queries `graph.json` for file dependencies
+3. Agent identifies impact zone before making changes
+4. Agent updates all affected files together
+
+### Example Query (Pseudo-code)
+
+```python
+# AI Agent internal logic
+file_to_modify = "src/utils/formatDate.ts"
+graph = load_graph(".agent/graph.json")
+
+# Find what depends on this file
+dependents = graph.get_dependents(file_to_modify)
+# Returns: ["src/components/DatePicker.tsx", "src/pages/Calendar.tsx"]
+
+# Agent now knows to check these files too
+```
+
+---
+
+## ⚡ Best Practices
+
+### When to Regenerate Graph
+
+| Trigger | Action |
+|---------|--------|
+| New files added | Run `generate_graph.py` |
+| Major refactoring | Run `generate_graph.py` |
+| Before AI-assisted changes | Ensure graph is fresh |
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/update-graph.yml
+on:
+  push:
+    paths:
+      - 'src/**'
+
+jobs:
+  update-graph:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: python .agent/skills/graph-mapper/scripts/generate_graph.py
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore: update dependency graph"
+```
+
+---
+
+## 🆚 Comparison with Full Graph DB
+
+| Feature | Graph Mapper (This) | Neo4j/Full Graph |
+|---------|---------------------|------------------|
+| **Setup** | Zero (just Python) | Docker + Config |
+| **Query Speed** | Fast (file-based) | Faster (indexed) |
+| **Complex Queries** | Limited | Full Cypher |
+| **Storage** | JSON file (~KB) | Database (~MB/GB) |
+| **Best For** | Small-Medium projects | Enterprise scale |
+
+---
+
+## 📋 Checklist
+
+Before using graph data:
+
+- [ ] Graph file exists (`.agent/graph.json`)
+- [ ] Graph is recent (check timestamp)
+- [ ] Excluded paths are correct (no node_modules)
+- [ ] Language detection is accurate
+
+---
+
+> **Remember:** The graph is a snapshot. Keep it updated when code structure changes significantly.