GOAT Flow: A Structured Workflow Framework for AI Programming Agents

GOAT Flow is a structured workflow system designed for AI programming agents. It addresses common reliability issues in agent development through the READ→SCOPE→ACT→VERIFY execution loop, seven structured skills, safety hooks, and learning loops.

While current mainstream AI programming assistants (such as Claude Code, Codex, Gemini CLI) are powerful, they have systemic flaws when executing autonomously. They tend to guess the meaning of unread code, submit modifications without checking, create duplicate files instead of editing existing ones, and fail to learn from past mistakes. The root cause of these issues lies in the lack of structured execution constraints and cross-session memory mechanisms.

The traditional solution is to write detailed instruction files telling agents the rules to follow, but instruction files can only provide suggestions and cannot enforce compliance. GOAT Flow's core insight is: Agents need a set of non-skippable mechanisms, not just rules they should remember.

GOAT Flow is built around five key concerns, each corresponding to a specific type of failure mode:

This is GOAT Flow's core workflow pattern. Before performing any operation, the agent must first read the relevant code (READ), clarify the modification scope (SCOPE), execute specific modifications (ACT), and finally verify the results (VERIFY). The VERIFY phase requires running actual tests and citing specific pass/fail outputs instead of simple retellings. This mandatory sequence prevents agents from making blind modifications without understanding the codebase.

GOAT Flow provides seven predefined skill commands (e.g., /goat-review, /goat-plan, /goat-critique), each with clear phases and human checkpoints. This contrasts with free-form prompts, which tend to drift during execution. The skill system ensures agents always handle specific types of tasks in a consistent manner.

The framework includes the deny-dangerous.sh hook by default, which intercepts tool calls before execution. This prevents dangerous operations such as rm -rf, force-push, and accessing key files. Unlike post-hoc audits, hooks block execution beforehand, providing true security protection.

GOAT Flow maintains footguns (common pitfalls), lessons (learned experiences), decisions (decision records), and session logs in the .goat-flow/ directory. These contents are automatically read at the start of a session, enabling agents to avoid errors that were recorded last week. This cross-session memory mechanism addresses the root problem of agents repeating mistakes.

The framework defines three autonomy levels: Always (execute always), Ask First (ask before executing), Never (never execute), to prevent agents from overstepping their authority. It also provides reference templates for planning, security, compliance, and other fields to ensure outputs meet domain-specific professional standards.