### Agent-Sync Go Quick Start Example

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/library.md

A practical example demonstrating how to initialize and use the agent-sync Go client. It covers updating lockfiles from upstream sources, syncing files to specified targets, and checking for any drift between the lockfile and the actual files. This snippet requires the agent-sync library to be installed and a valid configuration file (agent-sync.yaml) to be present.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/bianoble/agent-sync/pkg/agentsync"
)

func main() {
    client, err := agentsync.New(agentsync.Options{
        ProjectRoot: ".",
        ConfigPath:  "agent-sync.yaml",
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Update lockfile from upstream sources
    updateResult, err := client.Update(ctx, agentsync.UpdateOptions{})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Updated %d sources\n", len(updateResult.Updated))

    // Sync files to targets
    syncResult, err := client.Sync(ctx, agentsync.SyncOptions{})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Written: %d, Skipped: %d\n",
        len(syncResult.Written), len(syncResult.Skipped))

    // Check for drift
    checkResult, err := client.Check(ctx)
    if err != nil {
        log.Fatal(err)
    }
    if checkResult.Clean {
        fmt.Println("All files match lockfile")
    }
}
```

--------------------------------

### Hierarchical Configuration Setup

Source: https://context7.com/bianoble/agent-sync/llms.txt

Examples of system-wide and user-level configurations that allow projects to inherit global policies and personal tool preferences.

```yaml
# System-wide configuration example
version: 1
variables:
  org: acme-corp
  compliance_level: soc2

# User-level configuration example
version: 1
sources:
  - name: anthropic-skills
    type: git
    repo: https://github.com/anthropics/skills.git
    ref: main
```

--------------------------------

### Install agent-sync Go Library

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/library.md

This command installs the latest version of the agent-sync Go library using the go get command. It ensures that the library is available for use in your Go projects.

```bash
go get github.com/bianoble/agent-sync@latest
```

--------------------------------

### Install agent-sync using Shell Script or Go

Source: https://context7.com/bianoble/agent-sync/llms.txt

Provides instructions for installing the agent-sync tool. It can be installed via a curl command for macOS/Linux or using the Go toolchain for direct installation.

```bash
# macOS / Linux install script
curl -sSL https://raw.githubusercontent.com/bianoble/agent-sync/main/install.sh | sh
```

```bash
# Go install
go install github.com/bianoble/agent-sync/cmd/agent-sync@latest
```

--------------------------------

### Override with Source Sync Example

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/transforms.md

An example demonstrating how to sync a source file and then apply an override to append local team-specific additions to a policy file. This shows the integration of sources and overrides.

```yaml
# Sync shared security policy, then append team-specific additions
sources:
  - name: security
    type: git
    repo: https://github.com/org/policies.git
    ref: v2.0

targets:
  - source: security
    tools: [cursor]

overrides:
  - target: policy.md
    strategy: append
    file: local/team-policy-additions.md
```

--------------------------------

### Show Installation Info

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/cli.md

Displays diagnostic information about the agent-sync installation, including version, paths, and cache statistics.

```bash
agent-sync info
```

--------------------------------

### Example agent-sync Configuration

Source: https://github.com/bianoble/agent-sync/blob/main/README.md

An example YAML configuration file for agent-sync, demonstrating how to define sources (e.g., Git repositories) and targets for synchronization. This configuration specifies the version, source details, and which tools should receive the synchronized files.

```yaml
version: 1

sources:
  - name: team-rules
    type: git
    repo: https://github.com/org/agent-rules.git
    ref: v1.0.0

targets:
  - source: team-rules
    tools: [cursor, claude-code, copilot]
```

--------------------------------

### Template Syntax Example

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/transforms.md

Example of Go text/template syntax used within source files for variable substitution. Variables like project, team, and environment are dynamically inserted.

```go-template
Project: {{ .project }}
Team: {{ .team }}
Environment: {{ .env }}
```

--------------------------------

### Quick Start agent-sync Commands

Source: https://github.com/bianoble/agent-sync/blob/main/README.md

Demonstrates the basic workflow for using agent-sync: initializing configuration, updating sources and locking files, syncing files to tool directories, and checking for drift. These commands are essential for setting up and maintaining agent file synchronization.

```bash
# 1. Create a starter config
agent-sync init

# 2. Edit agent-sync.yaml to point at your sources, then resolve and lock
agent-sync update

# 3. Sync files to tool directories
agent-sync sync

# 4. Verify nothing has drifted (CI-friendly)
agent-sync check
```

--------------------------------

### Template Transform Example

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

An example of a template transform using Go text/template syntax for variable substitution.

```text
Project: {{ .project }}
```

--------------------------------

### Deploying System Config on macOS (Bash Script)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/enterprise-config.md

Example bash script for deploying the system-level agent-sync configuration file to the correct path on macOS. This is often automated using MDM solutions.

```bash
# Example install script
sudo mkdir -p /etc/agent-sync
sudo cp agent-sync.yaml /etc/agent-sync/agent-sync.yaml
sudo chmod 644 /etc/agent-sync/agent-sync.yaml

```

--------------------------------

### Project Configuration Example (agent-sync YAML)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/enterprise-config.md

Defines project-specific sources and targets, which are merged with system-level configurations. This allows developers to add project-specific rules alongside organizational standards.

```yaml
# ./agent-sync.yaml
version: 1

variables:
  project: payment-service
  team: payments

sources:
  - name: team-rules
    type: local
    path: ./agents/rules/

targets:
  - source: team-rules
    tools: [cursor, claude-code]

```

--------------------------------

### Example Configuration Version (YAML)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Illustrates the basic structure for declaring the specification version within a configuration or lockfile. This ensures compatibility between the agent-sync tool and the files it processes.

```YAML
version: 1
```

--------------------------------

### Advanced Source Configuration

Source: https://github.com/bianoble/agent-sync/blob/main/docs/getting-started/quickstart.md

Examples for defining local and URL-based sources in the configuration file.

```yaml
sources:
  - name: local-rules
    type: local
    path: ./agents/rules/

targets:
  - source: local-rules
    tools: [cursor]

---

sources:
  - name: security-policy
    type: url
    url: https://example.com/security.md
    checksum: sha256:abc123...

targets:
  - source: security-policy
    destination: .cursor/rules/
```

--------------------------------

### Install agent-sync CLI

Source: https://github.com/bianoble/agent-sync/blob/main/README.md

Provides commands to install the agent-sync command-line interface on macOS, Linux, and via Go modules. This allows users to manage agent file synchronization directly from their terminal.

```bash
# macOS / Linux
curl -sSL https://raw.githubusercontent.com/bianoble/agent-sync/main/install.sh | sh

# Go
go install github.com/bianoble/agent-sync/cmd/agent-sync@latest
```

--------------------------------

### Configure Transforms, Overrides, and Custom Tools

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/config.md

Examples for applying template transforms, file content overrides, and defining custom tool paths.

```yaml
transforms:
  - source: team-rules
    type: template
    vars:
      project: my-app

overrides:
  - target: security.md
    strategy: append
    file: local/security-extension.md

tool_definitions:
  - name: my-tool
    destination: .my-tool/config/
```

--------------------------------

### Source Type Definitions

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Configuration examples for defining Git, URL, and local sources within the agent-sync configuration.

```yaml
# Git Source
type: git
repo: https://github.com/org/repo.git
ref: v1.2.0
paths:
  - folder/

# URL Source
type: url
url: https://example.com/file.md
checksum: sha256:abcdef

# Local Source
type: local
path: ./agents/
```

--------------------------------

### Define agent-sync Configuration

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

An example of an agent-sync.yaml configuration file defining sources, targets, overrides, and transformation rules for agent files.

```yaml
version: 1

variables:
  project: my-project
  language: go

sources:

  - name: base-rules
    type: git
    repo: https://github.com/org/rules.git
    ref: v1.2.0
    paths:
      - core/

  - name: security-policy
    type: url
    url: https://example.com/policy.md
    checksum: sha256:abcdef...

  - name: team-standards
    type: local
    path: ./agents/standards/

targets:

  - source: base-rules
    tools: [cursor, claude-code, copilot]

  - source: security-policy
    tools: [cursor, claude-code]

  - source: team-standards
    destination: .custom/agents/

overrides:

  - target: security.md
    strategy: append
    file: local/security-extension.md

transforms:

  - source: base-rules
    type: template
    vars:
      project: "{{ .project }}"

  - source: team-standards
    type: custom
    command: "./scripts/merge-yaml.sh"
    output_hash: sha256:expected...
```

--------------------------------

### GET /check

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Verifies that target files match the lockfile to detect drift.

```APIDOC
## GET /check

### Description
Hashes all target files and compares them against the lockfile to report any drift (files changed, missing, or unexpected).

### Method
GET

### Endpoint
agent-sync check

### Response
#### Success Response (200)
- **result** (string) - Confirmation that files match the lockfile

#### Error Response (Non-zero exit)
- **drift** (string) - Details of detected file drift
```

--------------------------------

### System Configuration Example (agent-sync YAML)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/enterprise-config.md

Defines organization-wide policies, including pinned AI agent rule versions and approved prompts. This configuration is typically deployed via MDM or configuration management tools.

```yaml
# /etc/agent-sync/agent-sync.yaml
version: 1

variables:
  org: acme-corp
  compliance_level: soc2

sources:
  - name: org-security-rules
    type: git
    repo: https://github.com/acme-corp/ai-security-rules.git
    ref: v2.3.1
    paths:
      - policies/

  - name: org-approved-prompts
    type: url
    url: https://security.acme-corp.com/approved-prompts.md
    checksum: sha256:a1b2c3d4e5f6...

targets:
  - source: org-security-rules
    tools: [cursor, claude-code, copilot, windsurf]

  - source: org-approved-prompts
    tools: [cursor, claude-code]

overrides:
  - target: security.md
    strategy: prepend
    file: /etc/agent-sync/compliance-header.md

```

--------------------------------

### Configure Git, URL, and Local Sources

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/config.md

Examples for defining different source types in agent-sync. Git sources require a repository and ref, URL sources require a checksum for integrity, and local sources require a relative path.

```yaml
sources:
  - name: team-rules
    type: git
    repo: https://github.com/org/repo.git
    ref: v1.0.0
    paths:
      - rules/
  - name: policy
    type: url
    url: https://example.com/file.md
    checksum: sha256:abcdef...
  - name: local-rules
    type: local
    path: ./agents/rules/
```

--------------------------------

### Example Lockfile Structure

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

A YAML representation of the agent-sync.lock file, showing how sources (git, url, local) are resolved with their respective hashes and statuses.

```yaml
version: 1

sources:

  - name: base-rules
    type: git
    repo: https://github.com/org/rules.git

    resolved:

      commit: 3f8c9abf...
      tree: a8bcdef...

      files:

        core/security.md:
          sha256: 123abc...

        core/general.md:
          sha256: 456def...

    status: ok

  - name: security-policy
    type: url

    resolved:

      url: https://example.com/policy.md
      sha256: abcdef123...

    status: ok

  - name: team-standards
    type: local

    resolved:

      path: ./agents/

      files:

        standards/naming.md:
          sha256: 789ghi...

        standards/testing.md:
          sha256: 012jkl...

    status: ok
```

--------------------------------

### Override Configuration Example

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/transforms.md

Configuration for the overrides feature, specifying a target file, the strategy to apply (e.g., append), and the file containing the content to be used for the override. The target file must exist after sync.

```yaml
overrides:
  - target: security.md
    strategy: append
    file: local/security-extension.md
```

--------------------------------

### Configure Target Tools

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/toolmap.md

Defines how to map source files to specific tool directories using the tools property. This example writes files from team-rules to both cursor and claude-code directories.

```yaml
targets:
  - source: team-rules
    tools: [cursor, claude-code]
```

--------------------------------

### Skip Go Tests When Running as Root

Source: https://github.com/bianoble/agent-sync/blob/main/CONTRIBUTING.md

Provides an example of how to conditionally skip a Go test if the test is being executed with root privileges, as certain tests might be unreliable in that environment.

```go
if os.Getuid() == 0 {
  t.Skip("test unreliable as root")
}
```

--------------------------------

### CI/CD Integration with agent-sync

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/enterprise-config.md

Examples of integrating agent-sync into CI/CD pipelines, specifically GitHub Actions, to ensure reproducible builds by disabling hierarchical configuration resolution using the '--no-inherit' flag or an environment variable.

```yaml
# GitHub Actions
- name: Sync agent files
  run: agent-sync sync --no-inherit

# Or via environment variable
- name: Sync agent files
  env:
    AGENT_SYNC_NO_INHERIT: "1"
  run: agent-sync sync
```

--------------------------------

### Initialize Configuration

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/cli.md

Creates a starter agent-sync.yaml configuration file. It respects the global config flag and requires the --force flag to overwrite existing files.

```bash
agent-sync init [--force]
```

--------------------------------

### Initialize agent-sync Configuration

Source: https://context7.com/bianoble/agent-sync/llms.txt

Commands to create a starter `agent-sync.yaml` configuration file. Options include creating a default file, forcing an overwrite, or specifying a custom path for the configuration file.

```bash
# Create default config file
agent-sync init
```

```bash
# Overwrite existing config file
agent-sync init --force
```

```bash
# Create config at custom path
agent-sync init --config custom-config.yaml
```

--------------------------------

### Initialize Agent Sync Client (Go)

Source: https://context7.com/bianoble/agent-sync/llms.txt

Demonstrates how to initialize the agent-sync client in Go. It requires specifying project root, configuration path, and lockfile path. Disabling hierarchical config is recommended for CI environments.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/bianoble/agent-sync/pkg/agentsync"
)

func main() {
    client, err := agentsync.New(agentsync.Options{
        ProjectRoot:  ".",
        ConfigPath:   "agent-sync.yaml",
        LockfilePath: "agent-sync.lock",
        NoInherit:    true, // Disable hierarchical config (recommended for CI)
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Use client for update, sync, check, verify, prune operations
    _ = ctx
    _ = client
}
```

--------------------------------

### Initialize and Configure agent-sync

Source: https://github.com/bianoble/agent-sync/blob/main/docs/getting-started/quickstart.md

Commands to initialize the project and the structure of the agent-sync.yaml configuration file.

```bash
agent-sync init
```

```yaml
version: 1

sources:
  - name: team-rules
    type: git
    repo: https://github.com/your-org/agent-rules.git
    ref: main

targets:
  - source: team-rules
    tools: [cursor, claude-code]
```

--------------------------------

### Clone and Build agent-sync Project

Source: https://github.com/bianoble/agent-sync/blob/main/CONTRIBUTING.md

This snippet demonstrates the basic steps to clone the agent-sync repository, navigate into the directory, and build the project using make commands.

```bash
git clone https://github.com/bianoble/agent-sync.git
cd agent-sync
make build
```

--------------------------------

### Hierarchical Configuration Management

Source: https://github.com/bianoble/agent-sync/blob/main/docs/getting-started/quickstart.md

Demonstrates how to define user-level global configurations and project-specific overrides.

```yaml
# User Config (~/.config/agent-sync/agent-sync.yaml)
version: 1
sources:
  - name: anthropic-skills
    type: git
    repo: https://github.com/anthropics/skills.git
    ref: main

# Project Config (agent-sync.yaml)
version: 1
sources:
  - name: tob-differential-review
    type: git
    repo: https://github.com/trailofbits/skills.git
    ref: main
```

--------------------------------

### GET /verify

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Checks if upstream sources have changed since the last lockfile update.

```APIDOC
## GET /verify

### Description
Checks whether the upstream has changed since the lockfile was last written. Does not modify any files.

### Method
GET

### Endpoint
agent-sync verify [source-name...]

### Parameters
#### Query Parameters
- **source-name** (string) - Optional - Specific sources to verify

### Response
#### Success Response (200)
- **status** (string) - Indicates all sources match upstream

#### Error Response (Non-zero exit)
- **changes** (string) - List of sources with newer content available
```

--------------------------------

### Define Targets and Variables

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/config.md

Demonstrates how to map sources to tools or explicit file paths, and how to define global variables for use in templates.

```yaml
targets:
  - source: team-rules
    tools: [cursor, claude-code, copilot]
  - source: team-rules
    destination: .custom/agents/

variables:
  project: my-app
  team: platform
```

--------------------------------

### Define Agent-Sync Configuration Sources

Source: https://context7.com/bianoble/agent-sync/llms.txt

Demonstrates how to define different types of sources including Git repositories, remote URLs with checksums, and local file paths.

```yaml
sources:
  - name: team-rules
    type: git
    repo: https://github.com/org/agent-rules.git
    ref: v1.0.0
    paths:
      - rules/
  - name: remote-policy
    type: url
    url: https://security.example.com/approved-prompts.md
    checksum: sha256:a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
  - name: project-rules
    type: local
    path: ./agents/project-specific/
```

--------------------------------

### Build and Test Commands

Source: https://github.com/bianoble/agent-sync/blob/main/CLAUDE.md

Standard commands for compiling the agent-sync binary, running tests with race detection, and maintaining code quality through linting and formatting.

```bash
make build
make test
make lint
make vet
make fmt
```

```bash
go build ./cmd/agent-sync
go test -race ./...
```

--------------------------------

### Display Version

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/cli.md

Prints the current version information for the agent-sync CLI.

```bash
agent-sync version
```

--------------------------------

### GitHub Actions Workflow for Agent Files Check (YAML)

Source: https://context7.com/bianoble/agent-sync/llms.txt

A GitHub Actions workflow that automates the verification of agent file integrity. It installs agent-sync, syncs files, checks for drift, and verifies upstream sources on push and pull request events.

```yaml
name: Agent Files Check

on:
  push:
    branches: [main]
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install agent-sync
        run: |
          curl -sSL https://raw.githubusercontent.com/bianoble/agent-sync/main/install.sh | sh
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Sync agent files
        run: agent-sync sync --no-inherit

      - name: Check for drift
        run: agent-sync check --no-inherit

      - name: Verify upstream
        run: agent-sync verify --no-inherit
```

--------------------------------

### Execute agent-sync CLI commands

Source: https://github.com/bianoble/agent-sync/blob/main/docs/index.md

These commands demonstrate the standard workflow for managing agent files: updating sources to create a lockfile, synchronizing files to tool directories, and verifying the integrity of the current state.

```bash
# Resolve sources and create lockfile
agent-sync update

# Sync files to tool directories
agent-sync sync

# Verify nothing has drifted
agent-sync check
```

--------------------------------

### Agent Sync Go Library Usage

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Demonstrates the requirement for agent-sync to be usable as a Go library, indicating its integration capabilities within Go projects.

```go
package main

import (
	"fmt"
	"os"

	"github.com/your-repo/agent-sync/pkg/agent"
)

func main() {
	// Example: Initialize agent-sync client
	client, err := agent.NewClient(agent.WithConfigPath("agent-sync.yaml"))
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error initializing agent-sync client: %v\n", err)
		os.Exit(1)
	}

	// Example: Perform an update operation
	updateResult, err := client.Update(agent.UpdateOptions{Sources: []string{"my-source"}, DryRun: false})
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error during update: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("Update successful: %+v\n", updateResult)

	// Further library interactions can be added here...
}

```

--------------------------------

### Go Test Utilities for Temporary Directories

Source: https://github.com/bianoble/agent-sync/blob/main/CONTRIBUTING.md

Shows how to use `t.TempDir()` in Go tests to create temporary directories that are automatically cleaned up after the test finishes.

```go
tempDir := t.TempDir()
// Use tempDir for test files
```

--------------------------------

### Manage Sync Lifecycle

Source: https://github.com/bianoble/agent-sync/blob/main/docs/getting-started/quickstart.md

Essential commands for updating, syncing, and verifying file states against the lockfile.

```bash
agent-sync update
agent-sync sync
agent-sync check
agent-sync verify
agent-sync status
```

--------------------------------

### Sync agent-sync Files to Target Directories

Source: https://context7.com/bianoble/agent-sync/llms.txt

Commands to synchronize files from the lockfile to their respective tool-specific target directories. Includes options for dry runs to preview changes and disabling hierarchical configuration for CI environments.

```bash
# Sync all locked files to target directories
agent-sync sync
```

```bash
# Preview what would change without writing files
agent-sync sync --dry-run
```

```bash
# Disable hierarchical config resolution (recommended for CI)
agent-sync sync --no-inherit
```

--------------------------------

### Sync Agent Files (Go)

Source: https://context7.com/bianoble/agent-sync/llms.txt

Synchronizes files from the lockfile to their target directories. The `DryRun` option can be used to preview changes without writing files. The result details the number of files written and skipped.

```go
syncResult, err := client.Sync(ctx, agentsync.SyncOptions{
    DryRun: false,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Written: %d files\n", len(syncResult.Written))
fmt.Printf("Skipped: %d files (unchanged)", len(syncResult.Skipped))

for _, action := range syncResult.Written {
    fmt.Printf("  %s\n", action.Path)
}
```

--------------------------------

### Verifying agent-sync Configuration Chain

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/enterprise-config.md

Commands to inspect the active configuration files and detailed merge activity for agent-sync. Useful for debugging and understanding configuration precedence.

```bash
$ agent-sync info
agent-sync v0.5.0
  spec version:  1
  config chain:
    system:    /etc/agent-sync/agent-sync.yaml (loaded)
    user:      /Users/alice/Library/Application Support/agent-sync/agent-sync.yaml (not found)
    project:   ./agent-sync.yaml (loaded)
  lockfile:      agent-sync.lock
  cache dir:     /Users/alice/.cache/agent-sync
  cache size:    2.1 MB
```

```bash
$ agent-sync sync --verbose
  config: loaded system /etc/agent-sync/agent-sync.yaml
  config: user /Users/alice/Application Support/agent-sync/agent-sync.yaml (not found, skipping)
  config: loaded project ./agent-sync.yaml
  config: merged 2 layers
  ...
```

--------------------------------

### YAML Configuration for Explicit Path Targets

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Demonstrates configuring explicit path targets in agent-sync using YAML. This is useful for tools without a built-in mapping or when direct control over the destination path is required. The 'destination' field specifies the exact output directory.

```yaml
targets:
  - source: rules
    destination: .custom/rules/
```

--------------------------------

### Deploy agent-sync config on Linux (Ansible & Chef)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/enterprise-config.md

Configuration management for deploying agent-sync system configuration files to Linux systems. Ansible uses the 'copy' module, while Chef uses 'directory' and 'cookbook_file' resources.

```yaml
- name: Deploy agent-sync system config
  copy:
    src: files/agent-sync.yaml
    dest: /etc/agent-sync/agent-sync.yaml
    owner: root
    group: root
    mode: '0644'
```

```ruby
directory '/etc/agent-sync' do
  owner 'root'
  group 'root'
  mode '0755'
end

cookbook_file '/etc/agent-sync/agent-sync.yaml' do
  source 'agent-sync.yaml'
  owner 'root'
  group 'root'
  mode '0644'
end
```

--------------------------------

### Deploy agent-sync config on Windows (PowerShell)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/guides/enterprise-config.md

A PowerShell script to deploy the agent-sync configuration file to Windows systems. It ensures the target directory exists and then copies the configuration file.

```powershell
# PowerShell deployment script
$dir = "$env:ProgramData\agent-sync"
New-Item -ItemType Directory -Force -Path $dir
Copy-Item agent-sync.yaml "$dir\agent-sync.yaml"
```

--------------------------------

### Check for File Drift (Go)

Source: https://context7.com/bianoble/agent-sync/llms.txt

Verifies that files in the target directories match the contents specified in the lockfile. It reports any drifted files, their expected vs. actual states, and any missing files.

```go
checkResult, err := client.Check(ctx)
if err != nil {
    log.Fatal(err)
}

if checkResult.Clean {
    fmt.Println("All files match lockfile")
} else {
    fmt.Printf("Drifted files: %d\n", len(checkResult.Drifted))
    for _, entry := range checkResult.Drifted {
        fmt.Printf("  %s: expected %s, got %s\n", entry.Path, entry.Expected, entry.Actual)
    }
    fmt.Printf("Missing files: %d\n", len(checkResult.Missing))
    for _, path := range checkResult.Missing {
        fmt.Printf("  %s\n", path)
    }
}
```

--------------------------------

### POST /sync

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Synchronizes files to targets based on the lockfile configuration.

```APIDOC
## POST /sync

### Description
Synchronizes files to targets using the lockfile as the source of truth. It fetches content from cache or sources and writes them to the specified target locations.

### Method
POST

### Endpoint
/sync

### Parameters
#### Query Parameters
- **dry-run** (boolean) - Optional - If true, shows exactly which files would be written, modified, or removed without making changes to the filesystem.

### Request Example
agent-sync sync --dry-run

### Response
#### Success Response (200)
- **status** (string) - Indicates the sync operation result.
- **diff** (object) - Optional - Shows the diff for each changed file if dry-run is enabled.

#### Response Example
{
  "status": "success",
  "files_synced": ["security.md", "rules.yaml"]
}
```

--------------------------------

### Apply Template Transforms and Variable Substitution

Source: https://context7.com/bianoble/agent-sync/llms.txt

Uses Go text/template syntax to inject variables into synchronized files, allowing for dynamic configuration based on project or environment.

```yaml
variables:
  project: payment-service

transforms:
  - source: team-rules
    type: template
    vars:
      env: production
```

--------------------------------

### YAML Configuration for Tool-Based Targets

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Illustrates how to specify tool-based targets in agent-sync using YAML. This method resolves target paths based on a predefined tool map, allowing sources to be directed to specific tools like 'cursor' or 'claude-code'.

```yaml
targets:
  - source: rules
    tools: [cursor, claude-code]
```

--------------------------------

### Agent-Sync Client Options Structure

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/library.md

Defines the configuration options for the agent-sync client. These options control aspects like the project root, configuration file path, lockfile path, cache directory, and config resolution behavior. Setting `NoInherit: true` is recommended for CI environments to ensure consistent behavior by disabling hierarchical config resolution.

```go
type Options struct {
    ProjectRoot      string // Directory containing agent-sync.yaml
    ConfigPath       string // Default: "agent-sync.yaml"
    LockfilePath     string // Default: "agent-sync.lock"
    CacheDir         string // Default: ~/.cache/agent-sync
    SystemConfigPath string // Override system config path (default: OS-specific)
    UserConfigPath   string // Override user config path (default: OS-specific)
    NoInherit        bool   // Disable hierarchical config resolution
}

// By default, `Client` uses [hierarchical config resolution](config.md#configuration-discovery) to merge system, user, and project configs. Set `NoInherit: true` to use only the project config (recommended for CI and testing).
```

--------------------------------

### Agent-Sync Syncer Interface

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/library.md

Defines the `Sync` method for the agent-sync client, responsible for synchronizing files to their target locations. It accepts a context and `SyncOptions` and returns a `SyncResult` containing information about written, skipped files, and any errors encountered.

```go
type Syncer interface {
    Sync(ctx context.Context, opts SyncOptions) (*SyncResult, error)
}
```

--------------------------------

### YAML Configuration for Custom Transform Hooks

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Shows how to define custom transform hooks in agent-sync using YAML. These hooks allow for advanced transformations beyond simple templating or overrides by executing external commands. The 'command' specifies the script to run, and 'output_hash' can be used for verifying the transform output.

```yaml
transforms:
  - source: team-standards
    type: custom
    command: "./scripts/merge-yaml.sh"
    output_hash: sha256:expected...
```

--------------------------------

### Configure Tool Targets and Mappings

Source: https://context7.com/bianoble/agent-sync/llms.txt

Maps synchronized sources to specific AI tools. Built-in mappings exist for tools like Cursor and Claude-code, which can be overridden with custom definitions.

```yaml
targets:
  - source: team-rules
    tools: [cursor, claude-code, copilot]

tool_definitions:
  - name: cursor
    destination: .cursor/custom-path/
```

--------------------------------

### Define Core Agent Sync Interfaces (Go)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Defines the primary interfaces for agent-sync operations including Resolver, Syncer, Checker, Verifier, and Pruner. These interfaces abstract the core functionalities, allowing for flexible implementations and testing.

```Go
type Resolver interface {
    // Resolve resolves sources and returns an updated lockfile.
    // If sourceNames is non-empty, only those sources are resolved.
    Resolve(ctx context.Context, config Config, sourceNames []string) (Lockfile, error)
}

type Syncer interface {
    Sync(ctx context.Context, lock Lockfile, config Config, opts SyncOptions) (*SyncResult, error)
}

type Checker interface {
    Check(ctx context.Context, lock Lockfile, config Config) (*CheckResult, error)
}

type Verifier interface {
    // Verify checks whether upstream sources have changed since lockfile was written.
    Verify(ctx context.Context, lock Lockfile, config Config, sourceNames []string) (*VerifyResult, error)
}

type Pruner interface {
    Prune(ctx context.Context, lock Lockfile, config Config, opts PruneOptions) (*PruneResult, error)
}
```

--------------------------------

### Agent Sync Lockfile Structure (YAML)

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/lockfile.md

This snippet shows the typical structure of the agent-sync.lock file in YAML format. It includes the version, a list of sources, and detailed information about each source, such as its name, type, repository URL, resolved commit and tree SHAs, and a map of files with their respective SHA256 hashes. This structure is crucial for understanding how agent-sync tracks and verifies source integrity.

```yaml
version: 1
sources:
  - name: team-rules
    type: git
    repo: https://github.com/org/repo.git
    resolved:
      commit: abc123...
      tree: def456...
      files:
        rules/general.md:
          sha256: 789abc...
        rules/security.md:
          sha256: 012def...
    status: ok
```

--------------------------------

### Update Agent Sync Sources (Go)

Source: https://context7.com/bianoble/agent-sync/llms.txt

Updates agent sources by resolving them against their upstream and modifying the lockfile. It can update all sources or specific ones if `SourceNames` is provided. The result indicates which sources were updated.

```go
updateResult, err := client.Update(ctx, agentsync.UpdateOptions{
    // SourceNames: []string{"team-rules"}, // Optional: update specific sources only
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Updated %d sources\n", len(updateResult.Updated))
for _, source := range updateResult.Updated {
    fmt.Printf("  - %s\n", source)
}
```

--------------------------------

### Configuration: Overrides

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Defines how to modify target files after the sync process using append, prepend, or replace strategies.

```APIDOC
## Configuration: Overrides

### Description
Overrides allow modifying target files after they have been synced. The override file must exist at config validation time.

### Request Body
- **target** (string) - Required - The destination filename to match.
- **strategy** (string) - Required - The modification strategy: 'append', 'prepend', or 'replace'.
- **file** (string) - Required - The path to the override file relative to the project root.

### Request Example
overrides:
  - target: security.md
    strategy: append
    file: local/security-extension.md
```

--------------------------------

### Go Test Utilities for Environment Variables

Source: https://github.com/bianoble/agent-sync/blob/main/CONTRIBUTING.md

Demonstrates the use of `t.Setenv()` in Go tests for manipulating environment variables, ensuring they are automatically restored to their original state after the test.

```go
t.Setenv("MY_VAR", "test_value")
// Test code that uses MY_VAR
// Environment variable MY_VAR is automatically restored
```

--------------------------------

### Go Error Checking Convention

Source: https://github.com/bianoble/agent-sync/blob/main/CONTRIBUTING.md

Illustrates the recommended way to check for specific errors in Go, particularly `os.ErrNotExist`, using `errors.Is` to correctly handle wrapped errors.

```go
if errors.Is(err, os.ErrNotExist) {
  // Handle file not existing error
}
```

--------------------------------

### Agent Sync Configuration (YAML)

Source: https://context7.com/bianoble/agent-sync/llms.txt

Defines the sources and targets for agent-sync. It specifies repositories, branches, and paths to synchronize, along with variables for customization. This configuration is used to manage agent file integrity.

```yaml
version: 1

variables:
  project: payment-service
  team: payments

sources:
  - name: tob-differential-review
    type: git
    repo: https://github.com/trailofbits/skills.git
    ref: main
    paths:
      - plugins/differential-review/

targets:
  - source: tob-differential-review
    tools: [claude-code]
```

--------------------------------

### Run Full CI Checks Locally

Source: https://github.com/bianoble/agent-sync/blob/main/CONTRIBUTING.md

This command executes a series of local checks, including linting, testing with the race detector, and static analysis, to ensure code quality before submitting a pull request.

```bash
make lint && make test && make vet
```

--------------------------------

### Define Agent-Sync Configuration Structure

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/config.md

The base structure for the agent-sync.yaml file, including top-level keys for sources, targets, variables, transforms, and overrides.

```yaml
version: 1

sources:
  - name: ...
    type: git | url | local

targets:
  - source: ...
    tools: [...]
    destination: ...

variables:
  key: value

transforms:
  - source: ...
    type: template
    vars:
      key: value

overrides:
  - target: filename
    strategy: append | prepend | replace
    file: path/to/override

tool_definitions:
  - name: tool-name
    destination: .tool/path/
```

--------------------------------

### Check agent-sync for Configuration Drift

Source: https://context7.com/bianoble/agent-sync/llms.txt

Commands to verify that target files match the agent-sync lockfile. This is useful for CI pipelines to ensure consistency. The command returns an exit code of 0 if all files match, and 1 if drift is detected.

```bash
# Check all target files against lockfile
agent-sync check
```

```bash
# Exit code 0 = all files match, 1 = drift detected
agent-sync check && echo "All synced" || echo "Drift detected"
```

--------------------------------

### Agent-Sync Checker Interface

Source: https://github.com/bianoble/agent-sync/blob/main/docs/reference/library.md

Defines the `Check` method for the agent-sync client, used to verify the integrity of files against the lockfile. It takes a context and returns a `CheckResult` indicating whether the files are clean, listing any drifted or missing files, and any read errors.

```go
type Checker interface {
    Check(ctx context.Context) (*CheckResult, error)
}
```

--------------------------------

### Define Custom Tool Mappings

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Configuration snippet for defining custom tool paths or overriding built-in tool destination paths in agent-sync.

```yaml
tool_definitions:

  - name: internal-agent
    destination: .internal/agent-config/

  - name: cursor
    destination: .cursor/custom-rules/
```

--------------------------------

### POST /update

Source: https://github.com/bianoble/agent-sync/blob/main/docs/spec.md

Resolves sources against their upstream and updates the lockfile.

```APIDOC
## POST /update

### Description
Resolves each source to its current upstream state and updates the lockfile. Requires interactive confirmation unless --yes is passed.

### Method
POST

### Endpoint
agent-sync update [source-name...] [--dry-run]

### Parameters
#### Query Parameters
- **source-name** (string) - Optional - Specific sources to update
- **dry-run** (boolean) - Optional - Shows diff without applying changes
- **yes** (boolean) - Optional - Skip interactive confirmation

### Response
#### Success Response (200)
- **status** (string) - Success message indicating updated sources

#### Error Response (Non-zero exit)
- **error** (string) - Details of failed sources and error messages
```

--------------------------------

### Verify Upstream Sources (Go)

Source: https://context7.com/bianoble/agent-sync/llms.txt

Checks if upstream sources have changed since the lockfile was generated. It reports sources that are up-to-date and those that have changed, along with their old and new versions.

```go
verifyResult, err := client.Verify(ctx, []string{}) // Empty slice = all sources
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Up to date: %d sources\n", len(verifyResult.UpToDate))
fmt.Printf("Changed: %d sources\n", len(verifyResult.Changed))

for _, delta := range verifyResult.Changed {
    fmt.Printf("  %s: %s -> %s\n", delta.Name, delta.OldVersion, delta.NewVersion)
}
```