| name | github-flow |
| description | GitHub Flow branching and collaboration workflow for hardbox. Use when creating a feature branch, opening or reviewing a pull request, naming branches, writing commit messages, preparing a release, resolving conflicts, or enforcing PR conventions. |
| compatibility | Designed for Claude Code and any Agent Skills-compatible agent |
| metadata | {"author":"hardbox-io","version":"0.1","argument-hint":"Describe the task (e.g. 'new feature branch for firewall module', 'PR for ssh fix', 'release v0.2.0')"} |
GitHub Flow — hardbox Workflow
When to Use
- Creating or naming a feature/fix/chore branch
- Writing a commit message
- Opening, reviewing, or merging a pull request
- Resolving merge conflicts or rebasing
- Preparing a release tag
1. Core Principle
main is always deployable. Every change — no matter how small — flows through a branch and a pull request.
main ──────●──────────────────────────────●────
\ /
●──●──●──● (feature branch)
\
PR → review → merge → delete
2. Branch Naming
Format: <type>/<short-description> (lowercase kebab-case)
| Type | Purpose | Example |
|---|
feat/ | New feature or module | feat/firewall-module |
fix/ | Bug fix | fix/ssh-audit-panic |
chore/ | Tooling, deps, CI | chore/update-golangci |
refactor/ | Restructuring, no behavior change | refactor/engine-errors |
test/ | Tests only | test/ssh-coverage |
docs/ | Documentation only | docs/modules-reference |
release/ | Release preparation | release/v0.2.0 |
Rules:
- Always branch from
main (pull latest first)
- Lowercase kebab-case only — no camelCase, no underscores, no issue numbers
- Delete branch after merge
git checkout main && git pull
git checkout -b feat/firewall-module
See: references/branching.md
3. Commit Messages (Conventional Commits)
<type>(<scope>): <short description>
[body — explain WHY, not what. wrap at 72 chars]
[footer: Fixes #123]
Types: feat, fix, chore, refactor, test, docs, perf, ci
Scope: package/module name (ssh, engine, tui, config, ci)
Examples:
feat(ssh): add PermitRootLogin check (ssh-001)
fix(engine): prevent nil deref on empty module list
chore(ci): pin golangci-lint to v1.57
test(ssh): add table-driven tests for ParseSSHConfig
4. Pull Request Workflow
- Push branch:
git push -u origin feat/firewall-module
- Open PR targeting
main
- PR title follows Conventional Commits format
- Fill the PR description (see template below)
- Pass all CI checks before requesting review
- At least 1 approval required before merge
- Squash and Merge — keeps
main history linear
- Delete branch after merge
PR Description Template
## What
<!-- One-paragraph summary -->
## Why
Fixes #<issue-number>
## How
<!-- Implementation approach -->
## Testing
- [ ] `go test ./... -race` passes
- [ ] Manual: `sudo ./bin/hardbox audit --profile cis-level1`
- [ ] Module registered in `registry.go` (if applicable)
- [ ] `docs/MODULES.md` updated (if applicable)
## Checklist
- [ ] Branch branched from `main`
- [ ] Conventional Commits format
- [ ] `go vet ./...` passes
- [ ] `golangci-lint run` passes
- [ ] Atomic write pattern for any file writes
See: references/pr-workflow.md
5. Keeping Branch Up to Date
git fetch origin
git rebase origin/main
git add <file>
git rebase --continue
Always rebase (not merge) to keep history clean.
6. Release Flow
git checkout main && git pull
git checkout -b release/v0.2.0
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0
References
