Feature‑Card Automation: A 90‑Minute Repo→JSON‑LD Sprint to Keep Feature Metadata Fresh

Product teams ship features from code, but the surface systems that need feature metadata (marketing pages, product directories, in‑app help, search engines, and AI indexers) often rely on stale manual entries. A repo‑first approach keeps the canonical record inside the thing you already change: the feature commit and its files.

By baking structured metadata into the repo and producing JSON‑LD automatically at CI time, you create one source of truth that powers human pages and machine consumers (search, assistants, internal catalogs). Use schema.org types like SoftwareApplication or CreativeWork as the base vocabulary so external parsers have a standard interpretation. See schema.org and Google's SoftwareApplication guidance for fields search engines consume.

This sprint focuses on four deliverables you can implement in an hour and a half: (1) a feature metadata template file, (2) a commit convention and semantic ID pattern, (3) a small CI job to validate and build JSON‑LD, and (4) changelog automation to capture the human narrative.

Keep the feature metadata file intentionally small and human‑editable — a single YAML or JSON file per feature in a directory like /features/*.yaml. Use semantic IDs that are stable and URLable (for example: feature:auth/passwordless → feature-auth-passwordless). Commit messages should follow a lightweight conventional‑commits style (feat(scope): short subject) so automation can classify entries for changelog generation.

Feature metadata template (YAML). Save as /features/feature-<id>.yaml. Keep fields minimal: id, title, summary, author, dateIntroduced, status, tags, and optional changelog entry. A tiny example will be easier for engineers to adopt than a large schema-heavy file.

Validation and build: add a GitHub Action that runs on pushes to main and on pull requests. Steps: (1) run a JSON Schema validator against the feature files, (2) generate JSON‑LD from the validated YAML/JSON (use a small Node/Python script or an action), and (3) commit or publish the generated bundle to your website (or to a dedicated branch/artifact). Use an off‑the‑shelf JSON schema validator action to keep the CI concise.

Automated changelogs are valuable but noisy if they include every small commit. Use Conventional Commits and either a conservative changelog tool or a curated step. Tools inspired by Keep a Changelog and Common Changelog conventions give you a human‑readable CHANGELOG.md while your CI can still emit raw entries for machine consumption.

Semantic IDs should be deterministic and collision‑resistant: prefer a normalized slug of the feature title prefixed with a domain‑safe namespace (for example appwispr:feature:auth-passwordless). Record creation date and source commit SHA in the generated JSON‑LD to make rollbacks and audits straightforward.

Treat the generated JSON‑LD as a build artifact, not the canonical source. That means rollbacks are a matter of reverting the feature metadata file or the commit that introduced it. Keep the generated bundle in a commitable artifact location (CI can open a PR or push to a branch) so normal git tooling handles rollbacks.

For maintenance, add schema validation to protect consumers from accidental breaking changes, and schedule a quarterly check to reconcile feature files with live product state. Also include lightweight tests that assert required fields exist for every feature file to catch omissions early in CI.