git-workflow

Manage the ## Git Workflow section in AGENTS.md. Defines how the project branches, commits, merges, and handles PRs.

Philosophy. 99% of projects follow one of three well-known presets with at most 3-5 project-specific customizations. Free-form input bloats AGENTS.md and produces documents the agent cannot reliably parse. This skill forces a preset + delta structure: pick one of three presets, then answer a short checklist about the delta.

Scope

In scope:

• Create or refine the ## Git Workflow section
• Auto-detect current workflow from git log, branches, and (if GitHub) gh repo view
• Offer the three presets: Trunk-based, GitHub Flow, GitFlow
• Collect project-specific delta via a checklist (commit language, ticket prefix, force-push policy, release tag format, etc.)
• Write a compact, agent-readable ## Git Workflow section

Out of scope:

• Configuring git itself (git config, hooks, protected branches)
• Enforcing the rules at runtime (AGENTS.md is context, not a hook)
• Writing release notes or CHANGELOG — see /manage-refs for document pointers
• Managing branch protection settings on GitHub/GitLab (requires platform API and permissions)

Guardrails

#	Check	On failure
1	CWD is a Git repository	"Please run this inside a Git repository."
2	AGENTS.md exists	"AGENTS.md not found. Run /init-public-rules first."
3	## Git Workflow already exists	"Git Workflow already set. Refine (diff-based interview) or overwrite from scratch?"
-	Skill update check	Let SELF be the value of the name field in this SKILL.md's frontmatter (e.g., init-public-rules). Let LOCAL be metadata.version from this same frontmatter. Fetch https://raw.githubusercontent.com/dev-goraebap/agent-collabo/main/manifest.json (1 HTTP request, fail silently on network error). Then evaluate exactly one case in this order: Case A — outdated: if manifest.skills[SELF] exists and LOCAL < manifest.skills[SELF], tell the user (in their language) "agent-collabo {SELF} has a new version ({LOCAL} → {manifest.skills[SELF]}). Run /agent-collabo-updater when convenient. Continuing with the current task." then proceed. Case B — up to date: if manifest.skills[SELF] exists and LOCAL === manifest.skills[SELF], proceed silently. Case C — renamed away: if SELF does NOT exist as a key in manifest.skills AND SELF exists as a key in manifest.deprecated (note: check the keys of deprecated, not the renamedTo values), tell the user "This skill {SELF} was renamed to {manifest.deprecated[SELF].renamedTo} since v{manifest.deprecated[SELF].since}. Run /agent-collabo-updater to migrate." then proceed. Case D — unknown: if SELF is not in manifest.skills and not in manifest.deprecated, tell the user "Skill {SELF} is no longer maintained. Run /agent-collabo-updater to clean up." then proceed with caution. Important: manifest.deprecated maps OLD names → NEW names. Never warn about a skill whose name is currently in manifest.skills just because that name appears as a renamedTo value somewhere in deprecated. CDN cache caveat: GitHub raw enforces Cache-Control: max-age=300, so right after a new release is pushed the manifest may be stale for up to 5 minutes via Fastly PoPs. If the user explicitly mentions they just released a new version (e.g., "I just pushed v0.X.Y") and this check still reports up-to-date or shows an older manifest.version, do not insist the local install is current — instead mention the 5-minute CDN window and suggest retrying shortly. For all other users this is invisible because they fetch long after the cache expires.

Language Policy

Conduct all user-facing communication in the user's language: interview questions, follow-up prompts, status messages, diagnostic reports, and summaries. Detect the language from (in order):

1. The language of the user's most recent messages in the current session
2. Declarations in their local rules file (e.g., CLAUDE.local.md, .cursor/rules/local.mdc) — look for instructions like "respond in Korean"
3. OS locale ($LANG, $LC_ALL)
4. English as fallback

Generated file content follows the file's audience: team-shared files (AGENTS.md, CHANGELOG.md) stay in English regardless of the user's language; personal files (CLAUDE.local.md, GEMINI.local.md, etc.) use the user's language unless they specify otherwise.

The three presets

Preset A — Trunk-based development

One sentence: Short-lived feature branches off main, squashed back via PR, multiple times per day.

Shape:

## Git Workflow

- **Branching**: Trunk-based. Short feature branches off `main`.
  Merge within a day or two.
- **Branch naming**: `feat/`, `fix/`, `chore/`, `docs/` prefixes
  followed by a short kebab-case description.
- **Commits**: Conventional Commits (`feat:`, `fix:`, `docs:`, etc.).
  English.
- **PR merge**: Squash only. No merge commits. Feature branch deleted
  after merge.
- **Release**: Continuous. No release branch. Version tags cut from
  `main` on demand.
- **Never**: force-push `main`, amend published commits, skip
  `--no-verify`.

Typical for: SaaS products, internal tools, most web apps, agile teams shipping continuously.

Preset B — GitHub Flow

One sentence: Feature branches off main, merge commit back via PR, release cut from main with a tag.

Shape:

## Git Workflow

- **Branching**: GitHub Flow. Feature branches off `main`.
- **Branch naming**: Descriptive kebab-case
  (e.g., `redesign-search-bar`, `fix-login-race`).
- **Commits**: Conventional Commits. English.
- **PR merge**: Merge commit (preserves branch history). Feature
  branch deleted after merge.
- **Release**: Tag cut from `main` when ready. No release branches.
- **Never**: force-push `main`, push directly without a PR.

Typical for: OSS projects, documentation sites, simple team workflows where branch history is useful for context.

Preset C — GitFlow

One sentence: Long-lived main and develop branches, plus feature/*, release/*, and hotfix/* supporting branches.

Shape:

## Git Workflow

- **Branching**: GitFlow.
  - `main` is always production-releasable.
  - `develop` is the integration branch for the next release.
  - `feature/*` branches off `develop`, merges back to `develop`.
  - `release/*` branches off `develop`, merges to both `main` and
    `develop`, tagged on `main`.
  - `hotfix/*` branches off `main`, merges to both `main` and
    `develop`.
- **Branch naming**: `feature/<name>`, `release/<version>`,
  `hotfix/<name>`.
- **Commits**: Conventional Commits. English.
- **PR merge**: Merge commit (preserves branch lineage).
- **Release**: Cut via `release/*` branch, merged to `main`, tagged.
- **Never**: merge `feature/*` directly to `main`, tag on
  `develop`, skip the `release/*` ceremony for production changes.

Typical for: Enterprise projects, versioned libraries, products with staged QA/UAT environments.

Delta interview checklist

Whichever preset is chosen, ask the user which of these project-specific customizations apply:

Preset selected: Trunk-based

Any of these apply to your project? (Check what you need)

[ ] Commit subject language must be English (or specify another)
[ ] Commit message body must reference a ticket/issue number
    Example: "Closes #123" in the body, or "[PROJ-456]" in the subject
[ ] Specific commit message footer required
    (e.g., "Signed-off-by:", "Co-Authored-By:")
[ ] Release tags follow a strict format
    (e.g., `v0.1.0` matching CHANGELOG entries, semver only)
[ ] Specific branches are protected beyond `main`
    (e.g., `develop`, `release/*`)
[ ] PR title must follow a specific format
    (e.g., Conventional Commits, ticket prefix)
[ ] PR must pass specific checks before merge
    (e.g., CI green, at least 1 review, coverage threshold)
[ ] Merge commits must be signed (GPG or sigstore)
[ ] Other — describe in one line

For each checked item, ask a short follow-up to fill in the specific value. Do NOT ask follow-ups for unchecked items.

Workflow

Step 1: Auto-detect current convention

Before asking anything, gather signals:

Source	What to extract
git log --oneline -50	Commit message patterns (Conventional Commits? Gitmoji? plain English?)
git branch -a	Active branch names (prefixes detected: feat/, feature/, fix/, etc.)
git log --merges -20	Merge commit presence (squash vs merge commit)
gh repo view --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed (GitHub only)	Allowed merge strategies
Existing CHANGELOG.md	Release tag format (if references tags)
Existing .github/workflows/*.yml	Required checks, PR labels

Build a "detected profile" like:

Detected:
  - Branches: feat/, fix/, chore/ prefixes (23 branches)
  - Commits: Conventional Commits (48/50 match)
  - Merges: squash only (19/20 merges, no merge commits)
  - Repo: main branch, squash enabled, merge commits disabled
  → Most likely preset: Trunk-based

Step 2: Present preset choice

Show the detected profile and the matching preset as the default. Offer the other two as alternatives.

Based on your git history, this project looks like Trunk-based.

1. Confirm — Trunk-based (detected)
2. Choose a different preset (GitHub Flow / GitFlow)
3. Show me the preset template first

On option 3, show the raw preset template from above, then re-ask.

Step 3: Delta checklist

Run the delta interview checklist. Skip items the detection already answered.

Example — Trunk-based with detected Conventional Commits + English in commit log:

The "commit language English" item is auto-filled from detection and only shown for confirmation, not as an open question.

Step 4: Generate section

Assemble the preset template + delta answers into a single ## Git Workflow section. Write to AGENTS.md.

Placement order in AGENTS.md:

# Project Overview
## Project Structure
## External Tools
## Git Workflow           ← here
## Code Style
## Testing
## Boundaries
## References

If the section already exists, ask (from Guardrail 3) whether to refine or overwrite:

• Refine: show a diff-based interview — for each current bullet, "keep / change / delete?" Then apply.
• Overwrite: run the full Step 1–4 flow.

Step 5: Cross-skill follow-up

After writing, check for interactions:

• If the preset includes "Never force-push main" and no ## Boundaries section exists, suggest:

  The Trunk-based preset includes `Never force-push main`. You may
  also want this as a cross-cutting Boundary. Run /refine-boundaries
  with "force-push" as the rule? (y/n)
  

• If ## External Tools > CLIs does not mention gh or glab but one is installed and relevant, suggest running /manage-tools to register it.

Step 6: Summary

✅ Done. ## Git Workflow section written.

Preset: Trunk-based
Delta applied:
  - Commits in English (Conventional Commits)
  - PR requires CI green + 1 approval
  - Release tags match CHANGELOG versions

Next steps:
  - /refine-boundaries — to add force-push as a cross-cutting Boundary
  - /audit-rules — to verify the full AGENTS.md is under budget

Interaction with other skills

• /init-public-rules does not create ## Git Workflow — it's created by this skill, either during first setup or when the user invokes /git-workflow later.
• /refine-boundaries handles cross-cutting rules. Topic-inline rules (e.g., **NEVER** force-push main) live in this skill's territory.
• /work-unit-ritual requires ## Git Workflow to exist before setup. If the user runs /work-unit-ritual without it, the skill blocks and redirects here first.
• /audit-rules has no dedicated checks for Git Workflow content but T1 (length) and T2 (section balance) apply.

Prohibited actions

• Never allow free-form "describe your workflow" input — always force a preset choice first
• Never invent a fourth preset — if the user's workflow doesn't fit, use the closest preset and capture the difference in the delta
• Never write branch protection rules (that's a platform API concern, not AGENTS.md)
• Never duplicate cross-cutting rules into both ## Git Workflow and ## Boundaries — prefer inline if the rule is topic-scoped, cross-cutting if not