project-manager

Track and manage external repos: Learn (study) | Incubate (develop)

Golden Rule

ghq owns the clone → ψ/ owns the symlink

Never copy. Always symlink. One source of truth.

When to Use

Invoke this skill when:

• User shares a GitHub URL and wants to study/clone it

• User mentions wanting to learn from a codebase

• User wants to start developing on an external repo

• Need to find where a previously cloned project lives

Actions

learn [url|slug]

Clone repo for study (read-only reference).

1. Clone via ghq

ghq get -u https://github.com/owner/repo

2. Create org/repo symlink structure

GHQ_ROOT=$(ghq root) mkdir -p ψ/learn/owner ln -sf "$GHQ_ROOT/github.com/owner/repo" ψ/learn/owner/repo

Output: "✓ Linked [repo] to ψ/learn/owner/repo"

incubate [url|slug] [--offload|--contribute|--flash]

Clone repo for active development with optional workflow flags.

Same flow, different target

ghq get -u https://github.com/owner/repo GHQ_ROOT=$(ghq root) mkdir -p ψ/incubate/owner ln -sf "$GHQ_ROOT/github.com/owner/repo" ψ/incubate/owner/repo

Output: "✓ Linked [repo] to ψ/incubate/owner/repo"

Workflow Flags

Flag Scope Duration Cleanup

(none) Long-term dev Weeks/months Manual

--offload

Manual trigger — Remove symlink (keep ghq)

--contribute

Multi-feature Days/weeks Offload when all done (keep ghq for PR feedback)

--flash

Single fix Minutes Issue → PR → offload → purge (one shot)

--offload

Remove symlink after work is done (manual trigger):

unlink ψ/incubate/owner/repo rmdir ψ/incubate/owner 2>/dev/null

ghq clone preserved for future use

--contribute

For multi-feature contributions over days/weeks. Offload when ALL features are done:

1. Work on multiple features/fixes over time

git -C ψ/incubate/owner/repo checkout -b feat/feature-1

... work, commit, push, PR ...

git -C ψ/incubate/owner/repo checkout -b feat/feature-2

... work, commit, push, PR ...

2. When all done, offload (ghq kept for PR feedback)

unlink ψ/incubate/owner/repo

Use case: Extended contribution period. Keep ghq for addressing PR reviews.

--flash

Complete contribution cycle with full cleanup:

/project incubate URL --flash ↓

1. gh issue create → #N (document intent) ↓
2. ghq get → symlink to ψ/incubate/ ↓
3. git checkout -b issue-N-description ↓
4. Make changes, commit ↓
5. git push → gh pr create --body "Closes #N" ↓
6. cd back to main repo ↓
7. Auto-offload + purge ghq clone ↓ "✓ Issue #N → PR #M → Offloaded & Purged"

Use case: Quick external contributions without leaving traces.

find [query]

Search for project across all locations:

Search ghq repos

ghq list | grep -i "query"

Search learn/incubate symlinks (org/repo structure)

find ψ/learn ψ/incubate -type l 2>/dev/null | grep -i "query"

Output: List matches with their ghq paths

list

Show all tracked projects:

echo "📚 Learn" find ψ/learn -type l 2>/dev/null | while read link; do target=$(readlink "$link") echo " ${link#ψ/learn/} → $target" done

echo "🌱 Incubate" find ψ/incubate -type l 2>/dev/null | while read link; do target=$(readlink "$link") echo " ${link#ψ/incubate/} → $target" done

echo "🏠 External (ghq)" ghq list | grep -v "laris-co/Nat-s-Agents" | head -10

Directory Structure

ψ/ ├── learn/owner/repo → ~/Code/github.com/owner/repo (symlink) └── incubate/owner/repo → ~/Code/github.com/owner/repo (symlink)

~/Code/ ← ghq root (source of truth) └── github.com/owner/repo/ (actual clone)

Health Check

When listing, verify symlinks are valid:

Check for broken symlinks

find ψ/learn ψ/incubate -type l ! -exec test -e {} ; -print 2>/dev/null

If broken: ghq get -u [url] to restore source.

Examples

User shares URL to study

User: "I want to learn from https://github.com/SawyerHood/dev-browser" → ghq get -u https://github.com/SawyerHood/dev-browser → mkdir -p ψ/learn/SawyerHood → ln -sf ~/Code/github.com/SawyerHood/dev-browser ψ/learn/SawyerHood/dev-browser

User wants to develop long-term

User: "I want to work on claude-mem" → /project incubate https://github.com/thedotmack/claude-mem → Symlink created, work until done

User wants to contribute (keep ghq for follow-up)

User: "Fix a bug in oracle-v2" → /project incubate https://github.com/Soul-Brews-Studio/oracle-v2 --contribute → [edit, commit, push] → Auto-offload, ghq kept for PR feedback

User wants quick flash contribution (full cleanup)

User: "Quick README fix on oracle-skills-cli" → /project incubate https://github.com/Soul-Brews-Studio/oracle-skills-cli --flash → Issue #17 created → Branch: issue-17-fix-readme → [edit, commit, push] → PR #18 created (Closes #17) → Auto-offload + purge → "✓ Issue #17 → PR #18 → Offloaded & Purged"

Anti-Patterns

❌ Wrong ✅ Right

git clone directly to ψ/ ghq get then symlink

Flat: ψ/learn/repo-name

Org structure: ψ/learn/owner/repo

Copy files Symlink always

Manual clone outside ghq Everything through ghq

Quick Reference

Add to learn

ghq get -u URL && mkdir -p ψ/learn/owner && ln -sf "$(ghq root)/github.com/owner/repo" ψ/learn/owner/repo

Add to incubate

ghq get -u URL && mkdir -p ψ/incubate/owner && ln -sf "$(ghq root)/github.com/owner/repo" ψ/incubate/owner/repo

Offload (remove symlink only)

unlink ψ/incubate/owner/repo && rmdir ψ/incubate/owner 2>/dev/null

Offload + purge (remove symlink AND ghq clone)

unlink ψ/incubate/owner/repo && rm -rf "$(ghq root)/github.com/owner/repo"

Update source

ghq get -u URL

Find repo

ghq list | grep name

Workflow Intensity Scale

incubate → Long-term dev (manual cleanup) ↓ --contribute → Push → offload (keep ghq) ↓ --flash → Issue → Branch → PR → offload → purge (complete cycle)