/kbd-execute
Run the Execute phase of the KBD lifecycle.
OpenSpec lifecycle preflight
Before this stage, follow the orchestrator preflight: use the pinned OpenSpec 2.0.0 CLI through the managed runner — session start runs the read-only verify; phase entry runs refresh, which updates existing KBD/OpenSpec projects — then use that same runner for OpenSpec commands. Retry a pending phase-entry refresh before OpenSpec work; preserve authored specs and task state. Phase scripts run this automatically, including canonical-runtime paths.
What this does
Reads .kbd-orchestrator/phases/<phase-name>/plan.md, selects the best
execution backend (tool or OpenSpec), writes execution.md, and dispatches the
phase while keeping KBD as the source of truth.
Dispatch begins Execute; it does not complete it. Write the backend contract
in execution.md and a dispatch receipt at
.kbd-orchestrator/phases/<phase>/execute-dispatch.json with the actual
dispatch time, assigned changes, and pending work. This receipt is not a stage
handoff: do not give it completedAt or nextStage: reflect, and do not place
it at handoffs/execute.handoff.json.
Keep the parent Execute stage active while delegated or local work runs. Use
kbd-apply task boundaries and typed KBD mutations; the runtime refreshes
progress and waypoint projections. Resume from actual canonical work state,
not the existence of a dispatch artifact.
Value-phase boundary (B4)
Do not run tests, verification builds, compiler checks, artifact refinement or
adversarial review after individual tasks or changes (B1/B2 run nothing but
journaling and openspec validate). Complete every planned production change
first. When the active harness provides an agent team, assign implementation to
executor roles and keep reviewer, auditor, verifier and integration-checker roles
dormant until every production change is complete. Then run the B4 sequence
exactly as kbd-process-orchestrator/references/boundaries.md
defines it — this skill does not restate or vary it:
all phase production complete (typed KBD transitions) + contract amended to implementationComplete
│
├─ 1 admit scripts/kbd-phase-readiness-check.mjs (latest digest, spec deltas, method, authority)
│ + scripts/kbd-boundary-authorize.mjs --phase <id> --authorizer <who> (once, before any attempt)
├─ 2 freeze candidate identities (cadence `candidate freeze` is this step)
├─ 3 boundary packet adopted-contract boundaryPacket.commands, once, in order
│ (build → run → scenario → negativeControl) — value-scenario-verify
├─ 4 record boundary-results.json: PASS | FAIL | BLOCKED | NOT_EXERCISED + executedBy
├─ 5 static QA one cumulative artifact validation (no build) + one diff-mode adversarial review
├─ 6 close scripts/kbd-phase-close-eval.mjs → closure.json + closure-packet.md
├─ 7 after CLOSED kbd-apply verify + archive for every change of the phase
└─ 8 reflect kbd-reflect (contract-accuracy metrics)
Any FAIL at step 3 → steps 5–7 do not run. The owner either authorizes a bounded
B5 repair (rerun only the affected scenarios and negative controls; consumes
budgets.repairAttempts; record it with --boundary B5) or closes the phase unmet.
A CRITICAL adversarial finding at step 5 is handled the same way: record
certification BLOCKED through typed KBD commands; fixing it is a B5 repair,
never a free rerun.
Local review coverage
File-count and documentation-only skips do not exist. QA and adversarial review
cover the cumulative phase diff. They never interrupt production implementation.
Skipping either step-5 review records pending_review; final local certification
still requires a completed receipt or an explicit, signed waiver.
Progress Signals (MANDATORY)
FIRST tool call of every turn: Read .kbd-orchestrator/position-reminder.txt (if it exists) to get the current phase, step N of T, and next command. If that file is absent, read .kbd-orchestrator/current-waypoint.json.
Before any other action, emit to plain response text (BEFORE any tool call):
Starting kbd-execute — <phase-name> (step N of T)
Only after the execute completion checklist below is satisfied, emit:
Completed kbd-execute — <phase-name> (step N of T)
How to get N and T (MANDATORY — never estimate): read
completion.implementation.completed/.total from progress.json via
implementationCompleted(progress)/implementationTotal(progress)
(lib/kbd/progress.mjs), falling back to current-waypoint.json's
implementationCompleted/implementationTotal when progress.json is
absent.
When executing a named sub-phase within a multi-phase plan, emit the phase-level signal BEFORE the first change signal — even when the orchestrator is not present:
Starting phase <N> out of <total>: <sub-phase-name>
After all changes in that sub-phase satisfy the execute completion checklist:
Completed phase <N> out of <total>: <sub-phase-name>
Additionally, emit before and after each individual change (read canonical
completion.implementation from progress.json; legacy counters are fallback
aliases only — never guess and never use evidence-task completion):
Starting change <N> of <total>: <change-id>
Completed change <N> of <total>: <change-id>
When the code/integration contract for a change is complete, update the ledger
atomically with markImplementationComplete(progressFile, changeId, ctx) from
lib/kbd/progress.mjs:
import { markImplementationComplete } from '../../lib/kbd/progress.mjs';
await markImplementationComplete(
'.kbd-orchestrator/phases/<phase>/progress.json',
'<change-id>',
{ hooksFire },
);
This transition does not mark evidence, certification, or publication complete. Never postpone it merely because those independent dimensions are pending.
Use the canonical phase name from the argument or current-waypoint.json. Phase and change totals must come from progress.json or the plan — never guessed. Emit to plain response text — no tool call needed.
How to invoke
- Discover project identity — read
.kbd-orchestrator/project.jsonor infer - Confirm the active phase — from argument or waypoint
- Load waypoint —
.kbd-orchestrator/current-waypoint.jsonfirst when it exists - Load assessment and plan for the phase
- Write
execution.mdwith selected backend + dispatch contract - Record the active path through typed KBD commands; projections refresh automatically
- Register planned changes and tasks through
prometheus kbd change register/task register - Dispatch and write
execute-dispatch.json; keep Execute active - Complete every planned production change without intermediate verification
- Run the B4 sequence once (
kbd-process-orchestrator/references/boundaries.md): boundary packet, record, cumulative static QA and review, close - Verify and archive changes through
kbd-applyonly after the phase is CLOSED (B4 step 7) - Complete Execute only at the phase boundary — use the checklist below; dispatch is not completion
Task model handoff
Read the phase plan's Task model assignments and task model selection. Carry each scoped assignment reference, concrete model and supported route into execution.md and the worker handoff. Resolve the exact phase/change/backend task ID; do not replace task-level choices with a change-level model class or the session default.
Recheck availability and policy before dispatch. Changed task requirements, harness or model evidence require an explicit revised assignment; legacy plans receive an assignment through the same protocol. Unavailable routes remain unresolved with their native alternative recorded separately. kbd-apply retains task hooks and completion ownership; a liter-llm response alone is not a tool-enabled worker result. Planning prerequisites do not authorize installing or configuring providers.
Backend Types
| Backend | When to use |
|---|---|
openspec |
OpenSpec available; spec-backed traceability required |
native-tool |
Tool has explicit planning, inspectable progress |
hybrid |
Native tool for decomposition, OpenSpec for spec execution |
manual |
Human-only operation; no automation possible |
Examples
/kbd-execute # uses active waypoint phase
/kbd-execute phase-2-sales-module # explicit phase name
/kbd-execute --skip-qa # skip the artifact QA gate
/kbd-execute --skip-adversarial-review # skip the adversarial review gate
Hook integration
Fire execute:before when entering Execute, before selecting a backend.
Fire execute:after only at the completed Execute boundary described below,
never after merely writing execution.md or dispatching work. Use
hooksFire('execute', 'before'|'after', name, index, total, ctx)
from lib/kbd/hooks.mjs. task:before/task:after are fired per task by
the change-apply driver (kbd-apply's scope) — not by /kbd-execute and
not by bare OpenSpec apply. /kbd-execute writes the dispatch contract; the
apply driver walks the tasks, firing the per-task hooks and emitting the
plain-text position signal on each boundary.
import { hooksFire } from '../../lib/kbd/hooks.mjs';
await hooksFire('execute', 'before', phase, 1, 1, { orchestratorRoot, cwd, runCommand });
// … write execution.md and execute-dispatch.json; drive the assigned work …
// No execute:after or execute completion handoff at dispatch.
Note: the on_change_complete legacy alias is fired automatically by
hooksFire on the final task:after of each change (sentinel:
index === total, matching kbd_hook_index == kbd_hook_total). Projects
relying on on_change_complete continue to work without changes.
Execute completion checklist
Before completing Execute, inspect the active phase’s canonical state and actual evidence. All of the following must hold:
- Every change and task assigned to this phase’s execution scope is complete; none remains pending, in progress, or blocked. Completion of one delegated change does not complete the parent stage.
- The B4 sequence (
kbd-process-orchestrator/references/boundaries.md) has run once — boundary packet,boundary-results.json, cumulative QA and independent review — with real receipts or an explicitly permitted signed waiver. A skip flag orpending_reviewis not a passing result. Per-change QA is forbidden. - Required
kbd-apply verifyandkbd-apply archiveoperations have succeeded for every applicable change, including any reconciliation work assigned to this phase. Record actual outcomes and evidence locations.
If anything remains, report it and keep Execute active. Implementation N/N alone does not satisfy this checklist. Do not infer success from a dispatch receipt, a missing tool, or a previous completion claim.
Once all conditions hold, record the completed execute stage with a typed
prometheus kbd stage transition, fire execute:after, inspect its actual
outcome under project hook policy, and then write the completion handoff.
Required hook failures must be resolved before handing off to Reflect.
Preserve actual earlier receipts; never manufacture a successful past hook.
Pre-dispatch readiness gate (mandatory, mini #60)
Before any dispatch, the Plan→Execute stage gate enforces readiness; the standalone check is:
Run from the consumer project. Replace <package-root> with the absolute root
of the loaded mini package (the directory containing scripts and lib), or
the source checkout root for development. Keep the consumer working directory;
do not copy scripts into the project. Quote paths, including paths with spaces.
node "<package-root>/scripts/kbd-phase-readiness-check.mjs" --phase "<phase>"
READY(exit 0) is required to dispatch implementation. READY authorizes dispatch of implementation work only — it does NOT start testing; the contract's boundaryPacket runs once at the completed phase boundary.BLOCKED(exit 2): do not dispatch; surface the minimal missing list.REJECT-IDENTITY(3) /REJECT-STALE(4): do not dispatch; stale digests (a changed contract, or for v2 a changed bound OpenSpec requirement undermethod.specDeltaDigest) require an operator-adopted amendment (node "<package-root>/scripts/kbd-contract-adopt.mjs" "<contract>" --supersedes "<prior-decision-id>").- A phase the terminal evaluator has closed (
PHASE-CLOSED verdict=PASS) refuses further dispatch at this gate; open a successor phase through the canonical next-phase flow.
Never fabricate PASS, never treat unknown as success, and never hand-write handoffs, journals, or receipts.
Value-scenario authoring and verification
After the complete agreed production work, adopted scenario IDs may be authored
with bdd-cucumber-js author-only (writes files only; NOT_EXERCISED). The
contract's boundary packet is run once, at B4 after the owner's authorization
event (node "<package-root>/scripts/kbd-boundary-authorize.mjs" --phase "<phase>" --authorizer "<who>"),
through value-scenario-verify; its evidence goes to the existing
boundary-results.json and kbd-phase-close-eval. A task, hour, commit,
checkpoint or reviewer request never admits that run.
Stage gate & handoff
At dispatch, require the plan handoff and write only dispatch artifacts:
import { stageGate } from '../../lib/kbd/stage-gate.mjs';
const gate = stageGate('execute', { cwd });
if (gate.status !== 0) throw new Error(gate.stderr);
// … enter Execute with a typed command, write execution.md and execute-dispatch.json …
// Keep Execute active; do not write its completion handoff here.
Only after the completion checklist and required hook outcomes above are satisfied, invoke:
import { stageHandoffWrite } from '../../lib/kbd/stage-gate.mjs';
stageHandoffWrite(
'execute',
'<completed phase scope; QA/review and verify/archive evidence>',
['execution.md', 'progress.json'],
{ cwd },
);
This completion handoff is what Reflect reads first. Its completedAt and
nextStage describe a completed Execute boundary, never dispatch readiness.
A missing handoffs/ directory does not bypass required predecessors.
A missing required handoff fails with remediation: complete the predecessor
stage, or record an explicit skip with its reason under project policy.
A deliberate stage skip is recorded with
stageHandoffSkip('execute', '<reason>', { cwd }).
Delivery cadence profiles
When a delivery-cadence profile is selected, include its path, state root, iteration scope, required build/run actions and publication interval in the authored execution dispatch contract. The harness remains continuation owner; kbd-apply remains canonical task owner. Do not edit generated waypoints.
Finish the complete independently usable increment, then BUILD and RUN its actual function. Do not run test suites, per-task verification or reviewer loops at iteration boundaries. Fix build, launch or functional failures before beginning another increment. A timer never certifies partial work. Apply the profile's human review and publication policy; keep architecture approvals separate. See the delivery-cadence skill only for cadence-enabled work.
Selected-method recovery and authority
Before dependent work, run node <pack-root>/scripts/kbd-method-context.mjs --project <project-root> --phase <canonical-phase-id> --write (or read the phase-local method-context.md when Node is unavailable) and act on its status:
RESOLVED_REFERENCES— continue with the recovered method, contract and stage authority; preserve the same references in role inputs, dispatch and handoff read order.BLOCKED— the contract, its binding, a calibration reference, a supersession or a deviation's cadence/reason is missing or changed, or canonical status is unavailable; resolve it explicitly. Prior commands, memory and tool inventories are not fresh authority.CONFLICT— a governing rule file the active harness loads grants an exception VLBV forbids (for example a compiler check or an hourly integration gate during generation). Stop before dependent work and show the conflict; continue only after the operator records aKBD-POLICY-ACKdecision for that file's current hash. Never rewrite operator-owned policy, and never treat an exception as authority for tests, builds, dry-runs or generated-code verification.
VLBV is the method for every phase (project default verificationMethod: "VLBV"); a deviation exists only as a signed KBD-METHOD decision naming the method, its execution cadence and its reason, and it is disclosed in the closure packet. Define acceptance before generation; generated code executes only at the value-phase boundary (B4) and, after an authorized repair, at B5 — see kbd-process-orchestrator/references/boundaries.md. Tasks, hours, commits, reviewer requests and compiler problems create no boundary. Preserve original evidence, consumed budgets and unresolved effects across resume and supersession; reconcile an uncertain effect before any retry. Full rules: kbd-process-orchestrator/references/method-context.md.