PrompTrek Sync Feature

The sync feature allows you to import AI editor-specific configuration files into PrompTrek format, or sync generated editor files back to your PrompTrek configuration. This creates a workflow where you can:

  1. Import: Start with existing editor configs and convert them to PrompTrek
  2. Generate: Use PrompTrek to generate editor-specific files
  3. Sync back: Capture manual edits from editor files back into PrompTrek

Overview

Many AI editors allow manual editing of their configuration files. The sync feature allows you to capture these changes back into your PrompTrek configuration, maintaining PrompTrek as your single source of truth while preserving manual edits.

Supported Editors

Currently, the sync feature supports:

  • Continue: Reads from .continue/config.yaml, .continue/mcpServers/*.yaml, .continue/prompts/*.md, and .continue/rules/*.md files
  • GitHub Copilot: Reads from .github/copilot-instructions.md, .github/instructions/*.instructions.md, and .github/prompts/*.prompt.md files

Usage

Basic Sync

# Sync from Continue editor files to PrompTrek configuration
promptrek sync --source-dir . --editor continue --output project.promptrek.yaml

# Sync from GitHub Copilot files to PrompTrek configuration
promptrek sync --source-dir . --editor copilot --output project.promptrek.yaml

Preview Changes (Dry Run)

# See what would be changed without making modifications
promptrek sync --source-dir . --editor continue --dry-run

Force Overwrite

# Overwrite existing configuration without confirmation
promptrek sync --source-dir . --editor continue --force

How It Works

1. Parsing Editor Files

The sync command reads editor-specific files and extracts:

  • Instructions: From markdown bullet points and YAML config
  • Metadata: Project title, description, and context
  • Technologies: Detected from technology-specific rule files

2. Intelligent Merging

When syncing to an existing PrompTrek file:

  • Preserves user-defined metadata: Keeps custom titles/descriptions over auto-generated ones
  • Merges instructions additively: Combines new instructions with existing ones without data loss
  • Smart duplicate detection: Ensures no instruction appears twice across categories
  • Context preservation: Merges technologies and project information intelligently
  • Timestamp tracking: Updates sync timestamps while preserving creation dates
  • Source attribution: Distinguishes between user-defined and auto-generated content

3. Default Document Mappings

Important: Some editors have special default files that map to the main content field:

Editor Default File PrompTrek Field Action
Continue general.md Main content ⚠️ Do not rename
Kiro project.md Main content ⚠️ Do not rename
Cline default-rules.md Main content ⚠️ Do not rename
Windsurf general.md Main content ⚠️ Do not rename

These default files are automatically generated by PrompTrek and have special meaning during sync. Renaming them will cause them to be treated as regular documents instead of main content.

All other files in these editors become entries in the documents array.

4. Editor-Specific File Mappings

The sync feature maps editor files to PrompTrek fields:

Continue Editor

| Editor File | PrompTrek Field | |————-|—————–| | .continue/config.yaml | Project metadata (name, version, schema) | | .continue/mcpServers/*.yaml | Each MCP server file becomes an mcp_servers entry | | .continue/prompts/*.md | Each prompt file becomes a commands entry | | .continue/rules/general.md | Main content field ⚠️ Default - do not rename | | .continue/rules/*.md (other files) | Each file becomes a document entry in the documents field |

Note: Continue sync creates schema v3.1 format with modular structure. The general.md file is special - it maps to the main content field and should not be renamed. All other rule files become documents.

Kiro Editor

| Editor File | PrompTrek Field | |————-|—————–| | .kiro/steering/project.md | Main content field ⚠️ Default - do not rename | | .kiro/steering/*.md (other files) | Each file becomes a document entry in the documents field | | .kiro/settings/mcp.json | MCP servers configuration |

Note: The project.md file is special - it maps to the main content field and should not be renamed. All other steering documents become documents in the documents array.

Cline Editor

| Editor File | PrompTrek Field | |————-|—————–| | .clinerules/default-rules.md | Main content field ⚠️ Default - do not rename | | .clinerules/*.md (other files) | Each file becomes a document entry in the documents field | | .vscode/settings.json | MCP servers configuration (user-level) |

Note: The default-rules.md file is special - it maps to the main content field and should not be renamed. All other rule files become documents in the documents array.

Windsurf Editor

| Editor File | PrompTrek Field | |————-|—————–| | .windsurf/rules/general.md | Main content field ⚠️ Default - do not rename | | .windsurf/rules/*.md (other files) | Each file becomes a document entry in the documents field |

Note: The general.md file is special - it maps to the main content field and should not be renamed. All other rule files become documents in the documents array.

Cursor Editor

| Editor File | PrompTrek Field | |————-|—————–| | .cursor/rules/*.mdc | Each file becomes a document entry in the documents field |

Note: Cursor uses .mdc files and a flat document structure. The index.mdc file is typically the main rule file but is treated as a document.

Amazon Q Editor

| Editor File | PrompTrek Field | |————-|—————–| | .amazonq/rules/*.md | Each file becomes a document entry in the documents field | | .amazonq/prompts/*.md | Each prompt file becomes a commands entry | | .amazonq/cli-agents/*.json | Each agent file becomes an agents entry | | .amazonq/mcp.json | MCP servers configuration |

Note: Amazon Q uses a flat document structure for rules. If you have a general.md file, it will be treated as a document.

JetBrains AI Editor

| Editor File | PrompTrek Field | |————-|—————–| | .intellij/prompts/*.md | Each file becomes a document entry in the documents field |

Note: JetBrains uses a flat document structure. If you have a general.md file, it will be treated as a document.

GitHub Copilot

| Editor File | PrompTrek Category | |————-|——————-| | .github/copilot-instructions.md → ## General Instructions | instructions.general | | .github/copilot-instructions.md → ## Code Style Guidelines | instructions.code_style | | .github/instructions/testing.instructions.md | instructions.testing | | .github/instructions/code-style.instructions.md | instructions.code_style | | .github/prompts/*.prompt.md | instructions.general |

Example Workflow

  1. Start with PrompTrek configuration: 
    promptrek init --output project.promptrek.yaml
  2. Generate Continue files: 
    promptrek generate project.promptrek.yaml --editor continue --output continue_config
  3. AI editor modifies markdown files (simulated): 
    echo "- Always validate user input" >> continue_config/.continue/rules/security.md
  4. Sync changes back: 
    promptrek sync --source-dir continue_config --editor continue --output project.promptrek.yaml --force
  5. Result: PrompTrek configuration now includes the new security instruction.

Benefits

  • Import & sync workflow: Import existing configs, generate to editors, sync manual changes back
  • Lossless round-trip: No data loss when going from PrompTrek → Editor → PrompTrek
  • Centralized configuration: Maintain a single source of truth in PrompTrek format
  • Version control friendly: All changes are captured in PrompTrek YAML files
  • Flexible merging: Preserves manual customizations while adding new content

Error Handling

The sync command provides clear error messages for common issues:

  • Missing directory: Validates that source directory exists
  • Unsupported editor: Checks that the specified editor has sync support
  • Parse errors: Continues processing even if some files can’t be parsed
  • Permission issues: Handles file access problems gracefully

Advanced Features

Schema Version Handling

The sync command intelligently handles schema versions to ensure compatibility:

Current Behavior (Schema v3.1.0):

  • Synced files always use the latest schema version (3.1.0)
  • All adapters produce schema v3.1.0 format when syncing
  • Legacy fields are automatically converted to current format

Field Name Handling:

  • Schema v3.1.0 files: Agents use prompt field (new name)
  • Schema v3.0.x files: Agents use system_prompt field (backward compatibility)
  • Automatic conversion: Old field names are mapped to new ones during sync

Example:

# Generate from v3.0.0 file (has system_prompt)
promptrek generate old-v3.0.yaml --editor claude

# Sync back - produces v3.1.0 file (has prompt)
promptrek sync --editor claude --output new-v3.1.yaml

The synced new-v3.1.yaml will use:

  • schema_version: 3.1.0
  • prompt field for agents (not system_prompt)
  • Literal block scalar formatting (|-) for multi-line strings

YAML Formatting

Synced files use clean, readable YAML formatting:

Literal Block Scalars (|-):

  • All multi-line strings use literal block scalar style
  • No escaped newlines (\n) or quoted strings
  • Preserves markdown formatting and readability

Before (quoted style - old behavior):

agents:
  - name: code-reviewer
    prompt: "You are a code reviewer.\n\nAnalyze code for:\n- Best practices\n- Security issues"

After (literal block scalar - current behavior):

agents:
  - name: code-reviewer
    prompt: |-
      You are a code reviewer.

      Analyze code for:
      - Best practices
      - Security issues

Round-trip Compatibility

The sync system ensures complete round-trip compatibility:

  • Generate → Sync → Generate maintains data integrity
  • No information loss during the round-trip (PrompTrek → Editor → PrompTrek)
  • User customizations are preserved across sync operations
  • Schema versions are upgraded automatically (schema v3.0 → v3.1)
  • YAML formatting remains clean and readable