Git Workflow

Branch model

main          ← production gate; auto-deploys :prod image
  └── develop ← staging gate; auto-deploys :staging image
        └── feature/*, fix/*, chore/* ← short-lived work branches

Rules:

main and develop are protected — no direct push
Feature branches merge into develop via fast-forward or --no-ff merge commit
develop → main is the only prod gate; done via PR for audit trail
Solo dev exception: feature branches may merge directly to develop without a PR

Branch naming

{type}/{short-description}

Type	Use
`feature/`	New functionality
`fix/`	Bug fixes
`chore/`	Tooling, deps, config
`docs/`	Documentation only
`refactor/`	Code restructure without behaviour change
`perf/`	Performance work

Keep slugs lowercase, hyphen-separated, under 40 characters.

Examples:

feature/woodpecker-agent-taxonomy
fix/supabase-rls-policy
chore/update-dependencies

Commit message format

<type>: <description>

<optional body — explain WHY, not what>

Types: feat, fix, refactor, docs, test, chore, perf, ci

Rules:

First line ≤ 72 characters
Imperative mood: “add”, “fix”, “remove” — not “added”, “fixes”
No trailing period
Body separated from subject by blank line
Body explains motivation / context, not mechanics

Examples:

feat: add Woodpecker agent persistent config volume

Without a named volume at /etc/woodpecker, the agent re-registers
as a new identity on every container restart, creating ghost entries
in the admin UI.

fix: correct Supabase RLS policy for group_members

Private schema helpers must be called as private.get_my_role()
not get_my_role() — private isn't on the default search_path.

Solo dev workflow

For single-developer projects, the full PR review loop is skipped on develop. The flow is:

Cut a feature branch from develop
Implement and commit
Merge directly to develop: git merge --no-ff feature/xyz
Push — staging auto-deploys via Woodpecker
Verify on staging
Open a PR from develop → main as the prod gate

The develop → main PR exists for: diff review before prod, audit trail, rollback reference point.

Tagging and releases

Tags are applied to main after merge. Format: v{major}.{minor}.{patch} (semver).

git tag -a v1.3.0 -m "Phase 1C: badges and cosmetics"
git push origin v1.3.0

Increment	Trigger
`patch`	Bug fixes, no schema changes
`minor`	New features, backwards-compatible schema changes
`major`	Breaking changes, major architectural shifts

.gitignore standards

Every project must gitignore:

.env
.env.*
!.env.example
*.local
node_modules/
dist/
.tmp/

Scratch files and temporary snippets go in .tmp/ — never in src/, scripts/, or project root.

Commit attribution

CI commits (automated, from pipeline scripts):

Co-Authored-By: Woodpecker CI <ci@level147.net>

Claude Code-assisted commits: no co-author attribution (disabled globally in ~/.claude/settings.json).