Skip to content

team-setup-guide.md

Latest commit

 

History

History
177 lines (115 loc) · 5.85 KB

team-setup-guide.md

File metadata and controls

177 lines (115 loc) · 5.85 KB
Raw

Team Setup Guide

Using GAAI across a team of engineers.

The Core Tension

GAAI's memory and backlog are files in your repo. This is intentional — it makes them versionable, reviewable, and auditable. It also means teams need conventions around who edits what and when.

What Goes in Git

Always commit:

  • .gaai/project/ — all project-specific data:
    • contexts/rules/ — project rule overrides
    • contexts/memory/project/context.md — project fundamentals
    • contexts/memory/patterns/conventions.md — conventions
    • contexts/backlog/active.backlog.yaml — current backlog
    • contexts/backlog/done/ — completed work archive
    • contexts/artefacts/ — all artefact files
  • .gaai/core/ — framework files (managed via git subtree sync)

Consider carefully:

  • .gaai/project/contexts/memory/decisions/_log.md — accumulates quickly; commit on milestones, not every session

Do not commit:

  • Session notes or draft artefacts that haven't passed validation
  • Memory snapshots (archives generated by memory-snapshot.sh)

Branching Model

Simple model (small teams, fast pace)

Everything on main. Team members coordinate by:

  • Locking backlog items with status: in-progress (only one person per item)
  • Using scripts/backlog-scheduler.sh to pick next item (avoids collisions)

Feature branches (standard teams)

main
├── feat/BL-042-rate-limiting    ← one Story per branch
├── feat/BL-043-export-csv
└── feat/discovery-auth-flows    ← Discovery output (artefacts only, no code)

Branch naming: {type}/{backlog-id}-{short-title}

Merge rule: a Story branch may only be merged when status: done and QA has passed.

Backlog coordination

The backlog is a shared file. Concurrent edits are merge conflicts.

Conventions:

  • Only the item owner (the engineer doing the work) marks their item in-progress
  • Discovery output (new refined Stories) merges through a short-lived discovery/* branch
  • Done items are archived on merge to main

Discovery Sessions in Teams

Discovery is human-facing. In teams, Discovery sessions produce artefacts that the whole team can review before Delivery starts.

Recommended flow

  1. Engineer or PM activates Discovery for a new feature
  2. Discovery produces Epics, Stories, acceptance criteria
  3. Artefacts are committed to a discovery/* branch
  4. Team reviews artefacts via PR (not code review — artefact review)
  5. On approval: Stories are added to active.backlog.yaml with status: refined
  6. Branch merges to main
  7. Any engineer can now pick up a Story for Delivery

This makes Discovery output a first-class engineering artifact — reviewable, commentable, traceable.

Parallel Delivery

Multiple engineers can run Delivery loops in parallel, each on a separate Story.

Requirements:

  • Each Story has a unique id in the backlog
  • Each engineer works on a separate branch
  • Backlog item is marked in-progress before work starts (prevents collision)

The scripts/backlog-scheduler.sh helps coordinate without stepping on each other:

# Start of session: see what's available
.gaai/core/scripts/backlog-scheduler.sh --list active.backlog.yaml

# Pick what to work on next (highest priority, unblocked, not in-progress)
.gaai/core/scripts/backlog-scheduler.sh --next active.backlog.yaml

# See full dependency tree — who is waiting on whom
.gaai/core/scripts/backlog-scheduler.sh --graph active.backlog.yaml

# Sprint planning: find priority misalignments before they cause delays
.gaai/core/scripts/backlog-scheduler.sh --conflicts active.backlog.yaml

The --graph view is especially useful for parallel delivery: it shows at a glance which Stories are unblocked (✅), which are in flight (🔄), and which are waiting on a dependency (🔒). Teams can use this to assign work without accidentally pulling a Story whose dependency is still blocked.

Rule Ownership

Rules are team decisions. Treat them like architecture decisions.

Who can change rules: any engineer, but changes need review (same as architecture changes).

How to propose a rule change:

  1. Edit the relevant rule file
  2. Open a PR titled: rules: [short description]
  3. Engineers review and comment
  4. On merge, the rule takes effect for all subsequent agent sessions

This prevents rule drift and ensures the team's conventions stay explicit and aligned.

Shared Memory

Memory files in git are shared knowledge. Some guidelines:

memory/project/context.md — owned by the team lead or principal engineer. Changes require review.

memory/patterns/conventions.md — living document. Any engineer can propose changes via PR. Represents the team's current conventions.

memory/decisions/_log.md — append-only. Engineers add to it after significant decisions. Archive old entries quarterly.

Onboarding New Team Members

When a new engineer joins:

  1. Clone the repo (they get .gaai/ automatically)
  2. Run: bash .gaai/core/scripts/health-check.sh — verifies framework integrity
  3. Read: .gaai/README.md — 2 minutes, then .gaai/GAAI.md — 5 minutes
  4. Read: .gaai/project/contexts/memory/project/context.md — project context
  5. Read: .gaai/project/contexts/memory/patterns/conventions.md — team conventions
  6. First task: pick a refined Story from the backlog, run Delivery

The memory files are the onboarding documentation. Keep them accurate.

CI Integration

See Senior Engineer Guide for full CI setup.

Minimum recommended CI gate:

- name: GAAI structure validation
  run: bash .gaai/core/scripts/health-check.sh

Add artefact sync validation for regulated projects:

- name: GAAI artefact sync
  run: bash .gaai/core/scripts/artefact-sync.sh

→ Senior Engineer Guide → Contexts Reference