DEV Community: Alexander Ivanov

A change is committed where it is made

Alexander Ivanov — Wed, 04 Nov 2026 02:18:09 +0000

A change worked in its own worktree — since ADR 0043 the usual change —
could have its own harness set nowhere but in the file. The Changes tree
drew such a change as one worked "elsewhere" and gave it a shortened menu,
and the Pipeline's card offered only Start, the run's controls and Logs.
Every control added to the tree and not to the card, or the other way
round, left one host or one kind of change poorer.

The owner decided the same day: when a change is made, everything needed
is done, so the change can be worked at once as one's own.

The rules, now with when

The agent workflow rules say when: commit the planning artifacts on the
change's branch and push it with an upstream as soon as they are written;
commit and push after every task ticked; leave nothing uncommitted or
unpushed at the end of a turn; nothing of a change on main; a refused
push is said, not worked around.

Create Change, in both hosts, commits the new change on its branch and
pushes it at once. A refused push leaves the change made and says why
(OSW-GIT-203).

The git stage commits what the stages left before it pushes
(OSW-GIT-103 where that commit fails).

The survey and the card

The survey says where a change's own branch is not on the server: never
pushed, or at another commit. Read from the refs it lists anyway, so no
git runs in the directory.

A card of a change's own worktree says so ("not on the server"), and a
new action, Commit Change, commits everything the worktree holds on
the change's branch and pushes it. On the card and in Show Actions..., in
both hosts; refused in the main checkout and on the default branch.

A card of a change's own worktree offers its actions in the arrangement
by step as on the board, and Run Change...: the owner found on
2026-10-10 that such a change could be acted on but never run — a card's
Start was refused for a change this checkout does not have. It runs in
the change's worktree, in both hosts.

Messages in the new GIT group

Messages in the register's new GIT group (OSW-GIT-001..203) name
every failure, refusal and success in the commit and push path. ADR 0043
is amended to reflect the new rules.

Try it

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

openspec-ui-cli commit change --cwd .

Every message has an identifier, from one register

Alexander Ivanov — Fri, 30 Oct 2026 02:22:24 +0000

First published on openspec-ui.dev.

What the product says to a person — a failure's reason, a refusal, a CLI
error — was written where it is said, as a sentence. A person cannot look
up a message they saw, a host cannot act on one except by reading its
words, and nothing says which messages exist. A new register decides that
every message is said as <level> OSW-<GROUP>-<NNN>: <message>, from one
place, and that the register comes first with the groups CLI, RUN,
QST and PRM.

The register, and what it holds

message-register.ts in core holds the 14 groups, every message's
identifier, level, words with named values, why it is said and what to
do. say, formatMessage, withMessageCode, messageEntryUrl are the
functions the rest of the product calls.

The CLI, RUN, QST and PRM messages are said from the register:
the CLI's argument errors, the chain's refusals, limits and endings, the
operator's questions, and the permission requests nobody can answer. Their
words do not change; the CLI's lines lose openspec-ui-cli: and gain the
form, error OSW-CLI-003: --cwd requires a value.

A page you can search for

docs/messages.md is generated from the register: a page a person
searches for the identifier they saw. If you see error OSW-RUN-042 in
your terminal or panel, you can look up what it means, why it was said,
and what to do about it, without guessing from the words alone.

Codes on events and in JSON

progress, failed and cancelled events carry code beside their
words, and so does the CLI's JSON. The CLI, the output channel and the
panels put the identifier before the words; the panels show it as a label
that links to its entry.

Tests that hold the line

Tests check that identifiers are well formed and in a group, that every
identifier ever given is kept, that the page matches what the register
says, and a ratchet on the messages still said in place — 323 before, 290
after, and it may only fall. This ratchet prevents new ad-hoc messages
from being added outside the register.

Try it

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

openspec-ui-cli run change --cwd . 2>&1 | grep 'OSW-'

The agent asks the operator, and the chain waits

Alexander Ivanov — Sun, 25 Oct 2026 02:30:55 +0000

First published on openspec-ui.dev.

An agent ended its run with four decisions it needed from the operator,
and the product offered no way to answer them. A chain would have gone on
to the next stage with them open. The owner decided the same day: questions
are caught, the run stops and waits, nothing goes on without an answer, the
answers are kept in the change's decisions.md and in the audit log, and
the product's own agent asks in its turn from the start.

The marker, the event and the command

Every agent stage's instruction asks for Question for the operator: <…>
lines for decisions the agent needs. The product reads them as markers.
local-llm-acp gets an ask_operator tool that blocks its turn until
answered.

A question event and an answerQuestion command are added to the
protocol. A question waiting kind appears in the run's status. A run
that asked waits instead of completing, in a chain or alone, under every
autonomy level. Once answered, the stage runs again with the answers —
update for propose and review, the same command otherwise.

Where answers live

openspec/changes/<change>/decisions.md holds every question and answer.
The audit log records both. An agent run on a change with an open question
is refused.

Questions are answered from the card, the AI panel, the Human-Only Inbox
and openspec-ui-cli answer. The card shows open questions with answer
fields; the panel does the same. The Inbox surfaces questions alongside
its usual checkpoint answers. From a terminal:

openspec-ui-cli answer <changeId> --question "Which branch strategy?" --answer "gitflow"

What this changes about autonomy

Before this, an autonomy level of full meant the chain ran without
interruption. Now, a question is a hard stop regardless of autonomy level.
The chain waits for a human answer, even at full autonomy. This is
intentional: a question from an agent is a request for judgment, not a
checkpoint the chain can resolve on its own.

The refusal of a run past an open question is explicit. If someone tries
to start a new agent run on a change that still has unanswered questions,
the product says so and names the open questions. This prevents a second
agent from running while the first is still waiting for an answer.

Try it

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

openspec-ui-cli answer <changeId> --question <questionId> --answer <answer>

Local models can now search the web and fetch pages

Alexander Ivanov — Wed, 21 Oct 2026 12:31:55 +0000

First published on openspec-ui.dev.

OpenSpec Workbench puts local-model behavior and its security controls in
the shared core, but until now neither local adapter could search the web
or fetch a source page. Two new shared core tools have been added:
search_web and fetch_webpage. They let local-model agents consult a
SearXNG endpoint and retrieve HTML pages as Markdown-backed JSON artifacts
that can be analyzed or passed to another agent.

What the tools do

search_web sends a query to a SearXNG JSON endpoint and returns the
results as structured data. fetch_webpage retrieves a public HTTP(S) URL,
converts the article or main content to Markdown, writes every data table
as a Markdown table, and returns provenance, page metadata and timestamps
in JSON.

Both tools are available to both local-model adapters: local-llm and
local-llm-acp. Remote agents are unchanged. The tools do not speak to
any vendor API; they speak only to the SearXNG instance you configure.

Configuration and bounds

The single SearXNG instance is configured with the OPENSPEC_UI_SEARXNG_URL
environment variable. When search has not been configured, the tools return
an explicit error rather than failing silently or hanging.

Page fetching is restricted to bounded public HTTP(S) HTML. Pages larger
than the configured bound are read up to the bound and the response says
so. Remote content is treated as untrusted data throughout the pipeline.

Why this matters for local models

A local model is only as useful as the information it can bring to bear.
Before these tools, a local agent could reason about what was already in
its context window, but it could not look up a current fact or read a
source page. Now it can search for context and fetch the page that
contains it, all without sending data to a remote API.

The tools return Markdown-backed JSON artifacts, not raw HTML. This means
the local model receives clean, structured content that fits into its
context window more efficiently, and that data tables are preserved as
Markdown tables rather than lost in markup noise.

What this deliberately does not do

These tools are not a general-purpose web browser. They do not execute
JavaScript, they do not render CSS, and they do not interact with forms
or buttons. They search and fetch, convert to Markdown, and return. If a
page requires JavaScript to render its content, the fetch will return
whatever the server sends without execution.

They also do not change the command or event protocol. No new transport
channels are opened, no new agent types are introduced. The tools are
exposed through the existing local-model adapters, and the environment
configuration is read by the shared core runner.

Try it

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

OPENSPEC_UI_SEARXNG_URL=http://localhost:8080 openspec-ui-cli run --change my-change

A compliance monitor that does not busywork

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

First published on openspec-ui.dev.

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.