Team Workflow

Fresh

Overview

The team workflow covers how multiple developers share a single knowledge graph through Git, keeping everyone's AI assistant on the same page.

Architecture

flowchart TD
    Dev1[Developer A] -->|commits graph| Remote[Git Remote]
    Dev2[Developer B] -->|pulls graph| Remote
    Dev3[Developer C] -->|pulls graph| Remote
    Remote --> GH[graph.json]
    GH --> A[Dev A assistant]
    GH --> B[Dev B assistant]
    GH --> C[Dev C assistant]

Setup

Step 1: Designate the Initial Graph Builder

One person builds the initial graph:

cd your-project
/graphify .
git add graphify-out/graph.html graphify-out/graph.json graphify-out/GRAPH_REPORT.md
git commit -m "chore: add initial knowledge graph"
git push

Step 2: All Team Members Pull

git pull

Everyone now has graphify-out/ and can query immediately — no build required.

Step 3: Install Assistants

Each developer installs their preferred platform integration:

graphify claude install    # Claude Code
graphify codex install     # Codex/OpenCode
graphify cursor install    # Cursor

Step 4: Configure .gitignore

# Commit the graph files, not the cache
graphify-out/cache/

Update Strategy

Option A: Git Hook (Recommended)

Install the post-commit hook so the graph updates automatically on every commit:

graphify hook install

See Git Automation for full details.

Option B: Manual Updates by Designated Maintainer

One team member owns graph maintenance and runs updates before releases:

/graphify . --update
git add graphify-out/
git commit -m "chore: update knowledge graph"
git push

Option C: CI Pipeline

Add to your CI workflow:

# .github/workflows/graph.yml
name: Update Knowledge Graph
on:
  push:
    branches: [main]
    paths-ignore:
      - 'graphify-out/**'
jobs:
  update-graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - run: pip install graphifyy
      - run: graphify . --update --no-viz
      - run: |
          git config user.email "ci@yourcompany.com"
          git config user.name "CI"
          git add graphify-out/graph.json graphify-out/GRAPH_REPORT.md
          git commit -m "chore: auto-update knowledge graph [skip ci]" || echo "No changes"
          git push

Team Benefits

Benefit	How It Works
Instant onboarding	New team member clones repo, gets full graph context immediately
Shared vocabulary	God Nodes become shared architectural vocabulary for the team
Consistent answers	All assistants query the same graph, giving consistent architectural guidance
No duplicate analysis	Only one person (or CI) needs to run the LLM extraction

Conflict Resolution

If two developers update the graph simultaneously, Git will conflict on graph.json. The correct resolution is always:

# Accept either version and rebuild
/graphify . --update
git add graphify-out/
git commit -m "resolve graph conflict"

graph.json is a derived artifact — treat conflicts by rebuilding, not merging JSON manually.

Monorepo Setup

In a monorepo, run graphify per-service and commit each service's graphify-out/ separately. This keeps graph contexts scoped to their relevant service boundaries.