Team Collaboration with Waymaker Sync

How Teams Work Together

Waymaker Sync enables multiple team members to collaborate on the same project, sharing a workspace, taskboard, and documentation. This guide explains how it all works together.

The Golden Rule

Git is the source of truth. Waymaker Sync is a synchronization layer on top of it.

This means:

• Your existing Git workflow stays exactly the same
• Git handles merges, conflicts, history, and branches
• Waymaker Sync handles real-time task state and UI representation
• Your work is never lost—it's always in Git

┌─────────────────────────────────────────────────────────────┐
│                     Git Repository                           │
│                   (Source of Truth)                          │
│                                                              │
│   docs/02-working/tasks/implement-auth.md                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Waymaker Sync Layer                       │
│                                                              │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│   │   Alice     │  │    Bob      │  │   Carol     │         │
│   │   (IDE)     │  │   (IDE)     │  │ (Commander) │         │
│   └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Setting Up Your Team

What Everyone Shares

When your team uses Waymaker Sync on the same project, everyone connects to:

Shared Resource	Purpose
Git Repository	Single source of truth for all files
Commander Workspace	Organization-level container
Project	The specific project in Commander
Taskboard	Where tasks appear and get managed

Individual Setup

Each team member needs to:

1. Clone the repository

   git clone https://github.com/your-org/your-project.git
   cd your-project
   

2. Install and authenticate the CLI

   npm install -g @waymakeros/cli
   waymaker auth login
   

3. Initialize the project (only needed once per clone)

   waymaker init
   # Select the same workspace, project, and taskboard
   

4. Start syncing

   waymaker sync start
   

The .commander/config.json file should be committed to Git so everyone uses the same settings.

How Multi-User Sync Works

Scenario: Two Developers Edit the Same Task

Setup:

• Alice and Bob both have the project cloned
• Both have waymaker sync running
• Carol is using Commander in her browser

What happens when Alice edits a task file:

1. Alice modifies docs/02-working/tasks/auth-feature.md in her IDE
2. Her waymaker sync daemon detects the change
3. The task updates in Commander (status, description, etc.)
4. Bob sees the updated task in Commander immediately
5. Carol sees it too in her browser
6. Alice commits and pushes to Git

What happens when Bob also edits the same file:

Layer	What Happens
Git	Normal merge/conflict resolution when Bob pushes
Waymaker Sync	Both see real-time task status updates in Commander
Commander	Shows current state from most recent sync

Conflict Resolution

File Content Conflicts (Git Handles This)

When two people edit the same file content:

# Alice pushes first
git push origin main  # ✓ Success

# Bob pushes second
git push origin main  # ✗ Rejected (needs merge)

# Bob pulls and resolves
git pull origin main  # May have merge conflict
# Bob resolves in editor
git push origin main  # ✓ Success

This is standard Git workflow—nothing special about Waymaker here.

Task Metadata Conflicts (Last Write Wins)

When the same task's status/priority is updated by multiple users:

1. Commander stores the most recent state
2. Full history is preserved in Git (file history)
3. Frontmatter shows who last synced:

---
sync:
  type: task
  status: in-progress      # Most recent update wins
  last_synced: 2026-02-04T10:30:00Z
  last_synced_by: carol
---

Why last-write-wins? Task status is ephemeral—what matters is current state, not status history. Git preserves the full document history if you need to audit.

Team Workflow Patterns

Pattern 1: Small Team (2-4 people)

Everyone works on main, pulls frequently:

Alice (IDE + Sync) ──┐
                     ├──► main branch ──► Commander
Bob (IDE + Sync) ────┘

Best practices:

• Pull before starting work each day
• Communicate when working on the same task
• Use layers to organize by person or area

Pattern 2: Larger Team (5+ people)

Feature branches with pull request workflow:

Alice ──► feature/auth ──┐
                         ├──► main ──► Commander (production tasks)
Bob ────► feature/api ───┘

Best practices:

• Main branch reflects production tasks
• Feature branches for work-in-progress
• Merge to main when tasks are ready for the team

Pattern 3: Mixed Team (Developers + Non-Developers)

Developers use IDE + Sync, others use Commander web UI:

Developers (IDE + Sync) ──► Git ──► Commander
                                        ▲
Product Manager ────────────────────────┘
   (Commander web UI only)

Best practices:

• Developers own the markdown files
• Product/management updates status in Commander UI
• Sync brings Commander changes back to files

What Syncs Where

Data Type	Syncs Via	Conflict Handling
File content (task body)	Git	Git merge
Task status	Waymaker Sync	Last write wins
Task priority	Waymaker Sync	Last write wins
Task assignment	Commander	Last write wins
Layer association	Waymaker Sync	Last write wins
Comments	Commander	Append-only (no conflicts)
File history	Git	Full history preserved

Best Practices for Teams

Communication

1. Discuss active tasks - If two people work the same task, talk about it
2. Use layers for ownership - "Alice's Tasks", "Sprint 42", "Backend"
3. Check Commander before deep work - See what's already in progress

Git Hygiene

1. Pull before you push - Prevents most conflicts
2. Commit frequently - Smaller commits = easier merges
3. Push at logical points - End of task, end of day

Sync Configuration

1. Commit .commander/config.json - Everyone uses same settings
2. Agree on folder structure - Use consistent 02-working/tasks/ layout
3. Standardize frontmatter - Same status values, same layer naming

Troubleshooting

"I don't see my teammate's changes"

1. Check they pushed to Git: git log origin/main
2. Pull latest: git pull origin main
3. Check your sync is running: waymaker sync status

"Task shows wrong status after merge"

The frontmatter might have conflicting values. Check the file:

head -20 docs/02-working/tasks/the-task.md

If status is wrong, either:

• Edit the frontmatter manually
• Update status in Commander (will sync back)

"Duplicate tasks appeared"

This can happen if the same file was synced before receiving a sync_id. Check frontmatter:

---
sync:
  type: task
  sync_id: "abc123"  # If missing, duplicates can occur
---

Delete duplicates in Commander, then run waymaker sync all to re-sync with proper IDs.

"Conflict between my changes and Commander"

Waymaker Sync is designed to be non-destructive:

• IDE changes always go to Git (never lost)
• Commander changes update the database
• Frontmatter bridges the two

If you see unexpected state:

# Check git history
git log --oneline docs/02-working/tasks/the-task.md

# Force re-sync from IDE
waymaker sync all --force

Security & Permissions

Who Can Sync?

Anyone with:

• Write access to the Git repository
• Member of the Commander workspace
• Authenticated via waymaker auth login

Access Levels

Level	Can Do
Workspace Member	Sync tasks, update status
Workspace Admin	Above + manage taskboards
Org Admin	Above + manage workspace settings

Sync respects Commander permissions—you can't sync to a taskboard you don't have access to.

Next Steps

• Sync Command Reference - Detailed sync options
• Project Organization - Folder structure for teams
• AI Agent Setup - MCP server for AI assistants

---

Questions about team setup? Contact support at help.waymakerone.com