GoalRun: A Goal-Driven Verification Framework for AI Agents in Software Engineering

GoalRun is a goal-driven verification framework for AI agents in software engineering, designed to address the prevalent "false completion" issue in current AI programming assistants (e.g., claiming to fix a bug but the problem persists, stating tests passed without running them, etc.). Its core concept is "goal-driven + mandatory verification", ensuring AI outputs are verifiable, auditable, and meet expectations through a structured workflow. The framework does not replace existing AI tools; instead, it collaborates as a verification layer to enhance the credibility and maintainability of AI outputs.

With the popularity of AI programming assistants like Claude Code, Codex CLI, and Cursor, while developer productivity has increased, the "false completion" issue has become prominent: agents often claim to have completed tasks without actually doing so (e.g., bugs not fixed, tests not run, refactoring breaking APIs, etc.). Traditional AI programming workflows lack structured verification mechanisms, relying on the quality of prompt engineering and developer vigilance, which poses unacceptable risks for complex tasks (multi-file modifications, test updates, API changes).

The core concept of GoalRun is: before AI executes code, clear goals and verification standards are defined; after claiming completion, verification is enforced until the standards are met. The framework is positioned as a "Verification Harness"—it does not directly call LLM APIs or replace existing AI assistants, but provides a structured workflow to ensure the verifiability, auditability, and compliance of AI outputs.

GoalRun ensures quality through five mechanisms:

1. Goal Harness: Requires developers to define goals in YAML (including id, goal, skills, criteria, etc.), verifies the completeness and consistency of specifications, and rejects ambiguous standards.
2. Skill Harness: Performs static verification (schema compliance, permission review, sensitive information scanning, etc.) on reusable skills (e.g., tdd-change, code-review).
3. Policy Harness: Blocks dangerous operations (file deletion, API changes, authentication logic modifications, etc.) and configures security levels in conjunction with goal policies.
4. Criteria Harness: Automatically executes verification commands (e.g., tests, type checks) after AI claims completion; only marks as completed if all criteria are met, otherwise revision is required.
5. Audit Harness: Maintains a complete checkpoint history, recording state transitions, operations, verification outputs, file diffs, etc., to support troubleshooting and compliance.

Supervised Execution Loop: The state machine includes planned→waiting_for_agent→waiting_for_user (manual review)→verifying→completed/needs_revision; if verification fails, it iterates; if the budget is exceeded, it is marked as failed; policy-prohibited operations trigger manual approval. Collaboration Model: GoalRun collaborates with existing AI tools in a division of labor—developers use GoalRun to define goals and standards, the framework generates an execution plan for AI assistants (e.g., Claude Code) to execute, and after AI outputs, GoalRun is responsible for verification, leveraging their respective strengths (AI excels at generation, GoalRun excels at verification control).

Project Status: P0-P2 phases completed (core CLI, 5 verification mechanisms, 3 built-in skills, supervised checkpoint loop, etc.); P3 (Git isolation, rollback) and P4 (adaptation to Claude/Codex/Cursor) are planned; implemented in TypeScript/Node.js, requiring Node.js 20+ and pnpm 9+, with test coverage of 248 passing tests. Typical Scenarios: Complex bug fixes (multi-file modifications + regression tests), refactoring tasks (API compatibility + performance benchmarks), code review assistance (structured quality checks), team collaboration (auditable workflows).

GoalRun represents a more responsible AI-assisted programming paradigm. It faces up to the limitations of AI and upgrades "AI assistance" to "verifiable AI assistance" through structured verification. For developers/teams, it does not reduce productivity but significantly enhances the credibility and maintainability of AI outputs, making it a worthy consideration for AI programming governance.