Work Common

Work Common Utilities

This library provides:

• Configuration loading and validation
• Data normalization across platforms (future)
• Input validation helpers (future)
• Standard error code definitions (future)

config-loader.sh

Purpose: Load and validate work plugin configuration

Location: plugins/work/skills/work-common/scripts/config-loader.sh

Usage:

CONFIG_JSON=$(./plugins/work/skills/work-common/scripts/config-loader.sh) || exit $?
PLATFORM=$(echo "$CONFIG_JSON" | jq -r '.handlers["work-tracker"].active')

Returns: Full configuration JSON to stdout

Exit Codes:

• 0: Success - configuration loaded and valid
• 3: Validation error - config not found or invalid JSON

CRITICAL: Configuration must be loaded from the project working directory, NOT the plugin installation directory.

Configuration Location: .fractary/plugins/work/config.json (relative to project root / current working directory)

Common Mistake: Do NOT look in ~/.claude/plugins/marketplaces/fractary/plugins/work/ - that's the plugin installation directory, not the project config location.

Special Behavior: When config doesn't exist, the work plugin uses auto-detection (e.g., gh CLI automatically detects the repository). Skills can check if config exists and recommend running /work:init to persist settings.

Example:

# Load configuration
if ! CONFIG_JSON=$(./plugins/work/skills/work-common/scripts/config-loader.sh 2>&1); then
    echo "Error: Failed to load configuration" >&2
    exit 3
fi

# Extract platform-specific settings
PLATFORM=$(echo "$CONFIG_JSON" | jq -r '.handlers["work-tracker"].active')
GITHUB_OWNER=$(echo "$CONFIG_JSON" | jq -r '.handlers["work-tracker"].github.owner')
GITHUB_REPO=$(echo "$CONFIG_JSON" | jq -r '.handlers["work-tracker"].github.repo')

check-config-exists.sh

Purpose: Check if work plugin configuration file exists

Location: plugins/work/skills/work-common/scripts/check-config-exists.sh

Usage:

if [ -f ".fractary/plugins/work/config.json" ]; then
    # Config exists
else
    # Show recommendation to run /work:init
fi

Returns: Exit code 0 if config exists, 1 if not

Use Case: Skills can check config existence and include init recommendation in completion messages when config doesn't exist.

normalize-issue.sh (FUTURE)

Purpose: Normalize platform-specific issue JSON to universal format

Status: Not yet implemented - placeholder for Phase 5+

Planned Usage:

NORMALIZED=$(./plugins/work/skills/work-common/scripts/normalize-issue.sh "$PLATFORM" "$ISSUE_JSON")

validate-issue-id.sh (FUTURE)

Purpose: Validate issue ID format for specific platform

Status: Not yet implemented - placeholder for Phase 5+

Planned Usage:

./plugins/work/skills/work-common/scripts/validate-issue-id.sh "github" "123"

error-codes.sh (FUTURE)

Purpose: Centralized error code definitions and lookup

Status: Not yet implemented - placeholder for Phase 5+

Planned Usage:

source ./plugins/work/skills/work-common/scripts/error-codes.sh
exit $ERR_NOT_FOUND

Standard error codes used across all work plugin utilities:

• 0 - Success
• 1 - General error
• 2 - Invalid arguments
• 3 - Validation error (config, input format)
• 10 - Resource not found (issue, milestone, etc.)
• 11 - Authentication error
• 12 - Network error

Dependencies

• jq - JSON processing
• bash 4.0+ - Shell features
• Platform-specific CLIs:
  • gh for GitHub
  • jira for Jira
  • linear for Linear

Configuration Structure

CRITICAL: Configuration must be loaded from the project working directory, NOT the plugin installation directory.

Expected configuration file at .fractary/plugins/work/config.json (relative to project root / current working directory):

{
  "version": "2.0",
  "project": {
    "issue_system": "github",
    "repository": "owner/repo"
  },
  "handlers": {
    "work-tracker": {
      "active": "github",
      "github": {
        "owner": "myorg",
        "repo": "my-project",
        "api_url": "https://api.github.com"
      }
    }
  }
}

See plugins/work/config/config.example.json for complete configuration template.

Testing

Test config-loader.sh

# Test successful load
cd /mnt/c/GitHub/fractary/claude-plugins
./plugins/work/skills/work-common/scripts/config-loader.sh
# Expected: Outputs valid JSON configuration

# Test missing config
mv .fractary/plugins/work/config.json .fractary/plugins/work/config.json.bak
./plugins/work/skills/work-common/scripts/config-loader.sh
# Expected: Exit code 3, error message "Configuration file not found"

# Test invalid JSON
echo "{ invalid json" > .fractary/plugins/work/config.json
./plugins/work/skills/work-common/scripts/config-loader.sh
# Expected: Exit code 3, error message "Invalid JSON"

Integration

Other skills and handlers integrate work-common utilities like this:

#!/bin/bash
# Example handler script

set -euo pipefail

# Load configuration using work-common utility
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORK_COMMON_DIR="$SCRIPT_DIR/../../work-common/scripts"

CONFIG_JSON=$("$WORK_COMMON_DIR/config-loader.sh") || exit $?

# Extract configuration values
PLATFORM=$(echo "$CONFIG_JSON" | jq -r '.handlers["work-tracker"].active')

# Continue with operation...

Future Enhancements

• normalize-issue.sh - Standardize issue data across GitHub, Jira, Linear
• validate-issue-id.sh - Platform-specific ID format validation
• error-codes.sh - Shared error code constants
• cache-helper.sh - Optional caching for repeated API calls
• auth-checker.sh - Verify platform authentication before operations