Push Assistant | 推送助手

Language: English | 繁體中文

Version: 2.0.0 Created: 2026-04-23 Applicability: Claude Code Skills

---

AI-assisted safety layer for git push. Detects protected branches, enforces force-push guardrails, runs pre-push quality gates, outputs a structured push receipt, and integrates with PR automation.

git push 的 AI 輔助安全層。偵測保護分支、強制 force-push 護欄、執行 pre-push 品質 gate、輸出結構化推送收據，並整合 PR 自動化。

Core Standard | 核心標準

This skill implements .standards/push-standards.ai.yaml.

---

Workflow | 執行工作流程

When /push is invoked, Claude executes the following steps natively:

Step 1: Detect Protected Branch

Run git rev-parse --abbrev-ref HEAD to get current branch. Compare against protected_branches list (default: main, master, release/, hotfix/). If protected: show warning + pending commits, require explicit user confirmation before proceeding.

Step 2: Detect Force Push

If --force or --force-with-lease flag detected: Run git log origin/<branch>..HEAD --oneline to find commits that will be overwritten. Show count and author list. Require user to type yes, force push to proceed.

Step 3: Run Pre-Push Quality Gates

Run each configured gate in sequence using Bash tool:

• lint: detect and run project lint command
• test: detect and run project test command
• type-check (optional): TypeScript type check
• ac-coverage (optional): acceptance criteria coverage
• security-scan (optional): security vulnerability scan

If any required gate fails: abort with error message.

Step 4: Execute Push

Run git push <remote> <branch> [--force]. If push fails: show git error and suggest remediation.

Step 5: Emit Push Receipt

Output structured receipt to console (and optionally to ~/.uds/push-history.jsonl):

{
  "branch": "<branch>",
  "commit_sha": "<sha>",
  "gates_passed": ["lint", "test"],
  "force_push": false,
  "timestamp": "<ISO8601>",
  "target_remote": "origin"
}

Step 6: PR Integration

If auto_pr=true AND repo_mode=team AND no open PR exists for this branch: Suggest running /pr-automation-assistant to create a Pull Request.

---

Features | 功能說明

1. Push Target Risk Detection | 推送目標風險偵測

Before pushing, the assistant detects whether the target branch is a protected branch (e.g., main, master, release/*, hotfix/*).

推送前偵測目標分支是否為保護分支（例如 main、master、release/*、hotfix/*）。

• Displays a warning with branch name and commit list
• Requires explicit user confirmation before proceeding
• Aborts push if user does not confirm

2. Force-Push Guardrails | Force-Push 護欄

When --force is detected, shows the impact before allowing execution.

偵測到 --force 時，推送前顯示影響範圍。

• Calculates commits that will be overwritten on remote
• Shows count and authors of overwritten commits
• Requires user to type a confirmation string (yes, force push)
• Records force_push: true in the push receipt

3. Pre-Push Quality Gates | Pre-Push 品質 Gate

Runs configured quality gates in sequence before pushing.

推送前依序執行已設定的品質 gate。

Gate	Description	說明
lint	Run project lint command	執行 lint 檢查
test	Run project test command	執行測試
type-check	TypeScript type checking (optional)	TypeScript 型別檢查（選用）
ac-coverage	Acceptance criteria coverage check (optional)	AC 覆蓋率檢查（選用）
security-scan	Security vulnerability scan (optional)	安全掃描（選用）

4. Push Receipt | 推送收據

After a successful push, outputs a structured receipt for audit trail purposes.

推送成功後輸出結構化收據，供稽核追蹤使用。

{
  "branch": "feature/my-feature",
  "commit_sha": "a1b2c3d",
  "gates_passed": ["lint", "test"],
  "gates_skipped": false,
  "force_push": false,
  "timestamp": "2026-04-23T10:00:00Z",
  "target_remote": "origin"
}

Optionally appended to ~/.uds/push-history.jsonl for persistent audit trail.

可選擇附加到 ~/.uds/push-history.jsonl 以持久化稽核追蹤。

5. PR Automation Integration | PR 自動化整合入口

After pushing a feature branch, prompts user to create a Pull Request if none exists.

推送 feature branch 後，若尚無 PR，提示使用者建立 Pull Request。

• Checks if an open PR exists for the branch
• Prompts user to run pr-automation-assistant
• Skipped in single-owner repo mode or when --no-pr flag is used

---

Usage | 使用方式

# Standard push (runs quality gates automatically)
/push

# Push with force (shows overwritten commits, requires confirmation)
/push --force

# Push to a specific remote branch
/push --target main

# Skip quality gates (emergency use)
/push --skip-gates

# Push without PR prompt
/push --no-pr

# Force push without PR prompt (e.g., updating a personal branch)
/push --force --no-pr

Arguments | 參數說明

Argument	Description	說明
--force	Enable force push with guardrail checks	啟用 force push，含護欄確認
--target <branch>	Specify target remote branch explicitly	明確指定目標遠端分支
--skip-gates	Skip pre-push quality gates (emergency only)	跳過品質 gate（僅緊急情況）
--no-pr	Suppress PR automation prompt after push	推送後不提示建立 PR

---

Configuration | 設定

Configure via uds.project.yaml:

push:
  repo_mode: team           # "team" | "single-owner"
  protected_branches:
    - main
    - master
    - "release/*"
    - "hotfix/*"
  push_gates:
    default:
      - lint
      - test
    optional:
      - type-check
      - ac-coverage
      - security-scan
  receipt:
    output: console          # "console" | "file" | "both"
    file_path: "~/.uds/push-history.jsonl"
  auto_pr: true              # prompt to create PR after push to non-protected branch

Options | 選項模式

Option File	Mode	Description	說明
options/push/team-mode.md	team	Full collaboration guardrails (default)	完整協作護欄（預設）
options/push/single-owner-mode.md	single-owner	Reduced friction for personal repos	個人 repo 低摩擦模式

---

Next Steps Guidance | 下一步引導

After /push completes, the AI assistant should suggest:

推送完成。建議下一步 / Push complete. Suggested next steps:

• 執行 /pr-automation-assistant 建立或更新 Pull Request ⭐ Recommended / 推薦 — 確保協作流程完整 / Ensure complete collaboration workflow
• 執行 /checkin 確認程式碼簽入品質 — 下次提交前的品質確認 / Quality verification before next commit
• 查看 ~/.uds/push-history.jsonl 確認推送紀錄 — 稽核追蹤 / Audit trail verification

---

Related Standards | 相關標準

• Push Standards — Core push safety rules
• Git Workflow — Branching strategy
• Commit Message — Commit conventions
• PR Automation — Pull Request automation

---

Version History | 版本歷程

Version	Date	Changes
2.0.0	2026-04-28	Restore workflow execution steps (XSPEC-097 採用層解耦); remove deprecation notice
1.0.0	2026-04-23	Initial release — XSPEC-081 Phase 1

---

License | 授權

This skill is released under MIT License and CC BY 4.0.

Source: universal-dev-standards