repo-orch-graph

/repo-orch-graph [repo]

Build (or incrementally refresh) the knowledge summary for all repos, or a single named repo.

Usage:

• /repo-orch-graph — build summaries for all repos in the registry
• /repo-orch-graph auth-service — build/refresh summary for one repo
• /repo-orch-graph --rebuild — force full rebuild even if summary exists

Summaries are stored in .repo-orchestrator/graphs/<name>/ and consumed automatically by /repo-orch-triage.

No Python, no API key, no external tools required — this command runs entirely within the current Claude Code session.

---

Step 1 — Check registry

Read .repo-orchestrator/registry.json. If it does not exist, stop: "Registry not found. Run /repo-orch-init first."

If a repo name was provided, find that entry. If not found, stop: "Repo <name> not found in registry. Available: <list of names from registry>"

---

Step 2 — Decide full build vs. incremental

For each repo to process:

1. Determine the repo path from registry.json (the path field).
2. Set the output path: .repo-orchestrator/graphs/<name>/summary.json.
3. Full build if: --rebuild was passed OR summary.json does not exist.
4. Incremental update if: summary.json exists and --rebuild was not passed.

   • First, detect shallow clone or detached HEAD:

     git -C <repoPath> rev-parse --is-inside-work-tree 2>/dev/null
     git -C <repoPath> log --oneline -1 2>/dev/null
     git -C <repoPath> rev-parse --abbrev-ref HEAD 2>/dev/null
     

     If rev-parse --is-inside-work-tree fails, or log --oneline -1 returns empty output, or rev-parse --abbrev-ref HEAD returns HEAD (detached): force a full build and print:

     <name>  shallow clone or detached HEAD detected — full rebuild required.
     

     Do not attempt SHA comparison in these cases — the SHA is unreliable.

   • Otherwise, run git -C <repoPath> rev-parse HEAD to get the current HEAD SHA.

   • Read the generatedAt.commitSHA field from the existing summary.json.

   • If the SHAs match: print <name> up to date — skipping. and skip this repo.

   • If they differ: run a full build (the codebase has changed since last summary).