Configuration Management

CRITICAL: All configuration files are loaded from the project working directory, NOT the plugin installation directory.

Common Mistake: Do NOT look in ~/.claude/plugins/marketplaces/fractary/plugins/repo/ - that's the plugin installation directory.

load-config

Purpose: Load repo configuration from .fractary/plugins/repo/config.json (in project working directory) or .faber.config.toml Script: scripts/config-loader.sh Parameters: None (auto-detects config file)

Output Format:

{
  "handlers": {
    "source_control": {
      "active": "github",
      "github": {...},
      "gitlab": {...},
      "bitbucket": {...}
    }
  },
  "defaults": {
    "default_branch": "main",
    "protected_branches": ["main", "master", "production"],
    "branch_naming": "feat/{issue_id}-{slug}",
    "commit_format": "conventional",
    "require_signed_commits": false,
    "merge_strategy": "no-ff",
    "push_sync_strategy": "auto-merge"
  }
}

Special return value: If config file doesn't exist, returns defaults with a flag:

{
  "config_exists": false,
  "using_defaults": true,
  "handlers": { ... },
  "defaults": { ... }
}

check-config-exists

Purpose: Check if plugin configuration exists and return recommendation if not Script: scripts/check-config-exists.sh Parameters: None

Output Format:

{
  "config_exists": true,
  "config_path": ".fractary/plugins/repo/config.json"
}

Output Format (if not exists):

{
  "config_exists": false,
  "recommendation": "💡 Tip: Run /repo:init to create a configuration file for this repository. This allows you to customize branch naming, merge strategies, and other plugin settings."
}

Validation

validate-branch-name

Purpose: Validate branch name against semantic conventions Script: scripts/branch-validator.sh Parameters:

• branch_name - Branch name to validate
• pattern - Expected pattern (from config, e.g., "{prefix}/{issue_id}-{slug}")

Validation Rules:

• Matches configured pattern
• No special characters except / - _
• Not a protected branch (for creation)
• Prefix is valid (feat|fix|chore|hotfix|docs|test|refactor|style|perf)

Output Format:

{
  "valid": true,
  "branch_name": "feat/123-add-export",
  "components": {
    "prefix": "feat",
    "issue_id": "123",
    "slug": "add-export"
  }
}

Error Format (if invalid):

{
  "valid": false,
  "error": "Invalid branch prefix. Must be one of: feat, fix, chore, hotfix, docs, test, refactor, style, perf",
  "branch_name": "invalid/123-add-export"
}

validate-commit-message

Purpose: Validate commit message against Conventional Commits + FABER metadata Script: scripts/commit-validator.sh Parameters:

• message - Commit message to validate
• format - Expected format (conventional|faber)

Validation Rules:

• Follows Conventional Commits format: type(scope): subject
• Type is valid (feat|fix|chore|docs|test|refactor|style|perf|build|ci)
• Subject is capitalized and under 72 characters
• If FABER format: includes work item reference and author context

Output Format:

{
  "valid": true,
  "message": "feat: Add user export functionality",
  "components": {
    "type": "feat",
    "scope": null,
    "subject": "Add user export functionality"
  }
}

Formatting

format-pr-body

Purpose: Generate standardized PR body with FABER metadata Script: scripts/pr-formatter.sh Parameters:

• title - PR title
• description - PR description
• work_id - Work item ID (e.g., "123" for "#123")
• author_context - FABER context (architect|implementor|tester|reviewer)
• session_id - Optional FABER session ID

Output Format (markdown string):

## Summary
{description}

## Related Work
Closes #{work_id}

## Context
- FABER Session: {session_id}
- Author Context: {author_context}
- Generated: {timestamp}

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

extract-work-metadata

Purpose: Extract metadata from work item for branch/commit naming Script: scripts/metadata-extractor.sh Parameters:

• work_id - Work item ID (e.g., "123", "PROJ-456")
• title - Work item title
• type - Work item type (feature|bug|chore|hotfix)

Output Format:

{
  "work_id": "123",
  "type": "feature",
  "prefix": "feat",
  "slug": "add-user-export",
  "branch_name_suggestion": "feat/123-add-user-export"
}

Slug Generation Rules:

• Lowercase
• Replace spaces with hyphens
• Remove special characters
• Max 50 characters
• No leading/trailing hyphens