Waymaker
WaymakerDocs
Developer Documentation
Documentation

Project Organization for Sync

waymaker sync keeps markdown files in your IDE in sync with Commander. This page covers what the sync commands actually read from a file — not an aspirational schema, just what's implemented.

What sync reads from a file

Two frontmatter keys drive how a file is treated:

---
title: "My Document"
type: prd
---
  • title — used if present; otherwise the first # H1 heading; otherwise the filename.
  • type — the Commander document type. A prd: key present anywhere in the frontmatter is itself a strong signal and sets the type to prd even without an explicit type: key.

Frontmatter is parsed as real YAML, so structured values (arrays, nested objects) survive — malformed YAML is treated as empty frontmatter rather than crashing the sync.

Setting up sync for a project

cd /path/to/your/project
waymaker init                          # writes .commander/config.json
waymaker sync configure --workspace <id> --project <id> --taskboard <id>

--taskboard is for task extraction — omit it if you're only syncing documents.

Syncing

CommandWhat it does
waymaker sync file <path>Sync one markdown file
waymaker sync workspace --dry-runPreview syncing every markdown file in the project, without writing
waymaker sync workspaceSync every markdown file in the project
waymaker sync watchWatch for local changes and sync continuously, bidirectionally
waymaker sync statusShow session info, queue depth, and synced documents
waymaker sync stopClear the local sync session

Always run waymaker sync workspace --dry-run before your first real sync on an existing directory — it shows what would sync without making changes.

A reasonable folder shape (convention, not enforced)

Sync doesn't require any particular folder layout — it walks whatever markdown files it's pointed at. A layout that's worked well for teams using it:

your-project/
├── docs/
│   ├── 01-planning/     # PRDs (type: prd)
│   ├── 02-working/      # active work, session notes
│   └── 03-knowledge/    # patterns, decisions, reference
└── .commander/
    └── config.json      # created by `waymaker init`

Next steps