Defame1297
3920dfab20
Closes four PR #135 review findings in skill content. #2 — plugins/git/config.example.json was deleted inf5e4d0d, but four git-plugin files still told the agent to read it. The file only ever carried branching_pattern, commit_style and rebase_strategy, so the `base_branch` and scope instructions were wrong even before the deletion. Each site now describes what the skill actually does: base is `main` under GitHub Flow or `develop` when Gitflow is inferred, the Gitflow fallback keys off the repo's own branches, the orchestrator contract's `base` defaults to the inferred base branch, and the commit scope is inferred from the changed files. N6 — gitea-prs was the one gitea skill with no permission-scope caveat on a 404. Added one alongside the existing issue/PR number-space guidance rather than replacing it: a 404 is only evidence of "that number is an issue" once write:repository scope is confirmed. N4 — plugins/kyberforge/bin/README.md pointed at `.mcp.json`, but all six plugin-root .mcp.json files were deleted inc96ca9c(ADR-0018). ${CLAUDE_PLUGIN_ROOT} itself is still live, so the sentence now points at .apm/hooks/hooks.json, which kyberforge's own hook already uses. N7 — not applied. The finding claimed a marketplace field override emits a verbose BuildDiagnostic that `apm pack -v` surfaces, so "silently wins" was wrong. apm 0.28.0 does construct the diagnostic in marketplace/output_mappers.py, but nothing renders it: _render_marketplace_result in commands/pack.py iterates `warnings` only, and BuildReport.diagnostics has no consumer. Confirmed on a fixture — neither `apm pack -v` nor APM_LOG_LEVEL=DEBUG prints the override, and --check-versions reports [matches]. The existing wording in configure.md and marketplace.md is correct, so both are unchanged. Version bumps required by check-skill-version-bump.sh: git-branches 1.0.4 -> 1.0.5, git-commits 0.1.6 -> 0.1.7, gitea-prs 0.1.4 -> 0.1.5. bin/README.md is outside any skill directory and needs no bump. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2
77 lines
3.7 KiB
Markdown
77 lines
3.7 KiB
Markdown
---
|
|
name: git-branches
|
|
|
|
description: >
|
|
Use when creating, switching, deleting, renaming, tracking, merging, or comparing
|
|
local git branches under GitHub Flow or Gitflow.
|
|
Not writing or rewriting commits -> `git-commits`.
|
|
Not history inspection -> `git-history`.
|
|
Not a Gitea remote's branches -> `gitea-branches`.
|
|
|
|
metadata:
|
|
version: "1.0.5"
|
|
category: git
|
|
source_keys:
|
|
- context7-git-htmldocs
|
|
- nvie-gitflow-post
|
|
- atlassian-gitflow-tutorial
|
|
- gitflow-cheatsheet
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
|
|
- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list <name>`; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
|
|
- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead.
|
|
|
|
## Step 1 — Determine the branching pattern
|
|
|
|
Infer the branching pattern from the repo: Gitflow if a `develop` or `release/*` branch exists, GitHub Flow otherwise (the default).
|
|
|
|
The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.
|
|
|
|
## Step 2 — Dispatch on the action
|
|
|
|
| Action | Reference |
|
|
|---|---|
|
|
| create, switch, delete, rename, track, list, get-intent, stash | `references/branch-operations.md` |
|
|
| merge a branch, resolve merge conflicts | `references/merging.md` |
|
|
| compare two branches, find their divergence | `references/comparing-branches.md` |
|
|
|
|
Load only the file the action needs. A destructive action still passes Step 3 first.
|
|
|
|
## Step 3 — Gate destructive operations
|
|
|
|
Before any delete or force-delete that loses history:
|
|
|
|
- [ ] Does the branch track a remote? Warn if so.
|
|
- [ ] Are there unpushed commits on it? Warn if so.
|
|
- [ ] Did the caller pass `confirm: true`? Fail if not — for a human caller, prompt interactively instead of failing.
|
|
|
|
These gates are passable. The `main`/`master` refusal in Gotchas is not.
|
|
|
|
## Step 4 — Set tracking
|
|
|
|
A new branch's first push must be `rtk git push -u origin <branch>`. The push itself is `git-remotes`' — every remote-side gate lives there, which is why Step 2's remote-delete row hands off the same way — but the upstream requirement originates here, so carry it in the handoff. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.
|
|
|
|
## Step 5 — Return a structured result
|
|
|
|
Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"action": "create|switch|delete|rename|track|list|get-intent",
|
|
"branch": "<name>",
|
|
"message": "descriptive message",
|
|
"intent": "<intent if tracked>",
|
|
"tracking": "origin/<branch, if set>",
|
|
"error": "<error message if success=false>",
|
|
"suggestion": "<recovery suggestion if applicable>"
|
|
}
|
|
```
|
|
|
|
When the failure is uncommitted local changes, set `"suggestion": "stash changes and retry"` so the caller can offer recovery rather than surfacing a dead end.
|
|
|
|
When a calling agent supplies a structured request rather than prose, read `references/orchestrator-contract.md` for the request schema.
|