Workflow Config System

Overview

The Workflow Config System provides a centralized configuration file (.omgkit/workflow.yaml) that defines Git workflow preferences, commit conventions, PR templates, code review settings, deployment configuration, and git hooks. Once configured, all OMGKIT commands automatically respect these settings.

Core Principles

Set Once, Use Everywhere

Configure workflow preferences in one file
All commands automatically read and apply settings
No need to repeat parameters on every command

Convention Over Configuration

Sensible defaults for all settings
Only override what you need to customize
Progressive disclosure of advanced options

Workflow Flexibility

Support for trunk-based, gitflow, and github-flow
Easy switching between workflows
Project-specific customization

Configuration File Location

project-root/
├── .omgkit/
│   └── workflow.yaml    # Main configuration file
├── .git/
│   └── hooks/           # Auto-generated hooks
└── src/

Complete Configuration Schema

# .omgkit/workflow.yaml
# OMGKIT Workflow Configuration
# Version: 1.0

version: "1.0"

# =============================================================================
# GIT WORKFLOW SETTINGS
# =============================================================================
git:
  # Workflow type: trunk-based | gitflow | github-flow
  workflow: trunk-based

  # Main branch name
  main_branch: main

  # Development branch (only for gitflow)
  develop_branch: develop

  # Branch naming prefixes
  branch_prefix:
    feature: "feature/"
    fix: "fix/"
    hotfix: "hotfix/"
    release: "release/"
    chore: "chore/"

  # Maximum age for feature branches (trunk-based)
  max_branch_age_days: 2

  # Auto-delete branch after merge
  delete_branch_on_merge: true

  # Require linear history (rebase before merge)
  linear_history: true

# =============================================================================
# COMMIT SETTINGS
# =============================================================================
commit:
  # Use conventional commits format
  conventional: true

  # Require scope in commit message: feat(scope): message
  require_scope: false

  # Allowed commit types
  allowed_types:
    - feat      # New feature
    - fix       # Bug fix
    - docs      # Documentation
    - style     # Formatting, no code change
    - refactor  # Code restructuring
    - perf      # Performance improvement
    - test      # Adding tests
    - chore     # Maintenance
    - ci        # CI/CD changes
    - build     # Build system changes

  # Sign commits with GPG
  sign_commits: false

  # Maximum commit message length
  max_subject_length: 72
  max_body_line_length: 100

  # Require issue reference in commit
  require_issue_reference: false
  issue_pattern: "#[0-9]+"

# =============================================================================
# PULL REQUEST SETTINGS
# =============================================================================
pr:
  # PR template: auto | path | none
  # auto = use .github/PULL_REQUEST_TEMPLATE.md if exists
  template: auto

  # Require review before merge
  require_review: true

  # Minimum number of reviewers
  min_reviewers: 1

  # Auto-assign PR creator
  auto_assign: true

  # Default reviewers (GitHub usernames)
  default_reviewers: []

  # Create as draft by default
  draft_by_default: false

  # PR title format: conventional | freeform
  title_format: conventional

  # Auto-labeling configuration
  labels:
    enabled: true
    # Labels based on file paths
    by_path:
      "src/api/**": ["backend", "api"]
      "src/ui/**": ["frontend", "ui"]
      "src/components/**": ["frontend", "components"]
      "tests/**": ["testing"]
      "docs/**": ["documentation"]
      ".github/**": ["ci-cd"]
    # Labels based on branch prefix
    by_branch:
      "feature/": ["enhancement"]
      "fix/": ["bug"]
      "hotfix/": ["bug", "critical"]
      "chore/": ["maintenance"]

  # Squash merge settings
  squash_merge: true
  merge_commit_format: "pr_title"  # pr_title | pr_body | default

# =============================================================================
# CODE REVIEW SETTINGS
# =============================================================================
review:
  # Enable auto-review with Claude
  auto_review: true

  # When to trigger auto-review
  trigger: on_pr  # on_pr | on_push | manual

  # Review checks to perform
  checks:
    - security           # OWASP, vulnerabilities
    - performance        # N+1 queries, memory leaks
    - best-practices     # Code patterns, SOLID
    - tests              # Test coverage, quality
    - accessibility      # A11y for frontend
    - documentation      # Missing docs, outdated

  # Block merge on critical issues
  block_on_critical: true

  # Review strictness: relaxed | standard | strict
  strictness: standard

  # Files to always review
  always_review:
    - "**/*.env*"
    - "**/secrets/**"
    - "**/auth/**"
    - "**/security/**"

  # Files to skip in review
  skip_review:
    - "**/*.lock"
    - "**/generated/**"
    - "**/vendor/**"
    - "**/node_modules/**"

# =============================================================================
# DEPLOYMENT SETTINGS
# =============================================================================
deploy:
  # Deployment provider: vercel | netlify | aws | railway | none
  provider: vercel

  # Branch that triggers production deploy
  production_branch: main

  # Enable preview deployments for PRs
  preview_on_pr: true

  # Auto-deploy on merge to production branch
  auto_deploy: true

  # Environment variables to check before deploy
  required_env_vars: []

  # Pre-deploy checks
  pre_deploy_checks:
    - test
    - build
    - lint

  # Post-deploy actions
  post_deploy:
    notify_slack: false
    run_smoke_tests: false

# =============================================================================
# GIT HOOKS SETTINGS
# =============================================================================
hooks:
  # Pre-commit hook
  pre_commit:
    enabled: true
    actions:
      - lint           # Run linter
      - type-check     # TypeScript/Flow check
      - format         # Auto-format code
    fail_fast: true    # Stop on first failure

  # Commit message validation
  commit_msg:
    enabled: true
    validate_conventional: true
    max_length: 72

  # Pre-push hook
  pre_push:
    enabled: true
    actions:
      - test           # Run tests
      - security-scan  # Security audit
    skip_on_ci: true   # Skip when running in CI

  # Post-merge hook
  post_merge:
    enabled: false
    actions:
      - install        # npm/yarn install
      - migrate        # Database migrations

# =============================================================================
# FEATURE FLAGS SETTINGS
# =============================================================================
feature_flags:
  # Provider: none | vercel-edge | launchdarkly | unleash | flagsmith
  provider: none

  # Default state for new flags
  default_state: false

  # Flag naming convention
  naming_convention: "kebab-case"  # kebab-case | snake_case | camelCase

  # Require flag for incomplete features
  require_for_wip: true

# =============================================================================
# TESTING AUTOMATION SETTINGS
# =============================================================================
testing:
  # Enforcement level: soft | standard | strict
  enforcement:
    level: standard

  # Auto-generate test tasks when creating features
  auto_generate_tasks: true

  # Coverage gates (minimum thresholds)
  coverage_gates:
    unit:
      minimum: 80        # Block if below
      target: 90         # Goal to achieve
      excellent: 95      # Exceptional
    integration:
      minimum: 60
      target: 75
    branch:
      minimum: 70
      target: 80
    overall:
      minimum: 75
      target: 85

  # Required test types for all features
  required_test_types:
    - unit
    - integration

  # Optional test types (generated when applicable)
  optional_test_types:
    - e2e
    - security
    - performance
    - contract

  # Blocking behavior
  blocking:
    on_test_failure: true
    on_coverage_below_minimum: true
    on_missing_test_types: true

  # Override settings
  overrides:
    allow_emergency: true
    require_approval: true
    log_all_overrides: true

# =============================================================================
# CI/CD INTEGRATION
# =============================================================================
ci:
  # CI provider: github-actions | gitlab-ci | circleci | jenkins
  provider: github-actions

  # Required status checks before merge
  required_checks:
    - build
    - test
    - lint
    - coverage  # Added coverage check

  # Allow merge with failing checks (not recommended)
  allow_failing_checks: false

Workflow Types

Trunk-Based Development

Best for: Teams practicing continuous deployment, small PRs, feature flags.

git:
  workflow: trunk-based
  main_branch: main
  max_branch_age_days: 2
  delete_branch_on_merge: true

feature_flags:
  provider: vercel-edge
  require_for_wip: true

Characteristics:

Single main branch
Short-lived feature branches (< 2 days)
Feature flags for incomplete work
Continuous deployment to production
Small, frequent commits

GitHub Flow

Best for: Teams with regular releases, code review focus.

git:
  workflow: github-flow
  main_branch: main
  max_branch_age_days: 7
  delete_branch_on_merge: true

Characteristics:

Main branch always deployable
Feature branches for all changes
PR-based code review
Deploy after merge

GitFlow

Best for: Teams with scheduled releases, multiple environments.

git:
  workflow: gitflow
  main_branch: main
  develop_branch: develop
  branch_prefix:
    feature: "feature/"
    release: "release/"
    hotfix: "hotfix/"

Characteristics:

Main and develop branches
Feature branches from develop
Release branches for staging
Hotfix branches for urgent fixes

Command Integration

How Commands Use Config

All OMGKIT git commands automatically read from .omgkit/workflow.yaml:

# /git:commit reads commit settings
git:
  commit:
    conventional: true
    allowed_types: [feat, fix, ...]

# /git:pr reads PR settings
git:
  pr:
    template: auto
    require_review: true
    labels: ...

# /dev:review reads review settings
git:
  review:
    auto_review: true
    checks: [security, performance, ...]

Config Precedence

Command-line arguments (highest priority)
.omgkit/workflow.yaml settings
Default values (lowest priority)

Initialization

Quick Start

# Initialize with interactive setup
/workflow:init

# Initialize with specific workflow
/workflow:init --workflow=trunk-based

# Initialize with all defaults
/workflow:init --defaults

Manual Setup

Create .omgkit/workflow.yaml manually:

version: "1.0"

git:
  workflow: trunk-based
  main_branch: main

commit:
  conventional: true

pr:
  require_review: true

review:
  auto_review: true

Validation

The config is validated on every command:

# Check config validity
/workflow:status

# Output:
# Workflow Config Status
# ----------------------
# File: .omgkit/workflow.yaml
# Valid: Yes
# Workflow: trunk-based
# Main Branch: main
# Hooks: pre-commit, commit-msg, pre-push
# Review: auto (security, performance, best-practices)

Best Practices

For Trunk-Based Development

Keep branches short-lived
```
git:
  max_branch_age_days: 2
```

Enable feature flags

feature_flags:
  provider: vercel-edge
  require_for_wip: true

Auto-review on PR

review:
  auto_review: true
  trigger: on_pr

Squash merges
```
pr:
  squash_merge: true
```

For Team Collaboration

Enforce conventional commits

commit:
  conventional: true
  require_scope: true

Require reviews

pr:
  require_review: true
  min_reviewers: 2

Block on critical issues
```
review:
  block_on_critical: true
```

For CI/CD

Required checks

ci:
  required_checks:
    - build
    - test
    - lint

Pre-deploy validation

deploy:
  pre_deploy_checks:
    - test
    - build

Migration Guide

From No Config

Run /workflow:init
Review generated config
Commit .omgkit/workflow.yaml
Team syncs and starts using

From .github/workflows

Keep existing workflows, add OMGKIT config for local development:

# .omgkit/workflow.yaml complements .github/workflows
ci:
  provider: github-actions
  # Existing workflows continue to work

Troubleshooting

Config Not Found

Warning: No workflow config found at .omgkit/workflow.yaml
Using default settings. Run /workflow:init to create config.

Invalid Config

Error: Invalid workflow config
- git.workflow must be one of: trunk-based, gitflow, github-flow
- commit.max_subject_length must be a number
Run /workflow:status for details.

Hook Not Running

Check hooks are enabled in config
Run /hooks:setup to regenerate hooks
Verify .git/hooks/ permissions

Related Skills

devops/git-hooks - Git hooks setup and management
devops/feature-flags - Feature flag implementation
devops/github-actions - CI/CD workflows
methodology/finishing-development-branch - Branch completion patterns