Team-Scale Workflow Enhancements

On this page

Context

CRAIG’s contribution workflow now covers the individual contributor lifecycle: issue creation, branching, implementation, testing, MR, closing, and cleanup. It also covers coordination primitives: work claiming, code review, CODEOWNERS, migration ordering, and API contract stability.

This plan addresses the remaining items needed for a medium-sized team (30 contributors, mixed human and agent) to work effectively without stepping on each other.

Status

Planned — not yet started.

Items

1. Release Process

Problem: No defined process for cutting releases, generating changelogs, or deciding when main is releasable.

Deliverables:

  • Define version numbering: v0.PHASE.PATCH (e.g., v0.12.3 for Phase 12, third patch)

  • Changelog generation: script that collects MR titles since last tag, grouped by label (feat/fix/chore)

  • Release checklist: all tests green, no open P0/P1 issues, security dashboard clear, docs current

  • GitLab Release creation with tag + changelog

  • Add release label and document release workflow in CONTRIBUTING.adoc

Files:

  • scripts/changelog.sh — changelog generator from git log + MR titles

  • CONTRIBUTING.adoc — new "Release Process" section

  • .claude/CLAUDE.md — add release rules to Workflow section

2. Communication Protocols

Problem: No defined channels for design discussions, cross-service coordination, or breaking announcements.

Deliverables:

  • Design decisions: Use GitLab issues with design label for proposals. Decisions recorded as ADRs in docs/modules/ROOT/pages/adrs/.

  • Cross-service changes: When changing events schema, shared crate APIs, or Keycloak config, create a chore: heads-up issue listing affected services and tag their CODEOWNERS. Do this BEFORE the MR, not after.

  • Breaking announcements: Comment on affected open issues/MRs. For devstack changes that require restart, add a note to the MR description: "Requires cargo xtask dev restart after pulling main."

  • Document in CONTRIBUTING.adoc under "Communication" section.

Files:

  • CONTRIBUTING.adoc — new "Communication" section

  • .claude/CLAUDE.md — add cross-service coordination rule to Workflow section

3. Onboarding

Problem: New contributors (human or agent) have setup docs but no guidance on where to start or how to ramp up.

Deliverables:

  • Add good-first-issue label (green, scoped) — tag simple, well-defined issues

  • Create "Onboarding" section in CONTRIBUTING.adoc:

    • Read list: CONTRIBUTING.adoc → developer-guide.adoc → architecture.adoc → relevant service docs

    • First task: pick a good-first-issue

    • Who to ask: tag @bitskrieg on any issue for help

    • For agents: read .claude/CLAUDE.md (auto-loaded), then CONTRIBUTING.adoc

  • Create 3-5 starter issues tagged good-first-issue (e.g., add missing unit tests, improve error messages, add CLI --help examples)

Files:

  • CONTRIBUTING.adoc — new "Onboarding" section

  • .claude/CLAUDE.md — add onboarding reference

  • GitLab: create good-first-issue label + starter issues

4. Deployment Workflow

Problem: No documented path from "main is green" to "running in production." Currently devstack-only.

Deliverables:

  • Document target deployment architecture (Kubernetes? Docker Compose on a VM? Cloud Run?)

  • Define environments: dev (devstack), staging (CI-deployed), production

  • CI pipeline stages: build → test → staging deploy → smoke test → manual production gate

  • Health check endpoints already exist (/healthz) — document monitoring expectations

  • Secrets management: document where credentials live (not in code, not in env vars committed to repo)

Files:

  • docs/modules/ROOT/pages/deployment-guide.adoc — already exists, needs expansion

  • .gitlab-ci.yml — add staging deploy stage (when infrastructure is ready)

  • CONTRIBUTING.adoc — reference deployment guide

This item depends on infrastructure decisions that haven’t been made yet. The plan should be refined once a hosting platform is chosen.

5. Stale Work Policies

Problem: MRs and issues can sit indefinitely without activity. At 30 people, this creates confusion about what’s in progress vs. abandoned.

Deliverables:

  • Stale MR policy: MRs with no activity for 14 days get a bot comment asking for status. After 28 days, auto-close with stale label. Author can reopen.

  • Stale issue policy: Assigned issues with no branch/MR activity for 14 days: assignee is pinged. After 28 days: unassign so others can claim.

  • Draft MR timeout: Draft MRs older than 30 days without activity are closed.

  • Implement via GitLab’s triage policies (.gitlab/triage-policies.yml) or scheduled pipeline.

Files:

  • .gitlab/triage-policies.yml — triage bot configuration

  • .gitlab-ci.yml — scheduled pipeline for triage

  • CONTRIBUTING.adoc — document stale policies

6. Service Ownership Registry

Problem: CODEOWNERS handles reviewer auto-assignment but doesn’t document who is the domain expert, who approves architecture changes, or who to escalate to.

Deliverables:

  • Create docs/modules/ROOT/pages/service-ownership.adoc — table mapping each service to: owner, backup, domain description, key design decisions, escalation contact

  • Link from developer-guide.adoc and CONTRIBUTING.adoc

  • Update as team grows

Files:

  • docs/modules/ROOT/pages/service-ownership.adoc — new file

  • docs/modules/ROOT/nav.adoc — add nav entry

  • CONTRIBUTING.adoc — reference in "Onboarding" section

Implementation Order

  1. Release process — needed as soon as we want to tag v0.1.0

  2. Communication protocols — prevents cross-service surprises

  3. Onboarding — reduces friction for new contributors

  4. Stale work policies — keeps the issue board clean

  5. Service ownership registry — formalizes implicit knowledge

  6. Deployment workflow — blocked on infrastructure decisions

Verification

Each item should be:

  • Documented in CONTRIBUTING.adoc (human audience)

  • Documented in .claude/CLAUDE.md (agent audience) where applicable

  • Tested by having a new agent or human follow the docs without additional guidance

Edit this page · latest