uselink-share-spec

name	uselink-share-spec
description	Publish a planning spec or plan to uselink so stakeholders can read it without repo access. Use when the user says 'share spec', 'publish the plan', 'send this spec to PM', or wants a shareable link for a .planning artifact.
allowed-tools	["Bash","Read","Glob"]

Share Spec via Uselink

Publish specs and plans from .planning/ to uselink so PMs, stakeholders, and business people can read them without cloning the repo.

When to Use

• User wants to share a spec or plan with someone outside the repo
• User says "share the versioning spec" or "publish the analytics plan"
• User wants a link to send a stakeholder for review

Prerequisites

Check CLI installed and configured before anything else:

which uselink || echo "MISSING"
test -f ~/.uselink/config.json && echo "OK" || echo "NO_CONFIG"

If uselink is missing, tell the user to install it. If config is missing, tell them to run uselink login.

Workflow

1. Find the artifact

Scan both directories:

ls .planning/specs/*.md .planning/plans/*.md 2>/dev/null

If the user gave a name (e.g. "versioning"), fuzzy-match against filenames. If multiple files match, list them and ask which one. If zero match, ask for the path.

2. Clean the title

Strip prefixes and convert to human-readable Title Case:

Filename	Title
done_04_publishing.md	Publishing
10_versioning.md	Versioning
billing-hardening.md	Billing Hardening
spec-11-polish-v2.md	Polish V2

Rules: drop done_ prefix, drop leading number + underscore (04_), drop spec-NN- prefix, convert kebab/snake to spaces, Title Case the result.

3. Publish

uselink publish <file> --title "<clean title>"

Capture the URL from stdout.

4. Return the URL

Report the published URL to the user. If the file was a done_* spec, mention it was a completed spec.

Gotchas

• done_ prefix means the spec is implemented, not that it shouldn't be shared. Stakeholders often want to review completed specs for reference or onboarding. Publish it normally but mention the spec is marked as done.
• The CLI config file path is ~/.uselink/config.json, not ~/.config/uselink/. If the user says "I already logged in" but the config check fails, they may have installed a different version or the config landed in the wrong directory. Check both paths before giving up.
• Glob for .md only -- .planning/ also contains .html files (like the PRD). The uselink CLI handles HTML too, but the title-cleaning logic assumes markdown naming conventions. If the user asks to share an HTML file, skip the title cleaning and use the filename as-is.
• Some plans have no number prefix (e.g. public-profile.md, billing-hardening.md). The title cleaner must handle both numbered (10_versioning.md) and unnumbered (billing-hardening.md) filenames without mangling either.