Vibe-coding "just add one more feature" always rots. Here's the C++ skeleton I built to stop it.

Andy Cho — Wed, 01 Jul 2026 00:17:49 +0000

Repo (MIT): https://github.com/splendidz/uniflow

This is a long one. dev.to feels like the right place for that, so I am going to actually explain the thing instead of just dropping a link. If you only want the gist: I built a small framework that gives your control logic a fixed skeleton, so it stops rotting into spaghetti as you add features, and so an LLM has exactly one place to put each change. Everything runs cooperatively on one thread, so there are no locks. That's the whole pitch. The rest of this post is the "why" and the "how it actually works", because that part is what I actually care about.

One thing up front, before you decide this is not for you because of the language. It is C++ first (single header, no deps, C++17), but I did not stop there. I ported the entire framework and every demo to Python and C# as well, with the public APIs named to mirror each other (Task / StartFlow / SubmitAsync / AsyncResult / SetScale / Freeze, and so on). So whatever stack you are on, there is a version you can actually run. The code samples below are C++, but every one of them has a 1:1 equivalent file you can open and read:

C++: cpp/examples/
Python: python/examples/ (run with just python python/examples/<name>.py)
C#: cs/examples/ (run with dotnet run --project cs/examples/<name>)

If you are a Python or C# person, do not let the C++ snippets scare you off. Go open the same demo in your language, it reads almost the same.

I will also warn you up front: my English is not perfect. I am going to write plainly and a bit slowly so the ideas come through. Bear with me.

Where this comes from

I do equipment and motion control for a living. Machines, motors, sensors, that kind of thing. For about 14 years now. So the code I write all day is "ordered logic on a single thread": do this, wait for that sensor, then move the axis, then check the result, then go to the next step. If you have done embedded or automation work you know exactly the shape of it.

And for years, the shape of that code was always the same. One big switch on an integer step_no, a sleep(10) loop around it, and a pile of bool flags to remember where I was.

// the way I wrote it for years
int step_no = 0;
while (running_)
{
    switch (step_no)
    {
    case 0: Init();              step_no++; break;
    case 1: if (Ready()) step_no++;          break;
    case 2: Process();           step_no++; break;
    }
    sleep(10);   // always 10ms, whether we are busy or doing nothing
}

This works. It ships. Machines run on code that looks exactly like this all over the world right now. But you already know the problem, because everyone who writes this hits it: a few months of "just add one more case" later, the file is huge, the flags fight each other, and only the person who wrote it can read it.

The worst version of this I ever inherited was a single .cpp file with tens of thousands of lines of control logic in it. One guy had owned it for eight years. When I joined and could not instantly find my way around his file, he looked at me like I was the slow one. Honestly, to me, he was the one who looked bad. The code was readable only to him, and that was the whole problem, not me. That file basically held the team hostage.

So I have wanted a better default shape for this kind of code for a long time. The framework in this post is my attempt at it.

Then vibe-coding made it worse, and also made it matter more

Here is the new part. I lean on LLMs a lot now. I vibe-code big chunks of my work.

And the failure mode is brutal and familiar. You tell the model "add feature X." It says yes. The feature lands wherever it happens to fit. You say "now add Y." It says yes again. Three weeks later you open the file and it is the exact same flag soup I described above, except now it was generated faster, so there is more of it.

The model is not stupid. It is doing what the structure allows. If the structure allows a mess, you get a mess. There is no skeleton telling the model "the new step goes here, and nowhere else."

So that pushed me to finally build the thing. Not because AI is magic, but because AI removes the last bit of friction that used to keep code somewhat in shape. When a human adds the 40th feature by hand, the pain of touching the giant function at least makes them think. The model feels no pain. It will happily make it worse forever. So the structure has to be enforced by something that is not "a careful developer."

I called it uniflow.

The core idea, in plain words

The model is deliberately boring. Two concepts.

A Flow is one thing that can only be in one state at a time. A car cannot drive forward and backward at once, so one car is one Flow. A device, a connection, one agent in a sim, one event processor: each is one Flow. If only one operation can run on it at a time, it is a Flow.

A Task is one unit of work inside that Flow, and it is a chain of small named steps. Each step is a function. A step runs from start to finish, never blocks, and at the end it returns one of four things telling the framework what to do next:

Next(...) go to the next named step
Stay() stay on this step, run me again next round (this is how you wait without blocking)
Done() this task finished normally
Fail() this task failed

That is the entire vocabulary. A step never sleeps, never spins a loop waiting for something. If it needs to wait, it returns Stay() and gets called again later. The waiting is the framework's job, not yours.

Here is the smallest real shape. Notice that the declaration (the list of step names) and the bodies are separate. The declaration is the skeleton, and you can read the whole flow just by reading the function names top to bottom:

#include "uniflow.hpp"

// One flow = one module.
class Flow_Example : public uniflow::Uniflow<Flow_Example>
{
public:
    explicit Flow_Example(uniflow::Runtime& rt)
        : uniflow::Uniflow<Flow_Example>(rt, "Example")
    {
        AddTask(task_);   // wire the task to the flow, one line, once
    }

    // A task owns its own steps. Entry is public; the rest are private.
    struct MyTask : uniflow::Task<Flow_Example>
    {
        StepResult Entry() override { return Step1_Begin(); }   // the only entry point

    private:                          // these are reachable only via Entry / Next
        StepResult Step1_Begin();
        StepResult Step2_Work();
        StepResult Step3_Done();
    } task_;

private:
    bool ready_ = true;               // the flow holds the state; steps read it via flow()
};

And the bodies (in a real project these live in the .cpp):

uniflow::StepResult Flow_Example::MyTask::Step1_Begin()
{
    Describe("initialization complete");   // one line that shows up in the trace later
    return Next(UF_FN(Step2_Work));        // go to the next step of THIS task
}

uniflow::StepResult Flow_Example::MyTask::Step2_Work()
{
    if (!flow().ready_) return Stay();     // not ready yet? re-run me next round. no blocking.
    return Next(UF_FN(Step3_Done));
}

uniflow::StepResult Flow_Example::MyTask::Step3_Done()
{
    return Done();                          // task ends, module goes idle
}

Look at Step2_Work. That if (...) return Stay(); is the whole trick for waiting. There is no while, no sleep. You check the condition once. If it is not ready, you bail out and the framework calls you again on the next round. From the outside it looks like the step is "waiting" on the condition, but the thread is never stuck inside it.

Why this shape can't sprawl (the part that matters)

This is the actual point of the framework, more than the async stuff. The structure is not a style guide you hope people follow. It is enforced by the types and by visibility.

Three rules do all the work:

A step can only point to a sibling step in the same task. Next(UF_FN(Step2_Work)) only compiles for steps that belong to this task. You cannot jump into the middle of some other task's chain. To cross into another unit of work, you have to do it explicitly with StartTask(...), and that boundary shows up right there in the code.
Steps are private. Entry is the single public door. You literally cannot call Step3_Done() from outside the task. The only way in is Entry(). So there are no hidden entry points, no "oh someone set step_no = 2 from over here" surprises. The flag-based version lets anyone, anywhere, write step_no = 1 and cut into the middle of a sequence. This does not allow that. The compiler does not allow that.
Every transition is named, in code, at the point it happens. A step says return Next(UF_FN(Step3_Save)). So to understand the order of the logic, you read the list of step names. That's it. The flow is fixed by declaration, not by tracing flag mutations across 600 lines.

So now when I tell the model "add a step that slows down for pedestrians before the car waits at the light," the only legal place for that change is: one new private step function, plus one Next(...) rewire. It physically cannot spread the change across the file, because the file does not have a place to spread it into. Feature #50 has the same shape as feature #1.

That is the property I was chasing. Not "the AI writes good code." It is "the structure makes the bad version not expressible."

Let me show you the flag soup it replaces

I want to make this concrete, because "spaghetti" is too abstract. Here is a fairly honest version of what real flag-based control code turns into. This is a connect / send-command / wait-for-ack loop with retries, reconnects, e-stop, and fault. Read it and feel the dread:

void Update()
{
    if (estop_)
    {
        // e-stop can hit at ANY stage, so every progress flag must be rolled back here
        connecting_  = false;
        cmd_sent_    = false;
        waiting_ack_ = false;
        // oops, forgot draining_ -> next cycle waits for a ghost ack. that's a real bug.
        if (!device_.IsSafe()) return;
        estop_ = false;
    }

    if (!connected_)
    {
        if (!connecting_)
        {
            device_.BeginConnect();
            connecting_ = true;
            connect_timer_.Restart();
        }
        else if (device_.IsConnected())
        {
            connected_  = true;
            connecting_ = false;
        }
        else if (connect_timer_.Passed(5000ms))
        {
            if (++reconnect_count_ > 3)
                fault_ = true;        // fault_ is checked way down somewhere else, good luck
            connecting_ = false;      // and where do we reset reconnect_count_? who knows
        }
    }
    else if (!cmd_sent_)
    {
        if (input_.HasRequest() && !draining_)
        {
            device_.Send(input_.Take());
            cmd_sent_    = true;
            waiting_ack_ = true;      // these two flags must ALWAYS move as a pair. nothing enforces that.
            cmd_timer_.Restart();
        }
    }
    else if (waiting_ack_)
    {
        if (device_.HasAck())
        {
            // forget even one of these 5 lines and the next command is blocked forever
            cmd_sent_        = false;
            waiting_ack_     = false;
            retry_count_     = 0;
            reconnect_count_ = 0;
            draining_        = input_.HasRequest();
        }
        else if (cmd_timer_.Passed(3000ms))
        {
            if (++retry_count_ < 3)
            {
                cmd_sent_    = false;   // "go back to the send step" expressed as flag juggling
                waiting_ack_ = false;
            }
            else if (!fault_)
            {
                fault_ = true;
                connected_ = false;     // roll back the connection too... and reconnect_count_...?
            }
        }
    }
    // what handles fault_? what if estop_ AND fault_ at once? no branch actually says.
}

I have written code like this. You have too. Every flag is implicitly responsible for resetting some other flag, the e-stop and fault paths can cut in anywhere, and "forgetting to reset one flag" is a whole category of bug. The brace depth grows. Nobody can review it because reviewing it means simulating it in your head.

Here is the same logic in uniflow. Each state is one named step. The brace depth is flat. The transitions are explicit:

StepResult Step1_Connect()
{
    flow().device_.BeginConnect();
    return Next(UF_FN(Step2_WaitConnected));
}

StepResult Step2_WaitConnected()
{
    if (!flow().device_.IsConnected()) return Stay();   // poll until connected, no blocking
    return Next(UF_FN(Step3_WaitRequest));
}

StepResult Step3_WaitRequest()
{
    if (!flow().input_.HasRequest()) return Stay();
    flow().device_.Send(flow().input_.Take());
    return Next(UF_FN(Step4_WaitAck));
}

StepResult Step4_WaitAck()
{
    if (flow().device_.HasAck()) { flow().OnSuccess(); return Done(); }
    return StayTimeout(3000ms, UF_FN(Step5_Timeout));   // no ack in 3s -> jump to the timeout step
}

StepResult Step5_Timeout()
{
    if (++retry_count < 3) return Next(UF_FN(Step3_WaitRequest));   // retry_count is a task member
    flow().OnFail();
    return Fail();
}

Adding a stage now means: add one function, change one Next. The other stages do not move. The e-stop / fault paths become explicit transitions instead of flags that secretly reset each other. That StayTimeout is a nice one too: it means "keep polling this step, but if too much time passes, go over there instead." A timeout is just another named transition, not yet another timer flag.

The execution model: one thread, no locks

Okay, so how does "return Stay() and get called again" actually run? This is the part people poke at the most, so let me go slow.

The unit of execution is a pump thread. One Runtime owns one pump thread. You attach as many Flow modules as you want to that one Runtime. The pump goes around in rounds. Each round has three stages:

Drain the post queue. Other threads can hand work to the pump by calling Post(...). Those callbacks run here, on the pump thread. So they can touch module state without a lock, because they are running on the same thread as everything else.
Run each module once. For every active module, call its current step body exactly one time. The step returns one of Stay / Next / Done / Fail. Round-robin. Nobody blocks. If module A is sitting on Stay() waiting for a sensor, that is fine, it returns immediately and module B gets its turn.
Pick how long to sleep before the next round. This is the "smart" part, see below.

Now here is the thing that falls out of this, and it is the single biggest reason I like the model:

Because every module runs on the same one thread, one at a time, shared state between modules needs no lock.

No mutex. No spinlock. No rwlock. No "did every thread remember to take the right lock in the right order." That entire category of bug is just gone, because there is only ever one thread touching the shared world. In my traffic demo, 15 cars and the traffic lights all read and write a shared World object (where is every car, what is each light doing) and there is not a single lock on it. There cannot be a data race, because there is no second thread to race with.

I made a diagram for this because it is really the heart of it:

(left: a pile of threads all reaching into shared state through locks, hoping everyone took the right one. right: one pump thread visiting each flow in turn, shared state with no lock at all.)

Here is what running several modules on one thread looks like. This is two machine axes homing "at the same time" on a single thread:

uniflow::Runtime rt;            // one pump thread

Flow_XAxis x_axis{rt};
Flow_YAxis y_axis{rt};

x_axis.task_home_.StartFlow();  // start homing X
y_axis.task_home_.StartFlow();  // start homing Y, at the same time

// what the pump actually does, round by round:
//   Round 1: X.Step1 (send move cmd) -> Next   |  Y.Step1 (send move cmd) -> Next
//   Round 2: X.Step2 (still moving)   -> Stay   |  Y.Step2 (still moving)   -> Stay
//   Round N: X.Step2 (in position)    -> Done   |  Y.Step2 (still moving)   -> Stay
//   Round M: (X is idle now)                    |  Y.Step2 (in position)    -> Done
//
// while X is parked on Stay(), Y runs, and vice versa.
// both axes move together, and there is no mutex anywhere.

The old way to get two axes moving together was two threads and a join. Each GoHome() was a blocking call, so you needed a thread per blocking call, and then you needed locks around anything they shared. Here, "moving" is just a step that returns Stay() until the motor reports it is in position. No thread blocks, so you do not need a second thread, so you do not need a lock. The complexity does not move somewhere else. It actually goes away.

"But a single thread can't scale / will block"

Two objections always come, so let me answer both directly.

"One thread won't use my cores." Correct, one Runtime is one core, on purpose. If you want more cores, you make more Runtimes. Each Runtime is its own pump thread. The thread boundary is a decision you make as the designer ("these modules go on pump A, those go on pump B"), not something forced on you per unit of work. And if you decide two Runtimes should actually share one thread again, Runtime::Link() merges them back onto a single pump, and they are lock-free with each other again. You choose where the thread lines are. That is a feature, not a workaround.

"A long task will freeze the whole pump." This is the real one, and the answer is the same answer libuv and Node use. The pump thread must never block. So genuinely blocking work (network I/O, a heavy computation, a slow device call) does not run on the pump. You throw it to a built-in thread pool with SubmitAsync, and you get the result back later as just another step. While that work runs on a pool thread, the pump keeps spinning and every other module keeps making progress.

It looks like this:

StepResult Step1_FetchData()
{
    Describe("fetching");
    // hand the blocking call to the pool. returns an id. 0 means it was rejected.
    AsyncId job = SubmitAsync(UF_FN(DoFetch), std::chrono::milliseconds(5000), url);
    if (job == 0) return Fail();
    return Next(UF_FN(Step2_Process), job);   // carry the id to the step that reads the result
}

StepResult Step2_Process(AsyncId job)
{
    auto r = AsyncResult<std::string>(job);
    if (r.pending())                              // not done yet -> just Stay and poll
        return StayTimeout(5000ms, UF_FN(Step_GaveUp));
    if (r.is_timeout() || r.failed() || !r.ok())
        return Fail();
    data = *r.return_value;                       // filled in only when it actually finished
    return Next(UF_FN(Step3_Save));
}

// runs on a pool thread, so it has to be static. no access to instance state.
static std::string DoFetch(std::string url) { return http_.Get(url); }

The nice side effect: the step that starts the work and the step that reads the result are separate functions. So the flow stays explicit, the wait shows up in the trace, and the continuation runs back on the pump thread, which means even the result handling touches shared state with no lock. When the pool work finishes, it calls Wake() on the pump so you catch the result immediately instead of waiting out a poll interval. Honestly the longer the work takes, the more this model pays off, because the "start" and "finish" being separate steps is exactly what you want for something slow.

You can also fire several jobs and join them in one step, set per-step timeouts, abandon a worker you gave up on (it keeps running in the background and the framework logs that you abandoned it, so the leak is visible). I will not dump all of that here, it is in the repo.

Smart polling: it is not a busy-loop

Back to step 3 of the round, picking the sleep. The old sleep(10) had a dumb problem: it waits the same 10ms whether the machine is in the middle of a fast sequence of transitions or sitting completely idle. So it is both too slow (it adds 10ms of lag between back-to-back steps) and too wasteful (it burns a wakeup every 10ms doing nothing).

The pump picks the wait based on what just happened this round:

what happened this round	next wait	why
at least one module advanced (`Next`/`Done`/`Fail`)	0ms (default)	things are happening, go straight to the next round, no lag
everyone was just polling (`Stay`)	20ms (default)	normal idle-ish polling, CPU stays near zero
everyone is idle	1ms (default)	pick up brand new work fast

And when an external event shows up (a packet arrived, a sensor fired), any thread can call rt.Wake() and the pump wakes up right now instead of waiting out its sleep:

void OnNetworkReceived(Packet pkt)
{
    module_.SetPendingPacket(pkt);
    runtime_.Wake();      // wake the pump immediately, don't sit through the sleep
}

So it reacts instantly when there is work, and it nearly fully releases the CPU when there is not. That is the difference between this and a naive tick loop. Same mental model as the old switch/sleep, but the framework owns the timing and does it well.

The thing I did not expect to like the most: the trace

Because every single thing that runs reduces to "a step function got called once," there is exactly one place to measure. So the framework can just tell you what your code is doing, with no logging code from you:

[JobWorker    ] FLOW START  caller=main.cpp:42 main()
[JobWorker    ] Entry -> Step2_Validate                         #00 elapsed=0.01ms  tick x8 avg=0.01ms
[JobWorker    ]                 ASYNC SUBMIT  CallApi
[JobWorker    ]                 ASYNC DONE    CallApi  wait=124.38ms
[JobWorker    ] Step2_Validate -> Step3_WaitSave  inserted=3000  #01 elapsed=124.42ms tick x1 avg=0.03ms
[JobWorker    ] Step3_WaitSave -> Done                           #02 elapsed=18.71ms  tick x1
[JobWorker    ] FLOW END  DONE  steps=#02  wall=143.21ms  step=0.07ms  async=143.09ms  tick x10 avg=0.01ms

Each line is a transition, the time spent in that stage, how many times the body ran, the async wait, and whatever you wrote in Describe(). You can set "warn me if a step takes longer than 10ms" or "warn me if an async job takes longer than 500ms" with a couple of config lines, and you can plug your own observer in to push this to your metrics system. The measurement point is in one place, so your instrumentation and your business logic stay separate. For debugging machine behaviour at 2am this has saved me more than once.

Where it is the wrong tool

I do not want to waste your time, so here is where I would tell you not to use it:

CPU-bound work that needs every core. One pump is one core. You can push heavy compute to the pool, but if raw parallel number-crunching is the actual goal, use a real parallel tool, not this.
Hard real-time microsecond paths. The cooperative round is your latency floor. If you need guaranteed microsecond response, this is not it.
A third-party blocking loop you cannot break up. You can isolate it with SubmitAsync, but if your whole program is one big blocking library call, there is not much for uniflow to structure.

It shines for ordered, async-ish control logic with a mix of sync and async steps: equipment and motion control, protocol handlers (connect / handshake / send / reconnect), backend job pipelines (pull from queue / validate / call API / retry / store), simulations with many agents over shared state. Anything where the honest description is "a sequence of steps, some of which wait."

How it compares, quickly

vs C++20 coroutines: coroutines are great but they are a language feature, so they enforce no structure. How you split a coroutine is up to each developer's taste, so over time it fragments again, same as before. They also need C++20. uniflow is C++17 and enforces the flow/task shape. They also compose fine, you can co_await inside a step if you want.
vs Boost.Asio: Asio is powerful but adopting it means restructuring your code onto io_context / awaitable / executors, and it is shaped for sockets. uniflow is one header, no deps, and it does not absorb your existing objects. It only structures the logic that drives them. You can still use Asio for the actual I/O inside a step.
vs an actor framework: this stays plain C++ objects with no message-passing ceremony, and it drops into existing code without a rewrite.
vs Boost.SML / statecharts: those are transition-table DSLs. uniflow is just plain functions returning a result, so normal control flow, breakpoints, and debugging all work the way you expect.

The honest closing

Quick facts again: one header, zero dependencies, C++17, builds on MSVC / GCC / Clang. Ported to Python and C# with matching APIs. There are six demos (a virtual CNC line, a city of cars on one thread, a time-scaling simulator, and so on), each provided identically in all three languages. MIT licensed.

Here is the real reason it is MIT and the real reason I wrote it all out. After 14 years I have a pretty firm opinion: working-but-messy code is worse than clean code that does not run yet. Code that does not run gets fixed fast and has room to grow. Messy code that happens to work just grinds down your good engineers, while the people who cannot do better wall off their corner and call it job security. It becomes a kind of tumor in the team. I have watched it happen more times than I can count, and that eight-year single-file guy is just the clearest example.

uniflow is overkill for a tiny bit of logic, sure. But unless it is a project you will own alone forever, use some methodology, it does not have to be mine, and ideally one that can be enforced a little, so the shape of the code does not rot as it grows. That is the entire reason this exists. I would rather hand the idea out and let people argue with it than keep it sitting in my repo.

So: tell me where it breaks. Tell me where it is the wrong call. I will be in the comments answering, and honestly the technical pushback is the part I am here for.

Repo: https://github.com/splendidz/uniflow

DEV Community: Andy Cho