@neyugn/agent-kits 0.2.5 → 0.2.7

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

@@ -0,0 +1,166 @@
+# Common Skills Layer
+
+> Universal skills shared across ALL kits in @neyugn/agent-kits
+
+---
+
+## 🎯 Purpose
+
+The Common Skills Layer contains special skills that are shared across **all kits**. These skills:
+
+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
+
+---
+
+## 📁 Directory Structure
+
+```plaintext
+common/
+├── 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                                             | 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 |
+
+---
+
+## 🔄 How It Works
+
+### Installation
+
+When user runs `npx @neyugn/agent-kits`:
+
+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 invokes workflow to filter skills and agents
+/filter
+
+# 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
+
+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 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` | 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 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
+
+---

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

@@ -0,0 +1,225 @@
+---
+name: filter-skill
+description: Recommend enabling/disabling skills based on detected techstack. Reduces noise from irrelevant skills in the workspace.
+category: common
+trigger: manual
+workflow: /filter
+---
+
+# Filter Skill
+
+> Workspace-aware skill filtering for optimal AI performance.
+
+---
+
+## 🎯 Purpose
+
+Filter Skill analyzes the **techstack profile** (from scan-techstack) and recommends which skills to **enable/disable** based on project needs. This:
+
+1. **Reduces noise** - Only relevant skills are loaded
+2. **Improves context** - AI focuses on applicable patterns
+3. **Optimizes performance** - Less skill content to process
+
+---
+
+## 🔗 Dependency
+
+This skill requires **scan-techstack** to run first:
+
+```
+/filter workflow:
+  1. scan-techstack → detect techstack
+  2. filter-skill → recommend skills (this skill)
+  3. filter-agent → recommend agents
+```
+
+---
+
+## 📋 Skill Categories
+
+### Core Skills (NEVER DISABLE)
+
+These skills are ALWAYS enabled regardless of techstack:
+
+| Skill                   | Reason                        |
+| ----------------------- | ----------------------------- |
+| `clean-code`            | Universal coding standards    |
+| `brainstorming`         | Socratic questioning protocol |
+| `plan-writing`          | Task breakdown and WBS        |
+| `systematic-debugging`  | 4-phase debugging methodology |
+| `testing-patterns`      | Testing pyramid, AAA pattern  |
+| `security-fundamentals` | OWASP 2025 security basics    |
+
+### Frontend Skills
+
+| Skill                    | Enable When                     |
+| ------------------------ | ------------------------------- |
+| `react-patterns`         | React/Next.js detected          |
+| `typescript-patterns`    | TypeScript detected             |
+| `tailwind-patterns`      | Tailwind CSS detected           |
+| `frontend-design`        | Any frontend framework          |
+| `seo-patterns`           | Next.js, Nuxt.js (SSR) detected |
+| `accessibility-patterns` | Frontend detected               |
+
+### Backend Skills
+
+| Skill                   | Enable When                |
+| ----------------------- | -------------------------- |
+| `api-patterns`          | Backend framework detected |
+| `auth-patterns`         | Auth dependencies detected |
+| `graphql-patterns`      | GraphQL detected           |
+| `nodejs-best-practices` | Node.js detected           |
+
+### Database Skills
+
+| Skill               | Enable When           |
+| ------------------- | --------------------- |
+| `database-design`   | Any database detected |
+| `postgres-patterns` | PostgreSQL detected   |
+| `redis-patterns`    | Redis detected        |
+
+### Mobile Skills
+
+| Skill                   | Enable When           |
+| ----------------------- | --------------------- |
+| `flutter-patterns`      | Flutter/Dart detected |
+| `react-native-patterns` | React Native detected |
+| `mobile-design`         | Any mobile platform   |
+
+### DevOps Skills
+
+| Skill                      | Enable When                |
+| -------------------------- | -------------------------- |
+| `docker-patterns`          | Docker detected            |
+| `kubernetes-patterns`      | Kubernetes detected        |
+| `terraform-patterns`       | Terraform detected         |
+| `github-actions`           | GitHub Actions detected    |
+| `gitlab-ci-patterns`       | GitLab CI detected         |
+| `monitoring-observability` | DevOps/Production detected |
+
+### AI Skills
+
+| Skill                | Enable When                  |
+| -------------------- | ---------------------------- |
+| `ai-rag-patterns`    | AI/LLM dependencies detected |
+| `prompt-engineering` | AI/LLM dependencies detected |
+
+### Realtime & Queue Skills
+
+| Skill               | Enable When                    |
+| ------------------- | ------------------------------ |
+| `realtime-patterns` | Socket.IO/WebSocket detected   |
+| `queue-patterns`    | BullMQ/RabbitMQ detected       |
+| `multi-tenancy`     | Multi-tenant patterns detected |
+
+### Support Skills
+
+| Skill                     | Enable When                |
+| ------------------------- | -------------------------- |
+| `i18n-localization`       | i18n dependencies detected |
+| `documentation-templates` | Always available           |
+| `mermaid-diagrams`        | Always available           |
+
+---
+
+## 📊 Recommendation Output
+
+```json
+{
+  "skills": {
+    "enabled": [
+      "clean-code",
+      "testing-patterns",
+      "security-fundamentals",
+      "react-patterns",
+      "typescript-patterns",
+      "tailwind-patterns",
+      "frontend-design",
+      "api-patterns",
+      "database-design",
+      "postgres-patterns",
+      "docker-patterns",
+      "github-actions"
+    ],
+    "disabled": [
+      "flutter-patterns",
+      "react-native-patterns",
+      "mobile-design",
+      "queue-patterns",
+      "realtime-patterns",
+      "ai-rag-patterns",
+      "kubernetes-patterns"
+    ],
+    "coreSkills": [
+      "clean-code",
+      "brainstorming",
+      "plan-writing",
+      "systematic-debugging",
+      "testing-patterns",
+      "security-fundamentals"
+    ]
+  }
+}
+```
+
+---
+
+## 🔧 Mapping Rules
+
+### Category → Skill Mapping
+
+| Detected Category | Skills to ENABLE                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------------- |
+| `frontend`        | react-patterns, typescript-patterns, frontend-design, tailwind-patterns, seo-patterns, accessibility-patterns |
+| `backend`         | api-patterns, nodejs-best-practices, auth-patterns                                                            |
+| `mobile`          | flutter-patterns OR react-native-patterns, mobile-design                                                      |
+| `database`        | database-design, postgres-patterns OR redis-patterns                                                          |
+| `devops`          | docker-patterns, kubernetes-patterns, github-actions, monitoring-observability                                |
+| `ai`              | ai-rag-patterns, prompt-engineering                                                                           |
+| `realtime`        | realtime-patterns                                                                                             |
+| `queue`           | queue-patterns                                                                                                |
+| `graphql`         | graphql-patterns                                                                                              |
+
+### Framework → Additional Skills
+
+| Framework     | Additional Skills                  |
+| ------------- | ---------------------------------- |
+| `nextjs`      | seo-patterns, react-patterns       |
+| `tailwindcss` | tailwind-patterns                  |
+| `prisma`      | database-design, postgres-patterns |
+| `socketio`    | realtime-patterns                  |
+| `gitlab-ci`   | gitlab-ci-patterns                 |
+| `terraform`   | terraform-patterns                 |
+
+---
+
+## ⚠️ Important Notes
+
+1. **Core skills always ON** - Never disable core skills
+2. **Conservative approach** - When in doubt, keep skill enabled
+3. **User override** - User can force enable/disable any skill
+4. **Future planning** - Check user's future techstack plans before disabling
+
+---
+
+## 📄 Persistence
+
+Results are saved to `.agent/profile.json`:
+
+```json
+{
+  "version": "1.0",
+  "generatedAt": "2026-02-05T12:00:00Z",
+  "analyzedBy": "filter-skill v1.0",
+  "skills": {
+    "enabled": [...],
+    "disabled": [...],
+    "userOverrides": {
+      "force-enabled": [],
+      "force-disabled": []
+    }
+  }
+}
+```
+
+---