Reference vs definition

[MartinMalinda]

Hi @AshishKumar4

I understand the difference between reference and definition. But practically, for me it's easier to just put the entire template to the definition.

It seems like the vibesdk first loads the reference and includes it as is. The definition is then added in second step - but via LLM, reading it and writing it, if I understand it right.

For me, it's more convenient to put all the code in a reference and just have more references, if needed. It means some duplication but I can live with that.

The code is all pulled in in the first step and all the template code is together and I can cd there and npm run dev to develop it, which would otherwise be complicated if it's split into two places.

Am I losing anything significant if I go for this strategy?

[AshishKumar4]

It seems like the vibesdk first loads the reference and includes it as is. The definition is then added in second step - but via LLM, reading it and writing it, if I understand it right.

Not really. The generate_templates.py and deploy_templates.sh which calls it are called at the time of deployment - when either you are deploying the templates fresh via CI/CD of this repo, or when you are deploying vibesdk where the deploy script pulls the latest templates repo and makes the deployment.

The final templates are generated at the time of deployment itself, into a build folder, and pushed to R2. Now, I do understand that working on definitions and references separately is hard and unintuitive and also easy to mess things up if not being super careful. That's why, whenever I am not personally making any changes to the templates and instead using an AI assistant that I can't trust to write good code, I always ask it to operate directly on the final 'built' version of the template in the 'build' folder, OR copy paste a built template and make it a new one. Then, I manually copy over all the diffs over to either the reference (if needed) or the definition myself. This is also how I debug for bugs or test/verify if a template is good or not.

The reference/definitions separation was done for deduplication only - it was getting really hard making sure I do all the bug fixes across all the templates consistently, hence made this system. The only thing you would run into is the exact same problem I ran into due to duplication of code

[MartinMalinda]

I see - what I've experienced locally before is that I could see the reference files right away during the "initializing boilerplate" but the definition files I would see only later during an AI code generation step. But there's a chance its some mishap on my side.

Totally get the code duplication issue. I haven't made that many variations so I haven't experienced that too much. Thanks for the info! So far it seems better to just use references and I'd split the code only in case it's getting out of hand. But I might also try rebasing the templates on top of each other, if they live in different repos.