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

Important: If push fails due to conflict (someone else pushed a shared doc), retry from step 2.

7. Report Result

✅ Shared ${username}/${NNNN}-${slug} → shared/${NEXT_SHARED}-${slug}

Personal copy marked with shared_as in frontmatter.
Collaborators can now access: thoughts/shared/${NEXT_SHARED}-${slug}/

Error Handling

Personal doc doesn't exist:

❌ Error: thoughts/erik/0001-auth-system not found

Already shared:

❌ Error: Document already shared as 0042-auth-system (check frontmatter)
Consider creating a new version if updates are needed.

Git push conflict:

⚠️  Push rejected - shared number conflict detected
Retrying with next available number...

Automatically retry from step 2 (pull, find next number, copy, commit, push).

Example Usage

# User has: thoughts/erik/0001-auth-system/research.md
# User runs: /share-docs thoughts/erik/0001-auth-system

# Skill executes:
git pull
# Finds next shared: 0042
cp -r thoughts/erik/0001-auth-system thoughts/shared/0042-auth-system
# Updates frontmatter in both
git add thoughts/shared/0042-auth-system thoughts/erik/0001-auth-system
git commit -m "feat: share auth-system (was erik/0001)"
git push

# Result:
# ✅ Shared erik/0001-auth-system → shared/0042-auth-system

Collaboration Model

Personal namespace (thoughts/{username}/):

• Each developer has their own numbering (0001, 0002, etc.)
• No conflicts between developers
• Work-in-progress, experimentation, drafts
• Not visible to others until shared

Shared namespace (thoughts/shared/):

• Canonical numbered documents for team
• Numbers assigned atomically at share time
• Published, reviewed, ready for implementation
• Visible to all collaborators

Benefits:

• No numbering conflicts during development
• Explicit sharing moment
• Clear distinction between WIP and published
• Git handles conflicts automatically

After Sharing

Personal copy remains unchanged except for frontmatter. You can:

• Keep it as reference
• Continue working on improvements
• Share updates as a new document (new shared number)
• Delete it if no longer needed

The shared copy becomes the canonical version that others reference.