/kbd-assess
Run the Assess phase of the KBD lifecycle for any project.
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
Inspects the current codebase and produces a structured gap report against the
active phase's goals. Output written to
.kbd-orchestrator/phases/<phase-name>/assessment.md.
Also reads progress.json to incorporate any work completed by other tools
(Roo, Cursor, Cline, Codex, etc.) since the last session.
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-assess — <phase-name> (step N of T)
When all steps are complete, emit:
Completed kbd-assess — <phase-name> (step N of T)
How to get N and T (MANDATORY — never estimate):
- Read
.kbd-orchestrator/phases/<phase>/progress.json→completion.implementation.completed= N and.total= T; fall back to legacychanges_completed/changes_totalonly when canonical fields are absent.implementationCompleted(progress)/implementationTotal(progress)fromlib/kbd/progress.mjsare the single source of truth for this — they already encode the legacy-alias fallback, so read counters through them rather than re-deriving the precedence by hand. - If
progress.jsonis absent, readcurrent-waypoint.json→implementationCompleted/implementationTotal, then legacy aliases.
Use the canonical phase name from the argument or current-waypoint.json. Emit to plain response text — no tool call needed.
How to invoke
- Model preflight — assess is the KBD entry stage. When
adversarial-reviewis installed in this project, run its preflight step up front (cached 24h) before continuing. Never block the stage on preflight status — degrade and continue. - Discover project identity — read
.kbd-orchestrator/project.jsonor infer fromAGENTS.md,CLAUDE.md,README.md,package.json,Cargo.toml, etc. - Confirm the active phase — from argument or
.kbd-orchestrator/current-waypoint.json - Resume from progress — read
.kbd-orchestrator/phases/<phase>/progress.jsonto account for cross-tool work done - Load specs — read
openspec/specs/*.mdif OpenSpec is available, otherwise read the canonical spec files defined in.kbd-orchestrator/project.json - Inspect the codebase — scan feature directories, components, routes, etc.
- Write assessment file to
.kbd-orchestrator/phases/<phase>/assessment.md— gaps against phase goals, open questions, confidence per finding - Adversarial vet — when
adversarial-reviewis installed and--skip-adversarial-reviewwas not passed, run it in artifact mode against the written assessment. CRITICAL findings → reviseassessment.mdand re-vet (max 2 rounds, then accept with an "Unresolved review findings" section appended). WARNING findings → carry into the stage handoff summary. - Enter/complete the assessment stage through typed
prometheus kbd stagecommands and separately record the handoff (see below); never hand-edit generated progress or waypoint files.
Examples
/kbd-assess # uses active waypoint phase
/kbd-assess phase-1-foundation # explicit phase name
/kbd-assess phase-2-sales-module # for a new project phase
Hook integration
Fire assess:before immediately after the "Starting kbd-assess —" Progress
Signal, and assess:after immediately before the "Completed kbd-assess —"
Progress Signal. The existing Progress Signals continue to fire — hooks are
complementary, not a replacement.
The dispatcher is hooksFire(kind, edge, name, index, total, ctx) from
lib/kbd/hooks.mjs. It requires ctx.orchestratorRoot and ctx.runCommand —
an injected async (command, env, { timeout }) => { status, stdout, stderr }
that actually executes a matched hook's configured command (this repo never
shells out to a command string; see lib/platform/spawn.mjs). A caller
running this skill programmatically would do the equivalent of:
import { hooksFire } from '../../lib/kbd/hooks.mjs';
await hooksFire('assess', 'before', phase, 1, 1, { orchestratorRoot, cwd, runCommand });
// … write assessment.md …
await hooksFire('assess', 'after', phase, 1, 1, { orchestratorRoot, cwd, runCommand });
See the parent kbd-process-orchestrator skill's "Hooks" section for the full
event taxonomy, override semantics, and KBD_HOOK_* payload — all of which
hooksFire implements as documented there.
Stage gate & handoff
Assess has no predecessor, but its gate still requires a resolvable phase
and agreement between canonical phase views. Stop on any nonzero result.
After writing assessment.md, record the handoff that the next
stage (analyze, or plan when analyze is skipped) reads first.
lib/kbd/stage-gate.mjs exports stageGate(stage, ctx),
stageHandoffWrite(stage, summary, outputs, ctx), and
stageHandoffSkip(stage, reason, ctx):
import { stageGate, stageHandoffWrite } from '../../lib/kbd/stage-gate.mjs';
const gate = stageGate('assess', { cwd });
if (gate.status !== 0) throw new Error(gate.stderr); // remediation text is in gate.stderr
// … write assessment.md …
stageHandoffWrite(
'assess',
'<1–3 sentences: key gaps found, open questions for analyze/plan; include any WARNING findings from adversarial review>',
['assessment.md'],
{ cwd },
);
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('assess', '<reason>', { cwd }).
Adopted-outcome elicitation (required, mini #60)
Assess must elicit and record the adopted-outcome contract inputs (user
operation, observed baseline incl. UNKNOWNs, desired observable result,
supported environments, required safety checks, exclusions, risk acceptance,
decision owner). Explicit prior operator instructions count as adoption; never
infer adoption from TODOs. See
skills/kbd-process-orchestrator/references/templates/adopted-contract.template.md.
Value scenario discovery
Use value-scenario-discovery to propose a bounded, owner-calibrated frontier
of useful scenarios: actor/outcome, source or explicit assumption, reason now,
likelihood or UNKNOWN, mandatory constraints, exclusions and the decision it
informs. Reuse owner-reviewed examples already on record. Record usefulness and
open calibration in assessment.md; candidates stay proposals until adopted
through the existing contract. Discovery runs no checks and authors no tests.
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.
Host policy discovery
At this stage also discover the project's governing host instructions and the actual host capability (instruction-only, observed, enforced within a named boundary, or unsupported), and report an existing policy conflict, such as a compiler exception under VLBV, before dependent execution.