Repo Config Wizard

Config Wizard Skill

Your responsibility is to guide users through the initial setup and configuration of the repo plugin. You detect their environment, validate credentials, and create appropriate configuration files.

This is an interactive wizard that:

• Detects git repository and remote platform (GitHub, GitLab, Bitbucket)
• Validates authentication (SSH, HTTPS, tokens)
• Creates configuration files (project-specific or global)
• Tests connectivity and provides setup summary

You provide a friendly, interactive experience that makes setup straightforward for both beginners and advanced users.

1. Security First

   • NEVER log or display tokens in plain text (mask with ***)
   • NEVER overwrite config without confirmation (unless --force flag)
   • ALWAYS validate tokens before saving them
   • ALWAYS set appropriate file permissions on config files

2. User Control

   • ALWAYS show what will be changed before making changes
   • ALWAYS require confirmation for destructive actions
   • ALWAYS provide clear next steps after completion
   • NEVER make assumptions without user confirmation

3. Environment Detection

   • ALWAYS attempt auto-detection before prompting
   • ALWAYS validate detected values before using them
   • ALWAYS provide option to override auto-detected values
   • NEVER assume platform if detection is ambiguous

4. Error Handling

   • ALWAYS provide clear error messages with solutions
   • ALWAYS create backups before modifying existing configs
   • ALWAYS validate connectivity before confirming success
   • NEVER leave partially configured state

5. Graceful Degradation

   • ALWAYS continue setup even if optional features fail
   • ALWAYS warn about missing CLI tools but don't block
   • ALWAYS provide manual setup instructions as fallback
   • NEVER fail silently

6. Script-Based Execution

   • ALWAYS use scripts in scripts/ directory for deterministic operations
   • NEVER include bash code inline (use scripts instead)
   • ALWAYS pass script output to user in readable format
   • NEVER expose internal script implementation details

Request Format:

{
  "operation": "initialize-configuration",
  "parameters": {
    "platform": "github|gitlab|bitbucket",  // optional, auto-detect if omitted
    "scope": "project|global",              // optional, will prompt if omitted
    "token": "masked-token-value",          // optional, will prompt if omitted
    "interactive": true|false,              // default: true
    "force": true|false,                    // default: false
    "options": {
      "default_branch": "main",             // optional
      "protected_branches": ["main", "master"],  // optional
      "merge_strategy": "no-ff",            // optional
      "push_sync_strategy": "auto-merge"    // optional
    }
  }
}

Flags:

• interactive: true - Full wizard with prompts and confirmations
• interactive: false - Non-interactive mode, use provided/detected values with --yes
• force: true - Overwrite existing configuration without prompting

1. DISPLAY START MESSAGE:

🎯 STARTING: Config Wizard
Mode: {interactive|non-interactive}
Force: {true|false}
───────────────────────────────────────

2. DETECT ENVIRONMENT:

Execute detection script:

DETECTION=$(bash plugins/repo/skills/config-wizard/scripts/detect-environment.sh)

The script returns JSON with:

• in_git_repo: boolean
• remote_url: string
• platform: github|gitlab|bitbucket|unknown
• auth_method: SSH|HTTPS|unknown

Display detection results:

Detecting environment...
✓ Git repository detected
✓ Remote: {remote_url}
✓ Platform: {platform}
✓ Auth method: {auth_method}

If not in git repository (exit code 3):

✗ Not in a git repository

Initialize a git repository first:
  git init
  git remote add origin <url>

Or navigate to an existing repository.

RETURN: {"status": "failure", "error_code": 3, "error": "Not in git repository"}

3. CHECK EXISTING CONFIGURATION:

Execute check script:

EXISTING=$(bash plugins/repo/skills/config-wizard/scripts/check-existing-config.sh)

The script returns JSON with:

• project_config_exists: boolean
• project_config_path: string
• global_config_exists: boolean
• global_config_path: string

If config exists and not --force:

⚠ Configuration already exists at:
  {config_path}

**Note:** A backup will be created before making changes.

Options:
  1. Update existing config (merge changes, backup created)
  2. Overwrite with new config (backup created)
  3. Cancel and keep existing

Choice [1-3]:

4. PLATFORM SELECTION:

If platform not detected (platform == "unknown") or user wants to override:

Select source control platform:
  1. GitHub (github.com or Enterprise)
  2. GitLab (gitlab.com or self-hosted)
  3. Bitbucket (bitbucket.org or Server)

Choice [1-3]:

Validate selection and set PLATFORM variable.

5. AUTHENTICATION SETUP:

For SSH method: Display authentication requirements:

Current setup:
  Remote URL: {remote_url}
  Method: SSH (git push/pull use SSH keys)

You still need a Personal Access Token for API operations:
  • Creating pull requests
  • Managing issues
  • Commenting on PRs
  • Review operations

Environment variable check:
  • GitHub: GITHUB_TOKEN
  • GitLab: GITLAB_TOKEN
  • Bitbucket: BITBUCKET_TOKEN and BITBUCKET_USERNAME

For HTTPS method:

Current setup:
  Remote URL: {remote_url}
  Method: HTTPS (requires token for all operations)

Personal Access Token is required for:
  • Git operations (push, pull, fetch)
  • API operations (PRs, issues, comments)

Environment variable check:
  • GitHub: GITHUB_TOKEN
  • GitLab: GITLAB_TOKEN
  • Bitbucket: BITBUCKET_TOKEN and BITBUCKET_USERNAME

Check for token in environment variables and display found/not found status.

6. VALIDATE TOKEN:

Execute platform-specific validation script:

GitHub:

VALIDATION=$(bash plugins/repo/skills/config-wizard/scripts/validate-token-github.sh)

GitLab:

VALIDATION=$(bash plugins/repo/skills/config-wizard/scripts/validate-token-gitlab.sh)

Bitbucket:

VALIDATION=$(bash plugins/repo/skills/config-wizard/scripts/validate-token-bitbucket.sh)

Scripts return JSON with:

• valid: boolean
• user: string
• scopes: string (GitHub only)
• cli_available: boolean

Display validation results:

Validating token...
✓ Token is valid
✓ User: {user}
✓ Scopes: {scopes}  (if applicable)
✓ CLI available: {yes|no}

If validation fails (exit code 11):

✗ Token validation failed

Possible issues:
  1. Token is invalid or expired
  2. Token doesn't have required scopes
  3. Network connectivity issues

Generate a new token:
  • GitHub: https://github.com/settings/tokens (scopes: repo, workflow, read:org)
  • GitLab: https://gitlab.com/-/profile/personal_access_tokens (scopes: api, write_repository)
  • Bitbucket: https://bitbucket.org/account/settings/app-passwords/

RETURN: {"status": "failure", "error_code": 11, "error": "Token validation failed"}

7. ENVIRONMENT VARIABLE PERSISTENCE:

If token found in environment, verify persistence:

⚠ Token Environment Variable Detected

The {PLATFORM}_TOKEN environment variable is currently set.
To ensure this persists across sessions, add it to your shell profile:

  • bash: echo 'export {PLATFORM}_TOKEN="your_token"' >> ~/.bashrc
  • zsh: echo 'export {PLATFORM}_TOKEN="your_token"' >> ~/.zshrc
  • fish: echo 'set -Ux {PLATFORM}_TOKEN "your_token"' | fish

Or use a secure credential manager:
  • macOS: Use keychain or 'gh auth login'
  • Linux: Use gnome-keyring or 'gh auth login'
  • Windows: Use Windows Credential Manager

Continue with setup? (y/n):

8. CONFIGURATION SCOPE:

If not specified in parameters, prompt:

Where should the configuration be stored?

  1. Project-specific (.fractary/plugins/repo/config.json)
     - Only for this repository
     - Can be committed to version control (see .gitignore guidance below)
     - Overrides user-global config

  2. User-global (~/.fractary/repo/config.json)
     - Used for all repositories
     - Not committed to version control
     - Convenient for personal projects

Choice [1-2]:

9. .GITIGNORE GUIDANCE:

If scope is "project", provide .gitignore guidance:

📋 .gitignore Guidance for Project-Specific Config

The .fractary/ directory will be created in your project root.

Recommended .gitignore patterns:

  Option 1: Ignore all config (recommended for public repos)
    .fractary/

  Option 2: Ignore only sensitive data
    .fractary/plugins/repo/config.json
    .fractary/**/*.backup

  Option 3: Commit config template (team projects)
    # Add to .gitignore:
    .fractary/**/*.backup
    # But commit config.example.json with token placeholder

Current .gitignore status: {exists|missing}

Add .fractary/ to .gitignore? (y/n):

If user says yes, append to .gitignore:

echo ".fractary/" >> .gitignore

10. ADDITIONAL OPTIONS:

In interactive mode, prompt for configuration options:

Additional configuration:

  Default branch [{main}]:
  Protected branches [{main,master,production}]:
  Merge strategy (no-ff/squash/ff-only) [{no-ff}]:
  Push sync strategy (auto-merge/pull-rebase/pull-merge/manual/fail) [{auto-merge}]:

Use defaults? (y/n):

If user says no, prompt for each option individually.

Push Sync Strategy explanation:

Push Sync Strategy Options:
  • auto-merge: Automatically pull and merge when branch is out of sync (recommended for solo)
  • pull-rebase: Automatically pull and rebase local commits
  • pull-merge: Pull with explicit merge commit
  • manual: Prompt for action when out of sync
  • fail: Abort push if out of sync (safest for teams)

11. CREATE CONFIGURATION FILE:

Execute creation script:

CREATE_RESULT=$(bash plugins/repo/skills/config-wizard/scripts/create-config.sh \
  --platform "$PLATFORM" \
  --scope "$SCOPE" \
  --default-branch "$DEFAULT_BRANCH" \
  --protected-branches "$PROTECTED_BRANCHES" \
  --merge-strategy "$MERGE_STRATEGY" \
  --push-sync-strategy "$PUSH_SYNC_STRATEGY" \
  $([ "$FORCE" = true ] && echo "--force"))

The script:

• Creates directory structure
• Backs up existing config (unless --force)
• Writes configuration JSON
• Sets permissions to 600
• Returns JSON with status and paths

Display creation results:

Creating configuration...
✓ Configuration file created: {config_path}
✓ Backup created: {backup_path} (if applicable)
✓ Permissions set: 600 (owner read/write only)

12. VALIDATE SETUP:

Execute connectivity test script:

CONNECTIVITY=$(bash plugins/repo/skills/config-wizard/scripts/test-connectivity.sh \
  --platform "$PLATFORM" \
  --auth-method "$AUTH_METHOD")

The script returns JSON with:

• ssh_connected: boolean
• api_connected: boolean
• cli_available: boolean

Display validation results:

Testing connectivity...
✓ SSH connection: {verified|not tested}
✓ API connection: {verified|failed}
✓ CLI available: {gh|glab|none}

Warnings for missing/failed items:

⚠ SSH connection failed
  Setup SSH keys: ssh-keygen -t ed25519
  Add to platform: https://github.com/settings/keys

⚠ {Platform} CLI not installed
  The plugin can work without CLI but some features are limited.
  Install: brew install gh (macOS) or see docs

13. DISPLAY SUMMARY:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Configuration Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Platform: {platform}
Auth: {auth_method} + Token
Config: {config_path}
Scope: {project|global}

✓ Configuration file created
✓ {Platform} token validated
✓ SSH connection {verified|not tested}
✓ {Platform} CLI {available|not available}

Setup complete! Try these commands:

  /repo:branch create 123 "new feature"
  /repo:commit "Add feature" --type feat
  /repo:push --set-upstream
  /repo:pr create "feat: New feature"

Documentation: plugins/repo/docs/

14. DISPLAY COMPLETION MESSAGE:

✅ COMPLETED: Config Wizard
───────────────────────────────────────
Configuration file: {config_path}
Platform: {platform}
Auth method: {auth_method}
Backup created: {yes|no}

Environment variables required:
  • {PLATFORM}_TOKEN must be set in your shell
  • Add to ~/.bashrc, ~/.zshrc, or use CLI login

Next steps:
  1. Verify token persists: echo $GITHUB_TOKEN
  2. Test repo commands: /repo:branch create test-123 "test"
  3. Review configuration: cat {config_path}
  4. See documentation: plugins/repo/docs/

Troubleshooting:
  • Restore backup: mv {config_path}.backup {config_path}
  • Reconfigure: /repo:init --force
  • Manual setup: plugins/repo/docs/setup/
───────────────────────────────────────

The configuration is complete when:

1. Config File Created:

   • Configuration file exists at chosen location
   • Valid JSON structure
   • Appropriate file permissions (600)
   • Backup created if updating existing config

2. Authentication Validated:

   • Token validated with platform API
   • Environment variable persistence verified
   • SSH connectivity tested (if SSH method)

3. User Informed:

   • Setup summary displayed
   • Environment variable persistence guidance provided
   • .gitignore guidance provided (for project scope)
   • Next steps provided
   • Documentation references given

4. No Errors:

   • All validation checks passed
   • No connectivity issues (or warnings shown)
   • Configuration loadable by plugin

Success Response:

{
  "status": "success",
  "operation": "initialize-configuration",
  "result": {
    "config_file": "~/.fractary/repo/config.json",
    "platform": "github",
    "auth_method": "SSH + Token",
    "scope": "global",
    "backup_created": true
  }
}

Failure Response:

{
  "status": "failure",
  "operation": "initialize-configuration",
  "error": "Token validation failed",
  "error_code": 11
}

Error Codes:

• 0: Success
• 1: General error
• 2: Invalid arguments
• 3: Not in git repository
• 10: Configuration already exists (without --force)
• 11: Token validation failed
• 12: Network/connectivity error

Not in Git Repository:

✗ Error: Not in a git repository

Initialize a git repository first:
  git init
  git remote add origin <url>

Or navigate to an existing repository.

RETURN: {"status": "failure", "error_code": 3, "error": "Not in git repository"}

Token Validation Failed:

✗ Error: {Platform} token validation failed

Possible issues:
  1. Token is invalid or expired
  2. Token doesn't have required scopes (repo, workflow)
  3. Network connectivity issues
  4. Environment variable not set

Generate a new token:
  • GitHub: https://github.com/settings/tokens (scopes: repo, workflow, read:org)
  • GitLab: https://gitlab.com/-/profile/personal_access_tokens
  • Bitbucket: https://bitbucket.org/account/settings/app-passwords/

RETURN: {"status": "failure", "error_code": 11, "error": "Token validation failed"}

SSH Not Configured:

⚠ Warning: SSH authentication not configured

Git operations may fail. Setup SSH:
  1. Generate key: ssh-keygen -t ed25519
  2. Add to {Platform}: {platform_ssh_url}
  3. Test: ssh -T git@{platform}.com

Or switch to HTTPS:
  git remote set-url origin https://{platform}.com/owner/repo.git

Continuing with setup...

Configuration Already Exists:

⚠ Configuration already exists at: {config_path}

A backup will be created automatically before any changes.

Options:
  1. Update existing config (merge changes)
  2. Overwrite with new config
  3. Cancel and keep existing

Choice [1-3]:

(If --force flag: automatically overwrite without prompting, backup still created)

Network Error:

✗ Error: Unable to validate token

Network connectivity issues detected.

Troubleshooting:
  1. Check internet connection: ping {platform}.com
  2. Verify firewall settings
  3. Test platform access: curl -I https://{platform}.com
  4. Try again later

RETURN: {"status": "failure", "error_code": 12, "error": "Network connectivity error"}

CLI Tools Missing:

⚠ Warning: {Platform} CLI ({cli_name}) not installed

The plugin can still work using git commands and API calls,
but some features will be limited.

Install {Platform} CLI:
  • macOS: brew install {cli_name}
  • Linux: See {install_url}
  • Windows: winget install {package_name}

Continuing with setup...

Available Scripts:

All scripts are in plugins/repo/skills/config-wizard/scripts/:

1. detect-environment.sh

   • Detects git repository, remote URL, platform, auth method
   • Output: JSON with detection results
   • Exit codes: 0 (success), 3 (not in git repo)

2. check-existing-config.sh

   • Checks for existing project and global configuration files
   • Output: JSON with paths and existence booleans
   • Exit codes: 0 (success)

3. validate-token-github.sh

   • Validates GitHub authentication using gh CLI or API
   • Requires: GITHUB_TOKEN environment variable
   • Output: JSON with validation results, user, scopes
   • Exit codes: 0 (valid), 11 (invalid)

4. validate-token-gitlab.sh

   • Validates GitLab authentication using glab CLI or API
   • Requires: GITLAB_TOKEN environment variable
   • Output: JSON with validation results, user
   • Exit codes: 0 (valid), 11 (invalid)

5. validate-token-bitbucket.sh

   • Validates Bitbucket authentication using API
   • Requires: BITBUCKET_TOKEN and BITBUCKET_USERNAME
   • Output: JSON with validation results, user
   • Exit codes: 0 (valid), 11 (invalid)

6. create-config.sh

   • Creates configuration file with proper structure and permissions
   • Arguments: --platform, --scope, --default-branch, --protected-branches, --merge-strategy, --push-sync-strategy, --force
   • Output: JSON with config path, backup status
   • Exit codes: 0 (success), 2 (invalid args), 3 (config error)

7. test-connectivity.sh

   • Tests SSH and API connectivity for platform
   • Arguments: --platform, --auth-method
   • Output: JSON with SSH/API/CLI status
   • Exit codes: 0 (success), 12 (network error)

Script Usage Pattern:

• All scripts output JSON for easy parsing
• All scripts use consistent exit codes
• All scripts are idempotent (can be run multiple times)
• All scripts handle missing environment variables gracefully

Called By:

• /repo:init command
• repo-manager agent (initialize-configuration operation)

Calls:

• Bash tool - To execute scripts in scripts/ directory
• Read tool - For checking .gitignore (optional)
• Write tool - For updating .gitignore (optional)

Creates:

• .fractary/plugins/repo/config.json (project scope)
• ~/.fractary/repo/config.json (global scope)
• *.backup files (when updating existing config)
• .gitignore entry (if user confirms)

Validates:

• Git repository presence
• Remote URL and platform
• Token validity and scopes
• SSH connectivity
• CLI tool availability
• Environment variable persistence

GitHub:

• CLI: gh
• Token scopes: repo, workflow, read:org
• SSH test: ssh -T git@github.com
• API test: gh auth status
• Token URL: https://github.com/settings/tokens

GitLab:

• CLI: glab
• Token scopes: api, write_repository, read_repository
• SSH test: ssh -T git@gitlab.com
• API test: glab auth status
• Token URL: https://gitlab.com/-/profile/personal_access_tokens

Bitbucket:

• CLI: None (uses curl)
• Requires: username + app password + workspace slug
• SSH test: ssh -T git@bitbucket.org
• API test: curl -u username:password https://api.bitbucket.org/2.0/user
• Token URL: https://bitbucket.org/account/settings/app-passwords/

Summary

This skill provides an interactive, user-friendly setup wizard that:

• Auto-detects environment (git repo, platform, auth method)
• Validates credentials before saving
• Guides users through configuration options
• Provides environment variable persistence guidance
• Offers .gitignore recommendations for project configs
• Tests connectivity and CLI availability
• Creates properly secured configuration files
• Provides clear next steps and documentation
• Uses separate script files for all deterministic operations (55-60% context reduction)

The wizard handles both interactive and non-interactive modes, supports all three platforms (GitHub, GitLab, Bitbucket), and provides helpful error messages with solutions when issues occur.

All bash operations are delegated to scripts in the scripts/ directory, following the 3-layer architecture pattern for maximum context efficiency.