Handler Sync Github

Your responsibility is to implement the GitHub-specific sync mechanism. You are a HANDLER skill - you provide the concrete implementation of sync operations for GitHub repositories, following the handler pattern.

You handle:

• File Copying: Copying files from codex repository to local cache (or target repo in legacy mode)
• Pattern Matching: Glob and regex pattern matching for includes/excludes
• Frontmatter Parsing: Extracting sync rules from markdown file frontmatter
• Safety Checks: Deletion thresholds, dry-run mode, validation
• Sparse Checkout: Efficient cloning of only necessary files
• Cache Mode (v3.0): Writing to ephemeral cache directory with cache index updates

You are called by project-syncer and org-syncer skills. When cache_mode: true, you write to the local cache directory and update the cache index. When cache_mode: false (legacy), you delegate git operations to the fractary-repo plugin.

Handler Contract:

• Input: Source repo, target path (or repo), patterns, options
• Output: Files synced, files deleted, cache index updated (if cache_mode)
• Responsibility: File operations and cache management
• Does NOT: Create commits or push (unless legacy mode with repo plugin)

IMPORTANT: USE SCRIPTS FOR DETERMINISTIC OPERATIONS

• Complex operations live in bash scripts (scripts/*.sh)
• Keep LLM context minimal by executing scripts
• Scripts are deterministic and testable
• This skill coordinates script execution

IMPORTANT: SAFETY FIRST

• Always check deletion thresholds before applying changes
• Support dry-run mode (show what would change without changing)
• Validate patterns before using them
• Log all operations for audit trail

IMPORTANT: DELEGATE GIT OPERATIONS

• NEVER execute git commands directly
• Use fractary-repo plugin for clone, commit, push
• Maintain clean separation of concerns
• Handler = file operations, Repo plugin = git operations

Cache Mode (v3.0 - default):

{
  "operation": "sync-docs",
  "source_repo": "<org>/<codex-repo>",
  "target_path": ".fractary/plugins/codex/cache/<org>/<project>",
  "target_branch": "test",
  "direction": "to-cache",
  "patterns": {
    "include": ["docs/**", "CLAUDE.md", ...],
    "exclude": ["**/.git/**", "**/node_modules/**", ...]
  },
  "options": {
    "dry_run": false,
    "deletion_threshold": 50,
    "deletion_threshold_percent": 20,
    "sparse_checkout": true,
    "cache_mode": true,
    "update_cache_index": true
  }
}

Legacy Mode (git-to-git):

{
  "operation": "sync-docs",
  "source_repo": "<org>/<source-repo>",
  "target_repo": "<org>/<target-repo>",
  "target_branch": "main",
  "direction": "to-target",
  "patterns": {
    "include": ["docs/**", "CLAUDE.md", ...],
    "exclude": ["**/.git/**", "**/node_modules/**", ...]
  },
  "options": {
    "dry_run": false,
    "deletion_threshold": 50,
    "deletion_threshold_percent": 20,
    "sparse_checkout": true,
    "cache_mode": false,
    "create_commit": true,
    "commit_message": "sync: Update docs from project",
    "push": true
  },
  "repo_plugin": {
    "use_for_git_ops": true
  }
}

Required Parameters:

• operation: Must be "sync-docs"
• source_repo: Source (codex) repository full name
• target_path (cache mode) OR target_repo (legacy): Target location
• target_branch: Branch to checkout in codex repository (from environment mapping)
• patterns: Include and exclude patterns

Optional Parameters:

• direction: "to-cache" (v3.0) or "to-target" (legacy)
• options.cache_mode: true (default in v3.0) to write to cache directory
• options.update_cache_index: true to update cache index after sync
• options: Other configuration options with defaults
• repo_plugin: Repo plugin integration config (legacy mode only)

Environment/Branch Parameters:

• target_branch: The git branch in the codex repository to sync with
  • Example: "test" for test environment
  • Example: "main" for production environment
  • The handler MUST checkout this branch before syncing files
  • If the branch doesn't exist, return a clear error

Output:

🎯 STARTING: GitHub Sync Handler
Source: <source_repo>
Target: <target_repo>
Branch: <target_branch>
Patterns: <include_count> include, <exclude_count> exclude
Dry Run: <yes|no>
───────────────────────────────────────

Step 2: Validate Inputs

Execute validation:

• Check source_repo and target_repo are non-empty
• Check target_branch is non-empty
• Check patterns.include is non-empty array
• Check patterns.exclude is array (can be empty)
• Validate all patterns are valid glob expressions

If validation fails:

• Output error message
• Return failure
• Exit workflow

Step 3: Read Workflow for Sync Operation

Based on the operation, read the appropriate workflow file:

For operation = "sync-docs":

READ: skills/handler-sync-github/workflow/sync-files.md
EXECUTE: Steps from workflow

This workflow will:

1. Clone source (codex) repository (via repo plugin)
2. Checkout target_branch in codex repository (via repo plugin)
   • If branch doesn't exist, fail with clear error
3. Clone target repository if needed (via repo plugin)
4. Execute sync-docs.sh script to copy files
5. Validate results (deletion thresholds, file counts)
6. Return results to this skill

Branch Checkout Details:

• The codex repository must be checked out to the specified target_branch
• This ensures documentation is synced to/from the correct environment
• Example: git checkout test for test environment
• Example: git checkout main for production environment

Step 4: Process Workflow Results

The workflow returns:

{
  "status": "success|failure",
  "files_synced": 25,
  "files_deleted": 2,
  "files_modified": 15,
  "files_added": 10,
  "deletion_threshold_exceeded": false,
  "dry_run": false
}

If status is "failure":

• Output error from workflow
• Return failure
• Exit

If status is "success":

• Continue to step 5

Step 5: Output Completion Message

Output:

✅ COMPLETED: GitHub Sync Handler
Branch: <target_branch>
Files synced: <files_synced>
Files added: <files_added>
Files modified: <files_modified>
Files deleted: <files_deleted>
Deletion threshold: <passed|exceeded>
───────────────────────────────────────
Next: Caller will create commit and push

Step 6: Return Results

Return structured results to caller:

{
  "status": "success",
  "handler": "github",
  "target_branch": "<target_branch>",
  "files_synced": 25,
  "files_deleted": 2,
  "files_modified": 15,
  "files_added": 10,
  "deletion_threshold_exceeded": false,
  "files_list": {
    "added": ["file1.md", "file2.md", ...],
    "modified": ["file3.md", ...],
    "deleted": ["file4.md", ...]
  },
  "dry_run": false
}

✅ For successful sync:

• Files copied from source to target
• Patterns applied correctly
• Deletion thresholds validated
• Results returned with file counts
• No errors occurred

✅ For failed sync:

• Error clearly identified
• No partial changes applied (atomic operation)
• Cleanup performed (temp directories removed)
• Error returned to caller

✅ For dry-run:

• No files actually copied
• File counts show what WOULD be synced
• Deletion threshold validated
• Results show projected changes

✅ In all cases:

• Start and end messages displayed
• Structured results returned
• Temp directories cleaned up

{
  "status": "success",
  "handler": "github",
  "mode": "cache",
  "target_branch": "test",
  "files_synced": 25,
  "files_deleted": 2,
  "files_modified": 15,
  "files_added": 10,
  "deletion_threshold_exceeded": false,
  "cache_path": ".fractary/plugins/codex/cache/org/project",
  "cache_index_updated": true,
  "files_list": {
    "added": [...],
    "modified": [...],
    "deleted": [...]
  },
  "dry_run": false
}

Success Output (Legacy Mode)

{
  "status": "success",
  "handler": "github",
  "mode": "git",
  "target_branch": "main",
  "files_synced": 25,
  "files_deleted": 2,
  "files_modified": 15,
  "files_added": 10,
  "deletion_threshold_exceeded": false,
  "files_list": {
    "added": [...],
    "modified": [...],
    "deleted": [...]
  },
  "dry_run": false
}

Failure Output

{
  "status": "failure",
  "handler": "github",
  "target_branch": "test",
  "error": "Error message",
  "phase": "clone|checkout|sync|cache-index|validate",
  "partial_results": null
}

Dry-Run Output

{
  "status": "success",
  "handler": "github",
  "target_branch": "test",
  "files_synced": 25,
  "files_deleted": 2,
  "deletion_threshold_exceeded": false,
  "would_add": [...],
  "would_modify": [...],
  "would_delete": [...],
  "dry_run": true,
  "recommendation": "Safe to proceed|Review deletions"
}

If sync-docs.sh script fails:

1. Capture stderr and stdout
2. Parse error message
3. Clean up temp directories
4. Return failure with clear error

Common script errors:

• Pattern matching failed: Invalid glob expression
• File copy failed: Permission denied or disk full
• Repository structure unexpected: Codex structure doesn't match expected format

Common repo plugin errors:

• Clone failed: Authentication or repository not found
• Permission denied: No access to repository
• Network error: Connection timeout or API rate limit

Example error:

{
  "status": "failure",
  "handler": "github",
  "target_branch": "test",
  "error": "Branch 'test' not found in repository fractary/codex.fractary.com",
  "phase": "checkout",
  "resolution": "Create the branch or update environments config to use an existing branch"
}

Common causes:

• Branch doesn't exist: Need to create the branch first
• Branch name mismatch: Config has wrong branch name
• Permission denied: No access to the branch

Key Components:

1. sync-docs.sh: Main sync script (file copying with patterns)
2. parse-frontmatter.sh: Extract sync rules from markdown frontmatter
3. validate-sync.sh: Check deletion thresholds and file counts

Handler Benefits:

• Separation of concerns (file ops vs git ops)
• Testable scripts outside LLM context
• Reusable across different orchestration patterns
• Easy to add new handlers (vector, mcp) without changing orchestration

Future Handlers:

• handler-sync-vector: Sync to vector database
• handler-sync-mcp: Sync via MCP server
• All follow same contract, just different implementation