DEV Community: Alexander Ivanov

One interface, three forges

Alexander Ivanov — Sat, 26 Sep 2026 02:29:20 +0000

Until this week, OpenSpec Workbench knew one way to open a pull request,
check it, and merge it: gh, GitHub's own CLI. If your repository lived on
GitLab or Gitea, or if gh simply was not installed, the archive stage said
so and stopped. That is fixed now, on all three, and the way it got fixed is
the more interesting part.

The interface, not the tool

The fix is not "support GitLab too" bolted onto the GitHub path. It is one
Forge interface - list a pull request by branch, open one, ask for a merge,
read its checks - that the git stage and the archive pass call without
knowing which host answers. Three implementations sit behind it: GitHub's
own REST and GraphQL, GitLab's REST API, and Gitea's. Which one runs is
decided once, by reading the repository's own origin: github.com is
GitHub, gitlab.com is GitLab, and anything else is probed - Gitea's
/api/v1/version first, then GitLab's /api/v4/version - so a self-hosted
instance is found without being told what it is.

The token decides the way, even for GitHub

GitHub is the one host that had two paths from the start: gh, or now its
own API when GITHUB_TOKEN or GH_TOKEN (the same variable gh itself
reads) is set in the environment. Without one, the product goes through
gh exactly as before - this did not become a breaking change for anyone
already running it. Where neither a token nor gh is available, the
reading says so plainly: "gh is not installed, and GITHUB_TOKEN is not
set", rather than failing on a command that was never going to work.

What running it against real hosts found

Reading a REST API's documentation and calling it in anger are two
different exercises, and this is where the honest part of the story is.

Gitea was tested live on 1.26.4, in a throwaway repository deleted
after each run. Two behaviours needed handling that no amount of reading
would have surfaced: a repository with a single branch answers a pull
request listing with 404 rather than an empty list, and a merged pull
request's head can report a label naming a branch that no longer exists.
Handled once, both stay handled everywhere Gitea is the forge.

GitLab was tested live on gitlab.com, in a throwaway private project.
The first token given for it was fine-grained without quite enough scope,
and GitLab said so plainly (insufficient_granular_scope) rather than
failing silently. Once a token with the right scope was in place, the
first merge attempt was refused with a 422, "Branch cannot be merged" -
not because it could not be merged, but because GitLab had not yet finished
deciding whether it could. The forge now waits and asks again before
believing a 422. On both hosts, once that was in place, the full path ran
end to end with the real archive command: it found the finished change,
opened a pull request, watched it merge by itself, and the repository held
the archived change afterward, spec applied.

GitHub's own API was tested live too, on 2026-09-22, with gh's own
token handed to the process as GITHUB_TOKEN and gh itself kept off the
PATH - so there was no fallback to quietly catch a mistake. Against this
repository it read 147 pull requests and a real check run as a pass,
read-only. Against a fresh throwaway repository, the first automatic merge
was refused outright: "Auto merge is not allowed for this repository",
GitHub's own setting on a brand-new repo. The archive pass left the pull
request open and said why, exactly as the project's own rule requires
rather than pretending the merge had happened. Turning the setting on let
the same request merge by squash. A second pull request, opened to test
what the git stage's own gateway does with no checks configured at all,
correctly read "no check result was available" and declined to merge -
absence of information is not the same as a green light.

What this does not cover

GitHub Enterprise Server is not detected as its own case. A host that
answers neither Gitea's nor GitLab's version probe is assumed to be GitHub
and handled through gh, which already knows how to reach a GitHub host of
its own. The allowlist that gates what the git stage may push, create or
merge still speaks in gh's own terms - the remote and the branches it
names - regardless of which forge actually does the work underneath.

Try it

The code is at
github.com/VeryComplexAndLongName/OpenSpec-UI,
where the repository and packages keep the name OpenSpec-UI. The core this
rests on is described in
One core, two hosts.

Where each claim comes from

The Forge interface, the three implementations and how one is chosen: the archived changes the-forge-is-gitlab-or-gitea-too and github-without-gh.
The Gitea and GitLab live findings (the 404, the stale branch label, the scope error, the 422-until-decided): the-forge-is-gitlab-or-gitea-too's own tasks.md, task 3.2 and 3.3.
The GitHub API live findings (the 147 pull requests, the refused automatic merge, the "no check result" case): github-without-gh's own tasks.md, task 4.2.
Which forge, which token, and the exact reading when neither a token nor gh is available: HARNESS.md.
What this does not cover: github-without-gh's proposal, "Explicitly out of scope".

One core, two hosts

Alexander Ivanov — Thu, 24 Sep 2026 05:33:56 +0000

First published on openspec-ui.dev.

OpenSpec Workbench ships in two forms: a VS Code extension and a standalone
web application that runs on your machine. They show the same OpenSpec and Git
data and run the same workflows. The first architectural decision was how to
stop them from becoming two different products, because two deliveries of "the
same" behaviour diverge, and they do it quietly.

The answer was to write the behaviour once and let each host be a thin adapter
around it. This is what that looks like, what was turned down, and where "thin"
turned out to cost something.

The decision

Five packages, one of them holding all of the behaviour:

core owns execution, OpenSpec and Git integration, security, persistence and the derived state of a change.
webui holds the React components, written so they do not know how they are reached.
server and extension are the two hosts, and cli is a third, non-interactive one for CI.

The protocol began as five commands (plan, implement, review,
status and cancel) and seven events (started, stdout, stderr,
progress, completed, failed and cancelled), and it has grown since,
with events such as checkpoint and permissionRequest. It is defined in
core and nowhere else. A host serialises it and does not reimplement any of the
execution behind it.

Security is in the core too, from the start and not as a later addition. Every
run is restricted to the workspace, commands and their arguments are
allowlisted, executions are audited, and the contents of the repository are
treated as data, never as instructions.

What was rejected

Three alternatives were written down and refused.

Running the standalone server inside the extension. It would have made both
hosts share one transport, but the extension host already runs Node and needs no
HTTP for ordinary work. Dynamic ports, window collisions, authentication and
process clean-up would have burdened the most common workflow. So the extension
imports the core directly and talks to its webview over a message bridge, and
the local server stays an optional mode.

Implementing execution separately in each host. Streaming, cancellation,
errors and security would have drifted apart. Both hosts adapt the same
protocol instead.

Storing a change's state in .openspec.yaml. That would have extended a
format that belongs to OpenSpec. Draft, in progress, implemented and archived
are inferred from where a change sits and from its tasks.md, by a heuristic
in the core, so the tool never forks the format it depends on.

The delivery model was also reviewed independently after the first proposal,
and that review changed the recommendation for the extension's transport while
keeping the shared core.

What it bought

A defect is fixed once, in the core, which depends on neither HTTP nor the VS
Code API. The run status record that the Pipeline draws on a card is the same
record openspec-ui-cli status prints, whichever host started the run. A new
agent is one adapter in the core's registry, and both hosts see it.

One choice in that registry is worth naming. The plain agent adapters treat a
CLI's output as opaque text on purpose, so that a change in a CLI's output
format between versions cannot break the event stream. The price is that they
cannot see or gate a single action mid-run, which is what the adapters that
speak the Agent Client Protocol were added for, beside the plain ones and not in
place of them.

Where "thin" was not free

A thin adapter is still an adapter, and each host has to route each command.

When an agent asked for permission in the middle of a chain, the chain had no
way to receive the answer. The core routed cancel to the stage in flight but
not resolvePermission. The fix was in the core, and both hosts gained the matching branch. The run
did not fail. It waited.

So the rule is narrower than "hosts contain no logic". Hosts contain no
behaviour, but each of them still has to carry every command to the core, and a
command that one host forgets to carry is invisible until somebody uses it.
The project requires contract tests between the shared UI and the server before
a change is archived, for that reason.

Try it

The code is at
github.com/VeryComplexAndLongName/OpenSpec-UI,
where the repository and packages keep the name OpenSpec-UI. A short tour of
what it does is in
Supervise agents on OpenSpec changes.

Where each claim comes from

The layering, the protocol, the security model, the three rejected alternatives, the independent review and the consequences: the repository's ADR 0001.
The packages, the hosts and the direct import with a message bridge: the README's "Architecture at a Glance" and "Packages".
Plain adapters treating output as opaque text, and why ACP adapters were added beside them: ADR 0013.
The permission request that waited, and both hosts gaining the matching branch: the project's own write-up, What a run tells you: 0.40 to 0.44.
That the status record is the one openspec-ui-cli status prints: the README's "CI CLI" section.

Supervise the agents that build your OpenSpec changes

Alexander Ivanov — Thu, 24 Sep 2026 05:28:47 +0000

First published on openspec-ui.dev.

OpenSpec gives an agent something to build from: a proposal, a design, a list
of tasks, and the spec deltas the change will leave behind. What it does not
give you is a way to see the agent while it works.

Several tools draw OpenSpec changes as boards and lists, and they do it well.
Read on 2026-09-20 in their own words, none of the three I compared starts an
agent. OpenSpec Workbench does: it runs an agent CLI on a change, says what
the run is doing while it does it, and lets a person stop it. This is a short
tour of how, and of what it will not promise.

A change becomes a card

The Pipeline draws every active change in the order the changes declare, with
what a live run last said and what can start alongside what. A card is where
you act: it starts a run, answers a checkpoint, and asks a run to stop, with a
reason. The same Pipeline is in the standalone web application and in the VS
Code extension, and both read the same shared core.

A run is a chain of stages: propose, review, apply, verify, archive, git. You
choose the agent for each stage, and where the chain pauses for you.

What a run says it is doing

Every run writes a status record: whose it is, where it runs, what it last
said it was doing and how long ago. The Pipeline draws it on the card, and
openspec-ui-cli status prints it for every run of the repository, whichever
host started it.

It never says a run is stuck. A silent agent and a hung one look identical,
and telling them apart is a person's judgement, so the tool leaves that call
to you and gives you the last thing the run said and its age.

Changes can run side by side. Each one can have its own git worktree, guarded
by a lease, and openspec-ui-cli ready says which ready changes can start
alongside which, and why the others cannot.

Stop it where its work is sound

A card's Stop asks for a reason. The request is signed with the machine's key.
The run reads it at its next renewal and acts only if it is verified and
fresh, and it stops where its work is sound. From a terminal:

openspec-ui-cli stop <instanceId> --reason "wrong branch"

--after <task> lets the run finish a named task first and stops at the next
sound point after it.

Your agent, per stage

The picker drives the agent CLIs you already have: Claude CLI, GitHub Copilot
CLI, Codex CLI, Gemini CLI, DeepSeek CLI, and a local model behind an
OpenAI-compatible endpoint. The CLI-based ones also come in a variant that
speaks the Agent Client Protocol, which carries structured progress instead of
scraped text. The tool never handles an API key: each CLI keeps its own login.

Here is what has actually been run. Claude CLI and Copilot CLI have been run
against the real binaries, and so has DeepSeek CLI over ACP, on Node 22.18+ or
24.2+. Codex and Gemini never have, raw or over ACP: their adapters are
written to the vendors' documented interfaces and tested against a mocked
peer, and if either misbehaves for you, that is the likeliest reason and a
report would be useful. Two ACP caveats are worth knowing before you choose
one: the Claude adapter never asks for permission, and copilot --acp
completed file writes and shell commands here without asking either.

Checkpoints, ceilings and a record

Where a person decides is configuration, and the runner enforces it: an
autonomy level, checkpoints between stages, a review gate that only a change's
own settings can relax, and tasks marked as human-only or delegated to a named
agent. Each stage has its own spending cap in the unit its agent honours, each
chain has a ceiling, and every run lands in an audit log. The project also
states plainly which limits do not exist, in a document of their own.

The Workbench ships 17 change templates, for things like a Vite migration, a
production Dockerfile, an authentication middleware or a testing baseline, so
a new change can start from a proposal that already has the right shape.

Try it

In VS Code, install it from the Marketplace:

code --install-extension openspec-ui.openspec-ui-vscode

Or run the standalone application from a clone of the repository:

npm install
npm run build --workspace @openspec-ui/server
npm run start --workspace @openspec-ui/server -- <workspaceRoot> 4317

It prints a URL with a one-time token; open that exact URL. Everything runs on
your machine, against your own agent CLIs.

The repository, the packages and the extension are still called OpenSpec-UI;
the product's name is OpenSpec Workbench. The code and the issues are at
github.com/VeryComplexAndLongName/OpenSpec-UI,
and I would like to hear from anyone who tries it, above all from people who
run Codex or Gemini, which I have not been able to.

Where each claim comes from

The Pipeline, the stages, the status record, stop, and the other viewers compared on 2026-09-20: the repository's README, sections "How this differs from the other OpenSpec viewers", "Agentic Harness" and "CI CLI".
Which agents have been run against a real binary, and the ACP caveats: the README's "Agent Selection" section.
Checkpoints, autonomy levels and per-stage caps: HARNESS.md. What does and does not cap a run: LIMITS.md.
The 17 templates: packages/core/src/templates, 17 files.

A viewer is not a cockpit

Alexander Ivanov — Thu, 24 Sep 2026 05:28:47 +0000

First published on openspec-ui.dev.

Spec-driven development gives a coding agent a brief: a proposal, a design, a
list of tasks. There are already several good ways to read that brief. Boards,
dashboards and editor views show a change's documents and where it stands. I
read three of them on 2026-09-20, in their own words, and none of the three
starts an agent.

That is a fine thing for a viewer to be. But the moment an agent runs, the
questions change. Not "what does the change say?" but "what is it doing now,
what will it cost, and how do I stop it?" A viewer has no answer to those,
because it is not in the loop. A cockpit is.

I am building one, OpenSpec Workbench, and most of what I know about what a
cockpit needs I learned from it getting things wrong. Three of those mistakes
are worth writing down.

A run that hangs tells you less than one that fails

An agent asked for permission in the middle of a chain. The chain had no way to
answer. The request was routed to nobody, so the run did not fail and did not
time out. It waited, on a promise that nothing in the system could resolve.

The fix was to route the answer to the stage in flight, and, where a chain runs
fully autonomously with nobody to ask, to fail the stage with a stated reason
instead of waiting on a channel that does not exist. Failure is information.
Hanging is not.

A limit that cannot act reads as protection

A spending ceiling can be configured, saved, accepted by validation and never
fire. It counts only what an agent reports, and of the ten agents the tool
supports, six report no usage at all. Over those six a spending ceiling counts
nothing.

Two facts about ceilings are easy to assume away. A spending ceiling can stop
the next stage from starting, but it cannot interrupt the stage that is
already running, because a run's cost is not known until it ends. Only a time
ceiling can. And a run that fails may record nothing, so a ceiling protects you
from a long successful run, not from a sequence of expensive failures.

So the tool says which of a change's ceilings cannot act, where the
configuration is edited and before the run starts:

Silence is not a diagnosis

An agent that has said nothing for ten minutes might be thinking, or might be
hung. From outside the two look identical. A tool that draws a red "stuck"
badge is guessing, and a guess that looks like a measurement is worse than
none.

So the Workbench never says a run is stuck. It says what the run last said it
was doing, and how long ago. Telling a long turn from a hang is a person's
judgement, and the tool leaves it there.

What a cockpit has to do

Those three come down to four obligations.

Say what it will do before it does it. Which agent runs each stage, which setting it read, and which limits will not act.
Say what it is doing while it does it. The stage, the last thing said, how long ago.
Stop where the work is sound. A stop asks for a reason, is signed with the machine's key, and is honoured only if it is verified and fresh.
Say why it stopped. A run that hits a time ceiling ends as cancelled, with the reason naming the ceiling and its value, so a rule firing is not mistaken for a person's click, or for a failure.

None of that is about agents being smarter. It is about a tool being answerable
for what it is doing with your time and money.

What it still does not do

Claude CLI and Copilot CLI have been run against the real binaries. Codex and
Gemini never have: their adapters follow the vendors' documented interfaces and
are tested against a mocked peer, and a report from anyone who runs them would
be useful. Two ACP caveats: the Claude adapter never asks for permission, and
copilot --acp completed file writes and shell commands here without asking.

Try it

OpenSpec Workbench is a VS Code extension and a local web application, both over
the same core. There is a short tour of it in
Supervise the agents that build your OpenSpec changes.
The code and the issues are at
github.com/VeryComplexAndLongName/OpenSpec-UI,
where the repository and packages keep the name OpenSpec-UI.

Where each claim comes from

That none of three other OpenSpec interfaces starts an agent, read on 2026-09-20: the repository's README, "How this differs from the other OpenSpec viewers".
The permission request that waited, and routing the answer to the stage in flight: the project's own write-up, What a run tells you: 0.40 to 0.44.
Which ceilings can act, that six of the ten agents report no usage, that a spending ceiling cannot interrupt a running stage, that a failed run may record nothing, and that a time ceiling ends a run as cancelled with a reason: LIMITS.md, "At a glance", "timeout", and "Which agents report usage".
That a status never says "stuck", and that a stop is signed and needs a reason: the README's "CI CLI" section, status and stop.
Which agents have been run against a real binary, and the ACP caveats: the README's "Agent Selection" section.

A viewer is not a cockpit

Alexander Ivanov — Sun, 20 Sep 2026 15:49:05 +0000

First published on openspec-ui.dev.

Spec-driven development gives a coding agent a brief: a proposal, a design, a list of tasks. There are already several good ways to read that brief. Boards, dashboards and editor views show a change's documents and where it stands. I read three of them on 2026-09-20, in their own words, and none of the three starts an agent.

That is a fine thing for a viewer to be. But the moment an agent runs, the questions change. Not "what does the change say?" but "what is it doing now, what will it cost, and how do I stop it?" A viewer has no answer to those, because it is not in the loop. A cockpit is.

I am building one, OpenSpec Workbench, and most of what I know about what a cockpit needs I learned from it getting things wrong. Three of those mistakes are worth writing down.

A run that hangs tells you less than one that fails

An agent asked for permission in the middle of a chain. The chain had no way to answer. The request was routed to nobody, so the run did not fail and did not time out. It waited, on a promise that nothing in the system could resolve.

The fix was to route the answer to the stage in flight, and, where a chain runs fully autonomously with nobody to ask, to fail the stage with a stated reason instead of waiting on a channel that does not exist. Failure is information. Hanging is not.

A limit that cannot act reads as protection

A spending ceiling can be configured, saved, accepted by validation and never fire. It counts only what an agent reports, and of the ten agents the tool supports, six report no usage at all. Over those six a spending ceiling counts nothing.

Two facts about ceilings are easy to assume away. A spending ceiling can stop the next stage from starting, but it cannot interrupt the stage that is already running, because a run's cost is not known until it ends. Only a time ceiling can. And a run that fails may record nothing, so a ceiling protects you from a long successful run, not from a sequence of expensive failures.

So the tool says which of a change's ceilings cannot act, where the configuration is edited and before the run starts:

The run dialog for a change, with a section headed "What this configuration cannot do", listing the stages that can run without any bound

Silence is not a diagnosis

An agent that has said nothing for ten minutes might be thinking, or might be hung. From outside the two look identical. A tool that draws a red "stuck" badge is guessing, and a guess that looks like a measurement is worse than none.

So the Workbench never says a run is stuck. It says what the run last said it was doing, and how long ago. Telling a long turn from a hang is a person's judgement, and the tool leaves it there.

What a cockpit has to do

Those three come down to four obligations.

Say what it will do before it does it. Which agent runs each stage, which setting it read, and which limits will not act.
Say what it is doing while it does it. The stage, the last thing said, how long ago.
Stop where the work is sound. A stop asks for a reason, is signed with the machine's key, and is honoured only if it is verified and fresh.
Say why it stopped. A run that hits a time ceiling ends as cancelled, with the reason naming the ceiling and its value, so a rule firing is not mistaken for a person's click, or for a failure. None of that is about agents being smarter. It is about a tool being answerable for what it is doing with your time and money.

What it still does not do

Claude CLI and Copilot CLI have been run against the real binaries. Codex and Gemini never have: their adapters follow the vendors' documented interfaces and are tested against a mocked peer, and a report from anyone who runs them would be useful. Two ACP caveats: the Claude adapter never asks for permission, and copilot --acp completed file writes and shell commands here without asking.

Try it

OpenSpec Workbench is a VS Code extension and a local web application, both over the same core. There is a short tour of it in Supervise the agents that build your OpenSpec changes. The code and the issues are at github.com/VeryComplexAndLongName/OpenSpec-UI, where the repository and packages keep the name OpenSpec-UI.

Supervise the agents that build your OpenSpec changes

Alexander Ivanov — Sun, 20 Sep 2026 13:03:51 +0000

First published on openspec-ui.dev.*

A change becomes a card

A run is a chain of stages: propose, review, apply, verify, archive, git. You
choose the agent for each stage, and where the chain pauses for you.

What a run says it is doing

Changes can run side by side. Each one can have its own git worktree, guarded
by a lease, and openspec-ui-cli ready says which ready changes can start
alongside which, and why the others cannot.

Stop it where its work is sound

openspec-ui-cli stop <instanceId> --reason "wrong branch"

--after <task> lets the run finish a named task first and stops at the next
sound point after it.

Your agent, per stage

The picker drives the agent CLIs you already have: Claude CLI, GitHub Copilot
CLI, Codex CLI, Gemini CLI, and a local model behind an OpenAI-compatible
endpoint. The CLI-based ones also come in a variant that speaks the Agent
Client Protocol, which carries structured progress instead of scraped text.
The tool never handles an API key: each CLI keeps its own login.

Here is what has actually been run. Claude CLI and Copilot CLI have been run
against the real binaries. Codex and Gemini never have, raw or over ACP: their
adapters are written to the vendors' documented interfaces and tested against
a mocked peer, and if either misbehaves for you, that is the likeliest reason
and a report would be useful. Two ACP caveats are worth knowing before you
choose one: the Claude adapter never asks for permission, and copilot --acp
completed file writes and shell commands here without asking either.

Checkpoints, ceilings and a record

Try it

In VS Code, install it from the Marketplace:

code --install-extension openspec-ui.openspec-ui-vscode

Or run the standalone application from a clone of the repository:

npm install
npm run build --workspace @openspec-ui/server
npm run start --workspace @openspec-ui/server -- <workspaceRoot> 4317

It prints a URL with a one-time token; open that exact URL. Everything runs on
your machine, against your own agent CLIs.

Where each claim comes from

The Pipeline, the stages, the status record, stop, and the other viewers compared on 2026-09-20: the repository's README, sections "How this differs from the other OpenSpec viewers", "Agentic Harness" and "CI CLI".
Which agents have been run against a real binary, and the ACP caveats: the README's "Agent Selection" section.
Checkpoints, autonomy levels and per-stage caps: HARNESS.md. What does and does not cap a run: LIMITS.md.
The 17 templates: packages/core/src/templates, 17 files.

openspec, #ai, #vscode, #opensource

OpenSpec-UI: A Visual Workspace for Spec-Driven AI Development

Alexander Ivanov — Tue, 18 Aug 2026 12:41:17 +0000

AI coding agents are getting very good at writing code.

The harder problem is increasingly controlling what they are supposed to build.

When a project uses specification-driven development, the workflow is no longer just:

Prompt → AI → Code

It becomes something closer to:

Specification ↓ Change proposal ↓ Design ↓ Tasks ↓ AI coding agent ↓ Implementation ↓ Validation ↓ Archive

This workflow works well from the command line, but as the number of changes, specifications, agents, and repositories grows, a CLI-only interface can become difficult to navigate.

That's the problem I wanted to solve with OpenSpec-UI.

What is OpenSpec-UI?

OpenSpec-UI is an open-source visual workspace for OpenSpec.

It provides a graphical way to work with:

Changes
Proposals
Designs
Specs
Tasks
Archived changes
Templates
Repository setup
Validation workflows

It also provides an interface for launching AI coding agents directly from the same workspace.

The project currently supports:

Claude CLI
GitHub Copilot CLI
Codex CLI
Gemini CLI
local LLMs through an OpenAI-compatible API

The important part is that OpenSpec-UI is not intended to replace OpenSpec.

It is a workspace around it.

Why build another UI?

OpenSpec already provides openspec view, which is useful for browsing specifications and changes.

So why build another interface?

There are several practical reasons.

1. Working with archived changes

One useful addition is the ability to inspect differences between versions of archived changes.

When a project has accumulated many changes, simply browsing the current state is not always enough. Sometimes you want to understand how a particular proposal evolved.

2. AI agents become part of the workflow

An increasingly common development workflow looks like this:

Create specification
        ↓
Review specification
        ↓
Create implementation tasks
        ↓
Start AI coding agent
        ↓
Agent modifies repository
        ↓
Run validation
        ↓
Review result

If the specification management tool and the coding agent are separate applications, developers constantly switch between terminals, editors and browser windows.

OpenSpec-UI puts these operations closer together.

3. VS Code integration

Many developers already spend most of their working day inside VS Code.

For that reason, OpenSpec-UI has two delivery modes:

                   OpenSpec-UI
                       │
            ┌──────────┴──────────┐
            │                     │
      VS Code extension      Standalone Web UI
            │                     │
       native workbench       local browser

Both use the same underlying core.

The VS Code extension provides native integration with the editor, while the standalone application is useful when a separate local web interface is preferable.

One core, two interfaces

One architectural decision was particularly important: the business logic should not be duplicated between the Web UI and the VS Code extension.

The repository is organized as a TypeScript monorepo with shared packages.

At a high level:

                    OpenSpec / Git / CLI Agents
                              │
                              ▼
                       ┌─────────────┐
                       │    Core     │
                       │             │
                       │ OpenSpec    │
                       │ parser      │
                       │ Git         │
                       │ security    │
                       │ execution   │
                       │ agents      │
                       └──────┬──────┘
                              │
                 ┌────────────┴────────────┐
                 │                         │
                 ▼                         ▼
             REST / WS                Direct import
                 │                         │
                 ▼                         ▼
          Standalone Web UI          VS Code Extension

The repository currently separates responsibilities into packages such as:

core — execution engine, OpenSpec parsing, Git integration, agent orchestration and security
server — REST/WebSocket layer for the standalone application
webui — shared React UI
extension — VS Code integration
cli — non-interactive CLI functionality for CI workflows

This allows the UI to remain relatively independent from the transport mechanism.

Running everything locally

Another design goal is that OpenSpec-UI should work as a local developer tool.

The standalone application runs locally and operates on the local repository.

The VS Code extension also works without requiring a remote OpenSpec-UI service.

A typical standalone setup is currently as simple as:

npm install
npm run build --workspace @openspec-ui/server
npm run start --workspace @openspec-ui/server -- <workspaceRoot> 4317

The server exposes a localhost URL containing a temporary access token.

This is useful for workflows where source code and specifications should remain on the developer's machine.

AI agents as an execution layer

One of the interesting parts of the project is the agent integration.

Instead of treating an AI coding agent as a completely separate tool, OpenSpec-UI treats it as an execution component of the specification workflow.

Conceptually:

OpenSpec Change
      │
      ├── Proposal
      ├── Design
      ├── Spec
      └── Tasks
             │
             ▼
       Agent Launcher
             │
      ┌──────┼──────┬──────┐
      ▼      ▼      ▼      ▼
   Claude  Copilot Codex  Gemini

This is deliberately designed around a command/event protocol rather than tightly coupling the application to one particular AI provider.

That makes it possible to use different agents for different tasks.

For example, a developer might use one agent for implementation and another for review.

What about local LLMs?

The project also supports a local LLM through an OpenAI-compatible API.

That means the execution layer does not have to be limited to hosted AI services.

This can be particularly useful for development environments where source code cannot be sent to external services or where developers already operate their own inference infrastructure.

The goal is not to build another LLM runtime.

The goal is to make the model or agent available as one of the execution options in the development workflow.

A specification-first workflow

The larger idea behind OpenSpec-UI is that AI coding does not have to start with a prompt.

A more structured workflow can be:

                    Human
                      │
                      ▼
              Define the change
                      │
                      ▼
                 OpenSpec
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
       Proposal      Design      Tasks
          │           │           │
          └───────────┼───────────┘
                      ▼
                  AI Agent
                      │
                      ▼
                  Codebase
                      │
                      ▼
                  Validation
                      │
                      ▼
                   Archive

The human remains responsible for defining and reviewing the intended change.

The AI agent becomes an implementation tool operating within that context.

This distinction becomes increasingly important as coding agents become more autonomous.

Why not just use an AI coding IDE?

Tools such as AI-enabled IDEs are very good at generating and modifying code.

But specification management is a slightly different problem.

An IDE answers questions such as:

What code should I edit?

A specification workflow also needs to answer:

What are we changing?

Why are we changing it?

What requirements does the change introduce?

What tasks are required?

What was changed previously?

What is the canonical specification?

These are different layers of the development process.

OpenSpec-UI is intended to sit between the specification layer and the coding-agent layer.

The project is still evolving

OpenSpec-UI is actively developed.

The current implementation already contains:

standalone Web UI
VS Code extension
shared execution core
OpenSpec integration
Git integration
AI agent orchestration
archived change management
Specs and Tasks views
templates
repository setup tools
CLI functionality
local execution

But the project is intentionally still evolving.

One of the reasons for publishing it publicly is to get feedback from developers who are experimenting with specification-driven development and AI coding agents.

There are still many questions worth exploring:

How should agents and specifications interact?
What should an AI-native development workbench look like?
How much autonomy should an agent have?
How should changes be reviewed before execution?
How should multiple agents cooperate?
What is the right UI for long-running agent workflows?

These are not completely solved problems yet.

Try it

The project is open source:

GitHub: https://github.com/VeryComplexAndLongName/OpenSpec-UI

If you are experimenting with OpenSpec, AI coding agents, or specification-driven development, I'd be interested in your feedback.

In particular, I'm interested in whether a visual workspace makes specification-driven AI development easier to manage than a CLI-only workflow.

Final thought

AI coding agents are rapidly improving at implementation.

That makes the specification and orchestration layer increasingly important.

The future workflow may not simply be:

Human → AI → Code

It may look more like:

Human
  ↓
Specification
  ↓
Change
  ↓
Agent
  ↓
Implementation
  ↓
Validation
  ↓
Human review

OpenSpec-UI is an experiment in building the workspace around that workflow.

The code is open, the architecture is visible, and contributions and feedback are welcome.

I Built a Python Prompt Orchestrator for Structured LLM Pipelines

Alexander Ivanov — Fri, 29 May 2026 04:00:51 +0000

Most LLM applications eventually hit the same problem:

prompts become unmanageable.

At first, everything fits into a single string.

Then you add:

summaries
RAG
memory
safety checks
token budgets
conversation compaction
provider switching

And suddenly your prompt pipeline becomes harder to maintain than the model itself.

So I built prompt_orchestrator.

What is it?

prompt_orchestrator is a Python module for structured prompt orchestration with:

static/semi-stable/dynamic prompt layout
configurable summarization providers
optional RAG integration
safety heuristics
token budgeting
centralized configuration
prompt efficiency analysis

The goal was simple:

Make prompt pipelines deterministic, modular, and production-friendly.

Structured prompt sections

The orchestrator separates prompts into:

static parts
semi-stable parts
dynamic conversation context

This improves:

cacheability
token efficiency
prompt readability
debugging

Works with or without RAG

The module supports optional RAG providers.

It integrates directly with rag_orchestrator and compatible retrieval systems.

One particularly useful detail:

Both projects share a compatible DocChunk structure.

This makes integration extremely simple.

Safety checks included

The project includes lightweight safety heuristics for:

injection detection
contradiction checks

without requiring a separate moderation service.

Summary providers

Supported summary backends:

OpenAI
Ollama
deterministic local fallback
custom providers

So the orchestration layer is not tied to a single vendor.

Token-aware orchestration

The orchestrator includes:

token counting via tiktoken
automatic trimming
prompt fitting
configurable token budgets

which becomes critical for long-running conversations.

Designed for integration

The module was intentionally designed to integrate into existing systems.

It does not force:

a framework
an agent runtime
a specific LLM provider
a database stack

Tests and simulations

The repository already includes:

interactive simulations
safety simulations
conversation replay tests
console pipelines

which makes experimentation easy.

Installation

pip install -e .

Final thoughts

A lot of current LLM tooling focuses on:

agents
autonomous loops
framework ecosystems

But prompt orchestration itself is still an unsolved infrastructure problem.

This project focuses specifically on making that layer cleaner and easier to reason about.

I Built a Lightweight Python RAG Flow Orchestrator That Works with SQLite, PGVector and Qdrant

Alexander Ivanov — Thu, 28 May 2026 16:28:50 +0000

Most RAG frameworks today assume:

a huge dependency graph
mandatory LLM orchestration
opinionated pipelines
complex configuration

But many real-world systems need something simpler.

Especially when:

you already have an existing pipeline
you want local/offline execution
you need predictable retrieval
you do not want every step delegated to an LLM

So I built rag-orchestrator.

What makes it different?

The project was designed around one key idea:

RAG infrastructure should be modular, lightweight, and database-agnostic.

Works with multiple vector databases

The orchestrator supports:

SQLite
PGVector
Qdrant

through an abstract storage layer.

This means you can switch backends without rebuilding the whole pipeline.

Fully pluggable architecture

The project provides abstraction layers for:

Embeddings
Retrievers
Cleaners
Vector stores
Processing steps

You can easily plug in:

your own embedding provider
your own retriever
custom preprocessing logic
external pipelines

without rewriting internal logic.

Minimal LLM usage

One important design decision:

The orchestrator works without an LLM for almost the entire pipeline.

LLMs are only required at a single step where they actually add value.

This makes the system:

cheaper
faster
more deterministic
easier to debug

Minimal configuration

The module intentionally requires very few input parameters.

The goal was:

fast onboarding
simple integration
production-friendly defaults

Tested and production-oriented

The repository already includes:

integration tests
runnable scripts
usage examples

You can inspect them directly in the scripts/ directory.

Easy integration into existing systems

The project was built to integrate into:

existing RAG pipelines
enterprise systems
AI backends
local AI stacks
internal search systems

instead of forcing users into a completely new ecosystem.

Installation

```bash id="1b38r0"
pip install rag-orchestrator




## Why this matters

A lot of modern RAG tooling is becoming increasingly framework-heavy.

But many production systems actually need:

* predictability
* portability
* low overhead
* composability

rather than autonomous agent complexity.

This project focuses exactly on that.

PromptMan: REST API-First Prompt Registry for Real LLM Infrastructure

Alexander Ivanov — Wed, 20 May 2026 02:54:27 +0000

Large Language Models changed the way modern systems are built.
Prompts are no longer “just text” — they have become infrastructure:

behavioral contracts for LLMs,
reusable business logic,
configuration artifacts,
optimization targets,
security-sensitive assets.

As soon as teams start iterating on prompts, they immediately encounter classic infrastructure problems:

How should prompts be versioned?
How do multiple services share them?
How can teams enforce RBAC?
How are prompts audited?
How do you scale prompt access under concurrent load?
How do you keep prompts fully on-premise?

This is why prompt registries are becoming a separate software category.

For engineering teams, especially backend-focused teams, the ideal solution usually includes:

REST API access,
RBAC,
immutable version history,
tagging and search,
authentication,
automation support,
horizontal scalability,
cloud and on-premise deployment,
and no SaaS dependency.

Below is an updated overview of the current ecosystem.

Existing Solutions
PromptHub

Cloud prompt manager with UI collaboration, prompt versioning, evaluations, and experimentation tools.

REST API: Yes
RBAC: Partial
On-Premise: No
Scaling: SaaS
License: Freemium
PromptLayer

Focused mainly on LLM observability, request logging, analytics, and tracing.

REST API: Yes
RBAC: Limited
On-Premise: No
Scaling: SaaS
License: Freemium
LangSmith

LLM tracing, monitoring, evaluation, and debugging platform from LangChain.

REST API: Yes
RBAC: Partial
On-Premise: Enterprise only
Scaling: SaaS
License: Freemium
Promptfoo

Open-source framework focused on prompt testing, evaluation, regression analysis, and CI/CD workflows.

REST API: Partial
RBAC: No
On-Premise: Yes
Scaling: CI/CD
License: Free
Flowise

Visual low-code builder for LLM pipelines and AI workflows.

REST API: Yes
RBAC: Limited
On-Premise: Yes
Scaling: Docker/Kubernetes
License: Free / Enterprise
PromptPerfect

Automatic prompt optimization platform focused on prompt rewriting and quality improvements.

REST API: Yes
RBAC: No
On-Premise: No
Scaling: SaaS
License: Paid
Notion

General-purpose knowledge management platform sometimes used as ad-hoc prompt storage.

REST API: Yes
RBAC: Limited
On-Premise: No
Scaling: SaaS
License: Freemium
Obsidian

Local Markdown-based knowledge system frequently used for personal prompt collections.

REST API: No
RBAC: No
On-Premise: Yes (local)
Scaling: Git/local filesystem
License: Free
Dendron

VSCode-centered hierarchical note system.

REST API: No
RBAC: No
On-Premise: Yes (local)
Scaling: Git/local filesystem
License: Free
PromptMan

PromptMan takes a very different architectural approach compared to most tools in this space.

It is designed primarily as a REST API-first prompt registry rather than a SaaS UI product.

The HTTP API is the main integration surface.
The UI intentionally acts as a lightweight companion client over the same API.

This makes PromptMan closer to infrastructure software than to a browser-oriented prompt workspace.

Core Architecture

PromptMan provides:

REST API-first architecture
Immutable prompt versioning
Prompt storage by project + name
Structured prompt fields:
role
task
context
constraints
output format
examples
RBAC with:
admin
developer
viewer
Authentication for both API and UI
Access + refresh token sessions
Per-project access control
Audit metadata:
created_by
updated_by
timestamps
Prompt tagging and AND/OR search
Pagination and server-side sorting
Automatic DB migrations
Semantic versioning
Runtime version endpoint
Sensitive configuration encryption
Bootstrap admin initialization
Optimization Features

PromptMan also includes built-in prompt optimization workflows.

Features include:

Optimization profiles:
fast
quality
ultra
Multiple provider support:
Ollama
OpenAI-compatible APIs
Anthropic
Gemini
Groq
Mistral
Dynamic model discovery
Per-user optimization configuration
Heuristic fallback optimizer
Leo optimizer backend integration

Unlike many SaaS products, PromptMan supports fully local optimization flows using Ollama.

Plugin System (EPS)

One of the largest additions since earlier versions is the extensible plugin system.

PromptMan now supports:

Dynamic plugin loading
Hot plugin reload
Runtime plugin isolation
Detached plugin signatures
Trusted signer validation
Modal plugin sessions
Plugin hooks
Endpoint injection
UI control rendering
Plugin RBAC
Plugin health monitoring

Plugins can expose their own REST endpoints automatically:

/v1/plugins//

The platform also supports signed plugins through detached signature sidecars and trusted signer registries.

This makes PromptMan extensible without modifying the core application.

Prompt Efficiency Analyzer

PromptMan now includes a built-in Prompt Efficiency Analyzer plugin.

The analyzer:

works fully locally,
requires no external LLM calls,
evaluates prompt stability,
analyzes predictability,
measures cache friendliness,
estimates prompt efficiency characteristics.

This is particularly useful for teams trying to optimize prompt cost and cache reuse patterns in production systems.

Scalability And Infrastructure

PromptMan was designed with backend deployment patterns in mind.

Supported databases:

SQLite
PostgreSQL
MySQL/MariaDB (via SQLAlchemy)
Deployment Modes
Local single-node deployment
Docker deployment
Kubernetes deployment
Horizontally scaled multi-instance deployment
Horizontal Scaling

The architecture is stateless.

Multiple PromptMan instances can run behind a load balancer while sharing PostgreSQL as the central state store.

The repository also contains:

Locust-based load testing harness,
benchmark charts,
concurrency validation,
cache performance measurements,
race-condition tests.
Measured Performance

PromptMan includes real benchmark results in the repository.

Highlights from current measurements:

Cache-heavy workloads scale linearly under concurrent load.
Hot optimization paths sustain high throughput with zero failures.
PostgreSQL sync mode showed the best balanced production characteristics.
SQLite remains highly competitive for small local teams.
Cache reuse produced ~100× throughput improvement compared to cold optimization paths.

This is unusually infrastructure-focused for a prompt management tool.

Security Model

PromptMan emphasizes self-hosted security controls:

100% on-premise capable
Encrypted password hashes
Encrypted API tokens
RBAC enforcement
Signed plugin validation
Refresh token isolation
Authentication for both API and UI

Prompts never need to leave internal infrastructure.

Docker Images

Official container images are available via:

Docker Hub
GitHub Container Registry
Comparison Table
Tool,REST API,RBAC,On-Premise,Scaling,License
PromptHub,Yes,Partial,No,SaaS,Freemium
PromptLayer,Yes,Limited,No,SaaS,Freemium
LangSmith,Yes,Partial,Enterprise,SaaS,Freemium
Promptfoo,Partial,No,Yes,CI/CD,Free
Flowise,Yes,Limited,Yes,Docker/K8s,Free/Enterprise
PromptPerfect,Yes,No,No,SaaS,Paid
Notion,Yes,Limited,No,SaaS,Freemium
Obsidian,No,No,Yes,Git/local,Free
Dendron,No,No,Yes,Git/local,Free
PromptMan,Yes,Yes,Yes,Horizontal,Free
Why PromptMan Stands Out

Most prompt tools today optimize for:

browser collaboration,
prompt experimentation,
analytics dashboards,
SaaS workflows.

PromptMan instead optimizes for:

backend integration,
API semantics,
concurrent multi-user access,
infrastructure deployment,
self-hosting,
operational predictability.

That makes it particularly attractive for:

backend-heavy teams,
internal AI platforms,
regulated environments,
private deployments,
multi-service architectures,
CI/CD-driven prompt workflows.

In practice, PromptMan behaves less like a “prompt editor” and more like infrastructure software for LLM systems.

A useful analogy is:

PromptMan is closer to “PostgreSQL for prompts” than to a collaborative SaaS workspace.

For teams that need a local, secure, horizontally scalable, API-driven prompt registry with real engineering semantics, PromptMan is currently one of the most infrastructure-oriented open-source solutions available.