Skip to content

SpecBridge v0.6.0: capability-driven runner platform, Codex CLI and Ollama runners #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
HelloThisWorld merged 1 commit into from
Jul 14, 2026
Merged

SpecBridge v0.6.0: capability-driven runner platform, Codex CLI and Ollama runners #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"name": "specbridge",
"source": "./integrations/claude-code-plugin/specbridge",
"description": "Kiro-compatible spec workflows, verified interactive task execution, and deterministic drift checks.",
"version": "0.5.0",
"version": "0.6.0",
"license": "MIT",
"keywords": [
"spec-driven-development",
Expand Down
135 changes: 135 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,140 @@
# Changelog

## 0.6.0

Added:

- Capability-driven runner platform: core orchestration selects and gates
runners by DECLARED CAPABILITIES (17 stable keys), never by provider
names. Runner categories (`agent-cli`, `model-api`, `mock`,
`experimental`) and support levels (`production`, `preview`,
`experimental`, `unavailable`, `incompatible`) are explicit everywhere.
- Versioned, FROZEN runner adapter contract for v0.6.1
(docs/runner-adapter-contract.md) with snapshot tests guarding categories,
support levels, operation names, capability keys, normalized outcomes,
normalized error codes, event types, and required adapter methods — plus a
minimal-adapter test proving new providers register without core changes.
- Operation-specific capability validation: `stage-generation`,
`stage-refinement`, `task-execution`, `task-resume`, `model-list`,
`runner-test`, each with required capabilities and (for execution) a
required safe boundary (`sandbox` OR the documented `toolRestriction`
equivalent). Incompatible selections stop BEFORE any process spawn, HTTP
request, run record, or file change, and list the missing capabilities and
compatible configured profiles.
- Normalized provider events (17 types, size-limited flat payloads, no
reasoning content), normalized execution results (13 outcomes), normalized
runner errors (24 stable codes with safe messages, remediation, and
retryability), and normalized usage/cost metadata (cost is
provider-reported, configured-estimate, or unavailable — never computed
from hardcoded pricing; local Ollama reports `unavailable`, not zero).
- Versioned runner profiles (configuration schema 2.0.0): named
configurations of implementations (`codex-default`, `codex-fast`,
`ollama-qwen`, …) with per-profile executable/endpoint, model, timeout,
sandbox, and output limits; unique names; unknown implementations
rejected.
- Configuration migration tools: `specbridge config doctor` (read-only) and
`specbridge config migrate --dry-run|--apply` (atomic write, recoverable
`config.v1.backup.json`, validated result). The v1 schema remains fully
readable before explicit migration; migration preserves the Claude Code
default behavior and trusted verification commands, adds Codex/Ollama
profiles DISABLED, and creates no credentials.
- Deterministic runner selection with precedence explicit `--runner` →
operation default → global default, a capability-checked selection plan
(`--show-runner-plan`, dry-run output), and network-policy enforcement
(network-backed profiles are never selected implicitly).
- Explicit authoring fallback policy: per-operation chains
(`fallbacks.stageGeneration/.stageRefinement`), bounded correction and
transport retries, and hard stop conditions (auth/permission/config
failures, cancellation, quota, repository modification, real results).
Disabled by default; never during task execution or resume.
- Generated runner capability matrix: `specbridge runner matrix`
(`--json`, `--markdown`) from registered runner metadata; plus
`runner show <profile>`, `runner test <profile> [--network]`,
`runner conformance <profile> [--network]`, and
`runner models <profile>`.
- Reusable runner conformance framework (detection, structured-output,
process-control, stage-generation, stage-refinement, task-execution,
resume) with capability-derived applicability; a runner is production only
when every applicable group passes. Conformance uses throwaway fixture
workspaces, requires `--network` for real-provider invocations, and runs
fully against fake providers in CI.
- Production Codex CLI runner (`codex-cli`): read-only probes for
version/help/`exec --help`/`login status` (never a model request, never
credential files), JSONL event capture and normalization, JSON Schema
structured output with strict validation, read-only sandbox for authoring,
workspace-write sandbox for task execution, explicit-session resume
(`codex exec resume <id>`, never "latest"), and full failure
classification (auth, permission, sandbox, quota, rate limit, timeout,
cancellation, output limits).
- Production Ollama authoring runner (`ollama`): loopback-default native
HTTP API with strict URL safety (no credentials in URLs, no file/ftp
schemes, HTTPS-by-default for remote endpoints with a labeled insecure
development override, redirects never followed), model listing without
inference, schema-validated non-streaming structured output at
temperature 0, ONE bounded correction retry, input/output size limits,
thinking-content redaction, and task execution refused by capability
before any request.
- Append-only per-invocation attempt records under
`.specbridge/runs/<run-id>/attempts/<attempt-id>/`: capability snapshot,
operation, local/network boundary, model, normalized events and result,
process observation, error classification, and fallback lineage. Failed
attempts (including invalid structured-output candidates) are retained.
- Fake-provider test infrastructure: a process-level fake Codex CLI
(26 scenarios) and a real loopback fake Ollama HTTP server (20 scenarios);
CI needs no real providers, no network, no models, no credentials.

Changed:

- The existing Claude Code runner now implements the shared capability
contract (category `agent-cli`, declared capability set, detection-derived
support level) with its v0.3–v0.5 behavior, process safety, permission
modes, resume, structured-output validation, and configuration semantics
preserved unchanged.
- Runner selection validates operation capabilities before execution; task
execution is restricted to compatible agent CLI runners and model API
runners are authoring-only.
- Provider output is normalized (events, results, errors, usage) before it
enters shared orchestration; run records now reference per-attempt
capability snapshots and attempt metadata.
- The shared prompt contract (v1.1.0) parameterizes repository access:
agent CLIs receive read-only repository tools for authoring; model APIs
receive an explicit no-repository-access variant. The same core safety
sections appear for every provider (tested for semantic equivalence).
- `runner list`/`doctor`/`show` are profile-based; the v0.3 `unsupported`
stub registrations (codex/ollama/openai-compatible) were replaced by real
disabled-by-default profiles, and deferred providers are no longer
registered at all.

Security:

- No provider credentials stored; credential-looking configuration keys are
rejected; no credential-file parsing anywhere.
- No automatic paid or network-provider selection; no automatic
task-execution fallback or provider switching.
- No unrestricted Codex execution mode (`danger-full-access`, bypass flags,
and repo-check skips rejected at three layers).
- No source editing by Ollama (no repository access by construction).
- No provider claims treated as task evidence; Git snapshots and trusted
verification remain the only completion authority.
- No shell interpolation for runner commands (argv arrays only, both
schemas).
- Explicit local and network data boundaries in every plan and attempt
record; provider reasoning content never exposed; provider event payloads
size-limited.

Deferred to v0.6.1:

- Gemini CLI runner.
- OpenAI-compatible authoring runner.
- Antigravity capability adapter.
- MCP runner diagnostics.
- Claude Code runner-management Skill (`/specbridge:runners`).

Deferred to v0.7:

- Templates, plugin SDK, runner extension SDK distribution, analyzer and
verifier SDKs, extension registry, community ecosystem.

## 0.5.0

Added:
Expand Down
135 changes: 107 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,46 @@ Codex, local models, or any supported coding agent.

> Your `.kiro` specs remain the source of truth.

New in v0.5 — a self-contained **Claude Code plugin** with a local MCP
New in v0.6 — keep your existing `.kiro` specs and **choose a compatible
coding agent or authoring model per operation**:

```text
Spec authoring Task execution
Claude Code ✓ ✓
Codex CLI ✓ ✓
Ollama ✓ —
```

```bash
specbridge runner matrix

specbridge spec generate notification-preferences \
--stage requirements \
--runner ollama-local

specbridge spec generate notification-preferences \
--stage design \
--runner codex-default

specbridge spec run notification-preferences \
--task 2.3 \
--runner codex-default
```

Runner behavior is capability-driven: authoring-only model APIs (Ollama)
can never execute tasks, task execution needs a safe sandbox or tool
restriction, network-backed endpoints are never selected implicitly, and
whatever runs, task completion still requires actual Git evidence plus
trusted verification — never a provider claim. The live matrix above is
generated from registered runner metadata (`specbridge runner matrix`); not
every installed Codex version is compatible (`specbridge runner doctor
codex-default` reports the exact capabilities).

SpecBridge does not include provider subscriptions, hosted models, API
usage, or authentication — you install and authenticate Claude Code, the
Codex CLI, or Ollama yourself. See [docs/runners.md](docs/runners.md).

From v0.5 — a self-contained **Claude Code plugin** with a local MCP
server and verified interactive task execution:

```text
Expand Down Expand Up @@ -214,6 +253,9 @@ Working today (fully offline, no model, no API key):
| `specbridge verify rules / explain <id>` | **v0.4** — inspect the stable rule registry SBV001–SBV025 |
| `specbridge mcp serve / doctor / manifest / tools` | **v0.5** — local stdio MCP server (21 tools, 7 resources, 4 prompts) |
| `specbridge run recover-lock` | **v0.5** — diagnose and explicitly recover the interactive execution lock |
| `specbridge runner list / matrix / show / doctor` | **v0.6** — profile-based runner diagnostics and the generated capability matrix (read-only) |
| `specbridge runner test / conformance / models <profile>` | **v0.6** — bounded structured-output probe (`--network`), conformance suite, provider-supported model listing |
| `specbridge config doctor / migrate` | **v0.6** — configuration validation and the explicit v1 → v2 migration (dry-run by default, atomic apply with backup) |

Planned commands (`spec sync/export`) are registered, marked "(planned)" in
`--help`, and exit with an honest error — see the [roadmap](docs/roadmap.md).
Expand Down Expand Up @@ -317,25 +359,27 @@ by `spec approve` — see [docs/approval-workflow.md](docs/approval-workflow.md)
Runner-assisted generation (since v0.3) is always explicit opt-in; offline
templates remain the default.

## Model-assisted authoring and task execution (v0.3)
## Model-assisted authoring and task execution (v0.3, multi-runner since v0.6)

With a locally installed, locally authenticated Claude Code CLI (or the
offline mock runner), SpecBridge can draft spec stages and execute approved
tasks — with the safety model doing the real work:
With a locally installed, locally authenticated agent CLI (Claude Code or
Codex), a local Ollama endpoint for authoring, or the offline mock runner,
SpecBridge can draft spec stages and execute approved tasks — with the
safety model doing the real work:

```sh
specbridge runner doctor claude-code
specbridge runner matrix

specbridge spec generate notification-preferences --stage requirements
specbridge spec generate notification-preferences --stage requirements --runner ollama-local
specbridge spec analyze notification-preferences --stage requirements
specbridge spec approve notification-preferences --stage requirements

specbridge spec generate notification-preferences --stage design
specbridge spec generate notification-preferences --stage design --runner codex-default
specbridge spec approve notification-preferences --stage design
specbridge spec generate notification-preferences --stage tasks
specbridge spec approve notification-preferences --stage tasks

specbridge spec run notification-preferences --task 2.3
specbridge spec run notification-preferences --task 2.3 --runner codex-default
specbridge run show <run-id>
```

Expand Down Expand Up @@ -451,19 +495,26 @@ CI for this repository runs on Linux, macOS, and Windows with Node 20/22.
## Supported runners

Runners make SpecBridge model- and agent-agnostic. Default commands never
require one.

| Runner | Status |
| --- | --- |
| `mock` | ✅ Implemented — offline, deterministic, scenario-driven, used by CI |
| `claude-code` | ✅ **v0.3** — local CLI runner: generation, refinement, task execution, resume |
| `codex` | ❌ Stub — honestly not implemented (roadmap) |
| `ollama` | ❌ Stub — honestly not implemented |
| `openai-compatible` | ❌ Stub — honestly not implemented |

Configuration lives in `.specbridge/config.json`
([docs/agent-runners.md](docs/agent-runners.md)). Never commit API keys;
SpecBridge stores no credentials of any kind.
require one. Since v0.6, runners are configured as capability-checked
PROFILES; the live matrix comes from `specbridge runner matrix`:

| Profile | Support | Author | Refine | Execute | Resume | Local |
|---------|---------|--------|--------|---------|--------|-------|
| claude-code | production | yes | yes | yes | yes | no |
| codex-default | production | yes | yes | yes | yes | no |
| ollama-local | production | yes | yes | no | no | yes |
| mock | production | yes | yes | yes | yes | yes |

`codex-default` and `ollama-local` ship DISABLED until you enable them
explicitly. Ollama is authoring-only by capability — it can never execute
tasks or modify files. Gemini CLI, an OpenAI-compatible authoring runner,
and Antigravity are planned for v0.6.1 (no placeholders are registered).

Configuration lives in `.specbridge/config.json` (schema 2.0.0; v1 files
stay readable, migration is explicit — see
[docs/configuration-migration.md](docs/configuration-migration.md) and
[docs/runners.md](docs/runners.md)). Never commit API keys; SpecBridge
stores no credentials of any kind.

## Security and privacy

Expand All @@ -479,7 +530,7 @@ SpecBridge stores no credentials of any kind.
secrets or environment variables.
- Full model: [docs/security.md](docs/security.md).

## Limitations (v0.5)
## Limitations (v0.6)

- The MCP server is stdio-only and local-only: no HTTP/SSE/WebSocket
transport, no OAuth, no cloud hosting. One server process serves one
Expand All @@ -500,8 +551,18 @@ SpecBridge stores no credentials of any kind.
references, chore-task exclusion) are labelled and never default to error.
- `spec sync` and `spec export` are not implemented yet (they fail
honestly). SARIF output is deferred.
- Claude Code is the only production runner; codex/ollama/openai-compatible
remain stubs. Claude usage happens under your own account and plan.
- Production runners are claude-code, codex-cli, ollama (authoring-only),
and mock. Gemini CLI, OpenAI-compatible, and Antigravity are deferred to
v0.6.1 and are not registered as placeholders. Provider usage happens
under your own accounts and plans; not every installed Codex version is
compatible (the doctor reports the exact missing capabilities).
- Ollama cannot execute tasks or modify files — by capability, not by
configuration. Models are never pulled or selected automatically.
- Codex resume needs an installed version with explicit session resume;
without it, resume is reported unsupported instead of guessed.
- Authoring fallback exists only for explicitly configured chains, only for
stage generation/refinement, with bounded retries; there is no automatic
provider switching anywhere else.
- Task execution requires a git repository, sidecar workflow state, and
fully approved stages — by design; there is no force flag.
- Tasks can only auto-verify when verification commands are configured;
Expand Down Expand Up @@ -535,10 +596,15 @@ git snapshots, trusted verification, append-only evidence, verified-only
checkbox completion, manual acceptance, resumable sessions. v0.4:
deterministic drift verification (rule engine SBV001–SBV025, policies,
affected-spec resolution, evidence freshness, four report formats) and the
production GitHub Action. v0.5 (this release): the local stdio MCP server,
direct interactive task execution, and the self-contained Claude Code
plugin with its repository-local marketplace. Next — v0.6: production
multi-runner support. v0.7: templates, plugin SDK, extension registry,
production GitHub Action. v0.5: the local stdio MCP server, direct
interactive task execution, and the self-contained Claude Code plugin with
its repository-local marketplace. v0.6.0 (this release): the
capability-driven runner platform with a frozen adapter contract, runner
profiles and explicit configuration migration, deterministic selection and
bounded authoring fallback, the conformance framework, and the production
Codex CLI and Ollama (authoring-only) runners. Next — v0.6.1: Gemini CLI,
OpenAI-compatible authoring, Antigravity, MCP runner diagnostics, and the
runner-management Skill. v0.7: templates, plugin SDK, extension registry,
community ecosystem. Full detail: [docs/roadmap.md](docs/roadmap.md).

## Documentation
Expand All @@ -549,6 +615,19 @@ community ecosystem. Full detail: [docs/roadmap.md](docs/roadmap.md).
[Spec analysis](docs/spec-analysis.md) ·
[Approval workflow](docs/approval-workflow.md) ·
[Sidecar state](docs/sidecar-state.md) ·
[Runners (v0.6)](docs/runners.md) ·
[Runner capabilities](docs/runner-capabilities.md) ·
[Runner profiles](docs/runner-profiles.md) ·
[Runner selection](docs/runner-selection.md) ·
[Runner fallback](docs/runner-fallback.md) ·
[Runner conformance](docs/runner-conformance.md) ·
[Runner adapter contract](docs/runner-adapter-contract.md) ·
[Codex CLI runner](docs/codex-cli-runner.md) ·
[Ollama runner](docs/ollama-runner.md) ·
[Network & data boundaries](docs/network-data-boundaries.md) ·
[Runner security](docs/runner-security.md) ·
[Runner troubleshooting](docs/runner-troubleshooting.md) ·
[Configuration migration](docs/configuration-migration.md) ·
[Agent runners](docs/agent-runners.md) ·
[Claude Code runner](docs/claude-code-runner.md) ·
[Model-assisted authoring](docs/model-assisted-authoring.md) ·
Expand Down
13 changes: 10 additions & 3 deletions docs/agent-runners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,12 @@ Runners make SpecBridge model- and agent-agnostic: a runner wraps one way of
invoking an AI coding agent. Default SpecBridge commands never require one;
runner execution is always explicit.

## The contract (v0.3)
> **v0.6:** runners are now selected through capability-checked PROFILES
> (`claude-code`, `codex-default`, `ollama-local`, `mock`) with a frozen
> adapter contract. Start at **[runners.md](runners.md)**; this page keeps
> the v0.3 execution-contract fundamentals, which are unchanged.

## The contract (v0.3 core, extended by v0.6 capabilities)

Every runner implements the same model-agnostic contract
(`@specbridge/runners`):
Expand All @@ -25,8 +30,10 @@ orchestration lives in `@specbridge/execution` and evidence evaluation in
### Runner kinds and statuses

Kinds: `mock` (offline, deterministic), `claude-code` (local Claude Code
CLI), `unsupported` (honest stubs: `codex`, `ollama`, `openai-compatible` —
documented on the [roadmap](roadmap.md), not implemented, never faked).
CLI), `codex-cli` (local Codex CLI, v0.6), and `ollama` (local model API,
authoring-only, v0.6). The v0.3-era `unsupported` stubs are gone — deferred
providers (Gemini CLI, OpenAI-compatible, Antigravity) exist only on the
[roadmap](roadmap.md) and are not registered as placeholders.

Detection statuses: `available`, `unavailable`, `unauthenticated`,
`incompatible`, `misconfigured`, `error`. Only `available` permits
Expand Down
Loading
Loading