Configure AI Assistants for Waymaker Sync
When your AI coding assistant creates documentation, it should automatically include the correct frontmatter so files sync to Commander without manual editing.
Configure AI Assistants for Waymaker Sync
Difficulty: Beginner
Overview
When your AI coding assistant creates documentation, it should automatically include the correct frontmatter so files sync to Commander without manual editing.
Without configuration: You manually add frontmatter after AI creates files.
With configuration: AI writes correct frontmatter from the start.
This guide shows you how to configure popular AI assistants to write proper Waymaker Sync frontmatter.
What You'll Learn
- How to configure your AI assistant for Waymaker Sync
- The frontmatter format your AI should use
- Configuration files for each AI assistant
- How to verify your setup is working
Quick Reference
| AI Assistant | Configuration File |
|---|---|
| Claude Code | CLAUDE.md |
| Cursor | .cursorrules |
| GitHub Copilot | .github/copilot-instructions.md |
| Gemini Code Assist | .gemini/styleguide.md |
| Windsurf | .windsurfrules |
The Frontmatter Format
Your AI assistant needs to include this YAML frontmatter when creating markdown files that should sync:
Task (Creates Document + Task Card)
---
sync:
type: task
status: backlog | active | completed | blocked
priority: low | medium | high | critical # optional
assignee: username # optional
estimate_hours: 4 # optional
---
Document (Creates Document Only)
---
sync:
type: document
---
Epic/PRD (Creates Layer)
---
sync:
type: epic
layer_name: "Feature Name"
---
Session Brief (Creates Completed Task)
---
sync:
type: session
---
Claude Code Setup
Add this to your project's CLAUDE.md file:
## Waymaker Sync
This project uses Waymaker Sync to bridge IDE documentation with Commander.
### Creating Synced Documents
When creating markdown files in `docs/`, include frontmatter:
\`\`\`yaml
---
sync:
type: task | document | epic | session
status: backlog | active | completed | blocked # for tasks
priority: low | medium | high | critical # optional
---
\`\`\`
### Document Types
| Type | Creates | Use For |
|------|---------|---------|
| task | Document + Task Card | Actionable work with checklists |
| document | Document only | Knowledge base, patterns, guides |
| epic | Layer | PRDs, feature specifications |
| session | Completed Task | Session briefs, work logs |
### Rules
1. Files in `docs/` with `sync:` frontmatter automatically sync to Commander
2. Files without `sync:` frontmatter are ignored
3. After first sync, `document_id` and `task_id` are added automatically - commit these
4. Never manually edit auto-generated IDs
### Example Task
\`\`\`markdown
---
sync:
type: task
status: active
priority: medium
---
# Task Title
**Goal:** One sentence describing the objective
## Tasks
- [ ] First subtask
- [ ] Second subtask
## Acceptance Criteria
- Criterion 1
- Criterion 2
\`\`\`
Cursor Setup
Create .cursorrules in your project root:
# Waymaker Sync Integration
When creating markdown documentation in docs/:
1. Always include sync frontmatter for files that should sync to Commander
2. Use type: task for actionable items with checklists
3. Use type: document for knowledge base articles
4. Use type: epic for PRDs and feature specifications
5. Use type: session for session briefs and work logs
Frontmatter template:
---
sync:
type: [task|document|epic|session]
status: [backlog|active|completed|blocked] # tasks only
priority: [low|medium|high|critical] # optional
---
Files without sync: frontmatter will not sync to Commander.
GitHub Copilot Setup
Create .github/copilot-instructions.md:
# Copilot Instructions for Waymaker Project
## Documentation Standards
### Synced Documents
Markdown files in `docs/` that should sync to Commander must include:
\`\`\`yaml
---
sync:
type: task | document | epic | session
---
\`\`\`
### When to Use Each Type
| Type | Use Case |
|------|----------|
| task | Work items with checklists |
| document | Reference documentation |
| epic | Product requirements (PRDs) |
| session | Session briefs |
### Optional Fields for Tasks
\`\`\`yaml
---
sync:
type: task
status: active
priority: high
assignee: stuart
estimate_hours: 4
---
\`\`\`
Gemini Code Assist Setup
Create .gemini/styleguide.md:
# Gemini Code Assist Style Guide
## Markdown Documentation
### Waymaker Sync Integration
All documentation in `docs/` should include sync frontmatter:
\`\`\`yaml
---
sync:
type: task | document | epic | session
---
\`\`\`
This enables automatic sync between IDE and Commander.
### Type Reference
| Type | Use Case | Commander View |
|------|----------|----------------|
| task | Actionable work | Document + Task Card |
| document | Knowledge base | Document only |
| epic | PRD/Feature spec | Layer |
| session | Work log | Completed Task |
Windsurf Setup
Create .windsurfrules in your project root:
# Windsurf Rules for Waymaker
## Documentation
When creating markdown in docs/, include Waymaker Sync frontmatter:
---
sync:
type: task | document | epic | session
status: backlog | active | completed | blocked
priority: low | medium | high | critical
---
Types:
- task: Work items (creates Document + Task Card)
- document: Knowledge (creates Document)
- epic: PRDs (creates Layer)
- session: Work logs (creates completed Task)
Files without sync frontmatter are not synced.
Verify Your Setup
After adding the configuration file:
Step 1: Ask AI to Create a Task
Prompt your AI assistant:
Create a task document for implementing user authentication
Step 2: Check the Output
The generated file should include frontmatter:
---
sync:
type: task
status: active
---
# Implement User Authentication
...
Step 3: Confirm Sync Works
Save the file and check Commander. The document should appear within a few seconds.
Troubleshooting
AI Ignores Configuration
Problem: AI creates files without frontmatter.
Solutions:
- Ensure config file is in project root
- Restart your IDE to reload configuration
- Reference rules explicitly: "Following our CLAUDE.md conventions, create a task document for..."
Wrong Document Type
Problem: AI uses document when task would be better.
Solution: Add clearer guidance to your config:
Use `type: task` when the document has:
- Checklists (- [ ] items)
- Actionable work to complete
- Status tracking needed
Use `type: document` when:
- It's reference documentation
- No action items
- Knowledge base content
Frontmatter Syntax Errors
Problem: YAML parsing fails.
Check for:
---delimiters on their own lines- Quotes around values with special characters
- 2-space indentation for nested fields
Correct:
---
sync:
type: task
status: active
---
Incorrect:
---
sync:
type: task # Missing indentation
status:active # Missing space after colon
---
Best Practices
1. Commit Your Config File
Share AI configuration with your team:
git add CLAUDE.md .cursorrules
git commit -m "docs: add Waymaker Sync AI configuration"
2. Use Consistent Naming
Keep terminology consistent across your team's configs.
3. Start Simple
Begin with just type and status. Add optional fields as needed.
4. Review AI Output
Occasionally check that AI is following your conventions. Adjust config if patterns drift.
Related Articles
Need More Help?
- Community: Join the Waymaker community to ask questions
- Support: Contact support@waymakerone.com
- X/Twitter: @stuartdotleo
Next: Frontmatter Reference - All sync options explained