Waymaker
WaymakerDocs
Developer Documentation
Documentation

Project Organization for Sync

Deprecated. waymaker sync will be removed in the next release of the Waymaker CLI. Every waymaker sync command now prints this notice on stderr and still runs, so existing scripts keep working until then. Move to the taskboard GitHub repository connection for a roadmap built from your repo, or to the Waymaker MCP server to let an AI assistant read and write Commander directly.

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