@agentskillkit/agent-skills 1.0.1 → 3.2.1

package/docs/README.md

@@ -0,0 +1,62 @@
+# Agent Skill Kit Documentation
+
+> Your ideas, our engineering.
+
+---
+
+## 📚 Quick Links
+
+| Document                              | Description                     |
+| ------------------------------------- | ------------------------------- |
+| [Getting Started](getting-started.md) | User guide - build apps with AI |
+
+### Guides
+
+| Guide                                                | Description                   |
+| ---------------------------------------------------- | ----------------------------- |
+| [Context Engineering](guides/context-engineering.md) | Optimize AI context           |
+| [Migration](guides/migration.md)                     | Python → JavaScript migration |
+| [Publishing](guides/publishing.md)                   | npm publishing workflow       |
+| [Versioning](guides/versioning.md)                   | Version management            |
+
+### Reference
+
+| Reference                                       | Description                   |
+| ----------------------------------------------- | ----------------------------- |
+| [Scripts](reference/scripts.md)                 | Validation scripts            |
+| [Skill Standard](reference/skill-standard.md)   | Skill creation guidelines     |
+| [Python Strategy](reference/python-strategy.md) | Hybrid architecture rationale |
+
+---
+
+## 📂 Structure
+
+```
+docs/
+├── getting-started.md
+├── guides/
+│   ├── context-engineering.md
+│   ├── migration.md
+│   ├── publishing.md
+│   └── versioning.md
+├── reference/
+│   ├── scripts.md
+│   ├── skill-standard.md
+│   └── python-strategy.md
+└── archive/
+```
+
+---
+
+## 🚀 Getting Started
+
+1. **Install**: `npx -y add-skill-kit agentskillkit/agent-skills`
+2. **Use**: Type `/build your-idea` in your AI editor
+3. **Learn**: Read [Getting Started](getting-started.md)
+
+---
+
+## 🔗 Related
+
+- [ARCHITECTURE.md](../.agent/ARCHITECTURE.md) - System architecture
+- [GEMINI.md](../.agent/GEMINI.md) - AI rules & protocols

package/docs/archive/plan-v21.md

@@ -0,0 +1,170 @@
+# Project Plan: Agent Skill Kit v2.1.0
+
+## Overview
+
+| Aspect | Value |
+|--------|-------|
+| Goal | Fix v2.0 weaknesses and add production-ready features |
+| Timeline | 1-2 sessions |
+| Complexity | Medium |
+| Base Score | 7.8/10 → Target 9/10 |
+
+---
+
+## Stack (Unchanged)
+
+| Layer | Choice |
+|-------|--------|
+| Runtime | Node.js (ESM) |
+| CLI | @clack/prompts + @clack/core |
+| Storage | YAML files |
+| Testing | Vitest |
+
+---
+
+## Priority Ranking
+
+| Priority | Feature | Impact | Effort |
+|----------|---------|--------|--------|
+| P1 | Auto-Updating Flow | High | Medium |
+| P2 | Ignore Patterns | High | Low |
+| P3 | Backup/Restore | Medium | Low |
+| P4 | Export/Import Settings | Medium | Low |
+| P5 | Team Sync | Medium | High |
+
+---
+
+## Task Breakdown
+
+### Epic 1: Auto-Updating Flow (P1)
+> Implement proposal workflow when patterns are valuable
+
+- [ ] **Story 1.1**: Detect valuable patterns
+  - [ ] Track hitCount in lessons
+  - [ ] Compare with updateThreshold
+  - [ ] Identify candidates
+
+- [ ] **Story 1.2**: Generate update proposal
+  - [ ] Create `SKILL_PROPOSAL.md` template
+  - [ ] Include pattern analysis
+  - [ ] Show before/after
+
+- [ ] **Story 1.3**: User notification flow
+  - [ ] CLI notification in Stats
+  - [ ] Menu option "Review Proposals"
+  - [ ] Approve/Dismiss actions
+
+---
+
+### Epic 2: Ignore Patterns (P2)
+> Add `.agentignore` support
+
+- [ ] **Story 2.1**: Create ignore file parser
+  - [ ] Support glob patterns
+  - [ ] Support comments (#)
+  - [ ] Default ignores: node_modules, .git
+
+- [ ] **Story 2.2**: Integrate with Recall
+  - [ ] Filter files before scan
+  - [ ] Show ignored count in stats
+
+---
+
+### Epic 3: Backup/Restore (P3)
+> Protect lessons before changes
+
+- [ ] **Story 3.1**: Backup command
+  - [ ] `agent backup` → timestamped copy
+  - [ ] Store in `.agent/backups/`
+
+- [ ] **Story 3.2**: Restore command
+  - [ ] `agent restore` → list backups
+  - [ ] Select and restore
+
+---
+
+### Epic 4: Export/Import Settings (P4)
+> Share config between projects
+
+- [ ] **Story 4.1**: Export
+  - [ ] `agent export` → JSON file
+  - [ ] Include settings + lessons
+
+- [ ] **Story 4.2**: Import  
+  - [ ] `agent import <file>`
+  - [ ] Merge or replace option
+
+---
+
+## Architecture: Auto-Updating Flow
+
+```mermaid
+graph TD
+    A[Lesson hitCount >= threshold] --> B{autoUpdating ON?}
+    B -->|Yes| C[Analyze pattern value]
+    B -->|No| X[Skip]
+    C --> D[Generate SKILL_PROPOSAL.md]
+    D --> E[Add to proposals queue]
+    E --> F[Show in Stats/Menu]
+    F --> G{User reviews}
+    G -->|Approve| H[Update skill file]
+    G -->|Dismiss| I[Mark dismissed]
+```
+
+---
+
+## New Files
+
+| File | Purpose |
+|------|---------|
+| `lib/proposals.js` | Proposal generator |
+| `lib/backup.js` | Backup/restore logic |
+| `lib/ignore.js` | Ignore file parser |
+| `lib/export.js` | Export/import settings |
+| `lib/ui/proposals-ui.js` | Proposals review UI |
+| `.agentignore.default` | Default ignore template |
+
+---
+
+## Updated Files
+
+| File | Changes |
+|------|---------|
+| `lib/ui/index.js` | Add "Proposals" menu option |
+| `lib/recall.js` | Integrate ignore patterns |
+| `lib/stats.js` | Show proposal notifications |
+| `bin/ag-smart.js` | Add backup/restore subcommands |
+
+---
+
+## Verification Checklist
+
+- [ ] Auto-Updating flow works end-to-end
+- [ ] `.agentignore` excludes files from scan
+- [ ] Backup creates timestamped copy
+- [ ] Restore recovers from backup
+- [ ] Export/Import preserves data
+- [ ] All existing tests still pass
+- [ ] New tests added for new features
+
+---
+
+## Recommended Order
+
+| Phase | Epic | Estimate |
+|-------|------|----------|
+| 1 | Epic 2: Ignore Patterns | 30m |
+| 2 | Epic 3: Backup/Restore | 30m |
+| 3 | Epic 4: Export/Import | 30m |
+| 4 | Epic 1: Auto-Updating | 1-2h |
+
+> Start with quick wins (P2-P4) then tackle the complex feature (P1).
+
+---
+
+## Next Steps
+
+After approval:
+1. Run `/build Epic 2` for ignore patterns
+2. Continue with remaining epics
+3. Run `/validate` after completion

package/docs/getting-started.md

@@ -0,0 +1,337 @@
+# 📖 Agent Skill Kit - User Guide
+
+> **Agent Skill Kit** giúp bạn làm app mà không cần biết code.
+> Bạn chỉ cần nói ý tưởng, AI sẽ lo phần còn lại.
+
+---
+
+## 🎯 Agent Skill Kit dùng để làm gì?
+
+| Bạn muốn... | Agent Skill Kit giúp bạn... |
+|-------------|-----------------|
+| Làm app mới | Từ ý tưởng → App hoàn chỉnh |
+| Thêm tính năng | Thiết kế → Code → Test tự động |
+| Sửa lỗi | Tìm lỗi → Sửa → Kiểm tra |
+| Deploy lên server | Cấu hình → Đẩy lên → Theo dõi |
+
+---
+
+## 🗺️ Bản đồ các lệnh Agent Skill Kit
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                     AGENT SKILL KIT WORKFLOW MAP                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ╔═══════════════════════════════════════════════════════════════════════╗  │
+│  ║                    🌟 KHỞI ĐẦU & TÌM HIỂU                             ║  │
+│  ╠═══════════════════════════════════════════════════════════════════════╣  │
+│  ║  /think       │  /architect  │  /pulse       │  /agent                ║  │
+│  ║  Bàn ý tưởng  │  Lập kế hoạch│  Xem tiến độ  │  CLI thông minh        ║  │
+│  ╚═══════════════════════════════════════════════════════════════════════╝  │
+│                              │                                              │
+│                              ▼                                              │
+│  ╔═══════════════════════════════════════════════════════════════════════╗  │
+│  ║                    🎯 THIẾT KẾ & XÂY DỰNG                             ║  │
+│  ╠═══════════════════════════════════════════════════════════════════════╣  │
+│  ║  /build                   │  /studio                                  ║  │
+│  ║  Tạo app từ đầu           │  Thiết kế UI với 50+ styles               ║  │
+│  ╚═══════════════════════════════════════════════════════════════════════╝  │
+│                              │                                              │
+│                              ▼                                              │
+│  ╔═══════════════════════════════════════════════════════════════════════╗  │
+│  ║                    💻 CẢI TIẾN & KIỂM TRA                             ║  │
+│  ╠═══════════════════════════════════════════════════════════════════════╣  │
+│  ║  /boost       │  /validate     │  /inspect                            ║  │
+│  ║  Nâng cấp     │  Chạy tests    │  Code review                         ║  │
+│  ╚═══════════════════════════════════════════════════════════════════════╝  │
+│                              │                                              │
+│                              ▼                                              │
+│  ╔═══════════════════════════════════════════════════════════════════════╗  │
+│  ║                    🚀 TRIỂN KHAI & BẢO TRÌ                            ║  │
+│  ╠═══════════════════════════════════════════════════════════════════════╣  │
+│  ║  /launch   │  /diagnose  │  /stage     │  /autopilot                  ║  │
+│  ║  Deploy    │  Debug      │  Preview    │  Tự động hóa                 ║  │
+│  ╚═══════════════════════════════════════════════════════════════════════╝  │
+│                              │                                              │
+│                              ▼                                              │
+│  ╔═══════════════════════════════════════════════════════════════════════╗  │
+│  ║                    📚 TÀI LIỆU & MỞ RỘNG                              ║  │
+│  ╠═══════════════════════════════════════════════════════════════════════╣  │
+│  ║  /chronicle               │  /forge                                   ║  │
+│  ║  Tự động viết docs        │  Tạo skill mới                            ║  │
+│  ╚═══════════════════════════════════════════════════════════════════════╝  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+# 📚 3 KỊCH BẢN SỬ DỤNG
+
+---
+
+## 🆕 KỊCH BẢN 1: Tạo App Mới Từ Đầu
+
+> **Tình huống:** Bạn có ý tưởng và muốn làm app từ con số 0.
+
+### Luồng hoạt động:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                                                             │
+│   BẠN CÓ Ý TƯỞNG                                                            │
+│   "Em muốn làm app quản lý tiệm cà phê"                                     │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 1: /think (Nếu ý tưởng còn mơ hồ)                              │   │
+│   │                                                                     │   │
+│   │ AI sẽ hỏi:                                                          │   │
+│   │ • "App giải quyết vấn đề gì?"                                       │   │
+│   │ • "Ai sẽ dùng? Chủ tiệm hay nhân viên?"                             │   │
+│   │ • "Có muốn em tìm xem thị trường có app tương tự không?"            │   │
+│   │                                                                     │   │
+│   │ → Output: Phân tích 3+ alternatives                                 │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 2: /architect (Lập kế hoạch chi tiết)                          │   │
+│   │                                                                     │   │
+│   │ AI sẽ:                                                              │   │
+│   │ • Phân tích task breakdown                                          │   │
+│   │ • Chọn tech stack phù hợp                                           │   │
+│   │ • Tạo PLAN.md chi tiết                                              │   │
+│   │                                                                     │   │
+│   │ → Output: Blueprint hoàn chỉnh (không code)                         │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 3: /build (Tạo app)                                            │   │
+│   │                                                                     │   │
+│   │ AI TỰ LÀM:                                                          │   │
+│   │ • Tạo cấu trúc project                                              │   │
+│   │ • Viết code frontend + backend                                      │   │
+│   │ • Multi-agent coordination                                          │   │
+│   │                                                                     │   │
+│   │ → Output: App hoàn chỉnh, sẵn sàng chạy                             │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 4: /studio (Thiết kế UI - Optional)                            │   │
+│   │                                                                     │   │
+│   │ AI cung cấp:                                                        │   │
+│   │ • 50+ design styles                                                 │   │
+│   │ • 95+ color palettes                                                │   │
+│   │ • Anti-AI-slop design intelligence                                  │   │
+│   │                                                                     │   │
+│   │ → Output: UI đẹp, không generic                                     │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 5: /validate (Kiểm tra)                                        │   │
+│   │                                                                     │   │
+│   │ AI sẽ:                                                              │   │
+│   │ • Tự động generate tests                                            │   │
+│   │ • Chạy test suite                                                   │   │
+│   │ • Phân tích coverage                                                │   │
+│   │                                                                     │   │
+│   │ Nếu có lỗi → /diagnose để sửa                                       │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 6: /launch (Đưa lên production)                                │   │
+│   │                                                                     │   │
+│   │ AI TỰ LÀM:                                                          │   │
+│   │ • Security scan                                                     │   │
+│   │ • Build verification                                                │   │
+│   │ • Zero-downtime deployment                                          │   │
+│   │ • Health checks                                                     │   │
+│   │                                                                     │   │
+│   │ → Output: App live trên internet!                                   │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│   🎉 HOÀN THÀNH! App của bạn đã live!                                       │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Tóm tắt luồng:
+```
+/think → /architect → /build → /studio → /validate → /launch
+```
+
+---
+
+## 📦 KỊCH BẢN 2: Nâng Cấp App Có Sẵn
+
+> **Tình huống:** Bạn đã có app đang chạy, muốn thêm features.
+
+### Luồng hoạt động:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                                                             │
+│   BẠN CÓ APP SẴN                                                            │
+│   (Đã có code, đang chạy)                                                   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 1: /pulse (Xem tình trạng project)                             │   │
+│   │                                                                     │   │
+│   │ AI sẽ hiển thị:                                                     │   │
+│   │ • Agent status                                                      │   │
+│   │ • File statistics                                                   │   │
+│   │ • Real-time progress                                                │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 2: /boost (Thêm/cập nhật features)                             │   │
+│   │                                                                     │   │
+│   │ AI sẽ:                                                              │   │
+│   │ • Phân tích dependencies                                            │   │
+│   │ • Iterative upgrades                                                │   │
+│   │ • Đảm bảo không break existing code                                 │   │
+│   │                                                                     │   │
+│   │ → Output: Features mới được thêm an toàn                            │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 3: /inspect (Code review)                                      │   │
+│   │                                                                     │   │
+│   │ Multi-layer validation:                                             │   │
+│   │ • Defense-in-depth review                                           │   │
+│   │ • Prevent false completion claims                                   │   │
+│   │ • Security + performance check                                      │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ BƯỚC 4: /validate → /launch                                         │   │
+│   │                                                                     │   │
+│   │ Kiểm tra và deploy như bình thường                                  │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│   🎉 FEATURES MỚI ĐÃ LIVE!                                                  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Tóm tắt luồng:
+```
+/pulse → /boost → /inspect → /validate → /launch
+```
+
+---
+
+## 🤖 KỊCH BẢN 3: Tự Động Hóa Hoàn Toàn
+
+> **Tình huống:** Bạn muốn AI tự làm hết từ A-Z.
+
+### Luồng hoạt động:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                                                             │
+│   BẠN NÓI Ý TƯỞNG                                                           │
+│   "Làm cho anh app quản lý task giống Notion"                               │
+│          │                                                                  │
+│          ▼                                                                  │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ /autopilot                                                          │   │
+│   │                                                                     │   │
+│   │ AI sẽ TỰ ĐỘNG:                                                      │   │
+│   │ • Điều phối 3+ specialist agents                                    │   │
+│   │ • Làm việc song song                                                │   │
+│   │ • Self-verification                                                 │   │
+│   │                                                                     │   │
+│   │ Các agents phối hợp:                                                │   │
+│   │ • @frontend-specialist - UI/UX                                      │   │
+│   │ • @backend-specialist - API, Database                               │   │
+│   │ • @security-auditor - Bảo mật                                       │   │
+│   │ • @test-engineer - Testing                                          │   │
+│   │                                                                     │   │
+│   │ → Output: App hoàn chỉnh, đã test, sẵn sàng deploy                  │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│   🎉 CHỈ CẦN 1 LỆNH - AI LO HẾT!                                            │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Tóm tắt:
+```
+/autopilot → Xong!
+```
+
+---
+
+## 🆘 KHI GẶP KHÓ KHĂN
+
+### Bị lỗi?
+```
+Gõ: /diagnose
+→ AI tìm root cause với evidence-based debugging
+```
+
+### Cần chạy preview?
+```
+Gõ: /stage
+→ Start/stop/restart preview servers
+```
+
+### Muốn viết documentation?
+```
+Gõ: /chronicle
+→ Auto-generate README, API docs, inline comments
+```
+
+### Muốn tạo skill mới?
+```
+Gõ: /forge
+→ Create, validate, package new capabilities
+```
+
+---
+
+## 📊 BẢNG TÓM TẮT 15 LỆNH
+
+| Lệnh | Khi nào dùng | Output |
+|------|--------------|--------|
+| `/think` | Có ý tưởng, cần phân tích | 3+ alternatives analysis |
+| `/architect` | Cần blueprint chi tiết | PLAN.md (no code) |
+| `/build` | Tạo app mới từ đầu | Full-stack app |
+| `/boost` | Thêm features vào app có sẵn | Iterative upgrades |
+| `/studio` | Thiết kế UI đẹp | 50+ styles, anti-AI-slop |
+| `/validate` | Kiểm tra app | Test results + coverage |
+| `/inspect` | Code review | Multi-layer validation |
+| `/diagnose` | Debug lỗi | Root cause + fix |
+| `/launch` | Deploy lên production | Zero-downtime release |
+| `/stage` | Preview/staging server | Local dev environment |
+| `/autopilot` | Tự động hóa hoàn toàn | Multi-agent coordination |
+| `/chronicle` | Viết documentation | README, API docs |
+| `/forge` | Tạo skill mới | Packaged capability |
+| `/pulse` | Xem tiến độ project | Health dashboard |
+| `/agent` | CLI thông minh | Interactive commands |
+
+---
+
+## 💡 MẸO SỬ DỤNG
+
+1. **Mới bắt đầu:** `/think` để khám phá options
+2. **Cần plan:** `/architect` để có blueprint trước khi code
+3. **Muốn nhanh:** `/autopilot` để AI tự làm hết
+4. **Trước release:** `/validate` + `/inspect` + `/launch`
+5. **Nói tự nhiên:** AI sẽ tự động chọn agent phù hợp
+
+---
+
+*Agent Skill Kit*
+*Your ideas, our engineering.*

package/docs/guides/migration.md

@@ -0,0 +1,70 @@
+# Migration Guide
+
+> Python → JavaScript migration for Agent Skill Kit
+
+---
+
+## ✅ Status: Fully Migrated (v3.2.0)
+
+**All master scripts and Studio scripts migrated to JavaScript.** Zero Python dependency required.
+
+---
+
+## 📦 Current Scripts
+
+| Script               | npm Command              |
+| -------------------- | ------------------------ |
+| `checklist.js`       | `npm run checklist`      |
+| `verify_all.js`      | `npm run verify <URL>`   |
+| `auto_preview.js`    | `npm run preview:start`  |
+| `session_manager.js` | `npm run session:status` |
+| `rebrand/index.mjs`  | `npm run rebrand`        |
+
+**Location:** `.agent/scripts-js/*.js`
+
+---
+
+## 🎨 Studio Scripts
+
+| Component               | JavaScript         | LOC |
+| ----------------------- | ------------------ | --- |
+| Core Search Engine      | `core.js`          | 320 |
+| Design System Generator | `design_system.js` | 700 |
+| CLI Entry Point         | `search.js`        | 180 |
+
+### Usage
+
+```bash
+# Design system generation
+node .agent/skills/studio/scripts-js/search.js "SaaS dashboard" --design-system -p "MyProject"
+
+# npm scripts (recommended)
+npm run studio:design "SaaS dashboard" -- -p "MyProject"
+npm run studio:search "glassmorphism" -- --domain style
+```
+
+---
+
+## 🚀 Benefits
+
+- ✅ **Zero Python dependency** - Node.js only
+- ✅ **Better Windows support** - No PATH issues
+- ✅ **Unified stack** - 100% JavaScript
+- ✅ **~10% faster** - Native async I/O
+
+---
+
+## 🐍 Python Skill Scripts (Kept)
+
+**34 Python scripts** remain for specialized validation (security scanning, E2E testing, etc.).
+
+See [python-strategy.md](../reference/python-strategy.md) for details.
+
+---
+
+## 🧪 Testing
+
+```bash
+npm run test:studio  # 143 tests
+npm run test         # CLI integration
+```