Team Workflow

Team Workflow

Everything in SpecGit works identically for one person or twenty. What changes on a team is coordination: whose policy is authoritative, how a delivery maps onto branches and PRs, and what review actually reviews.

One delivery = one branch + N issues + one PR + required checks

That aggregate is the team's unit of work and the unit of acceptance:

• Branch or worktree. The delivery happens on one branch; parallel checkouts (worktrees) on that branch are equivalent. No delivery ever spans branches.
• Issues. Everything the delivery is "for" is an issue number in the record — one or many. The issues carry intent and scope; SpecGit only verifies they exist and are closed by the PR.
• One PR. The delivery merges through exactly one pull request. Its body's closing references are the contractual link back to the issues.
• Required checks. The policy is the shared definition of "CI passed" — one list of check names, enforced by branch protection and by SpecGit identically.

The policy is the team contract

spec_git/policy.yaml is committed on the default branch and reviewed like code:

• Adding a required check (say, a new security scan) is a PR that changes the policy and the branch-protection settings together. After it merges, every delivery must pass the new check before acceptance.
• Removing a required check is equally deliberate — SpecGit fails closed on an empty list, so nobody can silently turn acceptance into a no-op.

A delivery's lifecycle

issue(s) filed --> specgit issue (branch + draft PR + record) --> commits --> push
                                                                                   |
        specgit finish <--- closing refs + green checks <--------------------------+
              |
              |-- accepted --> merge --> specgit unbind (or delete .specgit.yaml)
              |-- rejected --> fix what the gates named, re-run finish
              +-- unknown  --> fix record/policy/auth, re-run finish

The record (.specgit.yaml) is committed on the delivery branch, so the binding travels with the work: anyone who checks the branch out — including worktrees on their own machine — can run specgit status and specgit finish and get the same verdict.

The PR flow

1. specgit issue "<type>: <title>" creates the issues, the branch, and the draft PR with the deterministic scaffold (Closes #n for every bound issue, then Why / What changed / Evidence / Checklist).
2. Fill in the scaffold sections as you deliver. The placeholders are advisory — the closing references are the only body gate. The PR body is written once at creation; no SpecGit command edits an existing PR body, and the repository's own PR template is never read.
3. A draft PR always fails the verdict (pr_draft): before specgit finish, mark it ready for review — gh pr ready <number> on GitHub, glab mr update <number> --ready on GitLab.
4. The CI gate (.github/workflows/specgit-accept.yml) runs specgit finish --json on every PR. Keep the Closes #n references intact; after changing the PR body, head branch, or CI, re-run specgit finish.
5. Finish with specgit finish locally: exit 0 is the only "done". Exit 1 = fix what the gates named; exit 3 = fix the environment first (specgit doctor). Never weaken spec_git/policy.yaml to make a verdict pass.

What review reviews

Acceptance answers "is the delivery complete and verified?" Review answers "should this delivery exist at all?" Reviewers therefore look at:

1. The linked issues (from the record's issues) — is this the right scope?
2. The diff — the usual engineering review.
3. The binding itself — does the PR really close those issues? Is the context branch the one being reviewed?

SpecGit removes the bookkeeping from review (no task checklists to audit, no artifact status to trust) and leaves the substance.

Conventions that work well

• Branch naming. Anything works; <type>/<issue>-<slug> (e.g. fix/124-flaky-tests) keeps the context self-describing and matches worktree labels.
• Bind early, complete later. A record with issues but no PR is a valid draft; specgit status shows it as such. Binding early makes the delivery discoverable.
• Re-run finish after every CI run. The verdict is a fact about now; treat it like that in conversation ("accept was green as of the last push").
• Delete the record after merge. specgit unbind --yes keeps merged branches clean if they linger; the binding has already done its job at merge time.

---

Chinese version: Team-Workflow-zh