The visible feature was only the surface
A page can look correct in a browser while link-card crawlers see missing/client-only metadata, an inaccessible/small image, or stale platform cache.
The system also had to respect concrete constraints. Proprietary social platforms' selection and cache algorithms cannot be simulated or controlled. Metadata must be crawler-visible and image URLs remotely reachable. Only PNG, JPEG, and supported WebP encodings yield deterministic dimension checks.
My role covered agent workflow design and automation engineering, with responsibility for agent workflow, validation automation, and packaging.
I turned the constraints into boundaries
Repository/framework inspection and standards; deterministic HTML/image checker with 0/1/2 exit contract; preserve/repair/create workflow followed by local and deployed verification.
Separate implementation eligibility from platform cache symptoms.
Preserve valid metadata and make the smallest framework-native repair.
Standardize new preview assets at 1200×630 while verifying bytes/type/dimensions rather than trusting file extensions.
The key decision: Separate implementation eligibility from platform cache symptoms.
The implementation had to prove the model
I delivered the work across the full path: Built raw HTML/meta/image response auditing. Implemented raster dimension validation and explicit exit codes. Codified framework patterns and a social-preview standard. Added installer, checker, and package-contract tests.
The result is concrete: Agents can diagnose missing versus cached cards. Repair incomplete/relative/client-only metadata. Create a branded large-image asset when needed. Verify local implementation and deployed crawler eligibility without promising a platform-specific layout.
The senior engineering lesson was that solving the visible workflow is only half the job. The architecture must also make constraints, failure modes, evidence, and ownership explicit enough for the next change to remain safe.