Spec Engines
The skill pack drives spec-driven implementation through pluggable spec
engines. /kbd-apply (in skills/process/kbd-process-orchestrator/skills/kbd-apply/)
wraps one engine at a time and walks its tasks ONE at a time so KBD stays the
source of truth: every task boundary fires the KBD hooks, emits a plain-text
position signal, and syncs progress.json and the waypoint.
Engine metadata (CLI, pinned version, adapter pointer) is registered in
config/spec-engines.json. The Node helper
shared/scripts/spec-engine-info.mjs
prints the registry and — with --root <dir> — the same detection result the
bash driver computes.
OpenSpec — the primary engine
OpenSpec (@fission-ai/openspec,
CLI openspec) is the primary engine. New projects adopt it through
/kbd-init (--spec-engine openspec, the default), which runs openspec init
through the managed runner (shared/openspec/cli.mjs init). Its artifacts live under
openspec/changes/<change>/{proposal.md,design.md,specs/,tasks.md}. The pack
pins the exact version in package.json (@fission-ai/openspec, exact pin —
currently 2.0.0, which needs Node.js 22.12.0 or newer; the authoritative value is whatever package.json says).
The managed runner uses the same exact pin and never follows the registry past it.
OpenSpec 2.0 writes its skills once to .agents/skills/openspec-* and has no
/opsx:* commands; KBD creates changes with openspec new change <id> through the
runner and implements them only through /kbd-apply.
The adapter is os_* in kbd-apply.sh: list and progress come from
openspec instructions apply --change <id> --json, mark_done flips the
matching checkbox in tasks.md, verify runs openspec validate (a static document check), and
archive runs openspec archive <id> --yes — only after the phase is CLOSED (the --yes is required — the
interactive prompt has no stdin here).
Spec Kit — the supported backup
GitHub Spec Kit (v1.x, CLI specify,
installed with uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.3.0,
pinned 1.3.0 in config/spec-engines.json) is the backup engine. Choose it for a
new project with /kbd-init --spec-engine speckit, which runs
specify init --here --force --non-interactive --integration <harness>. It writes its artifacts under .specify/ (templates
and scripts) and specs/<slug>/{spec.md,plan.md,tasks.md}. A "change" for the
adapter is the feature-dir slug under specs/.
Detection
- Repo-wide: a
.specify/directory, or anyspecs/*/tasks.md, selectsspeckit. - Change-scoped:
specs/<change>/tasks.md,specs/<change>/spec.md, orspecs/<change>/plan.md(v1 feature dirs may be driven beforetasks.mdis generated) selectsspeckitfor that change.
Pinning
Pin the engine explicitly in .kbd-orchestrator/project.json:
{ "specBackend": "speckit" }
Valid values: "openspec", "speckit", "native-kbd", "auto" (detect from
the repository shape; openspec wins when openspec/ exists). A pin always
overrides detection. The legacy key change_backend is read when specBackend
is absent.
Updating when a new Spec Kit release ships
- Update
pinnedVersioninconfig/spec-engines.jsonto the new exact version (dependency pins are exact, never ranges). - Verify the adapter ops —
sk_list/sk_progress/sk_mark_done/sk_verify/sk_archiveinkbd-apply.sh— against the new release'sspecs/layout (checkbox format oftasks.md, presence ofspec.md,plan.md,tasks.mdin the feature dir). - No code change is expected unless the layout changes. If it does, update
the adapter functions and the detection shapes together, and record the
reason in
config/spec-engines.json'srationalefield.
sk_verify is a structural gate — every checkbox in specs/<change>/tasks.md
checked AND specs/<change>/spec.md present — because Spec Kit's own
/speckit.analyze is model-driven (it dispatches an LLM, not a CLI) and
cannot run inside the driver's non-interactive loop. sk_archive is
best-effort and pack-side: Spec Kit has no native archive command, so the
adapter moves specs/<change> to specs/archive/<date>-<change>, mirroring
native-kbd's archive.
Native-kbd
The pack-owned backend. Source of truth:
.kbd-orchestrator/changes/<change>/tasks.json (schema:
references/schemas/change-tasks.schema.json); tasks.md is a regenerated
view. Detected change-scoped by tasks.json or a legacy change.md, and
repo-wide by .kbd-orchestrator/changes/*/tasks.json|change.md. It is kept
for compatibility: projects that already keep native changes, or pin
native-kbd, continue to use it. It is not offered as a default for new
projects; no external pin.
The adapter contract
Every engine implements five operations as <prefix>_* functions in
kbd-apply.sh (os_, sk_, nk_):
| Op | Signature | Output / effect |
|---|---|---|
list | <change> | TSV on stdout: `id[TAB]done(0 |
progress | <change> | total complete remaining on stdout |
mark_done | <change> <id> | flip one task to done in the engine's own artifact |
verify | <change> | structural/CLI gate; non-zero exit = fail |
archive | <change> | move the change out of the active area |
The b_* dispatchers (b_list, b_progress, b_mark_done, b_verify,
b_archive) resolve the backend per change via backend_detect (pin first,
then change-scoped shape, then repo-wide shape) and route to the right
adapter. Unknown backends fail loudly for list/progress/mark_done and are a
safe no-op pass for verify/archive. The driver never invokes a backend's
"implement everything" command — it calls the backend per task.
The TSV contract (id\tdone\ttitle) is what the per-task loop, reconcile, and
the position model consume; adapters must keep it stable.
Adding a new spec engine
- Implement the five ops as
<prefix>_functions inskills/process/kbd-process-orchestrator/skills/kbd-apply/kbd-apply.sh, honoring the TSV contract above. - Add a detection shape in
backend_detect— both the change-scoped branch (what marks this change as yours) and the repo-wide heuristic — and add your engine id to thespecBackendpincaselist. - Register the engine in
config/spec-engines.jsonunderengines(CLI name, exactpinnedVersion,rationalepointing at this document, adapter prefix). Third-party engines that are not shipped in the pack can be recorded undercustomEngines.