patch-repo - SKILL.md Agent Skill

name: patch-repo description: "Create deterministic git patches (stage/commit) and optionally push safely; writes audit reports under run/skills/patch-repo (scripts/skills/patch-repo.sh)."

SKILL: patch-repo

Summary

Automate a simple SCM workflow to stage all changes and create a deterministic commit message (update:) using scripts/skills/patch-repo.sh. By default the script does NOT push to upstream; pass --push to enable pushing. The skill captures stdout/stderr and writes a structured report under run/skills/patch-repo// for auditing and troubleshooting.

When to run

When local changes are ready to be saved as a patch and optionally pushed upstream.
Useful for agents that need to persist work by creating commits or preparing patches for review.

Inputs

args (array) — arguments forwarded to scripts/skills/patch-repo.sh (supports --push/--no-push; default is no push).

Outputs

run/skills/patch-repo//stdout.txt
run/skills/patch-repo//stderr.txt
run/skills/patch-repo//report.json — { "commit":"", "pushed":true|false, "branch":"", "upstream":"", "status":"ok"|"failed", "notes":"" }
run/skills/patch-repo//status.txt — git --no-pager status output after completion

Execution steps

Verify inside a git repository and capture working tree state and branch.
The skill does not push commits by default; use --push to enable automatic pushing. Ensure the calling agent has permission to push to the target remote/branch and avoid protected branches unless explicitly allowed.
Run scripts/skills/patch-repo.sh, capturing stdout/stderr to run/skills/patch-repo//.
After execution, verify that the created commit was successfully pushed; the script will retry pushing up to 3 times before failing. Record each attempt and any errors in the run/skills/patch-repo// outputs.
If any attempt succeeds, mark pushed=true and write the final report.json and status.txt. If all attempts fail after 3 retries, set status="failed", include details in notes (e.g., last push error), and exit with a non-zero error code so calling agents detect the failure.
On non-push failures (e.g., commit creation failed), capture git status and git log -n 5 and include error details in report.json.

Quality rules & safety

Do not push to protected branches (main, master, release) without explicit approval.
This skill does not push by default; ensure protected branches are not targeted by automated runs without explicit consent.
Do not perform remote network operations; only perform git operations on configured remotes.

Implementation notes

Helper script: scripts/skills/patch-repo.sh — commits staged changes and does not push by default (use --push to push). The script re-execs under bash when invoked with sh, performs up to 3 push retries on failure, and exits non-zero if pushes fail so calling agents can detect and react to errors.
Behavior: stages all changes with git add ., creates a deterministic commit update:<tree-hash> using git write-tree and git commit, then attempts to push; when no upstream is configured the first push uses git push -u origin <branch>.
Merge behavior: after a successful push, if the current branch is not main or master, the script will attempt to merge the pushed branch into the repository's primary branch (detects origin/main or falls back to origin/master). It will fetch both branches, ensure a clean local copy of the primary branch, and attempt a non-fast-forward merge. On conflicts the script first tries an automated 'theirs' strategy; if that fails it aborts the merge, creates a remote branch merge/<branch>-into-<main>-<timestamp> containing the state for manual resolution, and records merge metadata in run/skills/patch-repo/<timestamp>/report.json (merge_attempted, merge_result, merge_branch).
Agent guidance: invoke sh scripts/skills/patch-repo.sh (the script will re-exec to bash if needed). Ensure git credentials and remotes are configured (SSH key or token) and that the calling agent has permission to push to main or to create merge branches. After execution, parse run/skills/patch-repo/<timestamp>/report.json and check pushed, merge_attempted, merge_result, merge_branch and exit_code; inspect stdout.txt/stderr.txt for details.
Partial patches & cherry-picks: if an agent must commit a subset of changes, prepare the index (e.g., git add -p or use GIT_INDEX_FILE) before invoking this script; consider lower-level git commands for advanced workflows.
Troubleshooting / manual steps that fixed recent pushes: check git status -sb to see upstream and ahead counts, set upstream with git push -u origin <branch> when missing, and run git push to publish local commits (this was used to publish 5 local commits which updated remote to 355bf26).
Tuning suggestions: consider adding a dry-run flag, a selective-file mode, or explicit max-retries/config options for agents; ensure CI and agents have network access and appropriate git authentication.

References

scripts/skills/patch-repo.sh
scripts/skills/patch-repo.sh (wrapper)