codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/adapters/windsurf.md

@@ -0,0 +1,395 @@
+# Windsurf Integration Guide
+
+Guide for using codingbuddy with Windsurf (Codeium IDE).
+
+## Overview
+
+codingbuddy integrates with Windsurf in two ways:
+
+1. **AGENTS.md** - Industry standard format compatible with all AI tools
+2. **`.windsurf/rules/*.md`** - Windsurf-specific rules for Cascade AI
+
+## Two Usage Contexts
+
+### End Users (Your Project)
+
+End users access rules **only through MCP tools**. No local rule files needed.
+
+```json
+// .windsurf/mcp.json (or Windsurf MCP settings)
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+> **Important:** Whether Windsurf supports the `roots/list` MCP capability has not been confirmed.
+> Without `CODINGBUDDY_PROJECT_ROOT`, the server cannot locate your project's
+> `codingbuddy.config.json`, causing `language` and other settings to use defaults.
+> Always set this environment variable to your project's absolute path.
+
+Optional: Create `.windsurf/rules/codingbuddy.md` for basic integration:
+
+```markdown
+# codingbuddy Integration
+
+When PLAN, ACT, EVAL keywords detected -> call `parse_mode` MCP tool
+```
+
+### Monorepo Contributors
+
+Contributors to the codingbuddy repository can use direct file references:
+
+```
+Project Root/
+├── AGENTS.md                    # Cross-platform entry point
+├── .windsurf/rules/
+│   └── codingbuddy.md           # References .ai-rules
+└── packages/rules/.ai-rules/    # Single Source of Truth
+```
+
+## DRY Principle
+
+**Single Source of Truth**: `packages/rules/.ai-rules/`
+
+- All Agent definitions, rules, skills managed only in `.ai-rules/`
+- `.windsurf/rules/*.md` files act as **pointers only**
+- No duplication, only references
+
+## Windsurf Rules System
+
+### Rules Hierarchy
+
+Windsurf loads rules in this order (later rules take priority):
+
+1. **Global Rules** (`~/.codeium/windsurf/memories/global_rules.md`) - Personal preferences across all projects
+2. **Project Rules** (`.windsurf/rules/*.md` or `.windsurfrules`) - Project-specific conventions
+
+### Current Format (`.windsurf/rules/*.md`)
+
+Windsurf Wave 8+ uses markdown files in the `.windsurf/rules/` directory:
+
+```
+.windsurf/
+└── rules/
+    ├── codingbuddy.md       # codingbuddy integration rules
+    └── project-specific.md  # Additional project rules
+```
+
+### Legacy Format (`.windsurfrules`)
+
+Older versions use a single `.windsurfrules` file in the project root. This is still supported but the `.windsurf/rules/` directory is preferred.
+
+### Character Limits
+
+| Scope | Limit |
+|-------|-------|
+| Individual rule file | 6,000 characters |
+| Total combined (global + local) | 12,000 characters |
+
+> **Important:** Content beyond these limits is truncated. Global rules take priority if the combined limit is exceeded. Keep codingbuddy rules concise and use references to `.ai-rules/` files rather than duplicating content.
+
+## Integration Method
+
+### Option 1: MCP Server Only (Recommended for End Users)
+
+Use the MCP server configuration shown above. All rules, agents, and skills are accessed through MCP tools.
+
+### Option 2: Rules File + MCP (Recommended for Monorepo Contributors)
+
+Create `.windsurf/rules/codingbuddy.md`:
+
+```markdown
+# codingbuddy Rules
+
+## Workflow
+Follow PLAN/ACT/EVAL workflow from `.ai-rules/rules/core.md`.
+When PLAN, ACT, EVAL, or AUTO keywords are detected, call `parse_mode` MCP tool.
+
+## Code Quality
+- TDD cycle: Red -> Green -> Refactor
+- TypeScript strict mode (no `any`)
+- 90%+ test coverage goal
+- See `.ai-rules/rules/augmented-coding.md` for details
+
+## Agents
+See `.ai-rules/agents/README.md` for available specialist agents.
+```
+
+### Option 3: Global Rules (Personal Preferences)
+
+Access via Windsurf: **Settings > Manage Memories > Edit Global Rules**
+
+Or edit directly: `~/.codeium/windsurf/memories/global_rules.md`
+
+```markdown
+# Global Coding Preferences
+
+- Always use TypeScript strict mode
+- Prefer functional programming patterns
+- Follow TDD workflow
+```
+
+## Directory Structure
+
+```
+.windsurf/
+└── rules/
+    └── codingbuddy.md          # Project rules (references .ai-rules)
+
+.windsurfrules                   # Legacy project rules (optional)
+
+~/.codeium/windsurf/memories/
+└── global_rules.md              # Global rules (personal preferences)
+
+packages/rules/.ai-rules/        # Single Source of Truth
+├── rules/
+│   ├── core.md
+│   ├── project.md
+│   └── augmented-coding.md
+├── agents/
+│   └── *.json
+└── adapters/
+    └── windsurf.md              # This guide
+```
+
+## Usage
+
+### Mode Keywords
+
+```
+PLAN Design user authentication feature
+```
+
+> `parse_mode` MCP tool is called, loading appropriate Agent and rules
+
+### Specialist Usage
+
+```
+EVAL Review from security perspective
+```
+
+> security-specialist activated
+
+## MCP Tools
+
+Available codingbuddy MCP tools in Windsurf:
+
+| Tool | Purpose |
+|------|---------|
+| `parse_mode` | **MANDATORY.** Parse PLAN/ACT/EVAL/AUTO keywords and return mode-specific rules, agent, and context |
+| `search_rules` | Search rules and guidelines by query |
+| `get_agent_details` | Get specific Agent profile and expertise |
+| `get_project_config` | Get project configuration (language, tech stack) |
+| `get_code_conventions` | Get project code conventions and style guide |
+| `suggest_config_updates` | Analyze project and suggest config updates |
+| `recommend_skills` | Recommend skills based on prompt -> then call `get_skill` |
+| `get_skill` | Load full skill content by name |
+| `list_skills` | List all available skills with optional filtering |
+| `get_agent_system_prompt` | Get complete system prompt for a specialist agent |
+| `prepare_parallel_agents` | Prepare specialist agents for sequential execution |
+| `dispatch_agents` | Get dispatch params for agents (Claude Code optimized; use `prepare_parallel_agents` in Windsurf) |
+| `generate_checklist` | Generate contextual checklists (security, a11y, performance) |
+| `analyze_task` | Analyze task for risk assessment and specialist recommendations |
+| `read_context` | Read context document (`docs/codingbuddy/context.md`) |
+| `update_context` | **MANDATORY at mode end.** Update context document with decisions, notes, progress |
+| `cleanup_context` | Manually trigger context document cleanup |
+
+## Specialist Agents Execution
+
+Windsurf does not have a `Task` tool for spawning background subagents. When `parse_mode` returns `parallelAgentsRecommendation`, execute specialists **sequentially**.
+
+### Sequential Workflow
+
+```
+parse_mode returns parallelAgentsRecommendation
+  |
+Call prepare_parallel_agents with recommended specialists
+  |
+For each specialist (sequentially):
+  - Announce: "Analyzing from [icon] [specialist-name] perspective..."
+  - Apply the specialist's system prompt as analysis context
+  - Analyze the target code/design from that specialist's viewpoint
+  - Record findings
+  |
+Consolidate all specialist findings into unified summary
+```
+
+### Specialist Icons
+
+| Icon | Specialist |
+|------|------------|
+| 🔒 | security-specialist |
+| ♿ | accessibility-specialist |
+| ⚡ | performance-specialist |
+| 📏 | code-quality-specialist |
+| 🧪 | test-strategy-specialist |
+| 🏛️ | architecture-specialist |
+| 📚 | documentation-specialist |
+| 🔍 | seo-specialist |
+| 📨 | event-architecture-specialist |
+| 🔗 | integration-specialist |
+| 📊 | observability-specialist |
+| 🔄 | migration-specialist |
+| 🌐 | i18n-specialist |
+
+## Skills
+
+Windsurf accesses codingbuddy skills through MCP tools:
+
+1. **Auto-recommend** - AI calls `recommend_skills` based on intent detection
+2. **Browse and select** - User calls `list_skills` to discover, then `get_skill` to load
+3. **Slash-command** - User types `/<command>`, AI maps to `get_skill`
+
+### Using Skills in Windsurf
+
+**MCP Tool Chain (Recommended):**
+
+1. `recommend_skills({ prompt: "user's message" })` - Get skill recommendations
+2. `get_skill("skill-name")` - Load the recommended skill's full content
+3. Follow the skill instructions in the response
+
+> **Note:** `parse_mode` already embeds matched skill content in `included_skills` - no separate `get_skill` call needed when using mode keywords (PLAN/ACT/EVAL/AUTO).
+
+### Slash-Command Mapping
+
+When a user types `/<command>`, the AI should call `get_skill`:
+
+| User Types | MCP Call |
+|---|---|
+| `/debug` or `/debugging` | `get_skill("systematic-debugging")` |
+| `/tdd` | `get_skill("test-driven-development")` |
+| `/brainstorm` | `get_skill("brainstorming")` |
+| `/plan` or `/write-plan` | `get_skill("writing-plans")` |
+| `/execute` or `/exec` | `get_skill("executing-plans")` |
+| `/design` or `/frontend` | `get_skill("frontend-design")` |
+| `/pr` | `get_skill("pr-all-in-one")` |
+
+For unrecognized slash commands, call `recommend_skills` to find the closest match.
+
+## AUTO Mode
+
+AUTO mode enables autonomous PLAN -> ACT -> EVAL cycling until quality criteria are met.
+
+### Triggering AUTO Mode
+
+Use the `AUTO` keyword at the start of your message:
+
+| Language | Keyword |
+|----------|---------|
+| English | `AUTO` |
+| Korean | `AUTO` |
+| Japanese | `自動` |
+| Chinese | `自动` |
+| Spanish | `AUTOMATICO` |
+
+### Workflow
+
+1. **PLAN Phase**: Creates implementation plan with quality criteria
+2. **ACT Phase**: Executes implementation following TDD workflow
+3. **EVAL Phase**: Evaluates quality against exit criteria
+4. **Loop/Exit**: Continues cycling until:
+   - Success: `Critical = 0 AND High = 0`
+   - Failure: Max iterations reached (default: 3)
+
+### Configuration
+
+Configure in `codingbuddy.config.json`:
+
+```javascript
+module.exports = {
+  auto: {
+    maxIterations: 3
+  }
+};
+```
+
+> **Windsurf limitation:** AUTO mode has no enforcement mechanism in Windsurf. See [Known Limitations](#known-limitations) for details.
+
+## Context Document Management
+
+codingbuddy uses a fixed-path context document (`docs/codingbuddy/context.md`) to persist decisions across mode transitions.
+
+### How It Works
+
+| Mode | Behavior |
+|------|----------|
+| PLAN / AUTO | Resets (clears) existing content and starts fresh |
+| ACT / EVAL | Appends new section to existing content |
+
+### Required Workflow
+
+1. `parse_mode` automatically reads/creates the context document
+2. Review `contextDocument` in the response for previous decisions
+3. **Before completing each mode:** call `update_context` to persist current work
+
+### Windsurf-Specific Note
+
+Unlike Claude Code, Windsurf has no hooks to enforce `update_context` calls. You must **manually remember** to call `update_context` before concluding each mode to avoid losing context across sessions.
+
+## Known Limitations
+
+Windsurf environment does not support several features available in Claude Code:
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| **Task tool** (background subagents) | ❌ Not available | Use `prepare_parallel_agents` for sequential execution |
+| **Native Skill tool** (`/skill-name`) | ❌ Not available | Use MCP tool chain: `recommend_skills` -> `get_skill` |
+| **Session hooks** (PreToolUse, etc.) | ❌ Not available | Rely on `.windsurf/rules/*.md` for always-on instructions |
+| **Autonomous loop mechanism** | ❌ Not available | AUTO mode depends on Cascade AI voluntarily looping |
+| **Context compaction hooks** | ❌ Not available | Manually call `update_context` before ending each mode |
+| **`dispatch_agents` full usage** | ⚠️ Partial | Returns Claude Code-specific `dispatchParams`; use `prepare_parallel_agents` instead |
+| **`restart_tui`** | ❌ Not applicable | Claude Code TUI-only tool |
+| **Rules character limit** | ⚠️ Constrained | 6,000 chars/file, 12,000 total — keep rules concise, reference `.ai-rules/` |
+
+### AUTO Mode Reliability
+
+AUTO mode documents autonomous PLAN -> ACT -> EVAL cycling. In Windsurf, this depends entirely on Cascade voluntarily continuing the loop — there is no enforcement mechanism. Results may vary:
+
+- Cascade may stop after one iteration instead of looping
+- Quality exit criteria (`Critical = 0 AND High = 0`) are advisory, not enforced
+- For reliable multi-iteration workflows, prefer manual `PLAN` -> `ACT` -> `EVAL` cycling
+
+## AGENTS.md
+
+Industry standard format compatible with all AI tools (Windsurf, Cursor, Claude Code, Codex, etc.):
+
+```markdown
+# AGENTS.md
+
+This project uses codingbuddy MCP server to manage AI Agents.
+
+## Quick Start
+...
+```
+
+See `AGENTS.md` in project root for details.
+
+## Verification Status
+
+> Documentation based on Windsurf public documentation and community resources. Runtime verification in a live Windsurf + MCP environment has not yet been performed.
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| MCP Tools Access | ⚠️ Unconfirmed | Windsurf MCP support depends on version; verify in your environment |
+| `.windsurf/rules/*.md` loading | ✅ Documented | Wave 8+ format; automatically loaded by Cascade |
+| `.windsurfrules` legacy support | ✅ Documented | Still supported; `.windsurf/rules/` preferred |
+| Global rules (`global_rules.md`) | ✅ Documented | Accessible via Settings > Manage Memories |
+| AUTO mode workflow | ⚠️ Unconfirmed | Depends on Cascade voluntarily looping |
+| Context document management | ✅ Documented | Uses standard `update_context` MCP tool |
+| Known Limitations | ✅ Documented | Task tool, hooks, character limits documented |
+
+## Reference
+
+- [Windsurf Documentation](https://docs.windsurf.com/)
+- [Windsurf Rules Guide](https://docs.windsurf.com/windsurf/cascade/memories)
+- [Windsurf Rules Directory](https://windsurf.com/editor/directory)
+- [AGENTS.md Official Spec](https://agents.md)
+- [codingbuddy MCP API](../../docs/api.md)

package/.ai-rules/agents/README.md

@@ -165,9 +165,9 @@ Primary Agent is dynamically determined based on the following priority:
 
 **Korean:**
 ```
-backend-developer로 작업해      # "Work with backend-developer" (~로 작업해 = "work with ~")
-agent-architect으로 해줘        # "Do it with agent-architect" (~으로 해줘 = "do with ~")
-devops-engineer로 개발해        # "Develop with devops-engineer" (~로 개발해 = "develop with ~")
+backend-developer work with      # "Work with backend-developer"
+agent-architect do with          # "Do it with agent-architect"
+devops-engineer develop with     # "Develop with devops-engineer"
 ```
 
 **English:**
@@ -202,6 +202,7 @@ as agent-architect, design new agent
 | Data Scientist | `primary` | EDA, ML modeling, Jupyter notebooks, data analysis and visualization |
 | Systems Developer | `primary` | Rust/C/C++, FFI bindings, embedded systems, low-level performance optimization |
 | Software Engineer | `primary` | Universal fallback — any language, any domain, when no specific agent matches |
+| Parallel Orchestrator | `primary` | Parallel issue execution, taskMaestro orchestration, Wave planning |
 
 ### EVAL Mode
 
@@ -637,7 +638,7 @@ Unified specialist agents organized by domain:
 **Activation Patterns:**
 
 - Files: `*.tf`, `*.tfvars`, `Chart.yaml`, `kustomization.yaml`, `Pulumi.yaml`, `argocd/`, `flux-system/`
-- Korean: "인프라 코드", "쿠버네티스", "테라폼", "비용 최적화", "재해 복구"
+- Korean: "infrastructure code", "Kubernetes", "Terraform", "cost optimization", "disaster recovery"
 - English: "terraform", "kubernetes", "k8s", "helm", "pulumi", "gitops", "argocd", "infrastructure as code"
 
 **Auto-Activation:** Supported via MCP server. Platform Engineer is automatically selected when prompts contain IaC/Kubernetes keywords or when working with infrastructure files.
@@ -684,7 +685,7 @@ Unified specialist agents organized by domain:
 **Activation Patterns:**
 
 - Config files: `codingbuddy.config`, `tsconfig`, `eslint`, `prettier`, `vite.config`, `next.config`
-- Korean: "설정 파일", "빌드 설정", "패키지 관리", "린터 설정"
+- Korean: "config file", "build config", "package management", "linter config"
 - English: "config file", "build config", "package management"
 
 ---
@@ -767,7 +768,7 @@ Unified specialist agents organized by domain:
 
 **Activation Patterns:**
 
-- Korean: "LLM 통합", "RAG 구현", "프롬프트 엔지니어링", "AI 안전"
+- Korean: "LLM integration", "RAG implementation", "prompt engineering", "AI safety"
 - English: "LLM integration", "RAG implementation", "prompt engineering", "AI safety"
 
 ---
@@ -812,7 +813,7 @@ Unified specialist agents organized by domain:
 **Activation Patterns:**
 
 - Files: `*.ipynb`, `*eda*.py`, `*analysis*.py`, `*model*.py`, `notebooks/`
-- Korean: "데이터 분석", "탐색적 분석", "EDA", "시각화", "회귀", "분류", "주피터"
+- Korean: "data analysis", "exploratory analysis", "EDA", "visualization", "regression", "classification", "Jupyter"
 - English: "EDA", "exploratory", "data analysis", "visualization", "regression", "classification", "pandas", "scikit-learn", "jupyter"
 
 ---
@@ -860,7 +861,7 @@ Unified specialist agents organized by domain:
 
 **Activation Patterns:**
 
-- Korean: "Rust로 구현", "C++ 최적화", "FFI 바인딩", "메모리 관리", "임베디드 개발", "WASM 구현"
+- Korean: "Rust implementation", "C++ optimization", "FFI binding", "memory management", "embedded development", "WASM implementation"
 - English: "rust implementation", "FFI binding", "memory management", "embedded", "WASM", "low-level", "systems programming"
 
 ---
@@ -957,7 +958,7 @@ Software Engineer is the **fallback of last resort** — it has no intent patter
 **Activation Patterns:**
 
 - Files: API clients, webhook handlers, OAuth implementations, external service integrations
-- Korean: "외부 서비스 연동", "웹훅", "API 통합", "서킷 브레이커"
+- Korean: "external service integration", "webhook", "API integration", "circuit breaker"
 - English: "external API", "webhook", "integration", "circuit breaker", "third-party service"
 
 **Auto-Activation:** Supported via MCP server. Integration Specialist is automatically selected when prompts contain external service integration keywords or when working with API client/webhook files.
@@ -1013,7 +1014,7 @@ Software Engineer is the **fallback of last resort** — it has no intent patter
 **Activation Patterns:**
 
 - Files: `**/events/**`, `**/kafka/**`, `**/rabbitmq/**`, `**/sqs/**`, `**/eventgrid/**`, `**/pubsub/**`, `**/eventbridge/**`, `**/*producer*.ts`, `**/*consumer*.ts`, `**/*saga*.ts`, `**/*event-store*.ts`, `**/websocket/**`
-- Korean: "이벤트 아키텍처", "메시지 큐", "카프카", "사가 패턴", "이벤트 소싱"
+- Korean: "event architecture", "message queue", "Kafka", "saga pattern", "event sourcing"
 - English: "event-driven", "message queue", "kafka", "rabbitmq", "saga pattern", "event sourcing", "CQRS", "websocket"
 
 **Auto-Activation:** Supported via MCP server. Event Architecture Specialist is automatically selected when prompts contain event-driven architecture keywords or when working with message queue/event sourcing files.
@@ -1079,7 +1080,7 @@ Software Engineer is the **fallback of last resort** — it has no intent patter
 **Activation Patterns:**
 
 - Keywords: "observability", "distributed tracing", "OpenTelemetry", "SLI", "SLO", "error budget", "structured logging", "Prometheus", "Grafana", "Jaeger"
-- Korean: "관측 가능성", "분산 추적", "SLI/SLO", "에러 버짓"
+- Korean: "observability", "distributed tracing", "SLI/SLO", "error budget"
 - English: "observability", "distributed tracing", "SLI/SLO", "error budget", "OpenTelemetry"
 
 **Auto-Activation:** Supported via MCP server. Observability Specialist is automatically selected when prompts contain observability-related keywords or when working with tracing/monitoring files.
@@ -1156,7 +1157,7 @@ Software Engineer is the **fallback of last resort** — it has no intent patter
 **Activation Patterns:**
 
 - Keywords: "migration", "migrate", "legacy", "upgrade", "strangler fig", "rollback", "cutover", "deprecation", "backward compatibility"
-- Korean: "마이그레이션", "이전", "레거시", "업그레이드", "롤백", "호환성", "전환"
+- Korean: "migration", "transfer", "legacy", "upgrade", "rollback", "compatibility", "transition"
 - English: "migration", "legacy modernization", "framework upgrade", "zero-downtime", "api versioning"
 
 **Auto-Activation:** Supported via MCP server. Migration Specialist is automatically selected when prompts contain migration-related keywords or when working with migration/upgrade files.
@@ -1631,6 +1632,8 @@ Some specialist agents define **delegation rules** to clarify when work should b
 Each agent JSON contains:
 
 - **name**: Agent identifier
+- **description**: Brief description of the agent
+- **color**: Unique hex color code for visual identification (e.g., `#61DAFB`)
 - **role**: Title and expertise areas
 - **context_files**: Rules to reference
 - **modes**: Planning, implementation, and evaluation frameworks (for unified specialists)
@@ -1642,6 +1645,52 @@ Each agent JSON contains:
 - **design_system**: UI component guidelines
 - **communication**: Response language and style
 
+### Color Reference
+
+Each agent has a unique `color` field (hex code) for visual identification in UIs and dashboards.
+
+| Agent | Color | Hex |
+|-------|-------|-----|
+| **Mode Agents** | | |
+| Plan Mode | ![#6C8EBF](https://via.placeholder.com/12/6C8EBF/6C8EBF.png) Steel Blue | `#6C8EBF` |
+| Act Mode | ![#82B366](https://via.placeholder.com/12/82B366/82B366.png) Sage Green | `#82B366` |
+| Eval Mode | ![#D4A843](https://via.placeholder.com/12/D4A843/D4A843.png) Golden | `#D4A843` |
+| Auto Mode | ![#B85450](https://via.placeholder.com/12/B85450/B85450.png) Rust Red | `#B85450` |
+| **Primary Agents** | | |
+| Solution Architect | ![#4A90D9](https://via.placeholder.com/12/4A90D9/4A90D9.png) Royal Blue | `#4A90D9` |
+| Technical Planner | ![#7B68EE](https://via.placeholder.com/12/7B68EE/7B68EE.png) Slate Blue | `#7B68EE` |
+| Frontend Developer | ![#61DAFB](https://via.placeholder.com/12/61DAFB/61DAFB.png) React Cyan | `#61DAFB` |
+| Backend Developer | ![#68A063](https://via.placeholder.com/12/68A063/68A063.png) Node Green | `#68A063` |
+| Mobile Developer | ![#A4C639](https://via.placeholder.com/12/A4C639/A4C639.png) Android Green | `#A4C639` |
+| Data Engineer | ![#E97451](https://via.placeholder.com/12/E97451/E97451.png) Burnt Sienna | `#E97451` |
+| Agent Architect | ![#9B59B6](https://via.placeholder.com/12/9B59B6/9B59B6.png) Amethyst | `#9B59B6` |
+| Platform Engineer | ![#3498DB](https://via.placeholder.com/12/3498DB/3498DB.png) Dodger Blue | `#3498DB` |
+| Tooling Engineer | ![#95A5A6](https://via.placeholder.com/12/95A5A6/95A5A6.png) Concrete | `#95A5A6` |
+| AI/ML Engineer | ![#FF6F61](https://via.placeholder.com/12/FF6F61/FF6F61.png) Coral | `#FF6F61` |
+| DevOps Engineer | ![#2ECC71](https://via.placeholder.com/12/2ECC71/2ECC71.png) Emerald | `#2ECC71` |
+| Test Engineer | ![#F39C12](https://via.placeholder.com/12/F39C12/F39C12.png) Orange | `#F39C12` |
+| Security Engineer | ![#E74C3C](https://via.placeholder.com/12/E74C3C/E74C3C.png) Alizarin | `#E74C3C` |
+| Software Engineer | ![#1ABC9C](https://via.placeholder.com/12/1ABC9C/1ABC9C.png) Turquoise | `#1ABC9C` |
+| Data Scientist | ![#8E44AD](https://via.placeholder.com/12/8E44AD/8E44AD.png) Wisteria | `#8E44AD` |
+| Systems Developer | ![#D35400](https://via.placeholder.com/12/D35400/D35400.png) Pumpkin | `#D35400` |
+| **Domain Specialists** | | |
+| Architecture | ![#2C3E80](https://via.placeholder.com/12/2C3E80/2C3E80.png) Navy | `#2C3E80` |
+| Test Strategy | ![#F1C40F](https://via.placeholder.com/12/F1C40F/F1C40F.png) Sunflower | `#F1C40F` |
+| Performance | ![#E67E22](https://via.placeholder.com/12/E67E22/E67E22.png) Carrot | `#E67E22` |
+| Security | ![#C0392B](https://via.placeholder.com/12/C0392B/C0392B.png) Pomegranate | `#C0392B` |
+| Accessibility | ![#27AE60](https://via.placeholder.com/12/27AE60/27AE60.png) Nephritis | `#27AE60` |
+| SEO | ![#16A085](https://via.placeholder.com/12/16A085/16A085.png) Green Sea | `#16A085` |
+| UI/UX Designer | ![#E91E63](https://via.placeholder.com/12/E91E63/E91E63.png) Pink | `#E91E63` |
+| Documentation | ![#607D8B](https://via.placeholder.com/12/607D8B/607D8B.png) Blue Gray | `#607D8B` |
+| Integration | ![#00BCD4](https://via.placeholder.com/12/00BCD4/00BCD4.png) Cyan | `#00BCD4` |
+| Event Architecture | ![#FF5722](https://via.placeholder.com/12/FF5722/FF5722.png) Deep Orange | `#FF5722` |
+| Observability | ![#795548](https://via.placeholder.com/12/795548/795548.png) Brown | `#795548` |
+| Migration | ![#FF9800](https://via.placeholder.com/12/FF9800/FF9800.png) Amber | `#FF9800` |
+| i18n | ![#009688](https://via.placeholder.com/12/009688/009688.png) Teal | `#009688` |
+| **Utility Agents** | | |
+| Code Quality | ![#8BC34A](https://via.placeholder.com/12/8BC34A/8BC34A.png) Light Green | `#8BC34A` |
+| Code Reviewer | ![#673AB7](https://via.placeholder.com/12/673AB7/673AB7.png) Deep Purple | `#673AB7` |
+
 ---
 
 ## Adding New Agents
@@ -1667,6 +1716,7 @@ Create a new JSON file following this structure:
 {
   "name": "Agent Name",
   "description": "Brief description",
+  "color": "#HEXCOD",
   "role": {
     "title": "Role Title",
     "expertise": [],
@@ -1723,7 +1773,7 @@ Add a regex pattern to detect specialist-relevant keywords in user prompts:
 // apps/mcp-server/src/keyword/keyword.service.ts
 {
   pattern:
-    /keyword1|keyword2|한국어키워드|english\s*pattern/i,
+    /keyword1|keyword2|korean_keyword|english\s*pattern/i,
   specialist: '{domain}-specialist',
 },
 ```
@@ -1810,8 +1860,8 @@ describe('{domain}-specialist pattern', () => {
   });
 
   it.each([
-    '한국어 키워드 1',
-    '한국어 키워드 2',
+    'Korean keyword 1',
+    'Korean keyword 2',
     // ... more Korean patterns
   ])('detects {domain}-specialist for Korean: %s', async prompt => {
     const result = await service.parseMode(`PLAN ${prompt}`);
@@ -1869,7 +1919,7 @@ When modifying an existing specialist's integration:
 pattern: /existing|keywords/i,
 
 // After
-pattern: /existing|keywords|new_keyword|새키워드/i,
+pattern: /existing|keywords|new_keyword|new_korean_keyword/i,
 ```
 
 #### Adding New File Patterns

package/.ai-rules/agents/accessibility-specialist.json

@@ -1,6 +1,7 @@
 {
   "name": "Accessibility Specialist",
   "description": "Accessibility expert for Planning, Implementation, and Evaluation modes - unified specialist for WCAG 2.1 AA compliance, ARIA attributes, and keyboard navigation",
+  "color": "#27AE60",
   "role": {
     "title": "Accessibility Engineer",
     "expertise": [
@@ -305,7 +306,7 @@
         "auto_activate_conditions": [
           "UI component development or modifications",
           "Form component creation",
-          "User explicitly requests accessibility review (A11Y, 접근성 검토)",
+          "User explicitly requests accessibility review (A11Y, accessibility review)",
           "Code Reviewer identifies accessibility concerns"
         ],
         "mandatory_checklist": {
@@ -496,5 +497,11 @@
       "project_accessibility": "See project.md 'UX & Accessibility' section"
     },
     "project_rules": "See .ai-rules/rules/"
+  },
+  "visual": {
+    "eye": "✦",
+    "eyeFallback": "O",
+    "colorAnsi": "yellow",
+    "group": "frontend"
   }
 }

package/.ai-rules/agents/act-mode.json

@@ -1,6 +1,7 @@
 {
   "name": "Act Mode Agent",
   "description": "ACT mode agent - specialized for actual implementation execution",
+  "color": "#82B366",
   "role": {
     "title": "Act Mode Agent",
     "mode": "ACT",
@@ -31,7 +32,7 @@
     ".ai-rules/rules/augmented-coding.md"
   ],
   "activation": {
-    "trigger": "🔴 **STRICT**: When user types 'ACT' or equivalent (Korean: 실행, Japanese: 実行, Chinese: 执行, Spanish: ACTUAR)",
+    "trigger": "🔴 **STRICT**: When user types 'ACT' or equivalent (Korean: execute, Japanese: 実行, Chinese: 执行, Spanish: ACTUAR)",
     "rule": "🔴 **STRICT**: ACT MODE request must activate this Agent automatically",
     "mandatory_checklist": {
       "🔴 language": {
@@ -150,5 +151,11 @@
       "✅ Linting errors resolved",
       "✅ Design system components utilized"
     ]
+  },
+  "visual": {
+    "eye": "◆",
+    "eyeFallback": "O",
+    "colorAnsi": "blue",
+    "group": "workflow"
   }
 }