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.

Example 4: Overview of GitHub Actions triggers

User says: "When do my projects run their GitHub Actions — push, PR, or schedule?"

Actions:

1. Run bash scripts/list-workflow-triggers.sh (add --glob to narrow to one pipeline, --root for a different checkout directory)
2. Present the sorted overview (weekday/time, human-readable plus original cron) and the event-only workflows
3. Point the user to the generated report at target/workflow-triggers.md

Result: Consolidated, time-sorted trigger overview across all reference repos plus a Markdown report, without opening each workflow file.

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
bash scripts/sync-all.sh --list ~/claude-shared/projekte.txt

# Limit gh repo list to 50 repos
bash scripts/sync-all.sh --limit 50

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.

scripts/list-workflow-triggers.sh [--root <dir>] [--glob <pattern>] [--out <file>] [--no-report]

Scans every repo checkout for .github/workflows/*.yml and *.yaml, extracts the triggers from the on: block (push, pull_request, schedule, workflow_dispatch, release, …) plus any cron: expressions, prints the overview and writes a Markdown report. Scheduled workflows are sorted by weekday/time and shown with a human-readable run time (e.g. Monday 02:05) next to the original cron expression; workflows without a schedule are listed in a separate event-only section. Read-only, no network access.

• --root <dir> — directory containing repo checkouts. Default: $REFERENZEN_DIR or ~/projects/referenzen.
• --glob <pattern> — optional filename filter, e.g. maven-build.yml. Default: all workflows.
• --out <file> — Markdown report path. Default: target/workflow-triggers.md (relative to the current project directory, created if missing).
• --no-report — print to stdout only, skip the report file.

# Overview + report for all reference repos
bash scripts/list-workflow-triggers.sh

# Only maven-build.yml, custom report location
bash scripts/list-workflow-triggers.sh --glob 'maven-build.yml' --out target/maven-triggers.md

# A different checkout root (e.g. Windows mount)
bash scripts/list-workflow-triggers.sh --root /mnt/c/Development/projects/all-git-repos

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.

4. Overview of GitHub Actions triggers

Run scripts/list-workflow-triggers.sh to get a cross-repo overview of every workflow's on: triggers and cron: entries. It also writes the report to target/workflow-triggers.md. Use --glob to focus on a single pipeline (e.g. maven-build.yml) and --root for a different checkout directory.

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.