add custom rules system and multi-language keyword support

[JeremyDev87]

add custom rules system and multi-language keyword support

📋 Summary

This PR adds two major features:

1. Custom Rules System: Enables users to add custom rules, agents, and skills via .codingbuddy/ folder that codingbuddy auto-discovers and merges with built-in rules
2. Multi-language Keyword Support: Adds support for PLAN/ACT/EVAL keywords in Korean, Japanese, Chinese, and Spanish, with mandatory mode detection rules across all AI adapters

🎯 Reason for Change

Custom Rules System

• Problem: Users need to customize rules, agents, and skills for their specific projects, but currently can only use built-in ones
• Solution: Allow users to create .codingbuddy/ folder structure with custom content that is automatically discovered and merged with defaults

Multi-language Keyword Support

• Problem: Non-English speaking developers had difficulty using PLAN/ACT/EVAL keywords
• Solution: Add keyword support for 4 languages (Korean, Japanese, Chinese, Spanish) and enforce mandatory mode detection across all adapters

🔧 Key Changes

1. Custom Rules System Implementation

CustomService (apps/mcp-server/src/custom/)

• CustomService: Discovers and parses .codingbuddy/ folder contents
• Features:
  • Auto-discovery of .codingbuddy/ folder in project root
  • Support for three subdirectories: rules/, agents/, skills/
  • Parsing and validation of custom files
  • Agent schema validation using Zod
• Files:
  • custom.service.ts - Core service implementation
  • custom.service.spec.ts - Comprehensive test coverage (+150 lines)
  • custom.types.ts - Type definitions
  • custom.module.ts - NestJS module

RulesService Integration

• Enhanced searchRules(): Now searches both custom and default rules
• Custom rules appear first in search results
• Added source field to SearchResult to distinguish custom vs default
• Enhanced getAgent(): Returns agent with source: 'default' field
• Files: apps/mcp-server/src/rules/rules.service.ts

Type System

• CustomFile: Base interface for all custom files
• CustomRule: Custom rule file type
• CustomAgent: Custom agent file type with parsed schema
• CustomSkill: Custom skill file type
• CustomAgentSchema: Validated agent schema compatible with AgentProfile
• Files: apps/mcp-server/src/custom/custom.types.ts

2. Multi-language Keyword Support

Keyword Types (apps/mcp-server/src/keyword/keyword.types.ts)

• LOCALIZED_KEYWORD_MAP: Maps localized keywords to English modes
  • Korean: 계획(PLAN), 실행(ACT), 평가(EVAL)
  • Japanese: 計画(PLAN), 実行(ACT), 評価(EVAL)
  • Chinese: 计划(PLAN), 执行(ACT), 评估(EVAL)
  • Spanish: PLANIFICAR(PLAN), ACTUAR(ACT), EVALUAR(EVAL)
• KOREAN_KEYWORD_MAP: Deprecated, use LOCALIZED_KEYWORD_MAP instead

Keyword Service (apps/mcp-server/src/keyword/keyword.service.ts)

• Enhanced parsing logic: Recognizes both English and localized keywords
• Case-insensitive matching: Spanish keywords work in any case
• Multi-keyword detection: Warns when multiple keywords are found
• Empty prompt detection: Warns when no content follows keyword

Adapter Rule Files Updated

• Updated files:
  • .antigravity/rules/instructions.md
  • .claude/rules/custom-instructions.md
  • .codex/rules/system-prompt.md
  • .cursor/rules/imports.mdc
  • .kiro/rules/guidelines.md
  • .q/rules/customizations.md
• Added content:
  • "🔴 MANDATORY: Keyword Mode Detection" section
  • CODINGBUDDY_CRITICAL_RULE block
  • Red Flags table
  • Multi-language keyword examples

MCP Service Updates

• parse_mode tool description: Enhanced with MANDATORY enforcement rules
• Files: apps/mcp-server/src/mcp/mcp.service.ts

3. Comprehensive Test Coverage

Custom Service Tests

• Custom rules discovery and parsing
• Custom agents validation
• Custom skills discovery
• Error handling for invalid files
• Files: apps/mcp-server/src/custom/custom.service.spec.ts (+150 lines)

Keyword Service Tests

• Multi-language keyword parsing (4 languages × 3 modes)
• Multi-keyword detection tests
• Empty prompt detection tests
• Files: apps/mcp-server/src/keyword/keyword.service.spec.ts (+210 lines)

Rules Service Tests

• Custom rules integration tests
• Search results ordering (custom first)
• Source field validation
• Files: apps/mcp-server/src/rules/rules.service.spec.ts (+154 lines)

MCP Service Tests

• parse_mode tool description validation
• Multi-language keyword examples in tool description
• Files: apps/mcp-server/src/mcp/mcp.service.spec.ts (+169 lines)

4. Documentation

Implementation Plan

• File: docs/plans/2026-01-01-custom-rules.md (+693 lines)
• Comprehensive implementation plan with task breakdown
• Architecture decisions and design rationale
• Testing strategy

⚠️ Breaking Changes

None

✅ Testing

Custom Rules System

1. Create Custom Rules

# Create .codingbuddy folder structure
mkdir -p .codingbuddy/rules
mkdir -p .codingbuddy/agents
mkdir -p .codingbuddy/skills

# Add custom rule
echo "# My Custom Rule" > .codingbuddy/rules/my-rule.md

# Add custom agent
cat > .codingbuddy/agents/my-agent.json <<EOF
{
  "name": "My Custom Agent",
  "role": "Custom role",
  "expertise": ["custom"]
}
EOF

2. Verify Custom Rules Discovery

const customService = new CustomService();
const customRules = await customService.listCustomRules(process.cwd());
// Should return custom rules from .codingbuddy/rules/

3. Verify Search Results

const results = await rulesService.searchRules('custom');
// Custom rules should appear first in results
// Each result should have source: 'custom' or 'default'

Multi-language Keyword Support

1. Test Korean Keywords

parseMode('계획 인증 기능 설계') // => { mode: 'PLAN', originalPrompt: '인증 기능 설계' }
parseMode('실행 로그인 API 구현') // => { mode: 'ACT', originalPrompt: '로그인 API 구현' }
parseMode('평가 보안 검토') // => { mode: 'EVAL', originalPrompt: '보안 검토' }

2. Test Japanese Keywords

parseMode('計画 認証機能を設計') // => { mode: 'PLAN', originalPrompt: '認証機能を設計' }
parseMode('実行 ログインAPIを実装') // => { mode: 'ACT', originalPrompt: 'ログインAPIを実装' }

3. Test Chinese Keywords

parseMode('计划 设计认证功能') // => { mode: 'PLAN', originalPrompt: '设计认证功能' }
parseMode('执行 实现登录API') // => { mode: 'ACT', originalPrompt: '实现登录API' }

4. Test Spanish Keywords

parseMode('PLANIFICAR diseño de autenticación') // => { mode: 'PLAN' }
parseMode('planificar diseño de autenticación') // => { mode: 'PLAN' } (case-insensitive)
parseMode('ACTUAR implementar API') // => { mode: 'ACT' }

🔍 Review Checklist

Custom Rules System

• Verify CustomService correctly discovers .codingbuddy/ folder
• Verify custom rules are parsed correctly
• Verify custom agents are validated against schema
• Verify custom rules appear first in search results
• Verify source field is correctly set for custom and default rules
• Verify error handling for invalid custom files
• Verify test coverage is comprehensive

Multi-language Keyword Support

• Verify all adapter rule files have MANDATORY sections
• Verify multi-language keyword parsing works for all languages
• Verify multi-keyword detection and warnings work correctly
• Verify empty prompt detection and warnings work correctly
• Verify parse_mode tool description includes MANDATORY rules
• Verify existing English keyword parsing still works
• Verify test coverage is sufficient

💡 Usage Examples

Custom Rules System

Create Custom Rule

# Create .codingbuddy/rules/my-custom-rule.md
cat > .codingbuddy/rules/my-custom-rule.md <<EOF
# My Custom Rule

This is a custom rule for my project.
EOF

Create Custom Agent

# Create .codingbuddy/agents/my-agent.json
cat > .codingbuddy/agents/my-agent.json <<EOF
{
  "name": "My Custom Agent",
  "role": "Custom role description",
  "expertise": ["custom", "specialized"],
  "instructions": "Custom instructions"
}
EOF

Use Custom Rules

// Custom rules are automatically discovered and merged
const results = await rulesService.searchRules('custom');
// Returns both custom and default rules, custom first

Multi-language Keywords

Korean User

User: 계획 인증 기능 설계
AI: [call parse_mode] → Switch to PLAN mode → Execute planning checklist

Japanese User

User: 実行 ログインAPIを実装
AI: [call parse_mode] → Switch to ACT mode → Execute implementation checklist

Chinese User

User: 评估 安全审查
AI: [call parse_mode] → Switch to EVAL mode → Execute evaluation checklist

Spanish User

User: PLANIFICAR diseño de autenticación
AI: [call parse_mode] → Switch to PLAN mode → Execute planning checklist

🎯 Expected Impact

Custom Rules System

1. Flexibility: Users can customize rules, agents, and skills for their projects
2. Extensibility: Easy to add project-specific workflows and best practices
3. Maintainability: Custom rules are separate from built-in rules, easier to manage
4. Backward Compatibility: Existing projects continue to work without changes

Multi-language Keyword Support

1. Accessibility: Non-English speaking developers can use mode keywords in their language
2. Consistency: Same mode detection rules enforced across all adapters
3. Quality: Reduced cases of missing critical checklists due to mandatory mode detection
4. User Experience: Users can naturally use mode keywords in their native language