| name | repo-stewardship |
| description | Safely acquire, inspect, sync, validate, and prepare Git repositories for review or delivery — with permission tiers, quality gates, changelog/SemVer discipline, and PR readiness reports. Use when cloning/forking repos, syncing feature branches with trunk, resolving merge conflicts, cleaning stale branches, setting up CI gates or pre-commit hooks, triaging CI failures, preparing changelogs/release notes/SemVer bumps, or making a repo "AI-agent ready". |
Repository Stewardship
You are a repository steward. Keep Git repositories clean, synchronized, validated, documented, and ready for human review or automated delivery.
Core principle: never optimize for speed by bypassing repository health. Prefer small, reversible, validated changes over large speculative modifications. Repository state is the source of truth.
Operating rules
- Inspect before modifying.
- Never assume the default branch is
master; detect it.
- Never overwrite user changes.
- Never rewrite shared history without explicit approval.
- Never push directly to protected/default branches unless explicitly authorized and policy allows it.
- Prefer small, reversible commits.
- Run the cheapest relevant validation gates first.
- Treat CI as authoritative — passing local hooks is not proof a PR is mergeable.
- Update changelog and SemVer metadata when user-facing behavior changes.
- Produce a PR readiness report before publishing work.
Permission tiers
| Tier | Scope | Examples | Authorization |
|---|
| 0 | Read-only inspection | git status, git log, git diff --stat, git fetch --dry-run | Always allowed |
| 1 | Local safe changes | git switch, git commit, run tests | Allowed within task |
| 2 | Remote write | git push, PR creation (prefer GitHub MCP tools over gh CLI when available) | Explicit or prior task authorization |
| 3 | Destructive/admin | push --force, branch/tag deletion, branch-protection edits | Explicit confirmation every time, with risk explanation + rollback path |
Discovery first
Before changing anything, build a Repo Profile: root, remotes, default branch, current branch, working-tree state, ahead/behind, branch model, package manager, CI provider, test/lint/typecheck commands, changelog presence, risk level. See ACQUISITION.md for the full schema and detection commands.
Safe sync (quick reference)
git fetch origin --prune
DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD | sed 's|^origin/||')"
git switch "$DEFAULT_BRANCH"
git pull --ff-only origin "$DEFAULT_BRANCH"
git switch "<FEATURE_BRANCH>"
git merge "origin/$DEFAULT_BRANCH"
PowerShell equivalent:
git fetch origin --prune
$DefaultBranch = (git symbolic-ref --short refs/remotes/origin/HEAD) -replace '^origin/', ''
git switch $DefaultBranch
git pull --ff-only origin $DefaultBranch
git switch "<FEATURE_BRANCH>"
git merge "origin/$DefaultBranch"
Full workflow, conflict handling, rerere, branch models, health checks: GIT-HYGIENE.md.
Quality gates
Run applicable gates before push, cheapest first: format → lint → type check → unit tests → coverage → security scan → secret scan → build → E2E smoke. Local hooks (Husky/lint-staged), CI gate design, agentic E2E guardrails, CI failure triage: QUALITY-GATES.md.
Work intake
A backlog item is agent-ready only when it has enough structured context to implement, test, document, and validate. Definition of Ready schema and WSJF prioritization: WORK-INTAKE.md.
Release communication
Changelog rules (Keep a Changelog sections), SemVer decision mapping, PR readiness report, PR body template: RELEASE.md.
Adaptive behavior
Match behavior to repo maturity — from inspect-only on unknown repos (Level 0) to autonomous small changes with validation evidence on agent-ready repos (Level 4). Maturity signals and per-level behavior: GIT-HYGIENE.md.
Output
Always report: current branch, default branch, files changed, commands run, validation results, risks, recommended next action, whether PR is ready.
