Git Workflow
Remotes
Branch Strategy
| Branch |
Purpose |
Pushes To |
development |
Active working branch — all daily work lands here |
origin/development |
main |
Stable branch — CI runs here, deploy candidates |
origin/main |
All daily development happens on development. Use PRs from development to main when ready to trigger CI and prepare a release.
Commit Message Format
<type>(<scope>): <description>
<optional body>
| Field |
Values |
| type |
feat, fix, refactor, docs, test, chore, perf, ci |
| scope |
App name or feature area (e.g., auth, dashboard, billing) |
Before Pushing
Run your verification suite as a pre-push gate. Skipping it means broken code reaches origin:
npm run verify # typecheck + lint + test
If verify fails, fix issues before pushing.
CI Pipeline
Pull Request Workflow
When creating PRs:
- Analyze full commit history (not just latest commit)
- Use
git diff [base-branch]...HEAD to see all changes
- Draft comprehensive PR summary
- Include test plan with TODOs
- Push with
-u flag if new branch
Upstream Merge Process (Template Updates)
Feature Implementation Workflow
- Plan — Use
/create-plan to generate phases and structure
- Review Plan — Use
/review-plan to verify each phase
- Implement — Use
/implement to execute phases (handles TDD, coding, review loop)
- Code Review — Use
/code-review after implementation to verify quality
- Verify — Run verification suite before committing
- Commit — Follow conventional commits format with scope
1---2name: 1393-git-workflow-9a5c77263description: Git Workflow4---5# Git Workflow67## Remotes89<!-- CUSTOMIZE: Configure your git remotes.1011| Remote | URL | Purpose |12|--------|-----|---------|13| `origin` | `github.com/{your-org}/{your-repo}.git` | Your repository |14| `upstream` | (optional) | Third-party template source for updates |15-->1617## Branch Strategy1819| Branch | Purpose | Pushes To |20|--------|---------|-----------|21| `development` | Active working branch — all daily work lands here | `origin/development` |22| `main` | Stable branch — CI runs here, deploy candidates | `origin/main` |2324<!-- CUSTOMIZE: Adjust branch names and strategy to match your team's workflow.25Some teams use `dev`/`staging`/`main`, others use feature branches with PRs to `main`. -->2627All daily development happens on `development`. Use PRs from `development` to `main` when ready to trigger CI and prepare a release.2829## Commit Message Format3031```32<type>(<scope>): <description>3334<optional body>35```3637| Field | Values |38|-------|--------|39| **type** | `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci` |40| **scope** | App name or feature area (e.g., `auth`, `dashboard`, `billing`) |4142## Before Pushing4344Run your verification suite as a pre-push gate. Skipping it means broken code reaches `origin`:4546<!-- CUSTOMIZE: Replace with your project's verify command. -->4748```bash49npm run verify # typecheck + lint + test50```5152If verify fails, fix issues before pushing.5354## CI Pipeline5556<!-- CUSTOMIZE: Update to match your CI configuration.5758Typical CI jobs for Next.js/Supabase projects:5960| CI Job | What it does | Timeout |61|--------|-------------|---------|62| TypeScript | `typecheck` + `lint` | 10 min |63| Unit Tests | `npm test` | 10 min |64| E2E Tests | Playwright | 20 min |65-->6667## Pull Request Workflow6869When creating PRs:70711. Analyze full commit history (not just latest commit)722. Use `git diff [base-branch]...HEAD` to see all changes733. Draft comprehensive PR summary744. Include test plan with TODOs755. Push with `-u` flag if new branch7677## Upstream Merge Process (Template Updates)7879<!-- CUSTOMIZE: If you forked a SaaS template, document your merge process here.8081Key steps:821. `git fetch upstream`832. Check what changed: `git log --oneline $(git merge-base development upstream/main)..upstream/main`843. Create merge branch: `git checkout -b merge/upstream-<version> development`854. Merge: `git merge upstream/main --no-commit`865. Resolve conflicts (prioritize upstream for infrastructure, keep yours for custom features)876. Verify and commit8889If you have multiple product apps forked from the same template, remember to propagate90infrastructure changes to ALL apps, not just the primary one.91-->9293## Feature Implementation Workflow94951. **Plan** — Use `/create-plan` to generate phases and structure962. **Review Plan** — Use `/review-plan` to verify each phase973. **Implement** — Use `/implement` to execute phases (handles TDD, coding, review loop)984. **Code Review** — Use `/code-review` after implementation to verify quality995. **Verify** — Run verification suite before committing1006. **Commit** — Follow conventional commits format with scope
tools-only