@gurupanguji

Bluesky Link Facets 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: Update Bluesky publishing so snippet links become real Bluesky rich-text links, covering both raw URLs and markdown links.

Architecture: Add one narrow Bluesky text-preparation helper that converts authored snippet text into final visible Bluesky text plus non-overlapping UTF-8 byte-indexed link facets. Keep the change local to the Bluesky path in scripts/publish_social.py, and add focused unit tests for parsing, rewriting, and payload construction.

Tech Stack: Python 3, atproto client library, Bluesky rich-text facets, unittest

---

Task 1: Add Failing Tests For Bluesky Text Preparation

Files:

• Create: tests/test_publish_social.py

• Modify: scripts/publish_social.py

• Step 1: Add a raw URL test

Write a test that feeds Bluesky snippet text with a plain canonical URL into a new helper and asserts:

• visible text is unchanged
• one link facet is returned

• facet URI matches the raw URL

• Step 2: Run the single test to verify it fails

Run: python3 -m unittest tests/test_publish_social.py -k raw_url Expected: FAIL because the helper does not exist yet

• Step 3: Add a markdown link test

Write a test that uses [this essay](https://example.com) and asserts:

• visible text becomes this essay
• markdown syntax is removed

• one facet points to https://example.com

• Step 4: Run the markdown-link test to verify it fails

Run: python3 -m unittest tests/test_publish_social.py -k markdown_link Expected: FAIL because the behavior is not implemented yet

Task 2: Implement A Narrow Bluesky Text-To-Facets Helper

Files:

• Modify: scripts/publish_social.py

• Test: tests/test_publish_social.py

• Step 1: Add a helper that rewrites markdown links

Implement a helper that scans snippet text, replaces [label](url) with label, and records the linked span in the final visible text.

• Step 2: Add raw URL detection on the final visible text

Detect plain http or https URLs that remain in the final text after markdown link rewriting.

• Step 3: Compute UTF-8 byte offsets

Convert visible-text character positions into Bluesky byteStart and byteEnd values using UTF-8 encoded prefix lengths.

• Step 4: Reject overlapping facets

Ensure the helper returns only valid non-overlapping facets.

• Step 5: Run the focused helper tests

Run: python3 -m unittest tests/test_publish_social.py Expected: helper tests PASS

Task 3: Cover Punctuation And Unicode Edge Cases

Files:

• Modify: tests/test_publish_social.py

• Modify: scripts/publish_social.py

• Step 1: Add a trailing punctuation test

Write a test for a sentence like:

Read this: https://example.com/path.

Assert that the final facet excludes the trailing period.

• Step 2: Add a unicode offset test

Write a test with non-ASCII text before the linked span, for example an emoji or accented text, and assert the UTF-8 byte offsets match the intended visible span.

• Step 3: Add a mixed-links test

Write a test with one markdown link and one raw URL in the same snippet and assert:

• final visible text is correct
• two facets are returned

• facets do not overlap

• Step 4: Run the full focused test file

Run: python3 -m unittest tests/test_publish_social.py Expected: PASS with edge cases covered

Task 4: Wire The Helper Into Bluesky Publishing

Files:

• Modify: scripts/publish_social.py

• Test: tests/test_publish_social.py

• Step 1: Update publish_bluesky() to prepare rich text

Call the new helper before posting and capture:

• final visible text

• facets

• Step 2: Send the Bluesky post with facets

Update the post creation path so it includes the facets along with the final text and existing image embed.

• Step 3: Add a publish-path test

Mock the Bluesky client boundary lightly and assert the final outgoing post uses:

• rewritten text
• generated facets

• existing embed behavior when an image exists

• Step 4: Run the publish-path test

Run: python3 -m unittest tests/test_publish_social.py -k bluesky Expected: PASS

Task 5: Verify The Social Publisher Still Behaves Cleanly

Files:

• Verify: scripts/publish_social.py

• Verify: tests/test_publish_social.py

• Step 1: Run the new social publisher tests

Run: python3 -m unittest tests/test_publish_social.py Expected: PASS

• Step 2: Re-run the existing validator tests

Run: python3 -m unittest tests/test_validate_posts.py Expected: PASS

• Step 3: Dry-run the social publisher if credentials are not needed

Run: python3 scripts/publish_social.py --help Expected: script loads cleanly and prints usage without syntax or import errors

• Step 4: Review the final diff

Run: git diff --stat Expected: scripts/publish_social.py, tests/test_publish_social.py, and the design and plan docs only

Task 6: Land The Change Set

Files:

• Add: docs/superpowers/specs/2026-03-26-bluesky-link-facets-design.md
• Add: docs/superpowers/plans/2026-03-26-bluesky-link-facets-implementation-plan.md
• Modify: scripts/publish_social.py

• Create: tests/test_publish_social.py

• Step 1: Commit the change set

git add docs/superpowers/specs/2026-03-26-bluesky-link-facets-design.md docs/superpowers/plans/2026-03-26-bluesky-link-facets-implementation-plan.md scripts/publish_social.py tests/test_publish_social.py
git commit -m "feat: add bluesky link facets for social snippets"