jwill9999/git-workflow

Git workflow

Current state

• Branch: !git branch --show-current
• Remote status: !git status -sb | head -1
• Recent commits: !git log --oneline -5

User instructions

$ARGUMENTS

---

Branch structure

main
└── feat/e{N}-{epic-name}           ← epic branch (PR → main)
    ├── feat/e{N}-t{M}-{task-name}  ← task sub-branch (PR → epic branch)
    └── feat/e{N}-t{M}-{task-name}

Examples: feat/e4-agent-plugin-mulch, feat/e4-t1-mulch-adapter

---

Step-by-step workflow

1. Start of epic — create epic branch from main

git checkout main && git pull
git checkout -b feat/e{N}-{epic-name}

2. Start of each task — create task sub-branch from epic branch

git checkout feat/e{N}-{epic-name}
git checkout -b feat/e{N}-t{M}-{task-name}

3. Complete a task — commit, push, open PR to epic branch (not main)

git add . && git commit -m "feat(e{N}-t{M}): description

Co-authored-by: Copilot <[email protected]>"
git push -u origin feat/e{N}-t{M}-{task-name}
gh pr create --base feat/e{N}-{epic-name} --title "feat(e{N}-t{M}): description"

Human reviews the PR. Do not self-merge. Wait for approval.

4. All tasks complete — pre-merge local test

git checkout feat/e{N}-{epic-name}
npx nx run-many -t typecheck,lint,test,build --all

5. Open epic PR to main

git push -u origin feat/e{N}-{epic-name}
gh pr create --base main --title "feat: Epic {N} — {Epic Name}" --body "..."

6. After merge to main — changelog + version bump

git checkout main && git pull
git-cliff --output CHANGELOG.md
# Bump version in: package.json, packages/*/package.json
# Also update the static version badge in README.md: ![version](https://img.shields.io/badge/version-X.X.X--alpha.0-blue)
# (Replace with npm badge once packages are published to npm)
git add CHANGELOG.md package.json packages/*/package.json README.md
git commit -m "chore: update CHANGELOG.md and bump to 0.{N+1}.0-alpha.0"
git push

---

Commit message format

<type>(scope): short description

Types: feat | fix | docs | chore | refactor | test | ci
Scope: e.g. e4-t1, agent-core, agent-plugin-mulch

Always include:

Co-authored-by: Copilot <[email protected]>

---

Changelog

• CHANGELOG.md at the repo root — auto-generated by git-cliff (cliff.toml at root)
• Never edited manually

---

Package versioning (lockstep)

All package.json (root + packages/*/package.json) carry the same version.

| Stage | Format | When | | ------------------ | --------------- | ---------------- | | Active development | 0.x.0-alpha.0 | Now | | Feature complete | 0.x.0-beta.0 | All 9 epics done | | Release candidate | 1.0.0-rc.0 | Tested + docs | | Stable | 1.0.0 | Production ready |

Minor version increments per completed epic (e.g. Epic 4 merges → 0.4.0-alpha.0).