What happened
PR #3225 (Aug 10) fixed a broken appConfigExamples structure (flat baseUrl string instead of nested cluster object) in one metadata file (kserve-kubeflow-connector-backend.yaml), but two sibling metadata files in the same workspace (model-catalog.yaml, techdoc-url-reader.yaml) had the identical broken pattern. Issue #3221 even noted one sibling had the same pattern, but the code agent only fixed the primary file. All three files contribute to the same merged app-config.dynamic-plugins.yaml at deployment time, so any one broken file poisons the merged config. This caused 8 days of continuous smoke test failures (Aug 10–18) until the retro agent caught it via issue #3310, leading to fix PR #3312.
What could go better
The code agent had no repo-specific guidance telling it that metadata files within a workspace share a deployment config namespace and that structural fixes must be applied across all siblings. The general-purpose code agent behavior (agents#129) would help, but repo-specific AGENTS.md guidance is immediately actionable and provides the domain context that metadata files in a workspace are merged at deployment time. Existing issue #3222 covers guidance for NEW plugin additions (validating against upstream config.d.ts), and #3299 covers E2E config variants — but neither addresses the scenario of fixing EXISTING metadata structure across sibling files. Confidence: high — the root cause (incomplete fix) and the fix pattern (check all siblings) are well-established by the PR #3225 → #3312 sequence.
Proposed change
Add a paragraph to the AGENTS.md section "Working with Workspaces" (or as a subsection under the existing overlay/patch guidance) with guidance like:
Fixing appConfigExamples structure: When fixing a structural issue in any metadata/*.yaml file's appConfigExamples (e.g., correcting nesting, fixing schema violations), always check ALL other metadata/*.yaml files in the same workspace for the same pattern. All plugins in a workspace contribute to the merged app-config.dynamic-plugins.yaml at deployment time — a structural bug in any one file can break the entire deployment even if other files are correct. Use grep or equivalent to search for the broken pattern across all metadata files before considering the fix complete.
This is a repo-level fix that does not depend on the agent-layer improvement tracked in fullsend-ai/agents#129.
Validation criteria
The next time a code agent fixes an appConfigExamples structural issue in a workspace metadata file, it should check and fix all metadata/*.yaml files in the same workspace with the same pattern. Verify on the next 3 code agent PRs that touch workspace metadata — the agent should demonstrate awareness of sibling files in its PR description or commit message.
Generated by retro agent from #3312
What happened
PR #3225 (Aug 10) fixed a broken
appConfigExamplesstructure (flatbaseUrlstring instead of nested cluster object) in one metadata file (kserve-kubeflow-connector-backend.yaml), but two sibling metadata files in the same workspace (model-catalog.yaml,techdoc-url-reader.yaml) had the identical broken pattern. Issue #3221 even noted one sibling had the same pattern, but the code agent only fixed the primary file. All three files contribute to the same mergedapp-config.dynamic-plugins.yamlat deployment time, so any one broken file poisons the merged config. This caused 8 days of continuous smoke test failures (Aug 10–18) until the retro agent caught it via issue #3310, leading to fix PR #3312.What could go better
The code agent had no repo-specific guidance telling it that metadata files within a workspace share a deployment config namespace and that structural fixes must be applied across all siblings. The general-purpose code agent behavior (agents#129) would help, but repo-specific AGENTS.md guidance is immediately actionable and provides the domain context that metadata files in a workspace are merged at deployment time. Existing issue #3222 covers guidance for NEW plugin additions (validating against upstream config.d.ts), and #3299 covers E2E config variants — but neither addresses the scenario of fixing EXISTING metadata structure across sibling files. Confidence: high — the root cause (incomplete fix) and the fix pattern (check all siblings) are well-established by the PR #3225 → #3312 sequence.
Proposed change
Add a paragraph to the AGENTS.md section "Working with Workspaces" (or as a subsection under the existing overlay/patch guidance) with guidance like:
This is a repo-level fix that does not depend on the agent-layer improvement tracked in fullsend-ai/agents#129.
Validation criteria
The next time a code agent fixes an appConfigExamples structural issue in a workspace metadata file, it should check and fix all metadata/*.yaml files in the same workspace with the same pattern. Verify on the next 3 code agent PRs that touch workspace metadata — the agent should demonstrate awareness of sibling files in its PR description or commit message.
Generated by retro agent from #3312