codingbuddy-rules 4.2.0 → 4.4.0

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

@@ -37,7 +37,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "plan-mode": {
       "description": "PLAN mode - Analysis and planning without changes",
       "mode": "primary",
-      "prompt": "{file:packages/rules/.ai-rules/agents/plan-mode.json}\n\n[OpenCode Override]\nMode: PLAN only. Always respond in Korean. Do NOT make any file changes. Focus on analysis and planning.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/plan-mode.json}\n\n[OpenCode Override]\nMode: PLAN only. Do NOT make any file changes. Focus on analysis and planning. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "deny",
         "bash": {
@@ -51,7 +51,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "act-mode": {
       "description": "ACT mode - Full development with all tools",
       "mode": "primary",
-      "prompt": "{file:packages/rules/.ai-rules/agents/act-mode.json}\n\n[OpenCode Override]\nMode: ACT. Always respond in Korean. Follow TDD workflow and code quality standards.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/act-mode.json}\n\n[OpenCode Override]\nMode: ACT. Follow TDD workflow and code quality standards. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "allow",
         "bash": "allow"
@@ -60,7 +60,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "eval-mode": {
       "description": "EVAL mode - Code quality evaluation", 
       "mode": "primary",
-      "prompt": "{file:packages/rules/.ai-rules/agents/eval-mode.json}\n\n[OpenCode Override]\nMode: EVAL. Always respond in Korean. Provide evidence-based evaluation.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/eval-mode.json}\n\n[OpenCode Override]\nMode: EVAL. Provide evidence-based evaluation. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "deny",
         "bash": {
@@ -74,7 +74,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "backend": {
       "description": "Backend development - Node.js, Python, Go, Java, Rust",
       "mode": "subagent",
-      "prompt": "{file:packages/rules/.ai-rules/agents/backend-developer.json}\n\n[OpenCode Override]\nAlways respond in Korean. Follow TDD workflow and clean architecture.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/backend-developer.json}\n\n[OpenCode Override]\nFollow TDD workflow and clean architecture. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "allow",
         "bash": "allow"
@@ -83,7 +83,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "architect": {
       "description": "Architecture and design patterns specialist",
       "mode": "subagent",
-      "prompt": "{file:packages/rules/.ai-rules/agents/architecture-specialist.json}\n\n[OpenCode Override]\nAlways respond in Korean. Focus on layer boundaries and dependency direction.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/architecture-specialist.json}\n\n[OpenCode Override]\nFocus on layer boundaries and dependency direction. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "deny",
         "bash": "ask"
@@ -92,7 +92,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "tester": {
       "description": "Test strategy and TDD specialist",
       "mode": "subagent",
-      "prompt": "{file:packages/rules/.ai-rules/agents/test-strategy-specialist.json}\n\n[OpenCode Override]\nAlways respond in Korean. Enforce 90%+ coverage and no-mocking principle.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/test-strategy-specialist.json}\n\n[OpenCode Override]\nEnforce 90%+ coverage and no-mocking principle. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "allow",
         "bash": "allow"
@@ -101,7 +101,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "security": {
       "description": "Security audit - OAuth, JWT, XSS/CSRF protection",
       "mode": "subagent",
-      "prompt": "{file:packages/rules/.ai-rules/agents/security-specialist.json}\n\n[OpenCode Override]\nAlways respond in Korean. Follow OWASP guidelines.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/security-specialist.json}\n\n[OpenCode Override]\nFollow OWASP guidelines. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "deny",
         "bash": "ask"
@@ -110,7 +110,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "a11y": {
       "description": "Accessibility - WCAG 2.1 AA compliance",
       "mode": "subagent",
-      "prompt": "{file:packages/rules/.ai-rules/agents/accessibility-specialist.json}\n\n[OpenCode Override]\nAlways respond in Korean. Verify ARIA and keyboard navigation.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/accessibility-specialist.json}\n\n[OpenCode Override]\nVerify ARIA and keyboard navigation. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "deny",
         "bash": "ask"
@@ -119,7 +119,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
     "performance": {
       "description": "Performance optimization specialist",
       "mode": "subagent",
-      "prompt": "{file:packages/rules/.ai-rules/agents/performance-specialist.json}\n\n[OpenCode Override]\nAlways respond in Korean. Focus on bundle size and runtime optimization.",
+      "prompt": "{file:packages/rules/.ai-rules/agents/performance-specialist.json}\n\n[OpenCode Override]\nFocus on bundle size and runtime optimization. Follow languageInstruction from parse_mode response.",
       "permission": {
         "edit": "deny",
         "bash": "ask"
@@ -130,12 +130,17 @@ Update your configuration file (`.opencode.json` or `crush.json`):
   "mcp": {
     "codingbuddy": {
       "type": "local",
-      "command": ["npx", "codingbuddy@latest", "mcp"]
+      "command": ["npx", "codingbuddy@latest", "mcp"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project"
+      }
     }
   }
 }
 ```
 
+> **Note:** `auto-mode` does not require a separate agent entry. AUTO mode is triggered by prefixing any message with the `AUTO` keyword while using the `plan-mode` agent (see [AUTO Mode](#auto-mode) section below).
+
 ### 2. Agent System Mapping
 
 | Codingbuddy Agent | OpenCode Agent | Purpose |
@@ -143,6 +148,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
 | **plan-mode.json** | `plan-mode` | PLAN mode workflow (delegates to frontend-developer) |
 | **act-mode.json** | `act-mode` | ACT mode workflow (delegates to frontend-developer) |
 | **eval-mode.json** | `eval-mode` | EVAL mode workflow (delegates to code-reviewer) |
+| **auto-mode.json** | N/A (keyword-triggered) | AUTO mode workflow (autonomous PLAN→ACT→EVAL cycle) |
 | **frontend-developer.json** | N/A (delegate) | Primary development implementation |
 | **backend-developer.json** | `backend` | Backend development (Node.js, Python, Go, Java, Rust) |
 | **code-reviewer.json** | N/A (delegate) | Code quality evaluation implementation |
@@ -154,7 +160,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
 
 #### Mode Agent vs Specialist Agent
 
-- **Mode Agents** (`plan-mode`, `act-mode`, `eval-mode`): Workflow orchestrators that delegate to appropriate implementation agents
+- **Mode Agents** (`plan-mode`, `act-mode`, `eval-mode`, `auto-mode`): Workflow orchestrators that delegate to appropriate implementation agents
 - **Specialist Agents** (`architect`, `security`, etc.): Domain-specific expertise for specialized tasks
 - **Delegate Agents** (`frontend-developer`, `code-reviewer`): Implementation agents that Mode Agents delegate to
 
@@ -170,19 +176,79 @@ Add to your MCP configuration:
     "codingbuddy": {
       "type": "local",
       "command": ["npx", "codingbuddy@latest", "mcp"],
-      "env": ["NODE_ENV=production"]
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project"
+      }
     }
   }
 }
 ```
 
+> **Important:** OpenCode/Crush의 `roots/list` MCP capability 지원 여부는 미확인입니다.
+> `CODINGBUDDY_PROJECT_ROOT` 없이는 서버가 프로젝트의 `codingbuddy.config.json`을 찾지 못하여
+> `language` 등 설정이 기본값으로 동작합니다. 항상 이 환경변수를 프로젝트의 절대 경로로 설정하세요.
+
 #### Available MCP Tools
 
-Once connected, you can use:
+Once connected, you can use the following tools (17 tools total):
+
+**Core Workflow:**
+- `parse_mode`: Parse PLAN/ACT/EVAL/AUTO workflow mode (includes dynamic language instructions)
+- `update_context`: Persist decisions and notes to `docs/codingbuddy/context.md` (**mandatory** at mode completion)
+- `read_context`: Read current context document
+- `cleanup_context`: Manually trigger context document cleanup (auto-triggered when size exceeds threshold)
+
+**Analysis & Planning:**
 - `search_rules`: Query AI rules and guidelines
+- `analyze_task`: Pre-planning task analysis with risk assessment and specialist recommendations
+- `generate_checklist`: Contextual checklists (security, accessibility, performance, testing)
+
+**Agent Dispatch:**
 - `get_agent_details`: Get specialist agent information
+- `get_agent_system_prompt`: Get complete system prompt for a specialist agent
+- `dispatch_agents`: Get Task tool-ready dispatch parameters for agents
+- `prepare_parallel_agents`: Ready-to-use prompts for parallel specialist agents
+
+**Skills:**
 - `recommend_skills`: Get skill recommendations based on prompt
-- `parse_mode`: Parse PLAN/ACT/EVAL workflow mode (includes dynamic language instructions)
+- `get_skill`: Load full skill content by name
+- `list_skills`: List all available skills with optional filtering
+
+**Configuration:**
+- `get_project_config`: Get project configuration (tech stack, architecture, language)
+- `get_code_conventions`: Get project code conventions
+- `suggest_config_updates`: Analyze project and suggest config updates based on detected changes
+
+#### Context Persistence Workflow
+
+The `update_context` tool persists PLAN/ACT/EVAL decisions to `docs/codingbuddy/context.md`. This is **mandatory** — without it, context is lost between mode switches and context compaction.
+
+**Workflow:**
+
+```
+PLAN mode:
+  parse_mode → (automatically resets context document)
+  ... do planning work ...
+  update_context({ mode: "PLAN", task: "...", decisions: [...], notes: [...] })
+
+ACT mode:
+  parse_mode → (reads existing context, appends new section)
+  ... review previous PLAN decisions from contextDocument ...
+  ... implement changes ...
+  update_context({ mode: "ACT", progress: [...], notes: [...] })
+
+EVAL mode:
+  parse_mode → (reads existing context, appends new section)
+  ... review PLAN decisions + ACT progress from contextDocument ...
+  ... evaluate quality ...
+  update_context({ mode: "EVAL", findings: [...], recommendations: [...] })
+```
+
+**Key Rules:**
+- `parse_mode` automatically manages the context file (reset in PLAN, append in ACT/EVAL)
+- You **must** call `update_context` before completing each mode
+- The context file survives context compaction — it is the only persistent memory across modes
+- Use `read_context` to check current context state at any time
 
 #### Dynamic Language Configuration
 
@@ -238,7 +304,7 @@ The `parse_mode` tool now returns additional Mode Agent information and dynamic
 **New Fields:**
 - `language`: Language code from codingbuddy.config.json
 - `languageInstruction`: Formatted instruction text for AI assistants (🆕)
-- `agent`: Mode Agent name (plan-mode, act-mode, eval-mode)
+- `agent`: Mode Agent name (plan-mode, act-mode, eval-mode, auto-mode)
 - `delegates_to`: Which specialist agent the Mode Agent delegates to
 - `delegate_agent_info`: Detailed information about the delegate agent (optional)
 
@@ -388,18 +454,30 @@ For Crush users, additional features available:
 }
 ```
 
-### Skills System
+### Skills Integration
+
+Crush supports skills through two mechanisms:
+
+1. **Native Discovery**: Place skills in `~/.config/crush/skills/` or configure additional paths via `options.skills_paths`. Crush automatically injects available skills into the system prompt.
+
+2. **MCP Tools (Recommended)**: Use codingbuddy MCP server's skill tools for cross-platform, programmatic skill access:
+   - `recommend_skills` — prompt-based skill recommendations
+   - `get_skill` — load full skill content by name
+   - `list_skills` — list all available skills
+
+**Configuration:**
 ```json
 {
   "options": {
     "skills_paths": [
-      "packages/rules/.ai-rules/skills",
-      "~/.config/crush/skills"
+      "packages/rules/.ai-rules/skills"
     ]
   }
 }
 ```
 
+> **Note:** There is no `/skill` slash command. Skills are activated through natural language or via MCP tools. See [opencode-skills.md](opencode-skills.md) for detailed usage patterns.
+
 ## Benefits
 
 ### ✅ Advantages
@@ -409,14 +487,14 @@ For Crush users, additional features available:
 - **Agent-based Workflow**: Clear separation of concerns
 - **Consistent Standards**: Same rules across all AI tools
 - **MCP Integration**: Access to specialized tools and knowledge
-- **Korean Language Support**: Full Korean responses configured
+- **Dynamic Language Support**: Configurable language via codingbuddy.config.json (ko, en, ja, zh, es, etc.)
 
 ### ✅ Key Features
 
 - **Dynamic Model Switching**: Change AI models during session
 - **Advanced Permissions**: Fine-grained tool access control
 - **Auto-initialization**: Project-specific context loading
-- **File Reference System**: `{file:path}` syntax for instructions
+- **File Reference System**: `{file:path}` syntax for instructions — *unverified in Crush*
 
 ## Troubleshooting
 
@@ -441,9 +519,20 @@ npx codingbuddy@latest --version
 npx codingbuddy@latest mcp
 ```
 
-**3. Agent Not Responding in Korean**
-- Verify `[OpenCode Override]` includes Korean language setting
-- Check agent prompt includes language instruction
+**3. Agent Not Responding in Configured Language**
+- Verify `codingbuddy.config.json` has the correct `language` setting
+- Call `parse_mode` to receive dynamic `languageInstruction`
+- Ensure agent prompts do NOT hardcode a language — use `languageInstruction` from `parse_mode`
+
+**4. Project Config Not Detected**
+```bash
+# CODINGBUDDY_PROJECT_ROOT가 MCP env에 설정되어 있는지 확인
+# 이 환경변수 없이는 codingbuddy.config.json을 찾지 못합니다
+# .opencode.json 또는 crush.json의 mcp 섹션에 추가:
+"env": {
+  "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project"
+}
+```
 
 ### Migration from OpenCode to Crush
 
@@ -452,6 +541,21 @@ npx codingbuddy@latest mcp
 3. **Install Crush**: `brew install charmbracelet/tap/crush`
 4. **Migrate sessions**: Export/import session data
 
+## Verification Status
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Agent configuration (plan/act/eval-mode) | ✅ Verified | Agent JSON files exist at expected paths |
+| MCP server connection | ✅ Verified | `npx codingbuddy@latest mcp` works |
+| `parse_mode` with dynamic language | ✅ Verified | Returns `languageInstruction` field |
+| `update_context` persistence | ✅ Verified | Writes to `docs/codingbuddy/context.md` |
+| `{file:path}` syntax in prompts | ⚠️ Unverified | Not tested in live OpenCode/Crush environment |
+| Custom Commands (`~/.config/opencode/commands/`) | ⚠️ Unverified | Command syntax may differ in Crush |
+| AUTO mode single-agent execution | ⚠️ Unverified | Requires manual agent switching for permissions |
+| Crush `skills_paths` configuration | ⚠️ Unverified | Based on Crush documentation, not tested |
+| LSP integration | ⚠️ Unverified | Configuration format based on Crush docs |
+| Multi-model support | ⚠️ Unverified | Configuration format based on Crush docs |
+
 ## Maintenance
 
 ### Updating Rules
@@ -472,20 +576,112 @@ npx codingbuddy@latest mcp
 
 ## Advanced Usage
 
-### Parallel Agent Workflows
+### Specialist Agents Execution
 
-```bash
-# Terminal 1: Planning
-opencode --agent plan-mode
-Create a plan for me
+OpenCode/Crush does not have a `Task` tool for spawning background subagents like Claude Code. When `parse_mode` returns `parallelAgentsRecommendation`, execute specialists **sequentially** using the `/agent <name>` command.
 
-# Terminal 2: Implementation  
-opencode --agent act-mode
-ACT
+#### Auto-Detection
 
-# Terminal 3: Review
-opencode --agent eval-mode
-EVAL
+The MCP server automatically detects OpenCode/Crush as the client and returns a sequential execution hint in `parallelAgentsRecommendation.hint`. No manual configuration is needed.
+
+#### Sequential Workflow
+
+```
+parse_mode returns parallelAgentsRecommendation
+  ↓
+For each recommended specialist (sequentially):
+  /agent <specialist-name>
+  Perform specialist analysis
+  Record findings
+  ↓
+/agent <current-mode-agent>  (e.g., /agent eval-mode — return to mode agent)
+Consolidate all findings
+```
+
+#### Example (EVAL mode)
+
+```
+parse_mode({ prompt: "EVAL review auth implementation" })
+→ parallelAgentsRecommendation:
+    specialists: ["security-specialist", "accessibility-specialist", "performance-specialist"]
+
+Sequential analysis:
+  1. /agent security     → security-specialist: 🔒 Analyze from security perspective, record findings
+  2. /agent a11y         → accessibility-specialist: ♿ Analyze from accessibility perspective, record findings
+  3. /agent performance  → performance-specialist: ⚡ Analyze from performance perspective, record findings
+  4. /agent eval-mode    → Return to EVAL mode
+
+Present: Consolidated findings from all 3 specialists
+```
+
+#### Consuming dispatchReady from parse_mode
+
+When `parse_mode` returns `dispatchReady`, the specialist system prompts are pre-built. In OpenCode, use the `dispatchParams.prompt` field as analysis context (ignore `subagent_type` — it is Claude Code specific):
+
+```
+parse_mode returns dispatchReady
+  ↓
+dispatchReady.primaryAgent
+  → Use as the main analysis context
+  ↓
+dispatchReady.parallelAgents[] (if present)
+  → For each: the dispatchParams.prompt field contains the specialist's system prompt.
+    Switch via /agent, apply the prompt as analysis context, record findings
+  ↓
+Consolidate all findings
+```
+
+#### Specialist Agent Mapping
+
+| parallelAgentsRecommendation | OpenCode Agent | Icon |
+|------------------------------|----------------|------|
+| security-specialist | `security` | 🔒 |
+| accessibility-specialist | `a11y` | ♿ |
+| performance-specialist | `performance` | ⚡ |
+| architecture-specialist | `architect` | 🏛️ |
+| test-strategy-specialist | `tester` | 🧪 |
+| code-quality-specialist | N/A (inline) | 📏 |
+| event-architecture-specialist | N/A (inline) | 📨 |
+| integration-specialist | N/A (inline) | 🔗 |
+| observability-specialist | N/A (inline) | 📊 |
+| migration-specialist | N/A (inline) | 🔄 |
+| documentation-specialist | N/A (inline) | 📚 |
+| seo-specialist | N/A (inline) | 🔍 |
+| i18n-specialist | N/A (inline) | 🌐 |
+
+> **Note:** Specialists without a dedicated OpenCode agent (e.g., `code-quality-specialist`) should be analyzed inline within the current agent context using the specialist's system prompt from `prepare_parallel_agents`.
+>
+> **Fallback:** If `dispatchReady` is not present in the `parse_mode` response, call `prepare_parallel_agents` MCP tool to retrieve specialist system prompts.
+
+#### Visibility Pattern
+
+When executing sequential specialists, display clear status messages:
+
+**Start:**
+```
+🔄 Executing N specialist analyses sequentially...
+   → 🔒 security
+   → ♿ a11y
+   → ⚡ performance
+```
+
+**During:**
+```
+🔍 Analyzing from 🔒 security perspective... (1/3)
+```
+
+**Completion:**
+```
+📊 Specialist Analysis Complete:
+
+🔒 Security:
+   [findings summary]
+
+♿ Accessibility:
+   [findings summary]
+
+⚡ Performance:
+   [findings summary]
 ```
 
 ### Custom Agent Creation
@@ -559,7 +755,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
 | Korean | `자동` |
 | Japanese | `自動` |
 | Chinese | `自动` |
-| Spanish | `AUTOMATICO` |
+| Spanish | `AUTOMÁTICO` |
 
 ### Example Usage
 
@@ -580,21 +776,29 @@ AUTO Build a new user authentication feature
 
 ### OpenCode Agent Integration
 
-AUTO mode automatically switches between agents:
+AUTO mode describes an autonomous PLAN→ACT→EVAL cycle. However, agent switching behavior differs by platform:
+
+**⚠️ Limitation:** OpenCode/Crush does not support automatic agent switching. The `/agent <name>` command requires manual user input. Therefore, AUTO mode in OpenCode works in one of two ways:
 
+**1. Single-Agent AUTO (Recommended):** Stay in the `plan-mode` agent and prefix your message with `AUTO`. The AI handles all phases within a single agent context, using `parse_mode` for mode-specific rules at each phase.
+
+```
+/agent plan-mode
+AUTO Build a new user authentication feature
+→ AI internally cycles: PLAN → ACT → EVAL using parse_mode
+→ Note: File edits require the user to approve permission prompts
 ```
-AUTO detected
-    ↓
-plan-mode agent (PLAN phase)
-    ↓
-act-mode agent (ACT phase)
-    ↓
-eval-mode agent (EVAL phase)
-    ↓
-[Check quality criteria]
-    ↓
-Loop or Exit
+
+**2. Manual Agent Switching:** The user manually switches agents between phases:
+
 ```
+/agent plan-mode → AUTO Build auth feature (PLAN phase starts)
+/agent act-mode  → Continue (ACT phase — full edit/bash permissions)
+/agent eval-mode → Continue (EVAL phase — read-only evaluation)
+→ Repeat if quality criteria not met
+```
+
+**Recommended approach:** Use Single-Agent AUTO for simplicity. For strict permission control, use Manual Agent Switching.
 
 ### Configuration