docs: add Kiro YAML frontmatter step to setup instructions

[Flolight]

Adds a step to the Kiro setup section of the README instructing users to add YAML frontmatter to core-workflow.md after copying it into .kiro/steering/.

Without this frontmatter, Kiro treats the file as auto inclusion and may not load the AI-DLC workflow reliably. This matches how the Cursor setup already handles frontmatter for its .mdc file.

Closes #189

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[leandrodamascena]

Hey @Flolight, thanks for this!

I looked into the Kiro docs and they're actually ambiguous about what happens when there's no frontmatter - the heading says "Always included (default)" but it never explicitly states that files without frontmatter fall back to always. So I can see how this could cause inconsistent behavior in practice.

Either way, adding the frontmatter makes the behavior explicit and predictable, which is the right call. It also brings Kiro in line with how we already handle Cursor's .mdc frontmatter.

LGTM, approving.

[raj-jain-aws]

The inclusion behavior is not guaranteed in Kiro either way. The rules/steering files are meant to be tool agnostic. Adding more and more instructions in README for specific tools adds friction and complexity for users. That's why the global instruction of Using AI-DLC ... was added that's been shown to work most reliably across all tools.

Asking users to patch file locally also creates divergence which creates friction in future pulls. Since this is not really a problem and the solution isn't a guarantee, the proposed change is not really effective solution IMO.

We should add tool-specific packaging instructions systematically that should address this issue in future for other tools as well.

[leandrodamascena]

The inclusion behavior is not guaranteed in Kiro either way. The rules/steering files are meant to be tool agnostic. Adding more and more instructions in README for specific tools adds friction and complexity for users. That's why the global instruction of Using AI-DLC ... was added that's been shown to work most reliably across all tools.

Asking users to patch file locally also creates divergence which creates friction in future pulls. Since this is not really a problem and the solution isn't a guarantee, the proposed change is not really effective solution IMO.

We should add tool-specific packaging instructions systematically that should address this issue in future for other tools as well.

Hey @raj-jain-aws, great points. In my experience, Kiro actually works well without the frontmatter and I've been running AI-DLC with it and haven't had reliability issues, which is why I initially approved this PR.

That said, your point about drift is right. Asking users to patch files locally creates drift that will bite them on future updates, and it goes against the tool-agnostic principle of the rules/steering files. In this case, we already have a consistency issue: the Cursor setup already does exactly this because it says to creates an .mdc file with alwaysApply: true frontmatter. So if we reject this approach for Kiro, we should also remove it from Cursor to stay consistent.

I agree the right path forward is to remove tool-specific frontmatter patches from all setup instructions and work toward a systematic packaging solution that handles this per tool. What do you think?

[raj-jain-aws]

The inclusion behavior is not guaranteed in Kiro either way. The rules/steering files are meant to be tool agnostic. Adding more and more instructions in README for specific tools adds friction and complexity for users. That's why the global instruction of Using AI-DLC ... was added that's been shown to work most reliably across all tools.
Asking users to patch file locally also creates divergence which creates friction in future pulls. Since this is not really a problem and the solution isn't a guarantee, the proposed change is not really effective solution IMO.
We should add tool-specific packaging instructions systematically that should address this issue in future for other tools as well.

Hey @raj-jain-aws, great points. In my experience, Kiro actually works well without the frontmatter and I've been running AI-DLC with it and haven't had reliability issues, which is why I initially approved this PR.

That said, your point about drift is right. Asking users to patch files locally creates drift that will bite them on future updates, and it goes against the tool-agnostic principle of the rules/steering files. In this case, we already have a consistency issue: the Cursor setup already does exactly this because it says to creates an .mdc file with alwaysApply: true frontmatter. So if we reject this approach for Kiro, we should also remove it from Cursor to stay consistent.

I agree the right path forward is to remove tool-specific frontmatter patches from all setup instructions and work toward a systematic packaging solution that handles this per tool. What do you think?

Yes @leandrodamascena, we've bit of a consistency issue there with Cursor. Not sure if it was necessary for Cursor. I think we should leave it as it is for now so we don't risk breaking something and not let the problem grow further.

[leandrodamascena]

Yes @leandrodamascena, we've bit of a consistency issue there with Cursor. Not sure if it was necessary for Cursor. I think we should leave it as it is for now so we don't risk breaking something and not let the problem grow further.

Yep, lets keep this for now @raj-jain-aws.

We should add tool-specific packaging instructions systematically that should address this issue in future for other tools as well.

So, we agree that the right direction is to work on the specific aspects (tool-specific) of the packaging and close this PR for now, right?

[raj-jain-aws]

Yes @leandrodamascena, we've bit of a consistency issue there with Cursor. Not sure if it was necessary for Cursor. I think we should leave it as it is for now so we don't risk breaking something and not let the problem grow further.

Yep, lets keep this for now @raj-jain-aws.

We should add tool-specific packaging instructions systematically that should address this issue in future for other tools as well.

So, we agree that the right direction is to work on the specific aspects (tool-specific) of the packaging and close this PR for now, right?

Yes, the PR's input is well received and it'll inform our tool specific packaging design, but it should be closed for the current version.

[leandrodamascena]

Hey @Flolight, first of all, thank you so much for taking the time to contribute and improve AI-DLC, I really appreciate it.

After discussing this with @raj-jain-aws, we've concluded to close this PR for now. The core issue is that the rules/steering files are meant to be tool-agnostic, and asking users to patch files locally with tool-specific frontmatter creates drift because when we release updates to core-workflow.md (it can happen oftne), users who added frontmatter will have to manually merge or risk losing it.

I'm going to close this PR for now, but please don't let this discourage you from contributing - feedback like this helps us improve the project.

Thanks.