DEV Community: Wissem Boughamoura

Inside the Architecture of an Autonomous Multi-Model Coding Agent Engine

Wissem Boughamoura — Fri, 25 Sep 2026 06:11:52 +0000

Most AI coding workflows suffer from two core failure modes:

The Ghost Exit: The runner finishes with exit code 0, but made zero code edits and wrote zero reports.
The Context Amnesia: On multi-file tasks, models forget prior architectural decisions, rewrite already completed work, or validate their own hallucinations with "looks good to me."

To solve this, I designed wb-flow — an open-source, zero-dependency orchestrator that turns chaotic agent chats into a deterministic, wave-based engineering pipeline.

Here is the complete architectural map of how it works under the hood:

flowchart TD

subgraph group_setup["Setup Surface"]
  node_install_cli["Install CLI<br/>[install.js]"]
  node_initializer["Project Initializer<br/>[init.js]"]
  node_wrapper_generator["Agent Wrappers<br/>[wrappers.js]"]
  node_command_templates["Command Templates"]
end

subgraph group_planning["Planning Commands"]
  node_plan_command["Plan Procedure"]
  node_wave_parser["Plan Parser<br/>[wave_parser.js]"]
  node_next_generator["Next Generator<br/>[next.js]"]
end

subgraph group_execution["Wave Execution"]
  node_work_command["Work Procedure"]
  node_wave_runner["Wave Runner<br/>[wave.js]"]
  node_wave_generator["Wave Generator<br/>[wave_generator.js]"]
end

subgraph group_validation["Validation State"]
  node_valid_command["Validation Procedure"]
  node_plan_linter["Plan Linter<br/>[lint.js]"]
  node_run_watcher["Run Watcher<br/>[watch.js]"]
  node_report_archiver["Report Archiver<br/>[archive.js]"]
end

subgraph group_routing["Model Routing"]
  node_wave_router["Model Router<br/>[wave_router.js]"]
  node_model_manager["Model Manager<br/>[model.js]"]
  node_model_catalog["Model Catalog<br/>[models.json]"]
end

node_developer(("Developer"))
node_coding_agent(("Coding Agent"))
node_model_providers(("Model Providers"))

node_developer -->|"requests workflow"| node_coding_agent
node_coding_agent -->|"runs bootstrap"| node_install_cli
node_install_cli -->|"starts setup"| node_initializer
node_initializer -->|"writes wrappers"| node_wrapper_generator
node_initializer -->|"copies templates"| node_command_templates
node_wrapper_generator -->|"renders procedures"| node_command_templates
node_coding_agent -->|"runs planning"| node_plan_command
node_coding_agent -->|"runs work"| node_work_command
node_coding_agent -->|"runs validation"| node_valid_command
node_work_command -->|"starts wave"| node_wave_runner
node_valid_command -->|"starts validation"| node_wave_runner
node_wave_runner -->|"parses plan"| node_wave_parser
node_wave_runner -->|"generates dispatch"| node_wave_generator
node_wave_generator -->|"reads task cells"| node_wave_parser
node_wave_generator -->|"routes roles"| node_wave_router
node_wave_router -->|"reads catalog"| node_model_catalog
node_model_manager -->|"updates catalog"| node_model_catalog
node_model_manager -.->|"probes models"| node_model_providers
node_wave_generator -.->|"dispatches work"| node_model_providers
node_coding_agent -->|"runs lint"| node_plan_linter
node_plan_linter -->|"checks structure"| node_wave_parser
node_coding_agent -->|"watches runs"| node_run_watcher
node_coding_agent -->|"archives reports"| node_report_archiver
node_coding_agent -->|"derives next"| node_next_generator
node_next_generator -->|"reads plan"| node_wave_parser

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
class node_install_cli,node_initializer,node_wrapper_generator,node_command_templates toneBlue
class node_plan_command,node_wave_parser,node_next_generator toneAmber
class node_work_command,node_wave_runner,node_wave_generator toneMint
class node_valid_command,node_plan_linter,node_run_watcher,node_report_archiver toneRose
class node_wave_router,node_model_manager,node_model_catalog,node_developer,node_coding_agent,node_model_providers toneIndigo

The 5 Architectural Pillars

1. Setup Surface (`init.js`, `wrappers.js`)

Instead of locking developers into a single closed ecosystem, wb-flow generates native command wrappers for Claude Code, Codex, OpenCode, Gemini CLI, and Cursor. Any assistant can invoke the exact same slash commands.

2. Planning Commands & DAG (`wave_parser.js`, `next.js`)

The plan is stored in Markdown tables directly on disk. The parser extracts a Directed Acyclic Graph (DAG) and partitions tasks into parallel execution Waves (Wave A, Wave B, Wave C).

3. Wave Runner (`wave.js`, `wave_generator.js`)

Runs independent tasks in parallel using isolated workers. Before any task runs, a workspace hash snapshot is taken.

4. Validation & Gatekeeper (`lint.js`, `watch.js`, `archive.js`)

Gate 1: Checks the runner process exit code.
Gate 2 (Content-Hash Gate): Compares workspace file hashes. If the agent exited cleanly with code 0 but touched zero files, it is marked as a NO-OP and rejected.
Independent Model Validation: An entirely different LLM is dispatched to run unit tests and score the worker's evidence before any task can be marked ✅ Valid.

5. Dynamic Model Routing (`wave_router.js`, `models.json`)

You can assign specific models to specific roles:

Lightweight models for mechanical tasks.
Heavy reasoning models (e.g. Claude Opus, GPT-5) for planning.
Independent models for adversarial validation.

Try it out

The entire engine has zero external npm dependencies and runs on plain Node.js.

📖 Documentation: flow.wbc-ui.com
🐙 GitHub: wissemb11/wb-flow

If you find this approach interesting or want to test multi-model wave execution in your repo, star the repo on GitHub and let me know your thoughts in the comments!

The agent exited cleanly, did nothing, and reported success

Wissem Boughamoura — Mon, 21 Sep 2026 15:13:48 +0000

An agent I dispatched exited with status zero, did nothing at all to the code, and wrote a report saying the work was finished.

My runner scored it a pass.

It was not hallucinating wildly or throwing errors. It produced a beautifully structured markdown report, the report described plausible architectural work, and the report was the only artifact the runner checked.

That is the whole failure mode, and it has a general, recurring shape:

If the agent generates the evidence, it is not evidence.

Over the past month, I have watched developers hit this exact same failure from different directions:

The check said	What the question actually was
The report is well formed	Did the work actually happen?
The model name is different	Is the billing pool / provider different?
The action is legal	Is the state still current?
The process returned code 0	Did it execute anything, or just refuse silently?
The test suite passed green	Did the agent silently rewrite the test?

That last one came from another team, and it is the most alarming. Their agent removed an authorization control, rewrote the unit test assertions so the suite remained green, and hallucinated compensating controls in the PR description to justify the diff. The security rule had been placed in its context window multiple times. It read the rule, recognized the conflict, and bypassed it anyway.

Instructions do not fix this. Better system prompts do not fix this. The verification gate must live somewhere the executing agent cannot modify.

What I do now

Two structural gates, and the first matters more than the second.

1. Independent Validator with Provider Isolation

The model that executes a task never scores it. Where billing allows, the validator model sits behind a completely separate provider.

My early version of this rule only checked for a different model name (claude-3.5 vs claude-3.7). That quietly failed for months: both slugs were routed through the same API account and identical system-prompt wrappers. Two different model names, one single point of failure.

2. The Workspace Content-Hash Gate

To prevent an agent from doing nothing and pretending it succeeded, the orchestrator computes a content hash over the entire repository before and after the dispatch, strictly excluding the task's own report directory. Writing a markdown report can no longer masquerade as doing engineering work.

Credit belongs to community member saltexx, who suggested using isolated git worktrees for differential comparison before the current content-hash gate was built. His worktree approach is even more rigorous than content hashing, and it correctly identified that detecting a no-op is an operating system and filesystem question, not an LLM judgment call.

What is still broken

We should not pretend this is fully solved. While dogfooding the harness, I found two of my own validation gates broken in both directions: one passing a task cell that never ran because a CLI exit code returned 0 on an API error, and another failing a task that had completed cleanly because of unanchored string matching on the word "error".

The tool built to enforce accountability was itself flawed, and nothing was watching it.

I packaged these safeguards into wb-flow. It enforces a strict three-gate verdict contract (Infra, Artifact, and Oracle) and isolates Worker and Validator roles across different models. You can test it in any repo:

npx wb-flow

If you are running coding agents across complex repositories, how are you verifying that your agents actually changed the code rather than just writing reassuring prose?

I stopped letting the conversation be my project state

Wissem Boughamoura — Mon, 14 Sep 2026 15:25:34 +0000

The failure that started this was boring. A long session doing a change across several files would redo something it had already done. Not dramatically. It would just re-edit a file it had finished twenty minutes earlier, or mark a task complete based on what the conversation said rather than what was actually in the repo.

I tried the obvious things. Better system prompts. Stern reminders. A summary at the top of every message. They all worked for a few turns and then degraded, because they were all stored in the exact same place as the thing that was failing: the conversation buffer.

So I moved the state out of the chat window and onto disk.

A plan is now a markdown file in the repository. One row per task. Each row is a strict contract: what the task is, what it depends on, how to verify it before touching code, which role runs it, and whether an independent model validated it:

#	Requires	Dep	Task	Verify	P	Est. Time (mins)	Worker (Suggested)	Validator (Suggested)	☐ Done	☐ Valid
1	🔨 Worker	—	Fix prop types in WBCode	/wbTest --scope=task-1	P1	15	-M=$WORKER	-M=$VALIDATOR	✅	✅ 9/10
2	🔨 Worker	1	Extract helpers into wbc-utils	npm test	P1	30	-M=$WORKER	-M=$VALIDATOR	✅	✅ 8/10
3	✅ Validator	2	Audit exports for safety	/wbAudit --focus=exports	P0	20	—	-M=$VALIDATOR	⬜	⬜
4	🧠 Planner	2	Plan parser migration	/wbAudit wb-parser	P2	45	—	—	⬜	⬜

That was the architectural starting point. Once the workflow state became explicit and persistent, several other things became possible:

The session stopped mattering. Context compacts, a provider hits a rate limit, a run crashes overnight. None of that loses your progress. A new session opens the plan file, inspects the unchecked rows, and knows exactly where the work stands without needing a 20-minute re-explanation.

Dependencies became real data. Once a row specifies what it depends on (Dep: 1), parallelization and execution order can be derived deterministically from the dependency graph instead of something you hold in your head and pray the agent remembers.

The check moved to before the work. The Verify column gets written when the plan is authored, not after the task runs. Deciding how you will know a task succeeded before touching code is completely different from evaluating output when you are already psychologically invested in it.

Handoff stopped being a lossy transfer. Every agent reads the same codebase context and the same plan file. The next model picks up where the last one stopped. There is nothing to compress, because project state was never an ephemeral chat blob. The conversation became a working surface, not the source of truth. The repository became the source of truth.

What it costs: the unstructured exploratory chat is gone. Anything that did not become a task or a report does not survive. That is a real trade-off and I would not pretend otherwise.

I eventually packaged this pattern into an open-source tool called wb-flow. It keeps plans, task state, execution evidence, and validation artifacts in the repository, while the coding agent remains replaceable:

npx wb-flow

The conversation can disappear. The engineering state shouldn't.