project

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

Step 0 — Anchor (date-stamp + root)

date "+🕐 %H:%M %Z (%A %d %B %Y)"

# Find oracle root — git toplevel that has CLAUDE.md + ψ/
ORACLE_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
if [ -n "$ORACLE_ROOT" ] && [ -f "$ORACLE_ROOT/CLAUDE.md" ] && { [ -d "$ORACLE_ROOT/ψ" ] || [ -L "$ORACLE_ROOT/ψ" ]; }; then
  PSI="$ORACLE_ROOT/ψ"
elif [ -f "$(pwd)/CLAUDE.md" ] && { [ -d "$(pwd)/ψ" ] || [ -L "$(pwd)/ψ" ]; }; then
  ORACLE_ROOT="$(pwd)"
  PSI="$ORACLE_ROOT/ψ"
else
  echo "⚠️ Not in oracle repo (no CLAUDE.md + ψ/ at git root). Writing to pwd."
  ORACLE_ROOT="$(pwd)"
  PSI="$ORACLE_ROOT/ψ"
fi

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 "$PSI/learn/owner"
ln -sf "$GHQ_ROOT/github.com/owner/repo" "$PSI/learn/owner/repo"

Output (announce-mode — absolute path):

announce-mode → absolute path (no ψ/, no ~/, no $VAR, no ...).

Use: echo "marker: $RESOLVED_PATH" — bash substitutes. See CONVENTIONS.md.

LINK="$PSI/learn/owner/repo"
echo "✅ Linked: $LINK"

incubate — REDIRECTS TO /incubate

/project incubate is now /incubate. If the user says /project incubate [args], run /incubate [args] instead. Do NOT execute incubate logic here — invoke the standalone /incubate skill with the same arguments.

find [query]

Search for project across all locations:

# Search ghq repos
ghq list | grep -i "query"

# Search learn/incubate symlinks (org/repo structure)
find "$PSI/learn" "$PSI/incubate" -type l 2>/dev/null | grep -i "query"