@gurupanguji

Portable Post-Body Contract 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 #122 by landing the approved post-body contract as the repository’s source of truth and explicitly tying the implementation boundary to the follow-up issues that will do the actual code and archive work.

Architecture: Keep this branch narrow and docs-first. The work for #122 is to publish the canonical contract, link it cleanly to the dependent issues, and verify that the issue split is explicit enough that later implementation branches can execute without re-litigating policy. Do not implement embed normalization, validation, or archive rewrites here. Those belong to #121, #124, #125, and #126.

Tech Stack: Markdown docs, GitHub issues, git, existing docs/superpowers/specs/ and docs/superpowers/plans/ conventions

---

Task 1: Finalize The Contract Spec

Files:

• Modify: docs/superpowers/specs/2026-03-27-portable-post-body-contract-design.md

• Step 1: Re-read the approved contract and compare it against the written spec

Check that the spec still matches the approved decisions exactly:

• _posts/ stays canonical with front matter
• markdown-first body policy
• supported embed providers
• image and caption rules
• source-line format

• unsupported URL boundary

• Step 2: Tighten any wording that accidentally leaks into child-issue scope

Remove or sharpen any wording that sounds like this branch will implement:

• Mastodon, Bluesky, or Threads normalization
• hook automation
• validator rollout
• archive rewrites

• metadata inference

• Step 3: Verify the spec names the dependent issues explicitly

Make sure the spec points to:

• #121
• #124
• #125
• #126

Expected result: the contract doc is clearly the policy source of truth and not a hidden implementation branch.

Task 2: Write The Issue-Tie Plan In Repository Form

Files:

• Create: docs/superpowers/plans/2026-03-27-portable-post-body-contract-implementation-plan.md

• Step 1: Document what #122 resolves by itself

Spell out that #122 closes when:

• the contract spec is written
• the issue split is explicit

• downstream issues can implement without re-deciding policy

• Step 2: Document what #122 does not resolve

List the out-of-scope implementation work and point each one to its issue:

• provider expansion goes to #121
• unsupported bare URL cleanup goes to #124
• front matter burden reduction goes to #125

• hook and validator automation goes to #126

• Step 3: Save the plan with the standard plan header and task breakdown

Expected result: the repository has both the contract spec and a concrete handoff plan that preserves issue boundaries.

Task 3: Tie The GitHub Issues Together Explicitly

Files:

• Modify: GitHub issue #122

• Modify: GitHub issues #121, #124, #125, #126

• Step 1: Add a comment on #122 linking the approved spec and the child issues

The comment should state that #122 is the contract issue and link:

• the spec path
• the implementation plan path

• the dependent issues

• Step 2: Add short cross-link comments on #121, #124, #125, and #126

Each child issue should say it depends on the contract defined in #122 and link the spec file path for reference.

• Step 3: Verify the issue graph reads cleanly in GitHub

Manual check:

• #122 reads as the policy parent
• child issues read as implementation work
• there is no ambiguity about which branch should do which work

Expected result: future execution can start from the child issues without reopening policy debate.

Task 4: Verify The Repository State For A Docs-Only Resolution

Files:

• Verify: docs/superpowers/specs/2026-03-27-portable-post-body-contract-design.md

• Verify: docs/superpowers/plans/2026-03-27-portable-post-body-contract-implementation-plan.md

• Step 1: Run a focused diff review

Run:

git diff -- docs/superpowers/specs/2026-03-27-portable-post-body-contract-design.md docs/superpowers/plans/2026-03-27-portable-post-body-contract-implementation-plan.md

Expected: only docs changes relevant to #122

• Step 2: Confirm branch status is clean apart from the intended docs changes

Run:

git status --short

Expected: only the spec and plan docs are modified or staged for this issue

• Step 3: Optional sanity check against adjacent specs and plans

Open nearby docs in docs/superpowers/specs/ and docs/superpowers/plans/ to ensure formatting and naming stay consistent with the repo’s existing pattern.

Task 5: Commit, Push, And Open The Docs PR For #122

Files:

• Modify: docs/superpowers/specs/2026-03-27-portable-post-body-contract-design.md

• Create: docs/superpowers/plans/2026-03-27-portable-post-body-contract-implementation-plan.md

• Step 1: Stage the plan and any final spec edits

Run:

git add docs/superpowers/specs/2026-03-27-portable-post-body-contract-design.md docs/superpowers/plans/2026-03-27-portable-post-body-contract-implementation-plan.md

• Step 2: Commit with an issue-linked docs message

Run:

git commit -m "docs: define portable post-body contract"

Expected: commit contains only #122 docs and issue-tying updates

• Step 3: Push the branch and open a PR that closes #122

The PR body should:

• link the spec
• link the implementation plan

• list #121, #124, #125, and #126 as follow-up execution issues

• Step 4: Leave the child issues open

Expected: #122 closes as the resolved contract issue, while the child issues remain the active execution queue in the prescribed order.