ai-integrations AGENTS.md: add processor-behavior verification instructions for doc tasks

[fullsend-ai-retro]

What happened

The code agent produced PR #3859 documenting AIResource entity registration and schema fields. Two major accuracy issues required a fix cycle:

1. Schema table marked fields as "Required" that the processors (AIResourceExtensionsProcessor, AIResourceOciProcessor) don't actually enforce — they only validate spec.scope enum values and oci:// URI format (human review).
2. Claimed UrlReaderProcessor uses backstage.io/source-location for ingestion — this is inaccurate; the annotation is source metadata, not what drives entity ingestion.

The code agent's workspace AGENTS.md mentions checking openspec/changes/ specs but has no instruction to verify behavioral claims against actual processor source code. The fix agent (run) addressed all findings correctly in one iteration, confirming the processor source code is readable and checkable.

What could go better

The code agent wrote documentation about processor behavior without reading the processor source files to verify its claims. The workspaces/ai-integrations/AGENTS.md file directs agents to check openspec/changes/ for specs but doesn't instruct them to cross-reference documentation claims against the actual plugin source code under plugins/catalog-backend-module-*/src/.

This is a high-confidence assessment: the fix agent demonstrated that reading the processor source and correcting the claims was straightforward. The workspace AGENTS.md is the natural place for this guidance because it's already the entry point agents read before working in this workspace.

This complements but does not duplicate #3745 (changeset/doc-update instructions) — that issue covers mechanical PR conventions, not behavioral accuracy verification.

Proposed change

Add a "Documentation Tasks" section to workspaces/ai-integrations/AGENTS.md with instructions like:

## Documentation Tasks

- When documenting processor behavior (validation rules, required fields,
  ingestion behavior, error handling), read the relevant processor source
  files under `plugins/catalog-backend-module-*/src/` to verify claims.
  Do not infer behavior from field names or conventions alone.
- Cross-reference schema field documentation against the actual processor
  code to confirm which fields are validated/enforced vs. merely consumed.
- When writing examples, ensure field values (e.g., `spec.type`,
  `spec.scope`) are consistent with the asset description in the example.

This is repo-specific guidance that complements the platform-level improvements tracked in fullsend-ai/fullsend #3497 and #2199.

Validation criteria

The next 3 documentation PRs in the ai-integrations workspace produced by the code agent should not require human review feedback about inaccurate processor behavior claims. Specifically: documentation about what fields are required/enforced, what processors do, and what side effects they have should match the actual source code.

---

Generated by retro agent from #3859

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 10:34 PM UTC · Completed 10:37 PM UTC
Commit: e168046 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Feature (AGENTS.md enhancement)

Problem

The workspaces/ai-integrations/AGENTS.md currently directs agents to check openspec/changes/ for specs but contains no instructions to verify documentation claims against actual processor source code. This gap caused PR #3859 to ship with inaccurate required-field annotations and incorrect processor behavior descriptions, requiring a fix cycle.

Root Cause

The workspace AGENTS.md has no "Documentation Tasks" guidance. Without explicit instructions, agents infer processor behavior from field names and conventions rather than reading the source files under plugins/catalog-backend-module-*/src/.

Recommended Fix

Add a "Documentation Tasks" section to workspaces/ai-integrations/AGENTS.md with the three instructions proposed in the issue body:

1. Read processor source files to verify behavioral claims
2. Cross-reference schema field docs against processor code for required/enforced vs. consumed
3. Ensure example field values are consistent with descriptions

The proposed markdown content in the issue body is well-formed and ready to apply.

Proposed Test Case

Verification:
- Confirm the new "Documentation Tasks" section exists in workspaces/ai-integrations/AGENTS.md
- Confirm it includes instructions for: source-code verification, schema cross-referencing, and example consistency
- Validate that the section complements (does not duplicate) existing "Specifications" and "PR Conventions" sections
- Longitudinal: the next 3 documentation PRs should not require human feedback about inaccurate processor behavior claims

Relationship to Other Issues

• Add changeset and documentation-update instructions to agent config #3745 (changeset/doc-update instructions): Complementary, not overlapping — Add changeset and documentation-update instructions to agent config #3745 covers mechanical PR conventions while this issue covers behavioral accuracy verification.
• PR docs(#3858): add AIResource examples and registration docs #3859: The triggering PR is merged; the fix cycle there confirmed the proposed guidance would have prevented the inaccuracies.

---

Labels: This issue targets the ai-integrations workspace AGENTS.md file (workspace/ai-integrations), is an enhancement to agent configuration (enhancement, feature), involves documentation guidance (documentation), and is low review effort since the proposed change is a small markdown addition (Review effort 1/5). Adding fullsend label since the issue was filed by the retro agent for agent workflow improvement.