Branching & Deployment

````instructions
---
name: branching-and-deployment
description: 'Operate a simplified Git branching strategy end-to-end: create branches, verify code, push safely, and deploy via CI/CD. Use when requests mention git, branches, pushing code, pull requests, merges, deployment, CI pipelines, Vercel, commit messages, or any source-control operation.'
---

# Branching & Deployment

> **Agent-agnostic** — this skill works with any AI coding agent (Claude Code, GitHub Copilot, Codex, Cursor, Windsurf, etc.). All instructions use standard CLI tools and scripts.

## Overview

Manage source control with a simplified branching strategy. Two long-lived
branches: `main` (production) and `develop` (integration). AI agents push only
to feature branches; humans own merges, PRs, and deployments.
Prioritize pre-push verification over speed — a broken `main` costs more than
a delayed push.

## Follow This Workflow

### 1. Validate prerequisites

- Confirm you are on a feature branch (`feat/*`, `fix/*`, `doc/*`, etc.).
- Confirm the branch tracks a remote (or will be pushed for the first time).
- Confirm you are **not** on `main` or `develop`.

```powershell
.github/skills/branching-and-deployment/scripts/check-branch.ps1
```

### 2. Verify code before pushing

**PowerShell (Windows / cross-platform):**

```powershell
.github/skills/branching-and-deployment/scripts/pre-push-verify.ps1
```

With full diagnostics:

```powershell
.github/skills/branching-and-deployment/scripts/pre-push-verify.ps1 -Verbose
```

**Bash (Linux / macOS):**

```bash
pnpm lint && pnpm build
git status
git log --oneline -3
```

### 3. Push using the push script

```powershell
.github/skills/branching-and-deployment/scripts/safe-push.ps1 -Message "feat(data): add 5 new backend skills"
```

Or manually after verification:

```bash
git add <files>
git commit -m "<type>(scope): description"
git push origin <current-branch>
```

### 4. Report push result

After each push, confirm:
- Branch name pushed to
- Commit hash
- Verification results (lint, build)
- Any warnings or skipped checks

## Deferred Push Rule

**AI agents do NOT push code immediately after completing work.**

When you finish implementing a prompt/task:
1. **Stage and commit locally** but do NOT push.
2. **Report what was done** and wait for the user's next instruction.
3. When the user gives you the **next prompt**, push the previous commit **first**, then start the new work.
4. If the user explicitly says "push it" or "push now", push immediately.

This gives the user a chance to review, amend, or discard changes before they reach the remote. The only exception is when the user explicitly asks you to push.

## Use These Decision Rules

| Situation | Action |
| --- | --- |
| Finished a task | Commit locally, do NOT push — wait for user |
| User gives next prompt | Push previous commit first, then start new work |
| User says "push" explicitly | Push immediately after verification |
| Need to push code | Run `pre-push-verify.ps1` first, then `safe-push.ps1` |
| Creating a new branch | Run `check-branch.ps1` to validate naming |
| Unsure about code quality | **DO NOT PUSH** — run verification and fix issues first |
| Merge conflict | Inform the human developer — never force-push |
| Need to deploy | Inform the human — only `main` pushes trigger deploys |
| Commit message format | Read `references/commit-conventions.md` |
| Branch naming format | Read `references/branch-strategy.md` |

## Critical Rules for AI Agents

### What You CAN Do

- Push commits to the **current feature branch** only
- Run builds and lints locally to verify the pipeline will pass
- Create new files including workflow files
- Create new branches from the current HEAD

### What You MUST NEVER Do

- **NEVER merge branches** (no `git merge`)
- **NEVER create pull requests** (no GitHub PR API calls)
- **NEVER push to `main` or `develop`**
- **NEVER force-push** (`git push --force`)
- **NEVER delete remote branches**
- **NEVER push code unless you are 100% CERTAIN it is correct**
- **NEVER push immediately after finishing work** — commit locally and wait for user instruction

### The 100% Certainty Rule

**ONLY push code when ALL of the following are true:**

- All verification steps passed with ZERO errors
- You understand exactly what changed and why
- The code follows project patterns and conventions
- No experimental or uncertain code is included
- You would confidently explain these changes to a senior engineer

**IF YOU HAVE ANY DOUBT → DO NOT PUSH**

> The human developer handles all merges, PRs, branch cleanup, and deployments.

## Script Parameters

### `scripts/pre-push-verify.ps1`

| Parameter | Description |
| --- | --- |
| `-ProjectDir` | Repository root to verify (default: `.`) |
| `-SkipLint` | Skip the lint step |
| `-SkipBuild` | Skip the build step |
| `-SkipForbiddenPatterns` | Skip checking for `console.log` and other forbidden patterns |
| `-Verbose` | Show detailed output for each verification step |
| `-PackageManager` | Package manager to use: `pnpm`, `npm`, or `yarn` (default: auto-detect) |

### `scripts/safe-push.ps1`

| Parameter | Description |
| --- | --- |
| `-Message` | Commit message (must follow Conventional Commits format) |
| `-Files` | Files to stage (default: all modified tracked files) |
| `-SkipVerify` | Skip pre-push verification (use with caution) |
| `-DryRun` | Show what would happen without actually pushing |
| `-AllowUntracked` | Also stage untracked files matching the specified paths |
| `-Force` | Override the branch protection check (**DANGEROUS** — never use on protected branches) |

### `scripts/check-branch.ps1`

| Parameter | Description |
| --- | --- |
| `-Name` | Branch name to validate (default: current branch) |
| `-CreateFrom` | Create a new branch from this base (e.g., `develop`) |
| `-Type` | Branch type: `feat`, `fix`, `doc`, `refactor`, `chore`, `ci`, `style`, `test` |
| `-Description` | Branch description slug (e.g., `add-resource-search`) |

## Report Results in This Format

```
Branch: feat/add-resource-search
Lint: passed (0 errors)
Build: passed (XX static pages)
Forbidden patterns: none found
Git state: clean (no uncommitted changes)
Commit: abc1234 — feat(data): add 5 new backend skills
Push: success → origin/feat/add-resource-search
```

## Escalate Only When Needed

- Escalate merge conflicts — never resolve by force-pushing.
- Escalate if the current branch is `main` or `develop`.
- Escalate if verification fails and you cannot determine the fix.
- Escalate if the remote has diverged and a rebase/pull is needed.

## References

- Branch strategy and flow diagrams: `references/branch-strategy.md`
- Conventional Commits format and examples: `references/commit-conventions.md`
- CI/CD pipeline stages and triggers: `references/ci-cd-pipeline.md`
- Environment matrix and secrets: `references/environments.md`

````