@neyugn/agent-kits 0.2.6 → 0.2.8

package/README.md

@@ -163,7 +163,7 @@ The **Filter Skill** solves the "skill overload" problem by automatically detect
 | **1. Detection**      | Scans for config files (`package.json`, `pubspec.yaml`, `Dockerfile`, etc.) |
 | **2. Recommendation** | Maps detected techstack to required skills                                  |
 | **3. Confirmation**   | Presents changes and asks about future techstack plans                      |
-| **4. Persistence**    | Saves profile to `.agent/workspace-profile.json`                            |
+| **4. Persistence**    | Saves profile to `.agent/profile.json`                                      |
 
 ### Example
 

package/README.vi.md

@@ -155,7 +155,7 @@ Hoạt động trên **Windows**, **macOS**, và **Linux** với đường dẫn
 | **1. Phát hiện** | Quét các file config (`package.json`, `pubspec.yaml`, `Dockerfile`, etc.) |
 | **2. Đề xuất**   | Map techstack đã phát hiện với các skills cần thiết                       |
 | **3. Xác nhận**  | Hiển thị thay đổi và hỏi về kế hoạch techstack tương lai                  |
-| **4. Lưu trữ**   | Lưu profile vào `.agent/workspace-profile.json`                           |
+| **4. Lưu trữ**   | Lưu profile vào `.agent/profile.json`                                     |
 
 ### Ví dụ
 

package/README.zh.md

@@ -155,7 +155,7 @@ npx @neyugn/agent-kits
 | **1. 检测**   | 扫描配置文件（`package.json`、`pubspec.yaml`、`Dockerfile` 等） |
 | **2. 推荐**   | 将检测到的技术栈映射到所需技能                                  |
 | **3. 确认**   | 显示更改并询问未来的技术栈计划                                  |
-| **4. 持久化** | 将配置保存到 `.agent/workspace-profile.json`                    |
+| **4. 持久化** | 将配置保存到 `.agent/profile.json`                              |
 
 ### 示例
 

package/common/COMMON.md

@@ -6,11 +6,11 @@
 
 ## 🎯 Purpose
 
-Common Skills là một layer đặc biệt chứa các skill được chia sẻ giữa **tất cả các kits**. Những skill này:
+The Common Skills Layer contains special skills that are shared across **all kits**. These skills:
 
-1. **Được cài đặt cùng với mọi kit** - Khi user cài một kit bất kỳ (coder, writer, etc.), common skills cũng được cài theo
-2. **Được đề cập trong ARCHITECTURE.md** của mỗi kit
-3. **Có workflow riêng** - Chỉ được gọi khi user sử dụng slash command tương ứng
+1. **Installed with every kit** - When a user installs any kit (coder, writer, etc.), common skills are installed automatically
+2. **Referenced in ARCHITECTURE.md** - Each kit's architecture document mentions these skills
+3. **Have dedicated workflows** - Invoked only when user calls the corresponding slash command
 
 ---
 
@@ -18,23 +18,31 @@ Common Skills là một layer đặc biệt chứa các skill được chia sẻ
 
 ```plaintext
 common/
-├── COMMON.md               # This file - documentation
-├── skills/                 # Common skills
-│   └── filter-skill/       # Workspace filtering skill
-│       ├── SKILL.md
-│       └── scripts/
-│           └── workspace_analyzer.py
-└── workflows/              # Common workflows
-    └── filter.md           # /filter command
+├── COMMON.md                    # This file - documentation
+├── skills/                      # Common skills
+│   ├── scan-techstack/          # Techstack detection skill
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   │       └── techstack_scanner.py
+│   ├── filter-skill/            # Skill filtering skill
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   │       └── workspace_analyzer.py
+│   └── filter-agent/            # Agent filtering skill
+│       └── SKILL.md
+└── workflows/                   # Common workflows
+    └── filter.md                # /filter command
 ```
 
 ---
 
 ## 🧩 Common Skills
 
-| Skill          | Description                                                                | Workflow  |
-| -------------- | -------------------------------------------------------------------------- | --------- |
-| `filter-skill` | Tự động phân tích workspace và bật/tắt skills/agents phù hợp với techstack | `/filter` |
+| Skill            | Description                                             | Trigger                |
+| ---------------- | ------------------------------------------------------- | ---------------------- |
+| `scan-techstack` | Analyze workspace to detect technologies and frameworks | Part of `/filter` flow |
+| `filter-skill`   | Recommend enable/disable skills based on techstack      | Part of `/filter` flow |
+| `filter-agent`   | Recommend disable agents based on techstack             | Part of `/filter` flow |
 
 ---
 
@@ -42,61 +50,117 @@ common/
 
 ### Installation
 
-Khi user chạy `npx @neyugn/agent-kits`:
+When user runs `npx @neyugn/agent-kits`:
 
-1. User chọn kit (e.g., `coder`)
-2. Installer copy kit vào workspace
-3. Installer copy `common/` skills vào cùng vị trí
-4. Common skills được merge vào architecture của kit
+1. User selects a kit (e.g., `coder`)
+2. Installer copies kit to workspace
+3. Installer copies `common/` skills to the same location
+4. Common skills are merged into the kit's architecture
 
 ### Usage
 
 ```bash
-# User gọi workflow để filter skills
+# User invokes workflow to filter skills and agents
 /filter
 
-# AI sẽ:
-# 1. Phân tích workspace (package.json, pubspec.yaml, etc.)
-# 2. Xác định techstack
-# 3. Đề xuất enable/disable skills
-# 4. Hỏi user xác nhận + techstack tương lai
-# 5. Lưu kết quả vào .agent/workspace-profile.json
+# The workflow will:
+# 1. scan-techstack: Analyze workspace (package.json, pubspec.yaml, etc.)
+# 2. filter-skill: Recommend skill enable/disable based on techstack
+# 3. filter-agent: Recommend agent disable based on techstack
+# 4. Ask user confirmation + future techstack plans
+# 5. Save results to .agent/profile.json
+```
+
+### Workflow Flow
+
+```
+/filter
+  │
+  ├── Step 1: scan-techstack
+  │   └── Output: TechstackProfile (languages, frameworks, categories)
+  │
+  ├── Step 2: filter-skill
+  │   └── Output: SkillRecommendations (enable/disable lists)
+  │
+  ├── Step 3: filter-agent
+  │   └── Output: AgentRecommendations (disable list)
+  │
+  ├── Step 4: User Confirmation
+  │   └── Ask about future techstack plans
+  │
+  └── Step 5: Save to profile.json
 ```
 
 ---
 
 ## 📊 Integration with Kits
 
-Mỗi kit's `ARCHITECTURE.md` PHẢI đề cập:
+Each kit's `ARCHITECTURE.md` MUST mention:
 
 ```markdown
 ## 🔗 Common Skills
 
 This kit inherits from the **Common Skills Layer**. See `common/COMMON.md` for:
 
-- `/filter` - Workspace-aware skill filtering
-- [Future common skills...]
+- `/filter` - Workspace-aware skill and agent filtering
+  - `scan-techstack` - Techstack detection
+  - `filter-skill` - Skill recommendations
+  - `filter-agent` - Agent recommendations
 
 Common skills are automatically installed and available in all kits.
 ```
 
 ---
 
+## 📄 Profile Format
+
+The `/filter` workflow saves results to `.agent/profile.json`:
+
+```json
+{
+  "version": "1.0",
+  "generatedAt": "2026-02-05T12:00:00Z",
+  "analyzedBy": "filter-workflow v1.0",
+  "techstack": {
+    "languages": ["typescript", "python"],
+    "frameworks": ["nextjs", "tailwindcss"],
+    "databases": ["postgresql"],
+    "tools": ["docker", "github-actions"]
+  },
+  "skills": {
+    "enabled": ["react-patterns", "tailwind-patterns", "postgres-patterns"],
+    "disabled": ["flutter-patterns", "mobile-design", "queue-patterns"],
+    "userOverrides": {
+      "force-enabled": ["ai-rag-patterns"],
+      "force-disabled": []
+    }
+  },
+  "agents": {
+    "disabled": ["mobile-developer", "queue-specialist", "realtime-specialist"]
+  },
+  "futureTechstack": ["react-native", "kubernetes"]
+}
+```
+
+---
+
 ## 🚀 Future Common Skills (Planned)
 
-| Skill             | Description                                     | Status  |
-| ----------------- | ----------------------------------------------- | ------- |
-| `context-manager` | Quản lý context length, tự động tóm tắt history | Planned |
-| `memory-skill`    | Lưu trữ và recall thông tin quan trọng          | Planned |
-| `preference-sync` | Đồng bộ preferences của user giữa các sessions  | Planned |
+| Skill             | Description                                   | Status  |
+| ----------------- | --------------------------------------------- | ------- |
+| `context-manager` | Manage context length, auto-summarize history | Planned |
+| `memory-skill`    | Store and recall important information        | Planned |
+| `preference-sync` | Sync user preferences between sessions        | Planned |
 
 ---
 
 ## 📝 Adding Common Skills
 
 1. Create skill folder in `common/skills/`
-2. Create workflow in `common/workflows/`
-3. Update this file's Skills table
-4. Update all kits' ARCHITECTURE.md to reference
+2. Create SKILL.md with proper frontmatter
+3. (Optional) Create scripts/ for automation
+4. Update workflow in `common/workflows/` if needed
+5. Update this file's Skills table
+6. Update all kits' ARCHITECTURE.md to reference
 
 ---

package/common/skills/filter-agent/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: filter-agent
+description: Recommend enabling/disabling agents based on detected techstack. Reduces noise from irrelevant agents in the workspace.
+category: common
+trigger: manual
+---
+
+# Filter Agent Skill
+
+> Workspace-aware agent filtering for optimal AI performance.
+
+---
+
+## 🎯 Purpose
+
+Filter Agent analyzes the **techstack profile** (from scan-techstack) and recommends which agents to **disable** based on project needs. This:
+
+1. **Reduces cognitive load** - AI focuses on relevant agents only
+2. **Improves accuracy** - No confusion from unrelated agent personas
+3. **Optimizes routing** - Orchestrator routes to appropriate specialists
+
+---
+
+## 🤖 Agent Categories
+
+### Tier 1: Master Agents (NEVER DISABLE)
+
+| Agent             | Always Required For              |
+| ----------------- | -------------------------------- |
+| `orchestrator`    | Multi-agent coordination         |
+| `project-planner` | Project planning, task breakdown |
+| `debugger`        | Systematic problem solving       |
+
+### Tier 2: Development Specialists
+
+| Agent                 | Enable When                                |
+| --------------------- | ------------------------------------------ |
+| `frontend-specialist` | Frontend detected (React, Vue, Angular)    |
+| `backend-specialist`  | Backend detected (Express, NestJS, API)    |
+| `mobile-developer`    | Mobile detected (Flutter, RN, iOS/Android) |
+| `database-specialist` | Database detected (Prisma, PostgreSQL)     |
+| `devops-engineer`     | DevOps detected (Docker, K8s, CI/CD)       |
+
+### Tier 3: Quality & Security
+
+| Agent                 | Enable When                                 |
+| --------------------- | ------------------------------------------- |
+| `security-auditor`    | Always enabled for security reviews         |
+| `code-reviewer`       | Always enabled for PR reviews               |
+| `test-engineer`       | Testing detected (Jest, Vitest, Playwright) |
+| `performance-analyst` | Always enabled for optimization             |
+
+### Tier 4: Domain Specialists
+
+| Agent                    | Enable When                                |
+| ------------------------ | ------------------------------------------ |
+| `realtime-specialist`    | Realtime detected (Socket.IO, WS)          |
+| `multi-tenant-architect` | Multi-tenancy patterns detected            |
+| `queue-specialist`       | Queue detected (BullMQ, RabbitMQ)          |
+| `integration-specialist` | External API integrations detected         |
+| `ai-engineer`            | AI detected (OpenAI, LangChain)            |
+| `cloud-architect`        | Cloud infra detected (AWS, GCP, Terraform) |
+| `data-engineer`          | Data pipeline patterns detected            |
+
+### Tier 5: Support Agents
+
+| Agent                  | Enable When                |
+| ---------------------- | -------------------------- |
+| `documentation-writer` | Always enabled for docs    |
+| `i18n-specialist`      | i18n dependencies detected |
+| `ux-researcher`        | Frontend/Mobile detected   |
+
+---
+
+## 📋 Mapping Rules
+
+### Category → Agent Mapping
+
+| Detected Category | Agents to ENABLE                                 |
+| ----------------- | ------------------------------------------------ |
+| `frontend`        | frontend-specialist, ux-researcher               |
+| `backend`         | backend-specialist                               |
+| `mobile`          | mobile-developer, ux-researcher                  |
+| `database`        | database-specialist                              |
+| `devops`          | devops-engineer, cloud-architect                 |
+| `ai`              | ai-engineer                                      |
+| `realtime`        | realtime-specialist                              |
+| `queue`           | queue-specialist                                 |
+| `graphql`         | backend-specialist (GraphQL expertise)           |
+| `auth`            | security-auditor (always on), backend-specialist |
+| `testing`         | test-engineer                                    |
+
+### Never Disable (Core Agents)
+
+These agents are ALWAYS enabled regardless of techstack:
+
+- `orchestrator` - Master coordinator
+- `project-planner` - Planning and task management
+- `debugger` - Problem solving
+- `security-auditor` - Security reviews
+- `code-reviewer` - Code quality
+- `documentation-writer` - Documentation
+
+---
+
+## 📊 Recommendation Output
+
+```json
+{
+  "agents": {
+    "enabled": [
+      "orchestrator",
+      "project-planner",
+      "debugger",
+      "frontend-specialist",
+      "backend-specialist",
+      "database-specialist",
+      "devops-engineer",
+      "test-engineer",
+      "security-auditor",
+      "code-reviewer",
+      "documentation-writer"
+    ],
+    "disabled": [
+      "mobile-developer",
+      "realtime-specialist",
+      "queue-specialist",
+      "ai-engineer",
+      "multi-tenant-architect",
+      "i18n-specialist",
+      "data-engineer"
+    ],
+    "coreAgents": [
+      "orchestrator",
+      "project-planner",
+      "debugger",
+      "security-auditor",
+      "code-reviewer",
+      "documentation-writer"
+    ]
+  }
+}
+```
+
+---
+
+## 🔗 Integration
+
+### Input: TechstackProfile
+
+Receives output from `scan-techstack`:
+
+```json
+{
+  "categories": {
+    "frontend": true,
+    "backend": true,
+    "mobile": false,
+    "database": true,
+    "devops": true,
+    "ai": false,
+    "realtime": false,
+    "queue": false
+  }
+}
+```
+
+### Output: AgentProfile
+
+Produces agent recommendations for `profile.json`:
+
+```json
+{
+  "agents": {
+    "disabled": [
+      "mobile-developer",
+      "realtime-specialist",
+      "queue-specialist",
+      "ai-engineer"
+    ]
+  }
+}
+```
+
+---
+
+## ⚠️ Important Notes
+
+1. **Conservative approach** - When in doubt, keep agent enabled
+2. **User override** - User can force enable/disable any agent
+3. **Future planning** - If user plans to add mobile, keep mobile-developer enabled
+4. **Orchestrator respects profile** - Will skip disabled agents when routing
+
+---