Preface

AI coding agents (such as Claude Code, DeepSeek Harness, and Cursor) can sometimes bypass an established team GitFlow workflow during automated development, directly merging code into integration or production branches and causing version control chaos. AgentsGitFlowController aims to provide a configurable branch-role guard mechanism for these AI agents, enforcing compliance with the standard workflow.

Plugin Overview

Name: AgentsGitFlowController (agents-gitflow-guard)
Core positioning: Agents Client Level Git Flow Controller
Maintainer: FeatureAgents
Category: Workflow
License: MIT

Core Features

This plugin provides the following capabilities:

  1. Branch Role Guard: Defines different branch roles for AI coding agents, including integration, preview, production, and archive.
  2. Multi-Client Support: Supports Claude Code, DeepSeek Harness (DSH), Cursor, Codex, OpenCode, Antigravity, Pi, CodeBuddy, and ZCode.
  3. Workflow Enforcement: Prevents agents from skipping the GitFlow workflow, for example by disallowing direct merges into the integration branch.
  4. Sensitive Operation Control: Restricts sensitive merge operations, ensuring they must be controlled by human intervention.

Installation and Enablement

In DeepSeek Harness, install the plugin using the following command:

dsh plugin --profile web add agents-gitflow-guard

After installation, the plugin is automatically mounted into the DSH process. DSH peer dependencies (@deepseek-ai/cordis and @deepseek-ai/dsh-tools) are optional; DSH provides them at runtime through shared configuration modules, so manual installation is not required.

Typical Usage

After installation, the guard can be enabled by configuring hooks.

  1. Configure Hook:
    Use the wire command to connect the guard to a client. For example, configure Claude Code:
    gitflow-guard wire --client claude --project --yes

  1. Operation Interception Example:
    When an agent attempts to push directly to the protected develop branch, the operation is intercepted:

    • Blocked Operation:
        git push origin develop

    *Result: The operation is rejected, with a prompt that changes must be merged into the integration branch via PR/MR.*

*   **Allowed Operation**:

        gh pr create --base develop

    *Result: The operation is allowed, following the PR merge process.*

Notes

  1. Default Protection: The main branch is protected by default. For users using Trunk or single-branch development models, direct pushes to main are intercepted. Disable or customize branch mapping through the configuration file (gitflow-guard.config.json).
  2. Built-in Configuration: The plugin includes a default configuration that protects the develop (integration) and main (archive) branches.
  3. Dependency Notes: Users of CLI, Pi, or OpenCode do not need to force-install peer dependencies; the plugin handles compatibility automatically.

Conclusion

By defining branch rules at the client level, AgentsGitFlowController effectively resolves the problem of AI agents breaking GitFlow conventions during development. For developers using DeepSeek Harness, it is a tool for enforcing version control standards within the agents’ permission scope.