Use when cloning, creating, modifying, reviewing, or cleaning up Git repositories in a Hermes workspace. Keep non-Ansible repositories under the workspace git/ directory, preserve repository boundaries and local instructions, and use consent-based cleanup and archival under git_archive/ after pull-request work is complete.
Use when cloning, creating, modifying, reviewing, or cleaning up Git repositories in a Hermes workspace. Keep non-Ansible repositories under the workspace git/ directory, preserve repository boundaries and local instructions, and use consent-based cleanup and archival under git_archive/ after pull-request work is complete.
Act as a considerate team member whenever work requires a Git clone, repository, or worktree in a Hermes workspace. Keep general Git repositories together, protect unrelated work, and make active versus closed projects obvious. This skill is the specialized Git placement layer for hermes-workspace-manager: the repository directory selected here is the task's topic folder, so do not create a duplicate generic topic folder.
Use <workspace> for the active workspace supplied by Hermes. The standard paths are:
Never clone a general software, documentation, infrastructure, or bootstrap repository into ansible/ merely because the task mentions Ansible or changes an Ansible-related file. Classify by the repository's primary purpose, not by one file or task.
When to Use
Use this skill when:
Cloning an existing Git repository.
Initializing a new Git repository.
Creating branches, commits, tags, forks, or pull requests.
Reviewing or modifying a repository already present in the workspace.
Retaining a clean working tree for pull-request revisions.
Cleaning up or archiving completed repository work.
Correcting a repository that was placed in the wrong workspace directory.
Do not use git/ as a general scratch directory. Non-repository outputs belong in a task-appropriate workspace directory. Do not move a repository that the user explicitly located elsewhere unless they ask for workspace normalization or the placement violates these established workspace rules.
1. Classify Before Cloning or Moving
Determine the repository's primary purpose before choosing a path.
Ansible-native repositories
Use <workspace>/ansible/ only when the repository itself is primarily one of these:
Ansible playbook repository
Ansible role repository
Ansible collection repository
Ansible inventory or automation repository
Follow hermes-workspace-ansible for those repositories and archive them under ansible_archive/.
All other Git repositories
Use <workspace>/git/ for every other repository, including:
Application and library source repositories
Kubernetes, Helm, Terraform, platform, or installer repositories
Documentation repositories
Bootstrap and configuration repositories
Repositories that merely contain Ansible examples, roles, playbooks, or documentation as one component
Repositories used to publish or package an Ansible skill but whose primary purpose is not Ansible automation
Example classification:
kube.hermes_setup
Primary purpose: Kubernetes/K3s installer and Hermes bootstrap repository
Active path: <workspace>/git/kube.hermes_setup
Archive path: <workspace>/git_archive/kube.hermes_setup
Do not infer classification from the remote hosting service, repository name alone, or the current task. Inspect the README, top-level tree, repository description, and maintainer instructions first.
Classification is complete only when the repository's primary purpose and exact active path are explicit.
2. Prepare the Workspace Safely
Before cloning or creating a repository:
Read <workspace>/AGENTS.md and any other workspace-level instructions.
Load hermes-workspace-manager when available and classify the task as Git repository work.
Inspect <workspace>/git/ for an existing clone with the same repository identity.
Inspect <workspace>/git_archive/ for a prior closed copy that may contain useful history or indicate a naming conflict.
Create <workspace>/git/ if it does not exist.
Use one directory per repository; do not mix unrelated repositories in one working tree.
Before cloning, check whether the destination exists. Never overwrite or delete an existing directory to make room. If the same remote is already present and clean, inspect whether it can be reused. If it is active, dirty, or owned by another task, preserve it and choose a clearly distinct worktree or ask when ownership cannot be determined.
Do not place access tokens in clone URLs. Use an SSH identity, credential helper, askpass helper, or a non-logging API authentication mechanism.
Preparation is complete only when the selected path is collision-free and no existing work was overwritten.
The selected <workspace>/git/<repository-name> directory also satisfies the topic-resolution requirement from hermes-workspace-manager. Keep repository-specific artifacts within that boundary and do not mirror them under <workspace>/<repository-name>.
3. Inspect the Repository Before Changing It
After entering <workspace>/git/<repository-name>/:
Read repository guidance in this order where present:
AGENTS.md
AGENT.md
CLAUDE.md
.cursorrules
CONTRIBUTING.md
README.md
security and release documentation relevant to the task
Inspect git status --short --branch, remotes, current branch, default branch, and recent history.
Treat every pre-existing modified, staged, or untracked file as potentially user-owned.
Identify repository-specific build, test, lint, formatting, signing, and commit conventions.
Confirm the destination remote and base branch before publishing.
Do not use destructive cleanup commands such as git reset --hard, git clean -fd, branch force deletion, or forced push to erase unexpected state. Stop and report ambiguous ownership instead.
Inspection is complete only when repository instructions, pre-existing state, remotes, and the intended base branch are known.
4. Work Within the Repository Boundary
Keep repository-specific source, tests, generated fixtures, dependency manifests, and task artifacts inside the repository at <workspace>/git/<repository-name>/, following its own conventions.
Rules:
Use a focused feature branch unless the maintainer explicitly requires another workflow.
Make the smallest correct change and preserve unrelated files.
Put dependencies in the repository's established manifest and lock files.
Keep generated or temporary files ignored unless the repository intentionally tracks them.
Never commit credentials, private infrastructure details, local environment files, generated backups, or authentication state.
Use sanitized placeholders in public repositories.
Verify changed behavior with the repository's documented checks.
The workspace git/ directory is a container for repositories, not a shared dependency or artifact directory. Do not create files such as git/requirements.txt, git/package.json, or git/.env for multiple repositories.
When a task spans several repositories, keep each as a sibling:
Track and report changes per repository. Never assume one repository's instructions apply to another.
5. Verify Before Publishing
Before committing or pushing:
Run targeted tests for the changed behavior.
Run repository-required formatters, linters, static checks, and broader tests appropriate to impact.
Run git diff --check.
Review the complete diff, including staged and untracked files intended for commit.
Scan for secrets and private values using repository-approved tooling or a focused pattern scan.
Confirm the commit contains only intended paths.
Verify the working tree is clean after commit.
Before creating a pull request:
Push only the intended feature branch or fork branch.
Confirm the remote branch resolves to the expected commit SHA.
Create the PR against the intended base repository and branch.
Verify the returned PR URL, state, head, base, commit count, and changed-file count.
Check available CI/check-run status and report when no automated checks exist.
Do not claim success merely because git push exited successfully. A published task is complete only when the remote branch and PR, when requested, are verified.
6. Clean Up During Work
Remove only disposable artifacts created by the current task, such as:
Temporary patch or diff files
Build caches not intentionally retained
Generated test output
Downloaded archives
Editor backup files
One-time credential helpers
Temporary rendered output
Use the repository's clean command when it is safe and documented, or remove exact known task-owned paths. Do not remove pre-existing untracked files or broad file classes without proving ownership.
A clean repository means git status --porcelain is empty. It does not mean the repository itself is disposable.
7. Pull-Request Cleanup Decision
When a pull request is created, do not immediately archive the working repository. An open PR may need review fixes. Ask the user what to do and offer a concrete accounting:
Disposable files to delete now, with exact paths
Active repository to retain until merge, with exact path
Completed repositories eligible for immediate archival
Any sibling repositories or shared workspace paths that will remain untouched
Offer these choices when applicable:
Keep the clean repository under <workspace>/git/ until the PR is merged; this is the recommended default for an open PR.
Archive the repository now under <workspace>/git_archive/.
Leave cleanup for the user to handle later.
A useful prompt is:
The pull request is created. There are <disposable paths or none> to delete. The clean active repository is <workspace>/git/<name>; I recommend retaining it until merge so review changes can be applied. If archived now, it would move to <workspace>/git_archive/<name>. Should I retain it, archive it now, or leave cleanup for later?
Do not archive or delete until the user agrees. If the user chooses to retain it, leave the working tree clean and re-offer cleanup after the merge is observed or reported.
8. Archive a Completed Repository
After the user approves archival—or after a previously retained PR is merged and the user has already authorized post-merge archival—use this procedure:
Recheck PR/branch state and git status --porcelain.
Preserve uncommitted work; do not archive a dirty repository without explicitly reporting it and obtaining approval.
Fetch/prune if authentication and network access are available.
Switch to the default branch and fast-forward it to the verified remote default branch when safe.
Delete obsolete feature branches only when merged and approved. Never force-delete an unmerged branch merely to make cleanup easier.
Create <workspace>/git_archive/.
Move the whole repository directory, including .git, from git/ to git_archive/.
Verify the source path is absent, the destination is a valid Git working tree, its status is clean, and its HEAD is the expected commit.
If the destination already exists, never overwrite or merge directory trees. Append the actual local timestamp in YYYYMMDD_HHMM format to the repository directory name:
If a same-minute conflict also exists, generate a new unique suffix rather than overwriting. Preserve the repository's remote configuration and history unless the user explicitly requests a source-only archive.
Archival is complete only when the repository exists solely at the approved archive destination and its Git state is verified.
9. Correct a Misplaced Repository
When a general repository is found under ansible/ or ansible_archive/:
Confirm it is not Ansible-native using its README, top-level tree, and stated purpose.
