Faber Coordinator

FABER Coordinator Skill

This skill acts as the bridge between FABER workflows and FABER-DB operations, ensuring database changes are properly managed throughout the development lifecycle.

Example Request

{
  "operation": "detect-database-needs",
  "parameters": {
    "phase": "frame",
    "work_item": {
      "number": 123,
      "title": "Add user profiles table",
      "description": "Create user profiles with avatar and bio fields",
      "labels": ["feature", "database"]
    }
  }
}

High-level coordination process:

1. Detect Database Needs (Frame Phase)

1. Output start message with work item context
2. Analyze work item for database indicators
   • Title contains: "database", "table", "migration", "schema"
   • Labels contain: "database", "db", "migration"
   • Description mentions: database changes, schema updates
3. Return detection result
4. If database work detected: recommend architecture phase actions

2. Coordinate Architect Phase (Post-Architect)

1. Check if specification includes database schema
2. If schema changes detected:
   • Invoke migration-generator skill
   • Generate migration from spec
   • Validate migration file created
3. Log generation results
4. Return migration details

3. Coordinate Build Phase (Pre-Build)

1. Check if migrations exist to apply
2. If migrations pending:
   • Invoke migration-deployer for dev environment
   • Apply migrations automatically (dev auto-migrates)
   • Verify migrations applied successfully
3. Log deployment results
4. Return deployment status

4. Coordinate Evaluate Phase (Pre-Evaluate)

1. If staging environment exists:
   • Invoke migration-deployer for staging
   • Apply migrations with safety checks
2. Invoke health-checker for staging validation
   • Run connectivity and migration checks
   • Verify schema integrity
3. Log health check results
4. Return evaluation status

5. Coordinate Release Phase (Pre-Release)

1. Invoke backup-manager for production
   • Create pre-deployment backup
   • Verify backup successful
2. Invoke safety-validator
   • Analyze migrations for destructive operations
   • Check risk level
3. Invoke migration-deployer for production
   • Apply migrations with full safety checks
   • Require approval for protected environment
4. Invoke health-checker post-deployment
   • Verify production database healthy
   • Check schema drift
5. Log release results
6. Return deployment status

If coordination fails:

• Log failure details
• Provide recovery guidance
• Return failure status to FABER
• Do NOT block entire workflow for warnings
• ONLY block for critical errors

Output structured messages:

Start (Frame Phase):

🎯 STARTING: FABER Coordinator (Frame)
Work Item: #123 - Add user profiles table
Detecting database needs...
───────────────────────────────────────

Detection Result:

✅ COMPLETED: Database Needs Detection

Database Work Detected: YES
Indicators:
  • Title mentions: "table"
  • Labels include: "database", "feature"
  • Description includes schema changes

Recommendations:
  1. Generate specification including database schema
  2. Post-architect: Generate migration automatically
  3. Pre-build: Apply migration to dev environment
───────────────────────────────────────

Architect Coordination:

🎯 STARTING: FABER Coordinator (Architect)
Checking specification for database schema...
───────────────────────────────────────

✓ Database schema found in specification
✓ Invoking migration-generator...
✓ Migration generated: 20250124160000_add_user_profiles

✅ COMPLETED: Architect Phase Coordination

Migration File: prisma/migrations/20250124160000_add_user_profiles/migration.sql
Status: Ready for dev deployment
───────────────────────────────────────
Next: Build phase will apply migration to dev

Build Coordination:

🎯 STARTING: FABER Coordinator (Build)
Applying migrations to development...
───────────────────────────────────────

✓ Invoking migration-deployer (dev)...
✓ Migrations applied successfully
✓ Health check: Healthy

✅ COMPLETED: Build Phase Coordination

Environment: dev
Migrations Applied: 1 new migration
Database Status: Healthy
───────────────────────────────────────
Next: Evaluate phase will deploy to staging

Evaluate Coordination:

🎯 STARTING: FABER Coordinator (Evaluate)
Deploying to staging and validating...
───────────────────────────────────────

✓ Invoking migration-deployer (staging)...
✓ Migrations deployed to staging
✓ Running health checks...
✓ Health check: Healthy
  - Connectivity: 28ms
  - Migrations: 25 applied, 0 pending
  - Schema: No drift

✅ COMPLETED: Evaluate Phase Coordination

Environment: staging
Database Status: Healthy
Ready for Production: YES
───────────────────────────────────────
Next: Release phase will deploy to production

Release Coordination:

🎯 STARTING: FABER Coordinator (Release)
Production deployment with full safety...
───────────────────────────────────────

✓ Creating production backup...
✓ Backup created: backup-20250124-160000
✓ Analyzing migrations for safety...
✓ Risk Level: MEDIUM (DROP COLUMN detected)
✓ Deploying to production (requires approval)...
✓ User approved production deployment
✓ Migrations deployed successfully
✓ Running post-deployment health check...
✓ Health check: Healthy

✅ COMPLETED: Release Phase Coordination

Environment: production
Backup: backup-20250124-160000
Migrations Applied: 1 migration
Database Status: Healthy
───────────────────────────────────────
Production deployment successful! ✅

Return JSON:

Detection Result:

{
  "status": "success",
  "operation": "detect-database-needs",
  "result": {
    "database_work_detected": true,
    "confidence": "high",
    "indicators": [
      "Title contains 'table'",
      "Labels include 'database'",
      "Description mentions schema"
    ],
    "recommendations": [
      "Generate specification with database schema",
      "Plan migration generation in architect phase",
      "Prepare for dev deployment in build phase"
    ]
  }
}

Coordination Success:

{
  "status": "success",
  "operation": "coordinate-release",
  "phase": "release",
  "result": {
    "environment": "production",
    "backup_created": "backup-20250124-160000",
    "migrations_applied": 1,
    "health_status": "healthy",
    "deployment_successful": true
  },
  "message": "Production deployment completed successfully"
}

Coordination Failure:

{
  "status": "error",
  "operation": "coordinate-release",
  "phase": "release",
  "error": "Production health check failed",
  "result": {
    "environment": "production",
    "health_status": "unhealthy",
    "issues": [
      {
        "severity": "critical",
        "message": "Connection failed"
      }
    ]
  },
  "recovery": {
    "can_continue": false,
    "suggestions": [
      "Verify database is running",
      "Check connection string",
      "Run manual health check: /faber-db:health-check production"
    ]
  }
}

Common coordination failures:

Detection Failed:

{
  "status": "error",
  "error": "Cannot access work item details",
  "recovery": {
    "suggestions": [
      "Verify work item number is valid",
      "Check work plugin configuration"
    ]
  }
}

Migration Generation Failed:

{
  "status": "error",
  "error": "Migration generation failed",
  "phase": "architect",
  "recovery": {
    "suggestions": [
      "Review specification for database schema",
      "Generate manually: /faber-db:generate-migration",
      "Check Prisma schema syntax"
    ]
  }
}

Deployment Failed:

{
  "status": "error",
  "error": "Migration deployment failed",
  "phase": "build",
  "environment": "dev",
  "recovery": {
    "can_continue": false,
    "suggestions": [
      "Check database connectivity",
      "Review migration syntax",
      "Run manually: /faber-db:migrate dev",
      "Check error logs for details"
    ]
  }
}

Health Check Failed:

{
  "status": "warning",
  "error": "Health check degraded",
  "phase": "evaluate",
  "result": {
    "health_status": "degraded",
    "issues": [
      {
        "severity": "warning",
        "message": "Schema drift detected"
      }
    ]
  },
  "recovery": {
    "can_continue": true,
    "suggestions": [
      "Review schema drift details",
      "Consider syncing schema",
      "Proceed with caution"
    ]
  }
}

This skill coordinates with FABER-DB skills:

• migration-generator: Generate migrations from specs
• migration-deployer: Deploy migrations to environments
• backup-manager: Create pre-deployment backups
• safety-validator: Analyze migration safety
• health-checker: Validate database health

All coordination happens through skill invocation, never direct script execution.

Log coordination activities:

1. Phase being coordinated
2. Operations performed
3. Skills invoked
4. Results and status
5. Recommendations for next phase
6. Use fractary-logs plugin for audit trail

FABER Workflow Integration

The faber-coordinator skill is invoked from FABER phase hooks:

Frame Phase (Post-Frame)

Hook: post_frame Operation: detect-database-needs Purpose: Detect if work item requires database changes

{
  "hooks": {
    "post_frame": [
      {
        "skill": "fractary-faber-db:faber-coordinator",
        "operation": "detect-database-needs",
        "parameters": {
          "work_item": "${work_item}"
        }
      }
    ]
  }
}

Architect Phase (Post-Architect)

Hook: post_architect Operation: coordinate-architect Purpose: Generate migrations from specification

{
  "hooks": {
    "post_architect": [
      {
        "skill": "fractary-faber-db:faber-coordinator",
        "operation": "coordinate-architect",
        "parameters": {
          "spec_file": "${spec_file}"
        }
      }
    ]
  }
}

Build Phase (Pre-Build)

Hook: pre_build Operation: coordinate-build Purpose: Apply migrations to development

{
  "hooks": {
    "pre_build": [
      {
        "skill": "fractary-faber-db:faber-coordinator",
        "operation": "coordinate-build",
        "parameters": {
          "environment": "dev"
        }
      }
    ]
  }
}

Evaluate Phase (Pre-Evaluate)

Hook: pre_evaluate Operation: coordinate-evaluate Purpose: Deploy to staging and validate

{
  "hooks": {
    "pre_evaluate": [
      {
        "skill": "fractary-faber-db:faber-coordinator",
        "operation": "coordinate-evaluate",
        "parameters": {
          "environment": "staging"
        }
      }
    ]
  }
}

Release Phase (Pre-Release)

Hook: pre_release Operation: coordinate-release Purpose: Production deployment with full safety

{
  "hooks": {
    "pre_release": [
      {
        "skill": "fractary-faber-db:faber-coordinator",
        "operation": "coordinate-release",
        "parameters": {
          "environment": "production"
        }
      }
    ]
  }
}

Complete FABER Integration Example

See config/workflows/faber-db-integrated.json for a complete example workflow with FABER-DB integration.

Database Detection Patterns

Title Patterns:

• Contains: "database", "db", "table", "schema", "migration", "model", "entity"
• Contains: "add {model}", "create {model}", "remove {model}"
• Contains: "column", "field", "index", "constraint"

Label Patterns:

• "database", "db", "schema", "migration"
• "prisma", "typeorm", "sequelize"

Description Patterns:

• Mentions schema changes
• Describes table structure
• References database migrations
• Includes SQL snippets

Autonomy Levels

Dry-Run:

• Detect and report, no actual operations
• Useful for planning and testing

Assist:

• Automatic detection and dev deployment
• Manual approval for staging/production

Guarded (Recommended):

• Automatic through evaluate phase
• Approval required for release phase

Autonomous:

• Fully automatic (use with extreme caution)
• Only for non-production workflows

Configuration

FABER-DB coordination settings in .fractary/plugins/faber-db/config.json:

{
  "faber_integration": {
    "enabled": true,
    "auto_detect_database_work": true,
    "auto_generate_migrations": true,
    "auto_deploy_dev": true,
    "environments": {
      "dev": {
        "auto_migrate": true,
        "health_check_after": true
      },
      "staging": {
        "auto_migrate": false,
        "require_approval": true,
        "health_check_before": true,
        "health_check_after": true
      },
      "production": {
        "auto_migrate": false,
        "require_approval": true,
        "require_backup": true,
        "validate_safety": true,
        "health_check_before": true,
        "health_check_after": true
      }
    }
  }
}

Notes

• Context Awareness: Coordinator has full FABER workflow context
• Non-Blocking: Only critical errors block workflow
• Progressive Safety: Increasing safety checks through phases
• Audit Trail: All coordination logged for compliance
• Rollback Ready: Backups created before production changes