# Kbd Execute

> Use to select an execution backend for the active KBD phase, write canonical phase execution state, dispatch the phase, and maintain KBD as the source of truth. Supports multi-tool handoff via the progress.json protocol. Runs the B4 boundary sequence once at phase completion.

- Skill: `prometheus-ags/kbd-execute` (Agent Skill)
- Install (CLI): `npx get-skill add prometheus-ags/kbd-execute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prometheus-ags/kbd-execute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: Prometheus-AGS (https://skillmd.com/u/prometheus-ags)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/prometheus-ags/kbd-execute

---


# /kbd-execute

Run the **Execute** phase of the KBD lifecycle.

## OpenSpec lifecycle preflight

Before this stage, follow the [orchestrator preflight](../kbd-process-orchestrator/SKILL.md#openspec-lifecycle-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`](../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`:

```js
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

1. **Discover project identity** — read `.kbd-orchestrator/project.json` or infer
2. **Confirm the active phase** — from argument or waypoint
3. **Load waypoint** — `.kbd-orchestrator/current-waypoint.json` first when it exists
4. **Load assessment and plan** for the phase
5. **Write `execution.md`** with selected backend + dispatch contract
6. **Record the active path** through typed KBD commands; projections refresh automatically
7. **Register planned changes and tasks** through `prometheus kbd change register` / `task register`
8. **Dispatch** and write `execute-dispatch.json`; keep Execute active
9. Complete every planned production change without intermediate verification
10. Run the B4 sequence once (`kbd-process-orchestrator/references/boundaries.md`): boundary packet,
    record, cumulative static QA and review, close
11. Verify and archive changes through `kbd-apply` only after the phase is CLOSED (B4 step 7)
12. **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](../kbd-plan/references/task-model-selection.md). 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.

```js
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:

1. 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.
2. 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 or `pending_review` is not a passing result. Per-change QA is forbidden.
3. Required `kbd-apply verify` and `kbd-apply archive` operations 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 under
  `method.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:

```js
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:

```js
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 a `KBD-POLICY-ACK` decision 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`.


