project-references

Project References

This skill manages a local mirror of your own GitHub repositories under ~/projects/referenzen/ and lets you look up conventions and implementation patterns without guessing or reading all repos blindly.

All operations are read-only on the reference projects themselves. Only git clone and git pull write into that directory — never edits.

Instructions

Step 1: Check whether the relevant repo is already cloned

ls ~/projects/referenzen/

If the needed repo is missing, run scripts/clone-or-update.sh owner/repo to clone it first.

Step 2: Ask the user which reference project is most relevant

Do not scan all repos blindly — that fills context. Ask: "Which of your sibling projects uses this pattern?" or list the available repos and let the user pick.

Step 3: Search targeted — file first, then grep

Use find to locate a file by name, then cat or grep to read only the relevant section. For search commands and patterns, consult references/search-patterns.md.

Step 4: Cite the source when adopting a pattern

Always state which project and file path a pattern came from before applying it:

Pattern adopted from your-service → helm-charts/Chart.yaml line 4

Step 5: Sync only when explicitly requested

Run scripts/sync-all.sh only when the user says "sync all" or "update all references". For a single repo, prefer scripts/clone-or-update.sh.

Examples

Example 1: Looking up a Helm chart convention

User says: "How should I structure the Helm chart for this project?"

Actions:

1. Run ls ~/projects/referenzen/ to see available repos
2. Ask: "Which sibling project should I use as reference?" — user says your-service
3. Run find ~/projects/referenzen/your-service -name "Chart.yaml" to locate it
4. Read the file, note the structure (apiVersion, dependencies, version pattern)
5. Apply the same structure; cite: "adopted from your-service/helm-charts/Chart.yaml"

Result: Helm chart consistent with sibling projects, traceable source cited.

Example 2: Checking out a new reference repo

User says: "Clone my other-service project as a reference"

Actions:

1. Run bash scripts/clone-or-update.sh owner/other-service
2. Stream output so user sees CLONE/PULL/SKIP progress
3. Confirm with ls ~/projects/referenzen/other-service/

Result: Repo available locally for pattern lookups; no edits made.

Example 3: Finding a configuration pattern

User says: "How do I configure the database pool like in the other projects?"

Actions:

1. ls ~/projects/referenzen/ — pick a relevant sibling project
2. grep -rn "database.pool" ~/projects/referenzen/your-service/src/main/resources/
3. Read the relevant config section
4. Cite: "pattern from your-service/src/main/resources/application.yaml line 42"

Result: Exact config from a proven sibling project, not guessed.

Repository source

Two sources are supported — prefer the manual list when it exists:

1. Manual list (~/claude-shared/projekte.txt): one GitHub repo URL or owner/name slug per line, blank lines and # comments ignored.
2. Automatic discovery: gh repo list --limit 200 --json nameWithOwner when the file is absent or the user explicitly asks for a full sync.

Scripts

Two ready-made scripts live in scripts/ — use them instead of writing inline Bash. Both accept REFERENZEN_DIR as an env override (default: ~/projects/referenzen).

scripts/clone-or-update.sh <owner/repo>

Clones a single repository or pulls if it already exists locally. Refuses to pull when local changes are present (exit code 2) — never stashes or resets.

bash scripts/clone-or-update.sh owner/your-repo

Exit codes: 0 = ok, 2 = skipped (local changes), 3 = clone/pull failed.

scripts/sync-all.sh [--list <file>] [--limit <n>]

Iterates over all repositories and calls the clone-or-update logic for each. Prefers ~/claude-shared/projekte.txt as source; falls back to gh repo list when the file is absent. Prints a summary line at the end.

# Sync everything (auto-detect source)
bash scripts/sync-all.sh
 
# Use a specific list file

Do not run sync-all blindly — use it only when the user explicitly says "sync all" or "update all references". For a single repo prefer clone-or-update.sh.

Workflows

1. Check out or update repositories

Run the appropriate script and stream output so the user sees every CLONE / PULL / SKIP action as it happens.

2. Search within reference projects

Scope the search to what the user actually needs. Prefer targeted lookups over broad recursive greps. For ready-made search commands and citing patterns, consult references/search-patterns.md.

3. Discover available reference projects

ls ~/projects/referenzen/

If ~/claude-shared/projekte.txt exists, show its contents alongside to explain which repos are tracked vs. which are locally present.

When to suggest this skill proactively

Suggest looking up a reference project when:

• The user asks how something is structured and the answer may vary by project convention (Helm chart layout, Flyway migration naming, Dockerfile patterns, Maven plugin ordering, etc.)
• There is more than one reasonable approach and consistency with sibling projects matters
• The user says "like the other projects" or "same as before" without specifying which project

Ask the user which reference project is most relevant rather than scanning all of them — scanning is expensive in context.

Safety rules

• Never edit, stage, commit, or delete files inside ~/projects/referenzen/.
• If git pull would fail due to local changes, report the conflict clearly and stop — do not stash, reset, or force.
• Do not expose repository contents that contain secrets (.env, credential files) in the response — read and cite structure only.