docs: clarify YAML-first custom modes behavior#5988
docs: clarify YAML-first custom modes behavior#5988Olusammytee wants to merge 2 commits intoKilo-Org:mainfrom
Conversation
|
There was a problem hiding this comment.
Pull request overview
This PR improves the documentation for custom modes configuration by clarifying the YAML-first approach and the legacy status of JSON files. The changes address confusion around which file format to use and how the two formats interact.
Changes:
- Clarified that imported mode files should use
.yamlextension - Updated manual configuration section to explicitly mark
custom_modes.yamlas primary andcustom_modes.jsonas legacy fallback - Added informational callout explaining why both YAML and JSON files may coexist and clarifying that YAML takes precedence
| These files define an array/list of custom modes. | ||
|
|
||
| {% callout type="info" title="Why JSON Files May Still Exist" %} | ||
| If you see both YAML and JSON mode files, this is usually from legacy configuration. Kilo Code reads YAML first and does not keep both files synchronized line-by-line. In practice, edit YAML unless you have a specific reason to stay on JSON. |
There was a problem hiding this comment.
The phrase "Kilo Code reads YAML first" could be misleading. Based on the code implementation, Kilo Code only reads from custom_modes.yaml after migration. The JSON file is preserved during migration for rollback purposes but is not actively read or synchronized. Consider clarifying to: "Kilo Code reads only the YAML file; the JSON file is preserved for rollback but not actively used."
| If you see both YAML and JSON mode files, this is usually from legacy configuration. Kilo Code reads YAML first and does not keep both files synchronized line-by-line. In practice, edit YAML unless you have a specific reason to stay on JSON. | |
| If you see both YAML and JSON mode files, this is usually from legacy configuration. Kilo Code reads only the YAML file; the JSON file is preserved for rollback but not actively used. In practice, edit YAML unless you have a specific reason to stay on JSON. <!-- kilocode_change --> |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fdccdc2932
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| These files define an array/list of custom modes. | ||
|
|
||
| {% callout type="info" title="Why JSON Files May Still Exist" %} | ||
| If you see both YAML and JSON mode files, this is usually from legacy configuration. Kilo Code reads YAML first and does not keep both files synchronized line-by-line. In practice, edit YAML unless you have a specific reason to stay on JSON. |
There was a problem hiding this comment.
This callout implies that continuing to use JSON is a supported steady-state ("edit YAML unless you have a specific reason to stay on JSON"), but current runtime code only reads custom_modes.yaml (GlobalFileNames.customModes in src/shared/globalFileNames.ts and getCustomModesFilePath() in src/core/config/CustomModesManager.ts); custom_modes.json is only consulted during one-time migration when YAML is absent (src/utils/migrateSettings.ts). In environments where both files exist after migration, users who keep editing JSON based on this guidance will see no mode updates applied.
Useful? React with 👍 / 👎.
|
Migrated to Kilo-Org/kilo#481 due docs repo migration to Kilo-Org/kilo. Closing this PR as superseded. |
|
Superseded by Kilo-Org/kilo#481. |
Summary
Notes
Supersedes #5956 due stale head SHA/update mismatch on the original PR branch.