Add AGENTS.md guidance: code agent must verify all plugin versions against upstream ref on workspace updates

[fullsend-ai-retro]

What happened

On PR #3293, the code agent (run 32087179159) updated source.json to upstream commit 0a6959a and bumped metadata for 3 plugins as listed in issue #3290. However, the new upstream ref encompassed version changes for 6 plugins total — 3 intermediate plugins (ai-model-server 0.2.0→0.3.0, ai-resource-agent 0.2.1→0.4.0, ai-resource-extensions 0.4.0→0.5.0) were bumped in earlier Version Packages commits (44a5e4c, fc8ce3b) between the old and new refs. The human maintainer had to push 2 fix commits (0196e16, 33506b9) to correct the missing metadata, and the first /publish (run 32139842536) failed due to the version mismatch before the fixes were complete.

What could go better

The code agent faithfully implemented the issue specification, which only listed 3 plugins. The issue was manually created and did not account for intermediate version bumps between the old and new upstream refs. Existing issue #3032 proposes a workspace update procedure focused on supportedVersions/OCI tag alignment with versions.json, but does not address the completeness question: how to determine which plugins need updating. The code agent needs guidance to independently verify that ALL metadata versions in the workspace match the upstream source at the target ref, rather than relying solely on the issue description to enumerate which plugins changed. Confidence: high — the metadata validation gate is deterministic, and this same class of error (incomplete metadata updates) has occurred on prior PRs (#2896 per issue #2970, #3013 per issue #3032).

Proposed change

Add a step to the workspace update procedure in AGENTS.md (complementing the procedure proposed in #3032). After updating source.json, the code agent should:

1. Read plugins-list.yaml to enumerate all plugins exported from this workspace.
2. For each plugin, check the upstream package.json at the new repo-ref to get the actual version.
3. Compare against the corresponding metadata/*.yaml file's spec.version.
4. Update any metadata file where the version differs — bumping spec.version, spec.dynamicArtifact OCI tag, and any other version-dependent fields.

Example AGENTS.md text:

### Verifying metadata completeness on workspace updates
When updating `source.json` to a new upstream ref, do not rely solely on the
issue description to determine which plugins need metadata updates. The upstream
ref may encompass version changes across multiple intermediate commits.
Enumerate all plugins in `plugins-list.yaml`, check each plugin's `package.json`
at the new ref for its current version, and update any `metadata/*.yaml` file
where `spec.version` or the OCI tag no longer matches.

Validation criteria

The next 3 workspace version update PRs created by the code agent should include metadata updates for ALL plugins whose versions changed between the old and new upstream refs — not just the ones explicitly listed in the issue. Verify by checking that no /publish run fails with metadata version mismatch errors, and that no human fix commits are needed to add missing metadata updates.

---

Generated by retro agent from #3293

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 1:40 PM UTC · Completed 1:44 PM UTC

Commit: f9ae0fa · View workflow run →

[fullsend-ai-triage]

This is a well-scoped documentation change with a clear failure pattern and proposed fix text.

Related open issues:

• Add workspace update implementation procedure to AGENTS.md for code agent #3032 — Proposes the broader workspace update procedure in AGENTS.md (supportedVersions/OCI tag alignment with versions.json). This issue's guidance is complementary and can be added as a standalone subsection or integrated into Add workspace update implementation procedure to AGENTS.md for code agent #3032's procedure when it lands.
• Add AGENTS.md guidance that metadata version/OCI tag mismatches block /publish #2970 — Review-time guidance for metadata version/OCI tag mismatches (catches the problem at review rather than preventing it at implementation time).

Implementation note: The proposed text references checking upstream package.json at the new repo-ref. For flat repos (repo-flat: true in source.json), the package.json path differs from workspace-structured repos — the guidance should account for both layouts or reference existing path resolution logic.

Proposed test case:

Validation: On the next 3 workspace version update PRs:
1. Identify all plugins in plugins-list.yaml for the updated workspace
2. For each plugin, compare metadata/*.yaml spec.version against
   the plugin's package.json version at the new source.json repo-ref
3. Confirm all versions match (no stale metadata)
4. Confirm /publish succeeds without human fix commits

---

Labels: This is a documentation change to AGENTS.md. The 'documentation' label matches the category. The 'ready-to-code' label is appropriate because the issue has a concrete proposed change with example text, clear scope, and no open questions.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 1:45 PM UTC · Completed 1:49 PM UTC

Commit: f9ae0fa · View workflow run →