convention-sync

Convention Sync Across AI Tools

Overview

Teams using multiple AI coding tools hit convention drift: HARNESS.md declares the project's conventions and constraints, but Cursor, Copilot, and Windsurf each have their own convention file format. Without sync, those tools operate blind — or worse, with stale copies of rules that were updated in HARNESS.md weeks ago.

This skill reads the Context and Constraints sections of HARNESS.md and generates the corresponding convention files for each supported tool. HARNESS.md is the single source of truth. Sync is one-way only: HARNESS.md drives the other files. No tool-specific file feeds back into HARNESS.md.

---

What Gets Synced

HARNESS.md Section	Target Content
Context > Stack	Tool description / context block — languages, build system, test framework
Context > Conventions	Convention rules — naming, file structure, error handling, documentation
Constraints (each entry)	One rule block per constraint with enforcement level and scope
Constraint Scope field	Cursor glob pattern (falls back to **/* when Scope is absent)

Sections outside Context and Constraints (Garbage Collection, Status) are not synced — they are harness-internal and have no equivalent in other tools.

---

Running the Sync

Invoke via the slash command:

/convention-sync

Or ask the agent directly: "Sync my HARNESS.md conventions to Cursor, Copilot, and Windsurf."

The agent will:

1. Read HARNESS.md from the project root
2. Parse the Context and Constraints sections
3. Generate or update each target file
4. Report what changed in a summary table

---

Output Format Reference

Cursor

Generates two files in .cursor/rules/:

.cursor/rules/conventions.mdc

Contains the Context section from HARNESS.md. Frontmatter format:

---
description: Project conventions synced from HARNESS.md
globs: **/*
alwaysApply: true
---

# Project Conventions

## Stack

- Primary languages: Go 1.22
- Build system: make
...

## Conventions

- Naming: snake_case for files, PascalCase for types
...

.cursor/rules/constraints.mdc

Contains one rule block per constraint. Each constraint becomes a section with its enforcement level and scope. The globs frontmatter field is set from the constraint's Scope field if present, otherwise defaults to **/*.

---
description: Project constraints synced from HARNESS.md
globs: **/*
alwaysApply: true
---

# Project Constraints

## Consistent formatting

- Rule: All source files must pass the project's configured formatter
  without changes
- Enforcement: unverified
- Scope: commit

## No secrets in source

- Rule: No API keys, tokens, passwords, or private keys may appear
  in committed source files
- Enforcement: deterministic
- Scope: commit

Copilot

Generates a single flat markdown file:

.github/copilot-instructions.md

Combines Context and Constraints into one document. No frontmatter — Copilot reads plain markdown.

# Project Conventions

These conventions are synced from HARNESS.md. Do not edit this file
directly — run `/convention-sync` to regenerate.

## Stack

- Primary languages: Go 1.22
...

## Conventions

- Naming: snake_case for files, PascalCase for types
...

## Constraints

### Consistent formatting

- Rule: All source files must pass the project's configured formatter
  without changes
- Enforcement: unverified
- Scope: commit

### No secrets in source

- Rule: No API keys, tokens, passwords, or private keys may appear
  in committed source files
- Enforcement: deterministic
- Scope: commit

Windsurf

Generates two files in .windsurf/rules/:

.windsurf/rules/conventions.md

Same content structure as the Cursor conventions file but without frontmatter globs (Windsurf does not support glob scoping).

# Project Conventions

These conventions are synced from HARNESS.md. Do not edit this file
directly — run `/convention-sync` to regenerate.

## Stack

- Primary languages: Go 1.22
...

## Conventions

- Naming: snake_case for files, PascalCase for types
...

.windsurf/rules/constraints.md

Same content structure as the Cursor constraints file but without frontmatter.

# Project Constraints

These constraints are synced from HARNESS.md. Do not edit this file
directly — run `/convention-sync` to regenerate.

## Consistent formatting

- Rule: All source files must pass the project's configured formatter
  without changes
- Enforcement: unverified
- Scope: commit

---

Conflict Resolution

When a target file already exists:

1. Generate the new content from HARNESS.md
2. Diff the generated content against the existing file
3. If the files are identical, report "unchanged" and move on
4. If they differ, show the user what changed and ask before overwriting
5. If the user declines, report "skipped" for that file

HARNESS.md always wins. The target files are generated output. Any manual edits to them will be overwritten on the next sync unless the user explicitly skips the file. The correct workflow for adding tool-specific rules that do not belong in HARNESS.md is to create a separate rule file that the sync does not manage.

---

Verification

After generating all files, spot-check that every constraint from HARNESS.md appears in each output file:

1. List every constraint heading from HARNESS.md
2. For each target file, confirm the constraint heading appears
3. Report any missing constraints

If a constraint is missing from any output, the generation has a bug. Do not silently skip constraints.