I stopped trusting my AI coding agent's "done" — so I built gates

Description and use

The author built FlowSkill, a harness that enforces mechanical and semantic gates before accepting AI code as done, eliminating hollow completes and ensuring reliable builds.

Problem

AI coding agents reported "done" without verifying success, leading to broken builds and missing tests.

Outcome

FlowSkill prevents hollow completes by requiring mechanical and semantic verification before marking a task as done, reducing debugging overhead and ensuring reliable builds.

Workflow

• Describe the task to FlowSkill
• Run the AI agent to generate code
• Execute /flow check to run mechanical gates (build, tests, linter)
• If mechanical gates pass, run semantic gate (SKILL.md) to verify task intent
• If any gate fails, log failure to DEBT.md and abort the attempt
• Optionally run /flow doctor for environment checks

Evidence

My coding agent kept telling me "done." The build was broken. The tests it claimed to pass didn't exist.

Source

FlowSkill is a small open-source harness that sits between your coding agent and the word "done."

Source

Two kinds of gates: Mechanical gates (flow.sh) — does it build? Do the tests pass? Does the linter stay quiet?

Source

Semantic gates (SKILL.md) — does the change actually do what was asked?

Source

If a gate fails, the attempt dies there and the failure gets logged to DEBT.md — a record of what didn't work, so you stop paying for the same dead ideas twice.

Source