gstack/docs/TEAM_SYNC_SETUP.md

Team Sync Setup Guide

Team sync lets your team share eval results, retro snapshots, QA reports, ship logs, and Greptile triage data via a shared Supabase store. All sync is optional and non-fatal — without it, everything works locally as before.

Prerequisites

• A Supabase project (free tier works)
• gstack v0.3.10+

Step 1: Create a Supabase project

1. Go to supabase.com and create a new project
2. Note your Project URL (e.g., https://xxxx.supabase.co)
3. Note your anon/public key from Settings > API

Step 2: Run migrations

In the Supabase SQL Editor, run these files in order:

supabase/migrations/001_teams.sql
supabase/migrations/002_eval_runs.sql
supabase/migrations/003_data_tables.sql
supabase/migrations/004_eval_costs.sql
supabase/migrations/005_sync_heartbeats.sql

Copy-paste each file's contents into the SQL editor and run.

Step 3: Create your team

In the SQL editor, create a team and add yourself:

-- Create team
INSERT INTO teams (name, slug) VALUES ('Your Team', 'your-team-slug');

-- After authenticating (Step 5), add yourself as owner:
-- INSERT INTO team_members (team_id, user_id, role)
-- VALUES ('<team-id>', '<your-user-id>', 'owner');

Note the team slug — you'll need it in the next step.

Step 4: Configure your project

Copy the example config to your project root:

cp .gstack-sync.json.example .gstack-sync.json

Edit .gstack-sync.json with your Supabase details:

{
  "supabase_url": "https://YOUR_PROJECT.supabase.co",
  "supabase_anon_key": "eyJ...",
  "team_slug": "your-team-slug"
}

Important: Add .gstack-sync.json to .gitignore if it contains sensitive keys, or commit it if your team uses the same Supabase project (the anon key is safe to commit — RLS protects the data).

Step 5: Authenticate

gstack-sync setup

This opens your browser for Supabase OAuth. After authenticating, tokens are saved to ~/.gstack/auth.json (mode 0600).

For CI/automation: Set the GSTACK_SUPABASE_ACCESS_TOKEN env var instead of running setup.

Step 6: Verify

gstack-sync test

Expected output:

gstack sync test
────────────────────────────────────
  1. Config:        ok (team: your-team-slug)
  2. Auth:          ok (you@email.com)
  3. Push:          ok (123ms)
  4. Pull:          ok (1 heartbeats, 95ms)
────────────────────────────────────
  Sync test passed ✓

Step 7: See your data

gstack-sync show              # team summary dashboard
gstack-sync show evals        # recent eval runs
gstack-sync show ships        # recent ship logs
gstack-sync show retros       # recent retro snapshots
gstack-sync status            # sync health check
bun run eval:trend --team     # team-wide test trends

How it works

When sync is configured, skills automatically push data after completing their primary task:

• /ship pushes a ship log after PR creation (Step 8.5)
• /retro pushes the snapshot after saving to .context/retros/ (Step 13)
• /qa pushes a report after computing the health score (Phase 6)
• /review pushes Greptile triage entries after history file writes
• Eval runs are pushed automatically by EvalCollector.finalize()

All pushes are non-fatal. If sync fails, entries are queued in ~/.gstack/sync-queue.json and retried on the next push or via gstack-sync drain.

Troubleshooting

Problem	Fix
"No .gstack-sync.json found"	Copy .gstack-sync.json.example and fill in your values
"Not authenticated"	Run gstack-sync setup
Push fails with 404	Run the migration SQL files in order
"Connection failed"	Check your Supabase URL and that the project is running
Queue growing	Run gstack-sync drain to flush

Adding team members

Each team member needs to:

1. Have .gstack-sync.json in their project (commit it or share it)
2. Run gstack-sync setup to authenticate
3. Be added to team_members in Supabase (by an admin)