<CONTEXT>
Syncs project documentation with the codex repository using auto-detected environment from current branch.
/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 a single project with the codex repository. You handle:
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
IMPORTANT: ENVIRONMENT AUTO-DETECTION
--env explicitly provided: use that environment, skip confirmation--env provided: auto-detect from current git branch
test environment (no confirmation)prod environment (REQUIRES confirmation)IMPORTANT: CONFIRMATION PROMPTS
--env is explicitly provided (user was deliberate)IMPORTANT: USER-FRIENDLY DEFAULTS
IMPORTANT: NEVER DO WORK
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:
test environmentprod environment (with confirmation prompt)--env flag overrides auto-detection and skips confirmationExamples:
# 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:
--env <environment> (optional, triggers auto-detect if not provided)--to-codex, --from-codex, --bidirectional (default)--dry-run flag--patterns <list> (optional override)Track whether --env was explicitly provided (affects confirmation logic).
If project name NOT provided:
https://github.com/fractary/my-project.git → "my-project"git@github.com:fractary/my-project.git → "my-project"If project name provided:
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:
If --env explicitly provided:
env_explicit = true (skip confirmation later)If --env NOT provided (auto-detect):
main or master → environment = prodfeat/, fix/, chore/, docs/, refactor/, test/, perf/, style/, ci/, build/ → environment = testtest (safe default)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)
Look up the target branch for the determined environment from config:
target_branch = config.environments[environment].branch
Example mappings (from config):
test → test branchprod → main branchCheck if test==prod (same branch):
test_equals_prod = (config.environments.test.branch == config.environments.prod.branch)
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)Ensure direction is valid:
--to-codex: direction = "to-codex"--from-codex: direction = "from-codex"--bidirectional OR no direction flag: direction = "bidirectional"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:
Show the agent's response, which includes:
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
If first-time sync:
If errors occurred:
If target branch didn't exist:
<COMPLETION_CRITERIA> This command is complete when:
✅ For successful sync:
✅ For failed sync:
✅ For dry-run:
Display the agent's success response with:
Display error from agent with:
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:
<PROJECT_DETECTION_FAILED> If project auto-detection fails:
<CONFIGURATION_MISSING>
If configuration not found at .fractary/plugins/codex/config.json:
.fractary/plugins/codex/config.json~/.config/...
</CONFIGURATION_MISSING><INVALID_ENVIRONMENT> If specified environment doesn't exist in config:
<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:
<CONFLICTING_OPTIONS> If multiple direction flags provided:
<AGENT_FAILURE> If codex-manager agent fails:
What happened:
How to verify:
Common issues:
Next steps:
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:
--env prodAuto-Detection in FABER:
Keep guidance relevant and actionable. </DOCUMENTATION>