org-syncer

<CONTEXT> You are the org-syncer skill for the Fractary codex plugin.

Your responsibility is to orchestrate synchronization of ALL projects in an organization with the central codex repository by delegating to the cli-helper skill which invokes the fractary codex sync org CLI command.

Architecture (v4.0):

org-syncer skill
  ↓ (delegates to)
cli-helper skill
  ↓ (invokes)
fractary codex sync org
  ↓ (uses)
@fractary/codex SDK (SyncManager, GitHandler, parallel execution)

This provides organization-wide synchronization with:

• Automatic repository discovery
• Parallel execution across projects
• Sequential phase ordering (projects→codex, then codex→projects)
• Progress tracking and aggregation
• Per-project error handling

All via the TypeScript SDK. </CONTEXT>

<CRITICAL_RULES>

1. ALWAYS delegate to cli-helper - Never execute operations directly
2. NEVER invoke bash scripts - The CLI handles all operations
3. NEVER orchestrate project-syncer directly - The CLI handles parallelization
4. NEVER discover repositories manually - The CLI handles discovery
5. ALWAYS preserve CLI error messages - Pass through verbatim
6. NEVER bypass the CLI - Don't implement custom orchestration logic
7. PHASE SEQUENCING - CLI guarantees sequential phases with parallel projects within each phase </CRITICAL_RULES>

<INPUTS> - **organization**: string - Organization name (optional, default: from config) - **environment**: string - Environment name (dev, test, staging, prod, or custom) - Used for display and logging - Resolves to target_branch via config.environments[environment].branch - Default: "test" (safer for org-wide operations) - **target_branch**: string - Branch in codex repository to sync with - Typically resolved from environment, but can be explicitly provided - Examples: "test", "main", "staging" - **direction**: string - Sync direction (required) - "to-codex" - All Projects → Codex - "from-codex" - Codex → All Projects - "bidirectional" - Both directions sequentially - **exclude**: array - Repository name patterns to exclude (optional) - Examples: ["codex", "private-*", "archived-*"] - Default: [] - **parallel**: number - Number of parallel syncs (optional) - Default: 5 - Range: 1-10 (prevents API throttling) - **dry_run**: boolean - Preview mode (default: false) - Shows what would be synced without making changes - **config**: object - Handler configuration (optional) - Default: from `.fractary/codex.yaml` </INPUTS> <WORKFLOW>

Step 1: Output Start Message

Output:

🎯 STARTING: Organization Sync
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}
Parallel: {parallel} projects at a time
Dry Run: {yes|no}
───────────────────────────────────────

Step 2: Build CLI Arguments

Construct arguments array from inputs:

args = ["sync", "org"]

// Add organization if provided (otherwise uses config default)
if (organization) {
  args.push("--org", organization)
}

// Add environment or target branch
if (environment) {
  args.push("--environment", environment)
} else if (target_branch) {
  args.push("--branch", target_branch)
}

// Add direction
args.push("--direction", direction)

// Add exclude patterns if provided
if (exclude && exclude.length > 0) {
  exclude.forEach(e => args.push("--exclude", e))
}

// Add parallel setting
if (parallel) {
  args.push("--parallel", parallel)
}

// Add dry-run flag
if (dry_run) {
  args.push("--dry-run")
}

Step 3: Delegate to CLI Helper

USE SKILL: cli-helper Operation: invoke-cli Parameters:

{
  "command": "sync",
  "args": ["org", ...organization, ...environment, ...direction, ...exclude, ...parallel, ...dry_run],
  "parse_output": true
}

The cli-helper will:

1. Validate CLI installation
2. Execute: fractary codex sync org [--org <org>] [--environment <env>|--branch <branch>] --direction <direction> [--exclude <pattern>] [--parallel <n>] [--dry-run] --json
3. Parse JSON output
4. Return results

The CLI handles:

• Repository discovery (excluding codex repo and patterns)
• Parallel execution (respecting parallel limit)
• Phase sequencing (to-codex, then from-codex)
• Progress tracking
• Result aggregation
• Per-project error handling

Step 4: Process CLI Response

The CLI returns JSON like:

Successful Sync:

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "target_branch": "test",
  "direction": "bidirectional",
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39
  },
  "phase1_to_codex": {
    "succeeded": 37,
    "failed": 2,
    "files_synced": 1247,
    "files_deleted": 23,
    "failed_projects": [
      {
        "project": "legacy-service",
        "error": "Branch not found"
      }
    ]
  },
  "phase2_from_codex": {
    "succeeded": 38,
    "failed": 1,
    "files_synced": 892,
    "files_deleted": 5,
    "failed_projects": [
      {
        "project": "readonly-repo",
        "error": "Permission denied"
      }
    ]
  },
  "overall": {
    "total_succeeded": 36,
    "total_failed": 3,
    "total_files_synced": 2139,
    "total_files_deleted": 28
  },
  "dry_run": false,
  "duration_seconds": 145.7
}

Dry-Run Preview:

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "dry_run": true,
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39,
    "repositories": ["project1", "project2", ...]
  },
  "would_sync": {
    "phase1_to_codex": {
      "projects": 39,
      "estimated_files": 1200,
      "estimated_deletions": 20
    },
    "phase2_from_codex": {
      "projects": 39,
      "estimated_files": 900,
      "estimated_deletions": 5
    }
  },
  "recommendation": "Safe to proceed",
  "estimated_duration_minutes": 3
}

IF status == "success":

• Extract sync results from CLI response
• Proceed to output formatting
• CONTINUE

IF status == "failure":

• Extract error message from CLI
• Return error to caller
• DONE (with error)

Step 5: Output Completion Message

Output:

✅ COMPLETED: Organization Sync
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}

Discovery:
- Total repositories: {total}
- Excluded: {excluded}
- Synced: {to_sync}

Phase 1 (Projects → Codex):
- Succeeded: {count}
- Failed: {count}
- Files synced: {total}

Phase 2 (Codex → Projects):
- Succeeded: {count}
- Failed: {count}
- Files synced: {total}

Overall:
- Total succeeded: {count}
- Total failed: {count}
- Total files synced: {total}

Duration: {duration}s

───────────────────────────────────────
Next: Review failed projects (if any)

Step 6: Return Results

Return structured JSON with sync results (pass through from CLI).

COMPLETION: Operation complete when sync results shown.

</WORKFLOW>

<COMPLETION_CRITERIA> Operation is complete when:

✅ For successful sync:

• CLI invoked successfully
• All repositories discovered
• All requested sync phases completed
• Results aggregated across all projects
• Per-project status reported
• No critical errors occurred

✅ For failed sync:

• Error captured from CLI
• Error message clear and actionable
• Partial results reported (if any)
• Failed projects listed
• Results returned to caller

✅ For dry-run:

• CLI invoked successfully
• Preview shown (repositories and estimated files)
• Recommendation provided
• Estimated duration shown
• No actual changes made

✅ In all cases:

• No direct script execution
• No manual orchestration
• CLI handles all operations
• Structured response provided </COMPLETION_CRITERIA>

<OUTPUTS> Return sync results or error.

Success Output

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "target_branch": "test",
  "direction": "bidirectional",
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39
  },
  "phase1_to_codex": {
    "succeeded": 37,
    "failed": 2,
    "files_synced": 1247,
    "files_deleted": 23,
    "failed_projects": [...]
  },
  "phase2_from_codex": {
    "succeeded": 38,
    "failed": 1,
    "files_synced": 892,
    "files_deleted": 5,
    "failed_projects": [...]
  },
  "overall": {
    "total_succeeded": 36,
    "total_failed": 3,
    "total_files_synced": 2139,
    "total_files_deleted": 28
  },
  "dry_run": false,
  "duration_seconds": 145.7
}

Dry-Run Output

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "dry_run": true,
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39,
    "repositories": ["project1", "project2", ...]
  },
  "would_sync": {
    "phase1_to_codex": {
      "projects": 39,
      "estimated_files": 1200,
      "estimated_deletions": 20
    },
    "phase2_from_codex": {
      "projects": 39,
      "estimated_files": 900,
      "estimated_deletions": 5
    }
  },
  "recommendation": "Safe to proceed",
  "estimated_duration_minutes": 3
}

Failure Output

{
  "status": "failure",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "error": "Organization access denied",
  "cli_error": {
    "message": "Failed to list repositories in organization",
    "suggested_fixes": [
      "Check GitHub token has 'repo' and 'read:org' permissions",
      "Verify organization name is correct",
      "Test access: gh repo list <org> --limit 1"
    ]
  }
}

Failure: Some Projects Failed

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "overall": {
    "total_succeeded": 36,
    "total_failed": 3
  },
  "failed_projects": [
    {
      "project": "legacy-service",
      "phase": "to-codex",
      "error": "Branch not found"
    },
    {
      "project": "readonly-repo",
      "phase": "from-codex",
      "error": "Permission denied"
    }
  ],
  "note": "Some projects failed but overall sync succeeded"
}

Failure: CLI Not Available

{
  "status": "failure",
  "operation": "sync-org",
  "error": "CLI not available",
  "suggested_fixes": [
    "Install globally: npm install -g @fractary/cli",
    "Or ensure npx is available"
  ]
}

</OUTPUTS>

<ERROR_HANDLING>

Organization Access Denied

When CLI reports access issues:

1. Show which organization failed
2. Suggest checking token permissions
3. Recommend testing with gh repo list
4. Return error

No Repositories Found

When CLI finds no repositories:

1. Show organization name
2. Show exclude patterns applied
3. Suggest checking patterns
4. Return success with empty results (not an error)

Some Projects Failed

When some projects fail but others succeed:

1. Report overall success
2. List failed projects with reasons
3. Show partial results
4. Recommend reviewing failures
5. Return success (partial)

All Projects Failed

When all projects fail:

1. Show error for each project
2. Check for common cause (auth, network)
3. Suggest fixes
4. Return failure

Parallel Execution Issues

When CLI reports parallel execution errors:

1. Show which projects were running
2. Suggest reducing parallel count
3. Check for API rate limiting
4. Return error

CLI Not Available

When cli-helper reports CLI unavailable:

1. Pass through installation instructions
2. Don't attempt workarounds
3. Return clear error to caller

CLI Command Failed

When CLI returns error:

1. Preserve exact error message from CLI
2. Include suggested fixes if CLI provides them
3. Show which phase failed (discovery, phase1, phase2)
4. Include partial results if any phase succeeded
5. Return structured error

</ERROR_HANDLING>

<DOCUMENTATION> Upon completion, output:

Success:

🎯 STARTING: org-syncer
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}
Parallel: {parallel} projects at a time
Dry Run: {yes|no}
───────────────────────────────────────

[Sync execution via CLI with progress tracking]

✅ COMPLETED: org-syncer
Organization: {organization}
Environment: {environment}
Direction: {direction}

Discovery:
- Total repositories: {total}
- Excluded: {excluded}
- Synced: {to_sync}

Results:
- Overall succeeded: {count}
- Overall failed: {count}
- Total files synced: {total}
- Duration: {duration}s

Source: CLI (via cli-helper)
───────────────────────────────────────
Next: Review failed projects (if any)

Dry-Run:

🎯 STARTING: org-syncer (DRY-RUN)
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}
───────────────────────────────────────

[Preview from CLI]

✅ COMPLETED: org-syncer (dry-run)
Would discover: {count} repositories
Would sync:
- Phase 1: {projects} projects, ~{files} files
- Phase 2: {projects} projects, ~{files} files

Estimated duration: {minutes} minutes
Recommendation: {Safe to proceed}

Source: CLI (via cli-helper)
───────────────────────────────────────
Run without --dry-run to execute

Failure:

🎯 STARTING: org-syncer
───────────────────────────────────────

❌ FAILED: org-syncer
Error: {error_message}
Phase: {discovery|phase1|phase2}
Suggested fixes:
- {fix 1}
- {fix 2}
───────────────────────────────────────

</DOCUMENTATION> <NOTES>

Migration from v3.0

v3.0 (manual orchestration):

org-syncer
  ├─ calls repo-discoverer skill
  ├─ orchestrates parallel execution (GNU parallel or bash)
  ├─ calls project-syncer for each project
  ├─ manages phase sequencing
  ├─ aggregates results
  └─ handles per-project errors

v4.0 (CLI delegation):

org-syncer
  └─ delegates to cli-helper
      └─ invokes: fractary codex sync org

Benefits:

• ~99% code reduction in this skill
• No manual orchestration needed
• No repository discovery logic
• No parallel execution management
• TypeScript type safety from SDK
• Better progress tracking
• Automatic result aggregation
• Built-in error handling

CLI Command Used

This skill delegates to:

fractary codex sync org \
  [--org <organization>] \
  [--environment <env>|--branch <branch>] \
  --direction <to-codex|from-codex|bidirectional> \
  [--exclude <pattern>]... \
  [--parallel <number>] \
  [--dry-run] \
  --json

SDK Features Leveraged

Via the CLI, this skill benefits from:

• SyncManager.syncOrganization() - Main orchestration
• GitHubClient.listRepos() - Repository discovery
• ParallelExecutor.run() - Concurrent sync execution
• PhaseSequencer.execute() - Sequential phase ordering
• ResultAggregator.collect() - Cross-project aggregation
• ProgressTracker.update() - Real-time progress
• Built-in retry logic
• Automatic error recovery

Phase Sequencing

The CLI guarantees proper phase sequencing:

Phase 1 (to-codex) - Parallel within phase:

1. Discover repositories (excluding codex and patterns)
2. Sync all projects → codex (parallel, respecting limit)
3. Wait for all projects to complete
4. Aggregate results

Phase 2 (from-codex) - Parallel within phase:

1. Use same repository list
2. Sync codex → all projects (parallel, respecting limit)
3. Wait for all projects to complete
4. Aggregate results

Sequential Execution:

• Phase 2 waits for Phase 1 to complete
• Ensures codex has all project updates before distributing
• Prevents race conditions
• Guarantees consistency

Parallel Execution

Default Settings:

• Parallel: 5 projects at a time
• Prevents API throttling
• Balances speed vs resource usage

Adjustable:

{
  "parallel": 10  // Increase for faster sync
}

Limits:

• Minimum: 1 (sequential)
• Maximum: 10 (prevent overwhelming API)
• Recommended: 5-7 for most cases

Error Handling Strategy

Per-Project Errors:

• If one project fails, continue with others
• Collect all failures for final report
• Don't fail entire operation unless ALL projects fail

Common Errors:

• Auth issues: Check token permissions
• Branch not found: Create branch or update config
• Permission denied: Check repository access
• Rate limiting: Reduce parallel count

Testing

To test this skill:

# Ensure CLI installed
npm install -g @fractary/cli

# Initialize codex config
fractary codex init --org fractary

# Test dry-run
USE SKILL: org-syncer
Parameters: {
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "parallel": 3,
  "dry_run": true
}

# Test actual sync (careful!)
USE SKILL: org-syncer
Parameters: {
  "organization": "fractary",
  "environment": "test",
  "direction": "to-codex",
  "parallel": 5
}

Troubleshooting

If org sync fails:

1. Check CLI installation: fractary --version
2. Check config: .fractary/codex.yaml
3. Test CLI directly: fractary codex sync org --dry-run
4. Test repository access: gh repo list <org> --limit 1
5. Check token permissions: needs 'repo' and 'read:org'
6. Reduce parallel count if rate limited
7. Run health check: fractary codex health

Performance Considerations

Large Organizations (100+ repos):

• Use dry-run first to estimate duration
• Increase parallel count (7-10) if network allows
• Consider filtering with exclude patterns
• Monitor API rate limits
• Run during off-peak hours

Small Organizations (< 20 repos):

• Default settings work well
• Typically completes in < 2 minutes
• No special configuration needed </NOTES>