project-references

# Search Patterns for Reference Repositories

Base directory: `~/projects/referenzen/`

## Find files by name

```bash
# Find a specific file in one repo
find ~/projects/referenzen/repo-name -name "Chart.yaml"

# Find across all repos
find ~/projects/referenzen -name "values.yaml"
```

## Search for patterns (grep)

```bash
# Search in a specific file
grep -n "some-dependency" ~/projects/referenzen/repo-name/pom.xml

# Recursive search in a directory
grep -rn "some-dependency" ~/projects/referenzen/repo-name/

# Search with context lines
grep -rn -A 3 -B 3 "some-pattern" ~/projects/referenzen/repo-name/src/
```

## Explore project structure

```bash
# Top-level structure
ls ~/projects/referenzen/repo-name/

# Helm chart layout
ls ~/projects/referenzen/repo-name/helm-charts/

# Read a specific file
cat ~/projects/referenzen/repo-name/helm-charts/values.yaml
```

## List all available reference repos

```bash
ls ~/projects/referenzen/

# Show tracked repos from list file (if it exists)
cat ~/claude-shared/projekte.txt
```

## Citing patterns

Always tell the user which project and file a pattern came from:

> Pattern adopted from `your-service` →
> `~/projects/referenzen/your-service/helm-charts/Chart.yaml` (line 4)

#!/usr/bin/env bash
# Clone a single GitHub repository into ~/projects/referenzen/ or pull if it exists.
# Usage: clone-or-update.sh <owner/repo>
# Exit codes: 0=ok, 1=argument missing, 2=local changes present (pull skipped), 3=clone/pull failed

set -euo pipefail

REFERENZEN_DIR="${REFERENZEN_DIR:-$HOME/projects/referenzen}"

if [[ $# -lt 1 ]]; then
	echo "Usage: $0 <owner/repo>" >&2
	exit 1
fi

REPO="$1"
NAME="${REPO##*/}"
TARGET="$REFERENZEN_DIR/$NAME"

mkdir -p "$REFERENZEN_DIR"

if [[ -d "$TARGET/.git" ]]; then
	STATUS=$(git -C "$TARGET" status --porcelain)
	if [[ -n "$STATUS" ]]; then
		echo "SKIP  $REPO — local changes present, not pulling:"
		git -C "$TARGET" status --short | sed 's/^/      /'
		exit 2
	else
		echo "PULL  $REPO"
		if git -C "$TARGET" pull --ff-only 2>&1; then
			echo "      OK"
		else
			echo "      FAILED (not fast-forward or network error)" >&2
			exit 3
		fi
	fi
else
	echo "CLONE $REPO → $TARGET"
	if gh repo clone "$REPO" "$TARGET" -- --quiet 2>&1; then
		echo "      OK"
	else
		echo "      FAILED" >&2
		exit 3
	fi
fi

#!/usr/bin/env bash
# Sync all repositories to ~/projects/referenzen/.
# Reads from ~/claude-shared/projekte.txt if present, otherwise uses gh repo list.
# Usage: sync-all.sh [--list <file>] [--limit <n>]
#   --list  <file>  override the default projekte.txt path
#   --limit <n>     max repos when using gh repo list (default: 200)

set -euo pipefail

REFERENZEN_DIR="${REFERENZEN_DIR:-$HOME/projects/referenzen}"
PROJEKTE_FILE="${PROJEKTE_FILE:-$HOME/claude-shared/projekte.txt}"
GH_LIMIT=200
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

while [[ $# -gt 0 ]]; do
	case "$1" in
	--list)
		PROJEKTE_FILE="$2"
		shift 2
		;;
	--limit)
		GH_LIMIT="$2"
		shift 2
		;;
	*)
		echo "Unknown option: $1" >&2
		exit 1
		;;
	esac
done

mkdir -p "$REFERENZEN_DIR"

# --- Determine repo list ---
if [[ -f "$PROJEKTE_FILE" ]]; then
	echo "Source: $PROJEKTE_FILE"
	REPOS=$(grep -v '^\s*#' "$PROJEKTE_FILE" | grep -v '^\s*$' || true)
else
	echo "Source: gh repo list (limit $GH_LIMIT) — projekte.txt not found at $PROJEKTE_FILE"
	REPOS=$(gh repo list --limit "$GH_LIMIT" --json nameWithOwner --jq '.[].nameWithOwner')
fi

TOTAL=$(echo "$REPOS" | grep -c . || true)
echo "Repositories to sync: $TOTAL"
echo "Target directory:     $REFERENZEN_DIR"
echo "---"

CLONED=0
PULLED=0
SKIPPED=0
FAILED=0

inc() { eval "$1=\$(( \${$1} + 1 ))"; }

while IFS= read -r REPO; do
	[[ -z "$REPO" ]] && continue

	NAME="${REPO##*/}"
	TARGET="$REFERENZEN_DIR/$NAME"

	if [[ -d "$TARGET/.git" ]]; then
		STATUS=$(git -C "$TARGET" status --porcelain)
		if [[ -n "$STATUS" ]]; then
			echo "SKIP  $REPO — local changes present:"
			git -C "$TARGET" status --short | sed 's/^/      /'
			inc SKIPPED
		else
			echo "PULL  $REPO"
			if git -C "$TARGET" pull --ff-only 2>&1 | sed 's/^/      /'; then
				inc PULLED
			else
				echo "      FAILED" >&2
				inc FAILED
			fi
		fi
	else
		echo "CLONE $REPO → $TARGET"
		if gh repo clone "$REPO" "$TARGET" -- --quiet 2>&1 | sed 's/^/      /'; then
			echo "      OK"
			inc CLONED
		else
			echo "      FAILED" >&2
			inc FAILED
		fi
	fi
done <<<"$REPOS"

echo "---"
echo "Done.  Cloned: $CLONED  Pulled: $PULLED  Skipped (local changes): $SKIPPED  Failed: $FAILED"

---
name: project-references
description: "Look up conventions, patterns, and concrete implementations from your own GitHub repositories checked out locally under ~/projects/referenzen/. Use this skill whenever there is uncertainty about how something is done in your codebase family — e.g. Helm chart structure, Kubernetes manifests, framework configuration patterns, Docker Compose conventions, CI/CD pipeline setup, or any other recurring architectural decision. Invoke it proactively before guessing at a convention; always cite the source project and path when a pattern is adopted. Also use when the user asks to check out, update, or search reference repositories."
---

---

# 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

```bash
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
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.

```bash
# 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`.

---

## 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

```bash
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.