Sync Frontmatter Reference

Difficulty: Intermediate

Overview

This reference documents all frontmatter fields available for Waymaker Sync. Frontmatter controls how markdown files sync to Commander.

Key Behavior

Frontmatter is Optional

Files matching your watch_patterns will automatically sync even without frontmatter. The sync engine:

1. Detects new files matching watch patterns
2. Auto-adds minimal sync: frontmatter
3. Infers document type from folder path
4. Syncs to Commander

You only need to add frontmatter manually if you want to:

• Override the auto-inferred type
• Set specific metadata (priority, assignee, etc.)
• Exclude a file from sync (enabled: false)

Auto-Inferred Types

When frontmatter is missing or type is not specified, the sync engine infers type from the file path:

Folder Pattern	Inferred Type
*/product-requirements/*, */prd/*, *-prd.md	epic
*/tasks/*, */task/*, */backlog/*, */todo/*	task
*/sessions/*, *-session.md, *-session-brief.md	session
Everything else	document

Basic Structure

---
sync:
  type: task
  # ... other fields
---

# Your Document Title

Content starts here...

Sync Control Fields

enabled

Optional. Control whether this file syncs. Default: true

Use enabled: false to exclude a file from sync even if it matches watch patterns.

# This file will NOT sync
---
sync:
  enabled: false
---

# Draft Document - Not Ready

Work in progress...

type

Optional. Determines how the file syncs to Commander. Auto-inferred from path if not specified.

Value	Creates	Best For
task	Document + Task Card	Actionable work with checklists
document	Document only	Knowledge base, patterns, guides
epic	Layer (Epic)	PRDs, feature specifications
session	Completed Task	Session briefs, work logs

sync:
  type: task

Task Fields

These fields apply when type: task:

status

Current workflow status.

Value	Meaning
backlog	Not yet started
active	Currently being worked on
completed	Work finished
blocked	Waiting on something

sync:
  type: task
  status: active

priority

Task importance level.

Value	Use When
low	Nice to have
medium	Normal priority
high	Important, do soon
critical	Urgent, do now

sync:
  type: task
  priority: high

assignee

Username of person responsible.

sync:
  type: task
  assignee: stuart

tags

Categorization tags.

sync:
  type: task
  tags:
    - frontend
    - urgent

Epic Fields

These fields apply when type: epic:

layer

Layer path for hierarchical organization. Creates parent layers automatically.

sync:
  type: epic
  layer: "Product/Q1 2026/User Management"

layer_name

Simple layer name (alternative to layer path).

sync:
  type: epic
  layer_name: "User Authentication Feature"

Auto-Generated Fields

These fields are added automatically after first sync. Do not edit manually.

Field	Description
document_id	Links to Commander document
task_id	Links to Commander task card
layer_id	Links to Commander layer (for epics)
last_synced	Timestamp of last successful sync

# After first sync, the engine adds:
sync:
  type: task
  task_id: "abc123-def456"      # Auto-generated
  document_id: "xyz789-uvw012"  # Auto-generated
  last_synced: "2026-02-06T10:30:00Z"

Complete Examples

Minimal - Let Engine Decide

---
# No sync block needed - type auto-inferred from path
---

# Fix Login Bug

The login button doesn't work on mobile...

Explicit Skip

---
sync:
  enabled: false
---

# DRAFT - Architecture Notes

Not ready for Commander yet...

Task with Metadata

---
sync:
  type: task
  status: active
  priority: high
  assignee: stuart
  tags:
    - auth
    - security
---

# Implement User Authentication

**Goal:** Add login/logout functionality

## Tasks

- [ ] Set up Clerk integration
- [ ] Create login page
- [ ] Add protected routes
- [ ] Test authentication flow

## Acceptance Criteria

- Users can sign up with email
- Users can log in and out
- Protected routes redirect to login

Document (Knowledge Base)

---
sync:
  type: document
---

# Authentication Patterns

This document describes our authentication architecture...

Epic (PRD)

---
sync:
  type: epic
  layer: "Product/Q1 2026"
---

# User Management PRD

**Vision:** Complete user management system

## Goals

1. User registration
2. Role-based access
3. Team invitations

Session Brief

---
sync:
  type: session
---

# Session: Auth Implementation

**Date:** February 6, 2026
**Duration:** 2 hours

## Completed

- Set up Clerk
- Created login page

## Next Steps

- Add protected routes

---

AI Agent Guide

This section is specifically for AI coding assistants (Claude, Cursor, Windsurf, etc.) that need to create or update frontmatter.

When to Add Frontmatter

Scenario	Action
Creating new file in tasks/ folder	Optional - auto-inferred as task
Creating new file in product-requirements/	Optional - auto-inferred as epic
Creating file that should NOT sync	Add sync: enabled: false
Need specific metadata (priority, assignee)	Add frontmatter with fields
File type differs from folder convention	Add explicit type: field

Minimal Frontmatter Templates

Task (in any folder):

---
sync:
  type: task
  status: active
---

Document:

---
sync:
  type: document
---

Epic/PRD:

---
sync:
  type: epic
---

Session Brief:

---
sync:
  type: session
---

Skip File (don't sync):

---
sync:
  enabled: false
---

Full Field Reference for AI

---
sync:
  # Control
  enabled: true          # boolean - set false to skip sync
  type: task             # 'task' | 'document' | 'epic' | 'session'

  # Task metadata
  status: active         # 'backlog' | 'active' | 'completed' | 'blocked'
  priority: medium       # 'low' | 'medium' | 'high' | 'critical'
  assignee: username     # string - username
  tags:                  # string[] - categorization
    - frontend
    - urgent

  # Epic metadata
  layer: "Path/To/Layer" # string - creates hierarchy
  layer_name: "Name"     # string - simple name

  # DO NOT SET - Auto-generated
  # task_id: "..."
  # document_id: "..."
  # layer_id: "..."
  # last_synced: "..."
---

Rules for AI Agents

1. Prefer minimal frontmatter - Only add fields you need
2. Don't guess IDs - Never set task_id, document_id, layer_id, or last_synced
3. Trust folder inference - Files in tasks/ auto-become tasks
4. Use enabled: false for drafts - Mark WIP files to exclude from sync
5. Commit sync metadata - After sync adds IDs, include in commits

Example: AI Creating a New Task

---
sync:
  type: task
  status: active
  priority: high
---

# Implement Password Reset

## Description

Users need ability to reset forgotten passwords.

## Tasks

- [ ] Add "Forgot Password" link to login page
- [ ] Create password reset email template
- [ ] Implement reset token generation
- [ ] Build password reset form
- [ ] Add rate limiting for security

## Acceptance Criteria

- User receives reset email within 30 seconds
- Reset links expire after 1 hour
- Users can set new password successfully

---

Best Practices

1. Let Auto-Inference Work

Don't add frontmatter if the folder already implies the type:

# Good - no frontmatter needed
docs/tasks/implement-auth.md  → auto-syncs as task

# Unnecessary - type matches folder anyway
docs/tasks/implement-auth.md with sync.type: task

2. Use enabled: false for Drafts

Keep work-in-progress files out of Commander:

sync:
  enabled: false

3. Commit Auto-Generated IDs

When sync adds IDs, commit them to preserve the link:

git add docs/
git commit -m "docs: update sync metadata"

4. Don't Edit Auto-Generated Fields

Never manually change task_id, document_id, layer_id, or last_synced. This breaks the sync link.

Related Articles

• Getting Started with Waymaker Sync
• Configure AI Assistants
• Sync CLI Commands
• Troubleshooting Sync Issues

---

Need help? Contact support@waymakerone.com