codingbuddy-rules 1.3.1 → 2.1.0

package/.ai-rules/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to the Multi-AI Coding Assistant Common Rules System will be
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-01-06
+
+### Added
+
+- **PLAN Mode Primary Agents** with intent-based resolution
+  - `solution-architect.json`: High-level system design and architecture planning
+  - `technical-planner.json`: Low-level implementation planning with TDD and bite-sized tasks
+  - Intent-based automatic selection between architects based on prompt analysis
+  - Support for Korean and English intent patterns
+
+- **AI Model Selection and Resolution**
+  - CLI init prompt for model selection (Sonnet/Opus/Haiku)
+  - `ai.defaultModel` configuration field in `codingbuddy.config.js`
+  - Agent-level model preferences with priority resolution (agent > mode > system)
+  - `resolvedModel` field in MCP tool responses
+
+- **Parallel Agent Execution Support**
+  - `get_agent_system_prompt` MCP tool for generating subagent prompts
+  - `prepare_parallel_agents` MCP tool for batch agent preparation
+  - `parallelAgentsRecommendation` in `parse_mode` response
+  - Default specialist lists per mode (PLAN/ACT/EVAL)
+
+- **Dynamic Language Configuration**
+  - `LanguageService` supporting 10 languages (ko, en, ja, zh, es, de, fr, pt, ru, hi)
+  - `languageInstruction` field in `parse_mode` response
+  - Automatic language detection from project config
+
+- **Agent Activation Transparency**
+  - `ActivationMessageBuilder` for clear agent activation reporting
+  - `activation_message` field showing active agents with tiers
+
+### Changed
+
+- **Primary Agent Resolution**
+  - Extended `PrimaryAgentSource` type to include `intent`
+  - Priority order: explicit > config > intent > context > default
+  - Centralized Primary Agent constants with `_LIST` variants
+
+- **Token Usage Optimization**
+  - Mode-based `core.md` filtering to reduce token consumption
+  - Shared `ResponseUtils` for consolidated response generation
+
+### Fixed
+
+- Canary deployment timestamp mismatch bug
+- Type assertions replaced with proper typing in keyword service
+
+---
+
 ## [1.0.0] - 2025-11-20
 
 ### Added
@@ -48,18 +97,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Added
-- **Clarification Phase** for PLAN mode (`rules/clarification-guide.md`)
-  - Optional phase triggered when AI detects ambiguous requirements
-  - Sequential Q&A with progress indicator (Question N/M format)
-  - Multiple-choice questions preferred for easy response
-  - Ambiguity assessment checklist (6 categories, triggers on 2+ unclear)
-  - Question count guidelines (2-7 questions based on complexity)
-  - Korean/English output format support
-  - Updated `rules/core.md` with Clarification Phase section
-
 ### Planned
-- Real-world usage testing across all 6 AI tools
+- Real-world usage testing across all 7 AI tools (including OpenCode)
 - Performance metrics collection
 - User feedback integration
 - Advanced examples and use cases

package/.ai-rules/adapters/claude-code.md

@@ -165,3 +165,288 @@ recommend_skills({ prompt: "Build a dashboard component" })
 **Supported Languages:** English, Korean, Japanese, Chinese, Spanish
 
 The tool returns skill recommendations with confidence levels (high/medium) and matched patterns for transparency.
+
+## Agent Hierarchy
+
+CodingBuddy uses a layered agent hierarchy for different types of tasks:
+
+### Tier 1: Primary Agents (Mode-specific)
+
+| Mode | Agents | Description |
+|------|--------|-------------|
+| **PLAN** | solution-architect, technical-planner | Design and planning tasks |
+| **ACT** | tooling-engineer, frontend-developer, backend-developer, devops-engineer, agent-architect | Implementation tasks |
+| **EVAL** | code-reviewer | Code review and evaluation |
+
+> **Note**: `tooling-engineer` has highest priority for config/build tool tasks (tsconfig, eslint, vite.config, package.json, etc.)
+
+### Tier 2: Specialist Agents
+
+Specialist agents can be invoked by any Primary Agent as needed:
+
+- security-specialist
+- accessibility-specialist
+- performance-specialist
+- test-strategy-specialist
+- documentation-specialist
+- architecture-specialist
+- code-quality-specialist
+- seo-specialist
+- design-system-specialist
+
+### Agent Resolution
+
+1. **PLAN mode**: Always uses `solution-architect` or `technical-planner` based on prompt analysis
+2. **ACT mode**: Resolution priority:
+   1. Explicit agent request in prompt (e.g., "backend-developer로 작업해")
+   2. `recommended_agent` parameter (from PLAN mode recommendation)
+   3. Tooling pattern matching (config files, build tools → `tooling-engineer`)
+   4. Project configuration (`primaryAgent` setting)
+   5. Context inference (file extension/path)
+   6. Default: `frontend-developer`
+3. **EVAL mode**: Always uses `code-reviewer`
+
+### Using recommended_agent Parameter
+
+When transitioning from PLAN to ACT mode, pass the recommended agent:
+
+```typescript
+// After PLAN mode returns recommended_act_agent
+const planResult = await parse_mode({ prompt: "PLAN design auth API" });
+// planResult.recommended_act_agent = { agentName: "backend-developer", ... }
+
+// Pass to ACT mode for context preservation
+const actResult = await parse_mode({
+  prompt: "ACT implement the API",
+  recommended_agent: planResult.recommended_act_agent.agentName
+});
+// actResult.delegates_to = "backend-developer" (uses the recommendation)
+```
+
+This enables seamless agent context passing across PLAN → ACT workflow transitions.
+
+## Activation Messages
+
+When agents or skills are activated, CodingBuddy displays activation messages for transparency:
+
+### Output Format
+
+```
+🤖 solution-architect [Primary Agent]
+👤 security-specialist [Specialist] (by solution-architect)
+⚡ brainstorming [Specialist] (by technical-planner)
+```
+
+### Icons
+
+| Icon | Meaning |
+|------|---------|
+| 🤖 | Primary Agent |
+| 👤 | Specialist Agent |
+| ⚡ | Skill |
+
+### ParseMode Response Fields
+
+The `parse_mode` MCP tool returns these agent-related fields:
+
+```json
+{
+  "mode": "PLAN",
+  "delegates_to": "solution-architect",
+  "primary_agent_source": "intent",
+  "activation_message": {
+    "formatted": "🤖 solution-architect [Primary Agent]",
+    "activations": [
+      {
+        "type": "agent",
+        "name": "solution-architect",
+        "tier": "primary",
+        "timestamp": "2024-01-06T12:00:00Z"
+      }
+    ]
+  },
+  "recommended_act_agent": {
+    "agentName": "backend-developer",
+    "reason": "API implementation task detected",
+    "confidence": 0.9
+  }
+}
+```
+
+### Displaying Activation Messages
+
+AI assistants should display the `activation_message.formatted` field at the start of their response:
+
+```
+🤖 solution-architect [Primary Agent]
+
+# Mode: PLAN
+
+...
+```
+
+## Parallel Specialist Agents Execution
+
+CodingBuddy supports parallel execution of multiple specialist agents for comprehensive analysis.
+
+### When to Use Parallel Execution
+
+Parallel execution is recommended when `parse_mode` returns a `parallelAgentsRecommendation` field:
+
+| Mode | Default Specialists | Use Case |
+|------|---------------------|----------|
+| **PLAN** | architecture-specialist, test-strategy-specialist | Validate architecture and test approach |
+| **ACT** | code-quality-specialist, test-strategy-specialist | Verify implementation quality |
+| **EVAL** | security-specialist, accessibility-specialist, performance-specialist, code-quality-specialist | Comprehensive multi-dimensional review |
+
+### parallelAgentsRecommendation Response Field
+
+The `parse_mode` MCP tool returns this field to recommend parallel specialist execution:
+
+```json
+{
+  "mode": "EVAL",
+  "parallelAgentsRecommendation": {
+    "specialists": [
+      "security-specialist",
+      "accessibility-specialist",
+      "performance-specialist",
+      "code-quality-specialist"
+    ],
+    "hint": "Use Task tool with subagent_type=\"general-purpose\" and run_in_background=true for each specialist. Call prepare_parallel_agents MCP tool to get ready-to-use prompts."
+  }
+}
+```
+
+### Parallel Execution Workflow
+
+```
+parse_mode 호출
+     ↓
+parallelAgentsRecommendation 확인
+     ↓ (있으면)
+사용자에게 시작 메시지 표시
+     ↓
+prepare_parallel_agents MCP 호출
+     ↓
+반환된 각 agent.taskPrompt를 Task tool로 병렬 호출:
+  - subagent_type: "general-purpose"
+  - run_in_background: true
+  - prompt: agent.taskPrompt
+     ↓
+TaskOutput으로 결과 수집
+     ↓
+사용자에게 결과 종합하여 표시
+```
+
+### Code Example
+
+```typescript
+// Step 1: Parse mode returns parallelAgentsRecommendation
+const parseModeResult = await parse_mode({ prompt: "EVAL review auth implementation" });
+
+if (parseModeResult.parallelAgentsRecommendation) {
+  // Step 2: Display start message to user
+  console.log("🚀 Dispatching 4 specialist agents in parallel...");
+  console.log("   → 🔒 security-specialist");
+  console.log("   → ♿ accessibility-specialist");
+  console.log("   → ⚡ performance-specialist");
+  console.log("   → 📏 code-quality-specialist");
+
+  // Step 3: Prepare parallel agents
+  const preparedAgents = await prepare_parallel_agents({
+    mode: "EVAL",
+    specialists: parseModeResult.parallelAgentsRecommendation.specialists,
+    sharedContext: "Review authentication implementation",
+    targetFiles: ["src/auth/login.tsx"]
+  });
+
+  // Step 4: Execute in parallel using Task tool
+  const agentTasks = preparedAgents.agents.map(agent =>
+    Task({
+      subagent_type: "general-purpose",
+      prompt: agent.taskPrompt,
+      description: agent.description,
+      run_in_background: true,
+      model: "haiku" // Use haiku for efficiency
+    })
+  );
+
+  // Step 5: Collect results
+  const results = await Promise.all(agentTasks.map(task => TaskOutput(task.id)));
+
+  // Step 6: Display summary
+  console.log("📊 Specialist Analysis Complete:");
+  results.forEach(result => console.log(result.summary));
+}
+```
+
+### Visibility Pattern
+
+When executing parallel specialists, display clear status messages:
+
+**Start Message:**
+```
+🚀 Dispatching N specialist agents in parallel...
+   → 🔒 security-specialist
+   → ♿ accessibility-specialist
+   → ⚡ performance-specialist
+   → 📏 code-quality-specialist
+```
+
+**Completion Message:**
+```
+📊 Specialist Analysis Complete:
+
+🔒 Security Specialist:
+   [findings summary]
+
+♿ Accessibility Specialist:
+   [findings summary]
+
+⚡ Performance Specialist:
+   [findings summary]
+
+📏 Code Quality Specialist:
+   [findings summary]
+```
+
+### Specialist Icons
+
+| Icon | Specialist |
+|------|------------|
+| 🔒 | security-specialist |
+| ♿ | accessibility-specialist |
+| ⚡ | performance-specialist |
+| 📏 | code-quality-specialist |
+| 🧪 | test-strategy-specialist |
+| 🏛️ | architecture-specialist |
+| 📚 | documentation-specialist |
+| 🔍 | seo-specialist |
+| 🎨 | design-system-specialist |
+
+### Handling Failures
+
+When `prepare_parallel_agents` returns `failedAgents`:
+
+```
+⚠️ Some agents failed to load:
+   ✗ performance-specialist: Profile not found
+
+Continuing with 3/4 agents...
+```
+
+**Strategy:**
+- Continue with successfully loaded agents
+- Report failures clearly to user
+- Document which agents couldn't be loaded in final report
+
+### Specialist Activation Scope
+
+Each workflow mode activates different specialist agents:
+
+- **PLAN mode**: Architecture and test strategy specialists validate design
+- **ACT mode**: Code quality and test strategy specialists verify implementation
+- **EVAL mode**: Security, accessibility, performance, and code quality specialists provide comprehensive review
+
+**Important:** Specialists from one mode do NOT carry over to the next mode. Each mode has its own recommended specialist set.

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

@@ -1,151 +1,173 @@
 # Cursor Integration Guide
 
-This guide explains how to use the common AI rules (`.ai-rules/`) in Cursor.
+Guide for using codingbuddy with Cursor.
 
 ## Overview
 
-Cursor continues to use its native `.cursor/` directory structure while referencing the common rules from `.ai-rules/`.
+codingbuddy integrates with Cursor in two ways:
 
-## Integration Method
+1. **AGENTS.md** - Industry standard format compatible with all AI tools
+2. **.cursor/rules/*.mdc** - Cursor-specific optimization (glob-based auto-activation)
 
-### 1. Reference Common Rules
+## Two Usage Contexts
 
-Create `.cursor/rules/imports.mdc` to reference common rules:
+### End Users (Your Project)
 
-```markdown
+End users access rules **only through MCP tools**. No local rule files needed.
+
+```json
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy"]
+    }
+  }
+}
+```
+
+Optional: Create `.cursor/rules/codingbuddy.mdc` for basic integration:
+
+```yaml
 ---
-description: Common AI Rules Import
+description: codingbuddy integration
 globs:
 alwaysApply: true
 ---
 
-# Common Rules
-
-This project uses shared rules from `.ai-rules/` directory for all AI assistants.
-
-## 📚 Core Rules
-See [../../.ai-rules/rules/core.md](../../.ai-rules/rules/core.md) for:
-- PLAN/ACT/EVAL workflow modes
-- Agent activation rules
-- Communication guidelines
-
-## 🏗️ Project Setup
-See [../../.ai-rules/rules/project.md](../../.ai-rules/rules/project.md) for:
-- Tech stack and dependencies
-- Project structure and architecture
-- Development rules and conventions
-- Domain knowledge and business context
-
-## 🎯 Augmented Coding Principles
-See [../../.ai-rules/rules/augmented-coding.md](../../.ai-rules/rules/augmented-coding.md) for:
-- TDD cycle (Red → Green → Refactor)
-- Code quality standards (SOLID, DRY)
-- Testing best practices
-- Commit discipline
-
-## 🤖 Specialist Agents
-See [../../.ai-rules/agents/README.md](../../.ai-rules/agents/README.md) for available specialist agents:
-- Frontend Developer, Code Reviewer
-- Architecture, Test Strategy, Performance, Security
-- Accessibility, SEO, Design System, Documentation
-- Code Quality, DevOps Engineer
+When PLAN, ACT, EVAL keywords detected → call `parse_mode` MCP tool
 ```
 
-### 2. Keep Cursor-Specific Features
+### Monorepo Contributors
 
-Maintain `.cursor/rules/cursor-specific.mdc` for Cursor-only features:
+Contributors to the codingbuddy repository can use direct file references:
 
-```markdown
+```
+Project Root/
+├── AGENTS.md                    # Cross-platform entry point
+├── .cursor/rules/
+│   ├── imports.mdc              # Common rules (alwaysApply: true)
+│   ├── auto-agent.mdc           # File pattern-based Agent auto-activation
+│   └── custom.mdc               # Personal settings (Git ignored)
+└── 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/`
+- AGENTS.md and .mdc files act as **pointers only**
+- No duplication, only references
+
+## Configuration Files
+
+### imports.mdc (alwaysApply)
+
+Core rules automatically applied to all conversations:
+
+```yaml
 ---
-description: Cursor-specific configurations
+description: codingbuddy common rules
 globs:
 alwaysApply: true
 ---
 
-# Cursor-Specific Features
+# Core principles only (details in .ai-rules/)
+```
 
-## File Globbing
+### auto-agent.mdc (glob-based)
 
-[Add Cursor-specific glob patterns here]
+Automatically provides appropriate Agent context based on file patterns:
 
-## Agent Tool Integration
+```yaml
+---
+description: Agent auto-activation
+globs:
+  - "**/*.tsx"
+  - "**/*.ts"
+  - "**/*.go"
+alwaysApply: false
+---
 
-[Add Cursor-specific todo_write tool usage]
+# File pattern → Agent mapping table
 ```
 
-## Current Structure
+## Usage
+
+### Mode Keywords
 
 ```
-.cursor/
-├── agents/              # Keep for Cursor compatibility
-├── rules/
-│   ├── core.mdc        # Keep existing (can add reference to .ai-rules)
-│   ├── project.mdc     # Keep existing (can add reference to .ai-rules)
-│   ├── augmented-coding.mdc  # Keep existing
-│   ├── imports.mdc     # NEW: References to .ai-rules
-│   └── cursor-specific.mdc   # NEW: Cursor-only features
-└── config.json         # Cursor configuration
-
-.ai-rules/              # Common rules for all AI tools
-├── rules/
-│   ├── core.md
-│   ├── project.md
-│   └── augmented-coding.md
-├── agents/
-│   └── *.json
-└── adapters/
-    └── cursor.md (this file)
+PLAN Design user authentication feature
 ```
 
-## Usage
+→ `parse_mode` MCP tool is called, loading appropriate Agent and rules
 
-### In Cursor Chat
+### Auto-Activation on File Edit
 
-Reference rules directly:
-```
-@.ai-rules/rules/core.md
-@.ai-rules/agents/frontend-developer.json
+Open `.tsx` file → `auto-agent.mdc` auto-applies → frontend-developer Agent recommended
 
-Create a new feature following our common workflow
-```
+### Specialist Usage
 
-### In Cursor Composer
-
-The `.cursor/rules/imports.mdc` with `alwaysApply: true` will automatically apply common rules to all Composer sessions.
+```
+EVAL Review from security perspective
+```
 
-## Benefits
+→ security-specialist activated
 
-- ✅ Seamless integration with existing Cursor setup
-- ✅ Access to common rules shared across all AI tools
-- ✅ Cursor-specific features (globs, alwaysApply) still work
-- ✅ Easy to update: change `.ai-rules/` once, all tools benefit
+## MCP Tools
 
-## Maintenance
+Available codingbuddy MCP tools in Cursor:
 
-When updating rules:
-1. Update `.ai-rules/rules/*.md` for changes affecting all AI tools
-2. Update `.cursor/rules/*.mdc` only for Cursor-specific changes
-3. Keep both in sync for best experience
+| Tool | Purpose |
+|------|---------|
+| `parse_mode` | Parse mode keywords + load Agent/rules |
+| `get_agent_details` | Get specific Agent details |
+| `get_project_config` | Get project configuration |
+| `recommend_skills` | Recommend skills based on prompt |
+| `prepare_parallel_agents` | Prepare parallel Agent execution |
 
 ## Skills
 
 ### Using Skills in Cursor
 
-Reference skills in your prompts using file inclusion:
+Load skills via file reference (monorepo only):
 
 ```
-@.ai-rules/skills/test-driven-development/SKILL.md
+@packages/rules/.ai-rules/skills/test-driven-development/SKILL.md
 ```
 
-Or manually include skill content in `.cursorrules`.
+For end users, use `recommend_skills` MCP tool instead.
 
 ### Available Skills
 
-- `.ai-rules/skills/brainstorming/SKILL.md`
-- `.ai-rules/skills/test-driven-development/SKILL.md`
-- `.ai-rules/skills/systematic-debugging/SKILL.md`
-- `.ai-rules/skills/writing-plans/SKILL.md`
-- `.ai-rules/skills/executing-plans/SKILL.md`
-- `.ai-rules/skills/subagent-driven-development/SKILL.md`
-- `.ai-rules/skills/dispatching-parallel-agents/SKILL.md`
-- `.ai-rules/skills/frontend-design/SKILL.md`
+- `brainstorming/SKILL.md` - Idea → Design
+- `test-driven-development/SKILL.md` - TDD workflow
+- `systematic-debugging/SKILL.md` - Systematic debugging
+- `writing-plans/SKILL.md` - Implementation plan writing
+- `executing-plans/SKILL.md` - Plan execution
+- `subagent-driven-development/SKILL.md` - Subagent development
+- `dispatching-parallel-agents/SKILL.md` - Parallel Agent dispatch
+- `frontend-design/SKILL.md` - Frontend design
+
+## AGENTS.md
+
+Industry standard format compatible with all AI tools (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.
+
+## Reference
+
+- [AGENTS.md Official Spec](https://agents.md)
+- [Cursor Rules Documentation](https://cursor.com/docs/context/rules)
+- [codingbuddy MCP API](../../docs/api.md)

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

@@ -182,11 +182,40 @@ Once connected, you can use:
 - `search_rules`: Query AI rules and guidelines
 - `get_agent_details`: Get specialist agent information
 - `recommend_skills`: Get skill recommendations based on prompt
-- `parse_mode`: Parse PLAN/ACT/EVAL workflow mode (now returns Mode Agent information)
+- `parse_mode`: Parse PLAN/ACT/EVAL workflow mode (includes dynamic language instructions)
+
+#### Dynamic Language Configuration
+
+OpenCode agents get language instructions dynamically from the MCP server:
+
+1. **Set language in codingbuddy.config.js:**
+   ```javascript
+   module.exports = {
+     language: 'ko',  // or 'en', 'ja', 'zh', 'es', etc.
+     // ... other config
+   };
+   ```
+
+2. **Call parse_mode to get dynamic language instruction:**
+   ```bash
+   # AI should call parse_mode when user starts with PLAN/ACT/EVAL
+   # Returns languageInstruction field automatically
+   ```
+
+3. **Remove hardcoded language from agent prompts:**
+   ```json
+   {
+     "agent": {
+       "plan-mode": {
+         "prompt": "{file:...plan-mode.json}\n\n[OpenCode Override]\nMode: PLAN only. Use languageInstruction from parse_mode response.",
+       }
+     }
+   }
+   ```
 
 #### Enhanced parse_mode Response
 
-The `parse_mode` tool now returns additional Mode Agent information:
+The `parse_mode` tool now returns additional Mode Agent information and dynamic language instructions:
 
 ```json
 {
@@ -194,6 +223,8 @@ The `parse_mode` tool now returns additional Mode Agent information:
   "originalPrompt": "새로운 사용자 등록 기능을 만들어줘",
   "instructions": "설계 우선 접근. TDD 관점에서...",
   "rules": [...],
+  "language": "ko",
+  "languageInstruction": "Always respond in Korean (한국어).",
   "agent": "plan-mode",
   "delegates_to": "frontend-developer", 
   "delegate_agent_info": {
@@ -205,6 +236,8 @@ The `parse_mode` tool now returns additional Mode Agent information:
 ```
 
 **New Fields:**
+- `language`: Language code from codingbuddy.config.js
+- `languageInstruction`: Formatted instruction text for AI assistants (🆕)
 - `agent`: Mode Agent name (plan-mode, act-mode, eval-mode)
 - `delegates_to`: Which specialist agent the Mode Agent delegates to
 - `delegate_agent_info`: Detailed information about the delegate agent (optional)