DEV Community: Alexander Ivanov

A compliance monitor that does not busywork

Alexander Ivanov — Thu, 15 Oct 2026 04:25:40 +0000

OpenSpec Workbench initializes repositories and runs agents on changes. It
did not, until now, check that its own runtime files are ignored, or that
its repository rules are consistent. A compliance monitor has been added to
the shared core, and it does three things that matter: it keeps a versioned
catalogue of rules, it runs only when the host reports idle, and it reports
findings without moving or deleting anything.

The catalogue, versioned and evidence-linked

Every rule in the catalogue carries a stable identifier, a description of
what it checks, and metadata about the check's cost and whether it supports
automatic repair. Each finding is linked back to the rule that produced it
and to the evidence that triggered it, so you can trace a finding to the
exact check and the exact file or state that caused it.

The catalogue is versioned. When a rule changes, the new version is applied
to future checks, and old findings remain linked to the version that
produced them. This matters when a rule's threshold is tightened or
relaxed: old findings do not retroactively become violations or pass.

What it checks, on initialization

On explicit repository initialization, the monitor verifies that Workbench
runtime state is ignored by Git. It adds only the missing managed ignore
rule, preserving the rest of .gitignore exactly as you wrote it. Nothing
is overwritten.

It also checks Workbench runtime files in the main checkout and in
worktrees. It identifies untracked or visible state and explains the
expected root for each state kind without moving or deleting it. A run
journal in .openspec-ui/ is expected to be untracked; a lease file in the
main checkout is expected to be ignored. The monitor says which is which,
and why.

Grouping, deduplication and shadow detection

When the same change id appears in multiple worktrees, the monitor groups
them as one logical change and reports the count. It flags a change id
present in both active and archive trees, an archived change left in a
stale worktree, or a shadow copy in main beside its owning worktree. The
Pipeline card count is reconciled with the Changes list, and active changes
missing from the OpenSpec README index are flagged with a suggested link,
not an automatic edit.

Per-rule reactions and a periodic schedule

Each rule accepts one of three response settings: autorepair, advice
or none. autorepair applies a fix without asking; advice produces a
finding with a suggested action; none records the finding silently. A
global periodic-monitor switch enables or disables the entire schedule.

The monitor runs one bounded batch only after the host reports idle and no
mutating Workbench run is active. It measures each check's elapsed time,
schedules by due date and conservative cost, and spreads expensive checks
across later idle windows. Nothing runs as a separate OS daemon.

Process ledger and orphan detection

A companion capability, the process ledger, records a synchronous snapshot
for every process spawned by Workbench: PID, OS start time, executable,
hostname, cwd, change, and a secret-free command-line hash. Records are
marked exited on normal close and kept durable across host restarts, keyed
by canonical repository identity and hostname.

Before any kill, the snapshot is re-verified against the operating system.
Orphaned and overdue processes are surfaced as read-only Compliance
findings. An explicit, confirmable kill lives in the existing recovery
surface, never in Compliance itself. The two capabilities share the same
catalogue but never cross their boundaries: Compliance explains, recovery
acts.

What this deliberately does not do

The monitor does not start a background daemon, does not modify source code,
does not run on every file change, and does not replace a linter or a
formatter. It checks Workbench's own runtime hygiene and the consistency of
its repository state.

Try it

The code is at
github.com/VeryComplexAndLongName/OpenSpec-UI,
where the repository and packages keep the name OpenSpec-UI.

openspec-ui-cli compliance check --cwd .

Pay for the plan, not the typing

Alexander Ivanov — Sun, 11 Oct 2026 05:35:43 +0000

First published on openspec-ui.dev.

stepAgents has let you name a different agent for propose, review, apply
and verify since 0.42. What is new is a reason to actually do it: the four
stages do not cost the same thing to run well, and they do not need to.

Deciding what a change should do and reading whether the result is right both
call for judgement. Writing the diff that gets there is comparatively
mechanical - which is not an insult to the work, it is why a cheap, fast model
does it about as well as an expensive one. So the obvious split is: a capable
agent on propose and review, and a cheap one on apply. This is that
split, what it costs at today's prices, and - the part worth reading past the
headline number - exactly what this project's own telemetry can and cannot
prove about the savings.

The four stages take different things seriously

A harness.json entry accepts agent, model, effort, budget and
customAgent - and only propose, review, apply and verify accept a
stepAgents entry at all; archive and git are mechanical, with nothing to
configure. A model is only accepted for the four adapters whose registry
entry declares a --model flag: claude-cli, copilot-cli, claude-cli-acp
and copilot-cli-acp. budget is maxCostUsd or maxAiCredits, whichever
unit the chosen agent's own capabilities accept - the other is rejected.

{
  "stepAgents": {
    "propose": { "agent": "claude-cli-acp", "model": "claude-opus-5-5", "effort": "high", "budget": { "maxCostUsd": 5 } },
    "review":  { "agent": "claude-cli-acp", "model": "claude-opus-5-5", "effort": "high", "budget": { "maxCostUsd": 3 } },
    "apply":   { "agent": "deepseek-cli-acp" },
    "verify":  { "agent": "copilot-cli-acp", "effort": "medium", "budget": { "maxAiCredits": 200 } }
  },
  "timeout": { "maxStageSeconds": 2700 }
}

propose and review above pin claude-opus-5-5 at high effort, with a
dollar ceiling each. claude-fable-5-1 is the other reasonable choice for
either - cheaper per token, still a model built for judgement rather than
throughput; which of the two is worth its price on your own changes is
something to measure, not assume. apply carries no model, no effort and
no budget at all, and that is not an oversight: deepseek-cli-acp accepts
none of the three. Its model is a session option this project's driver never
sends, so DeepSeek's own default runs; nothing here can raise or lower how
hard it thinks.

What the harness can prove, and what it flatly cannot see

This is the part a "save money" article usually skips, and it is the most
useful thing this one has to say.

Two of the three agents in this split convert cleanly to a ceiling you can
actually set. claude-cli-acp reports a cost figure directly - measured in
this repository on 2026-09-05, one stage: 60 input, 8,262 output and
1,693,507 cache tokens for $1.57, and budget.maxCostUsd compares
against exactly that number. copilot-cli-acp reports no dollar figure, but
it reports AI Credits, which are not a proxy this project invented - they
are the unit Copilot itself bills in, 1 credit = $0.01 - so
budget.maxAiCredits is a real ceiling in real money, just denominated
differently. Two agents, two currencies, both enforceable.

deepseek-cli-acp is the one genuine blind spot. Measured 2026-09-23, its
one usage figure is a context gauge - tokens used against the model's
window - never a cost, a credit count or even a token split. budget has no
mechanism to set on it, in either unit, because there is nothing to compare
a ceiling against.

So the honest description of the harness.json above is: three of the four
stages carry a leash denominated in real money - two in dollars, one in AI
Credits - and the cheap one does not. timeout.maxStageSeconds still bounds
how long apply can run, because elapsed time needs no report from the
agent - but nothing in this product will tell you, or stop you, if a
deepseek-cli-acp stage is burning through a prepaid balance faster than
expected. That balance lives entirely on DeepSeek's side. Watch it there.

Two more limits worth knowing before you lean on the cheap stage. Neither
copilot --acp nor dsh (DeepSeek's CLI) asks for permission before writing
a file or running a command, despite the Agent Client Protocol supporting the
mechanism - both were observed completing writes and shell commands here
without ever raising session/request_permission. Cheaper is not the same as
better-supervised; the review gate between apply and verify is what is
actually watching this stage, not the permission channel. And dsh needs
Node 22.18+ on the 22 line, or 24.2+ - below that floor it exits with code 0
before answering, silently. If your repository pins an older Node for its own
tooling the way this one pins 22.11 with Volta, that is the first place to
look when an apply stage using DeepSeek produces nothing.

What this costs, at today's prices

These are vendor list prices, read 2026-09-24, not a figure this project
measured. Nothing here converts one into the other, and the harness has no
opinion about which subscription you carry - that lives entirely outside it,
in each CLI's own login.

Setup	Monthly	Runs
Claude Max 5x alone	$100	every stage on `claude-cli`/`claude-cli-acp`
Claude Pro + Copilot Pro + DeepSeek API credit	$20 + $10 + about $5 in tokens ≈ $35	`propose`/`review` on Claude, `apply` on DeepSeek, `verify` on Copilot

Claude Pro is $20/month billed monthly, $17 annually; Claude Max starts at
$100/month for the 5x tier. Copilot Pro is $10/month, including $10 of AI
Credits at 1 credit = $0.01 - which is also where budget.maxAiCredits's
minimum of 30 comes from: thirty cents is the smallest ceiling the product
will accept, because Copilot itself will not meter anything finer. DeepSeek
has no subscription tier at all: deepseek-flash (what this project's own
measurement on 2026-09-22 recorded as DeepSeek-V4-Flash - names move
faster than documentation; check what dsh reports before you trust either)
prices output at $0.60 per million tokens off-peak, $1.20 during DeepSeek's
own weekday peak windows. Five dollars of prepaid credit is, at off-peak
rates, upward of eight million output tokens - many multiples of what one
apply stage moves by the only measurement available here (1.7 million
tokens, all kinds, on a claude-cli-acp stage). Read that as "a lot", not as
a number of stages: different models tokenize and work differently, and this
project has no apply-stage measurement on DeepSeek to compare it against
directly.

The arithmetic says $65 a month, and it survives the correction: GitHub's own
current price for Copilot Pro is $10, not the $20 an older plan once charged,
and the saving lands in the same place regardless, because the difference
comes out of the Claude Max to Claude Pro step either way.

What this article is not

Not a benchmark. Nothing here measured whether deepseek-cli-acp produces
work as good as claude-cli-acp on the same apply stage - that is a
real, answerable question, and it is not this one. Not a recommendation for
your specific changes: an architecture decision or a security-sensitive
apply stage may be exactly the case where the expensive agent belongs on
every stage, ceilings included. And not a claim that Codex or Gemini would
be a worse or better third leg of this - both remain agents this project has
never run against a real binary, on any stage.

Try it

The full field reference for stepAgents, model, effort and budget is
in HARNESS.md.
Which agents report what, in which unit, is in
LIMITS.md.
The code is at
github.com/VeryComplexAndLongName/OpenSpec-UI,
where the repository and packages keep the name OpenSpec-UI.

Where each claim comes from

stepAgents, its four fields, which stages accept it, and which agents accept a model: HARNESS.md, "stepAgents".
The agent capability table (model, effort, spending-cap unit, run against a real binary): HARNESS.md, "Agents, models, effort, and spending caps".
Which agents report usage, in which unit, and the $1.57 and 1,701,829-token measurements: LIMITS.md, "Which agents report usage".
deepseek-cli-acp's context gauge, its measurement date, and that it reports no cost, no credits and no token split: LIMITS.md, the same section, and the archived change a-run-can-outgrow-its-context.
Neither copilot --acp nor dsh asking for permission, and the Node 22.18+/24.2+ floor: HARNESS.md, "ACP effort and budget capabilities", and the article A new agent, and nothing else moved.
Claude Pro and Max prices: claude.com/pricing, read 2026-09-24.
Copilot Pro's price and its AI Credits: GitHub's own announcement, read 2026-09-24.
DeepSeek's per-token prices and peak windows: DeepSeek's own pricing page, read 2026-09-24.

Two things nobody was watching

Alexander Ivanov — Tue, 06 Oct 2026 02:34:25 +0000

First published on openspec-ui.dev.

OpenSpec Workbench's whole pitch is watching an agent while it works. Two
small fixes this week are about the product not watching itself closely
enough - one where cleanup quietly stopped, one where a number was arriving
the whole time and nothing was reading it.

The leftover that survived being asked twice

A working directory is removed in two steps: git forgets it, then whatever
git left is deleted. Where the second step meets a file a live process
still has open, the deletion fails, something is left behind, and nobody
ever looks again - every later pass walks the directories git lists, and
git has already forgotten this one.

That is not a hypothetical. A shell from an already-archived change,
a-change-knows-its-stage, sat under the worktree root from one day to the
next: 54 megabytes, holding nothing but a downloaded copy of VS Code under
packages/extension/.vscode-test, which the extension's own test run had
been holding open at the exact moment something tried to remove it. Asked
again a day later, it went without complaint - one retry was all it ever
needed.

Two things had kept that retry from happening. The rule for "is this ours
to delete" was emptiness: a shell holding no file at any depth was cleared,
and anything else was left alone, on the reasoning that a directory with a
file in it belongs to someone. But a half-finished removal leaves exactly
the opposite - the files that could not be deleted are the ones still
there, so the rule excused the one case it existed for. And almost nothing
called the cleanup in the first place: it ran from a button in the
standalone app, and the periodic sweep that both hosts already run for
everything else never called it at all.

The fix changes what "ours" means: a shell named after a change this
repository knows, with no .git of its own, is cleared whatever is inside
it - what is in a directory says nothing about whose it is; its name and
the absence of a checkout do. The periodic sweep now clears these itself,
on every pass, and says what it removed and what it is still waiting on. A
shell it cannot clear yet is asked again next time, not forgotten.

Checked live against the real worktree root this repository uses: 320
known change names, two live working directories, one shell from an
archived change planted holding a file under .vscode-test. Read correctly
as not empty and ours, removed, with neither live working directory
touched.

The number that was arriving the whole time

DeepSeek's CLI reports no cost, no credits, no token split - the answer to
"how do we put a spending ceiling on it" turned out to be "you can't; only
a time limit binds it at all." But it does send one figure over the Agent
Client Protocol: usage_update, carrying how many of the model's window
tokens the session is using right now. That figure was already arriving.
Nothing was reading it.

It is a strange number to build a ceiling on, and the reasoning for
leaving it alone still holds: it falls after a compaction, so counting it
as spend would under-count exactly the long runs that compact. But it
says something a spending figure never could, and says it while a stage is
still running rather than after: a session that has filled most of its
window makes every further turn carry the whole conversation again -
slower, more expensive, and worse at the task than the same work started
fresh.

budget.maxContextShare is a share of the window - 0.8 for eighty
percent - and reaching it now ends the run as cancelled, not failed, the
same way a time limit already does: a ceiling doing its job is not a
defect. A value outside (0, 1] is refused up front, so someone who means
eighty percent and types 80 is told rather than handed a ceiling that
could never fire.

Checked live: a chain running deepseek-cli-acp with the ceiling set
absurdly low. On this project's own pinned Node version, dsh refused to
start at all - the Node-version problem an earlier article
already found, showing up again in a different feature. On Node 24.18, the
run's first reading arrived, and the stage stopped mid-run with a reason
naming exactly what happened: "stopped at the context ceiling:
budget.maxContextShare is 0.0%, and the agent reported 8,277 of
1,000,000 tokens in its context (0.8%)."

The product also now knows, and says, which agents this can even work on.
contextGauge is a separate question from whether an agent reports
spending: "none" where that is certain, "sends" for deepseek-cli-acp
from this measurement, "unknown" for every other ACP agent nobody here
has watched yet. A stage this ceiling can bind is no longer listed as
unbounded - and one it cannot bind still says so honestly, rather than
implying a safety net that was never there.

The pattern, twice

Neither of these was a code path that ran and did the wrong thing. Both
were something already true - a file still open, a number already
arriving - that nothing had been asked to look at. The fix, in both cases,
was smaller than finding the gap.

Try it

The code is at
github.com/VeryComplexAndLongName/OpenSpec-UI,
where the repository and packages keep the name OpenSpec-UI.

Where each claim comes from

The leftover shell, the rule that excused it, and the fix: the archived change the-sweep-comes-back-for-what-it-left, and its own tasks.md for the live numbers (320 known change names, the 54 MB find).
The context ceiling, the live cancellation message, and the Node-version refusal: the archived change a-run-can-outgrow-its-context and its tasks.md.
maxContextShare, why it is not counted as spend, and contextGauge: LIMITS.md, "caps how full the context gets" and the contextGauge section.

A new agent, and nothing else moved

Alexander Ivanov — Thu, 01 Oct 2026 02:40:01 +0000

First published on openspec-ui.dev.

The last article argued that a shared core is what keeps a VS Code extension
and a web app from drifting apart. Two days after it went out, a new agent
arrived, and it is as good a test of that argument as any: DeepSeek, over the
Agent Client Protocol, requested by the owner and added the same day.

What it took

One new file, deepseek-acp.ts, implementing the same AgentAdapter
interface every other agent implements. It runs dsh --profile acp, the
DeepSeek CLI's own Agent Client Protocol mode, through the driver the other
ACP-flavored adapters already share. It is added to the registry, allowed by
the default allowlist for exactly those arguments, and detected on PATH like
every other agent. Neither host's code changed. Both the standalone
application and the VS Code extension picked it up because both read the same
registry.

DeepSeek is the tenth agent, and the fifth that speaks ACP, beside Claude,
Copilot, Codex and Gemini.

What checking it live actually found

initialize answers as deepseek-harness-acp, with no auth method to run:
the key lives in the person's own dsh profile, never in this project.
session/new offers DeepSeek-V4-Flash as the default model and
DeepSeek-V4-Pro as an option, though nothing here sends that option yet, so
V4-Flash is what runs.

Two things worth a person's attention, both found by running it rather than
by reading its documentation.

On Node 22.11, dsh exits with code 0 before answering, saying nothing at
all. This repository pins Node 22.11 with Volta for its own tooling, and
Volta puts it first on the PATH of anything it starts, including an agent
CLI. The same run on Node 24.18 completed. "ACP connection closed" is not a
sentence a person can act on, so a run that ends this way is now told which
Node it met and that a newer one is needed on the PATH a host starts agents
with.

It reports no usage at all. The live run sent no usage_update and no
usage figure on its answer, so a spending ceiling over deepseek-cli-acp
counts nothing and cannot fire, the same as over five of the other nine
agents. Only a time ceiling has any force over it.

What was asked, and what was left for later

The owner has used DeepSeek enough to know it does best with instructions
taken literally, one at a time, rather than left to infer how strictly to
read what follows. So every prompt to it now opens with a short preamble:
follow the steps in order, do exactly what each one asks, name a step as it
finishes, and stop and say why rather than improvise if a step cannot be done
as written.

What it does not do yet: choose a model. DeepSeek's model is an Agent Client
Protocol session option (session/set_config_option), and nothing in this
project's shared driver sends session options. Whichever model dsh defaults
to is the one that runs. Fixing the Node a host starts agents with is also out
of reach from here: the product cannot choose what is on someone's PATH; it
can only say which one it met.

Why this is the article, and not just a changelog line

Adding a tenth agent is not, by itself, news. What is worth a reader's time is
that adding it stayed inside the one package the architecture says it should:
core, and nowhere else. An implement run against this same change wrote its
own file and ticked its own task in 22 seconds, over the very mechanism the
article describes.

Try it

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

Where each claim comes from

The adapter, the live initialize/session/new answers, the Node 22.11 exit and its explanation, and the preamble: packages/core/src/agents/deepseek-acp.ts.
The decision, the live findings and what was left out: the archived change, deepseek-joins-as-an-acp-agent.
The agent table and the ten agents: README.md, "Agent Selection".
That it reports no usage, and what that means for a spending ceiling: HARNESS.md, the agent capability table and "needs a Node newer than 22.11".
The 22-second implement run: HARNESS.md's own row for deepseek-cli-acp.

A team works through git

Alexander Ivanov — Sun, 27 Sep 2026 02:34:12 +0000

First published on openspec-ui.dev.

Every pitch for team features reaches for the same two things first: a
server, and a database. OpenSpec Workbench now answers three questions a
team actually asks - whose change is this, why did it go back a step, how
long did it spend in each step - and it does it with neither.

The three questions

The repository already had a team, even if the product did not know it:
the owner, the agents that run changes, and a second agent that writes
these articles. Three questions kept coming back, and nothing answered
them. Whose change is this, and who is doing it right now. Why did it go
back a step, and who sent it back. How long did it spend in each step,
counting every time it visited.

The answer, decided on 2026-09-22 and written down as ADR 0037: team work,
with no server and no database, git and the forge as the only shared
truth.

People are files, and joining is a pull request

Each person on a team gets one file, openspec/people/<handle>.json: a
handle, a display name, one public key per machine they sign on, and
optionally the git e-mail addresses that are theirs. Joining writes this
file. Nothing is committed on its own - joining is the pull request that
carries the file, the same way any other change reaches the repository.

A key is never removed, only retired with a date. What it signed before
keeps verifying for as long as the history is kept, which is for good. The
merge gate refuses a pull request that takes a person or a key out,
replaces a key, or edits a retirement already recorded - the same kind of
refusal that already guards a change's specs.

History is signed events, one file per event

A change has an Owner, who answers for it, and an Implementer, who does
the work, by hand or through agents. An agent is never either one: it acts
for a person and signs with that person's key, and every record of what it
did names it as an agent, not as the person.

Who holds a change is played forward from its history, kept as one signed
file per event in openspec/changes/<id>/history/. The events are a
closed list: owner-set, implementer-set, and sent-back, which carries
the stage it returns to, the reason, and every task item it reopens with
why. One file per event, rather than one shared file for the whole team,
is a small engineering decision with a real payoff: two branches never
edit the same file, so a merge on this never conflicts.

The reason in a sent-back event is shown as plain text, never run - the
same rule the rest of this product holds for everything a repository's own
contents might say.

Stages are derived, never declared

This is the same argument the project has made about a change's state
since its first months, applied one layer up. A change's stage - Proposed,
Planned, In progress, In review, Landed, Archived - is never set by a
person or a button. Each is proved by a dated fact: the commit that adds
proposal.md, the commit that adds tasks.md, a closed task line or a
run, a pull request opening, its merge, the archive commit. A sent-back
event moves a change back to a named stage, and after that only a fact
newer than the event moves it on again - so a change can visit a stage more
than once, and every visit is kept.

Getting the times right meant asking three different forges the same
question. The pull request's creation and merge times now come from
whichever one origin is on: GitHub, through gh or its own API, GitLab,
or Gitea - built on the same Forge interface this project described
two articles ago.

The board

The Pipeline already drew every active change as a card. It now offers a
second arrangement of the same cards: By step, the order changes
declare, and By stage, a column per stage from Proposed to Archived.
There are no lines between cards on the board - a stage says where a
change is, not what it waits for - and every card says who owns it and who
implements it, in either arrangement. Both hosts show the same board,
because both read the same core function, and the choice between them is
kept for the next visit.

What this deliberately does not do yet

The ADR is explicit about what it leaves for later, and only if people ask
for it: a server or a database (ruled out on purpose, not postponed), board
columns of the team's own choosing, transition policies such as
work-in-progress limits or required approvals, reports beyond time in
stage, one-way sync to an outside board, a plugin API, and licensing. A
paid plugin, if one ever comes, would build on the facts this records and
change none of them.

Try it

The code is at
github.com/VeryComplexAndLongName/OpenSpec-UI,
where the repository and packages keep the name OpenSpec-UI.

npm run start --workspace @openspec-ui/cli -- join --handle ada --name "Ada Lovelace" --cwd .

One interface, three forges

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

First published on openspec-ui.dev.

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.

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.

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.

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.

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.

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.