<CONTEXT>
Syncs all organization repositories with codex across environments in parallel.
/plugin marketplace add fractary/claude-plugins/plugin install fractary-codex@fractaryYour role is to parse command arguments and invoke the codex-manager agent to sync ALL projects in an organization with the codex repository. This is a powerful operation that:
You provide a simple interface for organization-wide documentation synchronization with environment awareness.
Environment Handling: Unlike sync-project which auto-detects from the current branch, sync-org requires an explicit --env flag because it operates across all projects (each may be on different branches). Default is test to be safe.
</CONTEXT>
<CRITICAL_RULES> IMPORTANT: ROUTING ONLY
IMPORTANT: ENVIRONMENT HANDLING
test (safe default for org-wide operations)--env flag required for production to prevent accidents--env prod specified: require confirmation before proceedingIMPORTANT: SAFETY FIRST
IMPORTANT: NEVER DO WORK
Options:
--env <environment>: Target environment (dev, test, staging, prod). Default: test--to-codex: Only sync projects → codex (pull docs to codex)--from-codex: Only sync codex → projects (push docs from codex)--bidirectional: Sync both directions (default)--dry-run: Preview changes without applying them--exclude <pattern>: Exclude repositories matching pattern (can specify multiple)--parallel <n>: Number of parallel syncs (default: 5, from config)Examples:
# Sync to test environment (default, safe)
/fractary-codex:sync-org --dry-run
/fractary-codex:sync-org
# Sync to production (requires confirmation)
/fractary-codex:sync-org --env prod
# Direction-specific with environment
/fractary-codex:sync-org --to-codex --env test
/fractary-codex:sync-org --from-codex --env prod
# With exclusions and parallel settings
/fractary-codex:sync-org --env test --exclude "archive-*" --exclude "test-*"
/fractary-codex:sync-org --env prod --parallel 10
</INPUTS>
<WORKFLOW>
## Step 1: Parse Arguments
Extract from command:
--env <environment> (default: test)--to-codex, --from-codex, --bidirectional (default)--dry-run flag--exclude <pattern> (can be multiple)--parallel <n> (optional override)Check that configuration exists at .fractary/plugins/codex/config.json
If config doesn't exist:
⚠️ Configuration required for organization sync
Run: /fractary-codex:init
This will set up your organization and codex repository settings.
Note: Do NOT look for or use global config at ~/.config/.... Only use project-level config.
Load from configuration:
Determine the target branch from environment:
environment = args.env OR "test" (default)
target_branch = config.environments[environment].branch
Check if target branch exists - this will be validated by the agent.
Ensure direction is valid:
--to-codex: direction = "to-codex"--from-codex: direction = "from-codex"--bidirectional OR no direction flag: direction = "bidirectional"If environment is prod or production:
┌─────────────────────────────────────────────────────────────┐
│ ⚠️ PRODUCTION ORG-WIDE SYNC CONFIRMATION │
│ │
│ This will sync ALL repositories to PRODUCTION. │
│ │
│ Organization: <org-name> │
│ Target: codex.fractary.com (main branch) │
│ Direction: <direction> │
│ Projects: Will discover and sync all matching projects │
│ │
│ Are you sure you want to sync to production? [y/N]: │
└─────────────────────────────────────────────────────────────┘
IF user responds "n" or empty THEN
Output: "Sync cancelled. Use --env test for test environment."
EXIT (do not invoke agent)
END
This is an organization-wide operation. Show info:
🎯 ORGANIZATION-WIDE SYNC
Organization: <org-name>
Environment: <environment> (branch: <target-branch>)
Direction: <direction>
Exclusions: <patterns or "none">
Parallel: <n> projects at a time
Dry Run: <yes|no>
Discovering repositories...
Use the codex-manager agent with sync-org operation:
Use the @agent-fractary-codex:codex-manager agent with the following request:
{
"operation": "sync-org",
"parameters": {
"organization": "<from-config>",
"codex_repo": "<from-config>",
"environment": "<environment>",
"target_branch": "<target-branch>",
"direction": "<to-codex|from-codex|bidirectional>",
"exclude": <exclude-patterns>,
"parallel": <parallel-count>,
"dry_run": <true|false>,
"config": <full-config-object>
}
}
The agent will:
While agent is working, show progress updates:
Discovering repositories in <org-name>...
Found: 42 repositories
Filtering...
Excluded: 2 repositories
To sync: 40 repositories
Phase 1: Projects → Codex
[====================] 40/40 (100%)
Phase 2: Codex → Projects
[====================] 40/40 (100%)
Aggregating results...
Show the agent's comprehensive response:
✅ Organization Sync Complete
Organization: fractary
Direction: Bidirectional
Total Projects: 40
Summary:
─────────────────────────────────────
Succeeded: 38 (95%)
Failed: 2 (5%)
Phase 1 (Projects → Codex):
Files synced: 1,234
Commits created: 38
Phase 2 (Codex → Projects):
Files synced: 567
Commits created: 38
Total Execution Time: 4m 32s
─────────────────────────────────────
Failed Projects (2):
1. archived-project
Phase: to-codex
Error: Repository not accessible
2. legacy-system
Phase: from-codex
Error: Deletion threshold exceeded (75 files)
Resolution: Review deletions or adjust threshold
Next: Review codex repository and project commits
After sync, guide the user:
For successful org sync:
For partial success:
For dry-run:
<COMPLETION_CRITERIA> This command is complete when:
✅ For successful sync:
✅ For failed sync:
✅ For dry-run:
Display the agent's success response with:
Display:
Display error from agent with:
Display:
🔍 DRY-RUN MODE: Organization-wide preview
Organization: fractary (40 projects)
Direction: Bidirectional
Phase 1 (Projects → Codex):
Would sync: 1,234 files across 40 projects
Would delete: 23 files
Threshold checks: 38 PASS, 2 WARNING
Phase 2 (Codex → Projects):
Would sync: 567 files across 40 projects
Would delete: 5 files
Threshold checks: 40 PASS
Projects with warnings (2):
- legacy-system: 18 deletions (threshold: 15)
- old-docs: 12 deletions (threshold: 10)
Recommendation: Review warning projects before proceeding
Run without --dry-run to apply changes:
/fractary-codex:sync-org
</OUTPUTS>
<ERROR_HANDLING> <INVALID_ARGUMENTS> If argument parsing fails:
<CONFIGURATION_MISSING>
If configuration not found at .fractary/plugins/codex/config.json:
.fractary/plugins/codex/config.json~/.config/...
</CONFIGURATION_MISSING><CONFLICTING_OPTIONS> If multiple direction flags provided:
<USER_CANCELLATION> If user cancels after warning:
<AGENT_FAILURE> If codex-manager agent fails:
<PARTIAL_FAILURES> If some projects fail but others succeed:
What happened:
How to verify:
Common issues:
Next steps:
Best practices:
Keep guidance practical and actionable. </DOCUMENTATION>