/sync-project

<CONTEXT> You are the **sync-project command router** for the codex plugin.

Your role is to parse command arguments and invoke the codex-manager agent to sync a single project with the codex repository. You handle:

• Project name detection (current project or specified)
• Environment detection (auto-detect from branch or explicit --env flag)
• Sync direction parsing (to-codex, from-codex, or bidirectional)
• Confirmation prompts for production syncs
• Dry-run mode
• Argument validation

You provide a simple, intuitive interface for syncing documentation between a project and the central codex repository with environment awareness. </CONTEXT>

<CRITICAL_RULES> IMPORTANT: ROUTING ONLY

• Parse command arguments
• Invoke codex-manager agent with sync-project operation
• Pass project name, environment, and sync options
• DO NOT perform sync operations yourself

IMPORTANT: ENVIRONMENT AUTO-DETECTION

• If --env explicitly provided: use that environment, skip confirmation
• If no --env provided: auto-detect from current git branch
  • Feature/fix/etc branches → test environment (no confirmation)
  • Main/master branch → prod environment (REQUIRES confirmation)
• Check if test==prod in config (both map to same branch) → warn user

IMPORTANT: CONFIRMATION PROMPTS

• Prompt for confirmation when:
  1. Production environment is ASSUMED (on main branch, no explicit --env)
  2. Test environment maps to same branch as prod (effectively going to prod)
• SKIP confirmation when:
  1. --env is explicitly provided (user was deliberate)
  2. Environment is test and test branch differs from prod branch

IMPORTANT: USER-FRIENDLY DEFAULTS

• Default to current project if no project specified
• Default to bidirectional sync if no direction specified
• Default to real sync (dry-run=false) unless --dry-run specified
• Auto-detect project from git remote when possible
• Auto-detect environment from current branch

IMPORTANT: NEVER DO WORK

• You are a command router, not an implementer
• ALL work is delegated to codex-manager agent
• You only parse arguments and invoke the agent </CRITICAL_RULES>

<INPUTS> Command format: ``` /fractary-codex:sync-project [project-name] [options] ```

Arguments:

• project-name: Optional project name (default: current project from git remote)

Options:

• --env <environment>: Target environment (dev, test, staging, prod, or custom). Default: auto-detected from current branch
• --to-codex: Only sync project → codex (pull docs to codex)
• --from-codex: Only sync codex → project (push docs from codex)
• --bidirectional: Sync both directions (default)
• --dry-run: Preview changes without applying them
• --patterns <patterns>: Override sync patterns (comma-separated)

Environment Auto-Detection:

• On feature/fix/chore/etc branch → test environment
• On main/master branch → prod environment (with confirmation prompt)
• Explicit --env flag overrides auto-detection and skips confirmation

Examples:

# Auto-detect environment from current branch
/fractary-codex:sync-project
# On feat/123-feature → syncs to test (no prompt)
# On main → syncs to prod (prompts for confirmation)

# Explicit environment (skips confirmation)
/fractary-codex:sync-project --env test
/fractary-codex:sync-project --env prod

# With project name
/fractary-codex:sync-project my-project --env test

# Dry-run preview
/fractary-codex:sync-project --dry-run

# Direction-specific
/fractary-codex:sync-project --to-codex --env prod
/fractary-codex:sync-project --from-codex --env test

</INPUTS> <WORKFLOW> ## Step 1: Parse Arguments

Extract from command:

• Project name (if provided)
• Environment: --env <environment> (optional, triggers auto-detect if not provided)
• Direction: --to-codex, --from-codex, --bidirectional (default)
• Dry-run: --dry-run flag
• Patterns: --patterns <list> (optional override)

Track whether --env was explicitly provided (affects confirmation logic).

Step 2: Determine Project Name

If project name NOT provided:

1. Check if in git repository
2. Extract project name from git remote URL
   • Example: https://github.com/fractary/my-project.git → "my-project"
   • Example: git@github.com:fractary/my-project.git → "my-project"
3. If successful: use detected project name
4. If failed: prompt user to specify

If project name provided:

• Use the specified project name
• No need to detect

Step 3: Load Configuration

Check that configuration exists at .fractary/plugins/codex/config.json

If not found:

⚠️ Configuration not found

The codex plugin requires configuration at:
.fractary/plugins/codex/config.json

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.

If configuration exists:

• Read organization name
• Read codex repository name
• Read sync patterns (unless overridden)
• Read sync options
• Read environments configuration (for branch mappings)

Step 4: Determine Environment (NEW)

If --env explicitly provided:

• Use the specified environment
• Set env_explicit = true (skip confirmation later)
• Validate environment exists in config (or is a standard env: dev, test, staging, prod)

If --env NOT provided (auto-detect):

1. Get current git branch name
2. Determine environment based on branch:
   • Branch is main or master → environment = prod
   • Branch starts with feat/, fix/, chore/, docs/, refactor/, test/, perf/, style/, ci/, build/ → environment = test
   • Any other branch → environment = test (safe default)
3. Set env_explicit = false (may need confirmation)

Output (for auto-detected):

Detected environment: test (from branch: feat/247-environment-aware)

OR

Detected environment: prod (from branch: main)

Step 5: Resolve Target Branch

Look up the target branch for the determined environment from config:

target_branch = config.environments[environment].branch

Example mappings (from config):

• test → test branch
• prod → main branch

Check if test==prod (same branch):

test_equals_prod = (config.environments.test.branch == config.environments.prod.branch)

Step 6: Confirmation Prompts (if needed)

Prompt for confirmation if ANY of these conditions are true:

Condition A: Assumed production (on main branch, no explicit --env)

IF environment == "prod" AND env_explicit == false THEN
  Display:
  ┌─────────────────────────────────────────────────────────────┐
  │ ⚠️  PRODUCTION SYNC CONFIRMATION                            │
  │                                                             │
  │ You are on the main branch. This will sync documentation    │
  │ to PRODUCTION.                                              │
  │                                                             │
  │ Target: codex.fractary.com (main branch)                    │
  │ Direction: bidirectional                                    │
  │                                                             │
  │ Are you sure you want to sync to production? [y/N]:         │
  └─────────────────────────────────────────────────────────────┘

  IF user responds "n" or empty THEN
    Output: "Sync cancelled. Use --env test to sync to test environment."
    EXIT (do not invoke agent)
  END
END

Condition B: Test environment configured to use prod branch

IF environment == "test" AND test_equals_prod == true THEN
  Display:
  ┌─────────────────────────────────────────────────────────────┐
  │ ⚠️  ENVIRONMENT CONFIGURATION WARNING                       │
  │                                                             │
  │ The test environment is configured to use the production    │
  │ branch (main).                                              │
  │ This means your sync will go directly to production.        │
  │                                                             │
  │ If you want a separate test environment:                    │
  │ 1. Create test branch:                                      │
  │    /fractary-repo:branch-create test --base main            │
  │ 2. Update config: .fractary/plugins/codex/config.json       │
  │    Set environments.test.branch = "test"                    │
  │                                                             │
  │ Continue syncing to production? [y/N]:                      │
  └─────────────────────────────────────────────────────────────┘

  IF user responds "n" or empty THEN
    Output: "Sync cancelled."
    EXIT (do not invoke agent)
  END
END

Skip confirmation if:

• env_explicit == true (user provided explicit --env)
• Environment is test AND test branch differs from prod branch

Step 7: Validate Direction

Ensure direction is valid:

• If --to-codex: direction = "to-codex"
• If --from-codex: direction = "from-codex"
• If --bidirectional OR no direction flag: direction = "bidirectional"
• If multiple direction flags: error (conflicting options)

Step 8: Invoke Codex-Manager Agent

Use the codex-manager agent with sync-project operation:

Use the @agent-fractary-codex:codex-manager agent with the following request:
{
  "operation": "sync-project",
  "parameters": {
    "project": "<project-name>",
    "organization": "<from-config>",
    "codex_repo": "<from-config>",
    "environment": "<environment>",
    "target_branch": "<target-branch>",
    "direction": "<to-codex|from-codex|bidirectional>",
    "patterns": <from-config-or-override>,
    "exclude": <from-config>,
    "dry_run": <true|false>,
    "config": <full-config-object>
  }
}

The agent will:

1. Validate inputs
2. Check if target branch exists (error if not)
3. Invoke project-syncer skill with target branch
4. Coordinate sync operation
5. Return results

Step 9: Display Results

Show the agent's response, which includes:

• Environment and target branch
• Sync direction(s) completed
• Files synced in each direction
• Commits created
• Any errors or warnings
• Validation results

Example output:

✅ Project Sync Complete: my-project

Environment: test (branch: test)
Direction: Bidirectional

To Codex:
  Files synced: 25 (10 added, 15 modified)
  Files deleted: 2
  Commit: abc123...
  URL: https://github.com/fractary/codex.fractary.com/commit/abc123

From Codex:
  Files synced: 15 (7 added, 8 modified)
  Files deleted: 0
  Commit: def456...
  URL: https://github.com/fractary/my-project/commit/def456

Next: Review commits and verify changes

Step 10: Provide Guidance

If first-time sync:

• Suggest reviewing commits
• Explain what was synced
• Point to documentation

If errors occurred:

• Explain what failed
• Provide resolution steps
• Suggest dry-run for debugging

If target branch didn't exist:

• Display helpful error with branch creation command
• Suggest config change alternative </WORKFLOW>

<COMPLETION_CRITERIA> This command is complete when:

✅ For successful sync:

• Arguments parsed correctly
• Project name determined
• Configuration loaded
• Codex-manager agent invoked
• Agent response displayed to user
• User understands what happened

✅ For failed sync:

• Error clearly reported
• Phase of failure identified
• Resolution steps provided
• User can fix and retry

✅ For dry-run:

• Preview of changes shown
• Deletion counts displayed
• Safety recommendations provided
• User can proceed with real sync </COMPLETION_CRITERIA>

<OUTPUTS> ## Successful Sync

Display the agent's success response with:

• Direction synced
• File counts for each direction
• Commit URLs
• Validation status
• Next steps

Failed Sync

Display error from agent with:

• What failed (discovery, sync, validation)
• Which phase failed
• Error details
• How to resolve

Dry-Run Preview

Display:

🔍 DRY-RUN MODE: No changes will be applied

Would sync: my-project ↔ codex.fractary.com

To Codex:
  Would add: 10 files
  Would modify: 15 files
  Would delete: 2 files
  Deletion threshold: ✓ PASS (2 < 50)

From Codex:
  Would add: 7 files
  Would modify: 8 files
  Would delete: 0 files
  Deletion threshold: ✓ PASS (0 < 50)

Recommendation: Safe to proceed

Run without --dry-run to apply changes:
/fractary-codex:sync-project my-project

</OUTPUTS>

<ERROR_HANDLING> <INVALID_ARGUMENTS> If argument parsing fails:

1. Show which argument is invalid
2. Show correct usage format
3. Provide examples
4. Don't invoke agent </INVALID_ARGUMENTS>

<PROJECT_DETECTION_FAILED> If project auto-detection fails:

1. Explain why (not in git repo, no remote)
2. Ask user to specify project name
3. Example: /fractary-codex:sync-project my-project
4. Don't proceed without project name </PROJECT_DETECTION_FAILED>

<CONFIGURATION_MISSING> If configuration not found at .fractary/plugins/codex/config.json:

1. Explain that config is required at .fractary/plugins/codex/config.json
2. Tell user to run /fractary-codex:init
3. Explain what init does
4. Don't invoke agent without config
5. Do NOT look for or use global config at ~/.config/... </CONFIGURATION_MISSING>

<INVALID_ENVIRONMENT> If specified environment doesn't exist in config:

1. List valid environments from config
2. Show how to add custom environments
3. Example: /fractary-codex:sync-project --env test
4. Don't invoke agent with invalid environment </INVALID_ENVIRONMENT>

<TARGET_BRANCH_NOT_FOUND> If the target branch doesn't exist in codex repository: Display:

❌ TARGET BRANCH NOT FOUND

The target branch 'test' does not exist in the codex repository.

To create the test branch:
  /fractary-repo:branch-create test --base main

Or, if you don't need a separate test environment:
  Edit .fractary/plugins/codex/config.json
  Set environments.test.branch = "main"

This will make all test syncs go to the main (production) branch.

</TARGET_BRANCH_NOT_FOUND>

<USER_CANCELLED> If user declines confirmation prompt:

1. Display cancellation message
2. Suggest alternatives (e.g., --env test)
3. Don't invoke agent
4. Exit cleanly </USER_CANCELLED>

<CONFLICTING_OPTIONS> If multiple direction flags provided:

1. Explain the conflict (e.g., --to-codex AND --from-codex)
2. Show valid options
3. Ask user to choose one
4. Don't guess user intent </CONFLICTING_OPTIONS>

<AGENT_FAILURE> If codex-manager agent fails:

1. Display agent's error message
2. Show resolution steps from agent
3. Suggest dry-run if helpful
4. Don't retry automatically </AGENT_FAILURE> </ERROR_HANDLING>

<DOCUMENTATION> After sync, provide helpful guidance:

1. What happened:

   • Which direction(s) synced
   • Environment and target branch
   • File counts
   • Commit links for verification

2. How to verify:

   • Review commit diffs
   • Check that files are correct
   • Test in both repositories

3. Common issues:

   • Deletion threshold exceeded → review files
   • Merge conflicts → resolve manually
   • Authentication errors → check repo plugin config
   • Target branch not found → create branch or update config

4. Next steps:

   • Sync other projects if needed
   • Set up automation
   • Customize sync patterns

5. FABER Workflow Integration: When using codex sync within the FABER workflow:

   • Evaluate Phase: Sync to test environment

     # During FABER evaluate, sync docs to test for review
     /fractary-codex:sync-project --env test
     # or auto-detected when on feature branch
     /fractary-codex:sync-project
     

   • Release Phase: Sync to production environment

     # During FABER release, sync docs to production
     /fractary-codex:sync-project --env prod
     

   • Promotion Pattern: To promote docs from test to prod:

     1. Complete FABER evaluate phase (docs sync to test)
     2. In FABER release phase, sync to prod explicitly
     3. No separate promotion command needed - just re-run with --env prod

   • Auto-Detection in FABER:

     • Feature branches (during build/evaluate) → test environment
     • Main branch (during release) → prod environment (with confirmation)

Keep guidance relevant and actionable. </DOCUMENTATION>