@gurupanguji

Provider Embed Expansion Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Resolve issue #121 by unifying standalone URL normalization across YouTube, X or Twitter, Mastodon, Bluesky, and Threads so all supported providers follow the same embed-or-markdown-fallback contract.

Architecture: Extend the existing scripts/normalize_post_media_links.py and scripts/validate_posts.py paths instead of creating a new parallel normalizer. Keep detection narrow: standalone supported provider URLs on their own line are eligible for official embeds, while provider URLs inside prose normalize only to [url](url). Successful embeds commit with repo-owned provider wrappers plus a *Source:* [Platform](URL) line that preserves the original authored URL. Provider fetch failures degrade to plain markdown links with logged reasons and must still pass validation.

Tech Stack: Python 3, unittest, git hooks, provider embed endpoints, Jekyll markdown content, _layouts/post.html inline post styling

---

Task 1: Capture The Unified Provider Contract In Tests

Files:

• Modify: tests/test_normalize_post_media_links.py

• Step 1: Add failing tests for standalone successful embed conversion across all supported providers

Cover:

• YouTube watch URL
• YouTube youtu.be share URL with ?si=...
• X or Twitter status URL
• Mastodon post URL
• Bluesky post URL

• Threads post URL

• Step 2: Add failing tests for provider-specific fallback behavior

Cover:

• provider embed fetch failure returns [url](url)
• failure reason is surfaced in script reporting

• no *Source:* line is emitted for markdown fallback

• Step 3: Add failing tests for prose handling

Cover:

• provider URL inside prose normalizes only to [url](url)

• no embed expansion happens in prose paragraphs

• Step 4: Run the focused normalizer tests and confirm they fail first

Run:

python3 -m unittest tests/test_normalize_post_media_links.py

Expected: FAIL for the new unified-provider behaviors before implementation.

Task 2: Refactor The Normalizer Around Supported Providers

Files:

• Modify: scripts/normalize_post_media_links.py

• Modify: scripts/normalize_wp_embeds.py

• Step 1: Extract or add shared provider classification helpers

Make the classifier distinguish:

• standalone supported provider URL
• prose provider URL

• generic unsupported URL

• Step 2: Normalize YouTube and X or Twitter to the new shared contract

Update existing behavior so:

• successful output uses repo-owned provider wrapper plus *Source:* [Platform](URL)
• YouTube source line preserves the original authored URL
• YouTube watch and youtu.be share links normalize to the same canonical embed payload

• X or Twitter follows the same embed-or-markdown-fallback rule as the newer providers

• Step 3: Add Mastodon, Bluesky, and Threads provider paths

For each provider:

• detect standalone URL shape
• fetch or derive official embed payload
• wrap it in the provider-specific repo wrapper
• emit the correct *Source:* [Platform](URL) line

• fall back to [url](url) with a logged reason on failure

• Step 4: Add prose-only URL normalization for supported providers

When a supported provider URL appears in prose:

• do not expand into an embed

• normalize only to [url](url)

• Step 5: Preserve idempotence and existing skip boundaries

Do not rewrite:

• existing markdown links
• existing embed HTML
• fenced code
• inline code

• blockquotes unless later policy changes say otherwise

• Step 6: Run the focused normalizer tests

Run:

python3 -m unittest tests/test_normalize_post_media_links.py tests/test_normalize_wp_embeds.py

Expected: PASS

Task 3: Add Shared Wrapper Styling In The Post Layout

Files:

• Modify: _layouts/post.html

• Step 1: Add or align provider-specific wrapper styles

Add styling hooks for:

• .post-content .gp-youtube-embed
• .post-content .gp-x-embed
• .post-content .gp-mastodon-embed
• .post-content .gp-bluesky-embed

• .post-content .gp-threads-embed

• Step 2: Ensure wrappers are centered and responsive

Verify the layout rules:

• center embed containers within the article body
• constrain width sensibly on desktop

• avoid overflow on mobile

• Step 3: Preserve current post-body style ownership

Keep these rules in _layouts/post.html because that file already owns embed presentation. Do not split this styling into a second CSS surface during this issue.

Task 4: Update Validator Rules To Match The New Contract

Files:

• Modify: tests/test_validate_posts.py

• Modify: scripts/validate_posts.py

• Step 1: Add failing validator tests for valid end states

Cover:

• successful wrapped embed plus source line passes
• markdown fallback link passes

• prose-normalized [url](url) passes

• Step 2: Add failing validator tests for invalid leftover states

Cover:

• leftover raw standalone supported provider URL fails

• stale old-shape YouTube or X output that no longer matches the unified contract fails if the policy window applies

• Step 3: Implement validator recognition for the two allowed provider outcomes

Validator should accept:

• official embed plus source line
• markdown-link fallback

Validator should reject:

• leftover raw standalone supported provider URLs

• Step 4: Run focused validator and normalizer tests

Run:

python3 -m unittest tests/test_validate_posts.py tests/test_normalize_post_media_links.py tests/test_normalize_wp_embeds.py

Expected: PASS

Task 5: Wire The Pre-Commit Path To The Unified Provider Policy

Files:

• Modify: hooks/pre-commit

• Step 1: Confirm the hook still runs the shared normalizer on staged posts

Keep the existing hook architecture. Do not invent a second provider-specific pre-commit entrypoint.

• Step 2: Verify restaging behavior still works after rewrites

The hook should:

• normalize staged post files
• re-stage changed files

• continue through validation

• Step 3: Confirm the hook tolerates markdown fallback cases

A provider fetch failure should not block commit if the staged file now contains the accepted markdown-link fallback.

Task 6: Verify Real-World Samples Before Repository-Wide Adoption

Files:

• Verify: representative posts in _posts/

• Step 1: Build a small representative sample set

Include at least:

• one YouTube watch URL example
• one YouTube youtu.be share URL example
• one X or Twitter status example
• one Mastodon example
• one Bluesky example
• one Threads example

• one prose paragraph example with a supported provider URL

• Step 2: Run the normalizer against only those samples first

Use explicit-path or fixture-driven checks before broad rollout.

• Step 3: Review resulting body shapes manually

Confirm:

• successful embeds use the right wrapper
• source lines preserve original authored URLs
• prose URLs become [url](url)
• failed embeds degrade cleanly to markdown links

Task 7: Full Verification And Handoff

Files:

• Modify: docs/superpowers/specs/2026-03-27-provider-embed-expansion-design.md

• Modify: docs/superpowers/plans/2026-03-27-provider-embed-expansion-implementation-plan.md

• Step 1: Run the full focused test suite

Run:

python3 -m unittest tests/test_normalize_post_media_links.py tests/test_normalize_wp_embeds.py tests/test_validate_posts.py

Expected: PASS

• Step 2: Run repository validation

Run:

python3 scripts/validate_posts.py --today "$(date +%F)"

Expected: PASS

• Step 3: Spot-check one rendered example per provider in local preview

Confirm:

• centering
• responsiveness
• readable source lines

• acceptable markdown fallback shape

• Step 4: Stage all changes and commit with an issue-linked message

Use a commit message tied to #121.

• Step 5: Push the branch and open a PR that closes #121

The PR body should call out that this branch also aligns the older YouTube and X or Twitter behavior with the new shared provider contract instead of leaving them on legacy rules.