share-docs

Share Documents

Promote personal documents to the shared namespace for team collaboration. This skill handles numbering, frontmatter updates, and git operations atomically.

When to Use

• When a research document is complete and ready for team review
• When a plan is finalized and ready for team implementation
• When you want to publish your work to collaborators

Workflow

1. Validate Personal Document

Check that the personal document exists and is ready to share:

• Path format: thoughts/{username}/NNNN-slug/
• Contains required files (research.md, plan.md, etc.)
• Frontmatter is complete
• No shared_as field yet (not already shared)

2. Pull Latest Changes

git pull

Get latest shared documents to determine next available number.

3. Find Next Shared Number

Scan thoughts/shared/ for highest number:

NEXT_SHARED=$(ls -1 thoughts/shared/ 2>/dev/null | grep -E '^[0-9]{4}-' | sort -r | head -1 | cut -d'-' -f1 || echo "0000")
NEXT_SHARED=$(printf "%04d" $((10#${NEXT_SHARED} + 1)))

4. Copy to Shared

Copy entire personal directory to shared with new number:

# Example: thoughts/erik/0001-auth-system → thoughts/shared/0042-auth-system
cp -r thoughts/{username}/{NNNN}-{slug} thoughts/shared/${NEXT_SHARED}-{slug}

5. Update Frontmatter in Both Copies

Personal copy (thoughts/erik/0001-auth-system/research.md):

---
feature_slug: "erik/0001-auth-system"
shared_as: "0042-auth-system"
shared_date: "2026-02-04"
status: shared
# ... other fields unchanged
---

Shared copy (thoughts/shared/0042-auth-system/research.md):

---
feature_slug: "0042-auth-system"
original_slug: "erik/0001-auth-system"
shared_date: "2026-02-04"
status: published
# ... other fields unchanged
---

Update frontmatter in all markdown files within both directories (research.md, plan.md, changelog.md, etc.).

6. Commit and Push

Atomic operation to claim the shared number:

git add thoughts/shared/${NEXT_SHARED}-${slug} thoughts/${username}/${NNNN}-${slug}
git commit -m "feat: share ${slug} (was ${username}/${NNNN})"
git push