Reflection SDD: Use a Reflection Harness to Level Up Your OpenSpec Workflow

Sign in<br>Subscribe

Introduction<br>In this article, I want to walk you through how I introduced a reflection mechanism into the OpenSpec workflow inside OpenCode, and how that dramatically improved the quality of AI-generated code.<br>After nearly a month of testing, this reflection workflow has gotten DeepSeek-V4-pro in OpenCode to perform at roughly the same level as Claude Opus 4.6. The only cost is some extra review time and a few more tokens. Trust me, it's worth it.<br>Can't wait to find out how? Let's get into it.<br>Why This Works

I've been using AI coding for a while now. Compared to Claude Code, I prefer building my own SDD-based coding workflow with OpenCode and OpenSpec. I wrote a well-received article specifically about this OpenCode workflow:<br>How I Use OpenCode, Oh-My-OpenCode-Slim, and OpenSpec to Build My Own AI Coding Environment<br>Ride the wave of AI coding, don’t get swept away by it<br>Data Leads FuturePeng Qian

With OpenSpec, and the explore → propose → apply → verify → archive workflow loop, we can finally get LLMs to handle complex project development.<br>With the OpenSpec workflow loop, LLMs can finally write usable code. Image by AuthorBut just like you've probably run into, even with the SDD workflow, no matter which model I use, GPT 5.5 or the latest DeepSeek-V4-pro, the AI still inevitably produces hidden bugs or piles up messy code. Code I'd never feel comfortable putting in production.<br>My first fix was to call a @reviewer sub-agent after the /opsx-apply phase to do a code review on the changes. Sometimes that worked and caught architectural or implementation issues. But the impact was limited.<br>Often I'd only discover something was wrong after using the project for a while: a scenario wasn't covered, edge cases were missed, or one part of the code got updated but a related module didn't.<br>Later I stepped back and looked at the whole AI coding workflow again, and that's when I spotted the real problem.<br>As programmers, we always focus on whether our code is good, so we naturally look at things from the code level.<br>But we completely overlooked the quality of the proposal files that OpenSpec generates. We'd finish discussing requirements, generate the proposal file, and then just let the AI start implementing. That's how input-level bugs get introduced. When things go wrong, we blame the model.<br>Think about it, back in the traditional coding era, when a product manager handed over a requirements doc, there was a critical step before we started coding: requirements review. We wouldn't touch the keyboard until every issue in the requirements doc or design doc was sorted out.<br>So why did we forget this step in the AI coding era? That's exactly what we're going to fix today: add the requirements review step back into the OpenSpec workflow and see if it makes AI-generated code better.<br>How to Do It<br>The SDD workflow isn't anything exotic. If you're familiar with multi-agent system design patterns, you'll recognize that SDD is basically the plan-execute pattern.<br>One agent breaks the user's task into a step-by-step plan file, then another agent follows that plan to execute the task. This lets the agent system handle complex work.<br>The Plan agent makes the plan, the Executor agent gets it done. Image by AuthorBut how do you guarantee the quality of what the agents produce in a plan-execute setup? That's where a pattern called reflection comes in.<br>The reflection pattern adds a reflection agent to the multi-agent workflow. This agent typically runs on a completely different LLM and reviews the output of the plan or executor agent from a different angle, which raises the overall performance of the multi-agent system.<br>The reflection pattern sees wide use in content creation and deep research scenarios, which proves it works.<br>Just adding a reflection step can dramatically improve task quality. Image by AuthorSince the pattern is proven, we can bring the same reflection step into the OpenSpec workflow, targeting the proposal files.<br>I'll introduce a reflection agent that runs on a different LLM from the primary agent, reviewing the proposal files from a different angle. We'll also adjust the OpenSpec workflow so this reflection agent plays an active role in it.<br>Introducing the reflection agent<br>Adding a new agent in OpenCode is simple. Just drop a new Markdown file into ~/.config/opencode/agents/ with the agent's prompt inside.<br>The core job of this agent is straightforward: review the artifact files that OpenSpec generates from multiple angles, making sure the quality of the requirements input is solid from the start. This agent sits between the /opsx-propose and /opsx-apply phases.<br>Only proposals that pass review can move on to the apply phase. Image by AuthorWe can have deepseek-v4-pro generate the first draft of this agent's prompt:<br>You are an **OpenSpec Change Reviewer** — a critical thinker and auditor focused on substance.

Your job is to...