x-push-branch

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Commit and Push

Purpose

Standardizes the Git workflow for {{PROJECT_NAME}}. Every feature starts with a branch and ends with a clean commit history following Conventional Commits.

Triggers

• /x-push-branch — commit and push current changes
• /x-push-branch branch-name — create branch, commit, and push
• /x-push-branch "commit message" — commit with message and push

Workflow

1. BRANCH     -> Create or verify feature branch
2. COMMIT     -> Stage and commit with Conventional Commits format
3. PUSH       -> Push to remote with tracking
4. PR         -> Create pull request (if applicable)

Step 1 — Branch Strategy

main (production, tagged releases only)
  +-- hotfix/short-description
develop (integration, always green)
  +-- feat/story-XXXX-YYYY-short-description       (parent/story branch)
  |     +-- feat/task-XXXX-YYYY-NNN-short-desc      (task branch)
  +-- release/vX.Y.Z

1.1 — Branch Naming

Task Branch (Task-Centric Model)

Pattern: feat/task-XXXX-YYYY-NNN-short-desc

Component	Format	Example
XXXX	4-digit epic ID	0029
YYYY	4-digit story ID	0015
NNN	3-digit task sequence (001-999)	001
short-desc	lowercase-hyphenated description	implement-phase2

Rules:

• Maximum 60 characters total (truncate description to fit, preserving whole words)
• All characters must be [a-z0-9/-] (lowercase, digits, hyphens, forward slashes)
• No underscores, no camelCase
• Prefix with feat/ (or fix/, refactor/ as appropriate)

Examples:

• feat/task-0029-0015-001-implement-phase2 (41 chars)
• fix/task-0029-0015-002-null-check-guard (40 chars)

Parent Branch (Auto-Approve Mode)

Pattern: feat/story-XXXX-YYYY-short-desc

Rules:

• Maximum 60 characters total
• Created from develop; task branches are created from this parent
• Used when --auto-approve-pr is active in x-implement-story

Example: feat/story-0029-0015-lifecycle (30 chars)

Story Branch (Legacy/Standard)

Pattern: feat/story-XXXX-YYYY-short-kebab-description

Rules:

• Always prefix with feat/ (or fix/, refactor/ as appropriate)
• Include the story/issue identifier
• Short description in kebab-case (English)
• Maximum 100 characters total

Branch Name Validation

Rule	Validation	Error
Epic ID (XXXX)	4 numeric digits	"Invalid epic ID: must be 4 digits"
Story ID (YYYY)	4 numeric digits	"Invalid story ID: must be 4 digits"
Task seq (NNN)	3 numeric digits (001-999)	"Invalid task sequence: must be 3 digits"
Description	lowercase, hyphens only	"Invalid description: use lowercase-hyphenated"
Task branch length	<= 60 chars total	"Branch name exceeds 60 chars: truncating description"
Characters	[a-z0-9/-] only	"Invalid characters in branch name"

1.2 — Creating a Branch

Task branch (from parent or develop):

git checkout feat/story-XXXX-YYYY-description  # or develop
git pull
git checkout -b feat/task-XXXX-YYYY-NNN-short-desc

Story/parent branch (from develop):

git checkout develop
git pull origin develop
git checkout -b feat/story-XXXX-YYYY-description

Step 2 — Commit Convention (Conventional Commits)

2.1 — Format

<type>(<scope>): <subject>

<optional body>

<optional footer>

2.2 — Types

Type	When to use
feat	New feature
test	Adding or modifying tests only
fix	Bug fix
refactor	Restructuring without behavior change
docs	Documentation changes
build	Build system changes
chore	Maintenance tasks
infra	Infrastructure and deployment changes

2.3 — Scopes

Task-centric scope (preferred for task branches):

Use TASK-XXXX-YYYY-NNN as the scope when working on a task branch:

feat(TASK-0029-0015-001): implement task execution loop [TDD:GREEN]

Module-based scope (for non-task work):

Use the module, package, or component name as scope. Define project-specific scopes based on the architecture (e.g., domain, rest, persistence, config).

2.4 — Rules

1. Atomic commits — one logical change per commit
2. Subject line — max 72 characters, imperative mood ("add" not "added"), no period at end
3. Body — optional; explain "why" not "what"; wrap at 72 characters
4. Tests with features — feature commits should include their tests

Step 3 — Workflow Per Story

3.1 — Starting a Story

git checkout develop
git pull origin develop
git checkout -b feat/story-XXXX-YYYY-description
git status

3.2 — During Implementation

Make frequent, atomic commits:

git add src/main/path/to/Feature.{{LANGUAGE}}
git add src/test/path/to/FeatureTest.{{LANGUAGE}}
git commit -m "feat(TASK-XXXX-YYYY-NNN): add feature description [TDD]"

For non-task branches, use module-based scopes:

git commit -m "feat(scope): add feature description"

3.3 — Finishing a Story

# 1. Run full build
{{BUILD_COMMAND}}

# 2. Review changes
git log --oneline develop..HEAD
git diff develop...HEAD --stat

# 3. Push
git push -u origin feat/story-XXXX-YYYY-description

Step 4 — Hotfix Workflow

Hotfixes branch from main and merge back to both main and develop.

4.1 — Starting a Hotfix

git checkout main
git pull origin main
git checkout -b hotfix/short-description

4.2 — Committing and Pushing

git add src/main/path/to/Fix.{{LANGUAGE}}
git add src/test/path/to/FixTest.{{LANGUAGE}}
git commit -m "fix(scope): description of critical fix"
git push -u origin hotfix/short-description

4.3 — Creating Hotfix PR

gh pr create \
  --base main \
  --title "fix(scope): description of critical fix" \
  --body "$(cat <<'EOF'
## Summary
<Description of the critical fix>

## Test plan
- [ ] Build passes (`{{BUILD_COMMAND}}`)
- [ ] Fix verified in production-like environment
EOF
)"

4.4 — Back-merge to Develop

After the hotfix is merged to main, propagate the fix to develop:

git checkout main
git pull origin main
gh pr create \
  --base develop \
  --title "chore: back-merge hotfix to develop" \
  --body "Propagates hotfix from main to develop."

Step 5 — Pull Request

5.1 — Task PR Creation

When creating a PR for a task branch:

gh pr create \
  --base feat/story-XXXX-YYYY-description \
  --title "feat(TASK-XXXX-YYYY-NNN): description" \
  --body "$(cat <<'EOF'
## Summary
<1-3 bullet points describing what was built>

Story: story-XXXX-YYYY
Epic: epic-XXXX
Task Plan: ai/epics/epic-XXXX/plans/task-plan-XXXX-YYYY-NNN.md

## Changed Files

| File | Layer | Change |
|------|-------|--------|
| `src/domain/model/Entity.{{LANGUAGE}}` | domain | Added |
| `src/adapter/outbound/EntityRepo.{{LANGUAGE}}` | adapter | Modified |

## TDD Summary
- RED-GREEN-REFACTOR cycles: N
- Test count: N unit, N integration

## Checklist
- [ ] Build passes (`{{BUILD_COMMAND}}`)
- [ ] Coverage thresholds met
- [ ] All acceptance criteria covered
EOF
)"

5.2 — Story PR Creation (Legacy/Standard)

When creating a PR for a story or non-task branch:

gh pr create \
  --base develop \
  --title "feat(scope): implement story-XXXX-YYYY -- title" \
  --body "$(cat <<'EOF'
## Summary
<1-3 bullet points describing what was built>

## Test plan
- [ ] Build passes (`{{BUILD_COMMAND}}`)
- [ ] Coverage thresholds met
- [ ] All acceptance criteria covered
EOF
)"

5.3 — PR Title Convention

Task PR format:

• Format: <type>(TASK-XXXX-YYYY-NNN): description
• Max length: 70 characters
• Example: feat(TASK-0029-0015-001): implement Phase 2 task loop

Story PR format (legacy):

• Format: feat(scope): implement story-XXXX-YYYY -- short title
• Max length: 70 characters

5.4 — PR Body Requirements (Task PRs)

Section	Content	Required
Story reference	Story: story-XXXX-YYYY	Yes
Epic reference	Epic: epic-XXXX	Yes
Task plan link	Task Plan: ai/epics/epic-XXXX/plans/task-plan-XXXX-YYYY-NNN.md	Optional
Changed files	Table with file path, layer, and change type	Yes
TDD summary	Number of RED/GREEN/REFACTOR cycles	Yes
Checklist	DoD items from the task	Yes

5.5 — Useful Commands

gh pr list
gh pr view <number>
gh pr checks <number>
gh pr merge <number> --squash --delete-branch

Step 6 — Tagging Releases

git tag -a v0.1.0 -m "Milestone description"
git push origin v0.1.0

Step 7 — TDD Commit Format

When following TDD, use these commit format variants:

Format	When to use
feat(scope): implement [behavior] [TDD]	Recommended default. Complete Red-Green(-Refactor) cycle in one commit: test + implementation (+ trivial refactor)
test(scope): add test for [behavior] [TDD:RED]	Optional, fine-grained. Test-only Red phase; must be paired with a [TDD:GREEN] commit before push
feat(scope): implement [behavior] [TDD:GREEN]	Optional, fine-grained. Implementation-only Green phase; must immediately follow a paired [TDD:RED] commit
refactor(scope): [improvement] [TDD:REFACTOR]	Optional. Non-trivial refactor-only commit (no new behavior), immediately after the corresponding Green commit

The combined format [TDD] is the recommended default for most work: one green commit per complete Red-Green(-Refactor) cycle. Use the separate [TDD:RED], [TDD:GREEN], [TDD:REFACTOR] tags only when finer granularity in the git history is needed, and always keep RED/GREEN commits paired (no orphaned test-only commits on shared branches).

TDD tags are additive suffixes — they do not replace the Conventional Commits type. All existing types (feat, test, fix, refactor, docs, build, chore, infra) remain valid.

Step 8 — Atomic TDD Commit Rules

1. Default: one combined commit per Red-Green-Refactor cycle — use the [TDD] suffix for a complete cycle in a single commit
2. Test and implementation in the SAME commit — RED-only [TDD:RED] commits are allowed locally for fine-grained work, but must be paired with a corresponding [TDD:GREEN] commit before push (no orphaned test-only commits on shared branches)
3. Refactoring may be a separate commit for non-trivial changes — use [TDD:REFACTOR] immediately after the Green commit, adding no new behavior
4. Each commit adds ONE testable behavior — keep changes focused and reviewable
5. Maximum ~50 lines changed per commit — larger commits should be split into smaller TDD cycles

Step 9 — Git History Storytelling

The sequence of commits should tell the story of TDD progression from simple to complex:

1. First commit: acceptance test + test infrastructure setup
2. Following commits: incremental unit tests following Transformation Priority Premise (TPP) order
   • Degenerate / nil cases first
   • Constants, then variables
   • Simple conditionals, then iterations
   • Complex / composition cases last
3. Final commits: refactoring and polish (no new behavior)

The git log should read as a progression from the simplest case to the most complex, making the development process transparent and reviewable.

Error Handling

Scenario	Action
Uncommitted changes when creating branch	Stash or commit before switching
Push rejected (remote ahead)	Pull with rebase, then push again
Merge conflict during rebase	Report conflict files, suggest resolution
PR creation fails (no remote branch)	Push branch first, then retry PR creation
Build fails before push	Abort push, report build errors

Integration Notes

Skill	Relationship	Context
x-implement-story	called-by	Phase 0 (branch from develop) and Phase 5 (push + PR to develop)
x-implement-task	called-by	Atomic TDD commits during implementation
x-release	called-by	Release commit and tag creation
x-commit-changes	delegates-to	Commit creation with task ID scope and TDD tags
x-create-pr	delegates-to	PR creation with task references and body template

• Hotfix workflow branches from main and creates PRs targeting main, then back-merges to develop
• Can be used standalone for any git workflow task
• For task branches, commit scope MUST use TASK-XXXX-YYYY-NNN format
• For non-task branches, commit scope should match the project's package/module structure
• Task PRs target the parent story branch; story PRs target develop