@gurupanguji

Auto-Convert Media Links 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: Normalize supported standalone media links in staged blog posts before commit and enforce the same shape through the shared validator path.

Architecture: Add a new scripts/normalize_post_media_links.py transformer that rewrites standalone YouTube, Twitter/X, and generic bare URL lines in _posts/*.md. Reuse embed rendering from the existing WordPress embed normalizer, call the transformer from the tracked hooks/pre-commit template, and extend the shared validator to catch any leftover supported lines for posts on or after the rollout date.

Tech Stack: Python 3, unittest, git hooks, existing repository scripts

---

Task 1: Add failing transformer tests

Files:

• Create: tests/test_normalize_post_media_links.py

• Step 1: Write failing tests for standalone YouTube, Twitter/X, and generic URL conversion
• Step 2: Write failing tests for ignored contexts such as inline prose, code, markdown links, and HTML
• Step 3: Run python3 -m unittest tests/test_normalize_post_media_links.py and verify the new tests fail for the missing module or behavior

Task 2: Implement the media-link transformer

Files:

• Create: scripts/normalize_post_media_links.py

• Modify: scripts/normalize_wp_embeds.py

• Step 1: Extract any reusable embed helpers needed by the new transformer without changing current embed behavior
• Step 2: Implement scanning and rewriting for standalone YouTube, Twitter/X, and generic URL lines
• Step 3: Implement CLI support for explicit paths, staged paths, and write mode
• Step 4: Run python3 -m unittest tests/test_normalize_post_media_links.py tests/test_normalize_wp_embeds.py and verify the new tests pass

Task 3: Add failing validator tests

Files:

• Modify: tests/test_validate_posts.py

• Step 1: Add failing tests for leftover standalone YouTube, Twitter/X, and generic URL lines
• Step 2: Add passing tests for converted iframe and wrapped markdown links
• Step 3: Run python3 -m unittest tests/test_validate_posts.py and verify the new tests fail before validator changes

Task 4: Extend validator and pre-commit hook

Files:

• Modify: scripts/validate_posts.py

• Modify: hooks/pre-commit

• Step 1: Add a shared detection helper for leftover standalone supported media lines
• Step 2: Fail validation with actionable file and line errors
• Step 3: Run the new transformer from pre-commit on staged posts and re-stage changed files
• Step 4: Run python3 -m unittest tests/test_validate_posts.py tests/test_normalize_post_media_links.py tests/test_normalize_wp_embeds.py and verify all pass

Task 5: Full verification and handoff

Files:

• Modify: docs/superpowers/specs/2026-03-27-auto-convert-media-links-design.md

• Modify: docs/superpowers/plans/2026-03-27-auto-convert-media-links-implementation-plan.md

• Step 1: Run targeted script verification against representative sample posts
• Step 2: Run python3 scripts/validate_posts.py --today "$(date +%F)" and verify repository validation still passes
• Step 3: Stage all changes and commit with an issue-linked message
• Step 4: Push the branch and open a PR that closes #105