repository-orientation

name	repository-orientation
description	Inspect a local Git repository's branch, changes, history, commits, and worktrees with Gocus read-only tools. Use when orienting in an unfamiliar repository, reviewing current Git state, tracing a change, finding a commit, or explaining recent history.

Repository Orientation

Use Gocus to establish the repository's current state before drawing conclusions from source files alone.

Workflow

1. Resolve the repository root to an absolute path. If more than one repository is plausible, state which one you are inspecting.
2. Call get_repository_overview first. Treat its branch, dirty counts, repository operation, and recent commits as the baseline.
3. Follow up only as needed:
   • Call get_changed_files for staged, unstaged, untracked, or conflicted paths.
   • Call get_commit_graph to explain topology or compare all, current, or named-branch history.
   • Call search_commits when the user gives a topic, author, hash fragment, ref, or message phrase.
   • Call inspect_commit when a specific commit needs its full message and nearby context.
4. Report the current branch and local-change state separately from historical findings.
5. Name limits or uncertainty, such as truncated results, a branch-only view, missing remotes, or a commit outside the selected view.

View Selection

• Use { "mode": "current" } for history reachable from the checked-out branch.
• Use { "mode": "branch", "ref": "<branch>" } for an explicitly named branch.
• Use { "mode": "all" } when comparing branches, tags, or linked worktrees. This is the default.

Safety

All repository-orientation tools in this plugin are read-only. Separate app-only initialization, checkout, cleanup, and merge controls run only after an explicit confirmation in the Gocus canvas; do not imply that inspecting a repository changed, fetched, checked out, cleaned, initialized, or committed anything.