Organizing Your Project for Sync

Before You Sync

Running waymaker sync start on a disorganized project can create chaos. This guide helps you prepare your documentation before enabling sync.

Recommended Folder Structure

Waymaker Sync works best with a structured documentation approach:

your-project/
├── docs/
│   ├── 00-archive/          # Old docs, superseded content
│   ├── 01-planning/         # PRDs, strategy, requirements
│   │   ├── product-requirements/
│   │   ├── strategy/
│   │   └── features/
│   ├── 02-working/          # Active development
│   │   ├── prompts/
│   │   │   ├── active/      # Current sprint work
│   │   │   ├── backlog/     # Future work
│   │   │   └── completed/   # Finished implementations
│   │   ├── sessions/        # Session briefs
│   │   └── tasks/           # Task files (sync target)
│   ├── 03-knowledge/        # Patterns, architecture, decisions
│   │   ├── patterns/
│   │   ├── architecture/
│   │   └── gotchas/
│   ├── 04-operations/       # Runbooks, debugging guides
│   │   ├── deployment/
│   │   ├── debugging/
│   │   └── runbooks/
│   └── 05-reference/        # API docs, tech stack, constants
└── .commander/
    └── config.json          # Created by waymaker init

Frontmatter for Sync

Files need YAML frontmatter to sync properly. Add this block at the top of markdown files:

Task Files (sync as tasks to taskboard)

---
sync:
  type: task
  taskboard: "your-taskboard-id"
  status: backlog
  priority: medium
---
# Task Title

Task description here...

Document Files (sync as documents to Explorer)

---
sync:
  type: document
  status: draft
  tags:
    - architecture
    - api
---
# Document Title

Content here...

Epic/Layer Files (creates layer hierarchy)

---
sync:
  type: epic
  layer: "Product/Sprint 1"
  methodology: agile
---
# Sprint 1 Goals

Sprint objectives...

Organizing Before Sync

Step 1: Audit Your Docs

Run this to see what you have:

find docs -name "*.md" | wc -l          # Count markdown files
find docs -name "*.md" -exec head -5 {} \;  # Check for frontmatter

Step 2: Choose What to Sync

Not everything needs to sync. Configure watch patterns in .commander/config.json:

{
  "sync": {
    "watch_patterns": [
      "docs/02-working/tasks/**/*.md",
      "docs/02-working/prompts/active/**/*.md"
    ],
    "ignore_patterns": [
      "docs/00-archive/**",
      "docs/05-reference/**"
    ]
  }
}

Step 3: Add Frontmatter Gradually

Don't try to add frontmatter to everything at once. Start with:

1. Active tasks in docs/02-working/tasks/
2. Current prompts in docs/02-working/prompts/active/
3. Session briefs in docs/02-working/sessions/

Step 4: Test with Dry Run

waymaker sync all --dry-run

This shows what would sync without making changes.

Organization Prompt Templates

We provide comprehensive prompt templates for different scenarios:

Scenario	Use When
Initial Setup	Starting a fresh project
Audit & Organize	Cleaning up existing disorganized docs
Sync Integration	Adding sync to existing well-organized docs
Workflow-Specific	Agile sprints, Kanban, or hybrid workflows

Quick Start Prompt

Copy this to your AI assistant for a basic organization audit:

## Project Organization Task

Please help me organize my documentation for Waymaker Sync.

### Current State
- Scan the /docs folder structure
- Identify markdown files without frontmatter
- Find misplaced files (e.g., completed work in active folders)

### Actions Needed
1. **Create folder structure** if missing:
   - 01-planning, 02-working, 03-knowledge, 04-operations, 05-reference

2. **Add frontmatter** to files in sync target folders:
   - docs/02-working/tasks/ → type: task
   - docs/02-working/prompts/active/ → type: task
   - docs/02-working/sessions/ → type: document

3. **Move misplaced files**:
   - Completed prompts → prompts/completed/
   - Old docs → 00-archive/
   - Reference material → 05-reference/

4. **Create .commander/config.json** with appropriate watch patterns

### Output
Show me what changes you'd make before implementing.

Full Prompt Templates

For more comprehensive prompts (audit workflows, Agile/Kanban configuration, CLAUDE.md router setup), see the full template collection:

Project Organization Prompt Templates

These templates are designed to be adapted to your specific workflow—we're a foundation, not a prescription.

Common Patterns

Converting TODO Comments to Tasks

If your codebase has // TODO: comments, you can extract them:

grep -r "TODO:" --include="*.ts" --include="*.tsx" src/ > todos.txt

Then create task files for important TODOs.

Migrating from Other Systems

From	To
Notion pages	docs/03-knowledge/ with document frontmatter
Jira tickets	docs/02-working/tasks/ with task frontmatter
Confluence	docs/03-knowledge/patterns/
README files	docs/05-reference/

Sync Modes

Choose the right mode for your needs:

Mode	Description	Use Case
bidirectional	IDE ↔ Commander	Full sync, changes flow both ways
ide-to-commander	IDE → Commander	Push docs to Commander only
commander-to-ide	Commander → IDE	Pull tasks to local files

Set in .commander/config.json:

{
  "sync": {
    "mode": "bidirectional"
  }
}

Troubleshooting Organization

"Too many files to sync"

Narrow your watch patterns:

{
  "sync": {
    "watch_patterns": [
      "docs/02-working/tasks/*.md"  // Only top-level, not recursive
    ]
  }
}

"Duplicate tasks created"

Files synced before may create duplicates. Check frontmatter for existing task_id:

---
sync:
  task_id: "existing-task-uuid"  # If present, updates instead of creates
---

"Wrong folder synced"

Update ignore patterns:

{
  "sync": {
    "ignore_patterns": [
      "docs/00-archive/**",
      "**/node_modules/**",
      "**/.git/**"
    ]
  }
}

Next Steps

1. Installation Guide - Install the CLI
2. Init Command - Initialize your project
3. Sync Command - Start syncing

---

Need help organizing? Use the prompt above with your AI assistant, or contact support at help.waymakerone.com