git-workflow
Orchestrates commits, documentation updates, pushes, and PRs. Use when finishing a feature with docs, coordinating multiple commits, or shipping changes through a full Git workflow.
SKILL.mdycc/skills/git-workflow/SKILL.md
GitHubGit Workflow Manager
Analyzes changes, writes Conventional Commit messages, coordinates documentation updates (parallel agents when the change is large), and optionally pushes, opens a PR, and monitors CI.
Current Task
Managing git workflow for: $ARGUMENTS
Hard Rules (survive compaction)
- Push and PR are never implicit. Push only when
push ∈ actions; create a PR only whenpr ∈ actions; the action set comes from explicit flags or the Phase 0.5 menu reply. - Every commit must be a Conventional Commit:
<type>(<scope>): <subject>. Types:feat fix docs style refactor test chore perf ci build revert. Subject imperative, lowercase start, no trailing period, ≤50 chars (≤72 max); scope lowercase alphanumeric with hyphens; breaking change via!and/orBREAKING CHANGE:footer; body wrapped at 72. Enforced byscripts/validate-commit.sh. - Validate before committing (direct commits), after agents finish (agent commits; amend non-conformant ones), and for PR titles. Do not leave Phase 3b until all agent commits pass.
- Read
templates/commit-types.mdbefore writing any commit message. - NEVER
git push --force, NEVER--no-verify, anywhere including the CI loop. CI-loop pushes go only to the PR head branch; refuse if head equals the default branch. - Stage and commit in a single operation. Agents never push; this skill pushes.
--dry-runmakes no changes: STOP after the Phase 1 dry-run report.- Lack of MCP tools never blocks the workflow; on any MCP failure fall back to
gh. - Never update the root
CLAUDE.md.
Arguments
At least one action flag is required in normal use; with none, resolve interactively in Phase 0.5. Bare --ci is valid on its own (monitor CI on the existing PR for this branch). Flag order does not matter.
Action flags (cumulative ladder --commit < --push < --pr; each implies the lower ones):
- --commit: commit only
- --push: commit and push
- --pr: commit, push, create PR
Modifier flags (do not satisfy the action requirement):
- --dry-run: show analysis and plan, change nothing
- --no-docs: skip documentation updates
- --draft: create PR as draft (requires
--pr) - --base <branch>: PR base branch (requires
--pr); overrides the base fromRELEASING.mdor the forge default (Step 22b) - --ci: monitor CI on the current branch's PR and auto-fix until green or a bail. Works with
--pr(create-then-monitor),--push(push-then-monitor), or bare (monitor only: no commit, no push). An open PR for the branch must exist when Phase 6 starts. Incompatible with--dry-runand with--commit-only. - --ci-max-pushes=N (default 5), --ci-max-same-failure=N (default 3), --ci-timeout-min=N (default 30, from first iteration), --ci-yes (skip the one-time auth prompt)
Questions: class clarify (Phase 0.5 action menu): headless (no question tool or chat turn), print the menu and stop; pass --commit, --push or --pr. Class confirm-publish (Step 22a "run --ci against the existing PR?", Phase 6 CI authorization): headless and without --ci-yes, skip CI monitoring and print rerun with --ci-yes. Class confirm-publish (backport-label question): headless, add no label and print the /ycc:backport hint. See ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/question-policy.md.
Tool Preference (before Phase 0)
If tools matching mcp__github__* exist, use MCP for GitHub operations (PR create/view/list); otherwise use gh via Bash. git operations, the skill scripts, and file reading always use Bash and the Read/Grep/Glob tools regardless.
Phase Checklist
- Phase 0 Analyze (Steps 1–3):
git status/diff,scripts/analyze-changes.sh, group changes. - Phase 0.5 Resolve action set (Step 3.5): below.
- Phase 1 Strategy (Steps 4–5): small (1–3 files, single feature) → direct; large (4+ files, multiple features, breaking/API changes) → agents;
--dry-runreport then STOP. - Phase 2 Documentation decision (Steps 6–7): skip if
--no-docs, internal refactor, test-only, docs-only, or trivial. - Phase 3a Direct commit (Steps 8–12) or Phase 3b Agent deployment (Steps 13–18), gated on
commit ∈ actions. - Phase 4 Summary and push (Steps 19–21), push gated on
push ∈ actions. - Phase 5 PR (Steps 22–31), gated on
pr ∈ actions. - Phase 6 CI monitoring (Steps 32–37), gated on
--ci.
Phase 0.5: Resolve Action Set (Step 3.5)
Every later phase keys off the action set.
Start
actionsfrom explicit flags (commit,push,pr).Apply implications:
praddspushandcommit;pushaddscommit.If empty:
--ci ∈ flags: leave empty, skip the menu (bare--ci: only Phase 6 runs; Phases 3, 4, 5 skip).Otherwise show this menu and wait; reject other replies and re-prompt. Map
1 → {commit},2 → {commit, push},3 → {commit, push, pr}:No action flag provided. What do you want to do? 1) Commit only 2) Commit and push 3) Commit, push, and create PR Reply with 1, 2, or 3 (or pass --commit / --push / --pr next time).
Validate:
--draftwithoutpr: stop with "--draftrequires--pr. Re-run with--pr --draft, or omit--draft."--base <branch>withoutpr: stop with "--baserequires--pr."--ciwithactions == {commit}: hard-stop with--ci requires --push or --pr (CI runs on the remote, so local-only commits can't be monitored). Pass --ci alone to skip commits and monitor an existing PR.--ciwith--dry-run: hard-stop with--ci is incompatible with --dry-run; the loop performs real pushes.
Record the set.
--dry-runand--no-docsapply regardless of the set.
Phases 0–4 (commit flow)
Read references/commit-phases.md before Phase 0 for exact commands, the dry-run report template, the documentation rules, the commit-message steps, the docs-git-committer agent prompt, agent-result validation (including the git rebase -x check), and the summary template. Key decisions:
- Strategy: direct commit vs parallel agents (single message, multiple Agent calls, one
docs-git-committerper scope; todos per agent). - Read
templates/documentation-decision.md(Step 6),templates/commit-types.md(Step 8),templates/agent-prompts.md(Step 14) when the step is reached. - Documentation: feature docs only for new user-facing features, significant API changes, complex flows, breaking changes; directory-level
CLAUDE.mdonly for critical directory-specific patterns. - Step 12/21:
git pushonly whenpush ∈ actions.
Phase 5: Pull Request (Steps 22–31)
Only when pr ∈ actions. Read references/pr-creation.md before Step 22. Decision points:
- Step 22a: existing PR → with
--ci, ask whether to skip creation and run Phase 6 against it (noexits cleanly, no Phase 6); without--ci, stop with the "PR already exists" message. - Step 22b: resolve
$BASE, run the sync-check guard (exit 3: no PR, stop), offer backport, per${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/pr-base-and-backport.md. Exit 2 (malformedRELEASING.md) stops with the parse error and/ycc:release-model --audit. - Step 23: read
templates/pr-template.md. - Step 25: PR title must be Conventional Commit format and pass
validate-commit.sh. - Step 28: MCP
mcp__github__create_pull_requestfirst,gh pr createfallback; forge routing via${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/forge-detection.md(teafor forgejo/gitea). - Step 27: draft when work is incomplete or feedback is wanted; honor
--draft.
Phase 6: CI Monitoring (Steps 32–37)
Only when --ci ∈ flags. Read references/ci-monitoring-phase.md before Step 32, and ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/ci-monitoring.md (authoritative policy: classification, termination, audit log, loop protocol) at Step 33. GitHub-only: RESULT=unsupported-provider is reported and skipped without error. No PR number: hard-stop. Authorization prompt unless --ci-yes. Branch on RESULT=: green → report; handoff → fix, validate, commit, push head branch, loop; rerun-pending → sleep 30, loop, no fix; bail-* → diagnosis, end; pr-not-found / refused-default-branch → surface, no retry. Print the Goal Signals block verbatim as the last lines of the run (PR_IN_SCOPE, PR_URL_PRINTED, CI_GREEN, CI_BAIL_VISIBLE); criteria are in that reference.
/goal Pairing
Pair /goal only in --ci mode. Read references/goal-pairing.md for keep-looping/done/stop semantics and the condition template, and ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/goal-pairing.md before relying on a /goal loop.
Quality, Examples, Troubleshooting
Read references/examples-and-troubleshooting.md for the commit/docs/agent/PR/overall checklists, eight worked examples, and failure fixes (validation failures, MCP fallback, gh install/auth, no upstream, existing PR, draft-to-ready). Key reminders: small changes direct, large changes agents; atomic commits; draft PRs for WIP; PR creation needs MCP or authenticated gh.
Reference Map
references/commit-phases.md— read before Phase 0.references/pr-creation.md— read before Step 22.references/ci-monitoring-phase.md— read before Step 32.references/goal-pairing.md— read when pairing with/goal.references/examples-and-troubleshooting.md— read for checklists, examples, or when a step fails.templates/commit-types.md,templates/documentation-decision.md,templates/agent-prompts.md,templates/pr-template.md— read at Steps 8, 6, 14, 23.scripts/analyze-changes.sh(Step 2),scripts/validate-commit.sh(Steps 10, 18, 25, 36),scripts/create-pr.sh(Step 24;--analyze --base "$BASE"; defensive existing-PR check).- Shared:
${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/{forge-detection,pr-base-and-backport,ci-monitoring,goal-pairing}.md,${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/{pr-guard,ci-monitor}.sh.branch-prep.mddoes not apply: this skill never creates branches.