Add repositories symlink feature for advanced AI usage

[hohwille]

Feature idea

As an IDEasy user, I want my project to be preconfigured for my AI tool-chain.
Unfortunately the AI tool makers and IDE vendors do not have a common standard or a smart approach for AI configuration yet. The current status is:

• Your configuration folder has to be in the workspace root
• The configuration folder name is specific for your AI tool
  • For Claude use .claude
  • For Kira use .kiro
  • For Copilot use .github (while it also honors .claude but not .kiro).

Surely you want to have your AI stuff in a git repository to share them with your team.
The most intuitive or naive way is that projects simply add such folder(s) directly to their git repo together with their code.
However, this may cause multiple problems:

• No support for multiple AI tools (without massive redundant maintenance)
• Problem if your project uses multiple git repositories (micro-services without mono-repo approach, and believe me if you are not Google then mono-repo is not the answer!)
• AI is moving fast but your code repo may be big and have complex pipelines to bring in changes so it might be slow you down to bring fast and frequent changes to skills, hooks, or instructions (to many branches)

The idea for this story is therefore that IDEasy will support a new property in the properties configuration of a repository:

git_url=https://github.com/someorg/ai-instructions.git
workspace=*
links=.github,.claude,.kiro
active=true

This is a generic feature that is not AI specific:

• workspaces=* means all existing workspaces.
• links=«path»[,«path»] means a comma separated list of relative paths that will be created as symbolic link to point to the cloded git repo.

When I run ide update again, it will honour this feature and find out if new workspaces have been created and links are missing and create all missing symlinks automatically and seamless.

As a result we should get this in every folder $IDE_HOME/workspaces/«workspace»:

/ 
├──/ .claude/ → ai-instructions/
├──/ .github/ → ai-instructions/
├──/ .kiro/ → ai-instructions/
├──/ ai-instructions/
│  ├──/ hooks/
│  ├──/ rules/
│  ├──/ skills/
│  ├──/ steering/
│  ├──/ CLAUDE.md
│  └──/ copilot-instructions.md
└──/ .../

Additional context

To support workspaces=* we have to collect all explicit workspaces from all repository properties upfront to avoid bugs that depending on the name order of multiple «repository».properties you will get different results.
However, additionally also all existing folders in workspaces need to be honored if the user manually creates them.

p.s.: We hope that AI and IDE vendors will get together and improve standardisation to prevent much of this mess. It is especially sad that there is no standard for instructions (.claude/CLAUDE.md vs. .github/copilot-instructions.md vs. .kiro/steering/*.md). Meanwhile you might use git-symbolic-links-feature as a workaround for such things.

[maybeec]

I am not sure, whether currently this would be overengineered to have one repository for all ai-instructions. Here is why:

1. ecosystem is in constant change. GitHub Copilot for example meanwhile also supports claude.md: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
2. the vendor specific ai-instructions folders might come with different elements like for example copilot support instructions, while claude supports rules. The semantics are very different. So having a multi-tool setup is not as re-usable as it seems to be.
3. I am using claude cli + github copilot and thus having two skills folders in .claude and .github and interestingly the AI does not care in which folder the skill is but sometimes finds in both locations skills which are needed.
4. hooks are very different so far between claude & github
   => Underlining most of my and others experiences shows that interpretation of the "ai-instructions" are for sure not deterministic on the one hand side which could end up in interfering behavior of configuration which is available just for github although it has been executed by claude and thus leading to different semantics in interpretation and prioritization of information.

My suggestion is to keep the ai-instructions separate per tool. Additionally, I would even vote for KISS and simply use the feature of ideasy to simply clone the same instructions repo to every of your workspace. This enables you to make some custom changes on specific workspaces if needed for more proper local execution or experiments without colliding your work in other workspaces.

I would not use this feature honestly and think it's too fragile as of speed of tool development to be reliable enough with a bad ROI.

[TonyCap]

With the simple approach of having links to the "whole repository", there would still be the limitation that for example CLAUDE.md and copilot-instructions.md might have just the same content. Moreover, I think CLAUDE.md even goes to the root of the workspace, next to .claude and not inside. To solve this by links avoiding duplication of the markdown files, they'd need to be more specific. For example, .github/copilot-instructions.md -> ai-instructions/instructions.md and CLAUDE.md -> ai-instructions/instructions.md. Thinking about this, maybe this could be separated from the repositories themselves? Like self-contained "link management" for a workspace?

[hohwille]

Thanks @maybeec and @TonyCap for your feedback.
Surely in the CSV for the links we could also support that we have key=value pairs where key is the target link path relative to the workspace folder and value is the path where the link will point to so if =value is omitted, the path to the cloned git repo dir is used as default.

However, @maybeec is proposing to go for KISS (do nothing) while the latter discussion with @TonyCap may rather lead to over-engineering?

I would not mind implementing this and still nothing in what will be implemented is in any way specific for AI - it is just a generic feature. However, maybe we find some common conclusion for the different ideas and views.

[hohwille]

I am not sure, whether currently this would be overengineered to have one repository for all ai-instructions. Here is why:

1. ecosystem is in constant change. GitHub Copilot for example meanwhile also supports claude.md: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions

Fully aware of this. Also wrote the same in the story spec.
The story I am proposing is motivated by AI but the feature is fully generic and not specific to AI.
If AI evolves and this will make such setup easier with less symbolic links - even better.
I guess at least one symlink will still be required.

2. the vendor specific ai-instructions folders might come with different elements like for example copilot support instructions, while claude supports rules. The semantics are very different. So having a multi-tool setup is not as re-usable as it seems to be.

I am fully fine to have these instruction MD files redundant if you really want to use multiple AIs in parallel as well.
But for hooks, skills, prompts, etc. this is not acceptable.

3. I am using claude cli + github copilot and thus having two skills folders in .claude and .github and interestingly the AI does not care in which folder the skill is but sometimes finds in both locations skills which are needed.

Sounds crazy. As already agreed AI is a hot and moving target.

4. hooks are very different so far between claude & github
   => Underlining most of my and others experiences shows that interpretation of the "ai-instructions" are for sure not deterministic on the one hand side which could end up in interfering behavior of configuration which is available just for github although it has been executed by claude and thus leading to different semantics in interpretation and prioritization of information.

That is very valuable feedback for the AI use-case. However, IMHO it will only change how to use such feature as described here once implemented in IDEasy.
I can still do

link=.github

or

link=.github/skills=skills,.claude/skills=skills,.github/hooks=myhooks/github,.claude/hooks=myhooks/claude

However, I am not suggesting this as a best-practice for the wild.
It just shows that the specified feature gives a lot of flexibility.

My suggestion is to keep the ai-instructions separate per tool.

Agreed.

Additionally, I would even vote for KISS and simply use the feature of ideasy to simply clone the same instructions repo to every of your workspace.

I am also happy for KISS.
If we can solve the problem without implementing any change, that is always the best option.
However, I do not see how the demands behind this story would be solved out of the box.
You could use

path=.

But this is a hack but not a solution:

• It will cause that we have the workspace itself as a local git repo clone that will/may contain sub-folders that are also local git repo clones but not sub-modules. This was called anti-pattern or even sick here.
• It will cause bugs: If you create your project before that repository config was present, then the workspace is already populated and git clone will fail.

Apart from how would you setup a project with IDEasy that automatically gives you preconfigured stuff like say workspaces/main/.github/copilot-instructions.md?
The only idea I have is not to use the «repository».properties approach at all but put your AI config into the settings git repo itself.
Maybe that would also be an interesting workaround:
Simply put it here: https://github.com/devonfw/ide-settings/tree/main/workspace/update
However, I would prefer to have the AI config in its own git repo...
Also users might get confused if they do edit the AI config that they see in their IDE root directory and then after restarting the IDE the next day all changes are reverted since they actually have to do the changes in the settings and commit + push then there...

This enables you to make some custom changes on specific workspaces if needed for more proper local execution or experiments without colliding your work in other workspaces.

That is IMHO a different discussion and more about #1569 and the option to configure if you want redundant clones or repos getting symlinked from the initial clone.
Also interesting feedback. However, according to my experience also with submodules it is even more painful to sync many redundant git repos and maintain them.

I would not use this feature honestly and think it's too fragile as of speed of tool development to be reliable enough with a bad ROI.

Implementing this feature is less invest for me than having this discussion. I also do not see much maintenance overhead for IDEasy.
Thanks for your feedback and clear words. I am often perceived a little harsh when I want to make my PoV clear to others ;)

[maybeec]

Thanks for taking the time for discussing this. I think this discussion is really valuable to the solution.

I can still do link=.github or link=.github/skills=skills,.claude/skills=skills,.github/hooks=myhooks/github,.claude/hooks=myhooks/claude

I buy this. I mean this would even enable flexibility in deploying and maintaining your different AI instructions.
Either you host

• all of them in a repo mixing all files in a joint file tree
• all of them in a repo with .github and .claude subfolders and tool-specific configuration within
• each tool-specific configuration in a separate repository <- Is this also supported by your design?

A proper CI/CD setup in such repositories allow even re-use or automatic syncing of certain repository artifacts easily. So either options would be proper and more matter to the architects to take their choice.

Apart from how would you setup a project with IDEasy that automatically gives you preconfigured stuff like say workspaces/main/.github/copilot-instructions.md?

No. They can be much more efficient auto-generated by AI and even in one click.

Also interesting feedback. However, according to my experience also with submodules it is even more painful to sync many redundant git repos and maintain them.

Agree. Maybe my case is more an ad-hoc case, which can anyhow be done manually.

Implementing this feature is less invest for me than having this discussion.

Then let's go ;)

[maybeec]

Here the reference to compare hooks from
Copilot: https://docs.github.com/en/copilot/reference/hooks-configuration#hook-types
Claude: https://code.claude.com/docs/en/hooks

There are even for simple hooks name clashes: UserPromptSubmit <> userPromptSubmitted

[hohwille]

No. They can be much more efficient auto-generated by AI and even in one click.

I disagree on this. The AI config gets more and more important. With its instructions, skills, prompts, hooks, MCP, etc. there can be month of work crafted into this.
To get the most valuable output the AI config is taylored to your project.