codingbuddy-rules 4.5.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/.ai-rules/adapters/aider.md +374 -0
  2. package/.ai-rules/adapters/antigravity.md +6 -6
  3. package/.ai-rules/adapters/claude-code.md +68 -4
  4. package/.ai-rules/adapters/codex.md +5 -5
  5. package/.ai-rules/adapters/cursor.md +2 -2
  6. package/.ai-rules/adapters/kiro.md +8 -8
  7. package/.ai-rules/adapters/opencode.md +7 -7
  8. package/.ai-rules/adapters/q.md +2 -2
  9. package/.ai-rules/adapters/windsurf.md +395 -0
  10. package/.ai-rules/agents/README.md +66 -16
  11. package/.ai-rules/agents/accessibility-specialist.json +8 -1
  12. package/.ai-rules/agents/act-mode.json +8 -1
  13. package/.ai-rules/agents/agent-architect.json +14 -7
  14. package/.ai-rules/agents/ai-ml-engineer.json +7 -0
  15. package/.ai-rules/agents/architecture-specialist.json +7 -0
  16. package/.ai-rules/agents/auto-mode.json +10 -2
  17. package/.ai-rules/agents/backend-developer.json +7 -0
  18. package/.ai-rules/agents/code-quality-specialist.json +7 -0
  19. package/.ai-rules/agents/code-reviewer.json +86 -64
  20. package/.ai-rules/agents/data-engineer.json +14 -7
  21. package/.ai-rules/agents/data-scientist.json +16 -9
  22. package/.ai-rules/agents/devops-engineer.json +7 -0
  23. package/.ai-rules/agents/documentation-specialist.json +7 -0
  24. package/.ai-rules/agents/eval-mode.json +30 -19
  25. package/.ai-rules/agents/event-architecture-specialist.json +7 -0
  26. package/.ai-rules/agents/frontend-developer.json +7 -0
  27. package/.ai-rules/agents/i18n-specialist.json +8 -1
  28. package/.ai-rules/agents/integration-specialist.json +7 -0
  29. package/.ai-rules/agents/migration-specialist.json +7 -0
  30. package/.ai-rules/agents/mobile-developer.json +8 -10
  31. package/.ai-rules/agents/observability-specialist.json +7 -0
  32. package/.ai-rules/agents/parallel-orchestrator.json +352 -0
  33. package/.ai-rules/agents/performance-specialist.json +7 -0
  34. package/.ai-rules/agents/plan-mode.json +9 -1
  35. package/.ai-rules/agents/plan-reviewer.json +211 -0
  36. package/.ai-rules/agents/platform-engineer.json +7 -0
  37. package/.ai-rules/agents/security-engineer.json +15 -8
  38. package/.ai-rules/agents/security-specialist.json +8 -1
  39. package/.ai-rules/agents/seo-specialist.json +7 -0
  40. package/.ai-rules/agents/software-engineer.json +7 -0
  41. package/.ai-rules/agents/solution-architect.json +17 -10
  42. package/.ai-rules/agents/systems-developer.json +15 -8
  43. package/.ai-rules/agents/technical-planner.json +17 -10
  44. package/.ai-rules/agents/test-engineer.json +13 -6
  45. package/.ai-rules/agents/test-strategy-specialist.json +7 -0
  46. package/.ai-rules/agents/tooling-engineer.json +10 -3
  47. package/.ai-rules/agents/ui-ux-designer.json +7 -0
  48. package/.ai-rules/keyword-modes.json +4 -4
  49. package/.ai-rules/rules/clarification-guide.md +14 -14
  50. package/.ai-rules/rules/core.md +73 -0
  51. package/.ai-rules/rules/parallel-execution.md +217 -0
  52. package/.ai-rules/schemas/agent.schema.json +38 -0
  53. package/.ai-rules/skills/README.md +29 -1
  54. package/.ai-rules/skills/agent-design/SKILL.md +5 -0
  55. package/.ai-rules/skills/agent-design/examples/agent-template.json +55 -0
  56. package/.ai-rules/skills/agent-design/references/expertise-guidelines.md +112 -0
  57. package/.ai-rules/skills/agent-discussion/SKILL.md +199 -0
  58. package/.ai-rules/skills/agent-discussion-panel/SKILL.md +448 -0
  59. package/.ai-rules/skills/api-design/SKILL.md +5 -0
  60. package/.ai-rules/skills/api-design/examples/error-response.json +159 -0
  61. package/.ai-rules/skills/api-design/examples/openapi-template.yaml +393 -0
  62. package/.ai-rules/skills/build-fix/SKILL.md +234 -0
  63. package/.ai-rules/skills/code-explanation/SKILL.md +4 -0
  64. package/.ai-rules/skills/context-management/SKILL.md +1 -0
  65. package/.ai-rules/skills/cost-budget/SKILL.md +348 -0
  66. package/.ai-rules/skills/cross-repo-issues/SKILL.md +257 -0
  67. package/.ai-rules/skills/database-migration/SKILL.md +1 -0
  68. package/.ai-rules/skills/deepsearch/SKILL.md +214 -0
  69. package/.ai-rules/skills/deployment-checklist/SKILL.md +1 -0
  70. package/.ai-rules/skills/error-analysis/SKILL.md +1 -0
  71. package/.ai-rules/skills/finishing-a-development-branch/SKILL.md +281 -0
  72. package/.ai-rules/skills/frontend-design/SKILL.md +5 -0
  73. package/.ai-rules/skills/frontend-design/examples/component-template.tsx +203 -0
  74. package/.ai-rules/skills/frontend-design/references/css-patterns.md +243 -0
  75. package/.ai-rules/skills/git-master/SKILL.md +358 -0
  76. package/.ai-rules/skills/incident-response/SKILL.md +1 -0
  77. package/.ai-rules/skills/legacy-modernization/SKILL.md +1 -0
  78. package/.ai-rules/skills/mcp-builder/SKILL.md +7 -0
  79. package/.ai-rules/skills/mcp-builder/examples/resource-example.ts +233 -0
  80. package/.ai-rules/skills/mcp-builder/examples/tool-example.ts +198 -0
  81. package/.ai-rules/skills/mcp-builder/references/protocol-spec.md +215 -0
  82. package/.ai-rules/skills/onboard/SKILL.md +150 -0
  83. package/.ai-rules/skills/performance-optimization/SKILL.md +3 -0
  84. package/.ai-rules/skills/plan-and-review/SKILL.md +115 -0
  85. package/.ai-rules/skills/plan-to-issues/SKILL.md +318 -0
  86. package/.ai-rules/skills/pr-all-in-one/SKILL.md +15 -13
  87. package/.ai-rules/skills/pr-all-in-one/configuration-guide.md +7 -7
  88. package/.ai-rules/skills/pr-all-in-one/pr-templates.md +10 -10
  89. package/.ai-rules/skills/pr-review/SKILL.md +4 -0
  90. package/.ai-rules/skills/receiving-code-review/SKILL.md +347 -0
  91. package/.ai-rules/skills/refactoring/SKILL.md +1 -0
  92. package/.ai-rules/skills/requesting-code-review/SKILL.md +348 -0
  93. package/.ai-rules/skills/retrospective/SKILL.md +192 -0
  94. package/.ai-rules/skills/rule-authoring/SKILL.md +5 -0
  95. package/.ai-rules/skills/rule-authoring/examples/rule-template.md +142 -0
  96. package/.ai-rules/skills/rule-authoring/examples/trigger-patterns.md +126 -0
  97. package/.ai-rules/skills/security-audit/SKILL.md +4 -0
  98. package/.ai-rules/skills/ship/SKILL.md +242 -0
  99. package/.ai-rules/skills/skill-creator/SKILL.md +461 -0
  100. package/.ai-rules/skills/skill-creator/agents/analyzer.md +206 -0
  101. package/.ai-rules/skills/skill-creator/agents/comparator.md +167 -0
  102. package/.ai-rules/skills/skill-creator/agents/grader.md +152 -0
  103. package/.ai-rules/skills/skill-creator/assets/eval_review.html +568 -0
  104. package/.ai-rules/skills/skill-creator/assets/skill-template.md +43 -0
  105. package/.ai-rules/skills/skill-creator/eval-viewer/generate_review.py +496 -0
  106. package/.ai-rules/skills/skill-creator/references/frontmatter-guide.md +632 -0
  107. package/.ai-rules/skills/skill-creator/references/multi-tool-compat.md +480 -0
  108. package/.ai-rules/skills/skill-creator/references/schemas.md +784 -0
  109. package/.ai-rules/skills/skill-creator/scripts/aggregate_benchmark.py +302 -0
  110. package/.ai-rules/skills/skill-creator/scripts/init_skill.sh +196 -0
  111. package/.ai-rules/skills/skill-creator/scripts/run_loop.py +327 -0
  112. package/.ai-rules/skills/systematic-debugging/SKILL.md +1 -0
  113. package/.ai-rules/skills/tech-debt/SKILL.md +1 -0
  114. package/.ai-rules/skills/test-coverage-gate/SKILL.md +303 -0
  115. package/.ai-rules/skills/tmux-master/SKILL.md +491 -0
  116. package/.ai-rules/skills/using-git-worktrees/SKILL.md +368 -0
  117. package/.ai-rules/skills/verification-before-completion/SKILL.md +234 -0
  118. package/.ai-rules/skills/widget-slot-architecture/SKILL.md +6 -0
  119. package/.ai-rules/skills/widget-slot-architecture/examples/parallel-route-setup.tsx +206 -0
  120. package/.ai-rules/skills/widget-slot-architecture/examples/widget-component.tsx +250 -0
  121. package/.ai-rules/skills/writing-plans/SKILL.md +78 -0
  122. package/bin/cli.js +170 -0
  123. package/lib/init/detect-stack.js +162 -0
  124. package/lib/init/generate-config.js +31 -0
  125. package/lib/init/index.js +86 -0
  126. package/lib/init/prompt.js +60 -0
  127. package/lib/init/scaffold.js +67 -0
  128. package/lib/init/suggest-agent.js +57 -0
  129. package/package.json +10 -2
@@ -0,0 +1,374 @@
1
+ # Aider Integration Guide
2
+
3
+ Guide for using codingbuddy with Aider (CLI AI pair programming tool).
4
+
5
+ ## Overview
6
+
7
+ codingbuddy integrates with Aider through:
8
+
9
+ 1. **AGENTS.md** - Industry standard format compatible with all AI tools
10
+ 2. **CONVENTIONS.md** - Aider's native convention file format
11
+ 3. **`.aider.conf.yml`** - Aider configuration file
12
+
13
+ ## Two Usage Contexts
14
+
15
+ ### End Users (Your Project)
16
+
17
+ End users provide codingbuddy rules to Aider via read-only convention files:
18
+
19
+ ```bash
20
+ # Load codingbuddy rules as read-only context
21
+ aider --read CONVENTIONS.md
22
+ ```
23
+
24
+ Or configure in `.aider.conf.yml`:
25
+
26
+ ```yaml
27
+ read:
28
+ - CONVENTIONS.md
29
+ ```
30
+
31
+ ### Monorepo Contributors
32
+
33
+ Contributors to the codingbuddy repository can reference `.ai-rules/` files directly:
34
+
35
+ ```bash
36
+ # Load multiple rule files as read-only context
37
+ aider --read packages/rules/.ai-rules/rules/core.md \
38
+ --read packages/rules/.ai-rules/rules/augmented-coding.md \
39
+ --read packages/rules/.ai-rules/rules/project.md \
40
+ --read AGENTS.md
41
+ ```
42
+
43
+ Or in `.aider.conf.yml`:
44
+
45
+ ```yaml
46
+ read:
47
+ - packages/rules/.ai-rules/rules/core.md
48
+ - packages/rules/.ai-rules/rules/augmented-coding.md
49
+ - packages/rules/.ai-rules/rules/project.md
50
+ - AGENTS.md
51
+ ```
52
+
53
+ ## DRY Principle
54
+
55
+ **Single Source of Truth**: `packages/rules/.ai-rules/`
56
+
57
+ - All Agent definitions, rules, skills managed only in `.ai-rules/`
58
+ - `CONVENTIONS.md` acts as a **pointer or summary** referencing `.ai-rules/`
59
+ - No duplication; reference source files via `--read`
60
+
61
+ ## Aider Configuration System
62
+
63
+ ### `.aider.conf.yml`
64
+
65
+ Aider's primary configuration file using YAML format. Loaded from these locations (in order, later files take priority):
66
+
67
+ 1. **Home directory** (`~/.aider.conf.yml`) - Global personal settings
68
+ 2. **Git root** (`.aider.conf.yml`) - Project-level settings
69
+ 3. **Current directory** (`.aider.conf.yml`) - Directory-specific settings
70
+
71
+ ### Configuration Example
72
+
73
+ ```yaml
74
+ # .aider.conf.yml - codingbuddy integration
75
+
76
+ # Load codingbuddy rules as read-only context
77
+ read:
78
+ - CONVENTIONS.md
79
+ - AGENTS.md
80
+
81
+ # Recommended settings for codingbuddy workflow
82
+ auto-commits: true
83
+ suggest-shell-commands: true
84
+ ```
85
+
86
+ ### List Format Options
87
+
88
+ Lists can be specified as bullet lists or inline arrays:
89
+
90
+ ```yaml
91
+ # Bullet list
92
+ read:
93
+ - CONVENTIONS.md
94
+ - AGENTS.md
95
+
96
+ # Inline array
97
+ read: [CONVENTIONS.md, AGENTS.md]
98
+ ```
99
+
100
+ ### CONVENTIONS.md
101
+
102
+ Aider's native mechanism for specifying coding guidelines. Create a `CONVENTIONS.md` in your project root:
103
+
104
+ ```markdown
105
+ # Project Conventions
106
+
107
+ ## Workflow
108
+ Follow PLAN/ACT/EVAL workflow modes.
109
+ - Start in PLAN mode for analysis and planning
110
+ - Move to ACT mode for implementation (TDD: Red -> Green -> Refactor)
111
+ - Use EVAL mode for code quality evaluation
112
+
113
+ ## Code Quality
114
+ - TypeScript strict mode (no `any`)
115
+ - 90%+ test coverage goal
116
+ - SOLID principles
117
+ - No mocking - test real behavior
118
+
119
+ ## TDD Cycle
120
+ 1. Write a failing test (Red)
121
+ 2. Implement minimum code to pass (Green)
122
+ 3. Refactor for clarity (Refactor)
123
+
124
+ ## Project Structure
125
+ See `packages/rules/.ai-rules/rules/project.md` for layered architecture details.
126
+
127
+ ## Specialist Agents
128
+ See `packages/rules/.ai-rules/agents/README.md` for available specialists.
129
+ ```
130
+
131
+ Load it with:
132
+
133
+ ```bash
134
+ aider --read CONVENTIONS.md
135
+ ```
136
+
137
+ > **Tip:** Use `--read` (read-only) instead of `--file` (editable) for convention files. This prevents accidental modifications and enables prompt caching.
138
+
139
+ ### `.aiderignore`
140
+
141
+ Aider supports `.aiderignore` for excluding files from its context, using `.gitignore`-style patterns:
142
+
143
+ ```gitignore
144
+ # .aiderignore
145
+ node_modules/
146
+ dist/
147
+ *.min.js
148
+ *.lock
149
+ ```
150
+
151
+ Place in the git root directory. For custom ignore files, use `--aiderignore <filename>`.
152
+
153
+ ## Integration Methods
154
+
155
+ ### Method 1: CONVENTIONS.md (Recommended for End Users)
156
+
157
+ Create a `CONVENTIONS.md` summarizing your project's coding standards, then load it as read-only context:
158
+
159
+ ```bash
160
+ aider --read CONVENTIONS.md
161
+ ```
162
+
163
+ ### Method 2: Direct `.ai-rules/` References (Recommended for Contributors)
164
+
165
+ Load specific rule files directly for comprehensive coverage:
166
+
167
+ ```yaml
168
+ # .aider.conf.yml
169
+ read:
170
+ - packages/rules/.ai-rules/rules/core.md
171
+ - packages/rules/.ai-rules/rules/augmented-coding.md
172
+ - packages/rules/.ai-rules/rules/project.md
173
+ - AGENTS.md
174
+ ```
175
+
176
+ ### Method 3: Combined Approach
177
+
178
+ Use `CONVENTIONS.md` for quick reference and load detailed rules separately:
179
+
180
+ ```yaml
181
+ # .aider.conf.yml
182
+ read:
183
+ - CONVENTIONS.md
184
+ - packages/rules/.ai-rules/rules/core.md
185
+ ```
186
+
187
+ ## Directory Structure
188
+
189
+ ```
190
+ project/
191
+ ├── .aider.conf.yml # Aider configuration
192
+ ├── .aiderignore # File exclusion patterns
193
+ ├── CONVENTIONS.md # Coding conventions (for Aider)
194
+ ├── AGENTS.md # Cross-platform agent definitions
195
+ ├── packages/rules/.ai-rules/
196
+ │ ├── rules/
197
+ │ │ ├── core.md
198
+ │ │ ├── project.md
199
+ │ │ └── augmented-coding.md
200
+ │ ├── agents/
201
+ │ │ └── *.json
202
+ │ └── adapters/
203
+ │ └── aider.md # This guide
204
+ └── ~/.aider.conf.yml # Global user settings
205
+ ```
206
+
207
+ ## Usage
208
+
209
+ ### Basic Workflow
210
+
211
+ ```bash
212
+ # Start Aider with codingbuddy conventions
213
+ aider --read CONVENTIONS.md
214
+
215
+ # In the Aider chat, reference workflow modes
216
+ > Please follow PLAN mode to design this feature first
217
+
218
+ # Add specific files for editing
219
+ > /add src/auth/login.ts
220
+
221
+ # Add read-only context
222
+ > /read packages/rules/.ai-rules/agents/security-specialist.json
223
+ ```
224
+
225
+ ### In-Chat Commands
226
+
227
+ | Command | Purpose |
228
+ |---------|---------|
229
+ | `/add <file>` | Add file for editing |
230
+ | `/read <file>` | Add file as read-only context |
231
+ | `/drop <file>` | Remove file from context |
232
+ | `/ask <question>` | Ask without making changes |
233
+ | `/architect <request>` | Use architect mode for planning |
234
+
235
+ ### Architect Mode
236
+
237
+ Aider's `/architect` command maps naturally to codingbuddy's PLAN mode:
238
+
239
+ ```bash
240
+ # PLAN mode equivalent
241
+ > /architect Design a user authentication system with JWT
242
+
243
+ # ACT mode equivalent (regular chat)
244
+ > Implement the authentication system following TDD
245
+ ```
246
+
247
+ ### Using Specialist Context
248
+
249
+ Load specialist agent definitions as read-only context for focused reviews:
250
+
251
+ ```bash
252
+ # Security review
253
+ > /read packages/rules/.ai-rules/agents/security-specialist.json
254
+ > Review the auth implementation from a security perspective
255
+
256
+ # Performance review
257
+ > /read packages/rules/.ai-rules/agents/performance-specialist.json
258
+ > Analyze performance bottlenecks in this module
259
+ ```
260
+
261
+ ## Community Conventions
262
+
263
+ Aider maintains a community conventions repository at [github.com/Aider-AI/conventions](https://github.com/Aider-AI/conventions) with pre-built convention files for various tech stacks. These can complement codingbuddy rules.
264
+
265
+ ## MCP Support
266
+
267
+ > **Note:** As of early 2026, Aider does not natively support MCP servers. Rules integration relies on the `--read` flag and `CONVENTIONS.md` approach described above. If MCP support is added in the future, the same codingbuddy MCP server configuration used by other tools can be applied.
268
+
269
+ ### Workaround: Using Aider with MCP-Provided Rules
270
+
271
+ Export rules from the MCP server to files, then load them in Aider:
272
+
273
+ ```bash
274
+ # Export rules content to a file (manual step)
275
+ # Then load in Aider
276
+ aider --read exported-rules.md
277
+ ```
278
+
279
+ ## Skills
280
+
281
+ Without MCP support, Aider accesses codingbuddy skills through file references:
282
+
283
+ ### Using Skills
284
+
285
+ ```bash
286
+ # Load a skill as read-only context
287
+ > /read packages/rules/.ai-rules/skills/systematic-debugging/SKILL.md
288
+ > Debug this authentication failure using the systematic debugging approach
289
+
290
+ > /read packages/rules/.ai-rules/skills/test-driven-development/SKILL.md
291
+ > Implement this feature following TDD workflow
292
+ ```
293
+
294
+ ### Available Skills
295
+
296
+ | Skill | File |
297
+ |-------|------|
298
+ | Systematic Debugging | `skills/systematic-debugging/SKILL.md` |
299
+ | Test-Driven Development | `skills/test-driven-development/SKILL.md` |
300
+ | Brainstorming | `skills/brainstorming/SKILL.md` |
301
+ | Writing Plans | `skills/writing-plans/SKILL.md` |
302
+ | Executing Plans | `skills/executing-plans/SKILL.md` |
303
+ | Frontend Design | `skills/frontend-design/SKILL.md` |
304
+
305
+ ## Known Limitations
306
+
307
+ Aider is a CLI tool with a different architecture than IDE-based AI assistants:
308
+
309
+ | Feature | Status | Workaround |
310
+ |---------|--------|------------|
311
+ | **MCP Server support** | ❌ Not available | Use `--read` flag with convention/rule files |
312
+ | **Mode keywords (PLAN/ACT/EVAL/AUTO)** | ❌ Not native | Manually instruct Aider to follow mode workflows |
313
+ | **Specialist agent dispatch** | ❌ Not available | Load specialist JSON as read-only context with `/read` |
314
+ | **Background subagents** | ❌ Not available | Sequential analysis only |
315
+ | **Session hooks** | ❌ Not available | Rely on `.aider.conf.yml` for always-on settings |
316
+ | **Context document persistence** | ❌ Not available | Manually manage context between sessions |
317
+ | **Skills auto-detection** | ❌ Not available | Manually load skills via `/read` |
318
+ | **Autonomous loop (AUTO mode)** | ❌ Not available | Use Aider's interactive chat loop manually |
319
+
320
+ ### Aider Strengths
321
+
322
+ Despite these limitations, Aider offers unique advantages:
323
+
324
+ - **CLI-native**: Works in any terminal, SSH sessions, CI/CD pipelines
325
+ - **Git-aware**: Automatic commits, diff-based editing
326
+ - **Repo-map**: Automatic codebase understanding via tree-sitter
327
+ - **Multi-model**: Supports OpenAI, Anthropic, local models, and more
328
+ - **Prompt caching**: Read-only files are cached for efficient token usage
329
+ - **Architect mode**: Built-in plan-then-implement workflow
330
+
331
+ ## AGENTS.md
332
+
333
+ Industry standard format compatible with all AI tools (Aider, Cursor, Claude Code, Codex, etc.):
334
+
335
+ ```markdown
336
+ # AGENTS.md
337
+
338
+ This project uses codingbuddy MCP server to manage AI Agents.
339
+
340
+ ## Quick Start
341
+ ...
342
+ ```
343
+
344
+ See `AGENTS.md` in project root for details. Aider can read this file:
345
+
346
+ ```bash
347
+ aider --read AGENTS.md
348
+ ```
349
+
350
+ ## Verification Status
351
+
352
+ > Documentation based on Aider public documentation and community resources. Runtime verification has been performed for core features.
353
+
354
+ | Pattern | Status | Notes |
355
+ |---------|--------|-------|
356
+ | `CONVENTIONS.md` loading via `--read` | ✅ Verified | Documented in official Aider docs |
357
+ | `.aider.conf.yml` configuration | ✅ Verified | YAML format with multi-location loading |
358
+ | `.aiderignore` file support | ✅ Verified | `.gitignore`-style patterns |
359
+ | Read-only file context (`/read`) | ✅ Verified | Files cached with prompt caching enabled |
360
+ | Architect mode for planning | ✅ Verified | Maps to PLAN mode workflow |
361
+ | MCP server integration | ❌ Not supported | No native MCP support as of early 2026 |
362
+ | AGENTS.md compatibility | ✅ Verified | Standard markdown, loadable via `--read` |
363
+ | Community conventions repo | ✅ Verified | Available at github.com/Aider-AI/conventions |
364
+
365
+ ## Reference
366
+
367
+ - [Aider Documentation](https://aider.chat/docs/)
368
+ - [Aider Conventions Guide](https://aider.chat/docs/usage/conventions.html)
369
+ - [Aider Configuration](https://aider.chat/docs/config/aider_conf.html)
370
+ - [Aider Options Reference](https://aider.chat/docs/config/options.html)
371
+ - [Aider In-Chat Commands](https://aider.chat/docs/usage/commands.html)
372
+ - [Community Conventions Repository](https://github.com/Aider-AI/conventions)
373
+ - [AGENTS.md Official Spec](https://agents.md)
374
+ - [codingbuddy Documentation](../../docs/)
@@ -30,9 +30,9 @@ End users access rules **only through MCP tools**. No local rule files needed.
30
30
  }
31
31
  ```
32
32
 
33
- > **Important:** Antigravity `roots/list` MCP capability 지원 여부는 미확인입니다.
34
- > `CODINGBUDDY_PROJECT_ROOT` 없이는 서버가 프로젝트의 `codingbuddy.config.json`을 찾지 못하여
35
- > `language` 설정이 기본값으로 동작합니다. 항상 환경변수를 프로젝트의 절대 경로로 설정하세요.
33
+ > **Important:** Whether Antigravity supports the `roots/list` MCP capability has not been confirmed.
34
+ > Without `CODINGBUDDY_PROJECT_ROOT`, the server cannot locate your project's `codingbuddy.config.json`,
35
+ > causing settings such as `language` to use default values. Always set this environment variable to your project's absolute path.
36
36
 
37
37
  Optional: Create `.antigravity/rules/instructions.md` for basic integration:
38
38
 
@@ -567,7 +567,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
567
567
  | Language | Keyword |
568
568
  |----------|---------|
569
569
  | English | `AUTO` |
570
- | Korean | `자동` |
570
+ | Korean | `AUTO` |
571
571
  | Japanese | `自動` |
572
572
  | Chinese | `自动` |
573
573
  | Spanish | `AUTOMÁTICO` |
@@ -579,7 +579,7 @@ AUTO implement user authentication feature
579
579
  ```
580
580
 
581
581
  ```
582
- 자동 사용자 인증 기능 구현해줘
582
+ AUTO implement user authentication feature
583
583
  ```
584
584
 
585
585
  When AUTO keyword is detected, Antigravity calls `parse_mode` MCP tool which returns AUTO mode instructions.
@@ -626,7 +626,7 @@ task_boundary(
626
626
  )
627
627
  ```
628
628
 
629
- > **Antigravity limitation:** AUTO mode에는 강제 루프 메커니즘이 없습니다. 자세한 내용은 [Known Limitations](#known-limitations) 참조하세요.
629
+ > **Antigravity limitation:** AUTO mode has no enforcement loop mechanism. See [Known Limitations](#known-limitations) for details.
630
630
 
631
631
  ## Context Document Management
632
632
 
@@ -191,8 +191,8 @@ Use `recommend_skills` MCP tool to get skill recommendations based on user promp
191
191
  recommend_skills({ prompt: "There is a bug in the login" })
192
192
  // => recommends: systematic-debugging
193
193
 
194
- recommend_skills({ prompt: "로그인에 버그가 있어" })
195
- // => recommends: systematic-debugging (Korean support)
194
+ recommend_skills({ prompt: "There is a bug in the login" })
195
+ // => recommends: systematic-debugging (multi-language support)
196
196
 
197
197
  recommend_skills({ prompt: "Build a dashboard component" })
198
198
  // => recommends: frontend-design
@@ -523,6 +523,70 @@ Each workflow mode activates different specialist agents:
523
523
 
524
524
  **Important:** Specialists from one mode do NOT carry over to the next mode. Each mode has its own recommended specialist set.
525
525
 
526
+ ### Auto-Dispatch Enforcement
527
+
528
+ When `parse_mode` returns `dispatch="auto"` or `dispatchReady` with specialist agents, dispatching is **mandatory** — not optional.
529
+
530
+ **Rule:** Every listed specialist MUST be dispatched. Skipping any specialist is a protocol violation.
531
+
532
+ #### Teams-Based Specialist Dispatch (Preferred)
533
+
534
+ Teams are preferred over the Agent tool for specialist dispatch because they enable structured coordination and message-based reporting:
535
+
536
+ ```
537
+ 1. TeamCreate({ team_name: "<task>-specialists" })
538
+ 2. Spawn specialists as teammates:
539
+ Agent({ team_name, name: "security-specialist", subagent_type: "general-purpose", prompt: ... })
540
+ Agent({ team_name, name: "code-quality-specialist", subagent_type: "general-purpose", prompt: ... })
541
+ 3. Create and assign tasks:
542
+ TaskCreate({ subject: "Security review of auth module" })
543
+ TaskUpdate({ taskId, owner: "security-specialist" })
544
+ 4. Specialists work autonomously, report via SendMessage:
545
+ SendMessage({ to: "team-lead", message: "## Security Findings\n- ...", summary: "Security review done" })
546
+ 5. Team lead collects all findings
547
+ 6. Shutdown: SendMessage({ to: "security-specialist", message: { type: "shutdown_request" } })
548
+ ```
549
+
550
+ #### SendMessage-Based Reporting
551
+
552
+ Specialists report findings through `SendMessage` to the team lead. This enables:
553
+ - Structured collection of all specialist outputs
554
+ - Consolidated summary for the user
555
+ - Clear audit trail of what each specialist found
556
+
557
+ **Report format:**
558
+ ```markdown
559
+ ## [Specialist Name] Findings
560
+
561
+ ### Critical
562
+ - [finding]
563
+
564
+ ### High
565
+ - [finding]
566
+
567
+ ### Medium
568
+ - [finding]
569
+
570
+ ### Recommendations
571
+ - [recommendation]
572
+ ```
573
+
574
+ #### Fallback: Agent Tool
575
+
576
+ If Teams-based dispatch fails, fall back to the Agent tool:
577
+ - Use `run_in_background: true` for each specialist
578
+ - Collect results via `TaskOutput`
579
+ - Document the fallback reason in your response
580
+
581
+ #### Red Flags
582
+
583
+ | Thought | Reality |
584
+ |---------|---------|
585
+ | "I can handle this analysis myself" | Specialists have domain expertise. Dispatch them. |
586
+ | "It's just a small change" | dispatch="auto" means the system determined specialists are needed. |
587
+ | "I'll save time by skipping" | Skipping causes missed issues that cost more later. |
588
+ | "I'll dispatch later" | Dispatch IMMEDIATELY when dispatch="auto" is returned. |
589
+
526
590
  ### Execution Strategy Selection (MANDATORY)
527
591
 
528
592
  When `parse_mode` returns `availableStrategies`:
@@ -621,7 +685,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
621
685
  | Language | Keyword |
622
686
  |----------|---------|
623
687
  | English | `AUTO` |
624
- | Korean | `자동` |
688
+ | Korean | `AUTO` |
625
689
  | Japanese | `自動` |
626
690
  | Chinese | `自动` |
627
691
  | Spanish | `AUTOMATICO` |
@@ -633,7 +697,7 @@ AUTO implement user authentication with JWT tokens
633
697
  ```
634
698
 
635
699
  ```
636
- 자동 사용자 인증 기능을 JWT로 구현해줘
700
+ AUTO implement user authentication with JWT
637
701
  ```
638
702
 
639
703
  ### Expected Behavior
@@ -30,10 +30,10 @@ End users access rules **only through MCP tools**. No local rule files needed.
30
30
  }
31
31
  ```
32
32
 
33
- > **Important:** Codex(GitHub Copilot) `roots/list` MCP capability 지원 여부는 미확인입니다.
34
- > `CODINGBUDDY_PROJECT_ROOT` 없이는 서버가 프로젝트의 `codingbuddy.config.json`을 찾지 못하여
35
- > `language` 설정이 기본값으로 동작합니다. 항상 환경변수를 프로젝트의 절대 경로로 설정하세요.
36
- > Codex `${workspaceFolder}` 변수 확장을 지원하는 경우, 절대 경로 대신 사용할 있습니다.
33
+ > **Important:** Whether Codex (GitHub Copilot) supports the `roots/list` MCP capability has not been confirmed.
34
+ > Without `CODINGBUDDY_PROJECT_ROOT`, the server cannot locate your project's `codingbuddy.config.json`,
35
+ > causing settings such as `language` to use default values. Always set this environment variable to your project's absolute path.
36
+ > If Codex supports `${workspaceFolder}` variable expansion, you can use it instead of an absolute path.
37
37
 
38
38
  ### Monorepo Contributors
39
39
 
@@ -599,7 +599,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
599
599
  | Language | Keyword |
600
600
  |----------|---------|
601
601
  | English | `AUTO` |
602
- | Korean | `자동` |
602
+ | Korean | `AUTO` |
603
603
  | Japanese | `自動` |
604
604
  | Chinese | `自动` |
605
605
  | Spanish | `AUTOMATICO` |
@@ -403,7 +403,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
403
403
  | Language | Keyword |
404
404
  |----------|---------|
405
405
  | English | `AUTO` |
406
- | Korean | `자동` |
406
+ | Korean | `AUTO` |
407
407
  | Japanese | `自動` |
408
408
  | Chinese | `自动` |
409
409
  | Spanish | `AUTOMATICO` |
@@ -415,7 +415,7 @@ AUTO implement user authentication feature
415
415
  ```
416
416
 
417
417
  ```
418
- 자동 사용자 인증 기능 구현해줘
418
+ AUTO implement user authentication feature
419
419
  ```
420
420
 
421
421
  When AUTO keyword is detected, Cursor calls `parse_mode` MCP tool which returns AUTO mode instructions.
@@ -30,9 +30,9 @@ End users access rules **only through MCP tools**. No local rule files needed.
30
30
  }
31
31
  ```
32
32
 
33
- > **Important:** Kiro `roots/list` MCP capability 지원 여부는 미확인입니다.
34
- > `CODINGBUDDY_PROJECT_ROOT` 없이는 서버가 프로젝트의 `codingbuddy.config.json`을 찾지 못하여
35
- > `language` 설정이 기본값으로 동작합니다. 항상 환경변수를 프로젝트의 절대 경로로 설정하세요.
33
+ > **Important:** Whether Kiro supports the `roots/list` MCP capability has not been confirmed.
34
+ > Without `CODINGBUDDY_PROJECT_ROOT`, the server cannot locate your project's `codingbuddy.config.json`,
35
+ > causing settings such as `language` to use default values. Always set this environment variable to your project's absolute path.
36
36
 
37
37
  Optional: Create `.kiro/rules/guidelines.md` for basic integration:
38
38
 
@@ -85,8 +85,8 @@ MCP server configuration for codingbuddy tools:
85
85
  }
86
86
  ```
87
87
 
88
- > **Note:** Kiro `${VARIABLE}` 문법으로 환경변수 확장을 지원합니다.
89
- > `${workspaceFolder}` 지원되는 경우 절대 경로 대신 사용할 있습니다.
88
+ > **Note:** Kiro supports environment variable expansion using the `${VARIABLE}` syntax.
89
+ > If `${workspaceFolder}` is supported, you can use it instead of an absolute path.
90
90
 
91
91
  **MCP configuration paths:**
92
92
  - **Project-level**: `.kiro/settings/mcp.json`
@@ -526,7 +526,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
526
526
  | Language | Keyword |
527
527
  |----------|---------|
528
528
  | English | `AUTO` |
529
- | Korean | `자동` |
529
+ | Korean | `AUTO` |
530
530
  | Japanese | `自動` |
531
531
  | Chinese | `自动` |
532
532
  | Spanish | `AUTOMÁTICO` |
@@ -538,7 +538,7 @@ AUTO implement user authentication feature
538
538
  ```
539
539
 
540
540
  ```
541
- 자동 사용자 인증 기능 구현해줘
541
+ AUTO implement user authentication feature
542
542
  ```
543
543
 
544
544
  When AUTO keyword is detected, Kiro calls `parse_mode` MCP tool which returns AUTO mode instructions.
@@ -571,7 +571,7 @@ module.exports = {
571
571
  - Bug fixes needing comprehensive testing
572
572
  - Code quality improvements with measurable criteria
573
573
 
574
- > **Kiro limitation:** AUTO mode에는 강제 루프 메커니즘이 없습니다. 자세한 내용은 [Known Limitations](#known-limitations) 참조하세요.
574
+ > **Kiro limitation:** AUTO mode has no enforcement loop mechanism. See [Known Limitations](#known-limitations) for details.
575
575
 
576
576
  ## Context Document Management
577
577
 
@@ -184,9 +184,9 @@ Add to your MCP configuration:
184
184
  }
185
185
  ```
186
186
 
187
- > **Important:** OpenCode/Crush `roots/list` MCP capability 지원 여부는 미확인입니다.
188
- > `CODINGBUDDY_PROJECT_ROOT` 없이는 서버가 프로젝트의 `codingbuddy.config.json`을 찾지 못하여
189
- > `language` 설정이 기본값으로 동작합니다. 항상 환경변수를 프로젝트의 절대 경로로 설정하세요.
187
+ > **Important:** Whether OpenCode/Crush supports the `roots/list` MCP capability has not been confirmed.
188
+ > Without `CODINGBUDDY_PROJECT_ROOT`, the server cannot locate your project's `codingbuddy.config.json`,
189
+ > causing settings such as `language` to use default values. Always set this environment variable to your project's absolute path.
190
190
 
191
191
  #### Available MCP Tools
192
192
 
@@ -526,9 +526,9 @@ npx codingbuddy@latest mcp
526
526
 
527
527
  **4. Project Config Not Detected**
528
528
  ```bash
529
- # CODINGBUDDY_PROJECT_ROOT MCP env에 설정되어 있는지 확인
530
- # 환경변수 없이는 codingbuddy.config.json 찾지 못합니다
531
- # .opencode.json 또는 crush.json의 mcp 섹션에 추가:
529
+ # Verify that CODINGBUDDY_PROJECT_ROOT is set in MCP env
530
+ # Without this environment variable, codingbuddy.config.json cannot be found
531
+ # Add to the mcp section of .opencode.json or crush.json:
532
532
  "env": {
533
533
  "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project"
534
534
  }
@@ -752,7 +752,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
752
752
  | Language | Keyword |
753
753
  |----------|---------|
754
754
  | English | `AUTO` |
755
- | Korean | `자동` |
755
+ | Korean | `AUTO` |
756
756
  | Japanese | `自動` |
757
757
  | Chinese | `自动` |
758
758
  | Spanish | `AUTOMÁTICO` |
@@ -178,7 +178,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
178
178
  | Language | Keyword |
179
179
  |----------|---------|
180
180
  | English | `AUTO` |
181
- | Korean | `자동` |
181
+ | Korean | `AUTO` |
182
182
  | Japanese | `自動` |
183
183
  | Chinese | `自动` |
184
184
  | Spanish | `AUTOMATICO` |
@@ -186,7 +186,7 @@ Use the `AUTO` keyword (or localized versions) at the start of your message:
186
186
  ### Example Usage
187
187
 
188
188
  ```
189
- AUTO 새로운 Lambda 함수 만들어줘
189
+ AUTO create a new Lambda function
190
190
  ```
191
191
 
192
192
  ### Workflow