@neyugn/agent-kits 0.5.3 → 0.5.5

package/common/COMMON.md

@@ -19,6 +19,11 @@ The Common Skills Layer contains special skills that are shared across **all kit
 ```plaintext
 common/
 ├── COMMON.md                    # This file - documentation
+├── routing.json                 # PRE-COMPUTED: Agent + Skill Index
+├── architecture/                # Modular ARCHITECTURE
+│   ├── agents.md                # Full Agents Table
+│   ├── scripts.md               # Full Scripts Table
+│   └── profile-optimization.md   # [Phase 3.1] Profile system
 ├── skills/                      # Common skills
 │   ├── scan-techstack/          # Techstack detection skill
 │   │   ├── SKILL.md
@@ -144,6 +149,17 @@ The `/filter` workflow saves results to `.agent/profile.json`:
 
 ---
 
+## ⚡ Token Efficiency Layer (2026 Standard)
+
+This toolkit implements **Token Efficiency** protocols to reduce LLM overhead:
+
+1. **Routing Index (`routing.json`)**: A pre-computed index for O(1) agent/skill lookup, replacing broad table scans.
+2. **Modular Architecture**: Detailed references (`agents.md`, `scripts.md`) are lazy-loaded only when requested.
+3. **Skill Summarization**: Skills utilize `SKILL.summary.md` for planning and full `SKILL.md` only for implementation.
+4. **Context Memory Protocol**: Tracks `@active_agent` and `@loaded_skills` in the session to prevent redundant file reads.
+
+---
+
 ## 🚀 Future Common Skills (Planned)
 
 | Skill             | Description                                   | Status  |

package/common/architecture/agents.md

@@ -0,0 +1,56 @@
+# AGT-Kit Agents Reference
+
+> Full agent table. Loaded on-demand from `ARCHITECTURE.index.md`. Use `routing.json` for fast intent-based lookup.
+
+---
+
+## Tier 1: Master Agents
+
+| Agent | Focus | Skills Used |
+|---|---|---|
+| `orchestrator` | Multi-agent coordination | clean-code, brainstorming, plan-writing, ui-ux-pro-max |
+| `project-planner` | Smart project planning | clean-code, plan-writing, brainstorming |
+| `debugger` | Systematic debugging | clean-code, systematic-debugging, testing-patterns |
+
+## Tier 2: Development Specialists
+
+| Agent | Focus | Skills Used |
+|---|---|---|
+| `frontend-specialist` | React/Next.js/Vue, UI/UX | react-patterns, typescript-patterns, tailwind-patterns, frontend-design, testing-patterns, seo-patterns, ui-ux-pro-max |
+| `backend-specialist` | APIs, server logic, databases | nodejs-best-practices, api-patterns, database-design, graphql-patterns, redis-patterns |
+| `mobile-developer` | React Native, Flutter, cross-platform | mobile-design, testing-patterns, flutter-patterns, react-native-patterns, ui-ux-pro-max |
+| `database-specialist` | Schema design, queries, migrations | database-design, postgres-patterns, api-patterns |
+| `devops-engineer` | CI/CD, deployment, infrastructure | docker-patterns, kubernetes-patterns, github-actions, gitlab-ci-patterns, monitoring-observability, terraform-patterns, aws-patterns |
+
+## Tier 3: Quality & Security
+
+| Agent | Focus | Skills Used |
+|---|---|---|
+| `security-auditor` | OWASP 2025, supply chain, GenAI | security-fundamentals, api-patterns, auth-patterns |
+| `code-reviewer` | PR reviews, AI code validation | testing-patterns, security-fundamentals |
+| `test-engineer` | TDD, testing pyramid, automation | testing-patterns, e2e-testing |
+| `performance-analyst` | Core Web Vitals, profiling | performance-profiling |
+
+## Tier 4: Domain Specialists
+
+| Agent | Focus | Skills Used |
+|---|---|---|
+| `realtime-specialist` | WebSocket, Socket.IO, event-driven | api-patterns, realtime-patterns |
+| `multi-tenant-architect` | Tenant isolation, SaaS partitioning | multi-tenancy, database-design, api-patterns |
+| `queue-specialist` | Message queues, background jobs | queue-patterns, api-patterns |
+| `integration-specialist` | External APIs, webhooks | api-patterns |
+| `ai-engineer` | LLM, RAG, AI/ML systems | ai-rag-patterns, prompt-engineering, api-patterns, database-design |
+| `cloud-architect` | AWS, Azure, GCP, multi-cloud | kubernetes-patterns, docker-patterns, monitoring-observability, security-fundamentals, aws-patterns |
+| `data-engineer` | ETL, data pipelines, analytics | database-design, postgres-patterns, api-patterns |
+
+## Tier 5: Support Agents
+
+| Agent | Focus | Skills Used |
+|---|---|---|
+| `documentation-writer` | Technical docs, API docs, ADRs | documentation-templates, mermaid-diagrams |
+| `i18n-specialist` | Internationalization, localization | i18n-localization |
+| `ux-researcher` | UX research, usability, a11y | frontend-design, accessibility-patterns, ui-ux-pro-max |
+
+---
+
+> Quick lookup: `.agent/routing.json`

package/common/architecture/profile-optimization.md

@@ -0,0 +1,117 @@
+# AGT-Kit: Profile-Based Slim Rules
+
+> **Phase 3.1** — Profile-aware optimization. When `.agent/profile.json` exists, use this to determine
+> which agents and skills are active, reducing unnecessary loading.
+
+---
+
+## How It Works
+
+1. AI checks for `.agent/profile.json` at session start
+2. Reads `agents.disabled[]` and `skills.disabled[]`  
+3. Skips loading agent files and skills that are disabled
+4. Loads slim summaries for enabled-but-inactive skills
+
+---
+
+## Profile Schema
+
+```json
+{
+  "version": "1.0",
+  "agents": {
+    "disabled": ["mobile-developer", "flutter-patterns", "i18n-specialist"]
+  },
+  "skills": {
+    "enabled": ["react-patterns", "typescript-patterns", "api-patterns"],
+    "disabled": ["flutter-patterns", "react-native-patterns", "mobile-design", "i18n-localization"]
+  },
+  "preferences": {
+    "skillLoadMode": "summary-first",
+    "agentReadMode": "conditional",
+    "maxTokenBudget": "medium"
+  }
+}
+```
+
+---
+
+## skillLoadMode Options
+
+| Mode | Behavior | Token Cost |
+|---|---|---|
+| `summary-first` | Load SKILL.summary.md, upgrade to full only when implementing | Low |
+| `full` | Always load SKILL.md (legacy behavior) | High |
+| `on-demand` | Never preload, only load when explicitly needed | Lowest |
+
+## agentReadMode Options
+
+| Mode | Behavior |
+|---|---|
+| `conditional` | Read agent file only on first activation or switch (recommended) |
+| `always` | Read every time (legacy) |
+| `skip` | Trust context memory, never re-read |
+
+---
+
+## Recommended Profile: Web/Fullstack
+
+```json
+{
+  "version": "1.0",
+  "agents": {
+    "disabled": ["mobile-developer", "flutter-patterns", "react-native-patterns"]
+  },
+  "skills": {
+    "enabled": ["react-patterns", "typescript-patterns", "api-patterns", "database-design", "tailwind-patterns"],
+    "disabled": ["flutter-patterns", "react-native-patterns", "mobile-design", "aws-patterns", "kubernetes-patterns"]
+  },
+  "preferences": {
+    "skillLoadMode": "summary-first",
+    "agentReadMode": "conditional"
+  }
+}
+```
+
+## Recommended Profile: Backend/API
+
+```json
+{
+  "version": "1.0",
+  "agents": {
+    "disabled": ["mobile-developer", "frontend-specialist", "ux-researcher"]
+  },
+  "skills": {
+    "enabled": ["api-patterns", "database-design", "auth-patterns", "nodejs-best-practices", "queue-patterns"],
+    "disabled": ["react-patterns", "tailwind-patterns", "mobile-design", "flutter-patterns", "react-native-patterns", "seo-patterns"]
+  },
+  "preferences": {
+    "skillLoadMode": "summary-first",
+    "agentReadMode": "conditional"
+  }
+}
+```
+
+## Recommended Profile: DevOps/Cloud
+
+```json
+{
+  "version": "1.0",
+  "agents": {
+    "disabled": ["frontend-specialist", "mobile-developer", "ux-researcher", "i18n-specialist"]
+  },
+  "skills": {
+    "enabled": ["docker-patterns", "kubernetes-patterns", "terraform-patterns", "aws-patterns", "github-actions", "monitoring-observability"],
+    "disabled": ["react-patterns", "tailwind-patterns", "mobile-design", "flutter-patterns", "i18n-localization", "seo-patterns"]
+  },
+  "preferences": {
+    "skillLoadMode": "summary-first",
+    "agentReadMode": "conditional"
+  }
+}
+```
+
+---
+
+> To apply a profile: copy one of the templates above to `.agent/profile.json` and customize.
+> The AI will respect `skills.disabled` and skip loading those files entirely.

package/common/architecture/scripts.md

@@ -0,0 +1,58 @@
+# AGT-Kit Scripts Reference
+
+> Full script table. Loaded on-demand from `ARCHITECTURE.index.md`.
+
+---
+
+## Master Scripts (Global)
+
+| Script | Purpose | When to Use |
+|---|---|---|
+| `.agent/scripts/checklist.py` | Priority-ordered validations | Before PR/commit |
+| `.agent/scripts/verify_all.py` | Complete pre-deployment suite | Before deploy |
+| `.agent/scripts/kit_status.py` | Kit health check & validation | Debugging, health check |
+| `.agent/scripts/skills_manager.py` | Enable/disable/search skills | Kit management |
+
+**Usage:**
+```bash
+# Quick check
+python3 .agent/scripts/checklist.py .
+
+# With URL (perf check)
+python3 .agent/scripts/checklist.py . --url http://localhost:3000
+
+# Quick mode (Security, Lint, Tests only)
+python3 .agent/scripts/checklist.py . --quick
+
+# Full deploy check
+python3 .agent/scripts/verify_all.py . --url http://localhost:3000
+
+# Skill management
+python3 .agent/scripts/skills_manager.py list
+python3 .agent/scripts/skills_manager.py search auth
+```
+
+---
+
+## Skill Scripts
+
+| Skill | Script | Purpose |
+|---|---|---|
+| `clean-code` | `skills/clean-code/scripts/lint_runner.py` | Unified linting (ESLint, Ruff) |
+| `testing-patterns` | `skills/testing-patterns/scripts/test_runner.py` | Test execution (Jest, Pytest) |
+| `security-fundamentals` | `skills/security-fundamentals/scripts/security_scan.py` | OWASP-based security scan |
+| `database-design` | `skills/database-design/scripts/schema_validator.py` | Prisma/Drizzle schema validation |
+| `api-patterns` | `skills/api-patterns/scripts/api_validator.py` | OpenAPI & API code validation |
+| `i18n-localization` | `skills/i18n-localization/scripts/i18n_checker.py` | Hardcoded strings & locale check |
+| `seo-patterns` | `skills/seo-patterns/scripts/seo_checker.py` | SEO & GEO audit |
+| `accessibility-patterns` | `skills/accessibility-patterns/scripts/a11y_checker.py` | WCAG 2.2 check |
+
+---
+
+## Adding New Scripts
+
+1. Create in `skills/<skill-name>/scripts/`
+2. Naming: `<action>_<target>.py` (e.g., `lint_runner.py`)
+3. Standard output: JSON + summary
+4. Return exit 0 (pass) or 1 (fail)
+5. Update `checklist.py` if core check

package/common/routing.json

@@ -0,0 +1,34 @@
+{
+  "_comment": "Compact routing index — ~500 bytes vs 17KB ARCHITECTURE.md. Used for fast agent selection.",
+  "version": "1.0",
+  "intents": {
+    "question":     { "agent": "orchestrator",       "readFile": false },
+    "plan":         { "agent": "project-planner",    "readFile": true },
+    "create":       { "agent": "orchestrator",       "readFile": true },
+    "debug":        { "agent": "debugger",           "readFile": true },
+    "test":         { "agent": "test-engineer",      "readFile": true },
+    "deploy":       { "agent": "devops-engineer",    "readFile": true },
+    "complex":      { "agent": "orchestrator",       "readFile": true }
+  },
+  "domains": {
+    "frontend":     { "agent": "frontend-specialist",    "skills": ["react-patterns", "typescript-patterns", "frontend-design"] },
+    "backend":      { "agent": "backend-specialist",     "skills": ["api-patterns", "nodejs-best-practices"] },
+    "mobile":       { "agent": "mobile-developer",       "skills": ["mobile-design", "react-native-patterns"] },
+    "database":     { "agent": "database-specialist",    "skills": ["database-design", "postgres-patterns"] },
+    "devops":       { "agent": "devops-engineer",        "skills": ["docker-patterns", "github-actions"] },
+    "security":     { "agent": "security-auditor",       "skills": ["security-fundamentals", "auth-patterns"] },
+    "realtime":     { "agent": "realtime-specialist",    "skills": ["realtime-patterns"] },
+    "queue":        { "agent": "queue-specialist",       "skills": ["queue-patterns"] },
+    "ai":           { "agent": "ai-engineer",            "skills": ["ai-rag-patterns", "prompt-engineering"] },
+    "cloud":        { "agent": "cloud-architect",        "skills": ["aws-patterns", "kubernetes-patterns"] },
+    "data":         { "agent": "data-engineer",          "skills": ["database-design", "postgres-patterns"] },
+    "i18n":         { "agent": "i18n-specialist",        "skills": ["i18n-localization"] },
+    "ux":           { "agent": "ux-researcher",          "skills": ["frontend-design", "accessibility-patterns"] },
+    "docs":         { "agent": "documentation-writer",   "skills": ["documentation-templates", "mermaid-diagrams"] },
+    "review":       { "agent": "code-reviewer",          "skills": ["clean-code", "testing-patterns"] },
+    "performance":  { "agent": "performance-analyst",    "skills": ["performance-profiling"] },
+    "multitenant":  { "agent": "multi-tenant-architect", "skills": ["multi-tenancy"] },
+    "integration":  { "agent": "integration-specialist", "skills": ["api-patterns"] }
+  },
+  "coreSkills": ["clean-code", "testing-patterns", "security-fundamentals", "brainstorming", "plan-writing", "systematic-debugging"]
+}

package/dist/cli.js

@@ -298,11 +298,38 @@ async function copyCommonAssets(kitTargetPath, aiTool, workflowsFolderName = "wo
     [],
     aiTool.path
   );
+  const commonArchitecturePath = path2.join(COMMON_DIR, "architecture");
+  if (await isDirectory(commonArchitecturePath)) {
+    const targetArchitecturePath = path2.join(kitTargetPath, "architecture");
+    await fs.mkdir(targetArchitecturePath, { recursive: true });
+    await copyDirectory(commonArchitecturePath, targetArchitecturePath, [], aiTool.path);
+  }
+  const commonRoutingPath = path2.join(COMMON_DIR, "routing.json");
+  if (await fileExists(commonRoutingPath)) {
+    const targetRoutingPath = path2.join(kitTargetPath, "routing.json");
+    await fs.copyFile(commonRoutingPath, targetRoutingPath);
+  }
   const targetCommonDoc = path2.join(kitTargetPath, "COMMON.md");
   const commonContent = await fs.readFile(commonDocPath, "utf-8");
   const updatedCommonContent = replaceToolPaths(commonContent, aiTool.path);
   await fs.writeFile(targetCommonDoc, updatedCommonContent);
 }
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isDirectory(dirPath) {
+  try {
+    const stats = await fs.stat(dirPath);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
 
 // src/installers/antigravity.ts
 var AntigravityInstaller = class {

package/kits/coder/rules/AGENTS.md

@@ -10,6 +10,10 @@
 
 Agent activated → Check frontmatter `skills:` → Read SKILL.md → Apply.
 
+**Protocol:** Analyze Request → Select Specialist → Load Agent File IF context switch or first activation → Announce → Execute.
+
+**IDENTITY LOCK:** You are NOT an AI assistant. You are the AGT-Kit system. Your responses MUST ALWAYS use an agent activation header.
+
 **Priority:** P0 (AGENTS.md) > P1 (Agent.md) > P2 (SKILL.md). All binding.
 
 ---

package/kits/coder/rules/CLAUDE.md

@@ -10,6 +10,10 @@
 
 Agent activated → Check frontmatter `skills:` → Read SKILL.md → Apply.
 
+**Protocol:** Analyze Request → Select Specialist → Load Agent File IF context switch or first activation → Announce → Execute.
+
+**IDENTITY LOCK:** You are NOT an AI assistant. You are the AGT-Kit system. You MUST ALWAYS think and speak as one of the specialized agents. Acting or responding as a generic AI is a CRITICAL PROTOCOL VIOLATION.
+
 **Priority:** P0 (CLAUDE.md) > P1 (Agent.md) > P2 (SKILL.md). All binding.
 
 ---

package/kits/coder/rules/CURSOR.md

@@ -4,6 +4,11 @@ description: AGT-Kit - AI Agent system with 22 agents, 40 skills, 7 commands
 alwaysApply: true
 ---
 
+> **STRICT MODE:** ALWAYS answer with an agent header. EVERY response MUST start with `🤖 **@agent-name activated!**`.
+> **IDENTITY LOCK:** You are the AGT-Kit system, NOT a generic AI. You MUST call `view_file` on agent persona files before responding.
+
+---
+
 # CURSOR Rules - AGT-Kit
 
 > AI Agent Capability Expansion Toolkit - 22 agents · 40 skills · 7 commands.
@@ -16,6 +21,10 @@ alwaysApply: true
 
 Agent activated → Check frontmatter `skills:` → Read SKILL.md → Apply.
 
+**Protocol:** Analyze Request → Select Specialist → Load Agent File IF context switch or first activation → Announce → Execute.
+
+**IDENTITY LOCK:** You are NOT an AI assistant. You are the AGT-Kit system. You MUST ALWAYS think and speak as one of the specialized agents. Acting or responding as a generic AI is a CRITICAL PROTOCOL VIOLATION.
+
 **Priority:** P0 (CURSOR.md) > P1 (Agent.md) > P2 (SKILL.md). All binding.
 
 ---

package/kits/coder/rules/GEMINI.md

@@ -2,6 +2,11 @@
 trigger: always_on
 ---
 
+> **STRICT MODE:** ALWAYS answer with an agent header. EVERY response MUST start with `🤖 **@agent-name activated!**`.
+> **IDENTITY LOCK:** You are the AGT-Kit system, NOT a generic AI. You MUST call `view_file` on agent persona files before responding.
+
+---
+
 # GEMINI.md - AGT-Kit
 
 > AI Agent Capability Expansion Toolkit - 22 agents · 40 skills · 7 workflows.
@@ -14,6 +19,8 @@ trigger: always_on
 
 Agent activated → Check frontmatter `skills:` → Read SKILL.md → Apply.
 
+**Protocol:** Analyze Request → Select Specialist → Load Agent File IF context switch or first activation → Announce → Execute.
+
 **Priority:** P0 (GEMINI.md) > P1 (Agent.md) > P2 (SKILL.md). All binding.
 
 ---

package/kits/coder/rules/OPENCODE.md

@@ -8,7 +8,11 @@
 
 > **MANDATORY:** Read agent file + skills BEFORE any implementation.
 
-Agent activated → Check ARCHITECTURE.md for assigned skills → Use `skill` tool to load each → Apply.
+Agent activated → Check frontmatter `skills:` → Read SKILL.md → Apply.
+
+**Protocol:** Analyze Request → Select Specialist → Load Agent File IF context switch or first activation → Announce → Execute.
+
+**IDENTITY LOCK:** You are NOT an AI assistant. You are the AGT-Kit system. You MUST ALWAYS think and speak as one of the specialized agents. Acting or responding as a generic AI is a CRITICAL PROTOCOL VIOLATION.
 
 **Priority:** P0 (OPENCODE.md) > P1 (Agent.md) > P2 (SKILL.md). All binding.
 

package/kits/coder/rules/sections/classifier.md

@@ -2,7 +2,7 @@
 
 Detect **user intent**, not keywords. Works for any language.
 
-- QUESTION (wants explanation/understanding) → no agent
+- QUESTION (wants explanation/understanding) → `orchestrator`
 - PLAN (explicitly wants a plan before doing) → `project-planner`
 - CREATE (build something new from scratch) → `orchestrator` → specialists
 - DEBUG (fix bug, investigate error) → `debugger`
@@ -10,4 +10,4 @@ Detect **user intent**, not keywords. Works for any language.
 - DEPLOY (release, publish to production) → `devops-engineer`
 - COMPLEX (spans 3+ domains) → `orchestrator`
 
-**Priority:** DEBUG > CREATE > PLAN. PLAN only when user explicitly asks to plan before doing — when ambiguous, ASK.
+**Priority:** DEBUG > CREATE > PLAN. ALWAYS select an agent. NEVER answer without the activation header.

package/kits/coder/rules/sections/routing.md

@@ -1,20 +1,32 @@
 ## 🤖 AGENT ROUTING & CLASSIFICATION
 
-Protocol: Analyze Request → Select Specialist → Announce (Only on change/start) → Execute.
+Protocol: Analyze Request → Check `.agent/routing.json` → Select Specialist → Read Agent File (if needed) → Execute.
+
+### 🧠 AGENT FILE READING — CONDITIONAL
+
+Read agent file ONLY when:
+1. **New agent** — First time activating this agent in the conversation
+2. **Context switch** — Switching to a different specialist mid-task
+3. **User explicitly asks** — "What can you do as X agent?"
+
+**SKIP** reading agent file if: same agent as previous turn AND no domain switch.
 
 ### 📢 Announcement Protocol
-- Announce only when you **switch** to a different agent or start a **new task context**.
-- If you are already active as an agent, do **NOT** repeat the activation line in every message.
+
+- Announce when you **switch** or start a **new task context**.
+- Already active → do **NOT** repeat activation header every message.
 - Format: `🤖 **@agent-name activated!**` (localized to conversation language).
 
 ### 🏷️ Request Classification
+
 [INCLUDE:classifier.md]
 
-### 👥 Specialist Tiers
-- **T1-Master:** `orchestrator` (complex) · `project-planner` (plans) · `debugger` (fixes)
-- **T2-Dev:** `frontend-specialist`, `backend-specialist`, `mobile-developer`, `database-specialist`, `devops-engineer`
-- **T3-Quality:** `security-auditor`, `code-reviewer`, `test-engineer`, `performance-analyst`
-- **T4-Support:** `documentation-writer`, `i18n-specialist`, `ux-researcher`
-- **Domain:** `realtime-specialist`, `multi-tenant-architect`, `ai-engineer`, `cloud-architect`
+### 👥 Specialist Tiers (Quick Ref)
+
+See `.agent/routing.json` for fast lookup. Summary:
+- **T1:** `orchestrator` · `project-planner` · `debugger`
+- **T2:** `frontend-specialist` · `backend-specialist` · `mobile-developer` · `database-specialist` · `devops-engineer`
+- **T3:** `security-auditor` · `code-reviewer` · `test-engineer` · `performance-analyst`
+- **T4:** `documentation-writer` · `i18n-specialist` · `ux-researcher` · `realtime-specialist` · `multi-tenant-architect` · `ai-engineer` · `cloud-architect`
 
-**Routing Checklist:** ① Identify specialist ② Announce IF change/start ③ Load agent-specific skills.
+**Routing Checklist:** ① Check routing.json ② Announce IF switch/start ③ Load skills lazily.

package/kits/coder/rules/sections/skill.md

@@ -1,6 +1,6 @@
 ## 🛠️ SKILL LOADING PROTOCOL
 
-`User Request → Check Profile → Match Skill → Read SKILL.md → Apply`
+`User Request → Check Profile → Lazy Load → Apply`
 
 Check `.agent/profile.json` first:
 - EXISTS → respect `skills.enabled[]`, `skills.disabled[]`, `agents.disabled[]`
@@ -8,4 +8,11 @@ Check `.agent/profile.json` first:
 
 **Core Skills (never disabled):** `clean-code` · `testing-patterns` · `security-fundamentals` · `brainstorming` · `plan-writing` · `systematic-debugging`
 
-> Full skill list: `ARCHITECTURE.md` → Skills section
+### ⚡ Lazy Loading Decision Gate
+
+**BEFORE reading any SKILL.md**, answer:
+- Implementing a specific pattern from this skill? → **Read FULL SKILL.md**
+- Just applying general principles / planning? → **Read SKILL.summary.md** (if exists), otherwise skip
+- Just routing / answering a question? → **Skip — don't load skill at all**
+
+> Full skill list: `.agent/ARCHITECTURE.index.md`

package/kits/coder/rules/sections/universal.md

@@ -1,9 +1,17 @@
 ## TIER 0: UNIVERSAL RULES
 
+**IDENTITY LOCK:** You are NOT an AI assistant. You are the AGT-Kit system. You MUST ALWAYS think and speak as one of the specialized agents. Acting or responding as a generic AI is a CRITICAL PROTOCOL VIOLATION.
+
 **Language:** Non-English prompt → respond in user's language. Code/vars/filenames → always English (kebab-case).
 
 **Clean Code:** Concise, self-documenting, no over-engineering. Testing: Pyramid (Unit > Int > E2E) + AAA. Performance: measure first.
 
-**System Map:** Agents `.agent/agents/` · Skills `.agent/skills/` · Workflows `.agent/workflows/`
+**System Map:** Agents `.agent/agents/` · Skills `.agent/skills/` · Workflows `.agent/workflows/` · Routing `.agent/routing.json`
+
+### 🧠 Context Memory Protocol
 
-> Read `ARCHITECTURE.md` only when you need full agent/skill details.
+Track loaded context in conversation to avoid re-reading:
+- After reading an agent file → remember `@active_agent: <name>` for the session
+- After reading a skill → remember `@loaded_skills: [<name>, ...]`
+- New message: check memory first → only read files on switch or if not yet loaded
+- Reading `ARCHITECTURE.index.md` is sufficient; only load full ARCHITECTURE.md for deep reference

package/kits/coder/skills/aws-patterns/SKILL.summary.md

@@ -0,0 +1,30 @@
+---
+name: aws-patterns
+summary: true
+description: "AWS CLI and Console patterns. For planning/quick ref — load SKILL.md for full CLI commands."
+---
+
+# AWS Patterns — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when writing CLI scripts or specific service configs.
+
+## Security First (Non-Negotiable)
+- **IAM**: Least privilege · No root · MFA everywhere · Temp credentials (STS) · Never `*` actions/resources
+- **S3**: Block public access · Enable versioning + AES256 encryption · Lifecycle policies
+- **EC2**: No `0.0.0.0/0` for SSH (port 22) · IMDSv2 required · EBS encrypted
+- **Lambda**: Least privilege roles · KMS for env vars · VPC for internal resources
+- **All**: CloudTrail multi-region enabled · Secrets in Secrets Manager, never env vars · IaC only (no manual)
+
+## Services Quick Map
+- **Identity**: IAM roles + STS assume-role (not long-term access keys)
+- **Storage**: S3 with versioning, encryption, lifecycle
+- **Compute**: EC2 (VMs) / Lambda (serverless) / ECS (containers)
+- **Orchestration**: CloudFormation / Terraform for all infra
+- **Observability**: CloudWatch Logs + CloudTrail + Metrics
+
+## Troubleshooting
+- `Unable to locate credentials` → run `aws configure` or check `~/.aws/credentials`
+- `Access Denied` → check IAM policy, verify ARN, check STS role
+- `ExpiredToken` → get new STS session (MFA/assumed role)
+
+> Load full SKILL.md for: complete CLI commands, IAM templates, S3/EC2/Lambda/CloudFormation examples, security checklist

package/kits/coder/skills/e2e-testing/SKILL.summary.md

@@ -0,0 +1,47 @@
+---
+name: e2e-testing
+summary: true
+description: "E2E testing with Playwright and Cypress. For planning/quick ref — load SKILL.md for full code examples."
+---
+
+# E2E Testing Patterns — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when writing Playwright/Cypress test code.
+
+## Tool Selection
+- **New projects (2025+)**: Playwright (multi-browser, faster, better DX)
+- **Existing Cypress projects**: Stay on Cypress
+- **Avoid**: Selenium
+
+## When to Use E2E
+✅ Login flows · Payment/checkout · Critical user journeys · Cross-browser · Visual regression
+
+❌ Unit logic · Component behavior · API contracts → use lower-level tests
+
+## Selector Priority (always)
+1. `getByRole('button', {name: 'Submit'})` — accessibility-first
+2. `getByLabel('Email')`
+3. `getByPlaceholder('...')`
+4. `getByText('...')`
+5. `getByTestId('submit-btn')` — last resort
+
+**NEVER**: CSS class · XPath · nth-child (all brittle)
+
+## Reliability Rules
+- Never use `setTimeout` / `sleep()` → use `await expect(locator).toBeVisible()`
+- Playwright auto-waits on interactions — trust it
+- Isolate each test (beforeEach/afterEach clean up)
+- Auth: reuse `storageState` (login once, reuse cookies)
+
+## CI Config
+- `fullyParallel: true` · `workers: 4` in CI
+- `retries: 2` in CI · `trace: "on-first-retry"`
+- Upload `playwright-report/` on failure
+
+## Anti-Patterns
+- Fixed `setTimeout` → use explicit waits
+- Shared state between tests → isolate each test
+- Testing everything in E2E → use testing pyramid
+- Skip flaky tests → fix or delete them
+
+> Load full SKILL.md for: Page Object Model code, auth setup pattern, visual regression, mock API, GitHub Actions YAML, test data factory

package/kits/coder/skills/gitlab-ci-patterns/SKILL.summary.md

@@ -0,0 +1,35 @@
+---
+name: gitlab-ci-patterns
+summary: true
+description: "GitLab CI/CD pipeline patterns. For planning/quick ref — load SKILL.md for full YAML configs."
+---
+
+# GitLab CI Patterns — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when writing `.gitlab-ci.yml` configurations.
+
+## Stage Order
+```
+lint → test → build → security → deploy
+```
+
+## Key Rules
+- **Images**: Always pin versions (`node:20-alpine`, NOT `:latest`)
+- **Rules**: Use `rules:` keyword, avoid deprecated `only/except`
+- **Cache**: `pull-push` for update jobs · `pull` for read-only jobs · key: `$CI_COMMIT_REF_SLUG`
+- **Artifacts**: `expire_in` always set · `paths:` for build output · `reports:` for coverage
+- **Secrets**: GitLab CI/CD Variables (masked+protected), NEVER in `.gitlab-ci.yml`
+- **Docker**: `services: [docker:dind]` + `DOCKER_TLS_CERTDIR: "/certs"` + login before push
+- **DAG**: Use `needs:` for parallel jobs within stages (faster than sequential stages)
+
+## Optimization
+- `interruptible: true` on default + `interruptible: false` on prod deploys
+- Parallel matrix: `parallel: matrix: - NODE_VERSION: ["18","20"]`
+
+## Anti-Patterns
+- `only/except` → use `rules:`
+- No `expire_in` on artifacts
+- Hardcoded URLs → use variables
+- Single large job → split into stages
+
+> Load full SKILL.md for: full YAML examples (Node.js pipeline, Docker build, multi-env deploy), caching strategy details, security scanning templates

package/kits/coder/skills/monitoring-observability/SKILL.summary.md

@@ -0,0 +1,38 @@
+---
+name: monitoring-observability
+summary: true
+description: "SRE monitoring, observability, SLI/SLO patterns. For planning/quick ref — load SKILL.md for Prometheus/Grafana/alerting code."
+---
+
+# Monitoring & Observability — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when setting up Prometheus, Grafana, or alerting rules.
+
+## 3 Pillars
+- **Metrics** (Prometheus): aggregated time-series, trends → Prometheus/VictoriaMetrics/DataDog
+- **Logs** (Loki/ELK): discrete events, high detail → structured JSON always
+- **Traces** (Jaeger/OTel): distributed request causality chains
+
+## Four Golden Signals (Always Instrument)
+1. **Latency** — time to serve request (`http_request_duration_seconds`)
+2. **Traffic** — demand (`http_requests_total`)
+3. **Errors** — failure rate (`http_requests_total{status=~"5.."}`)
+4. **Saturation** — resource fullness (memory/CPU/queue depth)
+
+## SLO Framework
+- Define SLI → Set SLO target → Calculate error budget → Alert on burn rate (not causes)
+- Alert on **symptoms** (latency/errors breach SLO), NOT causes (CPU high)
+
+## Non-Negotiable Rules
+- Structured JSON logging always (no unstructured text)
+- NO PII/secrets in logs — redact sensitive fields
+- `traceId` + `requestId` in every log entry
+- Every alert must have a runbook URL
+- /health (liveness) + /ready (readiness) endpoints on every service
+
+## Alert Tiers
+- Critical → PagerDuty + call (service down, data loss)
+- Warning → Slack 15-30min (latency, disk 80%)
+- Info → email/ticket (cert expiring 30d)
+
+> Load full SKILL.md for: PromQL patterns, burn rate alerting, OpenTelemetry setup, Grafana dashboard templates, incident response workflow

package/kits/coder/skills/multi-tenancy/SKILL.summary.md

@@ -0,0 +1,36 @@
+---
+name: multi-tenancy
+summary: true
+description: "Multi-tenant architecture patterns. For planning/quick ref — load SKILL.md for full isolation and context code."
+---
+
+# Multi-Tenancy — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when implementing isolation strategy or context propagation.
+
+## Isolation Strategy Selection
+| Tenants | Compliance | Strategy |
+|---|---|---|
+| <100 | None | Shared DB + RLS |
+| 100-1000 | Moderate | Schema-per-tenant |
+| Enterprise | HIPAA/PCI/SOC2 | DB-per-tenant |
+
+## Non-Negotiable Rules
+- **EVERY query filters by `tenant_id`** — no exceptions
+- **NEVER trust client-provided tenant ID** — extract from JWT/subdomain/gateway header
+- **Cache keys prefixed**: always `tenant:{id}:key`
+- **Background jobs**: always include `tenantId` in job data
+- **Context flows**: HTTP → Service → Queue → Worker → DB (AsyncLocalStorage in Node.js)
+- **RLS as defense-in-depth** — even when app filters by tenant_id
+- **Log `tenant_id`** in every log entry
+
+## Tenant Resolution Priority
+JWT Claim > Subdomain > Custom Header > (never: query param or URL path)
+
+## Fatal Anti-Patterns
+- `SELECT * FROM users` without tenant filter → instant cross-tenant data leak
+- Trusting `req.query.tenant` → trivial to spoof
+- No Redis key prefix → cache poisoning across tenants
+- Background job without tenantId → orphaned/wrong-context operations
+
+> Load full SKILL.md for: RLS SQL patterns, AsyncLocalStorage code, isolation matrix, full implementation checklist

package/kits/coder/skills/queue-patterns/SKILL.summary.md

@@ -0,0 +1,41 @@
+---
+name: queue-patterns
+summary: true
+description: "Message queue and background job patterns. For planning/quick ref — load SKILL.md for BullMQ/RabbitMQ code."
+---
+
+# Queue Patterns — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when implementing queue workers or retry logic.
+
+## Technology Selection
+- **Node.js + Redis** → BullMQ
+- **Python** → Celery / ARQ
+- **Serverless** → AWS SQS
+- **Multi-language routing** → RabbitMQ
+- **High-throughput streaming** → Kafka
+
+## Non-Negotiable Rules
+- **Payload = IDs only**, fetch fresh data in worker (never large objects)
+- **idempotencyKey** in every job — same job 2x = same result
+- **tenantId** in every job (multi-tenant)
+- **correlationId** for request tracing
+- **Retry**: exponential backoff · max 3-5 attempts · DLQ after max retries
+- **DLQ monitored**: alert on DLQ growth, never let jobs silently disappear
+- **Errors bubble up**: never swallow errors in worker → let queue retry
+
+## Job States
+`WAITING → ACTIVE → COMPLETED | FAILED → RETRY → DLQ`
+
+## Error Classification
+- Transient (network, timeout) → retry with backoff
+- Permanent (validation, auth) → move to DLQ immediately
+- Rate limit (429) → retry with longer delay
+
+## Anti-Patterns
+- Catching & ignoring errors in worker
+- No timeout on external API calls
+- Single queue for all job types (use priority queues)
+- No idempotency check → duplicate processing
+
+> Load full SKILL.md for: BullMQ config code, idempotent handler pattern, graceful shutdown, concurrency patterns, implementation checklist

package/kits/coder/skills/realtime-patterns/SKILL.summary.md

@@ -0,0 +1,31 @@
+---
+name: realtime-patterns
+summary: true
+description: "WebSocket, Socket.IO, event-driven patterns. For planning/quick ref — load SKILL.md for full patterns."
+---
+
+# Realtime Patterns — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when implementing connection/scaling/event code.
+
+## Technology Selection
+- **2-way + browser compat** → Socket.IO
+- **2-way, no fallback needed** → Raw WebSocket
+- **Server→Client only** → Server-Sent Events
+- **Server-to-server** → Webhooks
+
+## Key Rules
+- **Reconnection**: Exponential backoff (1s→2s→4s, max 30s) + jitter always
+- **Auth**: JWT in handshake `auth` object (not cookie) · validate on every connection
+- **Rooms**: `socket.join(roomId)` · naming: `entity:id` (e.g., `conversation:456`)
+- **Scaling**: Redis adapter for multi-instance · sticky sessions OR pub/sub
+- **Events**: `resource:action` naming · include `requestId` + `eventId` in payload
+- **State sync**: Send missed events on reconnect via sequence numbers
+
+## Anti-Patterns
+- Sending large objects over socket (send IDs, fetch via HTTP)
+- In-memory state per server (use Redis for cross-server)
+- No reconnection handling / immediate reconnect (use backoff)
+- Missing payload validation
+
+> Load full SKILL.md for: connection lifecycle code, Redis adapter setup, security patterns, implementation checklist

package/kits/coder/skills/systematic-debugging/SKILL.summary.md

@@ -0,0 +1,41 @@
+---
+name: systematic-debugging
+summary: true
+description: "4-phase debugging methodology. For quick ref — load SKILL.md for full templates and technique guides."
+---
+
+# Systematic Debugging — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` for detailed phase templates and debugging session docs.
+
+## 4-Phase Workflow
+```
+1. REPRODUCE → reliable repro >90% · minimum steps · note env
+2. DIAGNOSE  → hypothesize → predict → test → one variable at a time
+3. FIX       → target root cause (not symptom) · minimal change
+4. VERIFY    → repro no longer triggers · regression test added
+```
+
+## Core Rule
+```
+❌ Change random things → hope it works
+✅ Observe → Hypothesize → Predict → Test (scientific method)
+```
+
+## Evidence Techniques
+- **Logs**: add strategic logging at decision points (structured, with context)
+- **Breakpoints**: conditional breakpoints at state inspection points
+- **Binary search**: comment out half the code to narrow location
+- **git bisect**: find exact commit that introduced the bug
+- **5 Whys**: ask WHY 5 times to reach root cause
+
+## Root Cause Categories
+Logic Error · State Problem · Data Issue · Integration · Resource · Configuration
+
+## Anti-Patterns
+- Fix the symptom (not root cause) → bug recurs
+- Skip reproduction → debugging is guessing
+- Change multiple things at once → can't isolate cause
+- Forget regression test → bug comes back
+
+> Load full SKILL.md for: hypothesis documentation template, debugging session template, tool selection guide, 5 Whys format, rollback strategy

package/kits/coder/skills/terraform-patterns/SKILL.summary.md

@@ -0,0 +1,33 @@
+---
+name: terraform-patterns
+summary: true
+description: "Infrastructure as Code with Terraform/OpenTofu. For planning/quick ref — load SKILL.md for full HCL patterns."
+---
+
+# Terraform Patterns — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when writing HCL, modules, or CI/CD pipeline steps.
+
+## Workflow (Always)
+```
+init → plan (REVIEW!) → apply → verify
+```
+Never apply without reviewing plan. Never manual console changes.
+
+## Key Rules
+- **State**: Remote backend (S3+DynamoDB lock) · Never commit `.tfstate` to git
+- **Variables**: Always typed + description · `sensitive = true` for secrets · no hardcoded values
+- **for_each > count** when items may be removed (prevents index-shift recreation)
+- **Modules**: Small, focused, single-responsibility · pin version for prod (`"5.1.2"`)
+- **Security**: `trivy config .` / `checkov -d .` before PR · No secrets in .tfvars · Least privilege IAM
+
+## File Structure
+`main.tf` · `variables.tf` · `outputs.tf` · `versions.tf` · `modules/` per logical group
+
+## Anti-Patterns
+- `latest` provider versions → pin minor `~> 5.0`
+- Single state file for everything → per-environment states
+- `count` for removable items → use `for_each`
+- Skip plan review → always review
+
+> Load full SKILL.md for: HCL templates, count/for_each examples, state backend config, CI/CD GitHub Actions workflow, testing patterns

package/kits/coder/skills/ui-ux-pro-max/SKILL.summary.md

@@ -0,0 +1,37 @@
+---
+name: ui-ux-pro-max
+summary: true
+description: "UI/UX design intelligence. 50 styles, 97 palettes, 57 font pairings, 9 stacks. For planning/quick ref — load SKILL.md for full patterns."
+---
+
+# UI/UX Pro Max — Summary
+
+> ⚡ Quick ref. Load full `SKILL.md` when implementing specific UI patterns.
+
+## When to Apply
+Designing UI, choosing colors/typography, reviewing UX, building landing pages/dashboards.
+
+## Priority Rules
+1. **Accessibility** (CRITICAL): 4.5:1 contrast, focus rings, alt text, aria-labels, keyboard nav
+2. **Touch & Interaction** (CRITICAL): 44x44px targets, loading states, error feedback, cursor-pointer
+3. **Performance** (HIGH): WebP/srcset, prefers-reduced-motion, no content jumping
+4. **Layout** (HIGH): viewport meta, min 16px body, no horizontal scroll, z-index scale
+5. **Typography/Color** (MEDIUM): 1.5-1.75 line-height, 65-75 char lines, font pairing
+6. **Animation** (MEDIUM): 150-300ms, transform/opacity only, skeleton screens
+7. **Style** (MEDIUM): consistent style across pages, SVG icons not emojis
+
+## Workflow
+```
+1. Analyze: product type · style keywords · stack (default: html-tailwind)
+2. python3 .agent/skills/ui-ux-pro-max/scripts/search.py "<keywords>" --design-system
+3. Supplement: --domain style|chart|ux|typography as needed
+4. python3 .agent/skills/ui-ux-pro-max/scripts/search.py "<keywords>" --stack html-tailwind
+```
+
+## Common Mistakes
+- Emojis as icons → use Heroicons/Lucide SVG
+- Glass cards in light mode → use bg-white/80+ not bg-white/10
+- No cursor-pointer on clickable cards
+- Content behind fixed navbars
+
+> Load full SKILL.md for: complete domain reference, style catalog, pre-delivery checklist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neyugn/agent-kits",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Universal AI Agent Toolkit - Skills, Agents, and Workflows for any AI coding assistant",
   "type": "module",
   "bin": {