codingbuddy-rules 4.4.0 → 5.0.0

package/.ai-rules/agents/software-engineer.json

@@ -1,6 +1,7 @@
 {
   "name": "Software Engineer",
   "description": "General-purpose implementation engineer — any language, any domain, TDD-first",
+  "color": "#1ABC9C",
   "role": {
     "title": "Senior Software Engineer",
     "type": "primary",

package/.ai-rules/agents/solution-architect.json

@@ -1,6 +1,7 @@
 {
   "name": "Solution Architect",
   "description": "High-level system design and architecture planning specialist",
+  "color": "#4A90D9",
   "role": {
     "title": "Solution Architect",
     "type": "primary",
@@ -39,22 +40,22 @@
   "activation": {
     "trigger": "When high-level architecture design or system design is needed",
     "explicit_patterns": [
-      "아키텍처 설계",
-      "시스템 설계",
       "architecture design",
       "system design",
-      "기술 선택",
+      "architecture design",
+      "system design",
       "technology selection",
-      "설계 검토",
+      "technology selection",
+      "design review",
       "design review",
-      "solution-architect로"
+      "as solution-architect"
     ],
     "intent_patterns": [
-      "아키텍처|architecture",
-      "시스템\\s*설계|system\\s*design",
-      "전체\\s*구조|overall\\s*structure",
-      "기술\\s*스택|tech\\s*stack",
-      "설계\\s*방향|design\\s*direction"
+      "architecture",
+      "system\\s*design",
+      "overall\\s*structure",
+      "tech\\s*stack",
+      "design\\s*direction"
     ],
     "mandatory_checklist": {
       "🔴 brainstorming_first": {

package/.ai-rules/agents/systems-developer.json

@@ -1,6 +1,7 @@
 {
   "name": "Systems Developer",
   "description": "Primary Agent for systems programming, low-level optimization, native code development, and performance-critical implementations",
+  "color": "#D35400",
   "role": {
     "title": "Systems Developer",
     "type": "primary",
@@ -32,14 +33,14 @@
   "activation": {
     "trigger": "When user requests Rust/C/C++ implementation, FFI bindings, memory management, embedded systems, WASM, or low-level performance optimization",
     "explicit_patterns": [
-      "systems-developer로",
-      "Rust로 구현",
-      "C++ 최적화",
-      "FFI 바인딩",
-      "메모리 관리",
-      "임베디드 개발",
-      "WASM 구현",
-      "저수준 구현"
+      "as systems-developer",
+      "implement in Rust",
+      "C++ optimization",
+      "FFI binding",
+      "memory management",
+      "embedded development",
+      "WASM implementation",
+      "low-level implementation"
     ],
     "mandatory_checklist": {
       "🔴 memory_safety": {

package/.ai-rules/agents/technical-planner.json

@@ -1,6 +1,7 @@
 {
   "name": "Technical Planner",
   "description": "Low-level implementation planning with TDD and bite-sized tasks",
+  "color": "#7B68EE",
   "role": {
     "title": "Technical Planner",
     "type": "primary",
@@ -49,22 +50,22 @@
   "activation": {
     "trigger": "When detailed implementation planning with TDD is needed",
     "explicit_patterns": [
-      "구현 계획",
       "implementation plan",
-      "태스크 분해",
+      "implementation plan",
+      "task breakdown",
       "task breakdown",
-      "작업 계획",
       "work plan",
-      "TDD 계획",
+      "work plan",
+      "TDD plan",
       "TDD plan",
-      "technical-planner로"
+      "as technical-planner"
     ],
     "intent_patterns": [
-      "구현\\s*계획|implementation\\s*plan",
-      "작업\\s*분해|task\\s*breakdown",
-      "단계별|step.?by.?step",
-      "TDD|테스트\\s*먼저|test.?first",
-      "bite.?sized|작은\\s*단위"
+      "implementation\\s*plan",
+      "task\\s*breakdown",
+      "step.?by.?step",
+      "TDD|test.?first",
+      "bite.?sized"
     ],
     "mandatory_checklist": {
       "🔴 writing_plans_skill": {

package/.ai-rules/agents/test-engineer.json

@@ -1,6 +1,7 @@
 {
   "name": "Test Engineer",
   "description": "Primary Agent for TDD cycle execution, test writing, and coverage improvement across all test types",
+  "color": "#F39C12",
   "role": {
     "title": "Test Engineer",
     "type": "primary",
@@ -28,13 +29,13 @@
   "activation": {
     "trigger": "When user requests test writing, TDD implementation, coverage improvement, or test strategy",
     "explicit_patterns": [
-      "테스트 코드 작성",
-      "단위 테스트",
+      "write test code",
       "unit test",
-      "TDD로",
-      "test-engineer로",
-      "e2e 테스트",
-      "커버리지 개선",
+      "unit test",
+      "with TDD",
+      "as test-engineer",
+      "e2e test",
+      "coverage improvement",
       "coverage improvement"
     ],
     "mandatory_checklist": {

package/.ai-rules/agents/test-strategy-specialist.json

@@ -1,6 +1,7 @@
 {
   "name": "Test Strategy Specialist",
   "description": "Test strategy expert for Planning, Implementation, and Evaluation modes - unified specialist for TDD vs Test-After decisions, test coverage planning, and test quality assessment",
+  "color": "#F1C40F",
   "role": {
     "title": "Test Strategy Engineer",
     "expertise": [

package/.ai-rules/agents/tooling-engineer.json

@@ -1,6 +1,7 @@
 {
   "name": "Tooling Engineer",
   "description": "Project configuration, build tools, and development environment specialist",
+  "color": "#95A5A6",
   "role": {
     "title": "Tooling Engineer",
     "type": "primary",
@@ -27,7 +28,7 @@
   "activation": {
     "trigger": "When user works with config files, build tools, or development environment setup",
     "explicit_patterns": [
-      "설정 파일",
+      "config file",
       "config file",
       "tsconfig",
       "eslint",
@@ -36,9 +37,9 @@
       "vite.config",
       "next.config",
       "webpack",
-      "빌드 설정",
       "build config",
-      "tooling-engineer로"
+      "build config",
+      "as tooling-engineer"
     ],
     "mandatory_checklist": {
       "schema_compliance": {

package/.ai-rules/agents/ui-ux-designer.json

@@ -1,6 +1,7 @@
 {
   "name": "UI/UX Designer",
   "description": "UI/UX design specialist based on universal design principles and UX best practices - focuses on aesthetics, usability, and user experience rather than specific design system implementations",
+  "color": "#E91E63",
   "role": {
     "title": "UI/UX Design Specialist",
     "expertise": [

package/.ai-rules/keyword-modes.json

@@ -2,7 +2,7 @@
   "modes": {
     "PLAN": {
       "description": "Task planning and design phase",
-      "instructions": "설계 우선 접근. TDD 관점에서 테스트 케이스 먼저 정의. 구현 전 아키텍처 검토. 📝 완료 후 docs/codingbuddy/plan/ 에 PLAN 문서 작성 권장 (./docs/codingbuddy/scripts/new-doc.sh plan <slug>).",
+      "instructions": "Design-first approach. Define test cases first from a TDD perspective. Review architecture before implementation. 📝 After completion, creating a PLAN document in docs/codingbuddy/plan/ is recommended (./docs/codingbuddy/scripts/new-doc.sh plan <slug>).",
       "rules": ["rules/core.md", "rules/augmented-coding.md"],
       "agent": "plan-mode",
       "delegates_to": "frontend-developer",
@@ -17,7 +17,7 @@
     },
     "ACT": {
       "description": "Actual task execution phase",
-      "instructions": "Red-Green-Refactor 사이클 준수. 최소 구현 후 점진적 개선. 품질 기준 충족 확인. 📝 완료 후 docs/codingbuddy/act/ 에 ACT 문서 작성 권장 (./docs/codingbuddy/scripts/new-doc.sh act <slug>).",
+      "instructions": "Follow the Red-Green-Refactor cycle. Implement minimally first, then improve incrementally. Verify quality standards are met. 📝 After completion, creating an ACT document in docs/codingbuddy/act/ is recommended (./docs/codingbuddy/scripts/new-doc.sh act <slug>).",
       "rules": ["rules/core.md", "rules/project.md", "rules/augmented-coding.md"],
       "agent": "act-mode",
       "delegates_to": "frontend-developer",
@@ -30,7 +30,7 @@
     },
     "EVAL": {
       "description": "Result review and assessment phase",
-      "instructions": "코드 품질 검토. SOLID 원칙 준수 확인. 테스트 커버리지 점검. 개선점 제안. 📝 완료 후 docs/codingbuddy/eval/ 에 EVAL 문서 작성 권장 (./docs/codingbuddy/scripts/new-doc.sh eval <slug>).",
+      "instructions": "Review code quality. Verify SOLID principles compliance. Check test coverage. Suggest improvements. 📝 After completion, creating an EVAL document in docs/codingbuddy/eval/ is recommended (./docs/codingbuddy/scripts/new-doc.sh eval <slug>).",
       "rules": ["rules/core.md", "rules/augmented-coding.md"],
       "agent": "eval-mode",
       "delegates_to": "code-reviewer",
@@ -47,7 +47,7 @@
     },
     "AUTO": {
       "description": "Autonomous execution mode",
-      "instructions": "PLAN → ACT → EVAL 사이클 자동 실행. Critical/High 이슈가 0이 될 때까지 반복. (세션 문서는 각 PLAN/ACT/EVAL 단계에서 작성됨)",
+      "instructions": "Automatically execute the PLAN → ACT → EVAL cycle. Repeat until Critical/High issues reach 0. (Session documents are created at each PLAN/ACT/EVAL phase)",
       "rules": ["rules/core.md", "rules/project.md", "rules/augmented-coding.md"],
       "agent": "auto-mode",
       "delegates_to": "frontend-developer",

package/.ai-rules/rules/clarification-guide.md

@@ -98,32 +98,32 @@ Use these categories as reference when generating questions. Adapt to specific c
 ```markdown
 ## Clarification Phase
 
-### 질문 1/3
+### Question 1/3
 
-**[카테고리]에 대한 확인이 필요합니다:**
+**Clarification needed for [Category]:**
 
-[컨텍스트에 맞게 조정된 질문]
+[Question adapted to context]
 
-- **A)** [선택지 1]
-- **B)** [선택지 2]
-- **C)** [선택지 3]
+- **A)** [Option 1]
+- **B)** [Option 2]
+- **C)** [Option 3]
 
-> 답변을 선택해주세요 (A/B/C) 또는 다른 의견이 있으시면 말씀해주세요.
+> Please select your answer (A/B/C) or share your own input.
 ```
 
 ### After All Questions
 
 ```markdown
-## 수집된 정보 요약
+## Collected Information Summary
 
-| 항목 | 결정 사항 |
+| Item | Decision |
 |------|----------|
-| 범위 | [사용자 선택] |
-| 우선순위 | [사용자 선택] |
-| 제약조건 | [사용자 선택] |
+| Scope | [User's selection] |
+| Priority | [User's selection] |
+| Constraints | [User's selection] |
 | ... | ... |
 
-이 내용이 맞나요? 확인해주시면 PLAN 수립을 시작하겠습니다.
+Does this look correct? Once confirmed, we will proceed with creating the PLAN.
 ```
 
 ---
@@ -132,7 +132,7 @@ Use these categories as reference when generating questions. Adapt to specific c
 
 | Situation | Response |
 |-----------|----------|
-| User answers "I'm not sure" / "잘 모르겠어요" | Present default recommendation with rationale, ask for confirmation |
+| User answers "I'm not sure" | Present default recommendation with rationale, ask for confirmation |
 | User wants to skip a question | Note that AI will use best judgment, continue to next question |
 | User provides unexpected answer | Acknowledge the input, incorporate into understanding, continue |
 | User asks to skip all questions | Proceed to PLAN creation, note assumptions made |

package/.ai-rules/rules/core.md

@@ -46,6 +46,39 @@ PLAN → (user: ACT) → ACT → PLAN → (user: EVAL) → EVAL → Improved PLA
 
 ---
 
+### Output Language
+
+**Rule:** The `language` setting in `codingbuddy.config.json` controls **communication language only** (conversation, explanations, questions). All generated **artifacts** must always be written in **English**, regardless of the `language` setting.
+
+| Category | Language | Examples |
+|----------|----------|----------|
+| **Communication** | `codingbuddy.config.json` `language` setting | Conversation, explanations, status updates, questions |
+| **Artifacts** | Always English | Code, comments, variable names, documentation, commit messages, PR titles/descriptions, branch names, TODO items, error messages in code, log messages, JSDoc/TSDoc, type names |
+
+**Why:**
+- Code and documentation in English ensures global readability and collaboration
+- Mixed-language codebases create maintenance burden and hinder onboarding
+- Commit history and PR descriptions must be searchable in a common language
+
+**Examples:**
+
+```
+# Communication (follows language setting, e.g., "ko")
+"This function handles user authentication. Let's move on to the next step."
+
+# Artifacts (always English)
+/** Validates user authentication token and returns session data. */
+function validateAuthToken(token: string): SessionData { ... }
+
+# Commit message (always English)
+feat(auth): add token validation with session management
+
+# Code comments (always English)
+// Check token expiration before proceeding
+```
+
+---
+
 ### Plan Mode
 
 **Important:**
@@ -61,6 +94,18 @@ PLAN → (user: ACT) → ACT → PLAN → (user: EVAL) → EVAL → Improved PLA
 **Purpose:**
 Create actionable implementation plans following TDD and augmented coding principles
 
+### API Assumption Verification (PLAN mode)
+
+When a plan references external API fields, schemas, or behaviors:
+1. **Cite source**: Include the official documentation URL for every API assumption
+2. **Mark unverified**: Tag any assumption without a verified source as `[UNVERIFIED]`
+3. **Verify before ACT**: All `[UNVERIFIED]` items must be verified (via WebFetch/WebSearch) before transitioning to ACT mode
+4. **No fabricated schemas**: Never assume API input/output fields exist without documentation proof
+
+Example:
+- ✅ "Hook stdin includes `tool_name` field ([source](https://code.claude.com/docs/en/hooks))"
+- ❌ "Hook stdin includes `session_cost` field" (no source → will cause implementation failure)
+
 ---
 
 ### Structured Reasoning Process (SRP)
@@ -546,7 +591,8 @@ To preserve this implementation session for future reference:
 - All implementations must follow the Primary Developer Agent's code quality checklist
 - Respond in the language specified in the agent's communication.language setting
 - Execute one step at a time, verify tests after each step
-- Stop and return to PLAN if blockers encountered
+- On recoverable errors (file not found, command failure, path issues), try alternatives immediately
+- Only return to PLAN on unrecoverable blockers (missing dependencies, architectural conflicts)
 
 **Verification:**
 - Agent name should appear as `## Agent : [Primary Developer Agent Name]` in response
@@ -563,6 +609,48 @@ To preserve this implementation session for future reference:
 
 ---
 
+### Error Recovery (ACT mode)
+
+- On recoverable errors (file not found, command failure, path issues), try alternatives immediately
+- Do not wait for user confirmation on recoverable errors — recover immediately
+- Only report to user on unrecoverable errors (auth failure, critical data loss risk)
+- Never break the workflow on error — try alternatives and continue
+
+### Path Safety (monorepo)
+
+- Always verify current directory (pwd) or use absolute paths before git add/commit
+- In monorepo subdirectories, use git -C "$REPO_ROOT" flag for git commands
+- After using cd, ensure relative paths are not double-applied in subsequent commands
+
+### Working Directory Safety
+
+After any operation that changes directory (cd, clone, worktree operations):
+
+- Verify current working directory is the project root before running project-scoped commands
+- Use absolute paths for critical operations (version control, CI tools, package managers)
+- If working directory drifted, return immediately: `cd /path/to/project`
+- Never assume the working directory is correct after directory-changing operations
+
+### Skill Invocation Safety
+
+Before invoking any skill via a tool:
+
+- Check the skill file frontmatter for `disable-model-invocation: true`
+- Skills with this flag cannot be invoked via tool-based invocation
+- Instead, read the skill content and execute the workflow steps directly
+- This applies to all AI assistants, not just specific tool implementations
+
+### Issue Deduplication
+
+Before creating any issue in the project tracker:
+
+- Search for existing similar issues using relevant keywords (e.g., `gh issue list --search "<keywords>"`)
+- If a duplicate or closely related issue is found, update it instead of creating a new one
+- Track all issues created in the current session to prevent same-session duplicates
+- Include cross-references when creating related but distinct issues
+
+---
+
 ### Eval Mode
 
 **Important:**
@@ -867,6 +955,7 @@ To preserve this evaluation session for future reference:
 - User initiates with `AUTO` keyword and the system handles the entire workflow
 - Continues iterating until quality targets are achieved or maximum iterations reached
 - Best for tasks where iterative refinement is expected
+- For parallel task execution within AUTO mode, see [parallel-execution.md](parallel-execution.md)
 
 **Trigger:**
 - Type `AUTO` to start autonomous execution

package/.ai-rules/rules/parallel-execution.md

@@ -0,0 +1,217 @@
+# Parallel Execution Guidelines
+
+Rules for running multiple tasks concurrently using sub-agents, workers, or parallel processes. These rules are tool-agnostic and apply to any AI assistant orchestrating parallel work.
+
+---
+
+## The Iron Rule
+
+```
+ISSUES MODIFYING THE SAME FILES MUST NOT RUN IN THE SAME PARALLEL WAVE
+```
+
+No exceptions. If two tasks touch the same file, they run sequentially in different waves. Violating this rule causes merge conflicts, lost work, and corrupted state.
+
+**Why:** Parallel workers operate on isolated copies (e.g., git worktrees, branches). When two workers modify the same file simultaneously, their changes conflict on merge. One worker's changes will be lost or require manual resolution.
+
+---
+
+## Wave Planning
+
+Parallel tasks are organized into **waves** — groups of tasks that execute concurrently. Tasks within a wave must be independent; tasks across waves may depend on each other.
+
+### Step 1: File Overlap Matrix
+
+Before assigning tasks to waves, build a file overlap matrix. This is **mandatory**, not optional.
+
+**Process:**
+
+1. For each task, list all files that will be created or modified
+2. Compare every pair of tasks for file overlap
+3. Any overlap means those tasks **cannot** be in the same wave
+
+**Example Matrix:**
+
+```
+         Task A    Task B    Task C    Task D
+Task A     -       overlap     -         -
+Task B   overlap     -         -       overlap
+Task C     -         -         -         -
+Task D     -       overlap     -         -
+```
+
+**Result:** A and B cannot be in the same wave. B and D cannot be in the same wave. C is independent and can go in any wave.
+
+### Step 2: Dependency Analysis
+
+Beyond file overlap, check for logical dependencies:
+
+- Does Task B require output from Task A? (sequential dependency)
+- Does Task C need a type/interface that Task A creates? (creation dependency)
+- Does Task D modify a function that Task B also calls? (behavioral dependency)
+
+Tasks with dependencies must run in later waves than their prerequisites.
+
+### Step 3: Wave Assignment
+
+Use a greedy coloring algorithm:
+
+```
+1. Sort tasks by number of conflicts (most conflicts first)
+2. For each task:
+   a. Find the earliest wave where no conflict exists
+   b. Assign the task to that wave
+3. Result: minimum number of waves
+```
+
+**Example Result:**
+
+```
+Wave 1: Task A, Task C, Task D  (no mutual conflicts)
+Wave 2: Task B                  (conflicts with A and D)
+```
+
+### Step 4: Wave Ordering
+
+Order waves considering:
+
+- **Foundation first:** Tasks that create shared types, interfaces, or utilities go in Wave 1
+- **Consumers later:** Tasks that depend on Wave 1 outputs go in Wave 2+
+- **Independent tasks:** Can go in any wave; prefer earlier waves to maximize parallelism
+
+---
+
+## Sub-Agent Parallelization Strategy
+
+When dispatching parallel sub-agents (workers), follow these guidelines:
+
+### Worker Isolation
+
+Each worker must operate in an isolated environment:
+
+- **Separate working copy:** Each worker gets its own git worktree, branch, or directory
+- **No shared mutable state:** Workers must not write to the same files, databases, or caches simultaneously
+- **Independent commits:** Each worker commits to its own branch
+
+### Worker Prompt Design
+
+Each worker prompt must include:
+
+1. **Clear scope:** Exactly which files to create or modify
+2. **Boundary constraints:** Files the worker must NOT touch
+3. **Context:** Shared types, interfaces, or utilities the worker may read but not modify
+4. **Success criteria:** How to verify the task is complete
+5. **Verification command:** A command to run before completing (e.g., tests, lint)
+
+### Merge Strategy
+
+After all workers in a wave complete:
+
+1. **Verify each worker's changes:** Run tests and lint on each branch independently
+2. **Merge sequentially:** Merge each worker's branch into the target branch one at a time
+3. **Run integration tests:** After all merges, verify the combined changes work together
+4. **Resolve conflicts immediately:** If a merge conflict occurs, investigate the root cause — it likely indicates a violation of the Iron Rule
+
+---
+
+## Continuous Execution Rule
+
+Workers MUST complete all assigned tasks in a single uninterrupted flow.
+Stopping between tasks to wait for user input is a protocol violation.
+
+- DO NOT stop between steps
+- Complete ALL tasks without waiting for user input
+- Only stop after writing RESULT.json
+- Auto-nudge from conductor is a fallback safety net, not the primary mechanism
+
+---
+
+## AUTO Mode Iteration Methodology
+
+When using AUTO mode with parallel execution:
+
+### Iteration Structure
+
+```
+Iteration 1:
+  PLAN  → Identify tasks, build file overlap matrix, assign waves
+  ACT   → Execute Wave 1 (parallel workers)
+        → Merge Wave 1 results
+        → Execute Wave 2 (parallel workers)
+        → Merge Wave 2 results
+        → ... repeat for all waves
+  EVAL  → Verify all tasks complete, run full test suite
+        → If Critical/High issues found → iterate
+
+Iteration 2 (if needed):
+  PLAN  → Address issues found in previous EVAL
+  ACT   → Fix issues (may or may not need parallel execution)
+  EVAL  → Re-verify
+```
+
+### Quality Gates Between Waves
+
+Before starting the next wave:
+
+- All workers in the current wave must have completed successfully
+- All changes from the current wave must be merged
+- Tests must pass after merging
+- No unresolved conflicts
+
+### Escape Conditions
+
+Stop iterating when:
+
+- All acceptance criteria are met
+- EVAL reports Critical = 0 AND High = 0
+- Maximum iterations reached (default: 3)
+
+---
+
+## Post-Execution Verification Checklist
+
+After all waves complete, verify:
+
+```
+- [ ] All tasks completed successfully
+- [ ] All branches merged without conflicts
+- [ ] Full test suite passes
+- [ ] No files were modified by multiple workers (Iron Rule verification)
+- [ ] Lint and format checks pass
+- [ ] Type checking passes
+- [ ] No unintended changes outside task scope
+```
+
+### Iron Rule Verification Command
+
+Run this after merging to confirm no file was modified by multiple workers:
+
+```bash
+# For git-based workflows: check if any file appears in multiple worker branches
+# Compare each worker's changed files against all other workers
+git diff --name-only main..worker-1 > /tmp/w1.txt
+git diff --name-only main..worker-2 > /tmp/w2.txt
+comm -12 <(sort /tmp/w1.txt) <(sort /tmp/w2.txt)
+# Output must be empty — any listed files indicate an Iron Rule violation
+```
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Prevention |
+|---------|------------|
+| Skipping file overlap matrix | **Always** build the matrix before assigning waves |
+| "It probably won't conflict" | Assume it will. Check explicitly. No exceptions |
+| Shared config files (package.json, tsconfig) | Only one worker per wave may modify shared config |
+| Generated files (lock files, build output) | Exclude from worker scope; regenerate after merge |
+| Test files that import from multiple modules | Treat test files as modifying the modules they test |
+| Workers exceeding their scope | Define explicit file boundaries in worker prompts |
+
+---
+
+## Reference
+
+- For detailed wave analysis algorithms, see the skill-specific documentation in your tool's configuration
+- For AUTO mode general workflow, see [core.md](core.md) — Auto Mode section
+- For TDD practices during parallel execution, see [augmented-coding.md](augmented-coding.md)