[Coldbox CLI] Clarification on .gitignore for Agentic ColdBox .ai/ folder

Communities ColdBox HMVC
1

Really liking what you all are doing with Agentic ColdBox. I was reading through the docs and got a little confused about the recommended Git strategy for the new .ai/ folder.

From what I can tell, the .ai/ directory contains a mix of generated framework/module resources and project-specific custom resources.

The docs mention committing things like:

  • .ai/guidelines/custom/
  • .ai/skills/custom/
  • .ai/manifest.json

But I wasn’t sure if that means we should be ignoring the rest of .ai/ , or committing the whole folder.

For example, should folders like these normally be ignored?

  • .ai/guidelines/core/
  • .ai/guidelines/modules/
  • .ai/skills/core/
  • .ai/skills/modules/

It would be really helpful if the docs included a sample .gitignore so there is a clear best practice.

Right now I wasn’t sure if the recommendation is:

  1. Commit the whole .ai/ folder
  2. Only commit custom content and manifest.json
  3. Something in between

Could someone clarify what the intended best practice is?

2

The best practice is to include it all in source control. I thought I made that clear from the docs, if not, please let me know where to change that.

This is YOUR agentic AI for ColdBox. The templates/skills/guidelines are in the module but the .ai folder is for your app.

3

I interpreted the docs like this:

The following folders should be treated similar to Forgebox modules because they will receive periodic updates from their maintainers, therefore they should be ignored. I expect users will periodically run coldbox ai refresh to update them.
side note: I actually expected the command to be coldbox ai update, similar to updating modules. Maybe there could be an alias to keep the original convention?

.ai/skills/core/
.ai/skills/modules/

.ai/guidelines/core/
.ai/guidelines/modules

The following folders are MINE, because they contain skills and guidelines for my specific app:

.ai/skills/custom/
.ai/skills/overrides/ (folder not created by default, btw)

.ai/guidelines/custom/
.ai/guidelines/overrides/ (folder not created by default, btw)

Therefore, a .gitignore example would look like this:

# Ignore everything under .ai by default
.ai/**

# Keep the root folder
!.ai/

# Keep project-authored guidelines
!.ai/guidelines/
!.ai/guidelines/custom/
!.ai/guidelines/custom/**
!.ai/guidelines/overrides/
!.ai/guidelines/overrides/**

# Keep project-authored skills
!.ai/skills/
!.ai/skills/custom/
!.ai/skills/custom/**
!.ai/skills/overrides/
!.ai/skills/overrides/**

I intentionally left out manifest.json in my example above because when you run coldbox ai refresh it rebuilds the manifest based on all skills and guidelines, including custom ones, which is great!

One thing I did notice is that whenever you run coldbox ai refresh it will overwrite your CLAUDE.md file. I think this might be a bug since that file is a “living document” meant to be specific to your app. I’ll file an issue on the CLI Github repo.

Hopefully I interpreted the intent of the docs correctly. If so, maybe it would help to provide the above sample .gitignore with comments to make it clearer?