Skip to content

Workflow Rules

GitLab-first issue-driven workflow. Extracted from ~/CLAUDE.md.

Issue-first workflow (mandatory for feature/bugfix work)

  1. Find or create a GitLab issue at gitlab.com/blueflyio (project 860 for the platform).
  2. On the issue page, click Create merge request — GitLab creates the branch + MR and auto-links them.
  3. git fetch origin
  4. Work on the authoritative rig on Oracle: ssh [email protected] → /home/ubuntu/gt/<rig>/. There is no __BARE_REPOS/. (Or: buildkit gitlab start <issue-number>.)
  5. Commit and push from the clone. The MR auto-updates; merge auto-closes the issue.

Worktree discipline

  • Authoritative repos are rigs on Oracle at /home/ubuntu/gt/<rig>/ — there is no __BARE_REPOS/.
  • If you use git worktree, create it outside the product rig. Never create .claude/worktrees/ inside a rig — product rigs must stay clean (per BLUEFLY_FILESYSTEM_AUTHORITY_RULE).
  • Worktree paths are ephemeral — never hard-code them in aliases or scripts.
  • No worktree without a Bead. Never create a git worktree for exploratory or ad hoc work. Every worktree must trace to an open Bead (bd show <id>) that justifies the work.
  • Naming convention (mandatory): [BEAD_ID]-[PROJECT_NAME]-[AGENT_NAME], e.g. hq-7rue-agent-buildkit-blu. AGENT_NAME is the actual operating identity for the session (e.g. blu, or the assigned role name such as local-engineer) — never the generic harness/model name (claude). A bare project name (agent-buildkit, dragonfly) with no Bead ID or agent name is non-compliant; rename or recreate it before doing further work in it.
  • Remove a worktree once its Bead's MR is merged (or once the Bead is closed/superseded) — verify git status --short is clean and the branch is actually merged first, then trash it. Don't leave merged-and-done worktrees sitting on disk.

Branch naming

  • bugfix/<descriptor> — bug fixes (preferred for blu-cli; GitLab rejects fix/... in some repos)
  • feature/<n>-<descriptor> — new features (feat/ and fix/ are rejected by blu-cli's pre-receive regex)
  • chore/<descriptor> — maintenance / hygiene
  • release/v<x>.<y>.<z> — release branches
  • Always check the target repo's convention before naming

SSH remote (binding)

  • Bluefly Git remotes MUST use git@gitlab-bluefly:blueflyio/<group>/<repo>.git
  • Never [email protected]: or [email protected]: (literal hostname is wrong)
  • If .git/config has the wrong form, flag it; do not silently push to it
  • Rewrite is operator-authorized only

Commit discipline

  • Path-scoped git add <specific-files> — never git add -A or git add .
  • Single-purpose commits, reviewable in isolation
  • Commit message: conventional commits (feat:, fix:, chore:, test:, etc.)
  • Lefthook commit-msg gate must pass (conventional-commits, max-length)

BuildKit CLI

  • buildkit (npm @bluefly/agent-buildkit) is the standard interface for FS/git/test ops
  • buildkit <command> --help lists subcommands
  • Common: buildkit gitlab start|list|finish, buildkit test drupal, buildkit golden-audit, buildkit gitlab status
  • Install via GitLab npm registry: npm i -g @bluefly/agent-buildkit

Session closure

  • Push validated local work before session termination
  • If validation incomplete: explicitly defer with documented rationale
  • Never push failing CI / pre-push gate failures

Governance/hygiene exception

  • Pure docs-sync / persona-reconciliation / file-layout cleanup may skip GitLab issue ceremony if operator approves the commit message directly. Default rule (issue-first) still holds for feature / bugfix / behavior-change work.